@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/application-primitive-payload.js

@@ -0,0 +1,65 @@
+import { computePayloadDigest, PayloadDigestError } from "./application-payload-digest.js";
+import {
+  createApplicationGuards,
+  MAX_APPLICATION_IDENTITY_BYTES
+} from "./application-primitive-guards.js";
+import { decode, encode } from "./codec.js";
+const HEX_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+export const MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES = 2048;
+export function createPayloadValidators(ValidationError) {
+  const { requireIdentity, optionalIdentityOf, requireNonNegativeInteger } = createApplicationGuards(ValidationError), validateInlinePayload = async (payload, maxInlinePayloadBytes) => {
+    const value = Reflect.get(payload, "value");
+    let encoded;
+    try {
+      encoded = encode(value);
+    } catch (cause) {
+      throw new ValidationError("payload.value is not encodable by the structured-clone codec.", {
+        cause
+      });
+    }
+    if (encoded.byteLength > maxInlinePayloadBytes)
+      throw new ValidationError(`payload.value encodes to ${encoded.byteLength} bytes, over the ${maxInlinePayloadBytes}-byte inline ceiling. Store it behind a content-addressed reference instead.`);
+    const snapshot = decode(encoded);
+    try {
+      return {
+        payload: { form: "inline", value: snapshot },
+        digest: await computePayloadDigest(snapshot)
+      };
+    } catch (cause) {
+      if (cause instanceof PayloadDigestError)
+        throw new ValidationError(`payload.value cannot be digested: ${cause.message}`, { cause });
+      throw cause;
+    }
+  }, validateReferencePayload = (payload) => {
+    const reference = requireIdentity(Reflect.get(payload, "reference"), "payload.reference", MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES), digest = Reflect.get(payload, "digest");
+    if (typeof digest !== "string" || !HEX_DIGEST_PATTERN.test(digest))
+      throw new ValidationError("payload.digest must be a 64-character lowercase hexadecimal SHA-256 digest. A reference payload has no other way to bind idempotency to payload identity.");
+    const rawByteLength = Reflect.get(payload, "byteLength");
+    if (rawByteLength === void 0)
+      return { payload: { form: "reference", reference, digest }, digest };
+    const referencedBytes = requireNonNegativeInteger(rawByteLength, "payload.byteLength", Number.MAX_SAFE_INTEGER);
+    return {
+      payload: { form: "reference", reference, digest, byteLength: referencedBytes },
+      digest
+    };
+  };
+  return { validatePayload: async (payload, maxInlinePayloadBytes) => {
+    if (typeof payload !== "object" || payload === null || !("form" in payload))
+      throw new ValidationError("payload must be an inline or reference payload object.");
+    const form = Reflect.get(payload, "form");
+    if (form === "inline")
+      return validateInlinePayload(payload, maxInlinePayloadBytes);
+    if (form !== "reference")
+      throw new ValidationError("payload.form must be 'inline' or 'reference'.");
+    return validateReferencePayload(payload);
+  }, validateCausation: (causation) => {
+    if (causation === void 0)
+      return;
+    if (typeof causation !== "object" || causation === null)
+      throw new ValidationError("causation must be an object when present.");
+    const correlationId = optionalIdentityOf(causation.correlationId, "causation.correlationId", MAX_APPLICATION_IDENTITY_BYTES), causationId = optionalIdentityOf(causation.causationId, "causation.causationId", MAX_APPLICATION_IDENTITY_BYTES), traceparent = optionalIdentityOf(causation.traceparent, "causation.traceparent", MAX_APPLICATION_IDENTITY_BYTES);
+    if (correlationId === void 0 && causationId === void 0 && traceparent === void 0)
+      return;
+    return { correlationId, causationId, traceparent };
+  } };
+}

package/dist/core/application-primitive-timing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Timing helpers shared by the durable application primitives (the command
+ * mailbox, WFT-84, and the delivery outbox, WFT-85): the deterministic retry
+ * backoff every reschedule uses, and the abortable sleep every polling wait
+ * uses.
+ *
+ * @module core/application-primitive-timing
+ */
+/** Deterministic exponential backoff. No jitter, so redelivery timing is testable. */
+export declare function computeRetryBackoffMs(attempt: number, baseMs: number, maximumMs: number): number;
+/**
+ * Sleep, resolving `false` when the wait was aborted or the primitive disposed
+ * and `true` when the interval actually elapsed.
+ *
+ * The listeners are removed on every path, including the timer path, so a
+ * long-lived primitive does not accumulate abort listeners once per poll.
+ */
+export declare function delayUnlessAborted(milliseconds: number, disposal: AbortSignal, signal?: AbortSignal): Promise<boolean>;

package/dist/core/application-primitive-timing.js

@@ -0,0 +1,22 @@
+export function computeRetryBackoffMs(attempt, baseMs, maximumMs) {
+  const raw = baseMs * 2 ** Math.max(0, attempt - 1);
+  return Math.min(Number.isFinite(raw) ? raw : maximumMs, maximumMs);
+}
+export function delayUnlessAborted(milliseconds, disposal, signal) {
+  if (signal?.aborted === !0 || disposal.aborted)
+    return Promise.resolve(!1);
+  return new Promise((resolve) => {
+    const settle = (elapsed) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      disposal.removeEventListener("abort", onAbort);
+      resolve(elapsed);
+    }, onAbort = () => {
+      settle(!1);
+    }, timer = setTimeout(() => {
+      settle(!0);
+    }, milliseconds);
+    signal?.addEventListener("abort", onAbort, { once: !0 });
+    disposal.addEventListener("abort", onAbort, { once: !0 });
+  });
+}

package/dist/core/atomic-state.js

@@ -32,6 +32,8 @@ export function atomicStateDataKey(scope, key) {
       return KEYS.stateExecution(scope.ownerWorkflowId, key);
     case "workflow":
       return KEYS.stateWorkflow(scope.workflowType, key);
+    default:
+      throw Error(`Unknown atomic state scope type: ${JSON.stringify(scope)}`);
   }
 }
 function assertValidAtomicStateKey(key) {

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

@@ -0,0 +1,40 @@
+/**
+ * Encoding, decoding, and structural validation for durable catalog records.
+ *
+ * The active-pointer record (`catalog-active:<name>`) is the only catalog
+ * value whose bytes are read back and trusted for control-flow decisions
+ * (the CAS retry loop, generation comparisons) — so unlike the manifest
+ * entry (validated end-to-end by {@link parseWorkflowRevisionManifest}),
+ * it gets its own small structural validator here rather than round-tripping
+ * through a JSON-Schema-shaped parser.
+ *
+ * @module core/catalog/codec
+ */
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { WorkflowCatalogActivePointer } from './types.ts';
+/** Encode an active-pointer record for durable storage. */
+export declare function encodeActivePointer(pointer: WorkflowCatalogActivePointer): Uint8Array;
+/**
+ * Decode and structurally validate an active-pointer record read from
+ * durable storage. Returns `null` when the bytes do not decode as a valid
+ * `{ revision, generation, activatedAt }` record — the caller
+ * (`restoreWorkflowCatalog`) fails closed on `null` rather than treating it
+ * as absent, matching the codebase's fail-closed convention for corrupted
+ * durable singleton records (`ownership-mode-marker.ts`,
+ * `EngineLeaseCorruptedError`).
+ */
+export declare function decodeActivePointer(bytes: Uint8Array): WorkflowCatalogActivePointer | null;
+/**
+ * Deep-equality comparison between two workflow revision manifests, used by
+ * `WorkflowCatalog.install()` to decide whether a re-install for an existing
+ * `(name, revision)` key is a byte-identical no-op or a genuine metadata
+ * conflict. Compares each manifest's top-level identity scalars alongside
+ * its `contract` field's existing canonical serialization
+ * ({@link canonicalWorkflowContractJson}, `core/contract/normalize.ts`) —
+ * reusing that canonicalizer rather than a fresh `JSON.stringify` keeps this
+ * comparison immune to incidental object-key insertion-order differences
+ * inside `contract`, the same guarantee `contractHash()`/`revision` already
+ * rely on. A caller-supplied `revision` string that changed independently of
+ * contract content is also treated as a conflict, not a silent no-op.
+ */
+export declare function manifestsAreByteIdentical(a: WorkflowRevisionManifest, b: WorkflowRevisionManifest): boolean;

package/dist/core/catalog/codec.js

@@ -0,0 +1,45 @@
+import { decode, encode } from "../codec.js";
+import { canonicalWorkflowContractJson } from "../contract/normalize.js";
+export function encodeActivePointer(pointer) {
+  return encode(pointer);
+}
+export function decodeActivePointer(bytes) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    return null;
+  }
+  if (typeof decoded !== "object" || decoded === null)
+    return null;
+  return validateActivePointerRecord(decoded);
+}
+function validateActivePointerRecord(record) {
+  const { revision, generation, activatedAt } = record;
+  if (!isNonEmptyString(revision))
+    return null;
+  if (!isPositiveSafeInteger(generation))
+    return null;
+  if (typeof activatedAt !== "number" || !Number.isFinite(activatedAt))
+    return null;
+  return { revision, generation, activatedAt };
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+export function manifestsAreByteIdentical(a, b) {
+  return canonicalManifestJson(a) === canonicalManifestJson(b);
+}
+function canonicalManifestJson(manifest) {
+  return JSON.stringify({
+    manifestVersion: manifest.manifestVersion,
+    name: manifest.name,
+    workflowVersion: manifest.workflowVersion,
+    revision: manifest.revision,
+    contractHash: manifest.contractHash,
+    contract: canonicalWorkflowContractJson(manifest.contract)
+  });
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Error classes thrown by the durable workflow catalog (WFT-9/WFT-10) and
+ * its public promotion, `engine.workflows` (WFT-11).
+ *
+ * `WorkflowCatalogConflictError` and `WorkflowRevisionNotInstalledError` are
+ * public — part of `WeftErrorCode` and re-exported from `src/index.ts` —
+ * because `engine.workflows.install()`/`activate()` can throw either of them
+ * directly at a caller who holds no other way to reach the catalog.
+ * `WorkflowCatalogActivationConflictError` stays internal: it is reachable
+ * only through `engine.register()`'s unconditional `activateRegistered`
+ * path, which every public entry point already awaits via
+ * `ensureWorkflowCatalogReady` rather than calling directly, so no public
+ * caller ever observes it as a typed error to catch.
+ *
+ * @module core/catalog/errors
+ */
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown by {@link import('./workflow-catalog.ts').WorkflowCatalog.install}
+ * when a caller attempts to install a `(name, revision)` pair that already
+ * has a durably- or in-memory-installed entry with different manifest bytes.
+ * A byte-identical reinstall for the same key is a no-op, not an error — see
+ * `install()`'s JSDoc.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowCatalogConflictError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   throw new WorkflowCatalogConflictError('checkout', 'r1');
+ * } catch (error) {
+ *   if (error instanceof WorkflowCatalogConflictError) {
+ *     console.error(error.workflowName, error.revision);
+ *   }
+ * }
+ * void engine;
+ * ```
+ */
+export declare class WorkflowCatalogConflictError extends WeftError<'WorkflowCatalogConflictError'> {
+    readonly workflowName: string;
+    readonly revision: string;
+    constructor(workflowName: string, revision: string);
+}
+/**
+ * Thrown by
+ * {@link import('./workflow-catalog.ts').WorkflowCatalog.activateRegistered}
+ * after its bounded 5-attempt CAS retry loop exhausts without successfully
+ * committing the active pointer — mirrors `AtomicStateConflictError`'s
+ * exhaustion contract.
+ */
+export declare class WorkflowCatalogActivationConflictError extends WeftError<'WorkflowCatalogActivationConflictError'> {
+    readonly workflowName: string;
+    readonly attempts: number;
+    constructor(workflowName: string, attempts: number);
+}
+/**
+ * Thrown by `engine.workflows.activate()` when `(workflowName, revision)`
+ * has never been installed — distinct from
+ * `WorkflowCatalog.activateCandidate`'s own `applied: false` refusal
+ * variants, which all assume the candidate IS installed and instead
+ * describe why activating it was refused.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionNotInstalledError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.workflows.activate('checkout', 'unknown-revision');
+ * } catch (error) {
+ *   if (error instanceof WorkflowRevisionNotInstalledError) {
+ *     console.error(error.workflowName, error.revision);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowRevisionNotInstalledError extends WeftError<'WorkflowRevisionNotInstalledError'> {
+    readonly workflowName: string;
+    readonly revision: string;
+    constructor(workflowName: string, revision: string);
+}
+/**
+ * Thrown by
+ * {@link import('./workflow-catalog.ts').WorkflowCatalog.activateCandidate}
+ * when the durable active pointer for `name` names a revision whose catalog
+ * entry cannot be resolved — neither this process's in-memory cache nor a
+ * durable read-through finds it. This should be unreachable in practice:
+ * both activation entry points (`install()`-then-activate) always durably
+ * install a revision before ever pointing the active pointer at it, so a
+ * durably-active revision missing its own entry is a genuine storage
+ * inconsistency, not a race any caller can retry past. Fail-closed rather
+ * than silently skipping the compatibility check `activateCandidate`
+ * exists to enforce — see `#refuseIncompatibleCandidate`'s JSDoc. Stays
+ * internal (not re-exported from `src/index.ts`) like
+ * {@link WorkflowCatalogActivationConflictError}: no code path lets a public
+ * caller observe it as a typed error to catch, only as a generic
+ * `EngineFailure`-wrapped operation fault.
+ */
+export declare class WorkflowCatalogActiveEntryMissingError extends WeftError<'WorkflowCatalogActiveEntryMissingError'> {
+    readonly workflowName: string;
+    readonly revision: string;
+    constructor(workflowName: string, revision: string);
+}

package/dist/core/catalog/errors.js

@@ -0,0 +1,41 @@
+import { WeftError } from "../weft-error.js";
+
+export class WorkflowCatalogConflictError extends WeftError {
+  workflowName;
+  revision;
+  constructor(workflowName, revision) {
+    super("WorkflowCatalogConflictError", `Workflow catalog entry "${workflowName}" revision "${revision}" is already installed with ` + "different contract metadata. A revision identity must be immutable once installed \u2014 " + "register a workflow whose contract content differs under a new revision instead of reusing this one.");
+    this.workflowName = workflowName;
+    this.revision = revision;
+  }
+}
+
+export class WorkflowCatalogActivationConflictError extends WeftError {
+  workflowName;
+  attempts;
+  constructor(workflowName, attempts) {
+    super("WorkflowCatalogActivationConflictError", `Workflow catalog activation conflict: failed to activate "${workflowName}" after ${String(attempts)} attempts due to sustained concurrent writers.`);
+    this.workflowName = workflowName;
+    this.attempts = attempts;
+  }
+}
+
+export class WorkflowRevisionNotInstalledError extends WeftError {
+  workflowName;
+  revision;
+  constructor(workflowName, revision) {
+    super("WorkflowRevisionNotInstalledError", `Workflow "${workflowName}" has no installed revision "${revision}" \u2014 install it via ` + "engine.workflows.install() before activating it.");
+    this.workflowName = workflowName;
+    this.revision = revision;
+  }
+}
+
+export class WorkflowCatalogActiveEntryMissingError extends WeftError {
+  workflowName;
+  revision;
+  constructor(workflowName, revision) {
+    super("WorkflowCatalogActiveEntryMissingError", `Workflow catalog inconsistency: "${workflowName}" is durably active at revision "${revision}", but that revision's catalog entry cannot be resolved (neither in-memory nor durably). Refusing to activate a candidate without being able to check compatibility against the currently active revision.`);
+    this.workflowName = workflowName;
+    this.revision = revision;
+  }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Barrel for the durable workflow catalog (WFT-9/WFT-10, extended with
+ * reference accounting and removal in WFT-12).
+ *
+ * `WorkflowCatalog` itself and `WorkflowCatalogEntry` (which can carry a
+ * live `RegisteredWorkflowDefinition` function reference) stay
+ * package-internal — `core/engine/catalog-readiness.ts`,
+ * `core/engine/catalog-activation.ts`, `core/engine/catalog-removal.ts`, and
+ * `core/registry-snapshot.ts` are their consumers. Two different public
+ * surfaces are built on top: WFT-11's `engine.workflows`
+ * (`core/engine/engine-workflows-namespace.ts`), which is why
+ * `WorkflowCatalogConflictError`, `WorkflowRevisionNotInstalledError`,
+ * `WorkflowCatalogActivationResult`, `WorkflowCatalogActivePointer`, and
+ * `WorkflowRevisionRecord` ARE re-exported from `src/index.ts`; and WFT-12's
+ * `removeWorkflowRevision`/`getWorkflowRevisionDiagnostics`
+ * (`core/engine/catalog-removal.ts`).
+ *
+ * @module core/catalog
+ */
+export { WorkflowCatalogActivationConflictError, WorkflowCatalogActiveEntryMissingError, WorkflowCatalogConflictError, WorkflowRevisionNotInstalledError, } from './errors.ts';
+export { decrementNestedRevisionCount, incrementNestedRevisionCount, readNestedRevisionCount, totalWorkflowRevisionReferences, type WorkflowRevisionReferenceCounts, } from './reference-counts.ts';
+export { removeCatalogEntry, type WorkflowCatalogRemovalOutcome } from './removal.ts';
+export { restoreWorkflowCatalog, type RestoredWorkflowCatalogState } from './storage-io.ts';
+export type { WorkflowCatalogActivationResult, WorkflowCatalogActivePointer, WorkflowCatalogEntry, WorkflowRevisionRecord, } from './types.ts';
+export { WorkflowCatalog, type ActivateCandidateOptions } from './workflow-catalog.ts';

package/dist/core/catalog/index.js

@@ -0,0 +1,15 @@
+export {
+  WorkflowCatalogActivationConflictError,
+  WorkflowCatalogActiveEntryMissingError,
+  WorkflowCatalogConflictError,
+  WorkflowRevisionNotInstalledError
+} from "./errors.js";
+export {
+  decrementNestedRevisionCount,
+  incrementNestedRevisionCount,
+  readNestedRevisionCount,
+  totalWorkflowRevisionReferences
+} from "./reference-counts.js";
+export { removeCatalogEntry } from "./removal.js";
+export { restoreWorkflowCatalog } from "./storage-io.js";
+export { WorkflowCatalog } from "./workflow-catalog.js";

package/dist/core/catalog/reference-counts.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `WorkflowRevisionReferenceCounts` — the bounded accounting interface a
+ * `(name, revision)` removal decision is gated on (WFT-12).
+ *
+ * Seven fields, all always present so a consumer never has to special-case
+ * an "unknown" reference kind. Two are wired to real in-process signals this
+ * batch; the remaining five stay structurally present but always `0` until
+ * run-level revision pinning lands (WFT-17) gives them something real to
+ * count — see each field's own doc for its specific WFT-17 dependency. This
+ * mirrors `workflow-catalog.ts`'s own precedent of describing a forward
+ * dependency in prose rather than leaving a `TODO`/`FIXME` marker.
+ *
+ * Keyed by structured `(name, revision)` throughout — nested
+ * `Map<string, Map<string, number>>`, never a delimiter-joined string — so a
+ * workflow `name` or `revision` equal to `'__proto__'`/`'toString'` or
+ * containing a colon is always handled correctly, matching
+ * `WorkflowCatalog`'s own `#entries` convention.
+ *
+ * @module core/catalog/reference-counts
+ */
+/**
+ * Every reference kind a `(name, revision)` removal decision considers.
+ * Removal is refused whenever {@link totalWorkflowRevisionReferences} is
+ * nonzero for the target revision.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowRevisionReferenceCounts } from '@lostgradient/weft';
+ *
+ * function summarize(counts: WorkflowRevisionReferenceCounts): string {
+ *   return `${counts.registeredDefinitions} registered, ${counts.inFlightStarts} in flight`;
+ * }
+ * void summarize;
+ * ```
+ */
+export type WorkflowRevisionReferenceCounts = Readonly<{
+    /**
+     * `1` when this process's own `engine.register()`-drain path most
+     * recently activated exactly this revision for this name, `0` otherwise.
+     * Wired now, from `EngineInternals.registeredCatalogRevisions`.
+     */
+    registeredDefinitions: number;
+    /**
+     * Count of this process's own in-flight `startWorkflow` calls reserved
+     * against this revision (from `EngineInternals.inFlightStartsByRevision`).
+     * Wired now; the reservation lives inside `lifecycle/start.ts`'s single
+     * `startWorkflow` choke point itself, so every caller that funnels through
+     * it is already counted — `engine.start()`/`engine.startOrSignal()`'s
+     * create path, and `ctx.startChild()` too, since
+     * `createChildWorkflowOperationCallbacks` (`callback-creators-bundles.ts`)
+     * calls the very same `startWorkflow`. There is no separate bulk
+     * `startBatch()` entry point to funnel — `buildStartBatchOperations` is
+     * internal plumbing already inside this same `startWorkflow` call,
+     * building one start's own storage-write batch, not a distinct
+     * multi-start API.
+     */
+    inFlightStarts: number;
+    /**
+     * Non-terminal runs whose `WorkflowState` pins exactly this revision.
+     * Always `0` until run-level revision pinning (WFT-17) gives a run's
+     * persisted state a `revision` field to count against.
+     */
+    nonTerminalRuns: number;
+    /**
+     * Schedules pinned to exactly this revision. Always `0` until WFT-17
+     * introduces schedule-level revision pinning.
+     */
+    pinnedSchedules: number;
+    /**
+     * Queued dispatches (delayed starts, retries) targeting exactly this
+     * revision. Always `0` until WFT-17 threads revision identity through the
+     * dispatch ledger.
+     */
+    pendingDispatches: number;
+    /**
+     * Active execution realms (remote worker sessions) currently running
+     * exactly this revision. Always `0` until WFT-17 gives a realm's
+     * advertised contract a revision this accounting can compare against.
+     */
+    activeExecutionRealms: number;
+    /**
+     * Retained recovery records (crash-recovery checkpoints, dead letters)
+     * referencing exactly this revision. Always `0` until WFT-17 threads
+     * revision identity through those retained records.
+     */
+    retainedRecoveryRecords: number;
+}>;
+/** Sum every field of `counts` — nonzero means removal must be refused. */
+export declare function totalWorkflowRevisionReferences(counts: WorkflowRevisionReferenceCounts): number;
+/**
+ * Increment the `(name, revision)` count in a nested
+ * `Map<string, Map<string, number>>`, creating the inner map and the entry
+ * as needed.
+ */
+export declare function incrementNestedRevisionCount(counts: Map<string, Map<string, number>>, name: string, revision: string): void;
+/**
+ * Decrement the `(name, revision)` count in a nested
+ * `Map<string, Map<string, number>>`. Removes the revision's own entry once
+ * it reaches `0` (rather than leaving a stale `0` behind) and removes the
+ * name's inner map once it is empty. A decrement against an absent
+ * `(name, revision)` is a no-op — never goes negative.
+ */
+export declare function decrementNestedRevisionCount(counts: Map<string, Map<string, number>>, name: string, revision: string): void;
+/** Read the `(name, revision)` count from a nested map, `0` when absent. */
+export declare function readNestedRevisionCount(counts: Map<string, Map<string, number>>, name: string, revision: string): number;

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,52 @@
+/**
+ * The mechanical CAS-delete primitive `WorkflowCatalog.remove()` delegates
+ * to. 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.
+ *
+ * @module core/catalog/removal
+ */
+import { type Storage } from '../../storage/interface.ts';
+/** Outcome of {@link removeCatalogEntry}. */
+export type WorkflowCatalogRemovalOutcome = Readonly<{
+    outcome: 'removed';
+}> | Readonly<{
+    outcome: 'not-found';
+}> | Readonly<{
+    outcome: 'active';
+    activeRevision: string;
+}> | Readonly<{
+    outcome: 'conflict';
+}>;
+/**
+ * Durably delete the installed-revision record for `(name, revision)`.
+ *
+ * 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 via a `conditionalBatch` CAS'd on
+ * BOTH 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 (either key changed
+ * concurrently) surfaces as `'conflict'`.
+ */
+export declare function removeCatalogEntry(storage: Storage, name: string, revision: string): Promise<WorkflowCatalogRemovalOutcome>;

package/dist/core/catalog/removal.js

@@ -0,0 +1,14 @@
+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 };
+  return await storageConditionalBatch(storage, [
+    { key: entryKey, expectedValue: entryBytes },
+    { key: activeKey, expectedValue: activeBytes }
+  ], [{ type: "delete", key: entryKey }]) ? { outcome: "removed" } : { outcome: "conflict" };
+}