@lostgradient/weft 0.23.0 → 0.24.0

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current release: `0.23.0`.
+A Bun-native durable execution engine. Current release: `0.24.0`.
 
 Install the library from npm as `@lostgradient/weft`:
 
@@ -253,6 +253,74 @@ For stable-id re-sync flows, `engine.startOrSignal()` can replace a terminal pri
 
 When a workflow drains signals with `ctx.race([ctx.waitForSignal(name), ctx.sleep(0)])` and then returns, use that stable `id`, a deterministic per-event `signalId`, and `onTerminalConflict: 'start-new'` for the corresponding `startOrSignal` calls. Delivery is serialized against terminal completion, so a signal arriving across the completion boundary is consumed by the current run or handed to its successor; a positive drain window is not needed for correctness.
 
+### Durable Application Command Mailbox
+
+Signals are workflow control. When the thing receiving a command is an application _resource_ rather than a workflow run — an agent taking steering input, a resource fielding requests from a peer service — `Mailbox` gives it a durable, strictly FIFO command queue with real receipts.
+
+```typescript
+import { Mailbox, MemoryStorage } from '@lostgradient/weft';
+
+await using storage = new MemoryStorage();
+using mailbox = new Mailbox({ storage, namespace: 'bureau', resourceId: 'agent-7' });
+
+const admission = await mailbox.admit({
+  caller: 'user:42',
+  target: 'agent:7',
+  kind: 'steer',
+  payload: { form: 'inline', value: { text: 'stop and summarize' } },
+  idempotencyKey: 'steer-1',
+});
+
+const claimed = await mailbox.claim();
+if (claimed.status === 'claimed' && admission.status === 'admitted') {
+  await mailbox.acknowledge({
+    commandId: claimed.claim.receipt.commandId,
+    attemptToken: claimed.claim.attemptToken,
+    outcome: { applied: true },
+  });
+}
+```
+
+Admission returns a receipt that, on a persistent backend such as `BunSQLiteStorage`, survives process restart; `MemoryStorage` above keeps the example self-contained and is gone with the process. Idempotency binds to `(caller, target, kind, payloadDigest)`, so an exact retry returns the original receipt and a conflicting reuse of the key returns a stable conflict without touching the original. Claims are attempt-fenced, so two consumers sharing one durable store can never both hold a valid claim _on the same command_ — delivery is strictly FIFO, but a later command may be claimed while an earlier one is still in flight, so completion order is up to the consumers. Cancellation is durable before it reaches anyone, and reports honestly whether cleanup is still outstanding rather than claiming an uncooperative handler stopped.
+
+Delivery intent, ordering, ownership, and disposition are durable; external side effects are not made exactly-once. See [Application Mailbox](documentation/guides/mailbox.md).
+
+### Durable Application Delivery Outbox
+
+The mailbox is for commands coming _in_ to a resource. For work going _out_ — a webhook, a notification, a message to a peer service — `Outbox` is the matching primitive: a durable, at-least-once delivery queue whose enqueue, attempt leases, transport outcomes, retry schedule, cancellation, and dead-letter state are all durable and observable, without ever confusing a transport write with an acknowledgement.
+
+```typescript
+import { Outbox, MemoryStorage } from '@lostgradient/weft';
+
+await using storage = new MemoryStorage();
+using outbox = new Outbox({
+  storage,
+  namespace: 'bureau',
+  ownerId: 'agent-7',
+  adapter: {
+    async send(request) {
+      // Put the request on the wire. Present request.delivery.externalIdempotencyKey
+      // as the remote idempotency key when the delivery carries one; the attempt
+      // token changes per attempt and is only a request id or fence.
+      void request;
+      return { status: 'acknowledged', evidence: { messageId: 'm-1' } };
+    },
+  },
+});
+
+await outbox.enqueue({
+  destinationRef: 'webhook:orders',
+  kind: 'order.shipped',
+  payload: { form: 'inline', value: { orderId: 42 } },
+  idempotencyKey: 'order-42-shipped',
+});
+
+const delivered = await outbox.deliverNext();
+if (delivered.status === 'settled') console.log(delivered.receipt.state); // 'acknowledged'
+```
+
+Every attempt is durably marked `attempting` _before_ the adapter is called, so a crash before the send is a safe retry and a crash after it is an unknown outcome — which is parked or dead-lettered by explicit policy, and retried automatically only when the delivery carries stable external idempotency evidence. Returning from `send()` never settles anything by itself; the outbox commits the matching disposition, fenced on the attempt. See [Application Outbox](documentation/guides/outbox.md).
+
 ### Search Attributes
 
 Attach indexed metadata to a workflow at runtime, then list and filter on it.
@@ -335,7 +403,7 @@ A small `Storage` interface over string keys and `Uint8Array` values: five requi
 - **`SQLiteStorage`** (subpath `@lostgradient/weft/storage/sqlite`) for SQLite persistence; Bun resolves to `BunSQLiteStorage`, Node resolves to `NodeSQLiteStorage`
 - **`BunSQLiteStorage`** (subpath `@lostgradient/weft/storage/sqlite/bun`) for an explicit Bun SQLite override
 - **`NodeSQLiteStorage`** (subpath `@lostgradient/weft/storage/sqlite/node`) for an explicit Node.js SQLite override via `better-sqlite3`
-- **`LMDBStorage`** (subpath `@lostgradient/weft/storage/lmdb`) for embedded high-throughput workloads
+- **`LMDBStorage`** (subpath `@lostgradient/weft/storage/lmdb`) for embedded high-throughput workloads; accepts a `durability: 'relaxed'` option that skips `fsync` on every commit, trading crash durability for write latency—use it for test fixtures, not production storage. `capabilities().persistence` reports `'ephemeral'` for a relaxed-durability instance (instead of `'local'`), so `assertDurableStorageForRecovery()` correctly rejects it
 - **`TursoStorage`** (subpath `@lostgradient/weft/storage/turso`) for distributed libSQL deployments
 - **`NeonStorage`** (subpath `@lostgradient/weft/storage/neon`) for durable remote Neon/Postgres deployments
 - **`IndexedDBStorage`** (subpath `@lostgradient/weft/storage/indexeddb`) for browser environments
@@ -367,7 +435,7 @@ await using server = serve({ engine, port: 7233 });
 // server.url is e.g. "http://0.0.0.0:7233"
 ```
 
-Endpoints under `/api/v1/` cover the full lifecycle: start workflows, list, signal, update, query, cancel, fork, and stream events. JSON-RPC over WebSocket also exposes workflow and fleet event subscriptions for operator UIs that need live state without polling. Content negotiation supports JSON and MessagePack. The server can also mount an externally supplied dashboard shell at known page routes; see the [server guide](documentation/guides/server.md#external-dashboard-mounting) for the hosting contract.
+Endpoints under `/api/v1/` cover the full lifecycle: start workflows, list, signal, update, query, cancel, fork, and stream events. JSON-RPC over WebSocket also exposes workflow and fleet event subscriptions for operator UIs that need live state without polling. Content negotiation supports JSON and MessagePack. `engine.workflows` and the matching `/v1/registry/` operations expose the durable workflow catalog for admin tooling — install a revision's manifest and activate it as the advertised active revision — bookkeeping only, never workflow execution routing; see [`workflow-versioning.md`](documentation/guides/workflow-versioning.md#engineworkflows-public-catalog-control). `workflowSource()` pairs a typed, serializable source descriptor with a never-serialized loader capability, so one workflow can register lazily while another stays eagerly registered; `engine.registerSource()` records the candidate without importing it, and `engine.resolveWorkflowSource()` loads, validates, and installs it into the same catalog with single-flight deduplication per `(name, revision)`; see [Dynamic Workflow Sources](documentation/guides/workflow-versioning.md#dynamic-workflow-sources). The server can also mount an externally supplied dashboard shell at known page routes; see the [server guide](documentation/guides/server.md#external-dashboard-mounting) for the hosting contract.
 
 ### Remote Workers
 
@@ -565,7 +633,7 @@ Guides:
 - [Durable Timers](documentation/guides/durable-timers.md), [Timeouts](documentation/guides/timeouts.md), [Parallel Execution](documentation/guides/parallel-execution.md)
 - [Search Attributes](documentation/guides/search-attributes.md), [Workflow Visibility Backfill](documentation/guides/workflow-visibility-backfill.md), [State](documentation/guides/state.md), [Session State](documentation/guides/session-state.md), [Events](documentation/guides/events.md)
 - [Interceptors](documentation/guides/interceptors.md), [Observability](documentation/guides/observability.md), [Testing](documentation/guides/testing.md)
-- [Workflow Versioning](documentation/guides/workflow-versioning.md), [Remote Workers](documentation/guides/remote-workers.md), [Service Worker](documentation/guides/service-worker.md), [Resource Management](documentation/guides/resource-management.md), [Concurrency: Mutex and Semaphore](documentation/guides/concurrency.md)
+- [Workflow Versioning](documentation/guides/workflow-versioning.md), [Remote Workers](documentation/guides/remote-workers.md), [Service Worker](documentation/guides/service-worker.md), [Resource Management](documentation/guides/resource-management.md), [Concurrency: Mutex and Semaphore](documentation/guides/concurrency.md), [Application Mailbox](documentation/guides/mailbox.md), [Application Outbox](documentation/guides/outbox.md)
 
 Architecture and reference:
 

package/dist/cli/codegen-emit-dedup.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Schema-deduplication for `weft codegen`'s generated `.d.ts`.
+ *
+ * `codegen-emit-registry.ts` walks every active workflow's `inputSchema`/
+ * `outputSchema` in a fixed, deterministic order (workflows sorted by name,
+ * then input before output) and hands this module the resulting sequence of
+ * {@link SchemaFragmentOccurrence}s — each fragment's independently-emitted
+ * TypeScript text (`jsonSchemaToTypeScript`). {@link buildSchemaAliasTable}
+ * groups those by that emitted text and decides, for each group, whether the
+ * repeated type is worth hoisting into a single shared `type` alias
+ * referenced from every entry that uses it, rather than repeating the same
+ * TypeScript text inline at every call site.
+ *
+ * Grouping by the emitted TypeScript text itself — not by a normalization of
+ * the source JSON Schema — is deliberate: two JSON Schema fragments that
+ * differ only in an order-insensitive construct (`required: ['a', 'b']` vs
+ * `required: ['b', 'a']`; `properties` key order) render to byte-identical
+ * TypeScript through `jsonSchemaToTypeScript` (which sorts object keys), so
+ * grouping by a JSON-level canonical key would miss deduplicating them even
+ * though they are exactly the same type a consumer would want aliased
+ * together. Grouping by the rendered text instead means "these occurrences
+ * produce the same alias" and "these occurrences are the same TypeScript
+ * type" are the same question, answered once, so there is no JSON-vs-text
+ * disagreement to reconcile: any two occurrences landing in the same group
+ * are equal by construction (`Map` keys are compared by value), not merely
+ * expected to agree.
+ *
+ * A schema only qualifies for hoisting when it recurs (count >= 2) and the
+ * emitted type is not trivial — hoisting `unknown` or `string` behind an
+ * opaque alias name would only make the generated file harder to read for
+ * zero benefit, and would trivially "dedupe" every schema-less workflow
+ * (`inputSchema` undefined → emitted type `unknown`) into a shared alias the
+ * moment two workflows both lack an input schema, which is the common case,
+ * not an edge case.
+ *
+ * @module cli/codegen-emit-dedup
+ */
+export { CodegenEmitError } from './codegen-emit-keywords.ts';
+/** One schema fragment's independently-emitted TypeScript text. */
+export type SchemaFragmentOccurrence = {
+    tsType: string;
+};
+/** A hoisted schema's alias name and the TypeScript type it aliases. */
+export type SchemaAliasEntry = {
+    alias: string;
+    tsType: string;
+};
+/**
+ * Emitted TypeScript type expressions that are never worth hoisting behind
+ * an alias, no matter how many times they recur: bare primitives and the
+ * handful of compound "no meaningful shape" forms `jsonSchemaToTypeScript`
+ * produces for an absent, empty, or fully-open/closed schema.
+ */
+export declare const TRIVIAL_TYPESCRIPT_TYPES: ReadonlySet<string>;
+/** Options for {@link buildSchemaAliasTable}, injectable for deterministic testing. */
+export type BuildSchemaAliasTableOptions = {
+    /** Alias-name hash function. Defaults to {@link hashString} (FNV-1a). */
+    hash?: (key: string) => string;
+};
+/** Prefix for every generated schema alias name — distinctive and double-underscored so it never collides with a real consumer type name. */
+export declare const ALIAS_PREFIX = "__WeftSchema_";
+/**
+ * Group a fixed, deterministically-ordered sequence of schema occurrences
+ * by their emitted TypeScript text and decide which recurring, non-trivial
+ * types should be hoisted into a shared `type` alias.
+ *
+ * Returns a map keyed by `tsType` (not by alias) so a caller emitting one
+ * workflow entry's `input`/`output` field can look up "does this schema's
+ * emitted type have a hoisted alias?" directly, without a second reverse
+ * index — the caller computes the same `jsonSchemaToTypeScript` text it
+ * would otherwise emit inline, and either finds an alias or emits that text.
+ *
+ * Alias names are deterministic: `ALIAS_PREFIX` plus a hash of the emitted
+ * type text (FNV-1a via {@link hashString} by default, injectable via
+ * `options.hash` for testing). A real hash collision between two different
+ * emitted types is astronomically unlikely but not impossible, so it is
+ * checked and throws {@link CodegenEmitError} rather than silently letting
+ * one type's alias declaration shadow another's — `codegen.ts` already
+ * converts that error to `exitCode: 1`.
+ */
+export declare function buildSchemaAliasTable(occurrences: readonly SchemaFragmentOccurrence[], options?: BuildSchemaAliasTableOptions): ReadonlyMap<string, SchemaAliasEntry>;

package/dist/cli/codegen-emit-dedup.js

@@ -0,0 +1,45 @@
+import { hashString } from "../runtime/portable.js";
+import { CodegenEmitError } from "./codegen-emit-keywords.js";
+export { CodegenEmitError } from "./codegen-emit-keywords.js";
+export const TRIVIAL_TYPESCRIPT_TYPES = new Set([
+  "string",
+  "number",
+  "boolean",
+  "null",
+  "unknown",
+  "never",
+  "Record<string, never>",
+  "Record<string, unknown>",
+  "Array<unknown>"
+]);
+const LITERAL_TOKEN_PATTERN = /^(-?[0-9]+(\.[0-9]+)?|true|false|null|"([^"\\]|\\.)*")$/;
+function isTrivialTsType(tsType) {
+  return TRIVIAL_TYPESCRIPT_TYPES.has(tsType) || LITERAL_TOKEN_PATTERN.test(tsType);
+}
+export const ALIAS_PREFIX = "__WeftSchema_";
+function groupOccurrences(occurrences) {
+  const groups = new Map;
+  occurrences.forEach((occurrence, index) => {
+    const existing = groups.get(occurrence.tsType);
+    if (existing === void 0)
+      groups.set(occurrence.tsType, { count: 1, firstIndex: index });
+    else
+      existing.count += 1;
+  });
+  return groups;
+}
+export function buildSchemaAliasTable(occurrences, options) {
+  const hash = options?.hash ?? hashString, groups = groupOccurrences(occurrences), orderedTypes = [...groups.keys()].toSorted((a, b) => groups.get(a).firstIndex - groups.get(b).firstIndex), aliasOwners = new Map, table = new Map;
+  for (const tsType of orderedTypes) {
+    if (groups.get(tsType).count < 2)
+      continue;
+    if (isTrivialTsType(tsType))
+      continue;
+    const alias = `${ALIAS_PREFIX}${hash(tsType)}`, owner = aliasOwners.get(alias);
+    if (owner !== void 0 && owner !== tsType)
+      throw new CodegenEmitError(`codegen: schema alias collision: emitted-type hashes ${JSON.stringify(hash(owner))} and ${JSON.stringify(hash(tsType))} both resolved to alias "${alias}"`);
+    aliasOwners.set(alias, tsType);
+    table.set(tsType, { alias, tsType });
+  }
+  return table;
+}

package/dist/cli/codegen-emit-registry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `.d.ts` assembly for `weft codegen`'s active-workflow projection.
+ *
+ * Consumes the active workflow projection of a registry snapshot
+ * (`Record<name, CodegenWorkflowEntry>`, projected from its v2 manifest
+ * array by `codegen-validate.ts`'s `resolveActiveWorkflowEntries`) and
+ * produces a single `.d.ts` string that augments the public
+ * `'@lostgradient/weft'` module with typed `WorkflowRegistry` entries. The
+ * output is byte-stable across runs with the same input: keys are sorted
+ * with explicit codepoint comparators, property names and string-literal
+ * values are uniformly double-quoted via `emitStringLiteral`, and there are
+ * no timestamps or environment-dependent paths.
+ *
+ * The augmented `WorkflowRegistry` interface is the single source of truth
+ * for per-workflow input/output typing across the whole public surface:
+ * `engine.start`, `WorkflowHandle.result()`, AND the client
+ * (`WeftClient.start`/`schedule` and `ClientHandle.result()`). The client
+ * overloads key off this interface, so emitting one declaration narrows
+ * both engine and client call sites — there is no separate client-specific
+ * emission, and skipping codegen leaves both usable with plain string
+ * names. Every entry also carries `revision`/`workflowVersion` as
+ * string-literal fields for compile-time introspection; neither is
+ * required by `engine.start`/`WeftClient.start`/`.schedule()`, which read
+ * only `input`/`output` structurally (`WorkflowInput`/`WorkflowOutput` in
+ * `core/types/workflow-registries.ts`) — an ordinary start needs no
+ * caller-supplied revision.
+ *
+ * Activity names are no longer emitted as a global `ActivityTypes` module
+ * augmentation — that interface was removed when the chained workflow
+ * builder made activity names a per-workflow concern (typed at the
+ * builder's `.activities({...})` step). The snapshot still carries
+ * activity schemas because the same registry feeds discovery and MCP
+ * tooling, but the emitter intentionally drops them from the generated
+ * `.d.ts`.
+ *
+ * When two or more workflow entries' `inputSchema`/`outputSchema` render to
+ * the same non-trivial TypeScript text (see `codegen-emit-dedup.ts` — grouped
+ * by the emitted text itself, not by a JSON-level normalization of the
+ * source schema, so schemas differing only in an order-insensitive JSON
+ * construct like `required` array order still dedupe correctly), that text
+ * is hoisted into a single, unexported, file-top-level
+ * `type __WeftSchema_<hash> = <TS type>;` alias declared BEFORE
+ * `declare module '@lostgradient/weft' { ... }` — never inside it.
+ * Placing an alias inside the augmentation block would make it a
+ * pseudo-public exported type name of `@lostgradient/weft` (autocomplete
+ * pollution for every consumer), and because TypeScript `type` aliases
+ * don't structurally merge the way `interface` does, two independently
+ * generated `.d.ts` files declaring the same content-derived alias name
+ * inside the same augmented interface would collide with a real
+ * "Duplicate identifier" compile error the moment both landed in one
+ * TypeScript program. File-scoped placement avoids both problems.
+ *
+ * @module cli/codegen-emit-registry
+ */
+export { CodegenEmitError } from './codegen-emit-keywords.ts';
+/**
+ * One active workflow's codegen-relevant metadata: its input/output
+ * schemas plus the `revision`/`workflowVersion` identity fields every
+ * generated entry now carries. Deliberately narrower than, and separate
+ * from, `core/registry-workflow-manifest.ts`'s `RegistryWorkflowEntry` —
+ * that type also describes the full registration-time shape fed into
+ * `buildWorkflowRevisionManifest` itself (which doesn't yet have a
+ * `revision` to attach — a manifest can't carry the revision of the
+ * manifest used to build it), so widening it here would be circular.
+ * `description`/`tags` are carried through for parity with the source
+ * manifest and future codegen features, but this batch does not emit them
+ * into the `.d.ts` (see the module's `openQuestions` in its planning
+ * record — emitting free-text description as a JSDoc comment reopens the
+ * same injection-safety surface WFT-5 closed for the contract module, and
+ * is out of scope here).
+ */
+export type CodegenWorkflowEntry = {
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    description?: string;
+    tags?: ReadonlyArray<string>;
+    revision: string;
+    workflowVersion: string;
+};
+/**
+ * Emit the full `.d.ts` declaration string for a registry's active workflow
+ * projection.
+ *
+ * The output is deterministic: keys are sorted by codepoint, property
+ * names and string-literal values go through {@link emitPropertyKey}/
+ * {@link emitStringLiteral}, unions/intersections are always parenthesized
+ * so they compose correctly when nested, and hoisted schema aliases are
+ * sorted by alias name.
+ */
+export declare function emitRegistryDeclaration(activeWorkflows: Record<string, CodegenWorkflowEntry>): string;

package/dist/cli/codegen-emit-registry.js

@@ -0,0 +1,50 @@
+import { compareCodepoint } from "../core/compare-codepoint.js";
+import {
+  buildSchemaAliasTable
+} from "./codegen-emit-dedup.js";
+import { emitPropertyKey, emitStringLiteral, jsonSchemaToTypeScript } from "./codegen-emit.js";
+export { CodegenEmitError } from "./codegen-emit-keywords.js";
+const WEFT_PACKAGE_NAME = "@lostgradient/weft";
+function sortedWorkflowEntries(workflows) {
+  return Object.entries(workflows).toSorted(([a], [b]) => compareCodepoint(a, b));
+}
+function collectSchemaOccurrences(workflows) {
+  const occurrences = [], workflowsWithTypes = [];
+  for (const [name, entry] of workflows) {
+    const inputType = jsonSchemaToTypeScript(entry.inputSchema), outputType = jsonSchemaToTypeScript(entry.outputSchema);
+    occurrences.push({ tsType: inputType }, { tsType: outputType });
+    workflowsWithTypes.push({ name, entry, inputType, outputType });
+  }
+  return { occurrences, workflowsWithTypes };
+}
+function schemaTypeReference(tsType, aliasTable) {
+  const aliasEntry = aliasTable.get(tsType);
+  return aliasEntry !== void 0 ? aliasEntry.alias : tsType;
+}
+function emitWorkflowEntry(workflow, aliasTable) {
+  const { name, entry, inputType, outputType } = workflow, input = schemaTypeReference(inputType, aliasTable), output = schemaTypeReference(outputType, aliasTable), revision = emitStringLiteral(entry.revision), workflowVersion = emitStringLiteral(entry.workflowVersion);
+  return `    ${emitPropertyKey(name)}: { input: ${input}; output: ${output}; revision: ${revision}; workflowVersion: ${workflowVersion} };`;
+}
+function emitAliasDeclarations(aliasTable) {
+  return [...aliasTable.values()].toSorted((a, b) => compareCodepoint(a.alias, b.alias)).map((entry) => `type ${entry.alias} = ${entry.tsType};`);
+}
+export function emitRegistryDeclaration(activeWorkflows) {
+  const workflows = sortedWorkflowEntries(activeWorkflows), { occurrences, workflowsWithTypes } = collectSchemaOccurrences(workflows), aliasTable = buildSchemaAliasTable(occurrences), aliasLines = emitAliasDeclarations(aliasTable), workflowLines = workflowsWithTypes.map((workflow) => emitWorkflowEntry(workflow, aliasTable)), workflowBlock = workflowLines.length === 0 ? "  interface WorkflowRegistry {}" : ["  interface WorkflowRegistry {", ...workflowLines, "  }"].join(`
+`);
+  return [
+    "// Generated by `weft codegen`. Do not edit by hand.",
+    "// Augments `WorkflowRegistry` to type engine and client call sites",
+    "// (start/schedule input and handle.result() output) per workflow.",
+    "/* eslint-disable */",
+    "",
+    ...aliasLines,
+    ...aliasLines.length > 0 ? [""] : [],
+    `declare module '${WEFT_PACKAGE_NAME}' {`,
+    workflowBlock,
+    "}",
+    "",
+    "export {};",
+    ""
+  ].join(`
+`);
+}

package/dist/cli/codegen-emit.d.ts

@@ -1,50 +1,37 @@
 /**
- * Deterministic JSON-Schema → TypeScript emitter for `weft codegen`.
+ * Deterministic JSON-Schema → TypeScript expression converter for
+ * `weft codegen`.
  *
- * Consumes a {@link RegistrySnapshot} (the same shape served by
- * `GET /v1/registry`) and produces a single `.d.ts` string that
- * augments the public `'@lostgradient/weft'` module with typed `WorkflowRegistry`
- * entries. The output is byte-stable across runs with the same input:
- * keys are sorted with explicit codepoint comparators, property names
- * are uniformly double-quoted via `JSON.stringify`, and there are no
- * timestamps or environment-dependent paths.
+ * Converts a single JSON Schema fragment ({@link jsonSchemaToTypeScript})
+ * into a TypeScript type expression, and emits a safely-quoted TypeScript
+ * string literal or property key ({@link emitStringLiteral},
+ * {@link emitPropertyKey}). The JSON Schema subset supported here covers
+ * what `definitionSchemaToJsonSchema` actually produces today (Zod via
+ * `z.toJSONSchema` and Valibot via `@valibot/to-json-schema`). Anything
+ * outside that subset degrades to `unknown` so the converter never claims
+ * a type it cannot justify.
  *
- * The augmented `WorkflowRegistry` interface is the single source of
- * truth for per-workflow input/output typing across the whole public
- * surface: `engine.start`, `WorkflowHandle.result()`, AND the client
- * (`WeftClient.start`/`schedule` and `ClientHandle.result()`). The
- * client overloads key off this interface, so emitting one declaration
- * narrows both engine and client call sites — there is no separate
- * client-specific emission, and skipping codegen leaves both usable with
- * plain string names.
- *
- * Activity names are no longer emitted as a global `ActivityTypes`
- * module augmentation — that interface was removed when the chained
- * workflow builder made activity names a per-workflow concern (typed at
- * the builder's `.activities({...})` step). The snapshot still carries
- * activity schemas because the same registry feeds discovery and MCP tooling,
- * but the emitter intentionally drops them from the
- * generated `.d.ts`.
- *
- * The JSON Schema subset supported here covers what
- * `definitionSchemaToJsonSchema` actually produces today (Zod via
- * `z.toJSONSchema` and Valibot via `@valibot/to-json-schema`).
- * Anything outside that subset degrades to `unknown` so the emitter
- * never claims a type it cannot justify.
+ * `codegen-emit-registry.ts` is the module that actually assembles a full
+ * `.d.ts` file (the `WorkflowRegistry` module augmentation, revision/
+ * workflowVersion literals, and schema-alias hoisting) from these
+ * primitives — this module has no knowledge of the registry snapshot shape
+ * or the augmented module's structure, only of JSON Schema → TypeScript
+ * conversion.
  *
  * @module cli/codegen-emit
  */
-import type { RegistrySnapshot } from '../core/registry-snapshot.ts';
 export { CodegenEmitError } from './codegen-emit-keywords.ts';
+/**
+ * Emit a TypeScript string literal type for an arbitrary string value.
+ * Shared by {@link emitPropertyKey} (a literal used as a property key) and
+ * `codegen-emit-registry.ts`'s `revision`/`workflowVersion` emission (a
+ * literal used as a value type) — both need the same `JSON.stringify`
+ * safety property: quotes, backslashes, control characters, and any other
+ * hostile content are always safely embedded inside the double-quoted
+ * string, so neither call site can inject generated TypeScript.
+ */
+export declare function emitStringLiteral(value: string): string;
 /** Emit a TypeScript property key as a double-quoted string literal. */
 export declare function emitPropertyKey(name: string): string;
 /** Convert a single JSON Schema fragment to a TypeScript type expression. */
 export declare function jsonSchemaToTypeScript(schema: unknown): string;
-/**
- * Emit the full `.d.ts` declaration string for a registry snapshot.
- *
- * The output is deterministic: keys are sorted by codepoint, property
- * names go through {@link emitPropertyKey}, and unions/intersections
- * are always parenthesized so they compose correctly when nested.
- */
-export declare function emitRegistryDeclaration(snapshot: RegistrySnapshot): string;

package/dist/cli/codegen-emit.js

@@ -6,7 +6,6 @@ import {
   PRIMITIVE_SUPPORTED_KEYS
 } from "./codegen-emit-keywords.js";
 export { CodegenEmitError } from "./codegen-emit-keywords.js";
-const WEFT_PACKAGE_NAME = "@lostgradient/weft";
 function codepointCompare(a, b) {
   if (a < b)
     return -1;
@@ -14,8 +13,11 @@ function codepointCompare(a, b) {
     return 1;
   return 0;
 }
+export function emitStringLiteral(value) {
+  return JSON.stringify(value);
+}
 export function emitPropertyKey(name) {
-  return JSON.stringify(name);
+  return emitStringLiteral(name);
 }
 function primitiveTypeFor(typeKeyword) {
   switch (typeKeyword) {
@@ -253,28 +255,3 @@ function indexSignatureForObject(additionalRaw, namedValueTypes, hasOptionalName
   }
   return "unknown";
 }
-function sortedWorkflowEntries(workflows) {
-  return Object.entries(workflows).toSorted(([a], [b]) => codepointCompare(a, b));
-}
-function emitWorkflowEntry(name, entry) {
-  const input = jsonSchemaToTypeScript(entry.inputSchema), output = jsonSchemaToTypeScript(entry.outputSchema);
-  return `    ${emitPropertyKey(name)}: { input: ${input}; output: ${output} };`;
-}
-export function emitRegistryDeclaration(snapshot) {
-  const workflowLines = sortedWorkflowEntries(snapshot.workflows).map(([name, entry]) => emitWorkflowEntry(name, entry)), workflowBlock = workflowLines.length === 0 ? "  interface WorkflowRegistry {}" : ["  interface WorkflowRegistry {", ...workflowLines, "  }"].join(`
-`);
-  return [
-    "// Generated by `weft codegen`. Do not edit by hand.",
-    "// Augments `WorkflowRegistry` to type engine and client call sites",
-    "// (start/schedule input and handle.result() output) per workflow.",
-    "/* eslint-disable */",
-    "",
-    `declare module '${WEFT_PACKAGE_NAME}' {`,
-    workflowBlock,
-    "}",
-    "",
-    "export {};",
-    ""
-  ].join(`
-`);
-}

package/dist/cli/codegen-validate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Envelope and per-manifest validation for a `weft codegen` registry
+ * snapshot source (fetched from a live server or vendored as `--from`
+ * JSON).
+ *
+ * Split out of `codegen.ts` specifically to stay under the repository's
+ * implementation-file-size ceiling once WFT-6's manifest validation
+ * (reusing `core/contract`'s hostile-input `parseWorkflowRevisionManifest`)
+ * was added — `codegen.ts` was already 460 of 500 lines before this module
+ * existed.
+ *
+ * @module cli/codegen-validate
+ */
+import { type RegistryActivityEntry } from '../core/registry-snapshot.ts';
+import type { CodegenWorkflowEntry } from './codegen-emit-registry.ts';
+/**
+ * Ceiling on the raw `workflows` array's length, checked before a single
+ * element is parsed or cryptographically hashed, and on the number of
+ * entries in `activeRevisions`, checked before a single key/value pair is
+ * read (`activeRevisions` can never usefully point at more names than
+ * `workflows` could ever declare, so the same ceiling applies to both).
+ * Shared with `core/registry-snapshot.ts`'s producer-side enforcement via
+ * {@link MAX_REGISTRY_WORKFLOW_COUNT} rather than each defining its own
+ * number: a consumer ceiling looser than the producer's would be dead code,
+ * and one tighter would make `weft codegen --server` reject a
+ * legitimately-generated snapshot from a same-release server.
+ */
+export type ValidateSnapshotResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** The active workflow projection `weft codegen` emits from, plus the activity count for the CLI's summary line. */
+export interface ActiveRegistryProjection {
+    workflows: Record<string, CodegenWorkflowEntry>;
+    activities: Record<string, RegistryActivityEntry>;
+}
+/**
+ * Validate an untrusted registry snapshot end-to-end: the version/envelope
+ * shape, every `workflows` manifest, and the `activeRevisions` pointer map,
+ * projecting the result down to what `weft codegen` actually emits from.
+ *
+ * Surfaces a clear version-mismatch diagnostic before delegating to the
+ * full envelope schema, since the version check is the most likely failure
+ * when consumers vendor a snapshot from an older or newer server.
+ */
+export declare function validateRegistrySnapshot(value: unknown): Promise<ValidateSnapshotResult<ActiveRegistryProjection>>;