@substrat-run/kernel 0.139.0 → 0.141.0

package/dist/scope-copy-ledger.d.ts

@@ -0,0 +1,79 @@
+import type { ScopeCopyMoveConfirmation, ScopeScriptCopy } from './scope-host.js';
+/**
+ * The directory's copy ledger (#1722), in the one SQL grammar both adapters run: the pure
+ * adapter's directory and the control-plane Durable Object build the same `scope_script_copies`
+ * table (`lint:spine-ddl` holds them to it), so the statements that lease, confirm and claim
+ * its entries live here rather than being spelled twice.
+ *
+ * A pending entry belongs to the move that recorded it until its lease runs out. Two things
+ * read that lease, and they are what make crash recovery safe against a move that is merely
+ * slow rather than dead:
+ *
+ * - The bind that routes the scope onto the move's destination (`COPY_MOVE_LIVE_PREDICATE`)
+ *   lands only while every entry of the move is pending, unclaimed and inside its lease, and
+ *   settles them in the same write (`COPY_MOVE_CONFIRM_SQL`).
+ * - A sweep claims only an entry whose lease has run out (`COPY_EXPIRED_SQL` then
+ *   `COPY_CLAIM_SQL`), which no bind can confirm any more.
+ *
+ * So exactly one of them acts on a move: the bind before the lease ends, or the sweep after.
+ */
+/** Appended to a conditional bind's `UPDATE scopes … WHERE`. Params: `copyMoveLiveParams`. */
+export declare const COPY_MOVE_LIVE_PREDICATE = "\n  AND EXISTS (SELECT 1 FROM scope_script_copies AS move\n    WHERE move.tenant_id = scopes.tenant_id AND move.scope_id = scopes.scope_id AND move.move_id = ?)\n  AND NOT EXISTS (SELECT 1 FROM scope_script_copies AS move\n    WHERE move.tenant_id = scopes.tenant_id AND move.scope_id = scopes.scope_id AND move.move_id = ?\n      AND (move.state <> 'pending' OR move.lease_owner IS NOT NULL\n        OR move.lease_until IS NULL OR move.lease_until <= ?))";
+export declare const copyMoveLiveParams: (confirm: ScopeCopyMoveConfirmation, now: string) => string[];
+/**
+ * Run in the bind's own transaction once its row update landed: the destination is now the
+ * route, and the source becomes the state the confirmation names, with the marker its export
+ * read. An adopt or rebind names `eligible`, so the sweep wipes the old copy under its fence
+ * (the old copy is no backout; rollback is a snapshot taken first). A carry names `retained`
+ * and promotes the source itself once it has ruled out an overtaken destination. A source on a
+ * deployment that cannot fence a wipe stays `retained`. Params: `copyMoveConfirmParams`.
+ */
+export declare const COPY_MOVE_CONFIRM_SQL = "\n  UPDATE scope_script_copies SET\n    state = CASE role WHEN 'destination' THEN 'done' ELSE ? END,\n    load_stamp = CASE role WHEN 'destination' THEN load_stamp ELSE ? END,\n    revision = CASE role WHEN 'destination' THEN revision ELSE ? END,\n    last_attempt_at = ?\n  WHERE tenant_id = ? AND scope_id = ? AND move_id = ? AND state = 'pending'";
+export declare const copyMoveConfirmParams: (confirm: ScopeCopyMoveConfirmation, tenantId: string, scopeId: string, now: string) => (string | null)[];
+/** Pending entries whose lease ran out before `?` (or that never had one), oldest first, `LIMIT ?`. */
+export declare const COPY_EXPIRED_SQL = "\n  SELECT tenant_id, scope_id, script_ref, move_id FROM scope_script_copies\n  WHERE state = 'pending' AND (lease_until IS NULL OR lease_until <= ?)\n  ORDER BY lease_until, tenant_id, scope_id, script_ref, move_id LIMIT ?";
+/** Claim one expired entry, re-checked in the write. Params: owner, leaseUntil, the key, now. */
+export declare const COPY_CLAIM_SQL = "\n  UPDATE scope_script_copies SET lease_owner = ?, lease_until = ?\n  WHERE tenant_id = ? AND scope_id = ? AND script_ref = ? AND move_id = ?\n    AND state = 'pending' AND (lease_until IS NULL OR lease_until <= ?)";
+/**
+ * The fence a copy move's restore carries into the destination's own store (#1722). The vertical
+ * that holds the destination has no reach to the directory, so the move's lease travels with
+ * the restore instead: the store refuses the load, inside the load's own transaction, once
+ * `notAfter` has passed, and writes nothing.
+ *
+ * `notAfter` sits a margin inside the move's lease (`copyRestoreFence`), and everything that could
+ * make a late restore wrong waits for that lease to end first. A sweep claims an entry only once
+ * its lease has run out. A reap claims the scope, and an erasure finalizes, only while no entry
+ * of any move is pending, so for an unconfirmed move only after that sweep. A restore that is
+ * not refused therefore committed before any of them, and one that would land after any of them
+ * is refused. The margin absorbs clock skew between the directory and the destination, and
+ * `moveId` and `erasureEpoch` name the move and the erasure state it was issued under.
+ */
+export interface CopyRestoreFence {
+    moveId: string;
+    notAfter: string;
+    erasureEpoch: number;
+}
+/** How far inside the lease a restore must commit: five minutes, or a quarter of a short lease. */
+export declare const copyRestoreFenceMarginMs: (leaseMs: number) => number;
+/** The fence for a move whose entries were recorded no earlier than `recordedAt` (epoch ms). */
+export declare const copyRestoreFence: (moveId: string, recordedAt: number, leaseMs: number, erasureEpoch: number) => CopyRestoreFence;
+/** Whether a restore carrying `fence` may no longer land at `now` (epoch ms). */
+export declare const copyRestoreFenceLapsed: (fence: CopyRestoreFence, now: number) => boolean;
+/** The refusal a lapsed fence answers with, the same words on every host. */
+export declare const COPY_RESTORE_FENCE_LAPSED = "the copy move's lease ran out before its restore; nothing was loaded (#1722)";
+/** A ledger row as both adapters read it. */
+export interface ScopeScriptCopyRow {
+    tenant_id: string;
+    scope_id: string;
+    script_ref: string;
+    move_id: string;
+    state: string;
+    load_stamp: string | null;
+    revision: string | null;
+    role: string | null;
+    lease_until: string | null;
+}
+/** The columns `ScopeScriptCopyRow` names, for a read that does not take `SELECT *`. */
+export declare const SCOPE_SCRIPT_COPY_COLUMNS = "tenant_id, scope_id, script_ref, move_id, state, load_stamp, revision, role, lease_until";
+export declare const scopeScriptCopyOf: (r: ScopeScriptCopyRow) => ScopeScriptCopy;
+//# sourceMappingURL=scope-copy-ledger.d.ts.map

package/dist/scope-copy-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-copy-ledger.d.ts","sourceRoot":"","sources":["../src/scope-copy-ledger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElF;;;;;;;;;;;;;;;;;GAiBG;AAEH,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,4cAM0B,CAAC;AAEhE,eAAO,MAAM,kBAAkB,YAAa,yBAAyB,OAAO,MAAM,KAAG,MAAM,EACpD,CAAC;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,kWAM2C,CAAC;AAE9E,eAAO,MAAM,qBAAqB,YACvB,yBAAyB,YAAY,MAAM,WAAW,MAAM,OAAO,MAAM,KACjF,CAAC,MAAM,GAAG,IAAI,CAAC,EAGjB,CAAC;AAEF,uGAAuG;AACvG,eAAO,MAAM,gBAAgB,oOAG4C,CAAC;AAE1E,iGAAiG;AACjG,eAAO,MAAM,cAAc,4NAG6C,CAAC;AAEzE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,mGAAmG;AACnG,eAAO,MAAM,wBAAwB,YAAa,MAAM,KAAG,MAAuD,CAAC;AAEnH,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,WACnB,MAAM,cAAc,MAAM,WAAW,MAAM,gBAAgB,MAAM,KACxE,gBAID,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,UAAW,gBAAgB,OAAO,MAAM,KAAG,OAA2C,CAAC;AAE1H,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,iFAAiF,CAAC;AAExH,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,6FACsD,CAAC;AAE7F,eAAO,MAAM,iBAAiB,MAAO,kBAAkB,KAAG,eAUxD,CAAC"}

package/dist/scope-copy-ledger.js

@@ -0,0 +1,82 @@
+/**
+ * The directory's copy ledger (#1722), in the one SQL grammar both adapters run: the pure
+ * adapter's directory and the control-plane Durable Object build the same `scope_script_copies`
+ * table (`lint:spine-ddl` holds them to it), so the statements that lease, confirm and claim
+ * its entries live here rather than being spelled twice.
+ *
+ * A pending entry belongs to the move that recorded it until its lease runs out. Two things
+ * read that lease, and they are what make crash recovery safe against a move that is merely
+ * slow rather than dead:
+ *
+ * - The bind that routes the scope onto the move's destination (`COPY_MOVE_LIVE_PREDICATE`)
+ *   lands only while every entry of the move is pending, unclaimed and inside its lease, and
+ *   settles them in the same write (`COPY_MOVE_CONFIRM_SQL`).
+ * - A sweep claims only an entry whose lease has run out (`COPY_EXPIRED_SQL` then
+ *   `COPY_CLAIM_SQL`), which no bind can confirm any more.
+ *
+ * So exactly one of them acts on a move: the bind before the lease ends, or the sweep after.
+ */
+/** Appended to a conditional bind's `UPDATE scopes … WHERE`. Params: `copyMoveLiveParams`. */
+export const COPY_MOVE_LIVE_PREDICATE = `
+  AND EXISTS (SELECT 1 FROM scope_script_copies AS move
+    WHERE move.tenant_id = scopes.tenant_id AND move.scope_id = scopes.scope_id AND move.move_id = ?)
+  AND NOT EXISTS (SELECT 1 FROM scope_script_copies AS move
+    WHERE move.tenant_id = scopes.tenant_id AND move.scope_id = scopes.scope_id AND move.move_id = ?
+      AND (move.state <> 'pending' OR move.lease_owner IS NOT NULL
+        OR move.lease_until IS NULL OR move.lease_until <= ?))`;
+export const copyMoveLiveParams = (confirm, now) => [confirm.moveId, confirm.moveId, now];
+/**
+ * Run in the bind's own transaction once its row update landed: the destination is now the
+ * route, and the source becomes the state the confirmation names, with the marker its export
+ * read. An adopt or rebind names `eligible`, so the sweep wipes the old copy under its fence
+ * (the old copy is no backout; rollback is a snapshot taken first). A carry names `retained`
+ * and promotes the source itself once it has ruled out an overtaken destination. A source on a
+ * deployment that cannot fence a wipe stays `retained`. Params: `copyMoveConfirmParams`.
+ */
+export const COPY_MOVE_CONFIRM_SQL = `
+  UPDATE scope_script_copies SET
+    state = CASE role WHEN 'destination' THEN 'done' ELSE ? END,
+    load_stamp = CASE role WHEN 'destination' THEN load_stamp ELSE ? END,
+    revision = CASE role WHEN 'destination' THEN revision ELSE ? END,
+    last_attempt_at = ?
+  WHERE tenant_id = ? AND scope_id = ? AND move_id = ? AND state = 'pending'`;
+export const copyMoveConfirmParams = (confirm, tenantId, scopeId, now) => [
+    confirm.source, confirm.sourceMarker?.loadStamp ?? null, confirm.sourceMarker?.revision ?? null,
+    now, tenantId, scopeId, confirm.moveId,
+];
+/** Pending entries whose lease ran out before `?` (or that never had one), oldest first, `LIMIT ?`. */
+export const COPY_EXPIRED_SQL = `
+  SELECT tenant_id, scope_id, script_ref, move_id FROM scope_script_copies
+  WHERE state = 'pending' AND (lease_until IS NULL OR lease_until <= ?)
+  ORDER BY lease_until, tenant_id, scope_id, script_ref, move_id LIMIT ?`;
+/** Claim one expired entry, re-checked in the write. Params: owner, leaseUntil, the key, now. */
+export const COPY_CLAIM_SQL = `
+  UPDATE scope_script_copies SET lease_owner = ?, lease_until = ?
+  WHERE tenant_id = ? AND scope_id = ? AND script_ref = ? AND move_id = ?
+    AND state = 'pending' AND (lease_until IS NULL OR lease_until <= ?)`;
+/** How far inside the lease a restore must commit: five minutes, or a quarter of a short lease. */
+export const copyRestoreFenceMarginMs = (leaseMs) => Math.min(5 * 60_000, Math.floor(leaseMs / 4));
+/** The fence for a move whose entries were recorded no earlier than `recordedAt` (epoch ms). */
+export const copyRestoreFence = (moveId, recordedAt, leaseMs, erasureEpoch) => ({
+    moveId,
+    notAfter: new Date(recordedAt + leaseMs - copyRestoreFenceMarginMs(leaseMs)).toISOString(),
+    erasureEpoch,
+});
+/** Whether a restore carrying `fence` may no longer land at `now` (epoch ms). */
+export const copyRestoreFenceLapsed = (fence, now) => now > Date.parse(fence.notAfter);
+/** The refusal a lapsed fence answers with, the same words on every host. */
+export const COPY_RESTORE_FENCE_LAPSED = "the copy move's lease ran out before its restore; nothing was loaded (#1722)";
+/** The columns `ScopeScriptCopyRow` names, for a read that does not take `SELECT *`. */
+export const SCOPE_SCRIPT_COPY_COLUMNS = 'tenant_id, scope_id, script_ref, move_id, state, load_stamp, revision, role, lease_until';
+export const scopeScriptCopyOf = (r) => ({
+    tenantId: r.tenant_id,
+    scopeId: r.scope_id,
+    scriptRef: r.script_ref,
+    moveId: r.move_id,
+    state: r.state,
+    loadStamp: r.load_stamp,
+    revision: r.revision,
+    role: r.role === 'source' || r.role === 'destination' ? r.role : null,
+    leaseUntil: r.lease_until,
+});
+//# sourceMappingURL=scope-copy-ledger.js.map

package/dist/scope-copy-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-copy-ledger.js","sourceRoot":"","sources":["../src/scope-copy-ledger.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;+DAMuB,CAAC;AAEhE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAkC,EAAE,GAAW,EAAY,EAAE,CAC9F,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;6EAMwC,CAAC;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,OAAkC,EAAE,QAAgB,EAAE,OAAe,EAAE,GAAW,EAC/D,EAAE,CAAC;IACtB,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,SAAS,IAAI,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,QAAQ,IAAI,IAAI;IAC/F,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM;CACvC,CAAC;AAEF,uGAAuG;AACvG,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;yEAGyC,CAAC;AAE1E,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAG;;;wEAG0C,CAAC;AAsBzE,mGAAmG;AACnG,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;AAEnH,gGAAgG;AAChG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,MAAc,EAAE,UAAkB,EAAE,OAAe,EAAE,YAAoB,EACvD,EAAE,CAAC,CAAC;IACtB,MAAM;IACN,QAAQ,EAAE,IAAI,IAAI,CAAC,UAAU,GAAG,OAAO,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE;IAC1F,YAAY;CACb,CAAC,CAAC;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAuB,EAAE,GAAW,EAAW,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAE1H,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,8EAA8E,CAAC;AAexH,wFAAwF;AACxF,MAAM,CAAC,MAAM,yBAAyB,GACpC,0FAA0F,CAAC;AAE7F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAqB,EAAmB,EAAE,CAAC,CAAC;IAC5E,QAAQ,EAAE,CAAC,CAAC,SAAqB;IACjC,OAAO,EAAE,CAAC,CAAC,QAAmB;IAC9B,SAAS,EAAE,CAAC,CAAC,UAAU;IACvB,MAAM,EAAE,CAAC,CAAC,OAAO;IACjB,KAAK,EAAE,CAAC,CAAC,KAAiC;IAC1C,SAAS,EAAE,CAAC,CAAC,UAAU;IACvB,QAAQ,EAAE,CAAC,CAAC,QAAQ;IACpB,IAAI,EAAE,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;IACrE,UAAU,EAAE,CAAC,CAAC,WAAW;CAC1B,CAAC,CAAC"}