Rename operation database to runtime-persistent and runtime database to runtime-transient

.agent/skills/db/SKILL.md

@@ -7,13 +7,14 @@ description: Database schema and query conventions for ThunderID. Use when chang
 
 ## Logical Database Separation
 
-ThunderID uses three logically separated databases. Each database owns a specific category of data.
+ThunderID uses four logically separated databases. Each database owns a specific category of data.
 
-| Database     | Responsibility                                                         |
-|--------------|------------------------------------------------------------------------|
-| `configdb`   | Identity configuration data Ex: applications, authentication flows, roles, identity providers |
-| `runtimedb`  | Runtime temporal data which holds the state of the authentication flows: authorization codes, flow contexts, WebAuthn sessions |
-| `entitydb`   | Identity data: users, groups, indexed user attributes                  |
+| Database (config key) | Responsibility                                                |
+|-----------------------|---------------------------------------------------------------|
+| `config`              | Identity configuration data Ex: applications, authentication flows, roles, identity providers |
+| `runtime_transient`   | Short-lived runtime state: authorization codes, authorization/PAR requests, JTI records, WebAuthn/VCI state, flow contexts |
+| `entitydb`                | Identity data: users, groups, indexed user attributes         |
+| `runtime_persistent`  | Long-lived operational state that must survive restarts: revoked tokens, SSO sessions, consent records |
 
 Although the databases are logically separated, they share consistent schema design principles documented here.
 
@@ -169,15 +170,15 @@ CREATE INDEX idx_user_ou_deployment ON "USER" (DEPLOYMENT_ID, OU_ID);
 
 ### Expiry Indexes
 
-Tables in `runtimedb` that include an `EXPIRY_TIME` column should have a dedicated index on that column to support efficient cleanup queries.
+Tables in `runtime_transient` that include an `EXPIRY_TIME` column should have a dedicated index on that column to support efficient cleanup queries.
 
 ```sql
 CREATE INDEX idx_authz_code_expiry_time ON "AUTHORIZATION_CODE" (EXPIRY_TIME);
 ```
 
-## Runtime Database Expiry Handling
+## Runtime-transient Database Expiry Handling
 
-Use these rules for all temporary runtime tables in `runtimedb`.
+Use these rules for all temporary runtime tables in `runtime_transient`.
 
 ### Agent Rules
 
@@ -187,7 +188,7 @@ Use these rules for all temporary runtime tables in `runtimedb`.
 4. Cleanup jobs must delete expired rows regularly.
 5. For association tables, if the foreign key to the owning runtime record uses `ON DELETE CASCADE`, deleting an expired owner row also removes related association rows automatically.
 6. An association table does not require its own `EXPIRY_TIME` column unless the association has an independent expiry lifecycle.
-7. When runtime tables are added, removed, or renamed, update both cleanup artifacts: `backend/dbscripts/runtimedb/postgres-cleanup.sql` and `backend/scripts/cleanup_runtime_db.sh`.
+7. When runtime tables are added, removed, or renamed, update both cleanup artifacts: `backend/dbscripts/runtime-transient/postgres-cleanup.sql` and `backend/scripts/cleanup_runtime_transient_db.sh`.
 
 ### Expiry Column
 
@@ -211,13 +212,13 @@ WHERE AUTH_ID = $1 AND EXPIRY_TIME > $2 AND DEPLOYMENT_ID = $3
 
 Use the existing cleanup artifacts in this repository:
 
-- `backend/dbscripts/runtimedb/postgres-cleanup.sql`: defines the PostgreSQL stored procedure `cleanup_expired_runtimedb_data` (UTC-based cleanup).
-- `backend/scripts/cleanup_runtime_db.sh`: provides scheduled/manual cleanup support for PostgreSQL and SQLite.
+- `backend/dbscripts/runtime-transient/postgres-cleanup.sql`: defines the PostgreSQL stored procedure `cleanup_expired_runtime_transient_data` (UTC-based cleanup).
+- `backend/scripts/cleanup_runtime_transient_db.sh`: provides scheduled/manual cleanup support for PostgreSQL and SQLite.
 
 Keep these two files in sync with the current set of runtime tables.
 
 ```sql
-CREATE OR REPLACE PROCEDURE cleanup_expired_runtimedb_data()
+CREATE OR REPLACE PROCEDURE cleanup_expired_runtime_transient_data()
 LANGUAGE plpgsql
 AS $$
 DECLARE
@@ -293,6 +294,6 @@ Use a consistent prefix per store and increment the sequence number for each new
 | Query parameter order | Keep `DEPLOYMENT_ID` as the last parameter in parameterized queries. |
 | Runtime table expiry column | For runtime owner tables, require `EXPIRY_TIME TIMESTAMP NOT NULL`. |
 | Association table expiry column | Omit `EXPIRY_TIME` when lifecycle is inherited via `ON DELETE CASCADE`; add it only if association rows expire independently. |
-| Expired data cleanup | Use `backend/dbscripts/runtimedb/postgres-cleanup.sql` and `backend/scripts/cleanup_runtime_db.sh`; keep both updated when runtime tables change. |
+| Expired data cleanup | Use `backend/dbscripts/runtime-transient/postgres-cleanup.sql` and `backend/scripts/cleanup_runtime_transient_db.sh`; keep both updated when runtime tables change. |
 | Query declaration format | Define queries as `DBQuery` values with unique query IDs. |
 | Table identifier format | Use uppercase table names in double quotes in schema scripts and embedded SQL. |

.github/actions/run-integration-tests/action.yml

@@ -37,13 +37,13 @@ runs:
       shell: bash
       run: |
         PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d postgredb -c "CREATE DATABASE configdb;"
-        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d postgredb -c "CREATE DATABASE runtimedb;"
+        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d postgredb -c "CREATE DATABASE runtime_transient;"
         PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d postgredb -c "CREATE DATABASE entitydb;"
-        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d postgredb -c "CREATE DATABASE operationdb;"
+        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d postgredb -c "CREATE DATABASE runtime_persistent;"
         PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d configdb < backend/dbscripts/configdb/postgres.sql
-        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d runtimedb < backend/dbscripts/runtimedb/postgres.sql
+        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d runtime_transient < backend/dbscripts/runtime-transient/postgres.sql
         PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d entitydb < backend/dbscripts/entitydb/postgres.sql
-        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d operationdb < backend/dbscripts/operationdb/postgres.sql
+        PGPASSWORD=dbpassword psql -h localhost -p 5432 -U dbuser -d runtime_persistent < backend/dbscripts/runtime-persistent/postgres.sql
 
     - name: 📝 Configure Test Database
       shell: bash

ARCHITECTURE.md

@@ -9,7 +9,7 @@ backend/cmd/server/
   main.go               # startup
   servicemanager.go     # calls every internal/*/init.go to register routes
   bootstrap/flows/      # JSON auth/registration flow definitions (auto-seeded)
-  repository/           # configdb.db · runtimedb.db · entitydb.db created at runtime in the configured data directory (SQLite or Postgres)
+  repository/           # configdb.db · runtime-transient.db · runtime-persistent.db · entitydb.db created at runtime in the configured data directory (SQLite or Postgres)
 backend/internal/
   authn/                # credential / OTP / passkey / social login
   oauth/                # OAuth 2.0 + OIDC server (authorize, token, introspect, userinfo, JWKS, DCR)
@@ -34,7 +34,7 @@ samples/apps/           # react-sdk-sample · react-api-based-sample · react-va
 
 ## Flow engine
 
-Authentication/registration are JSON node graphs (`START → PROMPT → TASK → DECISION → COMPLETE`). The engine steps through nodes, persisting state in `runtimedb` across requests. Each `TASK` node names an executor (e.g. `"CredentialsAuthExecutor"`). To add one: implement `core.ExecutorInterface`, add name to `executor/constants.go`, register in `executor/init.go`.
+Authentication/registration are JSON node graphs (`START → PROMPT → TASK → DECISION → COMPLETE`). The engine steps through nodes, persisting state in `runtime_transient` across requests. Each `TASK` node names an executor (e.g. `"CredentialsAuthExecutor"`). To add one: implement `core.ExecutorInterface`, add name to `executor/constants.go`, register in `executor/init.go`.
 
 ## ThunderID React SDK
 

api/healthcheck.yaml

@@ -51,7 +51,7 @@ paths:
                 serviceStatus:
                   - serviceName: "ConfigDB"
                     status: "UP"
-                  - serviceName: "RuntimeDB"
+                  - serviceName: "RuntimeTransientDB"
                     status: "UP"
                   - serviceName: "EntityDB"
                     status: "UP"
@@ -66,7 +66,7 @@ paths:
                 serviceStatus:
                   - serviceName: "ConfigDB"
                     status: "DOWN"
-                  - serviceName: "RuntimeDB"
+                  - serviceName: "RuntimeTransientDB"
                     status: "UP"
                   - serviceName: "EntityDB"
                     status: "UP"
@@ -93,7 +93,7 @@ components:
           type: string
           enum:
             - ConfigDB
-            - RuntimeDB
+            - RuntimeTransientDB
             - EntityDB
         status:
           type: string

api/oauth2.yaml

@@ -388,7 +388,7 @@ paths:
         "500":
           description: >-
             Internal server error — the revocation could not be recorded, for example when the
-            operation database is unavailable.
+            runtime persistent database is unavailable.
           content:
             application/json:
               schema:

backend/cmd/server/config/default.json

@@ -42,10 +42,10 @@
         "max_retry_backoff_ms": 2000
       }
     },
-    "runtime": {
+    "runtime_transient": {
       "type": "sqlite",
       "sqlite": {
-        "path": "database/runtimedb.db",
+        "path": "database/runtime-transient.db",
         "options": "_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)",
         "max_open_conns": 500,
         "max_idle_conns": 100,
@@ -80,6 +80,19 @@
         "min_retry_backoff_ms": 50,
         "max_retry_backoff_ms": 2000
       }
+    },
+    "runtime_persistent": {
+      "type": "sqlite",
+      "sqlite": {
+        "path": "database/runtime-persistent.db",
+        "options": "_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)",
+        "max_open_conns": 500,
+        "max_idle_conns": 100,
+        "conn_max_lifetime": 3600,
+        "max_retries": 3,
+        "min_retry_backoff_ms": 50,
+        "max_retry_backoff_ms": 2000
+      }
     }
   },
   "cache": {

backend/cmd/server/deployment.yaml

@@ -17,10 +17,10 @@ database:
       max_idle_conns: 100
       conn_max_lifetime: 3600
 
-  runtime:
+  runtime_transient:
     type: "sqlite"
     sqlite:
-      path: "database/runtimedb.db"
+      path: "database/runtime-transient.db"
       options: "_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)"
       max_open_conns: 500
       max_idle_conns: 100
@@ -35,10 +35,10 @@ database:
       max_idle_conns: 100
       conn_max_lifetime: 3600
 
-  operation:
+  runtime_persistent:
     type: "sqlite"
     sqlite:
-      path: "database/operationdb.db"
+      path: "database/runtime-persistent.db"
       options: "_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)"
       max_open_conns: 500
       max_idle_conns: 100

backend/cmd/server/servicemanager.go

@@ -256,7 +256,7 @@ func registerServices(mux *http.ServeMux, cacheManager cache.CacheManagerInterfa
 	oauthCfg := oauthconfig.FromServerRuntime()
 	dpopVerifier := dpop.Initialize(oauthCfg, jti.Initialize(oauthCfg))
 
-	runtimeStoreProvider, transactioner, err := runtimestore.Initialize(runtime.Config.Database.Runtime.Type,
+	runtimeStoreProvider, transactioner, err := runtimestore.Initialize(runtime.Config.Database.RuntimeTransient.Type,
 		runtime.Config.Server.Identifier)
 	fatalOnError(ctx, logger, err, "Failed to initialize runtime store")
 

backend/dbscripts/operationdb/postgres-cleanup.sql → backend/dbscripts/runtime-persistent/postgres-cleanup.sql

@@ -16,48 +16,48 @@
 -- ----------------------------------------------------------------------------
 
 -- ============================================================
--- Stored procedure: purge expired operationdb rows in bounded batches.
+-- Stored procedure: purge expired runtime_persistent rows in bounded batches.
 --
--- Unlike runtimedb, operation data is authoritative and must survive a
--- runtime flush; only rows past their EXPIRY_TIME are safe to delete. A revoked
+-- Unlike runtime_transient, runtime_persistent data is authoritative and must survive a
+-- runtime_transient flush; only rows past their EXPIRY_TIME are safe to delete. A revoked
 -- token's row is removable once the token itself would have naturally expired.
 --
 -- Deletes expired rows in batches of p_batch_size (default 1000), committing
 -- after each batch to keep locks short on large tables. Must run as a top-level
 -- CALL (the per-batch COMMIT cannot run inside an outer transaction).
 --
 -- Run once manually (ad-hoc / on-demand):
---   PGPASSWORD=<pass> psql -h <host> -p <port> -U <user> -d <operationdb> \
---     -c "CALL cleanup_expired_operationdb_data();"
+--   PGPASSWORD=<pass> psql -h <host> -p <port> -U <user> -d <runtime_persistent> \
+--     -c "CALL cleanup_expired_runtime_persistent_data();"
 --
 --   -- Optional: override the batch size (rows deleted per batch):
---   -c "CALL cleanup_expired_operationdb_data(500);"
+--   -c "CALL cleanup_expired_runtime_persistent_data(500);"
 --
 -- Scheduled execution options:
 --
 --   1. pg_cron (RECOMMENDED, requires the pg_cron extension):
 --      CREATE EXTENSION IF NOT EXISTS pg_cron;
 --      SELECT cron.schedule(
---        'cleanup-operationdb-expired',
+--        'cleanup-runtime_persistent-expired',
 --        '*/60 * * * *',
---        $$CALL cleanup_expired_operationdb_data()$$
+--        $$CALL cleanup_expired_runtime_persistent_data()$$
 --      );
---      -- To verify: SELECT * FROM cron.job WHERE jobname = 'cleanup-operationdb-expired';
---      -- To remove: SELECT cron.unschedule('cleanup-operationdb-expired');
+--      -- To verify: SELECT * FROM cron.job WHERE jobname = 'cleanup-runtime_persistent-expired';
+--      -- To remove: SELECT cron.unschedule('cleanup-runtime_persistent-expired');
 --
---   2. Kubernetes CronJob: call CALL cleanup_expired_operationdb_data()
+--   2. Kubernetes CronJob: call CALL cleanup_expired_runtime_persistent_data()
 --      via a psql container on the desired schedule.
 --
 --   3. OS cron (every 60 minutes):
 -- --      */60 * * * * postgres PGPASSWORD=<pass> psql -h <host> -p <port> \
--- --        -U <user> -d <operationdb> -c "CALL cleanup_expired_operationdb_data();" \
+-- --        -U <user> -d <runtime_persistent> -c "CALL cleanup_expired_runtime_persistent_data();" \
 -- --        >> /var/log/thunderid-operation-cleanup.log 2>&1
 -- ============================================================
 
 -- Drop the old parameterless signature so re-applying doesn't leave an ambiguous overload.
-DROP PROCEDURE IF EXISTS cleanup_expired_operationdb_data();
+DROP PROCEDURE IF EXISTS cleanup_expired_runtime_persistent_data();
 
-CREATE OR REPLACE PROCEDURE cleanup_expired_operationdb_data(p_batch_size INT DEFAULT 1000)
+CREATE OR REPLACE PROCEDURE cleanup_expired_runtime_persistent_data(p_batch_size INT DEFAULT 1000)
 LANGUAGE plpgsql
 AS $$
 DECLARE

backend/dbscripts/operationdb/postgres.sql → backend/dbscripts/runtime-persistent/postgres.sql

@@ -16,7 +16,7 @@
 -- ----------------------------------------------------------------------------
 
 -- Table to store revoked token JTIs (single-token revocation deny list).
--- Part of the database.operation classification: authoritative authorization
+-- Part of the database.runtime_persistent classification: authoritative authorization
 -- enforcement state that must survive a runtime database flush.
 CREATE TABLE "REVOKED_TOKEN" (
     DEPLOYMENT_ID VARCHAR(255) NOT NULL,
@@ -34,7 +34,7 @@ CREATE UNIQUE INDEX idx_revoked_token_jti_deployment ON "REVOKED_TOKEN" (DEPLOYM
 CREATE INDEX idx_revoked_token_expiry_time ON "REVOKED_TOKEN" (EXPIRY_TIME);
 
 -- Table to store SSO sessions, grouped by flow (FLOW_ID) and resolved by an opaque handle.
--- Part of the database.operation classification: persistent session state that must survive a
+-- Part of the database.runtime_persistent classification: persistent session state that must survive a
 -- runtime database flush.
 CREATE TABLE "SSO_SESSION" (
     SESSION_ID VARCHAR(36) NOT NULL,

backend/dbscripts/operationdb/sqlite.sql → backend/dbscripts/runtime-persistent/sqlite.sql

@@ -16,7 +16,7 @@
 -- ----------------------------------------------------------------------------
 
 -- Table to store revoked token JTIs (single-token revocation deny list).
--- Part of the database.operation classification: authoritative authorization
+-- Part of the database.runtime_persistent classification: authoritative authorization
 -- enforcement state that must survive a runtime database flush.
 CREATE TABLE "REVOKED_TOKEN" (
     DEPLOYMENT_ID VARCHAR(255) NOT NULL,
@@ -34,7 +34,7 @@ CREATE UNIQUE INDEX idx_revoked_token_jti_deployment ON "REVOKED_TOKEN" (DEPLOYM
 CREATE INDEX idx_revoked_token_expiry_time ON "REVOKED_TOKEN" (EXPIRY_TIME);
 
 -- Table to store SSO sessions, grouped by flow (FLOW_ID) and resolved by an opaque handle.
--- Part of the database.operation classification: persistent session state that must survive a
+-- Part of the database.runtime_persistent classification: persistent session state that must survive a
 -- runtime database flush.
 CREATE TABLE "SSO_SESSION" (
     SESSION_ID VARCHAR(36) NOT NULL,

backend/dbscripts/runtimedb/postgres-cleanup.sql → backend/dbscripts/runtime-transient/postgres-cleanup.sql

@@ -16,44 +16,44 @@
 -- ----------------------------------------------------------------------------
 
 -- ============================================================
--- Stored procedure: purge expired runtimedb rows in bounded batches.
+-- Stored procedure: purge expired runtime_transient rows in bounded batches.
 --
 -- Deletes expired rows in batches of p_batch_size (default 1000), committing
 -- after each batch to keep locks short on large tables. Must run as a top-level
 -- CALL (the per-batch COMMIT cannot run inside an outer transaction).
 --
 -- Run once manually (ad-hoc / on-demand):
---   PGPASSWORD=<pass> psql -h <host> -p <port> -U <user> -d <runtimedb> \
---     -c "CALL cleanup_expired_runtimedb_data();"
+--   PGPASSWORD=<pass> psql -h <host> -p <port> -U <user> -d <runtime_transient> \
+--     -c "CALL cleanup_expired_runtime_transient_data();"
 --
 --   -- Optional: override the batch size (rows deleted per batch):
---   -c "CALL cleanup_expired_runtimedb_data(500);"
+--   -c "CALL cleanup_expired_runtime_transient_data(500);"
 --
 -- Scheduled execution options:
 --
 --   1. pg_cron (RECOMMENDED, requires the pg_cron extension):
 --      CREATE EXTENSION IF NOT EXISTS pg_cron;
 --      SELECT cron.schedule(
---        'cleanup-runtimedb-expired',
+--        'cleanup-runtime_transient-expired',
 --        '*/60 * * * *',
---        $$CALL cleanup_expired_runtimedb_data()$$
+--        $$CALL cleanup_expired_runtime_transient_data()$$
 --      );
---      -- To verify: SELECT * FROM cron.job WHERE jobname = 'cleanup-runtimedb-expired';
---      -- To remove: SELECT cron.unschedule('cleanup-runtimedb-expired');
+--      -- To verify: SELECT * FROM cron.job WHERE jobname = 'cleanup-runtime_transient-expired';
+--      -- To remove: SELECT cron.unschedule('cleanup-runtime_transient-expired');
 --
---   2. Kubernetes CronJob: call CALL cleanup_expired_runtimedb_data()
+--   2. Kubernetes CronJob: call CALL cleanup_expired_runtime_transient_data()
 --      via a psql container on the desired schedule.
 --
 --   3. OS cron (every 60 minutes):
 -- --      */60 * * * * postgres PGPASSWORD=<pass> psql -h <host> -p <port> \
--- --        -U <user> -d <runtimedb> -c "CALL cleanup_expired_runtimedb_data();" \
+-- --        -U <user> -d <runtime_transient> -c "CALL cleanup_expired_runtime_transient_data();" \
 -- --        >> /var/log/thunderid-cleanup.log 2>&1
 -- ============================================================
 
 -- Drop the old parameterless signature so re-applying doesn't leave an ambiguous overload.
-DROP PROCEDURE IF EXISTS cleanup_expired_runtimedb_data();
+DROP PROCEDURE IF EXISTS cleanup_expired_runtime_transient_data();
 
-CREATE OR REPLACE PROCEDURE cleanup_expired_runtimedb_data(p_batch_size INT DEFAULT 1000)
+CREATE OR REPLACE PROCEDURE cleanup_expired_runtime_transient_data(p_batch_size INT DEFAULT 1000)
 LANGUAGE plpgsql
 AS $$
 DECLARE