@substrat-run/adapter-sqlite 0.135.0 → 0.136.0

package/dist/index.js

@@ -1,10 +1,11 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 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, 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 { 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, ROUTE_SCOPE_HOSTNAMES_MAX, 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, copyMarkAudit, redrainEventsInput, REDRAIN_BATCH, } from '@substrat-run/contracts';
+import { actorOf, asPrincipal, assertAllowed, assertNoSecret, assertPermissionKey, CAPABILITY_DDL, COPY_ORIGIN_DDL, CAPABILITY_EXCHANGE_OPERATION, capabilityAttachmentWriteRefused, capabilityTokenHash, createCapabilityVerbs, createEntityEdgeVerbs, exchangeCapability as exchangeCapabilitySecret, guardSecrets, mintBecomeCapability, plausibleSessionToken, readCapabilityPage, redactSecrets, redactSecretText, moduleLog, consoleLogSink, asyncInvocationId, asyncLinePass, consoleInvocationLineSink, 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 { INERT_SCOPE_REASON, isPrimaryScopeRow } from '@substrat-run/kernel';
+import { LEGACY_SCOPE_ROWS_BACKFILL, assertNoSpineReference, assertSpineTablesBuilt, capabilitiesForLoad, dumpRowsInsert, isSpineTable, loadDirectoryDump, repointScopeGrants, settleCopiedWork, emittedHere, spineColumnAdditions } from '@substrat-run/kernel';
 import { ScopeActor } from './actor.js';
 import { createTupleChecker } from './checker.js';
 /**
@@ -208,6 +209,9 @@ const KERNEL_DDL = `
   -- an exchange trades that secret for. Spine (kernel-written), shared with the DO adapter
   -- from @substrat-run/kernel so the two cannot part company; the column comments are there.
   ${CAPABILITY_DDL}
+  -- #1686: where a copied scope's data came from, and the event id its own events start above.
+  -- Shared with the other adapter from @substrat-run/kernel; the column comments are there.
+  ${COPY_ORIGIN_DDL}
   -- #383 / #1232 / #1288: the platform sweep's per-scope gating state, holding two
   -- families of row that the kind COLUMN — not the spelling of a key — tells apart.
   -- Spine (kernel-written), never a module migration. Shared with the DO adapter from
@@ -418,11 +422,12 @@ function modelUsageEntryOf(r) {
     });
 }
 /**
- * The policy an undecodable event's executor delivery is journaled under (#1636): one
- * attempt, so the first failure is the dead letter. A decode is pure — retrying it cannot
- * succeed — and the Cloudflare coordinator records the same row with no next attempt.
+ * The policy a delivery that can never succeed is journaled under: one attempt, so the first
+ * is the dead letter, and the Cloudflare coordinator records the same row with no next
+ * attempt. An undecodable event (#1636) — a decode is pure, so a retry cannot succeed — and an
+ * inert scope's delivery (#2005) — a scope does not become primary, so a retry decides the same.
  */
-const UNDECODABLE_RETRY = { maxAttempts: 1, baseDelayMs: 0, maxDelayMs: 0 };
+const TERMINAL_RETRY = { maxAttempts: 1, baseDelayMs: 0, maxDelayMs: 0 };
 /**
  * The dispatch capability (#726 remedy B): a connector delivery may read the attachments
  * of the entity the DELIVERED EVENT names, and nothing else.
@@ -572,6 +577,8 @@ export class SqliteScopeHost {
     versionId;
     /** #1746: where `ctx.log` lines go — the console unless a caller (a test) says otherwise. */
     logSink;
+    /** #1901: where async work's invocation lines go. */
+    invocationLineSink;
     // The mint for event ids (#956) is NOT here: it lives on `ScopeRuntime`, one per
     // scope, seeded from that scope's persisted maximum (#1335). Its own monotonic
     // floor, because the timestamp it stamps comes from `this.clock` — a scripted
@@ -586,6 +593,7 @@ export class SqliteScopeHost {
         this.clock = options.clock ?? (() => instant.parse(new Date().toISOString()));
         this.versionId = options.versionId ?? null;
         this.logSink = options.logSink ?? consoleLogSink;
+        this.invocationLineSink = options.invocationLineSink ?? consoleInvocationLineSink;
         this.dir = options.dir;
         mkdirSync(this.dir, { recursive: true });
         this.directory = new Database(join(this.dir, '_directory.sqlite'));
@@ -2246,6 +2254,10 @@ export class SqliteScopeHost {
             // #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.
+            const switchSql = switchSqlOf(db);
+            // #1686: nothing the source queued runs in a copy; a return leaves it all queued. BEFORE
+            // the extraction queue below, which is this scope's own work, not the source's.
+            settleCopiedWork(switchSql, scopeId, dump.scopeId, this.clock());
             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
@@ -2257,7 +2269,7 @@ export class SqliteScopeHost {
             // (subject, relation, object) is the primary key, so a moved row can meet one the dump
             // already holds here; which one survives is that function's rule too (#1882), judged
             // at this host's clock as the checker judges expiry.
-            repointScopeGrants(switchSqlOf(db), scopeId, { scopeId: dump.scopeId, exact: dump.exact }, this.clock());
+            repointScopeGrants(switchSql, scopeId, { scopeId: dump.scopeId, exact: dump.exact }, this.clock());
             // #1742: inside the replay's transaction, so a failure here rolls the whole load back and
             // the dump's grants never commit without the switch that should cover them.
             afterLoad?.(rt);
@@ -2266,7 +2278,20 @@ export class SqliteScopeHost {
         // load was a SAVEPOINT inside it, and that invoke's rollback undid the restore after
         // this verb had audited it.
         await rt.actor.turn(() => {
-            load(dump.tables);
+            // #1686: a copy into another scope id loads no capability rows; a same-scope restore keeps them.
+            load(capabilitiesForLoad(dump.tables, scopeId, dump.scopeId));
+            // #1335 / #1686: ids resume above the outbox the dump brought, as on a reopen, so a copy's
+            // own events sort above every copied one (`emittedHere()`). A top id that is no ULID leaves
+            // the floor where it was.
+            const top = db.prepare('SELECT MAX(id) AS id FROM _substrat_outbox').get()?.id;
+            if (top) {
+                try {
+                    rt.mintEventId.seedFrom(top);
+                }
+                catch {
+                    // Not a ULID: nothing this mint could have written, so there is no floor to keep.
+                }
+            }
             // The frontier came in with the dump — refresh the cached applied-migration set so
             // a later bind/migrate builds on the loaded state, not the previous one.
             rt.appliedMigrations.clear();
@@ -2602,12 +2627,29 @@ export class SqliteScopeHost {
             const deadLetter = rt.db.prepare(`INSERT OR IGNORE INTO _substrat_deliveries
            (event_id, consumer_module, delivered_at, error, invocation_id)
          VALUES (?, ?, ?, ?, NULL)`);
+            // #1901: one line per (event, importing module), as for the scope's own consumers. The
+            // handler runs as the producer's peer, so that is who the line says it ran as.
+            const lines = asyncLinePass(this.invocationLineSink);
+            const unitOf = (moduleId, eventId, eventType) => ({
+                kind: 'consumer',
+                tenantId: rt.tenantId,
+                scopeId: rt.scopeId,
+                invocationId: asyncInvocationId(null),
+                operation: moduleId,
+                eventType,
+                eventId,
+                attempt: 1,
+                startedAt: Date.now(),
+                principalKind: subject.kind,
+                versionId: this.versionId,
+            });
             // Named and not carried: a dead letter per importing module, so the operator who reads
             // this scope's dead letters sees what the producer sent and why it did not arrive.
             for (const w of batch.withheld) {
                 record.run(w.id, source.scopeId, source.vertical, w.type, w.schemaVersion, w.occurredAt, w.entity.entityType, w.entity.entityId, 0, w.reason, at);
                 for (const moduleId of this.crossVertical.modulesImporting(source.vertical, w.type)) {
                     deadLetter.run(w.id, moduleId, at, withheldNote(w.reason, source.vertical));
+                    lines.write({ ...unitOf(moduleId, w.id, w.type), outcome: 'dead-lettered' });
                 }
                 result.withheld += 1;
             }
@@ -2623,14 +2665,17 @@ export class SqliteScopeHost {
                         // this scope's code changed between the two, so it is refused by version (K-39)
                         // exactly as the producer would have refused it.
                         deadLetter.run(e.id, imp.moduleId, at, withheldNote('version', source.vertical));
+                        lines.write({ ...unitOf(imp.moduleId, e.id, e.type), outcome: 'dead-lettered' });
                         result.deadLettered += 1;
                         continue;
                     }
                     const { hops: _hops, ...fact } = e;
                     const event = structuredClone({ ...fact, source });
+                    const unit = unitOf(imp.moduleId, e.id, e.type);
                     // What the handler emits was emitted BECAUSE of the producer's event (#1237). The id
                     // resolves through `_substrat_imports`, which the row above has just written.
                     rt.causedBy = e.id;
+                    rt.unitInvocationId = unit.invocationId;
                     rt.db.exec('BEGIN IMMEDIATE');
                     try {
                         // As the producer's principal, admitted above: the handler's checks are real ones,
@@ -2643,6 +2688,7 @@ export class SqliteScopeHost {
                             .run(e.id, imp.moduleId, new Date().toISOString());
                         rt.db.exec('COMMIT');
                         result.delivered += 1;
+                        lines.write({ ...unit, outcome: 'delivered' });
                     }
                     catch (err) {
                         rt.db.exec('ROLLBACK');
@@ -2650,9 +2696,11 @@ export class SqliteScopeHost {
                         // behind it still arrive.
                         deadLetter.run(e.id, imp.moduleId, new Date().toISOString(), String(err));
                         result.deadLettered += 1;
+                        lines.write({ ...unit, outcome: 'dead-lettered', error: err });
                     }
                     finally {
                         rt.causedBy = null;
+                        rt.unitInvocationId = null;
                     }
                 }
                 if (!ran)
@@ -2662,6 +2710,7 @@ export class SqliteScopeHost {
             // rows above absorb it.
             rt.db.prepare(IMPORT_CURSOR_ADVANCE_SQL).run(source.scopeId, source.vertical, batch.next, at);
             result.cursor = batch.next;
+            lines.end();
             // What the handlers emitted reaches this scope's own consumers and executors in the same
             // tail, under the ordinary cascade cap.
             await this.dispatch(rt, null);
@@ -3061,6 +3110,7 @@ export class SqliteScopeHost {
         // ended); the freshness evaluator's are `kind = 'freshness'` — see checkFreshness
         // for what the same two columns mean there.
         const now = Date.parse(nowIso);
+        const lines = asyncLinePass(this.invocationLineSink);
         for (const schedule of mod.schedules) {
             const lastRunAt = gate.lastRuns.get(schedule.operation) ?? null;
             const lastRun = lastRunAt ? Date.parse(lastRunAt) : null;
@@ -3077,19 +3127,39 @@ export class SqliteScopeHost {
             // produces either way carries it, and so does the row below.
             const invocationId = ulid();
             let status = 'ok';
+            // #1901: the run's line, under the call's own id — the one its `ctx.log` lines carry.
+            const startedAt = Date.now();
+            let emitted;
+            let failure;
             try {
                 const stub = await this.getSystemScope(moduleId, tenantId, scopeId);
-                await stub.invoke(schedule.operation, schedule.input, { invocationId });
+                await stub.invoke(schedule.operation, schedule.input, { invocationId, onEmitted: (r) => (emitted = r) });
                 report.fired += 1;
             }
             catch (err) {
                 status = 'failed';
+                failure = { error: err };
                 report.failed += 1;
                 report.errors.push({
                     operation: schedule.operation,
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
+            lines.write({
+                kind: 'schedule',
+                tenantId,
+                scopeId,
+                invocationId,
+                operation: schedule.operation,
+                startedAt,
+                outcome: status,
+                ...failure,
+                // Against the host's clock, which is what decided the run was due.
+                dueAt: lastRun === null ? null : new Date(dueAt).toISOString(),
+                latenessMs: lastRun === null ? null : now - dueAt,
+                ...(emitted ? { emitted } : {}),
+                versionId: this.versionId,
+            });
             // On the scope actor (#1678): the cadence row joined whatever transaction an invoke
             // held open, so its rollback forgot the run and the next pass fired it AGAIN.
             await rt.actor.turn(() => rt.db
@@ -3101,6 +3171,7 @@ export class SqliteScopeHost {
                 .run(schedule.operation, new Date(now).toISOString(), status, invocationId));
             report.runs.push({ operation: schedule.operation, outcome: status === 'ok' ? 'ok' : 'failed' });
         }
+        lines.end();
         return report;
     }
     /** The stub body, shared by the principal, connection, system, impersonation and capability doors. */
@@ -3496,7 +3567,26 @@ export class SqliteScopeHost {
             retrying: 0,
             deadLettered: 0,
         };
+        if (this.executors.size === 0)
+            return report;
+        const lines = asyncLinePass(this.invocationLineSink);
+        try {
+            await this.dispatchExecutorsPass(rt, invocationId, report, lines);
+        }
+        finally {
+            lines.end();
+        }
+        return report;
+    }
+    async dispatchExecutorsPass(rt, invocationId, report, lines) {
         const now = new Date().toISOString();
+        // #2005: a non-primary scope (a fork, a snapshot, a preview of either kind) causes no
+        // outbound effects. Every executor is host code acting with platform authority — a
+        // connector with the tenant's credential, a plain executor with `HostAdmin` — so its
+        // deliveries are journaled terminal with the reason and the handler never runs.
+        // Asked on the first due event, once per pass: most passes have none.
+        let inert;
+        const isInert = () => (inert ??= !this.isPrimaryInDirectory(rt.scopeId));
         for (const [id, executor] of this.executors) {
             const deliveryId = `executor:${id}`;
             // Due = never attempted, or retrying and past its next attempt time.
@@ -3505,13 +3595,26 @@ export class SqliteScopeHost {
                 .prepare(`SELECT o.* FROM _substrat_outbox o
            LEFT JOIN _substrat_deliveries d
              ON d.event_id = o.id AND d.consumer_module = ?
-           WHERE o.type = ?
+           WHERE o.type = ? AND ${emittedHere('o.')}
              AND (d.event_id IS NULL
                   OR (d.next_attempt_at IS NOT NULL AND d.next_attempt_at <= ?))
            ORDER BY o.id`)
                 .all(deliveryId, executor.eventType, now);
             for (const row of rows) {
                 report.attempted += 1;
+                // #1901: this attempt's line. Its number is the one the journal records, which
+                // `recordExecutorDelivery` answers — the Durable Object's RPC does the same.
+                const unit = {
+                    kind: 'consumer',
+                    tenantId: rt.tenantId,
+                    scopeId: rt.scopeId,
+                    invocationId: asyncInvocationId(invocationId),
+                    operation: deliveryId,
+                    eventType: executor.eventType,
+                    eventId: row.id,
+                    startedAt: Date.now(),
+                    versionId: this.versionId,
+                };
                 let event;
                 try {
                     event = domainEventOf(row);
@@ -3523,8 +3626,16 @@ export class SqliteScopeHost {
                     // on the FIRST failure, unlike a handler's: the decode is pure, of text already
                     // in hand, so a retry cannot succeed — and only the decode is caught here, so a
                     // handler's transient failure keeps its backoff below.
-                    this.recordExecutorDelivery(rt, row.id, deliveryId, String(err), UNDECODABLE_RETRY, invocationId);
+                    const { attempts } = this.recordExecutorDelivery(rt, row.id, deliveryId, String(err), TERMINAL_RETRY, invocationId);
                     report.deadLettered += 1;
+                    lines.write({ ...unit, attempt: attempts, outcome: 'dead-lettered' });
+                    continue;
+                }
+                if (isInert()) {
+                    const { attempts } = this.recordExecutorDelivery(rt, row.id, deliveryId, INERT_SCOPE_REASON, TERMINAL_RETRY, invocationId);
+                    report.inert = (report.inert ?? 0) + 1;
+                    // Its own outcome, never `delivered`: no handler ran (#2005).
+                    lines.write({ ...unit, attempt: attempts, outcome: 'inert' });
                     continue;
                 }
                 this.causedBy = event.id;
@@ -3537,26 +3648,27 @@ export class SqliteScopeHost {
                     else {
                         await executor.handler(this.admin, event);
                     }
-                    this.recordExecutorDelivery(rt, row.id, deliveryId, null, executor.retry, invocationId);
+                    const { attempts } = this.recordExecutorDelivery(rt, row.id, deliveryId, null, executor.retry, invocationId);
                     report.delivered += 1;
+                    lines.write({ ...unit, attempt: attempts, outcome: 'delivered' });
                 }
                 catch (err) {
-                    const dead = this.recordExecutorDelivery(rt, row.id, deliveryId, err instanceof Error ? (err.stack ?? err.message) : String(err), executor.retry, invocationId);
+                    const { dead, attempts } = this.recordExecutorDelivery(rt, row.id, deliveryId, err instanceof Error ? (err.stack ?? err.message) : String(err), executor.retry, invocationId);
                     if (dead)
                         report.deadLettered += 1;
                     else
                         report.retrying += 1;
+                    lines.write({ ...unit, attempt: attempts, outcome: dead ? 'dead-lettered' : 'retrying', error: err });
                 }
                 finally {
                     this.causedBy = null;
                 }
             }
         }
-        return report;
     }
     /**
-     * Journal one executor attempt. Returns true when this attempt was the last one
-     * — i.e. the delivery is now dead-lettered.
+     * Journal one executor attempt. Answers which attempt it was (#1901), and `dead` when
+     * it was the last one — i.e. the delivery is now dead-lettered.
      *
      * Written AFTER the handler ran, so a crash mid-effect retries rather than
      * silently marking success. Claiming first would make delivery at-most-once and
@@ -3589,7 +3701,11 @@ export class SqliteScopeHost {
             .run(eventId, deliveryId, new Date().toISOString(), error, attempts, nextAttemptAt, 
         // #1525: the call this attempt ran in, as the caller named it.
         invocationId);
-        return error !== null && exhausted;
+        return { dead: error !== null && exhausted, attempts };
+    }
+    /** Whether the directory says `scopeId` is the real install (`isPrimaryScopeRow`, #2005). */
+    isPrimaryInDirectory(scopeId) {
+        return isPrimaryScopeRow(this.directory.prepare('SELECT kind, forked_from FROM scopes WHERE scope_id = ?').get(scopeId));
     }
     async drainDue(tenantId, scopeId) {
         const rt = this.runtime(tenantId, scopeId);
@@ -3929,13 +4045,23 @@ export class SqliteScopeHost {
      * own emit is delivered in the same tail, so the whole cascade is one call's work.
      */
     invocationId) {
+        // #1901: one line per delivery, capped per drain.
+        const lines = asyncLinePass(this.invocationLineSink);
+        try {
+            await this.dispatchRounds(rt, invocationId, lines);
+        }
+        finally {
+            lines.end();
+        }
+    }
+    async dispatchRounds(rt, invocationId, lines) {
         for (let round = 0; round < 50; round++) {
             let deliveredAny = false;
             for (const mod of this.modules.values()) {
                 for (const consumer of mod.consumers) {
                     const rows = rt.db
                         .prepare(`SELECT * FROM _substrat_outbox o
-               WHERE o.type = ?
+               WHERE o.type = ? AND ${emittedHere('o.')}
                  AND NOT EXISTS (
                    SELECT 1 FROM _substrat_deliveries d
                    WHERE d.event_id = o.id AND d.consumer_module = ?
@@ -3943,6 +4069,20 @@ export class SqliteScopeHost {
                ORDER BY o.id`)
                         .all(consumer.eventType, mod.id);
                     for (const row of rows) {
+                        // #1901: this delivery's line — the call's id when it runs in one, else its own.
+                        const unit = {
+                            kind: 'consumer',
+                            tenantId: rt.tenantId,
+                            scopeId: rt.scopeId,
+                            invocationId: asyncInvocationId(invocationId),
+                            operation: mod.id,
+                            eventType: consumer.eventType,
+                            eventId: row.id,
+                            // A module consumer is tried once: a throw dead-letters it (v0).
+                            attempt: 1,
+                            startedAt: Date.now(),
+                            versionId: this.versionId,
+                        };
                         let event;
                         try {
                             event = domainEventOf(row);
@@ -3959,6 +4099,8 @@ export class SqliteScopeHost {
                      (event_id, consumer_module, delivered_at, error, invocation_id)
                    VALUES (?, ?, ?, ?, ?)`)
                                 .run(row.id, mod.id, new Date().toISOString(), String(err), invocationId);
+                            // Never reached the handler, so nothing threw in it: a warning, not an error.
+                            lines.write({ ...unit, outcome: 'dead-lettered' });
                             continue;
                         }
                         const ctx = this.operationContext(rt, asPrincipal(this.systemPrincipal), {
@@ -3969,6 +4111,8 @@ export class SqliteScopeHost {
                         // consumers never did, which is exactly where a backwards walk stopped.
                         // On the runtime rather than the host — see `ScopeRuntime.causedBy`.
                         rt.causedBy = event.id;
+                        // #1901: the handler's `ctx.log` lines join this delivery's line.
+                        rt.unitInvocationId = unit.invocationId;
                         rt.db.exec('BEGIN IMMEDIATE');
                         try {
                             await consumer.handler(ctx, event);
@@ -3979,6 +4123,7 @@ export class SqliteScopeHost {
                                 .run(event.id, mod.id, new Date().toISOString(), invocationId);
                             rt.db.exec('COMMIT');
                             deliveredAny = true;
+                            lines.write({ ...unit, outcome: 'delivered' });
                         }
                         catch (err) {
                             rt.db.exec('ROLLBACK');
@@ -3989,8 +4134,10 @@ export class SqliteScopeHost {
                      (event_id, consumer_module, delivered_at, error, invocation_id)
                    VALUES (?, ?, ?, ?, ?)`)
                                 .run(event.id, mod.id, new Date().toISOString(), String(err), invocationId);
+                            lines.write({ ...unit, outcome: 'dead-lettered', error: err });
                         }
                         finally {
+                            rt.unitInvocationId = null;
                             // Cleared on BOTH paths. Left set, the id would leak onto every later
                             // emit in this scope — an operation's own event stamped as caused by
                             // whatever happened to be delivered last, which is worse than no cause
@@ -5270,7 +5417,16 @@ export class SqliteScopeHost {
                     COALESCE(s.serving_ref, vv.deployment_ref) AS deployment_ref,
                     CASE WHEN s.serving_ref IS NOT NULL
                          THEN json_extract(sv.manifest_json, '$.outbound')
-                         ELSE json_extract(vv.manifest_json, '$.outbound') END AS outbound_json
+                         ELSE json_extract(vv.manifest_json, '$.outbound') END AS outbound_json,
+                    s.kind, s.forked_from,
+                    -- #2005: the scope's own addresses, bounded as the Cloudflare read bounds them.
+                    (SELECT json_group_array(sh.hostname) FROM (
+                       -- Pinned like the Cloudflare read: a range on the scope, never every
+                       -- active hostname through hostnames_status.
+                       SELECT hostname FROM hostnames INDEXED BY hostnames_scope
+                        WHERE scope_id = s.scope_id AND status = 'active'
+                        ORDER BY hostname LIMIT ${ROUTE_SCOPE_HOSTNAMES_MAX}
+                     ) sh) AS scope_hostnames_json
                FROM hostnames h
                JOIN scopes s ON s.scope_id = h.scope_id AND s.tenant_id = h.tenant_id
                JOIN tenants t ON t.tenant_id = s.tenant_id
@@ -5302,6 +5458,9 @@ export class SqliteScopeHost {
                     surface: r.surface,
                     region: r.region,
                     outboundHosts,
+                    // #2005: the egress worker holds a fork or a preview to no third-party egress.
+                    primary: isPrimaryScopeRow(r),
+                    hostnames: JSON.parse(r.scope_hostnames_json),
                 });
             },
             registerVertical: async (actor, input) => {
@@ -5828,6 +5987,15 @@ export class SqliteScopeHost {
                     .run(servingRef, scopeId);
                 this.recordAdmin(actor, 'setScopeServingRef', { tenantId, scopeId }, { servingRef: scope.serving_ref }, { servingRef, ...(ack.exportBreak ? { acknowledged: ack } : {}) });
             },
+            recordKeptCopyResolution: async (actor, tenantId, scopeId, r) => {
+                const scope = this.directory
+                    .prepare('SELECT tenant_id FROM scopes WHERE scope_id = ?')
+                    .get(scopeId);
+                if (!scope || scope.tenant_id !== tenantId) {
+                    throw substratError('not_found', `unknown scope ${scopeId} in tenant ${tenantId}`);
+                }
+                this.recordAdmin(actor, 'resolveKeptCopy', { tenantId, scopeId }, { script: r.script, keptAt: r.keptAt, revision: r.revisionBefore }, { action: r.action, liveScript: r.liveScript, revision: r.revisionAfter });
+            },
             setScopeExpiresAt: async (actor, tenantId, scopeId, expiresAt) => {
                 const scope = this.directory
                     .prepare('SELECT tenant_id, expires_at FROM scopes WHERE scope_id = ?')
@@ -5846,7 +6014,7 @@ export class SqliteScopeHost {
                 // — which is append-only — holding an event the scope never had. The mark that
                 // follows needs no such care: it stamps only rows that exist and are undrained.
                 const db = this.scopeReadDbFor(tenantId, scopeId);
-                const page = db.prepare(`SELECT * FROM _substrat_outbox WHERE drained_at IS NULL ORDER BY id LIMIT ? OFFSET ?`);
+                const page = db.prepare(`SELECT * FROM _substrat_outbox WHERE drained_at IS NULL AND ${emittedHere()} ORDER BY id LIMIT ? OFFSET ?`);
                 // 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).
@@ -7270,6 +7438,11 @@ export class SqliteScopeHost {
                 const { tenantId, scopeId, ...after } = ownerTransferAudit.parse(entry);
                 this.recordAdmin(actor, 'transferOwner', { tenantId, scopeId }, null, after);
             },
+            /** #2005: one change to a scope's copy marker, written around the vertical's own change. */
+            recordCopyMark: async (actor, entry) => {
+                const { tenantId, scopeId, action, ...after } = copyMarkAudit.parse(entry);
+                this.recordAdmin(actor, action === 'mark' ? 'markScopeCopy' : 'clearScopeCopyMark', { tenantId, scopeId }, null, after);
+            },
             accessLog: async (actor, filter) => {
                 const where = [];
                 const params = [];
@@ -8155,7 +8328,7 @@ export class SqliteScopeHost {
                 tenantId: rt.tenantId,
                 scopeId: rt.scopeId,
                 operation: operation ?? null,
-                invocationId: () => rt.invocationId,
+                invocationId: () => rt.invocationId ?? rt.unitInvocationId,
                 // A consumer runs under the system override, so it logs as `system`.
                 principalKind: overrideActor ? 'system' : subject.kind,
                 // The string-safe redaction: `redactSecrets` parses its serialization back, and a
@@ -8243,7 +8416,7 @@ export class SqliteScopeHost {
                 // as `pageOf`, applied here because the cursor is a COLUMN's value (plus
                 // the tie-break) rather than a field the caller could name.
                 const last = rows.length >= limit ? rows[rows.length - 1] : undefined;
-                const nextCursor = last === undefined ? null : cursorOf(last, q.sortColumn, plan.idColumn);
+                const nextCursor = last === undefined ? null : cursorOf(last, q.sortColumn, plan.idColumn, q.order);
                 const page = { entries: rows, nextCursor };
                 if (!params.total)
                     return page;
@@ -8653,6 +8826,9 @@ export class SqliteScopeHost {
         // executes, the table always already has `kind` in its key, never `invocation_id`.
         this.ensureColumn(db, '_substrat_schedule_state', 'invocation_id', 'invocation_id TEXT');
         this.ensureColumn(db, '_substrat_job_runs', 'subject_id', 'subject_id TEXT');
+        // #2009: the copy classification on a scope DB built before it (NULL reads as a copy; see
+        // `COPY_ORIGIN_DDL`).
+        this.ensureColumn(db, '_substrat_copy_origin', 'is_copy', 'is_copy INTEGER');
         // #1237: `readInvocation`'s lookup — WHERE invocation_id = ? ORDER BY id — over an outbox
         // that is never pruned. No index leads with invocation_id, so without this one SQLite
         // walks the PRIMARY KEY from the oldest event until it reaches the call, and reading a
@@ -8700,6 +8876,7 @@ export class SqliteScopeHost {
             mintEventId,
             causedBy: null,
             invocationId: null,
+            unitInvocationId: null,
         };
         this.scopes.set(key, created);
         this.scopesById.set(scopeId, created);