@substrat-run/adapter-sqlite 0.133.0 → 0.135.0

package/dist/index.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { dirname, join } from 'node:path';
 import Database from 'better-sqlite3';
 import { accessLogEntry, adminLogEntry, delegatedReadParams, opsFailureEntry, opsFailureFingerprint, issueEntry, FRESHNESS_HEARTBEAT_MINUTES, sweepRunEntry, modelUsageEntry, ATTACHMENT_ADDED, ATTACHMENT_REMOVED, attachmentRecord, createTenantInput, domainEvent, domainEventInput, exportReadInput, importBatch, importCursorMove, exportsOfManifestJson, importsOfManifestJson, entitlementGrant, entitlementGrantInput, eventId, meterReading, platformRequestInput, platformRequestId, MAX_PENDING_PLATFORM_REQUESTS, identityLink, identityPool, instant, connection, capabilityGrant, connectionGrant, connectionGrantRecord, connectionSecret, systemGrant, systemSwitch, systemSwitchRecord, peerSwitch, verticalCaller, verticalSlug as verticalSlugOf, subjectRef, requestFingerprint, createConnectionInput, projectedConnectionGrant, projectedConnectionKey, moduleManifest, createOrgInput, promotionAcknowledgement, bindAcknowledgement, bindHostnameInput, channelHistoryEntry, hostnameBinding, publishVersionInput, AUTO_ADMISSION_NOTE, routeTarget, registerVerticalInput, vertical as verticalSchema, verticalChannel, verticalVersion, objectRef, entityObjectRef, assertModuleEmittableType, assertKernelAuthoredType, grantRefFromProof, org as orgSchema, orgMembership, principalId, resolvedIdentity, identityMembership, roleDefinition, scope as scopeSchema, tenant as tenantSchema, tenantRole, subjectShredReceipt, SCOPE_TABLE_PAGE_DEFAULT, SCOPE_TABLE_PAGE_MAX, SCOPE_QUERY_ROW_MAX, verticalServingState, callsOfManifestJson, outboundOfManifestJson, listLimitOf, substratError, assertReplayableDump, delegatedReadRecord, ownerTransferAudit, redrainEventsInput, REDRAIN_BATCH, } from '@substrat-run/contracts';
-import { actorOf, asPrincipal, assertAllowed, assertNoSecret, assertPermissionKey, CAPABILITY_DDL, CAPABILITY_EXCHANGE_OPERATION, capabilityAttachmentWriteRefused, capabilityTokenHash, createCapabilityVerbs, createEntityEdgeVerbs, exchangeCapability as exchangeCapabilitySecret, guardSecrets, mintBecomeCapability, plausibleSessionToken, redactSecrets, redactSecretText, moduleLog, consoleLogSink, resolveCapabilitySession, revokeCapabilityAsPlatform, assertReadOnlyQuery, attachmentBlobKey, entitlementDenial, foldMeterReading, guardSpine, guardSqlLimits, DO_SQL_LIMITS, tooManyResultColumns, tooManyTableColumns, parseValidationRecords, resolveScopeRecord, ulid, ISSUE_RETENTION_DAYS, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, SWEEP_RUNS_INTENT_INDEX, sweepRunsIntentHasKind, MODEL_USAGE_RETENTION_DAYS, foldModelUsage, backoffAt, platformRequestHistoryQuery, platformRequestOf, PLATFORM_REQUEST_COLUMNS, PLATFORM_REQUEST_REDACTION_SQL, platformRequestRedactionParams, platformRequestRedactionQuery, intentPayloadCarriesSubject, redactSubjectJobRuns, JOB_RUN_PATCH_SQL, JOB_STEP_RECORD_SQL, DELIVERY_ERROR_REDACTION_SQL, REDACTED_DELIVERY_NOTE, seatScopeTuple, switchSystemSchedules, admitPeer, collectPeers, peerSeats, resolveVerticalInstanceFrom, switchPeer, peerGrantsStatus, systemGrantsStatus, systemScheduleState, systemSwitchedOff, systemSwitchedOffMessage, tenantSystemSwitchedOffMessage, SYSTEM_SWITCHES_BACKFILL_SQL, SYSTEM_SWITCHES_DDL, forgetSystemSwitchesOf, listSystemSwitchRecords, recordSystemSwitchedOff, recordSystemSwitchedOn, restoreSystemSwitchRecord, scopesSwitchedOffFor, switchedOffModulesOf, inUnitMovesToAudit, staleCarryRevertRow, staleCarryReverts, systemSwitchRecordsOf, systemSwitchesTableExists, withRecorded, VERSION_MIGRATIONS_DDL, splitManifestMigrations, splitVersionMigrationsBatch, versionMigrationsOf, writeVersionMigrations, denialListQuery, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, IMPERSONATION_COLUMNS, IMPERSONATION_DDL, ImpersonationRefused, assertImpersonationWrites, assertModuleEnqueueableKind, assertSessionUsable, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, impersonationStampOf, mapImpersonationRow, newImpersonationSession, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, noSealingKeyMessage, openSealed, sealTo, ConnectionSealingKeyUnavailableError, PermissionDenied, createAtomic, NotSearchable, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, moduleMigrations, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, searchLimit, searchMatchExpression, searchQuery, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, SCHEDULE_STATE_DDL, SCHEDULE_STATE_REBUILD, scheduleStateHasKind, VERTICAL_EVENTS_DDL, EXPORT_HOPS_SQL, IMPORT_CURSORS_SQL, IMPORT_CURSOR_OF_SQL, OUTBOX_MARK_SQL, emittedSinceQuery, emittedReportOf, EMITTED_REPORT_CAP, exportedSinceQuery, IMPORT_CURSOR_ADVANCE_SQL, IMPORT_RECORD_SQL, moveImportCursor, importCursorSourceOf, exportBreaksOf, exportBreakRefusal, bindExportBreaksOf, bindExportBreakRefusal, CrossVerticalRegistry, exportReadPlan, exportReadQuery, planExportBatch, withheldNote, JOB_RUN_DDL, jobRunListLimit, jobRunOf, runDueJobRuns, startJobRun, IDEMPOTENCY_DDL, REFUSALS_DDL, refusalInsert, refusedTransitionOf, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, globalFetch, createUlid, facetEvents, readHistory, walkEventCause, walkEventEffects, assertRedrainWindow, readInvocation, readDeadLetters, readLifecycleFlow, domainEventOf, readUndrainedOutbox, undrainedEventsOf, connectorCallRecord, noopConnectorCallRecorder, recordConnectorCall, settleConnectionUse, unknownRoleError, } from '@substrat-run/kernel';
+import { actorOf, asPrincipal, assertAllowed, assertNoSecret, assertPermissionKey, CAPABILITY_DDL, CAPABILITY_EXCHANGE_OPERATION, capabilityAttachmentWriteRefused, capabilityTokenHash, createCapabilityVerbs, createEntityEdgeVerbs, exchangeCapability as exchangeCapabilitySecret, guardSecrets, mintBecomeCapability, plausibleSessionToken, readCapabilityPage, redactSecrets, redactSecretText, moduleLog, consoleLogSink, resolveCapabilitySession, revokeCapabilityAsPlatform, assertReadOnlyQuery, attachmentBlobKey, attachmentSha256, entitlementDenial, requiredEntitlementFor, foldMeterReading, guardSpine, guardSqlLimits, DO_SQL_LIMITS, tooManyResultColumns, tooManyTableColumns, parseValidationRecords, resolveScopeRecord, ulid, ISSUE_RETENTION_DAYS, telemetryRetentionStatements, assertRowLimit, assertRowOffset, OPS_FAILURE_RETENTION_DAYS, SWEEP_RUN_RETENTION_DAYS, SWEEP_RUNS_INTENT_INDEX, sweepRunsIntentHasKind, MODEL_USAGE_RETENTION_DAYS, foldModelUsage, backoffAt, platformRequestHistoryQuery, platformRequestOf, PLATFORM_REQUEST_COLUMNS, PLATFORM_REQUEST_REDACTION_SQL, platformRequestRedactionParams, platformRequestRedactionQuery, intentPayloadCarriesSubject, redactSubjectJobRuns, redactSubjectScopeText, redactSubjectDirectoryText, ISSUE_EXEMPLAR_OWNER_BACKFILL_SQL, issueExemplarOwner, JOB_RUN_PATCH_SQL, JOB_STEP_RECORD_SQL, DELIVERY_ERROR_REDACTION_SQL, REDACTED_DELIVERY_NOTE, seatScopeTuple, switchSystemSchedules, admitPeer, collectPeers, peerSeats, resolveVerticalInstanceFrom, switchPeer, peerGrantsStatus, systemGrantsStatus, systemScheduleState, systemSwitchedOff, systemSwitchedOffMessage, tenantSystemSwitchedOffMessage, SYSTEM_SWITCHES_BACKFILL_SQL, SYSTEM_SWITCHES_DDL, forgetSystemSwitchesOf, listSystemSwitchRecords, recordSystemSwitchedOff, recordSystemSwitchedOn, restoreSystemSwitchRecord, scopesSwitchedOffFor, switchedOffModulesOf, inUnitMovesToAudit, staleCarryRevertRow, staleCarryReverts, systemSwitchRecordsOf, systemSwitchesTableExists, withRecorded, VERSION_MIGRATIONS_DDL, splitManifestMigrations, splitVersionMigrationsBatch, versionMigrationsOf, writeVersionMigrations, denialListQuery, refusalListQuery, mapRefusalRow, denialSummaryQuery, denialTotalsQuery, DENIAL_WINDOW_QUERY, mapDenialRow, mapDenialSummaryBuckets, IMPERSONATION_COLUMNS, IMPERSONATION_DDL, ImpersonationRefused, assertImpersonationWrites, assertModuleEnqueueableKind, assertSessionUsable, impersonationByIdQuery, impersonationListQuery, impersonationRowValues, impersonationStampOf, mapImpersonationRow, newImpersonationSession, resolveRetryPolicy, isSecretBoxConfigured, unconfiguredSecretBox, createSubjectKeys, generateSealingKeyPair, noSealingKeyMessage, openSealed, sealTo, ConnectionSealingKeyUnavailableError, PermissionDenied, createAtomic, NotSearchable, NotListable, listIndexMigrations, listIndexPlans, listQuery, cursorOf, moduleMigrations, isSearchIndexTable, searchIndexDdl, searchIndexMigrations, searchIndexPlans, searchLimit, searchMatchExpression, searchQuery, ATTACHMENT_TEXT_DDL, assertAttachmentExtractors, assertJobRegistrable, attachmentRecordOfRow, attachmentTextJob, enqueueAttachmentText, isAttachmentTextRun, reconcileAttachmentText, recordAttachmentText, searchAttachments, entityVersionQuery, entityVersionOf, assertIfMatch, OUTBOX_ENTITY_INDEX, SCHEDULE_STATE_DDL, SCHEDULE_STATE_REBUILD, scheduleStateHasKind, VERTICAL_EVENTS_DDL, EXPORT_HOPS_SQL, IMPORT_CURSORS_SQL, IMPORT_CURSOR_OF_SQL, OUTBOX_MARK_SQL, emittedSinceQuery, emittedReportOf, EMITTED_REPORT_CAP, exportedSinceQuery, IMPORT_CURSOR_ADVANCE_SQL, IMPORT_RECORD_SQL, moveImportCursor, importCursorSourceOf, exportBreaksOf, exportBreakRefusal, bindExportBreaksOf, bindExportBreakRefusal, CrossVerticalRegistry, exportReadPlan, exportReadQuery, planExportBatch, withheldNote, JOB_RUN_DDL, jobRunListLimit, jobRunOf, runDueJobRuns, startJobRun, IDEMPOTENCY_DDL, REFUSALS_DDL, refusalInsert, refusedTransitionOf, assertIdempotencyKey, idempotencyLookupQuery, idempotencyPruneStatement, idempotencyRecordStatement, idempotencyOptedOutMessage, replayFor, globalFetch, createUlid, facetEvents, readHistory, walkEventCause, walkEventEffects, assertRedrainWindow, readInvocation, readDeadLetters, readLifecycleFlow, domainEventOf, readUndrainedOutbox, undrainedEventsOf, connectorCallRecord, noopConnectorCallRecorder, recordConnectorCall, settleConnectionUse, unknownRoleError, } from '@substrat-run/kernel';
 import { attributedHost } from '@substrat-run/kernel';
 import { LEGACY_SCOPE_ROWS_BACKFILL, assertNoSpineReference, assertSpineTablesBuilt, dumpRowsInsert, isSpineTable, loadDirectoryDump, repointScopeGrants, spineColumnAdditions } from '@substrat-run/kernel';
 import { ScopeActor } from './actor.js';
@@ -295,6 +295,9 @@ const KERNEL_DDL = `
   );
   CREATE INDEX IF NOT EXISTS _substrat_attachments_entity
     ON _substrat_attachments (entity_type, entity_id);
+  -- #1575: attachment text and its FTS5 index, shared from @substrat-run/kernel. After
+  -- _substrat_attachments, whose delete trigger it adds.
+  ${ATTACHMENT_TEXT_DDL}
   -- #901: an entity's version is the ULID of the last event about it, so
   -- MAX(id) per (entity_type, entity_id) is the read. The id column sits last so
   -- SQLite walks to the end of the matched range instead of aggregating over it.
@@ -366,7 +369,7 @@ function keysetTail(where, params, key, page, defaultOrder = 'asc') {
     let tail = ` ORDER BY ${key} ${order}`;
     if (page?.limit !== undefined) {
         tail += ' LIMIT ?';
-        params.push(page.limit);
+        params.push(assertRowLimit('limit', page.limit));
     }
     return tail;
 }
@@ -513,7 +516,8 @@ export class SqliteScopeHost {
     listPlans = new Map();
     /** entityType → the declared attachment gate (#473): read key + write key (default: read). */
     attachmentTargets = new Map();
-    /** operation name → its owning module's entitlementKey (§4.3 gate). */
+    /** operation name → who binds it: the owning module, its entitlementKey and its declared
+     *  schedules — the §4.3 gate's input, resolved per invoke by `requiredEntitlementFor` (#1654). */
     operationEntitlement = new Map();
     /**
      * #893: name → the declared input schema, parsed before guards and handler.
@@ -560,6 +564,8 @@ export class SqliteScopeHost {
     onBehalfOf = null;
     systemPrincipal = principalId.parse(ulid());
     secretBox;
+    /** The parsers attachment text is extracted with (K-43); the host's own, never imported here. */
+    attachmentExtractors;
     fetchImpl;
     connectorCalls;
     clock;
@@ -573,6 +579,8 @@ export class SqliteScopeHost {
     // process-wide `ulid()` that every other id here still uses.
     constructor(options) {
         this.secretBox = options.secretBox ?? unconfiguredSecretBox;
+        assertAttachmentExtractors(options.attachmentExtractors ?? []);
+        this.attachmentExtractors = options.attachmentExtractors ?? [];
         this.fetchImpl = options.fetch ?? globalFetch;
         this.connectorCalls = options.connectorCalls ?? noopConnectorCallRecorder;
         this.clock = options.clock ?? (() => instant.parse(new Date().toISOString()));
@@ -1113,6 +1121,12 @@ export class SqliteScopeHost {
         first_seen TEXT NOT NULL,
         last_seen TEXT NOT NULL,
         last_message TEXT NOT NULL,
+        -- #1632: whose ops failure last_message was copied from, written in the same
+        -- statement as the message: last_owner_kind is 'tenant' (last_tenant_id names it) or
+        -- 'platform' (the platform's own row; last_tenant_id NULL). NULL kind = unknown, an
+        -- issue from before the columns that no retained row attributes.
+        last_tenant_id TEXT,
+        last_owner_kind TEXT,
         last_vertical TEXT,
         last_version TEXT,
         resolved_version TEXT,
@@ -1517,11 +1531,16 @@ export class SqliteScopeHost {
                 `${[...unboundOptOuts].sort().join(', ')} — an opt-out on nothing reads as an ` +
                 'exclusion someone decided, of an operation that does not exist');
         }
+        const entitlementBinding = {
+            moduleId: manifest.id,
+            entitlementKey: manifest.entitlementKey,
+            scheduledOperations: new Set((manifest.schedules ?? []).map((sch) => sch.operation)),
+        };
         for (const [name, handler] of Object.entries(registration.operations ?? {})) {
             this.defineOperation(name, handler);
             // Record which SKU flag gates this operation (§4.3). Bare defineOperation
             // bindings (tests, glue) carry no manifest and stay ungated.
-            this.operationEntitlement.set(name, manifest.entitlementKey);
+            this.operationEntitlement.set(name, entitlementBinding);
             // #893: withdrawal removes the binding, so the schema follows the handler
             // rather than the name — a withdrawn operation has nothing to parse for.
             const schema = declaredInputs[name];
@@ -1919,21 +1938,6 @@ export class SqliteScopeHost {
             }
             return gate;
         };
-        const rowToRecord = (row) => attachmentRecord.parse({
-            id: row.id,
-            entity: { entityType: row.entity_type, entityId: row.entity_id },
-            filename: row.filename,
-            contentType: row.content_type,
-            size: row.size,
-            sha256: row.sha256,
-            visibility: row.visibility,
-            createdBy: row.created_by,
-            createdAt: row.created_at,
-        });
-        const sha256Hex = async (body) => {
-            const digest = await globalThis.crypto.subtle.digest('SHA-256', body);
-            return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
-        };
         // One attachment mutation/read = one serialized scope task, transactional exactly
         // like an operation invoke (including K-35 denial recording and prompt dispatch of
         // the events it emitted).
@@ -2011,7 +2015,7 @@ export class SqliteScopeHost {
                     filename: input.filename,
                     contentType: input.contentType,
                     size: input.body.byteLength,
-                    sha256: await sha256Hex(input.body),
+                    sha256: await attachmentSha256(input.body),
                     visibility: input.visibility,
                     createdBy: creator.id,
                     createdAt: new Date().toISOString(),
@@ -2036,6 +2040,9 @@ export class SqliteScopeHost {
                             piiClass: 'none',
                             payload: { attachment: record },
                         });
+                        // #1575: queue its text extraction in the same transaction — a `pending` row
+                        // and a job run. Nothing is extracted here, so nothing here can fail the upload.
+                        enqueueAttachmentText(spineSql(rt.db), record.id, ulid(), this.clock());
                         return record;
                     });
                 }
@@ -2054,7 +2061,7 @@ export class SqliteScopeHost {
                     .prepare(`SELECT * FROM _substrat_attachments WHERE entity_type = ? AND entity_id = ?
                ORDER BY id DESC`)
                     .all(entity.entityType, entity.entityId);
-                return rows.map(rowToRecord);
+                return rows.map(attachmentRecordOfRow);
             }),
             open: async (attachmentId) => {
                 const record = await guarded('attachments.open', async (ctx) => {
@@ -2065,11 +2072,11 @@ export class SqliteScopeHost {
                         return null;
                     if (opts.admitByEvent !== undefined) {
                         admitByDelivery(rt, opts.admitByEvent, row);
-                        return rowToRecord(row);
+                        return attachmentRecordOfRow(row);
                     }
                     const gate = targetGate(row.entity_type);
                     assertAllowed(await ctx.check(gate.read, { entityType: row.entity_type, entityId: row.entity_id }));
-                    return rowToRecord(row);
+                    return attachmentRecordOfRow(row);
                 });
                 if (!record)
                     return null;
@@ -2078,7 +2085,7 @@ export class SqliteScopeHost {
                     throw new Error(`attachment ${record.id}: bytes missing from the blob store — the metadata row ` +
                         `survived something the object did not (rewind/reap); see the #473 integrity notes`);
                 }
-                if ((await sha256Hex(obj.body)) !== record.sha256) {
+                if ((await attachmentSha256(obj.body)) !== record.sha256) {
                     throw new Error(`attachment ${record.id}: bytes do not match the recorded sha256`);
                 }
                 return { record, body: obj.body, contentType: obj.contentType ?? record.contentType };
@@ -2098,7 +2105,7 @@ export class SqliteScopeHost {
                     const gate = targetGate(row.entity_type);
                     assertAllowed(await ctx.check(gate.write, { entityType: row.entity_type, entityId: row.entity_id }));
                     rt.db.prepare('DELETE FROM _substrat_attachments WHERE id = ?').run(attachmentId);
-                    const record = rowToRecord(row);
+                    const record = attachmentRecordOfRow(row);
                     kernelEmit(ctx, {
                         type: ATTACHMENT_REMOVED,
                         schemaVersion: 1,
@@ -2114,6 +2121,18 @@ export class SqliteScopeHost {
                     await store.delete(attachmentBlobKey(rt.scopeId, removed.id)).catch(() => { });
                 return removed;
             },
+            // #1575: extracted text, gated per hit by the check `open` makes, before the limit.
+            search: async (term, options) => {
+                if (opts.admitByEvent !== undefined) {
+                    // The delivery-admitted surface reads the ONE attachment its delivery names; a
+                    // search would reach past it. Nothing builds this surface for anything but `open`.
+                    throw new Error('attachments.search is not available on a delivery-scoped surface');
+                }
+                // The term is judged before the turn: a refusal costs no queue slot.
+                searchMatchExpression(term, 'prefix');
+                // Authorized first, as this surface's subject, then matched over readable owners only.
+                return guarded('attachments.search', (ctx) => searchAttachments(spineSql(rt.db), { targets: this.attachmentTargets, check: (permission, entity) => ctx.check(permission, entity) }, term, searchLimit(options?.limit)));
+            },
         };
     }
     async importScope(actor, input, dump) {
@@ -2224,6 +2243,10 @@ export class SqliteScopeHost {
                 if (present.has(plan.table))
                     db.exec(searchIndexDdl(plan));
             }
+            // #1575: attachment text is not in a dump, so a load left it as it was. Drop the
+            // text of attachments the dump did not bring back, and queue extraction for those
+            // it brought back without text — the bytes decide what that run finds.
+            reconcileAttachmentText(spineSql(db), ulid, this.clock());
             // Re-point scope-level grants at the scope they now live in. They are written as
             // `object = scope:<scopeId>`, so a fork, a restore into a different scope, or #286's
             // migration onto a stable script name all land rows naming a scope that is not this
@@ -3155,7 +3178,13 @@ export class SqliteScopeHost {
                 // only if the tenant holds its SKU flag. Checked per invoke — the simple,
                 // uncached path (K-OQ5); a DO-cached variant is a later benchmark call.
                 // Fails closed the same way withdrawal does: the operation is unavailable.
-                const requiredKey = this.operationEntitlement.get(operation);
+                //
+                // EXCEPTION (#1654): a module's own declared schedule, through the system door,
+                // demands no SKU — its `system:<moduleId>` grant is the switch, as it already is
+                // for permissions (#383). The kernel's `requiredEntitlementFor` holds the rule and
+                // why, and the Cloudflare coordinator runs the same predicate. Every other door
+                // (principal, connection, capability, peer, impersonation) is gated as before.
+                const requiredKey = requiredEntitlementFor(operation, this.operationEntitlement.get(operation), authority.kind === 'system' ? authority.id : undefined);
                 if (requiredKey && !this.tenantHoldsEntitlement(tenantId, requiredKey)) {
                     return Promise.reject(substratError('not_found', entitlementDenial(operation, requiredKey, this.heldEntitlements(tenantId))));
                 }
@@ -3571,6 +3600,8 @@ export class SqliteScopeHost {
         return rt.actor.enqueue(() => this.dispatchExecutors(rt, null));
     }
     registerJob(moduleId, name, handler, retry) {
+        // #1575: the kernel's own jobs are dispatched before this registry is read.
+        assertJobRegistrable(moduleId, name);
         const key = `${moduleId}/${name}`;
         if (this.jobs.has(key))
             throw new Error(`job '${key}' is already registered`);
@@ -3674,6 +3705,27 @@ export class SqliteScopeHost {
             }),
         };
     }
+    /**
+     * The extraction job's adapter half (#1575): the record and the bytes with no permission
+     * gate — extraction is the kernel's own derivation, and the person-facing gate is at
+     * search — and the outcome written in a turn of its own, like every job store write.
+     */
+    attachmentTextHandler(rt) {
+        return attachmentTextJob({
+            record: (attachmentId) => rt.actor.enqueue(() => {
+                const row = rt.db.prepare('SELECT * FROM _substrat_attachments WHERE id = ?').get(attachmentId);
+                return row ? attachmentRecordOfRow(row) : null;
+            }),
+            bytes: async (record) => {
+                const scope = this.directory.prepare('SELECT vertical FROM scopes WHERE scope_id = ?').get(rt.scopeId);
+                const store = this.attachmentStore(rt.tenantId, scope?.vertical ?? null);
+                return (await store.get(attachmentBlobKey(rt.scopeId, record.id)))?.body ?? null;
+            },
+            write: (attachmentId, outcome) => rt.actor.enqueue(() => recordAttachmentText(spineSql(rt.db), attachmentId, outcome, this.clock())),
+        }, 
+        // K-43: the host's parsers, handed in — this adapter imports none.
+        this.attachmentExtractors);
+    }
     async startJobRun(tenantId, scopeId, input) {
         const rt = this.runtime(tenantId, scopeId);
         await this.applyPendingMigrations(rt);
@@ -3682,9 +3734,12 @@ export class SqliteScopeHost {
     async runDueJobs(tenantId, scopeId, options) {
         const rt = this.runtime(tenantId, scopeId);
         await this.applyPendingMigrations(rt);
+        // #1575: the kernel's extraction job is this host's own, bound to this scope — no
+        // deployment registers it, and none can shadow it.
+        const attachmentText = { handler: this.attachmentTextHandler(rt) };
         return runDueJobRuns({
             store: this.jobStore(rt),
-            handlerFor: (run) => this.jobs.get(`${run.module_id}/${run.job}`),
+            handlerFor: (run) => isAttachmentTextRun(run) ? attachmentText : this.jobs.get(`${run.module_id}/${run.job}`),
             now: this.clock,
             openScope: (run) => this.getSystemScope(run.module_id, tenantId, scopeId),
             maxPasses: options?.maxPasses,
@@ -4060,7 +4115,7 @@ export class SqliteScopeHost {
             ` ORDER BY id ${order}`;
         if (filter?.limit !== undefined) {
             sql += ' LIMIT ?';
-            params.push(filter.limit);
+            params.push(assertRowLimit('limit', filter.limit));
         }
         const rows = this.directory.prepare(sql).all(...params);
         return rows.map((r) => modelUsageEntryOf(r));
@@ -4415,7 +4470,7 @@ export class SqliteScopeHost {
             // private vertical self-admit, and what lets a LISTED vertical's builder keep
             // previewing their own new code (issue #509 ask (d)).
             if (v.admission !== 'admitted' && scope.kind !== 'preview') {
-                throw new Error(`version ${versionId} is ${v.admission}, not admitted — it cannot be bound to a scope`);
+                throw substratError('conflict', `version ${versionId} is ${v.admission}, not admitted — it cannot be bound to a scope`);
             }
             return { v, scope };
         };
@@ -4828,7 +4883,7 @@ export class SqliteScopeHost {
                     ` ORDER BY tenant_id ${order}, role_key ${order}`;
                 if (filter?.limit !== undefined) {
                     sql += ' LIMIT ?';
-                    params.push(filter.limit);
+                    params.push(assertRowLimit('limit', filter.limit));
                 }
                 const rows = this.directory.prepare(sql).all(...params);
                 // Parsed, not cast: `permissions` is a JSON blob in a TEXT column, so the
@@ -5038,6 +5093,15 @@ export class SqliteScopeHost {
                     revoked: true,
                 });
             },
+            // #1686 — the operator's read of the directory `ctx.capabilities.list` reads. The
+            // denial log's discipline: `scopeReadDbFor` is the K-3 cross-check, the read is the
+            // kernel's one (`readCapabilityPage`: no `token_hash` column in it), and the read leaves a K-24 row.
+            listCapabilities: async (actor, tenantId, scopeId, filter) => {
+                const db = this.scopeReadDbFor(tenantId, scopeId);
+                const page = readCapabilityPage(spineSql(db), filter);
+                this.recordAccess(actor, 'listCapabilities', { tenantId, scopeId }, filter ?? null, page.entries.length);
+                return page;
+            },
             grantToOrg: async (actor, orgId, permission, node, entity) => {
                 // The org must exist in the node's tenant. A grant to a phantom org is
                 // worse than an error: it looks applied, resolves for nobody, and shows up
@@ -5287,7 +5351,7 @@ export class SqliteScopeHost {
                         return;
                     }
                     if (existing.ownerTenant !== parsed.ownerTenant) {
-                        throw new Error(`vertical '${parsed.slug}' is owned by ${existing.ownerTenant ?? 'the platform'}, not ${parsed.ownerTenant ?? 'the platform'}`);
+                        throw substratError('conflict', `vertical '${parsed.slug}' is owned by ${existing.ownerTenant ?? 'the platform'}, not ${parsed.ownerTenant ?? 'the platform'}`);
                     }
                     throw new Error(`vertical '${parsed.slug}' is already registered as ${existing.source}`);
                 }
@@ -5368,7 +5432,7 @@ export class SqliteScopeHost {
                         .get(slug);
                     const prodVersion = prod ? readVersion(prod.version_id) : undefined;
                     if (prodVersion?.admissionNote === AUTO_ADMISSION_NOTE) {
-                        throw new Error(`vertical '${slug}' prod version ${prodVersion.id} is auto-admitted (private self-serve) — ` +
+                        throw substratError('conflict', `vertical '${slug}' prod version ${prodVersion.id} is auto-admitted (private self-serve) — ` +
                             `a staff admit must vouch for it before listing`);
                     }
                 }
@@ -5478,7 +5542,7 @@ export class SqliteScopeHost {
                 if (!v)
                     throw substratError('not_found', `unknown version ${versionId}`);
                 if (v.admission === 'admitted') {
-                    throw new Error(`version ${versionId} is already admitted — it may be bound`);
+                    throw substratError('conflict', `version ${versionId} is already admitted — it may be bound`);
                 }
                 if (v.admission === 'rejected')
                     return; // idempotent
@@ -5507,10 +5571,10 @@ export class SqliteScopeHost {
                 if (!incoming)
                     throw substratError('not_found', `unknown version ${versionId}`);
                 if (incoming.verticalSlug !== verticalSlug) {
-                    throw new Error(`version ${versionId} belongs to '${incoming.verticalSlug}'`);
+                    throw substratError('conflict', `version ${versionId} belongs to '${incoming.verticalSlug}'`);
                 }
                 if (incoming.admission !== 'admitted') {
-                    throw new Error(`version ${versionId} is ${incoming.admission}, not admitted — it cannot be promoted`);
+                    throw substratError('conflict', `version ${versionId} is ${incoming.admission}, not admitted — it cannot be promoted`);
                 }
                 const current = this.directory
                     .prepare('SELECT version_id FROM vertical_channels WHERE vertical_slug = ? AND channel = ?')
@@ -5786,7 +5850,7 @@ export class SqliteScopeHost {
                 // The kernel's read, shared with the DO: the envelope and the columns lifted beside
                 // it (#1242, #1237) are decoded once, and a row that will not decode is stepped over
                 // rather than stalling the scope on it (#1636).
-                const read = readUndrainedOutbox((offset, count) => page.all(count, offset), Math.min(Math.max(limit ?? 200, 1), 1000));
+                const read = readUndrainedOutbox((offset, count) => page.all(count, offset), Math.min(assertRowLimit('limit', limit ?? 200), 1000));
                 this.recordAccess(actor, 'readUndrainedEvents', { tenantId, scopeId }, { limit }, read.events.length);
                 return undrainedEventsOf(read);
             },
@@ -6305,8 +6369,10 @@ export class SqliteScopeHost {
                 const known = new Set(db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table'`).all().map((r) => r.name));
                 if (!known.has(input.table))
                     throw new Error(`unknown table '${input.table}'`);
-                const limit = Math.min(Math.max(1, input.limit ?? SCOPE_TABLE_PAGE_DEFAULT), SCOPE_TABLE_PAGE_MAX);
-                const offset = Math.max(0, input.offset ?? 0);
+                // The ceiling clamps; a bound SQLite would misread (NaN, non-finite, fractional,
+                // negative) is refused instead of reaching LIMIT / OFFSET (#1632).
+                const limit = Math.min(assertRowLimit('limit', input.limit ?? SCOPE_TABLE_PAGE_DEFAULT), SCOPE_TABLE_PAGE_MAX);
+                const offset = assertRowOffset('offset', input.offset ?? 0);
                 const stmt = db.prepare(`SELECT * FROM "${input.table}" LIMIT ? OFFSET ?`).raw(true);
                 const rows = stmt.all(limit, offset).map((row) => row.map(cellToJson));
                 const columns = stmt.columns().map((c) => c.name);
@@ -6375,6 +6441,15 @@ export class SqliteScopeHost {
                     drained: Number(w.drained ?? 0),
                 };
             },
+            // #1745: the refusal log, read like the denial log above — same K-3 cross-check,
+            // same K-24 access row.
+            listRefusals: async (actor, tenantId, scopeId, filter) => {
+                const db = this.scopeReadDbFor(tenantId, scopeId);
+                const q = refusalListQuery(filter);
+                const rows = db.prepare(q.sql).all(...q.params).map(mapRefusalRow);
+                this.recordAccess(actor, 'listRefusals', { tenantId, scopeId }, filter ?? null, rows.length);
+                return rows;
+            },
             exportScope: async (actor, tenantId, scopeId) => {
                 // K-3: cross-check the pair before opening anything (same as the introspection reads).
                 const db = this.scopeReadDbFor(tenantId, scopeId);
@@ -6580,7 +6655,8 @@ export class SqliteScopeHost {
                 // Both scope-side redactions in ONE turn on the scope actor (#1678): issued while an
                 // invoke held its transaction open, they joined it, and its rollback put the
                 // person's PII back after this verb had destroyed the key and receipted the erasure.
-                const { redacted, intentsRedacted, jobRunsRedacted } = await this.runtime(tenantId, scopeId).actor.turn(() => ({
+                const scopeSql = redactionSqlOf(db);
+                const { redacted, intentsRedacted, jobRunsRedacted, text } = await this.runtime(tenantId, scopeId).actor.turn(() => ({
                     redacted: db
                         .prepare(`UPDATE _substrat_outbox SET payload = NULL
                 WHERE subject_id = ? AND pii_class != 'none' AND payload IS NOT NULL`)
@@ -6599,14 +6675,16 @@ export class SqliteScopeHost {
                         .run(REDACTED_DELIVERY_NOTE, REDACTED_DELIVERY_NOTE, subjectId),
                     // The job-run tables (#1632): a run, its cursor or a step's memo can hold a copy
                     // of the same event. The kernel's walk, so the DO runs the identical SQL.
-                    jobRunsRedacted: redactSubjectJobRuns((sql, params) => {
-                        const stmt = db.prepare(sql);
-                        if (stmt.reader)
-                            return stmt.all(...params);
-                        stmt.run(...params);
-                        return [];
-                    }, subjectId, at),
+                    jobRunsRedacted: redactSubjectJobRuns(scopeSql, subjectId, at),
+                    // The free-text copies (#1632), and the tombstoned intents the directory half
+                    // follows. Last, so those ids include every intent tombstoned above.
+                    text: redactSubjectScopeText(scopeSql, subjectId, at),
                 }));
+                const { idempotencyResults, intentIds } = text;
+                // The directory's failure text (#1632) — a drain failure quoting one of those
+                // intents, an issue's exemplar, a sweep record's error. Before the key, for the
+                // ordering reason above.
+                redactSubjectDirectoryText(redactionSqlOf(this.directory), { tenantId, scopeId, subjectId, intentIds });
                 const { existed } = await this.subjectKeysFor(tenantId, scopeId).destroy(subjectId, at);
                 const receipt = subjectShredReceipt.parse({
                     subjectId,
@@ -6622,7 +6700,7 @@ export class SqliteScopeHost {
                 this.recordAdmin(actor, 'shredSubject', { tenantId, scopeId }, null, receipt);
                 // BOTH counts: the access log's number is "how much evidence this destroyed", and
                 // an intent payload is a whole event's worth of it.
-                this.recordAccess(actor, 'shredSubject', { tenantId, scopeId }, { subjectId }, redacted.changes + intentsRedacted + jobRunsRedacted);
+                this.recordAccess(actor, 'shredSubject', { tenantId, scopeId }, { subjectId }, redacted.changes + intentsRedacted + jobRunsRedacted + idempotencyResults);
                 return receipt;
             },
             // -- impersonation (K-42, #868) ----------------------------------------
@@ -7248,6 +7326,7 @@ export class SqliteScopeHost {
                 return info.changes;
             },
             pruneAccessLog: async (actor, limit) => {
+                assertRowLimit('limit', limit);
                 // ONLY drained rows. Age alone is not a licence to delete evidence.
                 const info = this.directory
                     .prepare(`DELETE FROM _substrat_access_log WHERE id IN (
@@ -7305,7 +7384,7 @@ export class SqliteScopeHost {
                     ` ORDER BY id ${order}`;
                 if (filter?.limit !== undefined) {
                     sql += ' LIMIT ?';
-                    params.push(filter.limit);
+                    params.push(assertRowLimit('limit', filter.limit));
                 }
                 const rows = this.directory.prepare(sql).all(...params);
                 // Reading the audit trail is itself audited. Who examined the record of
@@ -7347,17 +7426,19 @@ export class SqliteScopeHost {
                 // 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, last_version, resolved_version, resolved_at)
-             VALUES (?, ?, ?, ?, ?, 'new', 1, ?, ?, ?, ?, ?, NULL, NULL)
+               (fingerprint, operation, stage, origin, code, status, seen_count, first_seen, last_seen, last_message, last_tenant_id, last_owner_kind, last_vertical, last_version, resolved_version, resolved_at)
+             VALUES (?, ?, ?, ?, ?, 'new', 1, ?, ?, ?, ?, ?, ?, ?, NULL, NULL)
              ON CONFLICT (fingerprint) DO UPDATE SET
                seen_count = seen_count + 1,
                last_seen = excluded.last_seen,
                last_message = excluded.last_message,
+               last_tenant_id = excluded.last_tenant_id,
+               last_owner_kind = excluded.last_owner_kind,
                last_vertical = COALESCE(excluded.last_vertical, last_vertical),
                last_version = COALESCE(excluded.last_version, last_version),
                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, entry.version ?? null);
+                    .run(fingerprint, entry.operation, entry.stage ?? null, entry.origin ?? null, entry.code ?? null, at, at, entry.message.slice(0, 2000), entry.tenantId ?? null, issueExemplarOwner(entry.tenantId ?? null), entry.vertical ?? null, entry.version ?? 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);
             },
@@ -7416,7 +7497,7 @@ export class SqliteScopeHost {
                     ` ORDER BY id ${order}`;
                 if (filter?.limit !== undefined) {
                     sql += ' LIMIT ?';
-                    params.push(filter.limit);
+                    params.push(assertRowLimit('limit', filter.limit));
                 }
                 const rows = this.directory.prepare(sql).all(...params);
                 // Rows can name tenants and scopes, so reading them is recorded like the
@@ -7490,7 +7571,7 @@ export class SqliteScopeHost {
                     ` ORDER BY id ${order}`;
                 if (filter?.limit !== undefined) {
                     sql += ' LIMIT ?';
-                    params.push(filter.limit);
+                    params.push(assertRowLimit('limit', filter.limit));
                 }
                 const rows = this.directory.prepare(sql).all(...params);
                 // Rows can name tenants and scopes, so reading them is recorded (K-24).
@@ -7514,6 +7595,15 @@ export class SqliteScopeHost {
                     at: r.at,
                 }));
             },
+            pruneTelemetry: async (_actor, limit) => {
+                // A negative LIMIT is no limit at all to SQLite (#1632): refused before any statement.
+                assertRowLimit('limit', limit);
+                const pruned = { opsFailures: 0, issues: 0, sweepRuns: 0 };
+                for (const { table, sql, params } of telemetryRetentionStatements(Date.now(), limit)) {
+                    pruned[table] = this.directory.prepare(sql).all(...params).length;
+                }
+                return pruned;
+            },
             listIssues: async (actor, filter) => {
                 const where = [];
                 const params = [];
@@ -7534,7 +7624,7 @@ export class SqliteScopeHost {
                 const sql = 'SELECT * FROM _substrat_issues' +
                     (where.length ? ` WHERE ${where.join(' AND ')}` : '') +
                     ' ORDER BY last_seen DESC, fingerprint LIMIT ?';
-                params.push(filter?.limit ?? 100);
+                params.push(assertRowLimit('limit', 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);
@@ -7603,8 +7693,10 @@ export class SqliteScopeHost {
         // Without case, as SQLite resolves a column name: a restore may have added this column
         // already, untyped and spelled as a newer kernel's dump spelled it (#1883).
         const existing = db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name.toLowerCase() === column.toLowerCase());
-        if (!existing)
-            db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+        if (existing)
+            return false;
+        db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+        return true;
     }
     /**
      * #1288: `_substrat_schedule_state`, rebuilt with `kind` in its key on a scope db
@@ -7810,6 +7902,15 @@ export class SqliteScopeHost {
         // #1236: the regression's version pair, on a directory whose issues table predates it.
         this.ensureColumn(this.directory, '_substrat_issues', 'last_version', 'last_version TEXT');
         this.ensureColumn(this.directory, '_substrat_issues', 'resolved_version', 'resolved_version TEXT');
+        // #1632: whose exemplar `last_message` is. Backfilled once, as the columns arrive, from
+        // the retained ops-failure rows that prove it; every other row stays unknown. The columns
+        // and the backfill commit together because this whole pass is `ensureDirectorySchema`'s
+        // one transaction: the backfill's gate is "this call added the column", so a column
+        // committed ahead of a backfill that then failed would read as migrated for good.
+        this.ensureColumn(this.directory, '_substrat_issues', 'last_tenant_id', 'last_tenant_id TEXT');
+        if (this.ensureColumn(this.directory, '_substrat_issues', 'last_owner_kind', 'last_owner_kind TEXT')) {
+            this.directory.exec(ISSUE_EXEMPLAR_OWNER_BACKFILL_SQL);
+        }
         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.
@@ -8619,6 +8720,16 @@ function cellToJson(v) {
         return null;
     return v;
 }
+/** The kernel's erasure walks over one SQLite connection — a read returns its rows, a write none. */
+function redactionSqlOf(db) {
+    return (sql, params) => {
+        const stmt = db.prepare(sql);
+        if (stmt.reader)
+            return stmt.all(...params);
+        stmt.run(...params);
+        return [];
+    };
+}
 /**
  * The connection module code holds. `guardSpine` is what makes "never write
  * `_substrat_*`" a mechanism rather than a lint rule (#954) — the kernel's own