@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/catalog/reference-counts.js

@@ -0,0 +1,28 @@
+export function totalWorkflowRevisionReferences(counts) {
+  return counts.registeredDefinitions + counts.inFlightStarts + counts.nonTerminalRuns + counts.pinnedSchedules + counts.pendingDispatches + counts.activeExecutionRealms + counts.retainedRecoveryRecords;
+}
+export function incrementNestedRevisionCount(counts, name, revision) {
+  let byRevision = counts.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    counts.set(name, byRevision);
+  }
+  byRevision.set(revision, (byRevision.get(revision) ?? 0) + 1);
+}
+export function decrementNestedRevisionCount(counts, name, revision) {
+  const byRevision = counts.get(name);
+  if (byRevision === void 0)
+    return;
+  const current = byRevision.get(revision);
+  if (current === void 0)
+    return;
+  if (current <= 1) {
+    byRevision.delete(revision);
+    if (byRevision.size === 0)
+      counts.delete(name);
+  } else
+    byRevision.set(revision, current - 1);
+}
+export function readNestedRevisionCount(counts, name, revision) {
+  return counts.get(name)?.get(revision) ?? 0;
+}

package/dist/core/catalog/removal.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The mechanical CAS-delete primitive `WorkflowCatalog.remove()` delegates
+ * to, plus the tombstone primitives that make its own resolution
+ * (restore-or-finalize) atomic too. Split into its own module to protect
+ * `workflow-catalog.ts`'s size against the repository's 500-line
+ * implementation-file ceiling — mirrors how `storage-io.ts`/`codec.ts`
+ * already sit alongside `workflow-catalog.ts` rather than inline in it.
+ *
+ * Fences the delete on BOTH the exact entry bytes read AND the exact active
+ * pointer bytes read, in one `conditionalBatch` — not entry bytes alone.
+ * Between an in-memory "is this the active revision" check and the delete,
+ * a concurrent `activateCandidate`/`activateRegistered` call (this process
+ * or another sharing the same durable store) could make the target revision
+ * active; fencing the active-pointer key too means that race loses the CAS
+ * and surfaces as `'conflict'` (the caller re-decides) instead of silently
+ * deleting a revision that became active a moment before the delete landed.
+ *
+ * Single-shot — no retry loop, matching `activateCandidate`'s own
+ * no-retry-caller-decides precedent, since a removal decision (unlike
+ * `activateRegistered`'s unconditional retry) already depends on reference
+ * counts computed by the caller and should not blindly re-attempt against
+ * possibly-stale counts.
+ *
+ * WFT-17/18 (Codex review, PR #958): a bare delete of the entry key, with
+ * `removeWorkflowRevision`'s own reference re-check and possible restore as
+ * a SEPARATE, later commit, left a crash window between the two commits
+ * where the entry was durably gone but a run still referenced it, with NO
+ * durable record of what was deleted for ANY process — including the one
+ * that crashed — to recover from. {@link removeCatalogEntry} now writes a
+ * `catalog-tombstone:<name>:<revision>` record (the exact deleted entry
+ * bytes) in the SAME `conditionalBatch` as the delete, so "the entry is
+ * gone" and "a durable record of what it was" land atomically together.
+ * {@link finalizeCatalogTombstone} and {@link restoreCatalogEntryFromTombstone}
+ * are the two possible resolutions, each its own single-CAS atomic
+ * operation conditioned on the tombstone's exact bytes — so a concurrent
+ * second attempt at resolving the SAME tombstone (this process retrying, or
+ * `catalog-readiness.ts`'s boot-time sweep racing a live caller) loses its
+ * CAS harmlessly rather than double-processing. Orphan resolution (a
+ * tombstone left behind by a process that crashed between the delete and
+ * its own resolution) is `resolveOrphanedCatalogTombstones` in
+ * `core/engine/catalog-tombstone-recovery.ts` — deliberately OUTSIDE
+ * `core/catalog/**`, not alongside these primitives, because it needs
+ * `core/engine/nonterminal-revision-count.ts`'s durable non-terminal-run
+ * scan and `core/catalog/**` never imports from `core/engine/**` (a
+ * directional boundary `check-import-cycles.ts` enforces); see that
+ * module's doc for why it lives there.
+ *
+ * @module core/catalog/removal
+ */
+import { type Storage } from '../../storage/interface.ts';
+/** Outcome of {@link removeCatalogEntry}. */
+export type WorkflowCatalogRemovalOutcome = Readonly<{
+    outcome: 'removed';
+    tombstoneBytes: Uint8Array;
+}> | Readonly<{
+    outcome: 'not-found';
+}> | Readonly<{
+    outcome: 'active';
+    activeRevision: string;
+}> | Readonly<{
+    outcome: 'conflict';
+}>;
+/**
+ * Durably delete the installed-revision record for `(name, revision)`,
+ * atomically replacing it with a tombstone carrying the deleted bytes (see
+ * this module's doc for why).
+ *
+ * Reads the current `catalog-entry:<name>:<revision>` bytes; `null` is
+ * `'not-found'` (a no-op — the caller may already believe the revision is
+ * gone). Reads the current `catalog-active:<name>` bytes and refuses with
+ * `'active'` when they decode to exactly this revision — a structural
+ * invariant independent of reference counts, since every future or
+ * resuming run resolves the active pointer, not a specific installed
+ * entry. Otherwise deletes the entry key and puts the tombstone key (CAS'd
+ * on the tombstone being absent — a stale leftover from a previous,
+ * unresolved removal of this exact `(name, revision)` is a durable-store
+ * inconsistency this fails closed on rather than silently overwriting) via
+ * ONE `conditionalBatch`, also CAS'd on the exact entry bytes AND the exact
+ * active-pointer bytes read above (present as a no-op `put`-free
+ * precondition when active-pointer bytes are `null` — never activated). A
+ * CAS loss (any of the three keys changed concurrently) surfaces as
+ * `'conflict'`.
+ */
+export declare function removeCatalogEntry(storage: Storage, name: string, revision: string): Promise<WorkflowCatalogRemovalOutcome>;
+/**
+ * Resolve an outstanding tombstone by completing the removal: CAS-delete
+ * the `catalog-tombstone:<name>:<revision>` key, conditioned on its exact
+ * bytes still being `tombstoneBytes`. Returns `false` (a harmless no-op for
+ * the caller, not an error) when the tombstone was already resolved by
+ * someone else — this same process re-driving after a transient failure,
+ * or a concurrent boot-time sweep on another process.
+ */
+export declare function finalizeCatalogTombstone(storage: Storage, name: string, revision: string, tombstoneBytes: Uint8Array): Promise<boolean>;
+/**
+ * Resolve an outstanding tombstone by restoring the entry: ONE
+ * `conditionalBatch` that both re-`put`s the `catalog-entry:<name>:<revision>`
+ * key (byte-identical to what {@link removeCatalogEntry} deleted — the
+ * tombstone bytes ARE the entry bytes) and deletes the tombstone key,
+ * conditioned on the tombstone's exact bytes still being `tombstoneBytes`.
+ * Atomic by construction — there is no intermediate durable state where the
+ * entry is back but the tombstone still claims a removal is in flight, or
+ * vice versa. Returns `false` (harmless no-op) when the tombstone was
+ * already resolved by someone else.
+ */
+export declare function restoreCatalogEntryFromTombstone(storage: Storage, name: string, revision: string, tombstoneBytes: Uint8Array): Promise<boolean>;

package/dist/core/catalog/removal.js

@@ -0,0 +1,30 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import { decodeActivePointer } from "./codec.js";
+export async function removeCatalogEntry(storage, name, revision) {
+  const entryKey = KEYS.catalogEntry(name, revision), entryBytes = await storage.get(entryKey);
+  if (entryBytes === null)
+    return { outcome: "not-found" };
+  const activeKey = KEYS.catalogActive(name), activeBytes = await storage.get(activeKey), activePointer = activeBytes === null ? null : decodeActivePointer(activeBytes);
+  if (activePointer !== null && activePointer.revision === revision)
+    return { outcome: "active", activeRevision: activePointer.revision };
+  const tombstoneKey = KEYS.catalogTombstone(name, revision);
+  return await storageConditionalBatch(storage, [
+    { key: entryKey, expectedValue: entryBytes },
+    { key: activeKey, expectedValue: activeBytes },
+    { key: tombstoneKey, expectedValue: null }
+  ], [
+    { type: "delete", key: entryKey },
+    { type: "put", key: tombstoneKey, value: entryBytes }
+  ]) ? { outcome: "removed", tombstoneBytes: entryBytes } : { outcome: "conflict" };
+}
+export async function finalizeCatalogTombstone(storage, name, revision, tombstoneBytes) {
+  const tombstoneKey = KEYS.catalogTombstone(name, revision);
+  return storageConditionalBatch(storage, [{ key: tombstoneKey, expectedValue: tombstoneBytes }], [{ type: "delete", key: tombstoneKey }]);
+}
+export async function restoreCatalogEntryFromTombstone(storage, name, revision, tombstoneBytes) {
+  const entryKey = KEYS.catalogEntry(name, revision), tombstoneKey = KEYS.catalogTombstone(name, revision);
+  return storageConditionalBatch(storage, [{ key: tombstoneKey, expectedValue: tombstoneBytes }], [
+    { type: "put", key: entryKey, value: tombstoneBytes },
+    { type: "delete", key: tombstoneKey }
+  ]);
+}

package/dist/core/catalog/storage-io.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Durable I/O for the workflow catalog: restoring catalog state at boot and
+ * writing individual installed-revision entries.
+ *
+ * `restoreWorkflowCatalog` fails closed on any corrupt or unparseable
+ * durable record — a corrupted catalog entry or active pointer is data
+ * corruption in Weft's own durable store, not hostile external input, and
+ * every other fail-closed precedent in this codebase (a corrupt lease epoch,
+ * a corrupt ownership-mode marker) treats that the same way. Silently
+ * dropping it could later resurrect a stale or wrong active revision.
+ *
+ * @module core/catalog/storage-io
+ */
+import { type Storage } from '../../storage/interface.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { WorkflowCatalogActivePointer, WorkflowCatalogEntry } from './types.ts';
+/** In-memory catalog state hydrated from durable storage. */
+export type RestoredWorkflowCatalogState = {
+    entries: Map<string, Map<string, WorkflowCatalogEntry>>;
+    active: Map<string, WorkflowCatalogActivePointer>;
+};
+/**
+ * Restore the durable workflow catalog: every installed `(name, revision)`
+ * entry and every name's active pointer. Every entry record is validated via
+ * {@link parseWorkflowRevisionManifest}; every active-pointer record is
+ * validated via {@link decodeActivePointer}. A corrupt or unparseable record
+ * throws rather than being silently skipped. Restoring an empty store
+ * returns empty maps.
+ */
+export declare function restoreWorkflowCatalog(storage: Storage): Promise<RestoredWorkflowCatalogState>;
+/**
+ * Decode and validate one durable catalog-entry record: parse as JSON,
+ * validate as a manifest via {@link parseWorkflowRevisionManifest}, and check
+ * that the decoded `(name, revision)` agrees with the caller-supplied
+ * expectation (normally read from the storage key itself). Fails closed on
+ * any disagreement — shared by {@link restoreWorkflowCatalog}'s per-entry
+ * restore, {@link readCatalogEntry}'s single-key read, and the by-name scan
+ * `WorkflowCatalog.listInstalledRevisions` uses, so the three consumers of
+ * one durable record shape can never validate it three different ways.
+ */
+/**
+ * Decode and validate a raw catalog-entry-record byte string against an
+ * expected `(name, revision)` — exported for {@link import('./removal.ts').restoreCatalogEntryFromTombstone}'s
+ * caller (`WorkflowCatalog.restoreFromTombstone`) and the boot-time orphan
+ * sweep (`orphaned-tombstones.ts`) to re-populate the in-memory cache from
+ * a tombstone's bytes, which are byte-identical to the entry bytes this
+ * function already validates for {@link restoreWorkflowCatalog} and
+ * {@link readCatalogEntry}.
+ */
+export declare function decodeCatalogEntryRecord(key: string, bytes: Uint8Array, expectedName: string, expectedRevision: string): Promise<{
+    manifest: WorkflowRevisionManifest;
+    installedAt: number;
+}>;
+/**
+ * Read one durable installed-revision record for `(name, revision)`, or
+ * `null` when absent. Fails closed on corruption, exactly matching
+ * {@link restoreWorkflowCatalog}'s per-entry validation — used by
+ * `WorkflowCatalog.install()` to read through the local in-memory cache to
+ * durable storage, which may already hold this `(name, revision)` key
+ * courtesy of a different `WorkflowCatalog` instance/process.
+ */
+export declare function readCatalogEntry(storage: Storage, name: string, revision: string): Promise<{
+    manifest: WorkflowRevisionManifest;
+    installedAt: number;
+} | null>;
+/**
+ * Durably scan every installed revision of `name` — the
+ * `catalog-entry:<name>:` prefix `WORKFLOW_CATALOG_KEYS.catalogEntryPrefix`
+ * builds. Each record is validated exactly like
+ * {@link restoreWorkflowCatalog}'s per-entry restore (via
+ * {@link decodeCatalogEntryRecord}, shared rather than duplicated); a
+ * corrupt or unparseable entry fails closed rather than being silently
+ * skipped. Returns entries in no particular order — callers that need a
+ * deterministic order (`WorkflowCatalog.listInstalledRevisions`) sort the
+ * result themselves.
+ */
+export declare function scanCatalogEntriesForName(storage: Storage, name: string): Promise<Array<{
+    manifest: WorkflowRevisionManifest;
+    installedAt: number;
+}>>;
+/** Read one name's durable active pointer, or `null` when absent. */
+export declare function readActivePointer(storage: Storage, name: string): Promise<WorkflowCatalogActivePointer | null>;
+/**
+ * Durably write one installed-revision entry, CAS-guarded on the key being
+ * absent (`expectedValue: null`). Returns `true` when this write won the
+ * race, `false` when another writer had already durably installed this
+ * exact `(name, revision)` key first — `WorkflowCatalog.install()` re-reads
+ * via {@link readCatalogEntry} on `false` to decide whether that concurrent
+ * write was byte-identical (idempotent) or a genuine conflict.
+ *
+ * CAS-protected rather than a plain `put`: "content-addressed by
+ * `(name, revision)`, so racing writers always agree" only holds when
+ * `revision` is content-derived. `buildWorkflowRevisionManifest`'s public
+ * `options.revision` escape hatch lets a caller supply a non-content-derived
+ * revision (e.g. a deploy tag), so two different `WorkflowCatalog`
+ * instances/processes — each with their own, independently-seeded
+ * in-memory cache — could otherwise race a differing-content write to the
+ * same key past each other's in-memory-only conflict check with a plain
+ * `put` (last write wins, silently).
+ */
+export declare function writeCatalogEntry(storage: Storage, manifest: WorkflowRevisionManifest, installedAt: number): Promise<boolean>;

package/dist/core/catalog/storage-io.js

@@ -0,0 +1,106 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import { tryDecodeStorageKeyComponent } from "../../storage/key-encoding.js";
+import { parseWorkflowRevisionManifest } from "../contract/manifest-parse.js";
+import { decodeActivePointer } from "./codec.js";
+function splitCatalogEntryKey(key) {
+  const parts = key.split(":");
+  if (parts.length !== 3)
+    return null;
+  const name = tryDecodeStorageKeyComponent(parts[1] ?? ""), revision = tryDecodeStorageKeyComponent(parts[2] ?? "");
+  if (name === null || revision === null)
+    return null;
+  return { name, revision };
+}
+function splitCatalogActiveKey(key) {
+  const parts = key.split(":");
+  if (parts.length !== 2)
+    return null;
+  return tryDecodeStorageKeyComponent(parts[1] ?? "");
+}
+function parseCatalogEntryRecord(bytes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    return null;
+  const record = parsed;
+  if (typeof record.installedAt !== "number")
+    return null;
+  return { manifest: record.manifest, installedAt: record.installedAt };
+}
+function failClosed(kind, key, reason) {
+  throw Error(`The store's ${kind} ("${key}") exists but ${reason}. Treating it as absent would risk resurrecting a stale or wrong active workflow revision, so the workflow catalog fails closed instead. Resolve by operator repair: inspect the stored bytes and, only if certain no other engine relies on them, delete the key so it can be re-established.`);
+}
+export async function restoreWorkflowCatalog(storage) {
+  const entries = new Map, active = new Map;
+  for await (const [key, bytes] of storage.scan("catalog-entry:"))
+    await restoreOneCatalogEntry(entries, key, bytes);
+  for await (const [key, bytes] of storage.scan("catalog-active:"))
+    restoreOneActivePointer(active, key, bytes);
+  return { entries, active };
+}
+export async function decodeCatalogEntryRecord(key, bytes, expectedName, expectedRevision) {
+  const parsedRecord = parseCatalogEntryRecord(bytes);
+  if (parsedRecord === null)
+    failClosed("workflow catalog entry", key, "could not be parsed as JSON");
+  const parsed = await parseWorkflowRevisionManifest(parsedRecord.manifest);
+  if (!parsed.ok)
+    failClosed("workflow catalog entry", key, "does not decode as a valid installed-revision record");
+  const manifest = parsed.manifest;
+  if (manifest.name !== expectedName || manifest.revision !== expectedRevision)
+    failClosed("workflow catalog entry", key, "contains a manifest whose (name, revision) disagrees with its storage key");
+  return { manifest, installedAt: parsedRecord.installedAt };
+}
+async function restoreOneCatalogEntry(entries, key, bytes) {
+  const split = splitCatalogEntryKey(key);
+  if (split === null)
+    failClosed("workflow catalog entry key", key, "does not match the expected catalog-entry:<name>:<revision> shape");
+  const { manifest, installedAt } = await decodeCatalogEntryRecord(key, bytes, split.name, split.revision);
+  let byName = entries.get(split.name);
+  if (byName === void 0) {
+    byName = new Map;
+    entries.set(split.name, byName);
+  }
+  byName.set(split.revision, { manifest, installedAt });
+}
+function restoreOneActivePointer(active, key, bytes) {
+  const name = splitCatalogActiveKey(key);
+  if (name === null)
+    failClosed("workflow catalog active pointer key", key, "does not match the expected catalog-active:<name> shape");
+  const pointer = decodeActivePointer(bytes);
+  if (pointer === null)
+    failClosed("workflow catalog active pointer", key, "does not decode as a valid { revision, generation, activatedAt } record");
+  active.set(name, pointer);
+}
+export async function readCatalogEntry(storage, name, revision) {
+  const key = KEYS.catalogEntry(name, revision), bytes = await storage.get(key);
+  if (bytes === null)
+    return null;
+  return decodeCatalogEntryRecord(key, bytes, name, revision);
+}
+export async function scanCatalogEntriesForName(storage, name) {
+  const results = [];
+  for await (const [key, bytes] of storage.scan(KEYS.catalogEntryPrefix(name))) {
+    const split = splitCatalogEntryKey(key);
+    if (split === null)
+      failClosed("workflow catalog entry key", key, "does not match the expected catalog-entry:<name>:<revision> shape");
+    results.push(await decodeCatalogEntryRecord(key, bytes, split.name, split.revision));
+  }
+  return results;
+}
+export async function readActivePointer(storage, name) {
+  const bytes = await storage.get(KEYS.catalogActive(name));
+  if (bytes === null)
+    return null;
+  const pointer = decodeActivePointer(bytes);
+  if (pointer === null)
+    failClosed("workflow catalog active pointer", KEYS.catalogActive(name), "does not decode as a valid { revision, generation, activatedAt } record");
+  return pointer;
+}
+export async function writeCatalogEntry(storage, manifest, installedAt) {
+  const bytes = new TextEncoder().encode(JSON.stringify({ manifest, installedAt })), key = KEYS.catalogEntry(manifest.name, manifest.revision);
+  return storageConditionalBatch(storage, [{ key, expectedValue: null }], [{ type: "put", key, value: bytes }]);
+}

package/dist/core/catalog/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * In-memory and wire types for the durable workflow catalog (WFT-9/WFT-10).
+ *
+ * `WorkflowCatalog` keys entries with nested `Map<string, Map<string, ...>>`
+ * structures — never delimiter-joined strings — so a workflow `name` or
+ * `revision` equal to `'__proto__'`, `'toString'`, or containing a colon is
+ * always safe to store and look up.
+ *
+ * @module core/catalog/types
+ */
+import type { WorkflowCompatibilityVerdict } from '../contract/compatibility.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { RegisteredWorkflowDefinition } from '../types/workflow-registry.ts';
+/**
+ * One installed `(name, revision)` catalog entry. `definition` is populated
+ * only when this process itself installed the entry (via
+ * `engine.register()`'s drain path) — an entry hydrated from durable storage
+ * at boot, for a revision this process has not (yet) registered, carries no
+ * live `definition` because a `RegisteredWorkflowDefinition` cannot be
+ * persisted (it holds function references). Consumers that only need
+ * identity (`resolveActive`, registry-snapshot's `activeRevisions`) never
+ * touch `definition`.
+ */
+export type WorkflowCatalogEntry = Readonly<{
+    manifest: WorkflowRevisionManifest;
+    definition?: RegisteredWorkflowDefinition;
+    installedAt: number;
+}>;
+/**
+ * The durable `{ revision, generation, activatedAt }` pointer for one
+ * workflow name — what `engine.workflows.getActive()` returns.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import type { WorkflowCatalogActivePointer } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const pointer: WorkflowCatalogActivePointer | null = await engine.workflows.getActive('checkout');
+ * console.log(pointer?.generation ?? null);
+ * ```
+ */
+export type WorkflowCatalogActivePointer = Readonly<{
+    revision: string;
+    generation: number;
+    activatedAt: number;
+}>;
+/**
+ * Public-facing view of one installed `(name, revision)` catalog entry —
+ * {@link WorkflowCatalogEntry} minus `definition`, which can carry a live
+ * function reference and must never reach a public return value.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import type { WorkflowRevisionRecord } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const record: WorkflowRevisionRecord | null = await engine.workflows.getRevision(
+ *   'checkout',
+ *   'some-revision',
+ * );
+ * console.log(record?.manifest.revision ?? null);
+ * ```
+ */
+export type WorkflowRevisionRecord = Readonly<{
+    manifest: WorkflowRevisionManifest;
+    installedAt: number;
+}>;
+/**
+ * Result of {@link import('./workflow-catalog.ts').WorkflowCatalog.activateCandidate}.
+ * A candidate either applies (bumping the durable generation) or is refused
+ * with a specific, machine-readable reason — never silently ignored.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import type { WorkflowCatalogActivationResult } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const active = await engine.workflows.getActive('checkout');
+ * const result: WorkflowCatalogActivationResult = await engine.workflows.activate(
+ *   'checkout',
+ *   active?.revision ?? '',
+ *   active === null ? {} : { expectedGeneration: active.generation },
+ * );
+ * console.log(result.applied);
+ * ```
+ */
+export type WorkflowCatalogActivationResult = Readonly<{
+    applied: true;
+    pointer: WorkflowCatalogActivePointer;
+}> | Readonly<{
+    applied: false;
+    reason: 'incompatible';
+    verdict: WorkflowCompatibilityVerdict;
+}> | Readonly<{
+    applied: false;
+    reason: 'stale-generation';
+    currentGeneration: number;
+}> | Readonly<{
+    applied: false;
+    reason: 'conflict';
+}> | Readonly<{
+    applied: false;
+    reason: 'expected-generation-required';
+    currentGeneration: number;
+}>;

package/dist/core/catalog/workflow-catalog.d.ts

@@ -0,0 +1,165 @@
+/**
+ * `WorkflowCatalog` — the immutable-entry, durable workflow catalog
+ * (WFT-9/WFT-10).
+ *
+ * In-memory state is `Map<string, Map<string, WorkflowCatalogEntry>>` for
+ * installed entries and `Map<string, WorkflowCatalogActivePointer>` for each
+ * name's active pointer — nested maps, never delimiter-joined keys, so a
+ * workflow `name` or `revision` equal to `'__proto__'`/`'toString'` or
+ * containing a colon is always handled correctly.
+ *
+ * Two activation entry points exist, matching WFT-9/WFT-10's distinct
+ * producers:
+ *
+ * - {@link WorkflowCatalog.activateRegistered} — unconditional, used
+ *   exclusively by `engine.register()`'s drain path
+ *   (`core/engine/catalog-readiness.ts`). Never consults
+ *   `checkWorkflowCompatibility`; always wins via a bounded 5-attempt CAS
+ *   retry loop. Registering a different version of an already-registered
+ *   workflow must never hard-fail construction or registration (the
+ *   `version-mismatch-recovery.test.ts` precedent), which is why this path
+ *   is unconditional. "Unconditional" is about bypassing
+ *   `checkWorkflowCompatibility`, not immunity to failure in general: under
+ *   sustained contention the bounded 5-attempt CAS retry can still exhaust
+ *   and throw {@link WorkflowCatalogActivationConflictError}, which
+ *   propagates out of `ensureWorkflowCatalogReady` and fails
+ *   `Engine.create()` itself (safely — `Engine.create()`'s `try`/`catch`
+ *   disposes the half-booted engine before rethrowing).
+ * - {@link WorkflowCatalog.activateCandidate} — the guarded primitive:
+ *   `checkWorkflowCompatibility`-gated, single-shot CAS (no retry — the
+ *   caller decides whether to re-read and retry), refuses on incompatibility
+ *   or a stale expected generation. As of WFT-11, reachable by external
+ *   callers via `engine.workflows.activate()` — the first production
+ *   caller. Because a multi-writer caller can activate a revision this
+ *   process's `#entries` cache never observed, the compatibility check
+ *   reads through to durable storage rather than trusting the cache.
+ *   Reused as-is by later dynamic-loading work (WFT-13+).
+ *
+ * @module core/catalog/workflow-catalog
+ */
+import { type Storage } from '../../storage/interface.ts';
+import { type WorkflowCompatibilityPolicy } from '../contract/compatibility.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { RegisteredWorkflowDefinition } from '../types/workflow-registry.ts';
+import { type WorkflowCatalogRemovalOutcome } from './removal.ts';
+import { type RestoredWorkflowCatalogState } from './storage-io.ts';
+import type { WorkflowCatalogActivationResult, WorkflowCatalogActivePointer, WorkflowCatalogEntry, WorkflowRevisionRecord } from './types.ts';
+/** Options accepted by {@link WorkflowCatalog.activateCandidate}. */
+export type ActivateCandidateOptions = {
+    /** The generation this caller last observed; refused with `stale-generation` if it disagrees with the durable pointer. */
+    expectedGeneration?: number;
+    /** Compatibility policy; defaults to {@link DEFAULT_WORKFLOW_COMPATIBILITY_POLICY}. */
+    policy?: WorkflowCompatibilityPolicy;
+};
+export declare class WorkflowCatalog {
+    #private;
+    constructor(storage: Storage, seed?: RestoredWorkflowCatalogState);
+    /** Look up one installed `(name, revision)` entry, or `undefined` when not installed. */
+    getEntry(name: string, revision: string): WorkflowCatalogEntry | undefined;
+    /** Every installed revision of `name`, in no particular order. */
+    listRevisions(name: string): readonly WorkflowCatalogEntry[];
+    /** The current active pointer for `name`, or `undefined` when never activated. */
+    resolveActive(name: string): WorkflowCatalogActivePointer | undefined;
+    /**
+     * Resolve one installed `(name, revision)` entry as a public
+     * {@link WorkflowRevisionRecord} — cache hit first, else a durable
+     * read-through via {@link readCatalogEntry} (adopted into the local cache
+     * on hit, exactly like `install()`'s own read-through), else `undefined`
+     * when truly absent. No TOCTOU gap against a concurrent `install()` on
+     * this same instance: JS is single-threaded and neither this method nor
+     * `install()`'s fast (already-cached) path yields between the cache read
+     * and its use.
+     */
+    resolveEntry(name: string, revision: string): Promise<WorkflowRevisionRecord | undefined>;
+    /**
+     * Every durably installed revision of `name`, sorted by {@link compareCodepoint}
+     * on `revision` for a deterministic order — never `localeCompare`, per
+     * this codebase's determinism rule. Durable scan via
+     * {@link scanCatalogEntriesForName}, validated the same fail-closed way
+     * {@link restoreWorkflowCatalog} validates every entry it restores.
+     * Returns an empty array for an unknown name rather than throwing.
+     */
+    listInstalledRevisions(name: string): Promise<readonly WorkflowRevisionRecord[]>;
+    /**
+     * Whether `(name, revision)` is already durably installed — checked
+     * against this process's in-memory cache first, then, on a cache miss,
+     * durable storage itself (a different process may have installed it).
+     * Used by `catalog-events.ts`'s installed/activated/draining dispatch
+     * helper to decide whether an activation call is installing genuinely
+     * new content, since `install()`'s own cache-hit branch does not
+     * distinguish "already known to this process" from "just installed a
+     * moment ago by this same call."
+     */
+    hasInstalled(name: string, revision: string): Promise<boolean>;
+    /**
+     * Durably resolve `name`'s active pointer — always reads through to
+     * durable storage rather than trusting the in-memory `#active` cache.
+     * Deliberately NOT cache-first like {@link hasInstalled}: `hasInstalled`'s
+     * cache-hit short-circuit can only go stale in the SAFE direction (a
+     * different process's `remove()` durably deleting an entry this
+     * process's `#entries` still holds still lets `catalog.remove()`'s own
+     * durable re-read refuse with `'not-found'` rather than double-deleting),
+     * whereas a name's active pointer has no such one-directional guarantee —
+     * a second engine/process can durably move it (e.g. via
+     * `activateCandidate`, or a second engine holding the ADR&nbsp;0002
+     * workflow-lease) to a revision this process never installed at all, so a
+     * stale cache HIT here can misreport a durably-active revision as
+     * inactive. Used by removal and diagnostics
+     * (`core/engine/catalog-removal.ts`) so a durably-active revision is
+     * never misreported as inactive/removable; `resolveActive` stays the
+     * cheap, synchronous, best-effort accessor for in-process callers (e.g.
+     * `reserveInFlightStart`) that only care about this process's own view.
+     */
+    resolveActiveDurable(name: string): Promise<WorkflowCatalogActivePointer | undefined>;
+    /**
+     * Durably remove the installed `(name, revision)` entry — delegates the
+     * CAS mechanics to {@link removeCatalogEntry}. On success, evicts the
+     * entry from this process's in-memory `#entries` cache too, so a
+     * subsequent `getEntry`/`listRevisions` call in this same process never
+     * observes a removed revision. Refuses (`'active'`) when `revision` is
+     * currently the active pointer for `name` — a structural invariant this
+     * method itself enforces, independent of any reference-count decision a
+     * caller layers on top (see `core/engine/catalog-removal.ts`).
+     */
+    remove(name: string, revision: string): Promise<WorkflowCatalogRemovalOutcome>;
+    /**
+     * Install `manifest` (paired with `definition`, when this process holds
+     * one). Idempotent on a byte-identical reinstall for the same
+     * `(name, revision)` key; throws {@link WorkflowCatalogConflictError} when
+     * an existing entry for that key has different manifest content —
+     * checked against BOTH this process's in-memory cache and, on a cache
+     * miss, durable storage itself (a different `WorkflowCatalog`
+     * instance/process may already have installed this exact key). The
+     * durable write is CAS-guarded ({@link writeCatalogEntry}) rather than a
+     * plain `put`, so two processes racing to install genuinely different
+     * content under the same key — possible whenever `revision` is an
+     * explicit, non-content-derived caller value rather than the default
+     * content hash — cannot silently last-write-win each other; the loser
+     * re-reads and resolves through the same idempotent/conflict check.
+     *
+     * Defensively re-validates `name` against the wire-safe name grammar even
+     * though `engine.register()`'s existing `validateWorkflowOrActivityName`
+     * already guarantees this for the only current producer — `install()` is
+     * deliberately safe for a future producer that is not `engine.register()`.
+     */
+    install(manifest: WorkflowRevisionManifest, definition?: RegisteredWorkflowDefinition): Promise<WorkflowCatalogEntry>;
+    /**
+     * Unconditionally activate `manifest` for `name`, installing it first if
+     * needed. Used exclusively by `engine.register()`'s drain path — never
+     * consults `checkWorkflowCompatibility`. Reactivating the currently active
+     * revision is a no-op (generation unchanged); activating a different
+     * revision bumps the generation by exactly 1. Retries the CAS write up to
+     * {@link MAX_ACTIVATE_REGISTERED_ATTEMPTS} times under contention, throwing
+     * {@link WorkflowCatalogActivationConflictError} on exhaustion.
+     */
+    activateRegistered(name: string, manifest: WorkflowRevisionManifest, definition: RegisteredWorkflowDefinition): Promise<WorkflowCatalogActivePointer>;
+    /**
+     * The guarded activation primitive: reads the currently-active manifest
+     * for `name` (absence is treated as automatically compatible — first
+     * activation), checks `checkWorkflowCompatibility`, and refuses rather
+     * than applies when incompatible or when `expectedGeneration` disagrees
+     * with the durably-read generation. Single-shot CAS write — no retry; the
+     * caller decides whether to re-read and retry.
+     */
+    activateCandidate(name: string, candidateManifest: WorkflowRevisionManifest, options?: ActivateCandidateOptions): Promise<WorkflowCatalogActivationResult>;
+}