@lostgradient/weft 0.23.0 → 0.24.0

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

@@ -0,0 +1,21 @@
+/**
+ * Canonical, normalized workflow contract vocabulary — the single input to
+ * both TypeScript code generation and `contractHash()`, plus the typed
+ * `WorkflowRevisionManifest` and its hostile-input parser.
+ *
+ * @module core/contract
+ */
+export { MAX_CONTRACT_IDENTIFIER_BYTES, MAX_CONTRACT_MESSAGE_COUNT, MAX_CONTRACT_SCHEMA_DEPTH, MAX_NORMALIZED_CONTRACT_BYTES, } from './limits.ts';
+export { WORKFLOW_CONTRACT_VERSION, WORKFLOW_REVISION_MANIFEST_VERSION } from './types.ts';
+export type { WorkflowActivityContract, WorkflowContract, WorkflowContractActivitySource, WorkflowContractMessageSource, WorkflowContractSource, WorkflowMessageContract, WorkflowRevisionManifest, } from './types.ts';
+export { WorkflowContractConversionError, buildWorkflowContract } from './build.ts';
+export { canonicalWorkflowContractJson, normalizeWorkflowContract } from './normalize.ts';
+export { WORKFLOW_CONTRACT_DIGEST_ALGORITHM, activityContractHash, contractHash, digestCanonicalWorkflowContract, } from './hash.ts';
+export { deriveWorkflowRevision } from './revision.ts';
+export { buildWorkflowRevisionManifest } from './manifest.ts';
+export type { BuildWorkflowRevisionManifestOptions } from './manifest.ts';
+export type { WorkflowRevisionManifestRejectionReason, WorkflowRevisionManifestValidationFailure, } from './failure.ts';
+export { parseWorkflowRevisionManifest } from './manifest-parse.ts';
+export type { WorkflowRevisionManifestParseResult, WorkflowRevisionManifestParseSuccess, } from './manifest-parse.ts';
+export { DEFAULT_WORKFLOW_COMPATIBILITY_POLICY, checkWorkflowCompatibility, } from './compatibility.ts';
+export type { WorkflowCompatibilityPolicy, WorkflowCompatibilityReason, WorkflowCompatibilityVerdict, } from './compatibility.ts';

package/dist/core/contract/index.js

@@ -0,0 +1,22 @@
+export {
+  MAX_CONTRACT_IDENTIFIER_BYTES,
+  MAX_CONTRACT_MESSAGE_COUNT,
+  MAX_CONTRACT_SCHEMA_DEPTH,
+  MAX_NORMALIZED_CONTRACT_BYTES
+} from "./limits.js";
+export { WORKFLOW_CONTRACT_VERSION, WORKFLOW_REVISION_MANIFEST_VERSION } from "./types.js";
+export { WorkflowContractConversionError, buildWorkflowContract } from "./build.js";
+export { canonicalWorkflowContractJson, normalizeWorkflowContract } from "./normalize.js";
+export {
+  WORKFLOW_CONTRACT_DIGEST_ALGORITHM,
+  activityContractHash,
+  contractHash,
+  digestCanonicalWorkflowContract
+} from "./hash.js";
+export { deriveWorkflowRevision } from "./revision.js";
+export { buildWorkflowRevisionManifest } from "./manifest.js";
+export { parseWorkflowRevisionManifest } from "./manifest-parse.js";
+export {
+  DEFAULT_WORKFLOW_COMPATIBILITY_POLICY,
+  checkWorkflowCompatibility
+} from "./compatibility.js";

package/dist/core/contract/limits.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Semantic bounds applied to a workflow contract before it is normalized,
+ * hashed, or admitted as a {@link WorkflowRevisionManifest}.
+ *
+ * Sized analogously to `src/worker/manifest/limits.ts` — the same
+ * placement rationale applies: the type declarations, the hostile-input
+ * manifest parser, and the canonical serializer can all depend on these
+ * limits without forming an import cycle.
+ *
+ * @module core/contract/limits
+ */
+/**
+ * Maximum UTF-8 byte length of any single identifier-shaped contract string —
+ * workflow/signal/update/query/activity name, `workflowVersion`, or an
+ * explicitly supplied `revision`.
+ *
+ * @example
+ * ```ts
+ * import { MAX_CONTRACT_IDENTIFIER_BYTES } from '@lostgradient/weft';
+ *
+ * const name = 'checkout';
+ * const fits = new TextEncoder().encode(name).byteLength <= MAX_CONTRACT_IDENTIFIER_BYTES;
+ * console.log(fits); // true
+ * ```
+ */
+export declare const MAX_CONTRACT_IDENTIFIER_BYTES = 512;
+/**
+ * Maximum number of entries in any one of a contract's `signals`, `updates`,
+ * `queries`, or `activities` records.
+ *
+ * @example
+ * ```ts
+ * import { MAX_CONTRACT_MESSAGE_COUNT } from '@lostgradient/weft';
+ *
+ * const signals = ['approved', 'rejected'];
+ * console.log(signals.length <= MAX_CONTRACT_MESSAGE_COUNT); // true
+ * ```
+ */
+export declare const MAX_CONTRACT_MESSAGE_COUNT = 512;
+/**
+ * Maximum nesting depth permitted inside one schema fragment
+ * (`inputSchema`/`outputSchema`).
+ *
+ * Mirrors `codegen-emit.ts`'s `MAX_RECURSION_DEPTH`. `isJSONValue()` and
+ * `canonicalJsonStringify()` are both unbounded recursion over their input,
+ * so {@link parseWorkflowRevisionManifest} enforces this bound itself,
+ * iteratively, before either ever walks an untrusted schema fragment.
+ *
+ * @example
+ * ```ts
+ * import { MAX_CONTRACT_SCHEMA_DEPTH } from '@lostgradient/weft';
+ *
+ * console.log(MAX_CONTRACT_SCHEMA_DEPTH >= 16); // true
+ * ```
+ */
+export declare const MAX_CONTRACT_SCHEMA_DEPTH = 64;
+/**
+ * Maximum UTF-8 byte length of the canonical, normalized contract JSON.
+ *
+ * Checked against the canonical serialization — not the received bytes — so
+ * a compact payload cannot evade the bound and then expand under
+ * normalization.
+ *
+ * @example
+ * ```ts
+ * import { buildWorkflowContract, canonicalWorkflowContractJson, MAX_NORMALIZED_CONTRACT_BYTES } from '@lostgradient/weft';
+ *
+ * const canonical = canonicalWorkflowContractJson(
+ *   buildWorkflowContract({ name: 'checkout', version: '2.1.0' }),
+ * );
+ * console.log(canonical.length <= MAX_NORMALIZED_CONTRACT_BYTES); // true
+ * ```
+ */
+export declare const MAX_NORMALIZED_CONTRACT_BYTES = 262144;

package/dist/core/contract/limits.js

@@ -0,0 +1 @@
+export const MAX_CONTRACT_IDENTIFIER_BYTES = 512, MAX_CONTRACT_MESSAGE_COUNT = 512, MAX_CONTRACT_SCHEMA_DEPTH = 64, MAX_NORMALIZED_CONTRACT_BYTES = 262144;

package/dist/core/contract/manifest-parse-schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hostile-input validation for the schema-fragment-shaped parts of an
+ * untrusted {@link WorkflowRevisionManifest}: `inputSchema`/`outputSchema`
+ * pairs, and the `signals`/`updates`/`queries`/`activities` records that
+ * carry them.
+ *
+ * Split out of `manifest-parse.ts` to keep each file under the repository's
+ * implementation-file-size ceiling and so the depth/JSON-safety walk that
+ * every schema fragment goes through has one place to audit.
+ *
+ * @module core/contract/manifest-parse-schema
+ */
+import { type NameKind } from '../types/name-grammar.ts';
+import { type WorkflowRevisionManifestValidationFailure } from './failure.ts';
+import type { WorkflowActivityContract, WorkflowMessageContract } from './types.ts';
+type ParseSuccess<T> = {
+    ok: true;
+    value: T;
+};
+type ParseOutcome<T> = ParseSuccess<T> | WorkflowRevisionManifestValidationFailure;
+/** Validate a `{ inputSchema?, outputSchema? }`-shaped entry from untrusted input. */
+export declare function parseSchemaPair(value: unknown, path: string): ParseOutcome<WorkflowMessageContract | WorkflowActivityContract>;
+/**
+ * Validate one record key: present, non-empty, within the identifier byte
+ * ceiling and, when `kind` is given, wire-safe per
+ * `validateWorkflowOrActivityName`. Signal/update/query names pass `kind:
+ * undefined` — those names are deliberately unconstrained, matching
+ * `SignalDefinition`/`UpdateDefinition`/`QueryDefinition` at the type level.
+ */
+export declare function checkContractKey(key: string, kind: NameKind | undefined, path: string): WorkflowRevisionManifestValidationFailure | undefined;
+/**
+ * Validate a `signals`/`updates`/`queries`/`activities` record from
+ * untrusted input: bounded entry count, bounded/validated keys, and every
+ * entry parsed as a schema pair.
+ */
+export declare function parseContractRecord(value: unknown, path: string, keyKind: NameKind | undefined): ParseOutcome<Readonly<Record<string, WorkflowMessageContract | WorkflowActivityContract>>>;
+export {};

package/dist/core/contract/manifest-parse-schema.js

@@ -0,0 +1,106 @@
+import { isRecord } from "../../worker/manifest/is-record.js";
+import { utf8ByteLength } from "../../worker/manifest/utf8.js";
+import { isJSONValue } from "../json.js";
+import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+import {
+  workflowRevisionManifestFailure
+} from "./failure.js";
+import {
+  MAX_CONTRACT_IDENTIFIER_BYTES,
+  MAX_CONTRACT_MESSAGE_COUNT,
+  MAX_CONTRACT_SCHEMA_DEPTH
+} from "./limits.js";
+function withinDepth(value, maxDepth) {
+  const stack = [{ value, depth: 1 }];
+  while (stack.length > 0) {
+    const frame = stack.pop();
+    if (frame === void 0)
+      break;
+    if (frame.depth > maxDepth)
+      return !1;
+    const current = frame.value;
+    if (current === null || typeof current !== "object")
+      continue;
+    const nextDepth = frame.depth + 1;
+    if (nextDepth > maxDepth)
+      return !1;
+    if (Array.isArray(current))
+      for (const item of current)
+        stack.push({ value: item, depth: nextDepth });
+    else
+      for (const item of Object.values(current))
+        stack.push({ value: item, depth: nextDepth });
+  }
+  return !0;
+}
+function cloneJsonSafe(value) {
+  if (value === null || typeof value !== "object")
+    return value;
+  if (Array.isArray(value))
+    return value.map((entry) => cloneJsonSafe(entry));
+  const record = value, cloned = Object.create(null);
+  for (const key of Object.keys(record))
+    cloned[key] = cloneJsonSafe(record[key]);
+  return cloned;
+}
+function parseSchemaFragment(value, path) {
+  if (!isRecord(value))
+    return workflowRevisionManifestFailure("invalid-field", "must be a JSON object", path);
+  if (!withinDepth(value, MAX_CONTRACT_SCHEMA_DEPTH))
+    return workflowRevisionManifestFailure("invalid-field", `nests deeper than the maximum schema depth of ${MAX_CONTRACT_SCHEMA_DEPTH}`, path);
+  if (!isJSONValue(value))
+    return workflowRevisionManifestFailure("invalid-field", "must be a JSON-safe object", path);
+  return { ok: !0, value: cloneJsonSafe(value) };
+}
+export function parseSchemaPair(value, path) {
+  if (!isRecord(value))
+    return workflowRevisionManifestFailure("invalid-field", "must be a JSON object", path);
+  const entry = {};
+  if (value.inputSchema !== void 0) {
+    const inputSchema = parseSchemaFragment(value.inputSchema, `${path}.inputSchema`);
+    if (!inputSchema.ok)
+      return inputSchema;
+    entry.inputSchema = inputSchema.value;
+  }
+  if (value.outputSchema !== void 0) {
+    const outputSchema = parseSchemaFragment(value.outputSchema, `${path}.outputSchema`);
+    if (!outputSchema.ok)
+      return outputSchema;
+    entry.outputSchema = outputSchema.value;
+  }
+  return { ok: !0, value: entry };
+}
+export function checkContractKey(key, kind, path) {
+  if (kind !== void 0 && key.length === 0)
+    return workflowRevisionManifestFailure("invalid-field", "must not be an empty string", path);
+  if (kind !== void 0) {
+    const bytes = utf8ByteLength(key);
+    if (bytes > MAX_CONTRACT_IDENTIFIER_BYTES)
+      return workflowRevisionManifestFailure("identifier-too-long", `is ${bytes} bytes, exceeding the maximum identifier size of ${MAX_CONTRACT_IDENTIFIER_BYTES}`, path);
+    try {
+      validateWorkflowOrActivityName(key, kind);
+    } catch (error) {
+      const message = (error instanceof Error ? error.message : "is not a wire-safe name").replaceAll(key, JSON.stringify(key));
+      return workflowRevisionManifestFailure("invalid-field", message, path);
+    }
+  }
+  return;
+}
+export function parseContractRecord(value, path, keyKind) {
+  if (!isRecord(value))
+    return workflowRevisionManifestFailure("invalid-field", "must be a JSON object", path);
+  const names = Object.keys(value);
+  if (names.length > MAX_CONTRACT_MESSAGE_COUNT)
+    return workflowRevisionManifestFailure("too-many-entries", `declares ${names.length} entries, exceeding the maximum of ${MAX_CONTRACT_MESSAGE_COUNT}`, path);
+  const built = Object.create(null);
+  for (const name of names) {
+    const keyFailure = checkContractKey(name, keyKind, `${path} key ${JSON.stringify(name)}`);
+    if (keyFailure !== void 0)
+      return keyFailure;
+    const entry = parseSchemaPair(value[name], `${path}.${name}`);
+    if (!entry.ok)
+      return entry;
+    built[name] = entry.value;
+  }
+  return { ok: !0, value: built };
+}

package/dist/core/contract/manifest-parse.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Hostile-input parsing for workflow revision manifests.
+ *
+ * A manifest arrives from a source this module does not control — persisted
+ * storage read by an older or differently-configured build, a wire payload,
+ * an operator-supplied fixture. Every field is proven from `unknown` rather
+ * than asserted, every open-ended collection is bounded before it is walked,
+ * and `contractHash` is always recomputed and compared rather than trusted
+ * as supplied — a caller cannot assert a hash it did not earn.
+ *
+ * @module core/contract/manifest-parse
+ */
+import { type WorkflowRevisionManifestValidationFailure } from './failure.ts';
+import type { WorkflowRevisionManifest } from './types.ts';
+/**
+ * A successfully validated manifest, paired with the canonical serialization
+ * of its (normalized) contract, so a caller does not have to re-derive it.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   buildWorkflowContract,
+ *   buildWorkflowRevisionManifest,
+ *   parseWorkflowRevisionManifest,
+ *   type WorkflowRevisionManifestParseSuccess,
+ * } from '@lostgradient/weft';
+ *
+ * const manifest = await buildWorkflowRevisionManifest(buildWorkflowContract({ name: 'checkout' }));
+ * const result = await parseWorkflowRevisionManifest(manifest);
+ * if (result.ok) {
+ *   const accepted: WorkflowRevisionManifestParseSuccess = result;
+ *   console.log(accepted.canonicalJson.length > 0);
+ * }
+ * ```
+ */
+export type WorkflowRevisionManifestParseSuccess = Readonly<{
+    ok: true;
+    /** The validated, normalized manifest. */
+    manifest: WorkflowRevisionManifest;
+    /** Canonical serialization of `manifest.contract` — `canonicalWorkflowContractJson(manifest.contract)`. */
+    canonicalJson: string;
+}>;
+/**
+ * Outcome of validating an untrusted workflow revision manifest.
+ *
+ * @example
+ * ```ts
+ * import { parseWorkflowRevisionManifest, type WorkflowRevisionManifestParseResult } from '@lostgradient/weft';
+ *
+ * const result: WorkflowRevisionManifestParseResult = await parseWorkflowRevisionManifest({});
+ * console.log(result.ok);
+ * ```
+ */
+export type WorkflowRevisionManifestParseResult = WorkflowRevisionManifestParseSuccess | WorkflowRevisionManifestValidationFailure;
+/**
+ * Validate an untrusted workflow revision manifest.
+ *
+ * The returned manifest is already normalized, `contractHash` is always
+ * recomputed from the (normalized) contract and compared against the
+ * supplied value — a mismatch is rejected with `'contract-hash-mismatch'`
+ * regardless of what the caller asserted — and `manifest.name`/
+ * `manifest.workflowVersion` must agree with `manifest.contract.name`/
+ * `manifest.contract.workflowVersion`. `revision` is validated (bounded,
+ * non-empty) but never recomputed: it is an opaque label the parser trusts
+ * once it is well-formed.
+ *
+ * @example
+ * ```ts
+ * import { buildWorkflowContract, buildWorkflowRevisionManifest, parseWorkflowRevisionManifest } from '@lostgradient/weft';
+ *
+ * const manifest = await buildWorkflowRevisionManifest(buildWorkflowContract({ name: 'checkout' }));
+ * const result = await parseWorkflowRevisionManifest(manifest);
+ * console.log(result.ok ? result.manifest.name : result.reason);
+ * ```
+ */
+export declare function parseWorkflowRevisionManifest(value: unknown): Promise<WorkflowRevisionManifestParseResult>;

package/dist/core/contract/manifest-parse.js

@@ -0,0 +1,189 @@
+import { isRecord } from "../../worker/manifest/is-record.js";
+import { utf8ByteLength } from "../../worker/manifest/utf8.js";
+import {
+  workflowRevisionManifestFailure
+} from "./failure.js";
+import { contractHash } from "./hash.js";
+import {
+  MAX_CONTRACT_IDENTIFIER_BYTES,
+  MAX_CONTRACT_MESSAGE_COUNT,
+  MAX_NORMALIZED_CONTRACT_BYTES
+} from "./limits.js";
+import { checkContractKey, parseContractRecord, parseSchemaPair } from "./manifest-parse-schema.js";
+import { canonicalWorkflowContractJson, normalizeWorkflowContract } from "./normalize.js";
+import { WORKFLOW_REVISION_MANIFEST_VERSION } from "./types.js";
+function parseIdentifier(value, path) {
+  if (typeof value !== "string" || value.length === 0)
+    return workflowRevisionManifestFailure("invalid-field", "must be a non-empty string", path);
+  const bytes = utf8ByteLength(value);
+  if (bytes > MAX_CONTRACT_IDENTIFIER_BYTES)
+    return workflowRevisionManifestFailure("identifier-too-long", `is ${bytes} bytes, exceeding the maximum identifier size of ${MAX_CONTRACT_IDENTIFIER_BYTES}`, path);
+  return { ok: !0, value };
+}
+function parseDescription(value, path) {
+  if (typeof value !== "string")
+    return workflowRevisionManifestFailure("invalid-field", "must be a string", path);
+  return { ok: !0, value };
+}
+function parseTag(value, path) {
+  if (typeof value !== "string")
+    return workflowRevisionManifestFailure("invalid-field", "must be a string", path);
+  return { ok: !0, value };
+}
+function parseTags(value, path) {
+  if (value === void 0)
+    return { ok: !0, value: void 0 };
+  if (!Array.isArray(value))
+    return workflowRevisionManifestFailure("invalid-field", "must be an array of strings", path);
+  if (value.length > MAX_CONTRACT_MESSAGE_COUNT)
+    return workflowRevisionManifestFailure("too-many-entries", `declares ${value.length} entries, exceeding the maximum of ${MAX_CONTRACT_MESSAGE_COUNT}`, path);
+  const tags = [];
+  let accumulatedBytes = 0;
+  for (const [index, entry] of value.entries()) {
+    const tag = parseTag(entry, `${path}[${index}]`);
+    if (!tag.ok)
+      return tag;
+    accumulatedBytes += utf8ByteLength(tag.value);
+    if (accumulatedBytes > MAX_NORMALIZED_CONTRACT_BYTES)
+      return workflowRevisionManifestFailure("manifest-too-large", `accumulated tag bytes exceed the maximum of ${MAX_NORMALIZED_CONTRACT_BYTES}`, path);
+    tags.push(tag.value);
+  }
+  return { ok: !0, value: tags.length === 0 ? void 0 : tags };
+}
+function parseContractIdentity(value, path) {
+  const name = parseIdentifier(value.name, `${path}.name`);
+  if (!name.ok)
+    return name;
+  const nameKeyFailure = checkContractKey(name.value, "workflow", `${path}.name`);
+  if (nameKeyFailure !== void 0)
+    return nameKeyFailure;
+  const workflowVersion = parseIdentifier(value.workflowVersion, `${path}.workflowVersion`);
+  if (!workflowVersion.ok)
+    return workflowVersion;
+  const identity = {
+    name: name.value,
+    workflowVersion: workflowVersion.value
+  };
+  if (value.description !== void 0) {
+    const description = parseDescription(value.description, `${path}.description`);
+    if (!description.ok)
+      return description;
+    identity.description = description.value;
+  }
+  const tags = parseTags(value.tags, `${path}.tags`);
+  if (!tags.ok)
+    return tags;
+  if (tags.value !== void 0)
+    identity.tags = tags.value;
+  return { ok: !0, value: identity };
+}
+const NAMED_RECORD_FIELDS = [
+  ["signals", void 0],
+  ["updates", void 0],
+  ["queries", void 0],
+  ["activities", "activity"]
+];
+function parseNamedRecordFields(value, path, collections) {
+  for (const [field, keyKind] of NAMED_RECORD_FIELDS) {
+    if (value[field] === void 0)
+      continue;
+    const parsed = parseContractRecord(value[field], `${path}.${field}`, keyKind);
+    if (!parsed.ok)
+      return parsed;
+    collections[field] = parsed.value;
+  }
+  return;
+}
+function parseContractCollections(value, path) {
+  const collections = {};
+  if (value.inputSchema !== void 0 || value.outputSchema !== void 0) {
+    const pair = parseSchemaPair({ inputSchema: value.inputSchema, outputSchema: value.outputSchema }, path);
+    if (!pair.ok)
+      return pair;
+    if (pair.value.inputSchema !== void 0)
+      collections.inputSchema = pair.value.inputSchema;
+    if (pair.value.outputSchema !== void 0)
+      collections.outputSchema = pair.value.outputSchema;
+  }
+  const recordFailure = parseNamedRecordFields(value, path, collections);
+  if (recordFailure !== void 0)
+    return recordFailure;
+  if (value.finalizer !== void 0) {
+    const finalizer = parseSchemaPair(value.finalizer, `${path}.finalizer`);
+    if (!finalizer.ok)
+      return finalizer;
+    collections.finalizer = finalizer.value;
+  }
+  return { ok: !0, value: collections };
+}
+function parseContract(value, path) {
+  if (!isRecord(value))
+    return workflowRevisionManifestFailure("invalid-field", "must be a JSON object", path);
+  const identity = parseContractIdentity(value, path);
+  if (!identity.ok)
+    return identity;
+  const collections = parseContractCollections(value, path);
+  if (!collections.ok)
+    return collections;
+  return { ok: !0, value: { ...identity.value, ...collections.value } };
+}
+const TOP_LEVEL_IDENTIFIER_FIELDS = [
+  ["name", "manifest.name"],
+  ["workflowVersion", "manifest.workflowVersion"],
+  ["revision", "manifest.revision"],
+  ["contractHash", "manifest.contractHash"]
+];
+function parseTopLevelIdentifiers(value) {
+  const parsed = {};
+  for (const [field, path] of TOP_LEVEL_IDENTIFIER_FIELDS) {
+    const result = parseIdentifier(value[field], path);
+    if (!result.ok)
+      return result;
+    parsed[field] = result.value;
+  }
+  return { ok: !0, value: parsed };
+}
+function checkIdentityAgreement(identifiers, contract) {
+  if (identifiers.name !== contract.name)
+    return workflowRevisionManifestFailure("invalid-field", "must equal manifest.contract.name", "manifest.name");
+  if (identifiers.workflowVersion !== contract.workflowVersion)
+    return workflowRevisionManifestFailure("invalid-field", "must equal manifest.contract.workflowVersion", "manifest.workflowVersion");
+  return;
+}
+async function finalizeManifest(identifiers, normalized) {
+  const canonicalJson = canonicalWorkflowContractJson(normalized), canonicalBytes = utf8ByteLength(canonicalJson);
+  if (canonicalBytes > MAX_NORMALIZED_CONTRACT_BYTES)
+    return workflowRevisionManifestFailure("manifest-too-large", `contract normalizes to ${canonicalBytes} bytes, exceeding the maximum of ${MAX_NORMALIZED_CONTRACT_BYTES}`, "manifest.contract");
+  const recomputedHash = await contractHash(normalized);
+  if (recomputedHash !== identifiers.contractHash)
+    return workflowRevisionManifestFailure("contract-hash-mismatch", `recomputed contractHash ${recomputedHash} does not match the supplied value`, "manifest.contractHash");
+  return {
+    ok: !0,
+    manifest: {
+      manifestVersion: WORKFLOW_REVISION_MANIFEST_VERSION,
+      name: identifiers.name,
+      workflowVersion: identifiers.workflowVersion,
+      revision: identifiers.revision,
+      contractHash: recomputedHash,
+      contract: normalized
+    },
+    canonicalJson
+  };
+}
+export async function parseWorkflowRevisionManifest(value) {
+  if (!isRecord(value))
+    return workflowRevisionManifestFailure("not-an-object", "manifest must be a JSON object");
+  if (value.manifestVersion !== WORKFLOW_REVISION_MANIFEST_VERSION)
+    return workflowRevisionManifestFailure("manifest-version-unsupported", `manifest.manifestVersion must be ${String(WORKFLOW_REVISION_MANIFEST_VERSION)}`);
+  const identifiers = parseTopLevelIdentifiers(value);
+  if (!identifiers.ok)
+    return identifiers;
+  const contract = parseContract(value.contract, "manifest.contract");
+  if (!contract.ok)
+    return contract;
+  const agreementFailure = checkIdentityAgreement(identifiers.value, contract.value);
+  if (agreementFailure !== void 0)
+    return agreementFailure;
+  const normalized = normalizeWorkflowContract(contract.value);
+  return finalizeManifest(identifiers.value, normalized);
+}

package/dist/core/contract/manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Build a {@link WorkflowRevisionManifest} from a normalized contract.
+ *
+ * @module core/contract/manifest
+ */
+import type { WorkflowContract, WorkflowRevisionManifest } from './types.ts';
+/**
+ * Options accepted by {@link buildWorkflowRevisionManifest}.
+ *
+ * @example
+ * ```ts
+ * import type { BuildWorkflowRevisionManifestOptions } from '@lostgradient/weft';
+ *
+ * const options: BuildWorkflowRevisionManifestOptions = { revision: 'deploy-2026.09.01' };
+ * console.log(options.revision);
+ * ```
+ */
+export interface BuildWorkflowRevisionManifestOptions {
+    /**
+     * Explicit opaque revision identity. When omitted, `revision` is derived
+     * from the full contract via {@link deriveWorkflowRevision}. An empty
+     * string, or a string exceeding `MAX_CONTRACT_IDENTIFIER_BYTES`, is
+     * rejected rather than silently falling back to derivation.
+     */
+    revision?: string;
+}
+/**
+ * Build a {@link WorkflowRevisionManifest} for a workflow contract.
+ *
+ * Normalizes the contract, computes `contractHash`, and either derives
+ * `revision` (the default) or validates and preserves an explicitly
+ * supplied one.
+ *
+ * Throws a plain `Error` when `options.revision` is present but empty, or
+ * exceeds `MAX_CONTRACT_IDENTIFIER_BYTES` — a caller-supplied identity is
+ * validated the same way any other contract identifier is, since it becomes
+ * part of the manifest a consumer will trust.
+ *
+ * **Round-trips through {@link parseWorkflowRevisionManifest} before
+ * returning.** A manifest this function builds but its own parser would
+ * reject (`identifier-too-long`, `too-many-entries`, `manifest-too-large`)
+ * is a build-time bug, not a runtime condition to defer to whoever later
+ * reads the manifest back — see WFT-5 PR #943 review thread
+ * PRRT_kwDORwthfM6eWFwv. Throws a plain `Error` describing the rejection
+ * reason when that happens.
+ *
+ * @example
+ * ```ts
+ * import { buildWorkflowContract, buildWorkflowRevisionManifest } from '@lostgradient/weft';
+ *
+ * const contract = buildWorkflowContract({ name: 'checkout', version: '2.1.0' });
+ * const manifest = await buildWorkflowRevisionManifest(contract);
+ * console.log(manifest.name, manifest.contractHash.startsWith('sha256:'));
+ * ```
+ */
+export declare function buildWorkflowRevisionManifest(contract: WorkflowContract, options?: BuildWorkflowRevisionManifestOptions): Promise<WorkflowRevisionManifest>;

package/dist/core/contract/manifest.js

@@ -0,0 +1,31 @@
+import { utf8ByteLength } from "../../worker/manifest/utf8.js";
+import { contractHash } from "./hash.js";
+import { MAX_CONTRACT_IDENTIFIER_BYTES } from "./limits.js";
+import { parseWorkflowRevisionManifest } from "./manifest-parse.js";
+import { normalizeWorkflowContract } from "./normalize.js";
+import { deriveWorkflowRevision } from "./revision.js";
+import { WORKFLOW_REVISION_MANIFEST_VERSION } from "./types.js";
+export async function buildWorkflowRevisionManifest(contract, options) {
+  const normalized = normalizeWorkflowContract(contract), hash = await contractHash(normalized);
+  let revision;
+  if (options?.revision !== void 0) {
+    if (options.revision.length === 0)
+      throw Error("buildWorkflowRevisionManifest: options.revision must not be an empty string");
+    const bytes = utf8ByteLength(options.revision);
+    if (bytes > MAX_CONTRACT_IDENTIFIER_BYTES)
+      throw Error(`buildWorkflowRevisionManifest: options.revision is ${bytes} bytes, exceeding the maximum identifier size of ${MAX_CONTRACT_IDENTIFIER_BYTES}`);
+    revision = options.revision;
+  } else
+    revision = await deriveWorkflowRevision(normalized);
+  const manifest = {
+    manifestVersion: WORKFLOW_REVISION_MANIFEST_VERSION,
+    name: normalized.name,
+    workflowVersion: normalized.workflowVersion,
+    revision,
+    contractHash: hash,
+    contract: normalized
+  }, parsed = await parseWorkflowRevisionManifest(manifest);
+  if (!parsed.ok)
+    throw Error(`buildWorkflowRevisionManifest: built manifest fails parseWorkflowRevisionManifest validation (${parsed.reason}${parsed.path === void 0 ? "" : ` at ${parsed.path}`}): ` + parsed.message);
+  return parsed.manifest;
+}