@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/outbox.js

@@ -0,0 +1,234 @@
+import {
+  attemptControllerRegistry,
+  releaseAttemptControllerRegistry
+} from "./application-primitive-attempt-registry.js";
+import { claimNextDelivery } from "./outbox-delivery.js";
+import { drainOutbox } from "./outbox-drain.js";
+import { capacityOf, enqueueDelivery } from "./outbox-enqueue.js";
+import {
+  ApplicationDeliveryValidationError,
+  requireClockInstant,
+  requireMaintenanceInstant,
+  validateCancellationReason,
+  validateDeliveryIdentifier,
+  validateDurableJSONValue
+} from "./outbox-guards.js";
+import {
+  OUTBOX_PRIMITIVE,
+  toApplicationDeliveryReceipt
+} from "./outbox-internals.js";
+import { listDeliveries } from "./outbox-listing.js";
+import { runOutboxMaintenance } from "./outbox-maintenance.js";
+import { deadLetterDelivery, retryDelivery } from "./outbox-operations.js";
+import { deliverNext } from "./outbox-runner.js";
+import {
+  beginAttempt,
+  heartbeatAttempt,
+  readCleanupState,
+  requestCancellation,
+  settleAttempt
+} from "./outbox-settlement.js";
+import { createOutboxKeys, loadDelivery, loadOutboxHeader } from "./outbox-storage.js";
+import { resolveOutboxPolicy, validateOutcome } from "./outbox-validation.js";
+import { waitForCleanup, waitForDueWork } from "./outbox-waits.js";
+function requireOutboxStorage(storage) {
+  const capabilities = storage.capabilities();
+  if (!capabilities.conditionalBatch)
+    throw new ApplicationDeliveryValidationError("Application outboxes require storage with conditional batch support: every transition is a compare-and-swap.");
+  if (capabilities.scanConsistency !== "snapshot")
+    throw new ApplicationDeliveryValidationError("Application outboxes require storage with snapshot scan consistency: claims read the earliest due entry, and a best-effort scan can miss one.");
+  if (capabilities.readAfterWrite !== "linearizable")
+    throw new ApplicationDeliveryValidationError("Application outboxes require storage with linearizable read-after-write: maintenance reconciles live attempts against what it reads, and a stale read could abort a current one.");
+}
+
+export class Outbox {
+  #runtime;
+  #disposal = new AbortController;
+  #ownAttempts = new Set;
+  #maintenanceCursor;
+  #maintenanceTimer = null;
+  #disposed = !1;
+  constructor(options) {
+    const policy = resolveOutboxPolicy(options);
+    requireOutboxStorage(options.storage);
+    if (options.adapter !== void 0 && typeof options.adapter.send !== "function")
+      throw new ApplicationDeliveryValidationError("adapter must expose a send() function.");
+    if (options.onMaintenanceError !== void 0 && typeof options.onMaintenanceError !== "function")
+      throw new ApplicationDeliveryValidationError("onMaintenanceError must be a function.");
+    this.#runtime = {
+      storage: options.storage,
+      events: options.events,
+      adapter: options.adapter,
+      policy,
+      keys: createOutboxKeys(policy.namespace, policy.ownerId),
+      now: () => requireClockInstant((options.now ?? Date.now)()),
+      generateId: options.generateId ?? (() => crypto.randomUUID()),
+      disposal: this.#disposal.signal,
+      attemptControllers: attemptControllerRegistry(options.storage, OUTBOX_PRIMITIVE, policy.namespace, policy.ownerId),
+      adoptAttempt: (attemptToken) => {
+        if (this.#disposed)
+          return null;
+        this.#ownAttempts.add(attemptToken);
+        return () => {
+          this.#ownAttempts.delete(attemptToken);
+        };
+      },
+      readMaintenanceCursor: () => this.#maintenanceCursor,
+      writeMaintenanceCursor: (cursor) => {
+        this.#maintenanceCursor = cursor;
+      }
+    };
+    if (policy.backgroundTasks === "automatic")
+      this.#scheduleMaintenance(options.onMaintenanceError ?? defaultMaintenanceErrorSink);
+  }
+  #scheduleMaintenance(onError) {
+    const tick = async () => {
+      this.#maintenanceTimer = null;
+      if (this.#disposed)
+        return;
+      try {
+        await runOutboxMaintenance(this.#runtime, this.#runtime.now());
+      } catch (error) {
+        if (this.#disposed)
+          return;
+        try {
+          onError(error);
+        } catch {}
+      }
+      if (!this.#disposed)
+        arm();
+    }, arm = () => {
+      this.#maintenanceTimer = setTimeout(() => {
+        tick();
+      }, this.#runtime.policy.maintenanceIntervalMs);
+      this.#maintenanceTimer.unref?.();
+    };
+    arm();
+  }
+  get namespace() {
+    return this.#runtime.policy.namespace;
+  }
+  get ownerId() {
+    return this.#runtime.policy.ownerId;
+  }
+  get storage() {
+    return this.#runtime.storage;
+  }
+  #assertLive() {
+    if (this.#disposed)
+      throw new ApplicationDeliveryValidationError("This application outbox has been disposed.");
+  }
+  async enqueue(delivery) {
+    this.#assertLive();
+    return enqueueDelivery(this.#runtime, delivery);
+  }
+  async receipt(deliveryId) {
+    this.#assertLive();
+    const loaded = await loadDelivery(this.#runtime.storage, this.#runtime.keys, validateDeliveryIdentifier(deliveryId));
+    return loaded === null ? null : toApplicationDeliveryReceipt(loaded.record);
+  }
+  async list(options) {
+    this.#assertLive();
+    return listDeliveries(this.#runtime, options);
+  }
+  async capacity() {
+    this.#assertLive();
+    const header = await loadOutboxHeader(this.#runtime.storage, this.#runtime.keys, this.#runtime.policy.namespace, this.#runtime.policy.ownerId);
+    return capacityOf(this.#runtime, header.record.openCount, header.record.enqueuedCount);
+  }
+  async claim(options) {
+    this.#assertLive();
+    return claimNextDelivery(this.#runtime, options);
+  }
+  async beginAttempt(options) {
+    this.#assertLive();
+    return beginAttempt(this.#runtime, {
+      deliveryId: validateDeliveryIdentifier(options.deliveryId),
+      attemptToken: options.attemptToken
+    });
+  }
+  async heartbeat(options) {
+    this.#assertLive();
+    return heartbeatAttempt(this.#runtime, {
+      deliveryId: validateDeliveryIdentifier(options.deliveryId),
+      attemptToken: options.attemptToken,
+      transportActivity: validateDurableJSONValue(options.transportActivity, "transportActivity")
+    });
+  }
+  async settle(options) {
+    this.#assertLive();
+    return settleAttempt(this.#runtime, {
+      deliveryId: validateDeliveryIdentifier(options.deliveryId),
+      attemptToken: options.attemptToken,
+      outcome: validateOutcome(options.outcome)
+    });
+  }
+  async deliverNext(options) {
+    this.#assertLive();
+    return deliverNext(this.#runtime, options);
+  }
+  async drain(options) {
+    this.#assertLive();
+    return drainOutbox(this.#runtime, options);
+  }
+  async requestCancellation(options) {
+    this.#assertLive();
+    return requestCancellation(this.#runtime, {
+      deliveryId: validateDeliveryIdentifier(options.deliveryId),
+      reason: validateCancellationReason(options.reason)
+    });
+  }
+  async cleanupState(deliveryId) {
+    this.#assertLive();
+    return readCleanupState(this.#runtime, validateDeliveryIdentifier(deliveryId));
+  }
+  async awaitCleanup(options) {
+    this.#assertLive();
+    return waitForCleanup(this.#runtime, {
+      ...options,
+      deliveryId: validateDeliveryIdentifier(options.deliveryId)
+    });
+  }
+  async retry(options) {
+    this.#assertLive();
+    return retryDelivery(this.#runtime, validateDeliveryIdentifier(options.deliveryId));
+  }
+  async deadLetter(options) {
+    this.#assertLive();
+    return deadLetterDelivery(this.#runtime, validateDeliveryIdentifier(options.deliveryId), validateCancellationReason(options.reason));
+  }
+  async waitForDue(options) {
+    this.#assertLive();
+    return waitForDueWork(this.#runtime, options);
+  }
+  async runMaintenance(now = this.#runtime.now()) {
+    this.#assertLive();
+    return runOutboxMaintenance(this.#runtime, requireMaintenanceInstant(now));
+  }
+  dispose() {
+    if (this.#disposed)
+      return;
+    this.#disposed = !0;
+    if (this.#maintenanceTimer !== null) {
+      clearTimeout(this.#maintenanceTimer);
+      this.#maintenanceTimer = null;
+    }
+    for (const attemptToken of this.#ownAttempts) {
+      const registration = this.#runtime.attemptControllers.get(attemptToken);
+      if (registration === void 0)
+        continue;
+      this.#runtime.attemptControllers.delete(attemptToken);
+      if (!registration.controller.signal.aborted)
+        registration.controller.abort(Error("The application outbox was disposed while this attempt was open."));
+    }
+    this.#ownAttempts.clear();
+    this.#disposal.abort(Error("The application outbox was disposed."));
+    releaseAttemptControllerRegistry(this.#runtime.storage, OUTBOX_PRIMITIVE, this.#runtime.policy.namespace, this.#runtime.policy.ownerId);
+  }
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+}
+function defaultMaintenanceErrorSink(error) {
+  console.error("Application outbox maintenance failed:", error);
+}

package/dist/core/registry-limits.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Aggregate registry-snapshot limits shared between the producer
+ * (`buildRegistrySnapshot`) and the codegen consumer
+ * (`cli/codegen-validate.ts`). Split into its own leaf module — rather than
+ * living in `registry-snapshot.ts` — so `codegen-validate.ts` can import the
+ * constant and error type without pulling in the rest of the (non-public)
+ * snapshot-building surface, and so `registry-snapshot.ts` stays under the
+ * repository's implementation-file-size ceiling.
+ *
+ * Deliberately not re-exported from `core/contract/limits.ts` or any other
+ * public-surface module: `registry-snapshot.ts` and this module are internal
+ * to the package (never re-exported from the package root), so this constant
+ * and error class are not part of the public API and carry no `@example`/
+ * jsdoc-audit obligations.
+ *
+ * @module core/registry-limits
+ */
+import { WeftError } from './weft-error.ts';
+/**
+ * Ceiling on the number of workflows one registry snapshot may report,
+ * enforced at snapshot-build time in `buildRegistrySnapshot` (the producer)
+ * and, independently, on the raw wire payload in `codegen-validate.ts` (the
+ * consumer) before that payload is parsed. The two call sites deliberately
+ * share this one constant rather than each defining its own: a consumer
+ * ceiling looser than the producer's would be dead code, and a consumer
+ * ceiling tighter than the producer's would make `weft codegen --server`
+ * reject a legitimately-generated snapshot from a same-release server.
+ *
+ * 512 matches `worker/manifest/limits.ts`'s `MAX_MANIFEST_WORKFLOW_COUNT` —
+ * the analogous ceiling an advertised worker manifest's `workflows` array is
+ * held to — without importing across the `core`/`worker` boundary; the two
+ * numbers are intentionally kept in sync by convention, not by a shared
+ * import, since `core/` does not depend on `worker/`.
+ */
+export declare const MAX_REGISTRY_WORKFLOW_COUNT = 512;
+/**
+ * Thrown when `buildRegistrySnapshot` would otherwise publish more than
+ * {@link MAX_REGISTRY_WORKFLOW_COUNT} workflows in one snapshot. Unlike
+ * {@link RegistryManifestLimitError}, this is an aggregate violation with no
+ * single offending workflow to name. Mirrors
+ * `RegistrySchemaConversionError`/`RegistryManifestLimitError`'s masked-500
+ * handling in `server/operations/get-registry.ts`: the wire response stays a
+ * generic `500 / Internal server error`, and the actual count reaches
+ * server-side logs only.
+ */
+export declare class RegistryWorkflowCountLimitError extends WeftError<'RegistryWorkflowCountLimitError'> {
+    readonly count: number;
+    constructor(count: number);
+}

package/dist/core/registry-limits.js

@@ -0,0 +1,10 @@
+import { WeftError } from "./weft-error.js";
+export const MAX_REGISTRY_WORKFLOW_COUNT = 512;
+
+export class RegistryWorkflowCountLimitError extends WeftError {
+  count;
+  constructor(count) {
+    super("RegistryWorkflowCountLimitError", `Registry snapshot would report ${count} workflows, exceeding the maximum of ${MAX_REGISTRY_WORKFLOW_COUNT}`);
+    this.count = count;
+  }
+}

package/dist/core/registry-schema-conversion.d.ts

@@ -0,0 +1,20 @@
+import type { DefinitionSchema } from './types/definition-schema.ts';
+import { WeftError } from './weft-error.ts';
+/**
+ * Thrown when a registered workflow or activity schema cannot be converted
+ * to JSON Schema. Carries the offending entity name and direction so
+ * server-side observability (logs and telemetry) and non-HTTP callers
+ * (the in-process MCP builder, programmatic users of `buildRegistrySnapshot`)
+ * can identify which registration is broken. The HTTP REST binding
+ * deliberately masks this on the wire as a generic `500 / Internal server
+ * error` so a misbehaving registration cannot leak schema layout to clients
+ * that only have `system:read`.
+ */
+export declare class RegistrySchemaConversionError extends WeftError<'RegistrySchemaConversionError'> {
+    readonly entityKind: 'workflow' | 'activity';
+    readonly entityName: string;
+    readonly direction: 'inputSchema' | 'outputSchema';
+    constructor(entityKind: 'workflow' | 'activity', entityName: string, direction: 'inputSchema' | 'outputSchema', cause: unknown);
+}
+/** Convert one `DefinitionSchema` fragment to JSON Schema, wrapping a conversion failure as {@link RegistrySchemaConversionError}. */
+export declare function convertSchema(entityKind: 'workflow' | 'activity', entityName: string, field: 'inputSchema' | 'outputSchema', schema: DefinitionSchema): Record<string, unknown>;

package/dist/core/registry-schema-conversion.js

@@ -0,0 +1,22 @@
+import { definitionSchemaToJsonSchema } from "./types/definition-schema-to-json.js";
+import { WeftError } from "./weft-error.js";
+
+export class RegistrySchemaConversionError extends WeftError {
+  entityKind;
+  entityName;
+  direction;
+  constructor(entityKind, entityName, direction, cause) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    super("RegistrySchemaConversionError", `Failed to convert ${direction} for ${entityKind} "${entityName}": ${causeMessage}`, { cause });
+    this.entityKind = entityKind;
+    this.entityName = entityName;
+    this.direction = direction;
+  }
+}
+export function convertSchema(entityKind, entityName, field, schema) {
+  try {
+    return definitionSchemaToJsonSchema(schema, field === "inputSchema" ? "input" : "output");
+  } catch (cause) {
+    throw new RegistrySchemaConversionError(entityKind, entityName, field, cause);
+  }
+}

package/dist/core/registry-snapshot.d.ts

@@ -8,41 +8,45 @@
  * exceptions surface as a typed {@link RegistrySchemaConversionError} (see
  * its JSDoc for what reaches the wire vs server logs).
  *
- * **Ordering guarantee.** Builder code inserts workflow, activity, signal,
- * update, and query keys in alphabetical (codepoint) order. Workflow and
- * activity names cannot be integer-like (the name grammar requires a leading
- * letter or underscore), but signal/update/query names accept any string, so
- * integer-like message names could theoretically be reordered by JS engines
- * despite the explicit sort. Clients that want to protect themselves from
- * future registry sources should still sort `Object.keys(...)` before
- * presenting or diffing snapshot entries.
+ * **v2.** Each registered workflow's schema/description/tags/message
+ * metadata is packaged as a {@link WorkflowRevisionManifest} (`core/contract`,
+ * WFT-5) rather than a flat `Record<name, entry>` — `workflows` is a sorted
+ * array and `activeRevisions` is the `name -> revision` pointer map a
+ * consumer resolves the "currently active" manifest through. Building a
+ * manifest hashes the normalized contract (`crypto.subtle`), so this module
+ * is async where v1 was not.
+ *
+ * **Ordering guarantee.** `workflows` is sorted by `(name, revision)` via
+ * {@link compareWorkflowManifests} — see that export's JSDoc for why the
+ * revision tiebreak can never actually fire through this builder.
+ * `activities` keys are inserted in alphabetical (codepoint) order, and
+ * signal/update/query keys inside each manifest's `contract` the same way.
+ * Workflow and activity names cannot be integer-like (the name grammar
+ * requires a leading letter or underscore), but signal/update/query names
+ * accept any string, so integer-like message names could theoretically be
+ * reordered by JS engines despite the explicit sort. Clients that want to
+ * protect themselves from future registry sources should still sort
+ * `Object.keys(...)` before presenting or diffing snapshot entries.
+ *
+ * The per-workflow entry/message/scoped-activity conversion this module
+ * folds into each manifest lives in `registry-workflow-manifest.ts` — see
+ * that module's doc for why it is a separate file.
  *
  * @module core/registry-snapshot
  */
 import type { ActivityMetadata } from './activity-registry.ts';
+import type { WorkflowRevisionManifest } from './contract/index.ts';
 import type { Engine } from './engine.ts';
-import { WeftError } from './weft-error.ts';
+import { RegistryWorkflowCountLimitError } from './registry-limits.ts';
+import { RegistrySchemaConversionError } from './registry-schema-conversion.ts';
+export { buildWorkflowManifestForType, RegistryManifestLimitError, type RegistryMessageEntry, type RegistryWorkflowEntry, } from './registry-workflow-manifest.ts';
+export { RegistrySchemaConversionError, RegistryWorkflowCountLimitError };
 /**
  * Current registry contract version. Future incompatible changes to the
  * snapshot shape must bump this number; the codegen CLI rejects unknown
  * versions with a clear upgrade message.
  */
-export declare const REGISTRY_VERSION = 1;
-/** Schema metadata reported for a statically registered workflow message. */
-export type RegistryMessageEntry = {
-    inputSchema?: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
-};
-/** Metadata reported per workflow in a registry snapshot. */
-export type RegistryWorkflowEntry = {
-    inputSchema?: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
-    description?: string;
-    tags?: ReadonlyArray<string>;
-    signals?: Record<string, RegistryMessageEntry>;
-    updates?: Record<string, RegistryMessageEntry>;
-    queries?: Record<string, RegistryMessageEntry>;
-};
+export declare const REGISTRY_VERSION = 2;
 /**
  * Metadata reported per activity in a registry snapshot.
  *
@@ -67,27 +71,46 @@ export type RegistryActivityEntry = {
 /**
  * Snapshot of every locally-registered workflow and activity, suitable for
  * serialization as the `GET /v1/registry` response body.
+ *
+ * `workflows` carries one {@link WorkflowRevisionManifest} per registered
+ * workflow, sorted by {@link compareWorkflowManifests}. `activeRevisions`
+ * points each workflow name at the `revision` of its currently active
+ * manifest in `workflows` — today that is always the manifest a consumer
+ * resolves, since the engine registers exactly one implementation per name;
+ * the pointer exists so a future multi-revision registry source does not
+ * require another wire-shape bump. `activities` is unchanged from v1: a
+ * flat `Record<name, entry>`, since activities are not versioned contracts.
  */
 export type RegistrySnapshot = {
-    registryVersion: 1;
-    workflows: Record<string, RegistryWorkflowEntry>;
+    registryVersion: typeof REGISTRY_VERSION;
+    /** ISO-8601 generation timestamp. Informational only — excluded from codegen input validation and any determinism/drift comparison. */
+    generatedAt: string;
+    workflows: readonly WorkflowRevisionManifest[];
+    activeRevisions: Readonly<Record<string, string>>;
     activities: Record<string, RegistryActivityEntry>;
 };
 /**
- * Thrown when a registered workflow or activity schema cannot be converted
- * to JSON Schema. Carries the offending entity name and direction so
- * server-side observability (logs and telemetry) and non-HTTP callers
- * (the in-process MCP builder, programmatic users of `buildRegistrySnapshot`)
- * can identify which registration is broken. The HTTP REST binding
- * deliberately masks this on the wire as a generic `500 / Internal server
- * error` so a misbehaving registration cannot leak schema layout to clients
- * that only have `system:read`.
+ * Order two workflow revision manifests by `(name, revision)`. `workflows`
+ * is sorted with this comparator so registry output is deterministic
+ * regardless of registration order.
+ *
+ * The `revision` tiebreak can never actually fire through
+ * {@link buildRegistrySnapshot}: the engine registers at most one
+ * implementation per workflow name, so `name` alone is already unique
+ * within one snapshot. It exists, and is exported, so a future
+ * multi-revision registry source (or this function in isolation) has a
+ * total order to rely on, and so the tiebreak itself has direct unit-test
+ * coverage independent of engine registration uniqueness.
  */
-export declare class RegistrySchemaConversionError extends WeftError<'RegistrySchemaConversionError'> {
-    readonly entityKind: 'workflow' | 'activity';
-    readonly entityName: string;
-    readonly direction: 'inputSchema' | 'outputSchema';
-    constructor(entityKind: 'workflow' | 'activity', entityName: string, direction: 'inputSchema' | 'outputSchema', cause: unknown);
+export declare function compareWorkflowManifests(a: Pick<WorkflowRevisionManifest, 'name' | 'revision'>, b: Pick<WorkflowRevisionManifest, 'name' | 'revision'>): number;
+/** Options accepted by {@link buildRegistrySnapshot}. */
+export interface BuildRegistrySnapshotOptions {
+    /**
+     * Clock used for `generatedAt`. Defaults to `Date.now`; exists solely so
+     * tests can pin `generatedAt` for exact-equality assertions. Production
+     * call sites never pass this.
+     */
+    now?: () => number;
 }
 /**
  * Build a registry snapshot from an engine's locally-registered workflows
@@ -95,7 +118,33 @@ export declare class RegistrySchemaConversionError extends WeftError<'RegistrySc
  * worker but never registered with the local engine) are excluded by
  * construction — `engine.listActivityDefinitions()` is the only source.
  *
+ * `engine.listWorkflowDefinitions()`/`listActivityDefinitions()` are read
+ * synchronously in one eager pass before any `await`, so a workflow
+ * registered concurrently mid-build simply does not appear in that call's
+ * snapshot — the same eventual-consistency behavior v1's fully-synchronous
+ * builder had. No torn or partial manifest is possible.
+ *
  * Throws {@link RegistrySchemaConversionError} if any registered schema
- * fails JSON Schema conversion.
+ * fails JSON Schema conversion, {@link RegistryManifestLimitError} if a
+ * registered workflow's contract exceeds a WFT-5 hostile-input limit, or
+ * {@link RegistryWorkflowCountLimitError} if the engine has more than
+ * {@link MAX_REGISTRY_WORKFLOW_COUNT} workflows registered in total —
+ * checked here, at the producer, so `weft codegen --server`'s matching
+ * consumer-side ceiling in `cli/codegen-validate.ts` can never reject a
+ * `GET /v1/registry` response this function actually emits. A caller that
+ * wants only one or a few workflows' manifests — never the full snapshot,
+ * so neither limit above is the right contract — should use
+ * `buildWorkflowManifestForType` (`registry-workflow-manifest.ts`) instead;
+ * it is what this function itself calls per workflow.
+ */
+export declare function buildRegistrySnapshot(engine: Engine, options?: BuildRegistrySnapshotOptions): Promise<RegistrySnapshot>;
+/**
+ * Convert one activity's catalog metadata to its `RegistryActivityEntry`
+ * projection (schema pair plus queue/description/retry/timeout). Exported
+ * so build tooling that resolves a single activity outside a full
+ * {@link buildRegistrySnapshot} pass — see
+ * `worker/manifest/registry-contract-builder.ts`'s workflow-scoped-first
+ * activity resolution — can reuse the same conversion rather than
+ * reimplementing it.
  */
-export declare function buildRegistrySnapshot(engine: Engine): RegistrySnapshot;
+export declare function buildActivityEntry(metadata: ActivityMetadata): RegistryActivityEntry;

package/dist/core/registry-snapshot.js

@@ -1,81 +1,50 @@
-import { definitionSchemaToJsonSchema } from "./types/definition-schema-to-json.js";
-import { WeftError } from "./weft-error.js";
-export const REGISTRY_VERSION = 1;
-
-export class RegistrySchemaConversionError extends WeftError {
-  entityKind;
-  entityName;
-  direction;
-  constructor(entityKind, entityName, direction, cause) {
-    const causeMessage = cause instanceof Error ? cause.message : String(cause);
-    super("RegistrySchemaConversionError", `Failed to convert ${direction} for ${entityKind} "${entityName}": ${causeMessage}`, { cause });
-    this.entityKind = entityKind;
-    this.entityName = entityName;
-    this.direction = direction;
-  }
+import { compareCodepoint } from "./compare-codepoint.js";
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./engine/catalog-readiness.js";
+import { MAX_REGISTRY_WORKFLOW_COUNT, RegistryWorkflowCountLimitError } from "./registry-limits.js";
+import { convertSchema, RegistrySchemaConversionError } from "./registry-schema-conversion.js";
+import { buildOneWorkflowManifest } from "./registry-workflow-manifest.js";
+export {
+  buildWorkflowManifestForType,
+  RegistryManifestLimitError
+} from "./registry-workflow-manifest.js";
+export { RegistrySchemaConversionError, RegistryWorkflowCountLimitError };
+export const REGISTRY_VERSION = 2;
+export function compareWorkflowManifests(a, b) {
+  if (a.name < b.name)
+    return -1;
+  if (a.name > b.name)
+    return 1;
+  if (a.revision < b.revision)
+    return -1;
+  if (a.revision > b.revision)
+    return 1;
+  return 0;
 }
-export function buildRegistrySnapshot(engine) {
-  const workflowDefinitions = engine.listWorkflowDefinitions(), activityDefinitions = engine.listActivityDefinitions(), sortedWorkflows = workflowDefinitions.toSorted((a, b) => {
-    if (a.type < b.type)
-      return -1;
-    if (a.type > b.type)
-      return 1;
-    return 0;
-  }), sortedActivities = activityDefinitions.toSorted((a, b) => {
-    if (a.name < b.name)
-      return -1;
-    if (a.name > b.name)
-      return 1;
-    return 0;
-  }), workflows = Object.create(null);
-  for (const definition of sortedWorkflows)
-    workflows[definition.type] = buildWorkflowEntry(definition);
-  const activities = Object.create(null);
+export async function buildRegistrySnapshot(engine, options) {
+  await ensureWorkflowCatalogReady(engine);
+  const workflowDefinitions = engine.listWorkflowDefinitions();
+  if (workflowDefinitions.length > MAX_REGISTRY_WORKFLOW_COUNT)
+    throw new RegistryWorkflowCountLimitError(workflowDefinitions.length);
+  const activityDefinitions = engine.listActivityDefinitions(), sortedWorkflows = workflowDefinitions.toSorted((a, b) => compareCodepoint(a.type, b.type)), sortedActivities = activityDefinitions.toSorted((a, b) => compareCodepoint(a.name, b.name)), manifests = await Promise.all(sortedWorkflows.map((definition) => buildOneWorkflowManifest(engine, definition))), catalog = getWorkflowCatalog(engine), activeRevisions = Object.create(null);
+  for (const manifest of manifests) {
+    const activePointer = catalog.resolveActive(manifest.name);
+    if (activePointer === void 0)
+      throw Error(`Registry snapshot invariant violated: workflow "${manifest.name}" has no active workflow ` + "catalog pointer. This is a Weft bug \u2014 engine.register() always installs and activates on " + "registration, and ensureWorkflowCatalogReady() is awaited before this point.");
+    activeRevisions[manifest.name] = activePointer.revision;
+  }
+  const sortedManifests = manifests.toSorted(compareWorkflowManifests), activities = Object.create(null);
   for (const metadata of sortedActivities)
     activities[metadata.name] = buildActivityEntry(metadata);
+  const now = options?.now ?? Date.now;
   return {
     registryVersion: REGISTRY_VERSION,
-    workflows,
+    generatedAt: new Date(now()).toISOString(),
+    workflows: sortedManifests,
+    activeRevisions,
     activities
   };
 }
-function buildWorkflowEntry(definition) {
-  const entry = {};
-  if (definition.inputSchema !== void 0)
-    entry.inputSchema = convertSchema("workflow", definition.type, "inputSchema", definition.inputSchema);
-  if (definition.outputSchema !== void 0)
-    entry.outputSchema = convertSchema("workflow", definition.type, "outputSchema", definition.outputSchema);
-  if (definition.description !== void 0)
-    entry.description = definition.description;
-  if (definition.tags.length > 0)
-    entry.tags = [...definition.tags];
-  addWorkflowMessageEntries(entry, definition);
-  return entry;
-}
-function addWorkflowMessageEntries(entry, definition) {
-  if (definition.signals !== void 0 && Object.keys(definition.signals).length > 0)
-    entry.signals = buildMessageEntries(definition.type, "signal", definition.signals);
-  if (definition.updates !== void 0 && Object.keys(definition.updates).length > 0)
-    entry.updates = buildMessageEntries(definition.type, "update", definition.updates);
-  if (definition.queries !== void 0 && Object.keys(definition.queries).length > 0)
-    entry.queries = buildMessageEntries(definition.type, "query", definition.queries);
-}
-function buildMessageEntries(workflowType, messageKind, definitions) {
-  const entries = Object.create(null);
-  for (const name of Object.keys(definitions).toSorted()) {
-    const definition = definitions[name];
-    if (definition === void 0)
-      continue;
-    const entry = {}, entityName = `${workflowType}.${messageKind}.${name}`;
-    if (definition.inputSchema !== void 0)
-      entry.inputSchema = convertSchema("workflow", entityName, "inputSchema", definition.inputSchema);
-    if (definition.outputSchema !== void 0)
-      entry.outputSchema = convertSchema("workflow", entityName, "outputSchema", definition.outputSchema);
-    entries[name] = entry;
-  }
-  return entries;
-}
-function buildActivityEntry(metadata) {
+export function buildActivityEntry(metadata) {
   const entry = { queue: metadata.queue };
   if (metadata.inputSchema !== void 0)
     entry.inputSchema = convertSchema("activity", metadata.name, "inputSchema", metadata.inputSchema);
@@ -89,10 +58,3 @@ function buildActivityEntry(metadata) {
     entry.timeout = metadata.timeout;
   return entry;
 }
-function convertSchema(entityKind, entityName, field, schema) {
-  try {
-    return definitionSchemaToJsonSchema(schema, field === "inputSchema" ? "input" : "output");
-  } catch (cause) {
-    throw new RegistrySchemaConversionError(entityKind, entityName, field, cause);
-  }
-}