@telorun/sql 0.21.3 → 0.22.0

package/dist/sql-connection-base.js

@@ -54,6 +54,9 @@ export class SqlConnectionBase {
     hasOpenTransaction(ctx) {
         return this.ctx.zonesFor(this, ctx).some((entry) => this.#executors.has(entry));
     }
+    bindsZone(zone) {
+        return this.#executors.has(zone);
+    }
     /**
      * Every statement this connection runs funnels through here — `executeTemplate`
      * and `executeScript` both delegate — so it is the single instrumentation point.
@@ -68,11 +71,16 @@ export class SqlConnectionBase {
      */
     async execute(sql, params = [], zone, ctx) {
         const executor = this.resolveExecutor(zone, ctx);
-        if (!this.ctx.log.enabled(SEVERITY.debug)) {
-            return executor.executeQuery(CompiledQuery.raw(sql, params));
-        }
+        return this.instrument(sql, () => executor.executeQuery(CompiledQuery.raw(sql, params)));
+    }
+    /** The single instrumentation point, shared by every path that runs a
+     *  statement. The disabled branch allocates nothing and takes no clock
+     *  reading — a query is the hottest thing this module does. */
+    async instrument(sql, run) {
+        if (!this.ctx.log.enabled(SEVERITY.debug))
+            return run();
         const startedAt = Date.now();
-        const result = await executor.executeQuery(CompiledQuery.raw(sql, params));
+        const result = await run();
         this.ctx.log.debug("Statement executed", {
             "db.query.text": sql,
             "db.response.returned_rows": result.rows.length,
@@ -85,6 +93,24 @@ export class SqlConnectionBase {
         });
         return result;
     }
+    /**
+     * Run a statement on the CONNECTION, never on an ambient transaction.
+     *
+     * The complement of {@link resolveExecutor}, and it exists because "joins
+     * whatever transaction is open" is the right default and the wrong one for a
+     * particular class of write: a record ABOUT the work rather than part of it.
+     * A durable journal settling a run is the case that forced it — a settlement
+     * discarded by the caller's rollback leaves a run recorded as still executing
+     * while its effects are gone, and a claim that rolls back releases a run
+     * another poller may already hold.
+     *
+     * On the contract rather than left to each caller to reach for `kysely`,
+     * because the escape hatch is the same for everyone and a caller that reaches
+     * past `execute` also loses its instrumentation — this keeps both.
+     */
+    async executeUncommitted(sql, params = []) {
+        return this.instrument(sql, () => this.db.executeQuery(CompiledQuery.raw(sql, params)));
+    }
     async executeTemplate(fragments, values, zone, ctx) {
         let sql = fragments[0] ?? "";
         for (let i = 1; i < fragments.length; i++) {

package/dist/sql-connection.d.ts

@@ -42,6 +42,14 @@ export interface SqlConnection extends ResourceInstance {
     /** Assemble SQL from literal fragments by interleaving dialect-native
      *  placeholders, then bind `values` positionally. */
     executeTemplate<T>(fragments: string[], values: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
+    /**
+     * Run a statement on the CONNECTION, never on an ambient transaction.
+     *
+     * For a write that is a record ABOUT the work rather than part of it, and so
+     * must survive whatever the work was doing — a durable journal settling a run,
+     * releasing a claim. Everything else should use {@link execute} and join.
+     */
+    executeUncommitted<T>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
     /** Run a multi-statement script. */
     executeScript(sql: string): Promise<void>;
     /** Open a database transaction and hand the caller a `bind` that keys the
@@ -51,6 +59,17 @@ export interface SqlConnection extends ResourceInstance {
     /** True when an ambient transaction zone correlated on this connection has an
      *  open executor here — the flat-nesting check `Sql.Transaction` reuses. */
     hasOpenTransaction(ctx?: InvokeContext): boolean;
+    /**
+     * Does THIS connection hold the open executor for THIS zone?
+     *
+     * The named zone rather than whatever is ambient, which is what an attestation
+     * needs: a caller asking whether its own writes land inside a particular
+     * region gets a wrong answer from an ambient check the moment a second
+     * transaction is open somewhere in the stack. `hasOpenTransaction` answers the
+     * dispatch-time question ("is there one to execute on"); this answers the
+     * membership question ("is it that one").
+     */
+    bindsZone(zone: ZoneEntry): boolean;
     /** Rows affected by a write, normalized across drivers. */
     toRowCount(result: QueryResult<unknown>): number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.21.3",
+  "version": "0.22.0",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,12 +43,14 @@
     "@types/node": "^20.0.0",
     "esbuild": "^0.25.12",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.77.0"
+    "vitest": "^2.1.8",
+    "@telorun/sdk": "0.79.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.lib.json"
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run"
   }
 }

package/src/index.ts

@@ -11,8 +11,42 @@ export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";
 // these by PURL fragment, so the whole module is one bundle and its shared
 // state is one module scope.
 export * as SqlCommandController from "./sql-command-controller.js";
-export * as SqlMigrationController from "./sql-migration-controller.js";
-export * as SqlMigrationsController from "./sql-migrations-controller.js";
 export * as SqlQueryController from "./sql-query-controller.js";
 export * as SqlSelectionController from "./sql-selection-controller.js";
 export * as SqlTransactionController from "./sql-transaction-controller.js";
+
+// Declarative schema. The shared half only — the diff, the ledger, the
+// tombstones and the ordering. Every backend implements `SchemaDriver` and owns
+// its own type vocabulary, DDL rendering, introspection and locking, so nothing
+// here is a lowest-common-denominator type layer.
+export type {
+  DeclaredColumn,
+  DeclaredForeignKey,
+  DeclaredIndex,
+  DeclaredTable,
+  SchemaObjectId,
+  SchemaObjectKind,
+} from "./schema/declared-schema.js";
+export { describeObject, objectKey } from "./schema/declared-schema.js";
+export type {
+  ChangeSafety,
+  LiveColumn,
+  LiveForeignKey,
+  LiveIndex,
+  LiveTable,
+  SchemaDriver,
+} from "./schema/schema-driver.js";
+export { ledgerTables, SchemaLedger } from "./schema/schema-ledger.js";
+export type { LedgerTables, TombstoneRecord, VersionRecord } from "./schema/schema-ledger.js";
+export { assessTombstone } from "./schema/reclaim-policy.js";
+export type { Eligibility, ReclaimPolicy } from "./schema/reclaim-policy.js";
+export { snapshotDeclaration, snapshotDigest } from "./schema/declaration-snapshot.js";
+export type { DeclarationSnapshot } from "./schema/declaration-snapshot.js";
+export { planReconciliation } from "./schema/schema-reconciler.js";
+export type { PlannedStatement, PlannedTombstone, SchemaPlan } from "./schema/schema-reconciler.js";
+export { migrationStatements, pendingKeys } from "./schema/migration-runner.js";
+export type { MigrationEntry, MigrationMap } from "./schema/migration-runner.js";
+export { normalizeTable } from "./schema/normalize-table.js";
+export type { RawColumn, RawForeignKey, RawIndex, RawTable } from "./schema/normalize-table.js";
+export { runSchemaPass } from "./schema/schema-run.js";
+export type { PendingReclamation, SchemaRunInput, SchemaRunStatus } from "./schema/schema-run.js";

package/src/schema/declaration-snapshot.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import type { DeclaredTable, SchemaObjectId } from "./declared-schema.js";
+import { objectKey } from "./declared-schema.js";
+
+/**
+ * The declaration, flattened to one entry per schema object.
+ *
+ * Recording the snapshot rather than only its digest is what answers the
+ * question reconciliation cannot answer from live state alone: which objects
+ * THIS schema resource owns. An object in the namespace that has never appeared
+ * in a snapshot was never declared here — a legacy table, another application's,
+ * one predating adoption — and is invisible to both the diff and reclamation.
+ * Inferring ownership from presence would make adopting an existing database a
+ * data-loss event.
+ *
+ * It also supplies a tombstone's last-known definition for free, so nothing has
+ * to reconstruct what a dropped object was after the declaration stopped
+ * describing it.
+ */
+export type DeclarationSnapshot = Record<string, string>;
+
+function stable(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => [k, stable(v)]),
+    );
+  }
+  return value;
+}
+
+function entry(snapshot: DeclarationSnapshot, id: SchemaObjectId, definition: unknown): void {
+  snapshot[objectKey(id)] = JSON.stringify(stable(definition));
+}
+
+export function snapshotDeclaration(tables: readonly DeclaredTable[]): DeclarationSnapshot {
+  const snapshot: DeclarationSnapshot = {};
+  for (const table of tables) {
+    entry(snapshot, { kind: "table", table: table.name }, { name: table.name });
+    for (const column of table.columns) {
+      entry(snapshot, { kind: "column", table: table.name, name: column.name }, column);
+    }
+    for (const index of table.indexes) {
+      entry(snapshot, { kind: "index", table: table.name, name: index.name }, index);
+    }
+    for (const fk of table.foreignKeys) {
+      entry(snapshot, { kind: "foreignKey", table: table.name, name: fk.name }, fk);
+    }
+  }
+  return snapshot;
+}
+
+/** Stable digest of a snapshot — what the ledger compares boots against. */
+export function snapshotDigest(snapshot: DeclarationSnapshot): string {
+  const canonical = JSON.stringify(
+    Object.keys(snapshot)
+      .sort()
+      .map((key) => [key, snapshot[key]]),
+  );
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+export function parseObjectKey(key: string): SchemaObjectId {
+  const [kind, rest] = key.split(":", 2) as [SchemaObjectId["kind"], string];
+  const dot = rest.indexOf(".");
+  if (kind === "table" || dot < 0) return { kind, table: rest };
+  return { kind, table: rest.slice(0, dot), name: rest.slice(dot + 1) };
+}

package/src/schema/declared-schema.ts

@@ -0,0 +1,73 @@
+/**
+ * The normalized declaration a backend's `Table` kind reduces to.
+ *
+ * Backends declare columns in their own vocabulary — `citext`, `jsonb`, SQLite
+ * storage classes — and this model carries the type through as an opaque
+ * `type` plus its structured `params`. Nothing here parses a type; only the
+ * driver understands one. What IS shared is the shape of a table: named
+ * columns, named indexes, named foreign keys, each with the durable identity
+ * reconciliation diffs and tombstones key on.
+ */
+
+export interface DeclaredColumn {
+  /** Durable identity. Tombstones key on it; renaming is expand-contract. */
+  readonly name: string;
+  /** Backend-native type name, never parsed here. */
+  readonly type: string;
+  /** Structured type parameters (`length`, `precision`, …), never spelled into `type`. */
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly nullable: boolean;
+  readonly array: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  /** A typed literal. Mutually exclusive with {@link defaultExpression}. */
+  readonly default?: unknown;
+  /** Raw backend SQL evaluated by the database. */
+  readonly defaultExpression?: string;
+  /** Backend-specific identity/auto-increment mode, passed through to the driver. */
+  readonly identity?: string;
+  /** The column this one supersedes. The pass adds, copies, then tombstones the source. */
+  readonly renamedFrom?: string;
+}
+
+export interface DeclaredIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  /** Backend-specific extras (partial predicate, method), passed through. */
+  readonly options: Readonly<Record<string, unknown>>;
+}
+
+export interface DeclaredForeignKey {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly references: { readonly table: string; readonly columns: readonly string[] };
+  readonly onDelete?: string;
+  readonly onUpdate?: string;
+}
+
+export interface DeclaredTable {
+  /** Physical table name. */
+  readonly name: string;
+  readonly columns: readonly DeclaredColumn[];
+  readonly indexes: readonly DeclaredIndex[];
+  readonly foreignKeys: readonly DeclaredForeignKey[];
+}
+
+/** Every schema object reconciliation tracks, by the identity a tombstone keys on. */
+export type SchemaObjectKind = "table" | "column" | "index" | "foreignKey";
+
+export interface SchemaObjectId {
+  readonly kind: SchemaObjectKind;
+  readonly table: string;
+  /** The column / index / constraint name; absent for a table. */
+  readonly name?: string;
+}
+
+export function objectKey(id: SchemaObjectId): string {
+  return id.name == null ? `${id.kind}:${id.table}` : `${id.kind}:${id.table}.${id.name}`;
+}
+
+export function describeObject(id: SchemaObjectId): string {
+  return id.name == null ? `table ${id.table}` : `${id.kind} ${id.table}.${id.name}`;
+}

package/src/schema/migration-runner.ts

@@ -0,0 +1,69 @@
+import type { SchemaLedger } from "./schema-ledger.js";
+import type { SchemaDriver } from "./schema-driver.js";
+
+/**
+ * A migration is one `statement` or an ordered list of `statements`, keyed by a
+ * durable id. Phase is NOT part of identity: keys are unique across both maps
+ * and the ledger stores the key alone, so moving a migration between
+ * `beforeMigrations:` and `migrations:` keeps its identity and does not re-run
+ * it.
+ */
+export interface MigrationEntry {
+  readonly statement?: string;
+  readonly statements?: readonly string[];
+}
+
+export type MigrationMap = Record<string, MigrationEntry>;
+
+export function migrationStatements(key: string, entry: MigrationEntry): string[] {
+  const statements = entry.statements ?? (entry.statement != null ? [entry.statement] : []);
+  if (statements.length === 0) {
+    throw new Error(
+      `migration '${key}' has no statement(s) — set 'statement' or a non-empty 'statements'`,
+    );
+  }
+  return [...statements];
+}
+
+/** Keys not yet in the ledger, in key order — the order they are applied in. */
+export function pendingKeys(migrations: MigrationMap, applied: ReadonlySet<string>): string[] {
+  return Object.keys(migrations)
+    .filter((key) => !applied.has(key))
+    .sort();
+}
+
+/**
+ * Apply the pending migrations in key order, each with its ledger row in the
+ * SAME atomic group.
+ *
+ * Applying and recording are one operation, not two: a crash between them would
+ * re-run a migration that may not be idempotent. Whether the group is genuinely
+ * atomic is the engine's to say — {@link SchemaDriver.runAtomically} groups it
+ * where DDL is transactional and runs it sequentially where it is not — but the
+ * ledger write is never the thing left outstanding, because it is last in the
+ * group.
+ */
+export async function runMigrations(
+  driver: SchemaDriver,
+  ledger: SchemaLedger,
+  migrations: MigrationMap,
+  applied: ReadonlySet<string>,
+  now: () => Promise<string>,
+): Promise<string[]> {
+  const pending = pendingKeys(migrations, applied);
+  for (const key of pending) {
+    await driver.runAtomically([
+      ...migrationStatements(key, migrations[key]!),
+      ledger.migrationRecordStatement(key, await now()),
+    ]);
+  }
+  return pending;
+}
+
+export function orphanedKeys(
+  applied: ReadonlySet<string>,
+  ...declared: readonly MigrationMap[]
+): string[] {
+  const known = new Set(declared.flatMap((map) => Object.keys(map)));
+  return [...applied].filter((key) => !known.has(key)).sort();
+}

package/src/schema/normalize-table.ts

@@ -0,0 +1,218 @@
+import type {
+  DeclaredColumn,
+  DeclaredForeignKey,
+  DeclaredIndex,
+  DeclaredTable,
+} from "./declared-schema.js";
+
+/**
+ * The manifest shape a backend's `Table` kind declares, reduced to the
+ * normalized model.
+ *
+ * The STRUCTURE is shared — named columns, named indexes, named foreign keys —
+ * while the type vocabulary is not: `type` is carried through opaquely and
+ * every field the shared model does not name becomes a type parameter, so a
+ * backend adds `length`, `precision` or `collation` to its schema and nothing
+ * here changes. Types are structured rather than spelled into a scalar
+ * (`type: varchar` with `length: 64`, never `varchar(64)`), so nothing has to
+ * parse a type back apart.
+ */
+export interface RawColumn {
+  readonly type: string;
+  readonly nullable?: boolean;
+  readonly array?: boolean;
+  readonly primaryKey?: boolean;
+  readonly unique?: boolean;
+  readonly default?: unknown;
+  readonly defaultExpression?: string;
+  readonly identity?: string;
+  readonly renamedFrom?: string;
+  readonly [param: string]: unknown;
+}
+
+export interface RawIndex {
+  readonly columns: readonly string[];
+  readonly unique?: boolean;
+  readonly [option: string]: unknown;
+}
+
+export interface RawForeignKey {
+  readonly columns: readonly string[];
+  readonly references: { readonly table: unknown; readonly columns: readonly string[] };
+  readonly onDelete?: string;
+  readonly onUpdate?: string;
+}
+
+export interface RawTable {
+  readonly table: string;
+  readonly columns?: Record<string, RawColumn>;
+  readonly indexes?: Record<string, RawIndex>;
+  readonly foreignKeys?: Record<string, RawForeignKey>;
+}
+
+const COLUMN_KEYS = new Set([
+  "type",
+  "nullable",
+  "array",
+  "primaryKey",
+  "unique",
+  "default",
+  "defaultExpression",
+  "identity",
+  "renamedFrom",
+]);
+
+const INDEX_KEYS = new Set(["columns", "unique"]);
+
+function params(raw: Record<string, unknown>, known: ReadonlySet<string>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(raw).filter(([key, value]) => !known.has(key) && value !== undefined),
+  );
+}
+
+function normalizeColumn(name: string, raw: RawColumn): DeclaredColumn {
+  if (raw.default !== undefined && raw.defaultExpression !== undefined) {
+    throw new Error(
+      `column '${name}' declares both 'default' and 'defaultExpression' — a typed literal and ` +
+        `a backend SQL expression are separate fields and exactly one may be set`,
+    );
+  }
+
+  // A primary key and an identity column cannot hold NULL, and the engine
+  // enforces that whether or not the declaration says so. Left at the `nullable`
+  // default of true, the column would read back NOT NULL on the next boot, the
+  // pass would see a difference it could "fix", and every boot from then on
+  // would try to DROP NOT NULL on a primary key and fail. So the implication is
+  // applied here, once, where both the DDL and the comparison read it — and a
+  // declaration that states the opposite is refused rather than quietly
+  // overruled.
+  const impliesNotNull = raw.primaryKey === true || raw.identity !== undefined;
+  if (impliesNotNull && raw.nullable === true) {
+    throw new Error(
+      `column '${name}' is declared nullable and ${raw.primaryKey ? "a primary key" : "an identity column"}, ` +
+        `which cannot hold NULL. Remove 'nullable: true'.`,
+    );
+  }
+
+  return {
+    name,
+    type: raw.type,
+    params: params(raw as Record<string, unknown>, COLUMN_KEYS),
+    nullable: impliesNotNull ? false : (raw.nullable ?? true),
+    array: raw.array ?? false,
+    primaryKey: raw.primaryKey ?? false,
+    unique: raw.unique ?? false,
+    default: raw.default,
+    defaultExpression: raw.defaultExpression,
+    identity: raw.identity,
+    renamedFrom: raw.renamedFrom,
+  };
+}
+
+/** A `references.table` is a `!ref` to another table resource, injected as the
+ *  live instance by the time a controller reads it. */
+function referencedTableName(value: unknown, fk: string): string {
+  if (typeof value === "string") return value;
+  const table = (value as { table?: unknown } | null)?.table;
+  if (typeof table === "string") return table;
+  throw new Error(`foreign key '${fk}': 'references.table' does not name a table`);
+}
+
+/**
+ * Structural checks over one declaration, at resource creation — before any
+ * connection is opened, let alone any DDL planned.
+ *
+ * Each of these would otherwise reach the engine as raw SQL and come back as a
+ * driver error naming a statement the author never wrote. They are decidable
+ * from the declaration alone, so they are decided here and reported against the
+ * field that is wrong.
+ */
+function validateTable(table: DeclaredTable): void {
+  const where = `${table.name}`;
+  if (table.columns.length === 0) {
+    throw new Error(`table '${where}' declares no columns — a table needs at least one.`);
+  }
+
+  const names = new Set(table.columns.map((c) => c.name));
+
+  const primaryKeys = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  if (primaryKeys.length > 1) {
+    throw new Error(
+      `table '${where}' marks ${primaryKeys.map((n) => `'${n}'`).join(" and ")} as primaryKey. ` +
+        `A composite primary key is not expressible as a per-column flag — declare one column ` +
+        `as the key, or create the constraint in a 'migrations:' entry.`,
+    );
+  }
+
+  for (const column of table.columns) {
+    if (!column.renamedFrom) continue;
+    if (column.renamedFrom === column.name) {
+      throw new Error(
+        `column '${where}.${column.name}' declares renamedFrom itself, which describes no rename.`,
+      );
+    }
+    if (names.has(column.renamedFrom)) {
+      throw new Error(
+        `column '${where}.${column.name}' renames from '${column.renamedFrom}', which this table ` +
+          `also declares. A rename's source is the column being retired, so declaring both would ` +
+          `copy one live column into another and retire neither.`,
+      );
+    }
+  }
+
+  // An index or foreign key over a column the table does not declare cannot be
+  // created, and the engine's complaint would name a generated statement.
+  for (const index of table.indexes) {
+    for (const column of index.columns) {
+      if (!names.has(column)) {
+        throw new Error(
+          `index '${where}.${index.name}' names column '${column}', which this table does not ` +
+            `declare.`,
+        );
+      }
+    }
+  }
+  for (const fk of table.foreignKeys) {
+    for (const column of fk.columns) {
+      if (!names.has(column)) {
+        throw new Error(
+          `foreign key '${where}.${fk.name}' names column '${column}', which this table does not ` +
+            `declare.`,
+        );
+      }
+    }
+    if (fk.references.columns.length !== fk.columns.length) {
+      throw new Error(
+        `foreign key '${where}.${fk.name}' has ${fk.columns.length} column(s) but references ` +
+          `${fk.references.columns.length} — a foreign key maps its columns one for one.`,
+      );
+    }
+  }
+}
+
+export function normalizeTable(raw: RawTable): DeclaredTable {
+  const columns = Object.entries(raw.columns ?? {}).map(([name, column]) =>
+    normalizeColumn(name, column),
+  );
+  const indexes: DeclaredIndex[] = Object.entries(raw.indexes ?? {}).map(([name, index]) => ({
+    name,
+    columns: [...index.columns],
+    unique: index.unique ?? false,
+    options: params(index as Record<string, unknown>, INDEX_KEYS),
+  }));
+  const foreignKeys: DeclaredForeignKey[] = Object.entries(raw.foreignKeys ?? {}).map(
+    ([name, fk]) => ({
+      name,
+      columns: [...fk.columns],
+      references: {
+        table: referencedTableName(fk.references.table, name),
+        columns: [...fk.references.columns],
+      },
+      onDelete: fk.onDelete,
+      onUpdate: fk.onUpdate,
+    }),
+  );
+  const table: DeclaredTable = { name: raw.table, columns, indexes, foreignKeys };
+  validateTable(table);
+  return table;
+}

package/src/schema/reclaim-policy.ts

@@ -0,0 +1,73 @@
+import { parseDurationMs } from "@telorun/sdk";
+import type { TombstoneRecord, VersionRecord } from "./schema-ledger.js";
+
+/**
+ * When a tombstone may be reclaimed. Eligibility is a CONJUNCTION: N released
+ * versions must have been observed since the object went missing, AND T must
+ * have elapsed. Version is the primary signal — it is what proves older code is
+ * no longer live — and time is the backstop, because N versions can land in an
+ * afternoon.
+ *
+ * Declaring no policy means nothing is ever dropped, so reclamation is opt-in
+ * by declaration rather than by invocation.
+ */
+export interface ReclaimPolicy {
+  readonly afterVersions: number;
+  readonly afterDuration: string;
+}
+
+export interface Eligibility {
+  readonly eligible: boolean;
+  /** Versions observed since the tombstone, and how many are still needed. */
+  readonly versionsObserved: number;
+  readonly versionsRemaining: number;
+  readonly msElapsed: number;
+  readonly msRemaining: number;
+}
+
+/**
+ * A rollback resets progress rather than merely pausing it.
+ *
+ * Going backwards proves older code is live, so a boot at a version that was
+ * already observed at or before the tombstone is not one more release past the
+ * removal — it is evidence the removal is not yet safe. Both counters restart
+ * from that observation: the version count, and the elapsed-time baseline. This
+ * is answerable only because the ledger records the observed *sequence* rather
+ * than a counter.
+ */
+export function assessTombstone(
+  tombstone: TombstoneRecord,
+  history: readonly VersionRecord[],
+  policy: ReclaimPolicy,
+  nowMs: number,
+): Eligibility {
+  const priorVersions = new Set(
+    history
+      .filter((entry) => entry.sequence <= tombstone.missingSinceSequence)
+      .map((entry) => entry.version),
+  );
+  let counted = new Set<string>();
+  let baselineAt = tombstone.missingSinceAt;
+  for (const entry of history) {
+    if (entry.sequence <= tombstone.missingSinceSequence) continue;
+    if (priorVersions.has(entry.version)) {
+      counted = new Set();
+      baselineAt = entry.firstSeenAt;
+      continue;
+    }
+    counted.add(entry.version);
+  }
+
+  const versionsObserved = counted.size;
+  const msElapsed = Math.max(0, nowMs - Date.parse(baselineAt));
+  const requiredMs = parseDurationMs(policy.afterDuration);
+  const versionsRemaining = Math.max(0, policy.afterVersions - versionsObserved);
+  const msRemaining = Math.max(0, requiredMs - msElapsed);
+  return {
+    eligible: versionsRemaining === 0 && msRemaining === 0,
+    versionsObserved,
+    versionsRemaining,
+    msElapsed,
+    msRemaining,
+  };
+}