@substrat-run/adapter-sqlite 0.98.0 → 0.102.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import Database from 'better-sqlite3';
-import { accessLogEntry, adminLogEntry, opsFailureEntry, modelUsageEntry, ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, createTenantInput, domainEvent, domainEventInput, entitlementGrant, entitlementGrantInput, eventId, meterReading, platformRequestInput, platformRequestId, platformRequest, MAX_PENDING_PLATFORM_REQUESTS, identityLink, identityPool, instant, connection, capabilityGrant, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, subjectRef, requestFingerprint, createConnectionInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, routeTarget, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, objectRef, grantRefFromProof, org as orgSchema, orgMembership, principalId, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, subjectShredReceipt, SCOPE_TABLE_PAGE_DEFAULT, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, verticalServingState, outboundOfManifestJson, listLimitOf, substratError, assertReplayableDump, } from '@substrat-run/contracts';
-import { asPrincipal, assertAllowed, assertReadOnlyQuery, attachmentBlobKey, entitlementDenial, foldMeterReading, guardSpine, parseValidationRecords, resolveScopeRecord, ulid, OPS_FAILURE_RETENTION_DAYS, MODEL_USAGE_RETENTION_DAYS, foldModelUsage, backoffAt, platformRequestHistoryQuery, PLATFORM_REQUEST_COLUMNS, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialBucketRow, IMPERSONATION_COLUMNS, IMPERSONATION_DDL, ImpersonationRefused, assertImpersonationWrites, assertSessionUsable, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, impersonationStampOf, mapImpersonationRow, newImpersonationSession, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, noSealingKeyMessage, openSealed, sealTo, ConnectionSealingKeyUnavailableError, PermissionDenied, createAtomic, NotSearchable, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, searchLimit, searchMatchExpression, searchQuery, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, IDEMPOTENCY_DDL, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, } from '@substrat-run/kernel';
+import { accessLogEntry, adminLogEntry, opsFailureEntry, opsFailureFingerprint, issueEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunEntry, modelUsageEntry, ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, createTenantInput, domainEvent, domainEventInput, entitlementGrant, entitlementGrantInput, eventId, meterReading, platformRequestInput, platformRequestId, platformRequest, MAX_PENDING_PLATFORM_REQUESTS, identityLink, identityPool, instant, connection, capabilityGrant, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, subjectRef, requestFingerprint, createConnectionInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, createOrgInput, promotionAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, routeTarget, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, objectRef, grantRefFromProof, org as orgSchema, orgMembership, principalId, resolvedIdentity, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, subjectShredReceipt, SCOPE_TABLE_PAGE_DEFAULT, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, verticalServingState, outboundOfManifestJson, listLimitOf, substratError, assertReplayableDump, } from '@substrat-run/contracts';
+import { asPrincipal, assertAllowed, assertReadOnlyQuery, attachmentBlobKey, entitlementDenial, foldMeterReading, guardSpine, parseValidationRecords, resolveScopeRecord, ulid, ISSUE_RETENTION_DAYS, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, MODEL_USAGE_RETENTION_DAYS, foldModelUsage, backoffAt, platformRequestHistoryQuery, PLATFORM_REQUEST_COLUMNS, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialBucketRow, IMPERSONATION_COLUMNS, IMPERSONATION_DDL, ImpersonationRefused, assertImpersonationWrites, assertSessionUsable, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, impersonationStampOf, mapImpersonationRow, newImpersonationSession, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, noSealingKeyMessage, openSealed, sealTo, ConnectionSealingKeyUnavailableError, PermissionDenied, createAtomic, NotSearchable, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, searchLimit, searchMatchExpression, searchQuery, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, IDEMPOTENCY_DDL, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, globalFetch, } from '@substrat-run/kernel';
 import { ScopeActor } from './actor.js';
 import { createTupleChecker } from './checker.js';
 const KERNEL_DDL = `
@@ -26,8 +26,19 @@ const KERNEL_DDL = `
     -- session/by). NULL is the ordinary case — nobody was impersonating — and the
     -- actor column above stays the principal the permission model answered about.
     impersonation TEXT,
+    -- #1231: the invoke() string this event was emitted from. NULL is two facts the
+    -- spine cannot tell apart afterwards: a consumer emit (no operation ran), and a
+    -- row written before the column.
+    operation TEXT,
+    -- #1242: the version REGISTRY id of the vertical version the host ran when this
+    -- event was emitted (the signals version dimension, #1231). NULL = the host was
+    -- handed no version id, or the row predates the column.
+    version TEXT,
     drained_at TEXT
   );
+  -- #1232: the freshness evaluator's read — MAX(occurred_at) per type, every pass,
+  -- over a table that is never pruned. Unindexed, that is a full history scan.
+  CREATE INDEX IF NOT EXISTS _substrat_outbox_type_at ON _substrat_outbox (type, occurred_at);
   -- platform-intents.md: durable intents a vertical enqueues (ctx.requestPlatform) for the platform
   -- to drain and execute with HostAdmin authority — the sandbox-clean way a vertical asks for a
   -- privileged action. Written by the kernel (spine), settled by the platform drain.
@@ -196,6 +207,23 @@ function keysetTail(where, params, key, page, defaultOrder = 'asc') {
     }
     return tail;
 }
+/** snake_case row → the camelCase `issueEntry` shape (#1233). */
+function issueOf(r) {
+    return {
+        fingerprint: r.fingerprint,
+        operation: r.operation,
+        stage: r.stage,
+        origin: r.origin,
+        code: r.code,
+        status: r.status,
+        count: r.seen_count,
+        firstSeen: r.first_seen,
+        lastSeen: r.last_seen,
+        lastMessage: r.last_message,
+        lastVertical: r.last_vertical,
+        resolvedAt: r.resolved_at,
+    };
+}
 /** A ledger row → the wire entry, the attribution re-nested. Shared by both adapters' shape. */
 function modelUsageEntryOf(r) {
     return modelUsageEntry.parse({
@@ -337,10 +365,12 @@ export class SqliteScopeHost {
     secretBox;
     fetchImpl;
     clock;
+    versionId;
     constructor(options) {
         this.secretBox = options.secretBox ?? unconfiguredSecretBox;
-        this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.fetchImpl = options.fetch ?? globalFetch;
         this.clock = options.clock ?? (() => instant.parse(new Date().toISOString()));
+        this.versionId = options.versionId ?? null;
         this.dir = options.dir;
         mkdirSync(this.dir, { recursive: true });
         this.directory = new Database(join(this.dir, '_directory.sqlite'));
@@ -822,15 +852,69 @@ export class SqliteScopeHost {
         tenant_id TEXT,
         scope_id TEXT,
         vertical TEXT,
+        version TEXT,
         status INTEGER,
         message TEXT NOT NULL,
         reference TEXT,
+        origin TEXT,
+        code TEXT,
+        fingerprint TEXT,
         at TEXT NOT NULL
       );
       CREATE INDEX IF NOT EXISTS _substrat_ops_failures_vertical ON _substrat_ops_failures (vertical, id);
       CREATE INDEX IF NOT EXISTS _substrat_ops_failures_tenant ON _substrat_ops_failures (tenant_id, id);
       CREATE INDEX IF NOT EXISTS _substrat_ops_failures_reference ON _substrat_ops_failures (reference);
       CREATE INDEX IF NOT EXISTS _substrat_ops_failures_at ON _substrat_ops_failures (at);
+      -- #1233: fingerprint-grouped failure classes ("issues"), materialized on
+      -- every ops-failure insert. The row OWNS its counters: the evidence beneath
+      -- it prunes at 90 days, and a count must survive its own exemplars.
+      CREATE TABLE IF NOT EXISTS _substrat_issues (
+        fingerprint TEXT PRIMARY KEY,
+        operation TEXT NOT NULL,
+        stage TEXT,
+        origin TEXT,
+        code TEXT,
+        status TEXT NOT NULL DEFAULT 'new',
+        seen_count INTEGER NOT NULL DEFAULT 0,
+        first_seen TEXT NOT NULL,
+        last_seen TEXT NOT NULL,
+        last_message TEXT NOT NULL,
+        last_vertical TEXT,
+        resolved_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS _substrat_issues_seen ON _substrat_issues (last_seen);
+      -- The durable sweep record (#1232): one row per unit outcome per pass —
+      -- a connection swept/skipped/failed, a schedule fired/skipped/failed. What
+      -- makes "when was this last swept" answerable after the log line rolls off.
+      -- Retention-bounded harder than ops failures (SWEEP_RUN_RETENTION_DAYS):
+      -- high-frequency telemetry whose job is the recent-runs strip.
+      CREATE TABLE IF NOT EXISTS _substrat_sweep_runs (
+        id TEXT PRIMARY KEY,
+        kind TEXT NOT NULL,
+        unit TEXT NOT NULL,
+        outcome TEXT NOT NULL,
+        tenant_id TEXT,
+        scope_id TEXT,
+        vertical TEXT,
+        version TEXT,
+        operation TEXT,
+        connection_id TEXT,
+        error TEXT,
+        elapsed_ms INTEGER,
+        -- #1232: the platform-intent id a drained batch arrived under (NULL for the
+        -- direct sweep path). The unique index below is what makes a replayed drain
+        -- write nothing twice; NULLs are distinct, so direct writes never collide.
+        request_id TEXT,
+        -- #1232 freshness rows: the judged event type (its own dimension, never
+        -- the operation column) and the newest matching evidence. NULL on other kinds.
+        event_type TEXT,
+        observed_at TEXT,
+        at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS _substrat_sweep_runs_unit ON _substrat_sweep_runs (kind, unit, id);
+      CREATE UNIQUE INDEX IF NOT EXISTS _substrat_sweep_runs_intent ON _substrat_sweep_runs (request_id, unit);
+      CREATE INDEX IF NOT EXISTS _substrat_sweep_runs_tenant ON _substrat_sweep_runs (tenant_id, id);
+      CREATE INDEX IF NOT EXISTS _substrat_sweep_runs_at ON _substrat_sweep_runs (at);
       -- Model usage (#1054, meter 3): one line per model call a vertical made through
       -- the platform's model host, drained here as a model-usage intent. request_id is
       -- the intent id and UNIQUE, which is what makes a retried drain write nothing twice.
@@ -1069,6 +1153,7 @@ export class SqliteScopeHost {
             migrations: [...migrations, ...searchMigrations, ...listMigrations],
             consumers,
             schedules: manifest.schedules ?? [],
+            freshness: manifest.freshness ?? [],
         });
         for (const rel of manifest.entityRelations ?? []) {
             const parents = this.relations.get(rel.entityType) ?? new Set();
@@ -1466,7 +1551,7 @@ export class SqliteScopeHost {
         // like an operation invoke (including K-35 denial recording and prompt dispatch of
         // the events it emitted).
         const serialized = (operation, fn) => rt.actor.enqueue(async () => {
-            const ctx = this.operationContext(rt, subject);
+            const ctx = this.operationContext(rt, subject, undefined, undefined, undefined, operation);
             rt.db.exec('BEGIN IMMEDIATE');
             let result;
             try {
@@ -1498,7 +1583,7 @@ export class SqliteScopeHost {
          */
         const reentrant = async (operation, fn) => {
             try {
-                return await fn(this.operationContext(rt, subject));
+                return await fn(this.operationContext(rt, subject, undefined, undefined, undefined, operation));
             }
             catch (err) {
                 if (err instanceof PermissionDenied)
@@ -1692,6 +1777,10 @@ export class SqliteScopeHost {
             // KERNEL_DDL is all IF NOT EXISTS, so it fills only the gaps and never disturbs a
             // table the dump carried.
             db.exec(KERNEL_DDL);
+            // …and the additive columns, for the same reason: a dump captured before a
+            // column existed replays DDL WITHOUT it, and IF NOT EXISTS cannot widen a
+            // table the dump did bring.
+            this.ensureSpineColumns(db);
             // Rebuild the derived search indexes over the rows just loaded (#827). The DDL
             // drops and recreates, so this also repairs an index the dump left stale, and
             // the triggers it recreates are what keep the restored scope in step from here.
@@ -1956,8 +2045,99 @@ export class SqliteScopeHost {
         }
         return out;
     }
+    registeredFreshness() {
+        const out = [];
+        for (const mod of this.modules.values()) {
+            if (mod.freshness.length > 0) {
+                out.push({ moduleId: mod.id, freshness: mod.freshness });
+            }
+        }
+        return out;
+    }
+    /**
+     * The freshness evaluator (#1232): judge each declared expectation against this
+     * scope's own outbox, and return only what should be RECORDED — a verdict that
+     * changed since the last recorded one, or one whose hourly heartbeat lapsed.
+     * State rides `_substrat_schedule_state` under a `freshness:<eventType>` key
+     * (operation names are `module/verb`, event types `ns.verb` — the prefix cannot
+     * collide), reusing its columns as (last recorded at, last recorded outcome).
+     * Aggregates across EVERY registered module, not just the asking one: two
+     * modules declaring one type share a single gating-state key and a single
+     * dedupe unit, so per-module evaluation would have them fighting over both —
+     * flip-flopping state, and colliding rows the dedupe index silently eats.
+     * Duplicates collapse to the TIGHTEST window; the caller invokes this once
+     * per scope, with any registered module's id as the entry ticket.
+     *
+     * Deliberately NOT gated on the system grant — see the interface doc.
+     */
+    async checkFreshness(moduleId, tenantId, scopeId) {
+        const report = { checks: [] };
+        if (!this.modules.has(moduleId))
+            return report;
+        const scope = this.directory
+            .prepare('SELECT status FROM scopes WHERE scope_id = ? AND tenant_id = ?')
+            .get(scopeId, tenantId);
+        if (!scope || scope.status !== 'active')
+            return report;
+        const rt = this.runtime(tenantId, scopeId);
+        await this.applyPendingMigrations(rt);
+        // Same lazy create as runDueSchedules — a freshness-only module must not hit
+        // `no such table` on a scope no schedule ever swept.
+        rt.db.exec(`CREATE TABLE IF NOT EXISTS _substrat_schedule_state (
+         schedule_op TEXT PRIMARY KEY,
+         last_run_at TEXT,
+         last_status TEXT
+       )`);
+        // Collapse duplicate event types to the tightest window, ACROSS modules.
+        const windows = new Map();
+        for (const m of this.modules.values()) {
+            for (const f of m.freshness) {
+                const prev = windows.get(f.eventType);
+                if (prev === undefined || f.within.hours < prev)
+                    windows.set(f.eventType, f.within.hours);
+            }
+        }
+        if (windows.size === 0)
+            return report;
+        const types = [...windows.keys()];
+        const observed = new Map();
+        for (const row of rt.db
+            .prepare(`SELECT type, MAX(occurred_at) AS at FROM _substrat_outbox
+          WHERE type IN (${types.map(() => '?').join(', ')}) GROUP BY type`)
+            .all(...types)) {
+            if (row.at !== null)
+                observed.set(row.type, row.at);
+        }
+        const nowIso = this.clock();
+        const now = Date.parse(nowIso);
+        for (const [eventType, withinHours] of windows) {
+            const observedAt = observed.get(eventType) ?? null;
+            const outcome = observedAt === null
+                ? 'skipped' // never observed — the never-run analogue, not a failure
+                : now - Date.parse(observedAt) <= withinHours * 3_600_000
+                    ? 'ok'
+                    : 'failed';
+            const stateKey = `freshness:${eventType}`;
+            const state = rt.db
+                .prepare('SELECT last_run_at, last_status FROM _substrat_schedule_state WHERE schedule_op = ?')
+                .get(stateKey);
+            const changed = state?.last_status !== outcome;
+            const heartbeatDue = !state?.last_run_at ||
+                now - Date.parse(state.last_run_at) > FRESHNESS_HEARTBEAT_MINUTES * 60_000;
+            if (!changed && !heartbeatDue)
+                continue;
+            rt.db
+                .prepare(`INSERT INTO _substrat_schedule_state (schedule_op, last_run_at, last_status)
+             VALUES (?, ?, ?)
+           ON CONFLICT(schedule_op) DO UPDATE SET last_run_at = excluded.last_run_at,
+                                                  last_status = excluded.last_status`)
+                .run(stateKey, nowIso, outcome);
+            report.checks.push({ eventType, outcome, observedAt, withinHours });
+        }
+        return report;
+    }
     async runDueSchedules(moduleId, tenantId, scopeId) {
-        const report = { fired: 0, skipped: 0, failed: 0, errors: [] };
+        const report = { fired: 0, skipped: 0, failed: 0, errors: [], runs: [] };
         const mod = this.modules.get(moduleId);
         if (!mod || mod.schedules.length === 0)
             return report;
@@ -2000,6 +2180,7 @@ export class SqliteScopeHost {
             const dueAt = lastRun === null ? -Infinity : lastRun + schedule.cadence.everyMinutes * 60_000;
             if (now < dueAt) {
                 report.skipped += 1;
+                report.runs.push({ operation: schedule.operation, outcome: 'skipped' });
                 continue;
             }
             // Due — invoke through the system door (a fresh stub per schedule keeps the
@@ -2024,6 +2205,7 @@ export class SqliteScopeHost {
            ON CONFLICT(schedule_op) DO UPDATE SET last_run_at = excluded.last_run_at,
                                                   last_status = excluded.last_status`)
                 .run(schedule.operation, new Date(now).toISOString(), status);
+            report.runs.push({ operation: schedule.operation, outcome: status === 'ok' ? 'ok' : 'failed' });
         }
         return report;
     }
@@ -2105,7 +2287,7 @@ export class SqliteScopeHost {
                 const invoked = await rt.actor.enqueue(async () => {
                     // Fresh per operation: the context carries the K-34 authorization accumulator,
                     // which must not leak across operations (invokes are serialized per scope).
-                    const ctx = this.operationContext(rt, subject, undefined, signals, session);
+                    const ctx = this.operationContext(rt, subject, undefined, signals, session, operation);
                     const clonedInput = structuredClone(input);
                     // #893: parse, don't trust — at the scope door, from the operation's own
                     // declaration. BEFORE `BEGIN`, so a malformed call never opens a
@@ -2648,6 +2830,8 @@ export class SqliteScopeHost {
             // was impersonating, because `DomainEvent.impersonation` is optional — the
             // shape module code never sees is also the shape it cannot branch on.
             ...(row.impersonation ? { impersonation: JSON.parse(row.impersonation) } : {}),
+            // #1231: absent rather than null, the same shape rule as the stamp above.
+            ...(row.operation ? { operation: row.operation } : {}),
             payload: row.payload === null ? undefined : JSON.parse(row.payload),
         });
     }
@@ -5087,19 +5271,39 @@ export class SqliteScopeHost {
                 }));
             },
             recordOpsFailure: async (entry) => {
+                const at = new Date().toISOString();
+                const fingerprint = opsFailureFingerprint(entry);
                 this.directory
                     .prepare(`INSERT INTO _substrat_ops_failures
-               (id, actor, operation, stage, tenant_id, scope_id, vertical, status, message, reference, at)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                    .run(ulid(), entry.actor, entry.operation, entry.stage ?? null, entry.tenantId ?? null, entry.scopeId ?? null, entry.vertical ?? null, entry.status ?? null, 
+               (id, actor, operation, stage, tenant_id, scope_id, vertical, version, status, message, reference, origin, code, fingerprint, at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(ulid(), entry.actor, entry.operation, entry.stage ?? null, entry.tenantId ?? null, entry.scopeId ?? null, entry.vertical ?? null, entry.version ?? null, entry.status ?? null, 
                 // Bounded here, not trusted from the catch site: one runaway upstream
                 // body must not become a runaway directory row (#559).
-                entry.message.slice(0, 2000), entry.reference ?? null, new Date().toISOString());
+                entry.message.slice(0, 2000), entry.reference ?? null, entry.origin ?? null, entry.code ?? null, fingerprint, at);
                 // Prune-on-write (#559): retention lives here, not in a cron — every insert
                 // pays for its own housekeeping, so the table stays bounded even where no
                 // scheduled pass runs (this adapter has none).
                 const horizon = new Date(Date.now() - OPS_FAILURE_RETENTION_DAYS * 86_400_000).toISOString();
                 this.directory.prepare('DELETE FROM _substrat_ops_failures WHERE at < ?').run(horizon);
+                // The issues materialization (#1233): the group's counters live on their
+                // own row, bumped in the same call, because the evidence self-prunes above
+                // and a count must survive its own exemplars. A fresh arrival regresses a
+                // resolved issue; an ignored one stays ignored — that is what ignoring means.
+                this.directory
+                    .prepare(`INSERT INTO _substrat_issues
+               (fingerprint, operation, stage, origin, code, status, seen_count, first_seen, last_seen, last_message, last_vertical, resolved_at)
+             VALUES (?, ?, ?, ?, ?, 'new', 1, ?, ?, ?, ?, NULL)
+             ON CONFLICT (fingerprint) DO UPDATE SET
+               seen_count = seen_count + 1,
+               last_seen = excluded.last_seen,
+               last_message = excluded.last_message,
+               last_vertical = COALESCE(excluded.last_vertical, last_vertical),
+               origin = COALESCE(excluded.origin, origin),
+               status = CASE WHEN status = 'resolved' THEN 'regressed' ELSE status END`)
+                    .run(fingerprint, entry.operation, entry.stage ?? null, entry.origin ?? null, entry.code ?? null, at, at, entry.message.slice(0, 2000), entry.vertical ?? null);
+                const issueHorizon = new Date(Date.now() - ISSUE_RETENTION_DAYS * 86_400_000).toISOString();
+                this.directory.prepare('DELETE FROM _substrat_issues WHERE last_seen < ?').run(issueHorizon);
             },
             listOpsFailures: async (actor, filter) => {
                 const where = [];
@@ -5116,10 +5320,22 @@ export class SqliteScopeHost {
                     where.push('vertical = ?');
                     params.push(filter.vertical);
                 }
+                if (filter?.version) {
+                    where.push('version = ?');
+                    params.push(filter.version);
+                }
                 if (filter?.operation) {
                     where.push('operation = ?');
                     params.push(filter.operation);
                 }
+                if (filter?.code) {
+                    where.push('code = ?');
+                    params.push(filter.code);
+                }
+                if (filter?.fingerprint) {
+                    where.push('fingerprint = ?');
+                    params.push(filter.fingerprint);
+                }
                 if (filter?.reference) {
                     where.push('reference = ?');
                     params.push(filter.reference);
@@ -5158,12 +5374,130 @@ export class SqliteScopeHost {
                     tenantId: r.tenant_id,
                     scopeId: r.scope_id,
                     vertical: r.vertical,
+                    version: r.version,
                     status: r.status,
                     message: r.message,
                     reference: r.reference,
+                    origin: r.origin,
+                    code: r.code,
+                    fingerprint: r.fingerprint,
+                    at: r.at,
+                }));
+            },
+            recordSweepRun: async (entry) => {
+                this.directory
+                    .prepare(`INSERT OR IGNORE INTO _substrat_sweep_runs
+               (id, kind, unit, outcome, tenant_id, scope_id, vertical, version, operation,
+                connection_id, error, elapsed_ms, request_id, event_type, observed_at, at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(ulid(), entry.kind, entry.unit, entry.outcome, entry.tenantId ?? null, entry.scopeId ?? null, entry.vertical ?? null, entry.version ?? null, entry.operation ?? null, entry.connectionId ?? null, 
+                // Bounded here, not trusted from the sweep: one runaway provider body
+                // must not become a runaway directory row (the #559 rule).
+                entry.error == null ? null : entry.error.slice(0, 2000), entry.elapsedMs ?? null, entry.requestId ?? null, entry.eventType ?? null, entry.observedAt ?? null, entry.at ?? new Date().toISOString());
+                // Prune-on-write, like ops failures and for the same reason: the table stays
+                // bounded even on a deployment whose scheduled pass is broken.
+                const horizon = new Date(Date.now() - SWEEP_RUN_RETENTION_DAYS * 86_400_000).toISOString();
+                this.directory.prepare('DELETE FROM _substrat_sweep_runs WHERE at < ?').run(horizon);
+            },
+            listSweepRuns: async (actor, filter) => {
+                const where = [];
+                const params = [];
+                const eq = (col, v) => {
+                    if (v !== undefined) {
+                        where.push(`${col} = ?`);
+                        params.push(v);
+                    }
+                };
+                eq('kind', filter?.kind);
+                eq('unit', filter?.unit);
+                eq('outcome', filter?.outcome);
+                eq('tenant_id', filter?.tenantId);
+                eq('scope_id', filter?.scopeId);
+                eq('vertical', filter?.vertical);
+                eq('connection_id', filter?.connectionId);
+                if (filter?.since) {
+                    where.push('at >= ?');
+                    params.push(filter.since);
+                }
+                if (filter?.until) {
+                    where.push('at < ?');
+                    params.push(filter.until);
+                }
+                // Default DESC: "last run" and the recent-runs strip both read newest-first.
+                const order = (filter?.order ?? 'desc') === 'desc' ? 'DESC' : 'ASC';
+                if (filter?.cursor) {
+                    where.push(order === 'DESC' ? 'id < ?' : 'id > ?');
+                    params.push(filter.cursor);
+                }
+                let sql = 'SELECT * FROM _substrat_sweep_runs' +
+                    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+                    ` ORDER BY id ${order}`;
+                if (filter?.limit !== undefined) {
+                    sql += ' LIMIT ?';
+                    params.push(filter.limit);
+                }
+                const rows = this.directory.prepare(sql).all(...params);
+                // Rows can name tenants and scopes, so reading them is recorded (K-24).
+                this.recordAccess(actor, 'listSweepRuns', { tenantId: filter?.tenantId ?? null, scopeId: filter?.scopeId ?? null }, filter, rows.length);
+                return rows.map((r) => sweepRunEntry.parse({
+                    id: r.id,
+                    kind: r.kind,
+                    unit: r.unit,
+                    outcome: r.outcome,
+                    tenantId: r.tenant_id,
+                    scopeId: r.scope_id,
+                    vertical: r.vertical,
+                    version: r.version,
+                    operation: r.operation,
+                    connectionId: r.connection_id,
+                    error: r.error,
+                    elapsedMs: r.elapsed_ms,
+                    eventType: r.event_type,
+                    observedAt: r.observed_at,
                     at: r.at,
                 }));
             },
+            listIssues: async (actor, filter) => {
+                const where = [];
+                const params = [];
+                if (filter?.status) {
+                    where.push('status = ?');
+                    params.push(filter.status);
+                }
+                if (filter?.operation) {
+                    where.push('operation = ?');
+                    params.push(filter.operation);
+                }
+                if (filter?.code) {
+                    where.push('code = ?');
+                    params.push(filter.code);
+                }
+                // No cursor by design: grouping IS the compression — cardinality is the
+                // number of distinct failure shapes, not the number of failures.
+                const sql = 'SELECT * FROM _substrat_issues' +
+                    (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
+                    ' ORDER BY last_seen DESC, fingerprint LIMIT ?';
+                params.push(filter?.limit ?? 100);
+                const rows = this.directory.prepare(sql).all(...params);
+                // Issues aggregate fleet-wide failures; the read is recorded like the rows' own (K-24).
+                this.recordAccess(actor, 'listIssues', {}, filter, rows.length);
+                return rows.map((r) => issueEntry.parse(issueOf(r)));
+            },
+            setIssueStatus: async (actor, fingerprint, status) => {
+                const existing = this.directory
+                    .prepare('SELECT * FROM _substrat_issues WHERE fingerprint = ?')
+                    .get(fingerprint);
+                if (!existing)
+                    return undefined;
+                const resolvedAt = status === 'resolved' ? new Date().toISOString() : null;
+                this.directory
+                    .prepare('UPDATE _substrat_issues SET status = ?, resolved_at = ? WHERE fingerprint = ?')
+                    .run(status, resolvedAt, fingerprint);
+                const after = issueEntry.parse(issueOf({ ...existing, status, resolved_at: resolvedAt }));
+                // A lifecycle flip is a staff mutation — audited with the diff (K-33).
+                this.recordAdmin(actor, 'setIssueStatus', { tenantId: null, vertical: after.lastVertical }, { fingerprint, status: existing.status }, { fingerprint, status: after.status });
+                return after;
+            },
             recordModelUsage: async (input) => {
                 const l = input.line;
                 // INSERT OR IGNORE on the UNIQUE request id: the drain may replay a settled-then-
@@ -5330,6 +5664,22 @@ export class SqliteScopeHost {
         ]) {
             this.ensureColumn(this.directory, '_substrat_entitlements', col, ddl);
         }
+        // The signals `version` stamp (#1231): a directory created before the column
+        // must still open, and an old row's NULL reads as "predates the stamp".
+        this.ensureColumn(this.directory, '_substrat_ops_failures', 'version', 'version TEXT');
+        // The error shape (#1233): who refused + the taxonomy code, on a directory that predates them.
+        this.ensureColumn(this.directory, '_substrat_ops_failures', 'origin', 'origin TEXT');
+        this.ensureColumn(this.directory, '_substrat_ops_failures', 'code', 'code TEXT');
+        // #1233: the grouping key + its exemplar-walk index — created only after the
+        // column exists on every path, the sweep-runs pattern.
+        this.ensureColumn(this.directory, '_substrat_ops_failures', 'fingerprint', 'fingerprint TEXT');
+        this.directory.exec('CREATE INDEX IF NOT EXISTS _substrat_ops_failures_fingerprint ON _substrat_ops_failures (fingerprint, id)');
+        // #1232: the drained batch's dedupe key, on a directory created before it. The
+        // unique index rides here too — created after the column exists on every path.
+        this.ensureColumn(this.directory, '_substrat_sweep_runs', 'request_id', 'request_id TEXT');
+        this.ensureColumn(this.directory, '_substrat_sweep_runs', 'event_type', 'event_type TEXT');
+        this.ensureColumn(this.directory, '_substrat_sweep_runs', 'observed_at', 'observed_at TEXT');
+        this.directory.exec('CREATE UNIQUE INDEX IF NOT EXISTS _substrat_sweep_runs_intent ON _substrat_sweep_runs (request_id, unit)');
         const existing = new Set(this.directory.prepare('PRAGMA table_info(scopes)').all().map((c) => c.name));
         for (const [column, ddl] of [
             ['parent_scope_id', 'parent_scope_id TEXT'],
@@ -5400,7 +5750,13 @@ export class SqliteScopeHost {
      * on it, and "hide this row when support is looking" is the one behaviour
      * this whole feature exists to make impossible.
      */
-    impersonation) {
+    impersonation, 
+    /**
+     * #1231: the exact `invoke()` string this context runs on behalf of — stamped
+     * onto every event it emits. Absent for consumer dispatch: a consumer runs on
+     * behalf of no operation, and the emitted row's NULL says so.
+     */
+    operation) {
         const principal = subject.id;
         const checker = this.checker;
         const relations = this.relations;
@@ -5522,14 +5878,21 @@ export class SqliteScopeHost {
                                 : principal),
                     ...(passed.length ? { authorization: passed.map((p) => ({ ...p })) } : {}),
                     ...(stamp ? { impersonation: stamp } : {}),
+                    // #1231: kernel-stamped like the two above — `domainEventInput.parse`
+                    // already stripped anything module code tried to smuggle under this key.
+                    ...(operation ? { operation } : {}),
                 });
                 rt.db
                     .prepare(`INSERT INTO _substrat_outbox
                (id, type, schema_version, occurred_at, tenant_id, scope_id, actor,
                 entity_type, entity_id, pii_class, subject_id, authorization,
-                impersonation, payload)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                    .run(full.id, full.type, full.schemaVersion, full.occurredAt, full.tenantId, full.scopeId, JSON.stringify(full.actor), full.entity.entityType, full.entity.entityId, full.piiClass, full.subjectId ?? null, full.authorization ? JSON.stringify(full.authorization) : null, full.impersonation ? JSON.stringify(full.impersonation) : null, full.payload === undefined ? null : JSON.stringify(full.payload));
+                impersonation, operation, version, payload)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(full.id, full.type, full.schemaVersion, full.occurredAt, full.tenantId, full.scopeId, JSON.stringify(full.actor), full.entity.entityType, full.entity.entityId, full.piiClass, full.subjectId ?? null, full.authorization ? JSON.stringify(full.authorization) : null, full.impersonation ? JSON.stringify(full.impersonation) : null, full.operation ?? null, 
+                // #1242: host configuration, not envelope data — the version is a fact
+                // about the process, so it never rides `DomainEvent` for module code to
+                // branch on; it exists for the observability joins the column serves.
+                this.versionId, full.payload === undefined ? null : JSON.stringify(full.payload));
             },
             requestPlatform: (request) => {
                 assertImpersonationWrites(impersonation, 'ctx.requestPlatform');
@@ -5815,14 +6178,15 @@ export class SqliteScopeHost {
             throw new Error(`unknown scope for tenant: (${tenantId}, ${scopeId})`);
         return this.runtime(tenantId, scopeId).db;
     }
-    runtime(tenantId, scopeId) {
-        const key = `${tenantId}/${scopeId}`;
-        const existing = this.scopes.get(key);
-        if (existing)
-            return existing;
-        const db = new Database(join(this.dir, `${tenantId}__${scopeId}.sqlite`));
-        db.pragma('journal_mode = WAL');
-        db.exec(KERNEL_DDL);
+    /**
+     * The additive spine-column migrations, shared by `runtime()` and the dump replay.
+     * KERNEL_DDL is all IF NOT EXISTS, so a scope DB created before a column keeps the
+     * old shape — and so does a table a DUMP replay just recreated from legacy DDL,
+     * which is why `loadDump` re-runs this after its replay: `runtime()` already ran
+     * for that scope, and without the re-run the very next emit in this process fails
+     * with `no such column`.
+     */
+    ensureSpineColumns(db) {
         // KERNEL_DDL is all IF NOT EXISTS, so a scope DB created before K-21 keeps the
         // old shape — ALTER the tombstone in.
         this.ensureColumn(db, '_substrat_tuples', 'revoked_at', 'revoked_at TEXT');
@@ -5847,6 +6211,22 @@ export class SqliteScopeHost {
         this.ensureColumn(db, '_substrat_outbox', 'impersonation', 'impersonation TEXT');
         this.ensureColumn(db, '_substrat_platform_requests', 'impersonation', 'impersonation TEXT');
         this.ensureColumn(db, '_substrat_denials', 'impersonation', 'impersonation TEXT');
+        // #1231: the emitting operation, on a scope DB created before the column. Nullable
+        // so every legacy row reads as unrecorded rather than claiming a name nobody stamped.
+        this.ensureColumn(db, '_substrat_outbox', 'operation', 'operation TEXT');
+        // #1242: the signals `version` dimension on the outbox, for a scope DB created
+        // before the column. NULL stays honest — unstamped, not a version nobody named.
+        this.ensureColumn(db, '_substrat_outbox', 'version', 'version TEXT');
+    }
+    runtime(tenantId, scopeId) {
+        const key = `${tenantId}/${scopeId}`;
+        const existing = this.scopes.get(key);
+        if (existing)
+            return existing;
+        const db = new Database(join(this.dir, `${tenantId}__${scopeId}.sqlite`));
+        db.pragma('journal_mode = WAL');
+        db.exec(KERNEL_DDL);
+        this.ensureSpineColumns(db);
         const appliedMigrations = new Set(db.prepare('SELECT module_id, version FROM _substrat_migrations').all().map((r) => `${r.module_id}@${r.version}`));
         const created = { tenantId, scopeId, db, actor: new ScopeActor(), appliedMigrations };
         this.scopes.set(key, created);