Datasance · emirhandurmus · Jul 3, 2026 · Jun 30, 2026 · Jun 30, 2026 · Jun 30, 2026
diff --git a/.env.example b/.env.example
@@ -6,7 +6,7 @@ NODE_ENV=development
 
 # EdgeOps Console static embed (npm run build:console → dev/console/build)
 EDGEOPS_CONSOLE_PATH=dev/console/build  # must be absolute path
-EDGEOPS_CONSOLE_VERSION=v1.0.3
+EDGEOPS_CONSOLE_VERSION=v1.0.8
 # EDGEOPS_CONSOLE_REPO=https://github.com/Datasance/edgeops-console
 # EDGEOPS_CONSOLE_FLAVOR=datasance
 

diff --git a/.github/actions/set-build-env/action.yml b/.github/actions/set-build-env/action.yml
@@ -8,7 +8,7 @@ runs:
       shell: bash
       run: |
         VERSION="${{ env.EDGEOPS_CONSOLE_VERSION }}"
-        if [ -z "$VERSION" ]; then VERSION="1.0.3"; fi
+        if [ -z "$VERSION" ]; then VERSION="1.0.8"; fi
         echo "EDGEOPS_CONSOLE_VERSION=$VERSION" >> "${GITHUB_ENV}"
 
         REPO="${{ env.EDGEOPS_CONSOLE_REPO }}"

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/Dockerfile b/Dockerfile
@@ -5,7 +5,7 @@
 FROM node:24-bookworm@sha256:fdddfb3e688158251943d52eba361de991548f6814007acba4917ae6b512d6be AS console-builder
 
 ARG EDGEOPS_CONSOLE_REPO=https://github.com/Datasance/edgeops-console
-ARG EDGEOPS_CONSOLE_VERSION=v1.0.3
+ARG EDGEOPS_CONSOLE_VERSION=v1.0.8
 ARG EDGEOPS_CONSOLE_FLAVOR=datasance
 
 RUN apt-get update \
@@ -48,9 +48,9 @@ RUN npm pack
 
 
 # ubi9/nodejs-24-minimal:latest — pin manifest list digest for reproducible multi-arch builds
-FROM registry.access.redhat.com/ubi9/nodejs-24-minimal@sha256:cc7648f8e1c7d628e4334328a712f30ea0820787bb92836cc93e349674c689bf
+FROM registry.access.redhat.com/ubi9/nodejs-24-minimal@sha256:5f1ac8eab93c93eb2227f4ee7822668b312ee292d122dddd580bee8f17359c2f
 
-ARG EDGEOPS_CONSOLE_VERSION=v1.0.3
+ARG EDGEOPS_CONSOLE_VERSION=v1.0.8
 ARG IMAGE_REGISTRY
 ARG OCI_SOURCE_REPO
 ARG CONTROLLER_DISTRIBUTION=iofog

diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 # Local Docker build — mirrors CI/release build-args (see .github/actions/set-build-env).
-# Override any variable: make build FLAVOR=iofog EDGEOPS_CONSOLE_VERSION=v1.0.3
+# Override any variable: make build FLAVOR=iofog EDGEOPS_CONSOLE_VERSION=v1.0.8
 
 FLAVOR ?= datasance
 IMAGE_NAME ?= controller
@@ -25,7 +25,7 @@ else
   $(error FLAVOR must be "datasance" or "iofog", got "$(FLAVOR)")
 endif
 
-EDGEOPS_CONSOLE_VERSION ?= v1.0.3
+EDGEOPS_CONSOLE_VERSION ?= v1.0.8
 
 IMAGE_REF = $(IMAGE_REGISTRY)/$(IMAGE_NAME):$(DOCKER_TAG)
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -206,7 +206,7 @@ Full spec: [`.cursor/controllerv3.8/docs/15-fog-platform-reconcile.md`](../.curs
 
 ## WebSocket exec & log sessions
 
-Interactive **exec** and **log streaming** use paired WebSocket sessions between operators (Bearer JWT), Controller, and Edgelet agents (fog token). Plan 16 hardens log sessions and shared WS infra (HA, drain, OTEL). **Plan 17** redesigns **microservice exec** to log-style multi-session flow (3 concurrent per MS, agent poll + session-scoped WS). **Plan 18** production-hardens cross-replica relay via **`WsRelayTransport`** — AMQP pool + recovery when `nats.enabled=false`, NATS Core when `nats.enabled=true` (R102–R113). **Edgelet agent wire change required** for exec only (see [edgelet-invariants.md §10.1](../.cursor/controllerv3.8/docs/edgelet-invariants.md)).
+Interactive **exec** and **log streaming** use paired WebSocket sessions between operators (Bearer JWT), Controller, and Edgelet agents (fog token). Plan 16 hardens log sessions and shared WS infra (HA, drain, OTEL). **Plan 17** redesigns **microservice exec** to log-style multi-session flow (5 concurrent per MS, agent poll + session-scoped WS). **Plan 18** production-hardens cross-replica relay via **`WsRelayTransport`** — AMQP pool + recovery when `nats.enabled=false`, NATS Core when `nats.enabled=true` (R102–R113). **Edgelet agent wire change required** for exec only (see [edgelet-invariants.md §10.1](../.cursor/controllerv3.8/docs/edgelet-invariants.md)).
 
 ```mermaid
 flowchart TB
@@ -283,14 +283,14 @@ sequenceDiagram
 | Topic | Normative value |
 |-------|-----------------|
 | MS exec entry | **Direct user WS** — no `POST …/microservices/…/exec` (R92, R94) |
-| MS exec concurrency | **3** user exec WS per microservice (R93) |
+| MS exec concurrency | **5** user exec WS per microservice |
 | MS exec lifecycle | **Per-session** — close deletes session row only; **no** `execEnabled=false` (R98) |
 | MS exec pending / max | **60s** pending for agent; **8h** max active session (Plan 16 carry-over) |
 | Agent exec discovery | `GET /agent/exec/sessions` on `execSessions` change flag (R95, R100) |
 | Agent exec WS | `/agent/exec/microservice/:uuid/:sessionId` only — legacy `/agent/exec/:uuid` removed (R96) |
 | User session notify | **ACTIVATION** (type 5) with `{ sessionId, microserviceUuid }` (R97) |
 | Fog debug provision | `POST/DELETE /iofog/:uuid/exec` unchanged; shell via `WS /microservices/system/exec/:debugMsUuid` (R99) |
-| Log concurrency | **3** user log WS per microservice (or per fog for node logs) |
+| Log concurrency | **5** user log WS per microservice (or per fog for node logs) |
 | Log limits | Tail max **5,000** lines; **120s** pending; **2h** idle |
 | Log content | Live relay only — no log line persistence; audit connect/disconnect |
 | HA relay | Cross-replica sessions **require** a **relay backend** (R112): **AMQP** router queues when `nats.enabled=false`; **NATS Core** subjects on hub when `nats.enabled=true`. Same-replica may use direct WS; **fail fast** close **1013** when active backend unavailable |
@@ -369,18 +369,69 @@ For the full bilateral contract (including ControlPlane env vars and verificatio
 
 | Topic | v3.8 behavior |
 |-------|---------------|
-| **Database** | Greenfield v3.8.0 schema — **new install only** (no v3.7 migrator). Supports **sqlite** (single-controller production), **mysql**, and **postgres** (multi-replica / HA). |
+| **Database** | Greenfield v3.8.0 schema — **new install only** (no v3.7 migrator). Supports **sqlite** (single-controller production), **mysql**, and **postgres** (multi-replica / HA). All mutating paths use **`runInTransaction()`** (Plan 19, R114–R125). Plan **19-I** stabilization (R126–R135): unified ALS transaction context, phased NATS reconcile, grep gates, first-fog integration SLO. |
+
+### Database profiles (Plan 19 / 19-I)
+
+| Profile | Database | Controller replicas | Typical fleet size | Notes |
+|---------|----------|---------------------|-------------------|-------|
+| **Edge / PoT** | sqlite | 1 | ≤ **50** fogs (default warning threshold) | Single write queue; embedded OIDC |
+| **Small production** | sqlite | 1 | 50–100 fogs | Supported within single-writer physics; soft warning logged above threshold |
+| **Enterprise / HA** | mysql or postgres | 1+ | **100+** fogs recommended | Default for large fleets; `FOR UPDATE SKIP LOCKED` task claims; shared OIDC session store |
+
+**Enterprise default:** mysql/postgres for fleets above **100** fogs or any multi-replica deployment. sqlite remains supported for single-node edge deployments within Plan 19 SLOs (200 fogs acceptance profile).
+
+```mermaid
+flowchart LR
+  subgraph callers [Mutating callers]
+    API[REST / Agent API]
+    WS[WS session DB ops]
+    JOBS[Background jobs]
+  end
+
+  subgraph runner [runInTransaction]
+    Q{provider?}
+    SQ[SQLite priority queue]
+    POOL[mysql/postgres pool]
+    TX[Real Sequelize transaction]
+  end
+
+  subgraph outbox [ReconcileOutbox]
+    INS[Same-commit insert]
+    DRAIN[Outbox drainer]
+  end
+
+  API --> runner
+  WS --> runner
+  JOBS --> runner
+  Q -->|sqlite| SQ --> TX
+  Q -->|mysql/pg| POOL --> TX
+  TX --> INS --> DRAIN
+```
+
+| Priority lane | Callers |
+|---------------|---------|
+| **interactive** | Agent routes, user RBAC API, WS session DB ops, OIDC/auth |
+| **background** | Reconcile workers, outbox drainer, platform sweep, cleanup timers |
+
+Full operator runbook: [operations/database-transactions.md](operations/database-transactions.md).
 
 ### SQLite single-node production
 
 Small deployments with **one Controller process** may use SQLite as the production database (embedded OIDC requires a single replica in this profile).
 
 | Topic | Behavior |
 |-------|----------|
-| **When to use** | Single Controller, no DB HA requirement, edge/small-cluster PoT |
-| **Concurrency** | WAL journal mode + `busy_timeout` pragmas on connect; connection pool size 1 |
-| **Background jobs** | Reconcile-heavy jobs start after a configurable delay (`settings.jobStartupDelaySeconds`, default 3s) and stagger by 500ms to avoid restart lock bursts |
-| **Task claims** | Fog/service/NATS reconcile task claims retry on `SQLITE_BUSY` (same retry budget as `TransactionDecorator`) |
+| **When to use** | Single Controller, no DB HA requirement, edge/small-cluster PoT (≤ recommended fog count) |
+| **Write path** | All mutations via `runInTransaction()` — **real** ACID transactions (no `fakeTransaction`); nested reuse via **`runWithTransactionContext`** ALS (R126–R128) |
+| **Concurrency** | Global **priority write queue** (interactive before background); pool `max: 1`; WAL + `busy_timeout` pragmas |
+| **First-fog SLO (R133)** | sqlite integration gate: first fog reconcile + concurrent operator login/list **< 2s**; `RUN_INTEGRATION=1 npm run test:integration:first-fog` |
+| **Load close gate (R135)** | `node test/load/transaction-safety-load.js --fogs=50 --soak-minutes=5` — agent p99 &lt; 200ms, operator p99 &lt; 1s |
+| **Busy retry** | Exponential backoff + jitter on `SQLITE_BUSY` inside queue task (configurable max attempts) |
+| **Reconcile enqueue** | **`ReconcileOutbox`** — mutation + outbox row in same commit; drainer creates reconcile tasks |
+| **Background jobs** | `priority: 'background'`; startup stagger (`settings.jobStartupDelaySeconds`, default 3s) + 500ms between jobs |
+| **Task claims** | Same runner; busy retry on sqlite; mysql/postgres use `FOR UPDATE SKIP LOCKED` |
+| **Load SLO** | 200 fogs / 40s poll / 10 operators / 30 min soak: agent poll p99 **< 200ms**; operator REST p99 **< 1s** |
 | **Persistence** | Mount a persistent volume for `controller_db.sqlite` and WAL sidecar files (`-wal`, `-shm`) |
 | **Backup** | Use SQLite backup API or copy DB + WAL files during a quiet window |
 | **HA path** | mysql/postgres + multiple Controller replicas — see [oidc-configuration.md](oidc-configuration.md) |
@@ -415,4 +466,5 @@ Agent routes and WebSocket exec/logs for agents are **outside** OIDC — see [rb
 | [pki.md](pki.md) | Central CAs, cert renewal, NATS operator rotation |
 | [oidc-configuration.md](oidc-configuration.md) | Embedded/external auth modes and env vars |
 | [external-oidc-client-setup.md](external-oidc-client-setup.md) | External IdP client configuration |
+| [operations/database-transactions.md](operations/database-transactions.md) | Transaction runner, OTEL metrics, SQLITE_BUSY runbook |
 | [CONTRIBUTING](../CONTRIBUTING) | Dual-mirror CI and development |