@substrat-run/kernel 0.138.0 → 0.140.0

package/dist/attribution.js.map

@@ -1 +1 @@
-{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAO,EACP,UAAsB,EACtB,UAAkC;IAElC,IAAI,SAAgC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE;QAC3B,GAAG,CAAC,MAAM,EAAE,IAAI;YACd,IAAI,IAAI,KAAK,YAAY;gBAAE,OAAO,UAAU,CAAC;YAC7C,IAAI,IAAI,KAAK,OAAO;gBAAE,OAAO,SAAS,CAAC;YACvC,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3C,CAAC;KACF,CAAC,CAAC;IACH,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAO,EACP,WAA4B,EAC5B,UAAkC;IAElC,IAAI,SAAgC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE;QAC3B,GAAG,CAAC,MAAM,EAAE,IAAI;YACd,IAAI,IAAI,KAAK,YAAY,IAAI,WAAW,CAAC,UAAU,KAAK,SAAS;gBAAE,OAAO,WAAW,CAAC,UAAU,CAAC;YACjG,IAAI,IAAI,KAAK,UAAU,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS;gBAAE,OAAO,WAAW,CAAC,QAAQ,CAAC;YAC3F,IAAI,IAAI,KAAK,OAAO;gBAAE,OAAO,CAAC,SAAS,KAAK,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YACnE,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3C,CAAC;KACF,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAO,EACP,UAAsB,EACtB,UAAkC;IAElC,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC"}

package/dist/audit-outcome.d.ts

@@ -0,0 +1,149 @@
+import type { OpsFailureInput } from './scope-host.js';
+/**
+ * The admin actions written intent-then-outcome, which a settle closes: the two the control plane
+ * writes around a vertical call, (#2089) the schedule and peer kill switches, which each adapter
+ * writes around the scope's move, and (#2114) the replay lever, written the same way around the
+ * watermark's move. A lever row written before #2114 carries only `replayId`, no `operationId`,
+ * so every reader passes it over as it passes over any row without one.
+ */
+export declare const AUDITED_CHANGE_ACTIONS: readonly ["transferOwner", "manageScopeMember", "setPeerBinding", "revokeFromSystem", "restoreToSystem", "revokeFromPeer", "restoreToPeer", "moveImportCursor"];
+export type AuditedChangeAction = (typeof AUDITED_CHANGE_ACTIONS)[number];
+/** The structured line an outcome row that could not be written leaves, keyed so a log search finds every one. */
+export declare const UNRECORDED_OUTCOME_LOG = "audit-outcome-unrecorded";
+/** Where an unwritten outcome is reported: the host's error log (the kernel has none of its own). */
+export type AuditLogError = (message: string, fields: Record<string, unknown>) => void;
+/**
+ * Write one outcome row of an audited change (#2064, #2089 for the kill switches), never
+ * swallowing its failure. Answers null when the row landed. When it did not, the failure is
+ * logged as `UNRECORDED_OUTCOME_LOG` with the flow, the operation id and the phase, and its
+ * message is the answer, for the caller to surface: a `refused`/`failed` caller still answers
+ * with its own error (so a refusal never reads as retryable), and an `applied` caller answers
+ * success with `auditWarningOf`. The intent left without an outcome is closed as `unknown` by
+ * the control plane's scheduled settle either way.
+ */
+export declare function recordAuditOutcome(write: () => unknown, line: {
+    flow: string;
+    operationId: string;
+    phase: string;
+}, logError: AuditLogError): Promise<string | null>;
+/** The `auditWarning` a change that went through answers when its `applied` row could not be written. */
+export declare const auditWarningOf: (what: string, unrecorded: string) => string;
+/** The intent a settle reads by id, inside its transaction. */
+export declare const SETTLE_INTENT_SQL = "SELECT id, action, tenant_id, scope_id, vertical, after FROM _substrat_admin_log WHERE id = ?";
+/**
+ * Both statements below write `+action`, so the action column cannot drive an index choice: an
+ * operation's few rows are reached through `_substrat_admin_log_operation` (the kernel's
+ * admin-log index list), never by walking every row of an action. A planner left to choose takes
+ * `(action, id)`, which reads the whole history of the action.
+ */
+/**
+ * Whether the operation already has an outcome: a non-intent row of the SAME operation, its whole
+ * identity compared column by column. The operation id reaches `_substrat_admin_log_operation`.
+ * The action, tenant and scope are compared with `IS`, so a null tenant or scope matches only
+ * null and never acts as a wildcard, and written `+column` so that the operation id is the only
+ * index the statement can use: left to choose, the planner took `(action, id)` once, and
+ * `(tenant_id, id)` or `(scope_id, id)` would read as much. No
+ * value is serialized to compare, so nothing depends on two encoders agreeing. Never by row
+ * order: the intent, a real outcome and a settle's `unknown` are stamped by different writers
+ * whose ids and clocks need not agree.
+ */
+export declare const SETTLE_OUTCOME_SQL = "SELECT 1 AS present FROM _substrat_admin_log\n  WHERE json_extract(after, '$.operationId') = ?\n    AND json_extract(after, '$.operationId') IS NOT NULL\n    AND +action IS ?\n    AND +tenant_id IS ?\n    AND +scope_id IS ?\n    AND json_extract(after, '$.phase') <> 'intent'\n  LIMIT 1";
+/** `SETTLE_OUTCOME_SQL`'s parameters for one operation, every part of its identity in order. */
+export declare const settleOutcomeParamsOf: (operation: AuditedOperationRef) => [string, string, string | null, string | null];
+/** How many operation ids one batched read binds: well under a Durable Object's 100 parameters. */
+export declare const AUDITED_OPERATIONS_BATCH = 50;
+/**
+ * Every row of the given operations, by the operation-id index. One statement per batch of
+ * `AUDITED_OPERATIONS_BATCH` ids. The caller narrows the rows to the action, tenant and scope it
+ * asked about.
+ */
+export declare function auditedOperationsSql(count: number): string;
+/** One row as `auditedOperationsSql` reads it. */
+export interface AuditedOperationSqlRow {
+    id: string;
+    action: string;
+    tenant_id: string | null;
+    scope_id: string | null;
+    operation_id: string;
+    phase: string | null;
+}
+/** One row of an audited operation, as `HostAdmin.auditedOperations` answers it. */
+export interface AuditedOperationRow {
+    id: string;
+    action: string;
+    tenantId: string | null;
+    scopeId: string | null;
+    operationId: string;
+    phase: string | null;
+}
+/** The operations a reader asks about: an operation is its action, its id and its scope. */
+export interface AuditedOperationRef {
+    action: string;
+    operationId: string;
+    tenantId: string | null;
+    scopeId: string | null;
+}
+/**
+ * Run `auditedOperationsSql` over `refs` in batches through `all`, and keep only the rows of
+ * the exact operations asked about. An operation id from another action or scope is not one.
+ */
+export declare function readAuditedOperations(all: (sql: string, params: string[]) => AuditedOperationSqlRow[], refs: readonly AuditedOperationRef[]): AuditedOperationRow[];
+/**
+ * An audited operation's identity: its action, its operation id AND the tenant and scope it was
+ * made in. The one key every grouping, lookup and resolution uses, built only here. An id alone
+ * is not an operation: the same id in two scopes is two operations, never a conflict.
+ */
+export type OperationKey = string & {
+    readonly __operationKey: unique symbol;
+};
+export declare const operationKeyOf: (r: AuditedOperationRef) => OperationKey;
+/** One row as `SETTLE_INTENT_SQL` reads it. */
+export interface SettleIntentRow {
+    id: string;
+    action: string;
+    tenant_id: string | null;
+    scope_id: string | null;
+    vertical: string | null;
+    after: string | null;
+}
+/** What a settle writes: the admin row's target and payload, and the ops-failure row. */
+export interface UnknownOutcome {
+    action: AuditedChangeAction;
+    operationId: string;
+    /** The operation the intent belongs to, the settle check's whole key. */
+    operation: AuditedOperationRef;
+    target: {
+        tenantId: string | null;
+        scopeId: string | null;
+        vertical: string | null;
+    };
+    after: Record<string, unknown>;
+    failure: Omit<OpsFailureInput, 'actor'>;
+}
+/**
+ * The `unknown` outcome for one intent row: the intent's own fields with `phase: 'unknown'` and
+ * `error` saying why, parsed by the same schema the flow writes its rows with. Throws `not_found`
+ * when the row is absent, or is not the intent of an audited change.
+ */
+export declare function unknownOutcomeOf(row: SettleIntentRow | undefined, intentId: string, error: string): UnknownOutcome;
+/** The phases an audited change's rows carry. */
+export type AuditedPhase = 'intent' | 'applied' | 'refused' | 'failed' | 'unknown';
+/** Where an operation stands, by priority over its rows (see the module header). */
+export interface EffectiveOutcome {
+    /** `conflicting`: more than one real outcome row, which the audit must never hold. */
+    outcome: 'applied' | 'refused' | 'failed' | 'unknown' | 'conflicting';
+    /** The real outcome phases found, in no particular order: one, or several when conflicting. */
+    real: string[];
+}
+/**
+ * Each audited operation's effective outcome among `rows`, keyed by `operationKeyOf`. A real
+ * outcome beats `unknown` regardless of which was written first. Two or more real outcome rows
+ * are `conflicting`. An operation with only an intent has no entry, so it is pending. Row ids
+ * and timestamps decide nothing.
+ */
+export declare function effectiveOutcomes(rows: readonly (AuditedOperationRef & {
+    phase: string | null;
+})[]): Map<OperationKey, EffectiveOutcome>;
+/** Whether a row is an outcome its operation's effective outcome replaced: an `unknown` beaten by a real one. */
+export declare function isSupersededOutcome(phase: string | null, effective: EffectiveOutcome | undefined): boolean;
+//# sourceMappingURL=audit-outcome.d.ts.map

package/dist/audit-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-outcome.d.ts","sourceRoot":"","sources":["../src/audit-outcome.ts"],"names":[],"mappings":"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"}

package/dist/audit-outcome.js

@@ -0,0 +1,233 @@
+/**
+ * Closing an audited change whose outcome was never written (#2064), shared by both adapters.
+ *
+ * The owner hand-over (#1665) and dashboard member management (#1150) audit a change made in the
+ * vertical's own deployment in two rows paired by `operationId`: an `intent`, then `applied`,
+ * `refused` or `failed`. The schedule and peer kill switches (#1666, #1706; #2089) audit the
+ * scope's move the same way, from inside each adapter, and so does the replay lever
+ * (`moveImportCursor`, #2114), whose rows carry its `replayId` as their `operationId`. The two
+ * stores are separate, so an intent can be left with no outcome: its outcome write failed (`recordAuditOutcome` logs it), or the
+ * request died between the two. The control plane's scheduled
+ * pass finds such an intent and asks the host to settle it through
+ * `HostAdmin.settleUnrecordedOutcome`.
+ *
+ * **The settle is one transaction, and it claims the outcome only if none exists.** It reads
+ * the intent by id, checks there is no outcome row for the operation, then writes the `unknown`
+ * row and the ops-failure row that brings it to the staff digest. Two passes that race settle
+ * once. An outcome that lands before the settle runs wins, and the settle writes nothing.
+ * Because the ops-failure row is written in the same unit, an `unknown` row cannot exist without
+ * the digest hearing of it.
+ *
+ * **A real outcome supersedes `unknown`, by priority, not by order.** The log is append-only, so
+ * a real outcome that lands after the settle is still recorded. Every reader resolves an
+ * operation by `effectiveOutcomes`: a real outcome (`applied`, `refused`, `failed`) beats
+ * `unknown` whichever row was written first, since the two writers' ids and clocks need not
+ * agree. Two real outcomes for one operation break the audit's invariant, so they resolve to
+ * `conflicting`, which is reported and never guessed past. The control plane bounds the vertical call well inside the
+ * settle's grace window, so a live request cannot normally be overtaken this way. The rule is
+ * stated for the case where one is.
+ */
+import { AUDIT_ERROR_MAX, auditOperationId, memberChangeAudit, ownerTransferAudit, peerBindingAudit, substratError } from '@substrat-run/contracts';
+import { SWITCH_ACTIONS } from './system-switch-record.js';
+/**
+ * The admin actions written intent-then-outcome, which a settle closes: the two the control plane
+ * writes around a vertical call, (#2089) the schedule and peer kill switches, which each adapter
+ * writes around the scope's move, and (#2114) the replay lever, written the same way around the
+ * watermark's move. A lever row written before #2114 carries only `replayId`, no `operationId`,
+ * so every reader passes it over as it passes over any row without one.
+ */
+export const AUDITED_CHANGE_ACTIONS = [
+    'transferOwner',
+    'manageScopeMember',
+    'setPeerBinding',
+    ...SWITCH_ACTIONS,
+    'moveImportCursor',
+];
+/** The structured line an outcome row that could not be written leaves, keyed so a log search finds every one. */
+export const UNRECORDED_OUTCOME_LOG = 'audit-outcome-unrecorded';
+/**
+ * Write one outcome row of an audited change (#2064, #2089 for the kill switches), never
+ * swallowing its failure. Answers null when the row landed. When it did not, the failure is
+ * logged as `UNRECORDED_OUTCOME_LOG` with the flow, the operation id and the phase, and its
+ * message is the answer, for the caller to surface: a `refused`/`failed` caller still answers
+ * with its own error (so a refusal never reads as retryable), and an `applied` caller answers
+ * success with `auditWarningOf`. The intent left without an outcome is closed as `unknown` by
+ * the control plane's scheduled settle either way.
+ */
+export async function recordAuditOutcome(write, line, logError) {
+    try {
+        await write();
+        return null;
+    }
+    catch (auditError) {
+        const message = auditError instanceof Error ? auditError.message : String(auditError);
+        try {
+            logError(UNRECORDED_OUTCOME_LOG, { ...line, auditError: message });
+        }
+        catch {
+            // Reporting an unwritten row must not replace the operation’s own error or warning.
+        }
+        return message;
+    }
+}
+/** The `auditWarning` a change that went through answers when its `applied` row could not be written. */
+export const auditWarningOf = (what, unrecorded) => `${what} completed, but its outcome could not be written to the admin log: ${unrecorded}`;
+/** The intent a settle reads by id, inside its transaction. */
+export const SETTLE_INTENT_SQL = 'SELECT id, action, tenant_id, scope_id, vertical, after FROM _substrat_admin_log WHERE id = ?';
+/**
+ * Both statements below write `+action`, so the action column cannot drive an index choice: an
+ * operation's few rows are reached through `_substrat_admin_log_operation` (the kernel's
+ * admin-log index list), never by walking every row of an action. A planner left to choose takes
+ * `(action, id)`, which reads the whole history of the action.
+ */
+/**
+ * Whether the operation already has an outcome: a non-intent row of the SAME operation, its whole
+ * identity compared column by column. The operation id reaches `_substrat_admin_log_operation`.
+ * The action, tenant and scope are compared with `IS`, so a null tenant or scope matches only
+ * null and never acts as a wildcard, and written `+column` so that the operation id is the only
+ * index the statement can use: left to choose, the planner took `(action, id)` once, and
+ * `(tenant_id, id)` or `(scope_id, id)` would read as much. No
+ * value is serialized to compare, so nothing depends on two encoders agreeing. Never by row
+ * order: the intent, a real outcome and a settle's `unknown` are stamped by different writers
+ * whose ids and clocks need not agree.
+ */
+export const SETTLE_OUTCOME_SQL = `SELECT 1 AS present FROM _substrat_admin_log
+  WHERE json_extract(after, '$.operationId') = ?
+    AND json_extract(after, '$.operationId') IS NOT NULL
+    AND +action IS ?
+    AND +tenant_id IS ?
+    AND +scope_id IS ?
+    AND json_extract(after, '$.phase') <> 'intent'
+  LIMIT 1`;
+/** `SETTLE_OUTCOME_SQL`'s parameters for one operation, every part of its identity in order. */
+export const settleOutcomeParamsOf = (operation) => [
+    operation.operationId,
+    operation.action,
+    operation.tenantId,
+    operation.scopeId,
+];
+/** How many operation ids one batched read binds: well under a Durable Object's 100 parameters. */
+export const AUDITED_OPERATIONS_BATCH = 50;
+/**
+ * Every row of the given operations, by the operation-id index. One statement per batch of
+ * `AUDITED_OPERATIONS_BATCH` ids. The caller narrows the rows to the action, tenant and scope it
+ * asked about.
+ */
+export function auditedOperationsSql(count) {
+    return `SELECT id, action, tenant_id, scope_id,
+      json_extract(after, '$.operationId') AS operation_id, json_extract(after, '$.phase') AS phase
+    FROM _substrat_admin_log
+    WHERE json_extract(after, '$.operationId') IN (${Array.from({ length: count }, () => '?').join(', ')})
+      AND json_extract(after, '$.operationId') IS NOT NULL
+      AND +action IN (${AUDITED_CHANGE_ACTIONS.map((a) => `'${a}'`).join(', ')})`;
+}
+/**
+ * Run `auditedOperationsSql` over `refs` in batches through `all`, and keep only the rows of
+ * the exact operations asked about. An operation id from another action or scope is not one.
+ */
+export function readAuditedOperations(all, refs) {
+    const wanted = new Set(refs.map(operationKeyOf));
+    const ids = [...new Set(refs.map((r) => r.operationId))];
+    const rows = [];
+    for (let i = 0; i < ids.length; i += AUDITED_OPERATIONS_BATCH) {
+        const batch = ids.slice(i, i + AUDITED_OPERATIONS_BATCH);
+        for (const r of all(auditedOperationsSql(batch.length), batch)) {
+            const row = { id: r.id, action: r.action, tenantId: r.tenant_id, scopeId: r.scope_id, operationId: r.operation_id, phase: r.phase };
+            if (wanted.has(operationKeyOf(row)))
+                rows.push(row);
+        }
+    }
+    return rows;
+}
+export const operationKeyOf = (r) => JSON.stringify([r.action, r.operationId, r.tenantId, r.scopeId]);
+const isAudited = (action) => AUDITED_CHANGE_ACTIONS.includes(action);
+const isSwitch = (action) => SWITCH_ACTIONS.includes(action);
+/** The actions whose rows have no schema of their own, so an `unknown` row is the intent's fields. */
+const copiesIntent = (action) => isSwitch(action) || action === 'moveImportCursor';
+/**
+ * The `unknown` row of a kill switch's operation (#2089), or of the replay lever's (#2114): the
+ * intent's own fields (its subject, position and reason) with `phase: 'unknown'` and the error.
+ * Neither has a row schema of its own: each adapter writes the switch's rows from
+ * `switchAuditSubject` and the lever's from its move, and the history readers count only
+ * `applied` rows, so an `unknown` row moves no position.
+ */
+const intentUnknownOf = (after, error) => ({
+    ...after,
+    phase: 'unknown',
+    error: error.slice(0, AUDIT_ERROR_MAX),
+});
+/**
+ * The `unknown` outcome for one intent row: the intent's own fields with `phase: 'unknown'` and
+ * `error` saying why, parsed by the same schema the flow writes its rows with. Throws `not_found`
+ * when the row is absent, or is not the intent of an audited change.
+ */
+export function unknownOutcomeOf(row, intentId, error) {
+    const after = row?.after ? JSON.parse(row.after) : null;
+    if (!row || !isAudited(row.action) || after?.phase !== 'intent' || !auditOperationId.safeParse(after.operationId).success) {
+        throw substratError('not_found', `no audited-change intent ${intentId} to settle`);
+    }
+    const parsed = copiesIntent(row.action) ? intentUnknownOf(after, error) : auditedUnknownOf(row, after, error);
+    const operationId = after.operationId;
+    return {
+        action: row.action,
+        operationId,
+        operation: { action: row.action, operationId, tenantId: row.tenant_id, scopeId: row.scope_id },
+        target: { tenantId: row.tenant_id, scopeId: row.scope_id, vertical: row.vertical },
+        after: parsed,
+        failure: {
+            operation: `audit.${row.action}`,
+            stage: 'outcome-unknown',
+            tenantId: row.tenant_id,
+            scopeId: row.scope_id,
+            vertical: row.vertical,
+            // The operation id is the row's handle: the digest reads the admin log by it, to drop an
+            // `unknown` that a real outcome has since superseded.
+            reference: operationId,
+            message: `operation ${operationId}: ${error}`,
+        },
+    };
+}
+/** A control-plane flow's `unknown` row, parsed by the same schema the flow writes its rows with. */
+function auditedUnknownOf(row, after, error) {
+    const entry = { ...after, tenantId: row.tenant_id, scopeId: row.scope_id, phase: 'unknown', error };
+    const { tenantId: _t, scopeId: _s, ...parsed } = row.action === 'transferOwner' ? ownerTransferAudit.parse(entry)
+        : row.action === 'manageScopeMember' ? memberChangeAudit.parse(entry)
+            : peerBindingAudit.parse(entry);
+    return parsed;
+}
+const REAL_OUTCOMES = new Set(['applied', 'refused', 'failed']);
+/**
+ * Each audited operation's effective outcome among `rows`, keyed by `operationKeyOf`. A real
+ * outcome beats `unknown` regardless of which was written first. Two or more real outcome rows
+ * are `conflicting`. An operation with only an intent has no entry, so it is pending. Row ids
+ * and timestamps decide nothing.
+ */
+export function effectiveOutcomes(rows) {
+    const seen = new Map();
+    for (const row of rows) {
+        if (!isAudited(row.action) || row.phase === null || row.phase === 'intent')
+            continue;
+        const key = operationKeyOf(row);
+        const entry = seen.get(key) ?? { real: [], unknown: false };
+        if (REAL_OUTCOMES.has(row.phase))
+            entry.real.push(row.phase);
+        else if (row.phase === 'unknown')
+            entry.unknown = true;
+        seen.set(key, entry);
+    }
+    const out = new Map();
+    for (const [key, { real, unknown }] of seen) {
+        if (real.length > 1)
+            out.set(key, { outcome: 'conflicting', real });
+        else if (real.length === 1)
+            out.set(key, { outcome: real[0], real });
+        else if (unknown)
+            out.set(key, { outcome: 'unknown', real });
+    }
+    return out;
+}
+/** Whether a row is an outcome its operation's effective outcome replaced: an `unknown` beaten by a real one. */
+export function isSupersededOutcome(phase, effective) {
+    return phase === 'unknown' && effective !== undefined && effective.real.length > 0;
+}
+//# sourceMappingURL=audit-outcome.js.map

package/dist/audit-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-outcome.js","sourceRoot":"","sources":["../src/audit-outcome.ts"],"names":[],"mappings":"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"}

package/dist/connect-links.d.ts

@@ -0,0 +1,91 @@
+import { type ConnectLink, type ConnectLinkConsume, type ScopeId, type TenantId } from '@substrat-run/contracts';
+import type { RedactionSql } from './subject-redaction.js';
+/**
+ * The platform-held connect link (connections.md §3.5.4), as statements both adapters run
+ * against their directory — the SQLite host over better-sqlite3, the hosted one inside
+ * ControlPlaneDO — so the lifecycle is written once, the way the findings store is.
+ *
+ * A vertical mints one to be MAILED: a bookkeeping bureau's staff send it to a client
+ * company's Fortnox administrator, who opens it days later. A signature alone cannot be
+ * withdrawn and cannot be spent, which is what §3.5.3's in-session URL gets away with by
+ * living minutes; a link living a week cannot. So the signed state names this row, and the
+ * row decides: outstanding and unexpired opens, anything else refuses.
+ *
+ * Every read and write is keyed by (tenant, scope, id). A link of another scope or tenant
+ * is not a forbidden row — it is an absent one, and answers exactly as `unknown` does.
+ *
+ * Expiry is judged against the `now` the caller passes: the pure host's clock, or the
+ * coordinator's wall clock on the hosted one. ISO 8601 UTC text on both sides, so a string
+ * comparison is a chronological one.
+ */
+export declare const CONNECT_LINKS_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_connect_links (\n    id            TEXT PRIMARY KEY,\n    tenant_id     TEXT NOT NULL,\n    scope_id      TEXT NOT NULL,\n    vertical      TEXT NOT NULL,\n    provider      TEXT NOT NULL,\n    status        TEXT NOT NULL,\n    created_by    TEXT NOT NULL,\n    subject_ref   TEXT,\n    return_url    TEXT,\n    created_at    TEXT NOT NULL,\n    expires_at    TEXT NOT NULL,\n    used_at       TEXT,\n    account_ref   TEXT,\n    account_label TEXT\n  );\n  CREATE INDEX IF NOT EXISTS _substrat_connect_links_scope\n    ON _substrat_connect_links (tenant_id, scope_id, created_at);\n";
+export interface ConnectLinkKeyRow {
+    tenantId: string;
+    scopeId: string;
+    id: string;
+}
+/**
+ * The admin-log row a link move hands back, for the caller to write in the SAME unit as the
+ * move: a consume whose audit row failed would otherwise leave the link spent with no
+ * connection and no record, and the retry refused as `used`. Shaped here, once, so both
+ * adapters write the same row. A move that changed nothing hands back nothing.
+ */
+export interface ConnectLinkAudit {
+    action: 'mintConnectLink' | 'revokeConnectLink' | 'consumeConnectLink' | 'restoreConnectLink';
+    target: {
+        tenantId: TenantId;
+        scopeId: ScopeId;
+        vertical: string;
+    };
+    before: unknown;
+    after: unknown;
+}
+export declare function insertConnectLink(sql: RedactionSql, row: {
+    id: string;
+    tenantId: string;
+    scopeId: string;
+    vertical: string;
+    provider: string;
+    createdBy: string;
+    subjectRef: string | null;
+    returnUrl: string | null;
+    createdAt: string;
+    expiresAt: string;
+}, audit: (row: ConnectLinkAudit) => void): ConnectLink;
+export declare function readConnectLink(sql: RedactionSql, key: ConnectLinkKeyRow): ConnectLink | undefined;
+export declare function listConnectLinks(sql: RedactionSql, filter: {
+    tenantId: string;
+    scopeId?: string;
+    ids?: readonly string[];
+    provider?: string;
+    outstandingOnly?: boolean;
+}, now: string): ConnectLink[];
+/**
+ * Withdraw an outstanding link. Idempotent, and only an outstanding row moves: a used link
+ * has already been spent (its connection is what to disconnect), and a revoked one stays
+ * revoked. `undefined` when no such link exists in this scope; `changed` says whether this
+ * call is the one that revoked it, so a no-op is not audited.
+ */
+export declare function revokeConnectLinkRow(sql: RedactionSql, key: ConnectLinkKeyRow, audit: (row: ConnectLinkAudit) => void): {
+    link: ConnectLink;
+    changed: boolean;
+} | undefined;
+/**
+ * Spend a link — the callback's act, BEFORE it stores the credential, so of two racing
+ * callbacks exactly one gets past it. Single-use is decided by the UPDATE's WHERE, not by
+ * the read in front of it: the read only picks which refusal to answer with.
+ */
+export declare function consumeConnectLinkRow(sql: RedactionSql, input: ConnectLinkKeyRow & {
+    provider: string;
+    accountRef?: string;
+    accountLabel?: string;
+}, now: string, audit: (row: ConnectLinkAudit) => void): ConnectLinkConsume;
+/**
+ * The compensating half of consume: the callback spent the link, then failed to store the
+ * credential, so nothing was connected and the link goes back to outstanding — a platform
+ * hiccup costs a retry, not a fresh link mailed to a client. Only a `used` row moves (a
+ * revocation is never undone by this), and only an unexpired one: a link that lapsed while
+ * the store failed stays spent rather than coming back already dead.
+ */
+export declare function restoreConnectLinkRow(sql: RedactionSql, key: ConnectLinkKeyRow, now: string, audit: (row: ConnectLinkAudit) => void): ConnectLink | undefined;
+//# sourceMappingURL=connect-links.d.ts.map

package/dist/connect-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-links.d.ts","sourceRoot":"","sources":["../src/connect-links.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EAEvB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,qnBAmB7B,CAAC;AA0CF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;IAC9F,MAAM,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAWD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE;IACH,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,EACD,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GACrC,WAAW,CA4Bb;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,iBAAiB,GAAG,WAAW,GAAG,SAAS,CAGlG;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,EACrH,GAAG,EAAE,MAAM,GACV,WAAW,EAAE,CAgBf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GACrC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAmBrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3F,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GACrC,kBAAkB,CAuBpB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GACrC,WAAW,GAAG,SAAS,CAiBzB"}