@lostgradient/weft 0.23.0 → 0.24.0

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

@@ -0,0 +1,78 @@
+/**
+ * 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>;
+/**
+ * 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 };
+}
+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>;
+}

package/dist/core/catalog/workflow-catalog.js

@@ -0,0 +1,198 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { compareCodepoint } from "../compare-codepoint.js";
+import {
+  checkWorkflowCompatibility,
+  DEFAULT_WORKFLOW_COMPATIBILITY_POLICY
+} from "../contract/compatibility.js";
+import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+import { encodeActivePointer, manifestsAreByteIdentical } from "./codec.js";
+import {
+  WorkflowCatalogActivationConflictError,
+  WorkflowCatalogActiveEntryMissingError,
+  WorkflowCatalogConflictError
+} from "./errors.js";
+import { removeCatalogEntry } from "./removal.js";
+import {
+  readActivePointer,
+  readCatalogEntry,
+  scanCatalogEntriesForName,
+  writeCatalogEntry
+} from "./storage-io.js";
+const MAX_ACTIVATE_REGISTERED_ATTEMPTS = 5;
+
+export class WorkflowCatalog {
+  #storage;
+  #entries;
+  #active;
+  constructor(storage, seed) {
+    this.#storage = storage;
+    this.#entries = seed?.entries ?? new Map;
+    this.#active = seed?.active ?? new Map;
+  }
+  getEntry(name, revision) {
+    return this.#entries.get(name)?.get(revision);
+  }
+  listRevisions(name) {
+    const byName = this.#entries.get(name);
+    return byName === void 0 ? [] : [...byName.values()];
+  }
+  resolveActive(name) {
+    return this.#active.get(name);
+  }
+  async resolveEntry(name, revision) {
+    const cached = this.getEntry(name, revision);
+    if (cached !== void 0)
+      return { manifest: cached.manifest, installedAt: cached.installedAt };
+    const durable = await readCatalogEntry(this.#storage, name, revision);
+    if (durable === null)
+      return;
+    this.#cacheEntry(name, revision, durable);
+    return durable;
+  }
+  async listInstalledRevisions(name) {
+    return (await scanCatalogEntriesForName(this.#storage, name)).toSorted((a, b) => compareCodepoint(a.manifest.revision, b.manifest.revision));
+  }
+  async hasInstalled(name, revision) {
+    if (this.getEntry(name, revision) !== void 0)
+      return !0;
+    return await readCatalogEntry(this.#storage, name, revision) !== null;
+  }
+  async resolveActiveDurable(name) {
+    return await readActivePointer(this.#storage, name) ?? void 0;
+  }
+  async remove(name, revision) {
+    requireStorageCapability(this.#storage, "conditionalBatch", "workflow catalog removal");
+    const result = await removeCatalogEntry(this.#storage, name, revision);
+    if (result.outcome === "removed")
+      this.#entries.get(name)?.delete(revision);
+    return result;
+  }
+  async install(manifest, definition) {
+    validateWorkflowOrActivityName(manifest.name, "workflow");
+    const existing = this.getEntry(manifest.name, manifest.revision);
+    if (existing !== void 0) {
+      if (!manifestsAreByteIdentical(existing.manifest, manifest))
+        throw new WorkflowCatalogConflictError(manifest.name, manifest.revision);
+      return existing;
+    }
+    const durable = await readCatalogEntry(this.#storage, manifest.name, manifest.revision);
+    if (durable !== null)
+      return this.#adoptDurableEntry(manifest, durable, definition);
+    const installedAt = Date.now();
+    if (!await writeCatalogEntry(this.#storage, manifest, installedAt)) {
+      const raced = await readCatalogEntry(this.#storage, manifest.name, manifest.revision);
+      if (raced === null)
+        throw new WorkflowCatalogConflictError(manifest.name, manifest.revision);
+      return this.#adoptDurableEntry(manifest, raced, definition);
+    }
+    return this.#cacheEntry(manifest.name, manifest.revision, {
+      manifest,
+      installedAt,
+      ...definition === void 0 ? {} : { definition }
+    });
+  }
+  #adoptDurableEntry(manifest, durable, definition) {
+    if (!manifestsAreByteIdentical(durable.manifest, manifest))
+      throw new WorkflowCatalogConflictError(manifest.name, manifest.revision);
+    return this.#cacheEntry(manifest.name, manifest.revision, {
+      manifest: durable.manifest,
+      installedAt: durable.installedAt,
+      ...definition === void 0 ? {} : { definition }
+    });
+  }
+  #cacheEntry(name, revision, entry) {
+    let byName = this.#entries.get(name);
+    if (byName === void 0) {
+      byName = new Map;
+      this.#entries.set(name, byName);
+    }
+    byName.set(revision, entry);
+    return entry;
+  }
+  async activateRegistered(name, manifest, definition) {
+    requireStorageCapability(this.#storage, "conditionalBatch", "workflow catalog activation");
+    await this.install(manifest, definition);
+    for (let attempt = 1;attempt <= MAX_ACTIVATE_REGISTERED_ATTEMPTS; attempt++) {
+      const current = await readActivePointer(this.#storage, name);
+      if (current !== null && current.revision === manifest.revision) {
+        this.#active.set(name, current);
+        return current;
+      }
+      const nextGeneration = current === null ? 1 : current.generation + 1, nextPointer = {
+        revision: manifest.revision,
+        generation: nextGeneration,
+        activatedAt: Date.now()
+      };
+      if (await storageConditionalBatch(this.#storage, [
+        {
+          key: KEYS.catalogActive(name),
+          expectedValue: current === null ? null : encodeActivePointer(current)
+        }
+      ], [{ type: "put", key: KEYS.catalogActive(name), value: encodeActivePointer(nextPointer) }])) {
+        this.#active.set(name, nextPointer);
+        return nextPointer;
+      }
+    }
+    throw new WorkflowCatalogActivationConflictError(name, MAX_ACTIVATE_REGISTERED_ATTEMPTS);
+  }
+  async activateCandidate(name, candidateManifest, options) {
+    requireStorageCapability(this.#storage, "conditionalBatch", "workflow catalog activation");
+    await this.install(candidateManifest);
+    const currentPointer = await readActivePointer(this.#storage, name), refusal = await this.#refuseIncompatibleOrStaleCandidate(name, candidateManifest, currentPointer, options);
+    if (refusal !== void 0)
+      return refusal;
+    const nextGeneration = currentPointer === null ? 1 : currentPointer.generation + 1, nextPointer = {
+      revision: candidateManifest.revision,
+      generation: nextGeneration,
+      activatedAt: Date.now()
+    };
+    if (!await storageConditionalBatch(this.#storage, [
+      {
+        key: KEYS.catalogActive(name),
+        expectedValue: currentPointer === null ? null : encodeActivePointer(currentPointer)
+      }
+    ], [{ type: "put", key: KEYS.catalogActive(name), value: encodeActivePointer(nextPointer) }]))
+      return { applied: !1, reason: "conflict" };
+    this.#active.set(name, nextPointer);
+    return { applied: !0, pointer: nextPointer };
+  }
+  async#refuseIncompatibleOrStaleCandidate(name, candidateManifest, currentPointer, options) {
+    if (currentPointer === null)
+      return this.#refuseStaleFirstActivation(options);
+    const generationRefusal = this.#refuseMissingOrStaleGeneration(currentPointer, options);
+    if (generationRefusal !== void 0)
+      return generationRefusal;
+    return this.#refuseIncompatibleCandidate(name, candidateManifest, currentPointer, options);
+  }
+  #refuseStaleFirstActivation(options) {
+    if (options?.expectedGeneration !== void 0 && options.expectedGeneration !== 0)
+      return { applied: !1, reason: "stale-generation", currentGeneration: 0 };
+    return;
+  }
+  #refuseMissingOrStaleGeneration(currentPointer, options) {
+    if (options?.expectedGeneration === void 0)
+      return {
+        applied: !1,
+        reason: "expected-generation-required",
+        currentGeneration: currentPointer.generation
+      };
+    if (options.expectedGeneration !== currentPointer.generation)
+      return {
+        applied: !1,
+        reason: "stale-generation",
+        currentGeneration: currentPointer.generation
+      };
+    return;
+  }
+  async#refuseIncompatibleCandidate(name, candidateManifest, currentPointer, options) {
+    const currentEntry = await this.resolveEntry(name, currentPointer.revision);
+    if (currentEntry === void 0)
+      throw new WorkflowCatalogActiveEntryMissingError(name, currentPointer.revision);
+    const verdict = checkWorkflowCompatibility(currentEntry.manifest, candidateManifest, options?.policy ?? DEFAULT_WORKFLOW_COMPATIBILITY_POLICY);
+    return verdict.compatible ? void 0 : { applied: !1, reason: "incompatible", verdict };
+  }
+}

package/dist/core/compare-codepoint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Order two strings by codepoint rather than `localeCompare` (project rule:
+ * deterministic comparisons in runtime logic). A standalone leaf module so
+ * every codepoint sort across the registry-snapshot family of modules —
+ * `registry-snapshot.ts`'s `sortedWorkflows`/`sortedActivities` and
+ * `registry-workflow-manifest.ts`'s scoped-activity sort — shares one
+ * implementation of the unreachable-in-isolation tie branch, rather than
+ * each defining its own uncovered copy, without creating an import cycle
+ * between those two modules.
+ *
+ * @module core/compare-codepoint
+ */
+export declare function compareCodepoint(a: string, b: string): number;