@lostgradient/weft 0.23.1 → 0.24.1

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

@@ -0,0 +1,64 @@
+/**
+ * Bounded failure vocabulary for workflow revision manifest validation.
+ *
+ * Mirrors `src/worker/manifest/failure.ts`: rejections are returned rather
+ * than thrown, `reason` is a closed union safe to use as a metric label, and
+ * `message`/`path` are diagnostics only.
+ *
+ * @module core/contract/failure
+ */
+/**
+ * Why an untrusted {@link WorkflowRevisionManifest} was rejected.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowRevisionManifestRejectionReason } from '@lostgradient/weft';
+ *
+ * const counts = new Map<WorkflowRevisionManifestRejectionReason, number>();
+ * counts.set('contract-hash-mismatch', 1);
+ * console.log(counts.get('contract-hash-mismatch'));
+ * ```
+ */
+export type WorkflowRevisionManifestRejectionReason = 'manifest-version-unsupported' | 'contract-hash-mismatch' | 'not-an-object' | 'invalid-field' | 'identifier-too-long' | 'too-many-entries' | 'manifest-too-large';
+/**
+ * A rejected workflow revision manifest, with enough detail to fix the
+ * caller's input and not so much that it leaks contract content into logs.
+ *
+ * @example
+ * ```ts
+ * import { parseWorkflowRevisionManifest, type WorkflowRevisionManifestValidationFailure } from '@lostgradient/weft';
+ *
+ * const result = await parseWorkflowRevisionManifest({ manifestVersion: 99 });
+ * if (!result.ok) {
+ *   const rejection: WorkflowRevisionManifestValidationFailure = result;
+ *   console.log(rejection.reason); // 'manifest-version-unsupported'
+ * }
+ * ```
+ */
+export type WorkflowRevisionManifestValidationFailure = Readonly<{
+    ok: false;
+    /** Bounded rejection reason, safe as a metric label. */
+    reason: WorkflowRevisionManifestRejectionReason;
+    /** Human-readable diagnostic. Never use as a metric label. */
+    message: string;
+    /** Dotted path to the offending field, when one applies. */
+    path?: string;
+}>;
+/**
+ * Build a validation failure whose message reads as one sentence about the
+ * offending path — `manifest.contract.workflowVersion must be a non-empty
+ * string`.
+ *
+ * @example
+ * ```ts
+ * import { workflowRevisionManifestFailure } from '@lostgradient/weft';
+ *
+ * const failure = workflowRevisionManifestFailure(
+ *   'invalid-field',
+ *   'must be a non-empty string',
+ *   'manifest.name',
+ * );
+ * console.log(failure.message);
+ * ```
+ */
+export declare function workflowRevisionManifestFailure(reason: WorkflowRevisionManifestRejectionReason, message: string, path?: string): WorkflowRevisionManifestValidationFailure;

package/dist/core/contract/failure.js

@@ -0,0 +1,4 @@
+export function workflowRevisionManifestFailure(reason, message, path) {
+  const described = path === void 0 ? message : `${path} ${message}`;
+  return path === void 0 ? { ok: !1, reason, message: described } : { ok: !1, reason, message: described, path };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Content-addressed digests of a workflow contract's public payload.
+ *
+ * `contractHash()` answers "which public payload contract does this
+ * revision implement" — it excludes `name`, `workflowVersion`,
+ * `description`, and `tags`, which identify the workflow and describe it in
+ * prose rather than describe what callers may send and get back. That
+ * exclusion is what lets a documentation edit change `deriveWorkflowRevision()`'s
+ * broader identity (see `revision.ts`) without changing `contractHash()`.
+ *
+ * `digestCanonicalWorkflowContract()` is a generic "digest this canonical
+ * JSON text" primitive shared by both identities: which identity a caller
+ * gets back depends entirely on which canonical serializer produced the
+ * text handed to it — `canonicalWorkflowContractJson()`'s full-identity
+ * output yields the same digest `deriveWorkflowRevision()` returns; this
+ * module's internal payload-only serializer is what `contractHash()` feeds
+ * it. Treat it as a shared digesting primitive, not as itself a payload-only
+ * function.
+ *
+ * SHA-256 rather than the repository's FNV-1a helpers, matching the worker
+ * manifest digest's choice: `contractHash` is compared for compatibility
+ * decisions, so a collision would let two different contracts pass for one
+ * another, ruling out a cache-key-quality hash.
+ *
+ * @module core/contract/hash
+ */
+import type { WorkflowActivityContract, WorkflowContract } from './types.ts';
+/**
+ * Algorithm tag prefixed to every digest {@link contractHash} and
+ * {@link activityContractHash} produce.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_CONTRACT_DIGEST_ALGORITHM } from '@lostgradient/weft';
+ *
+ * const hash = 'sha256:2b1f0c9d';
+ * console.log(hash.startsWith(`${WORKFLOW_CONTRACT_DIGEST_ALGORITHM}:`)); // true
+ * ```
+ */
+export declare const WORKFLOW_CONTRACT_DIGEST_ALGORITHM = "sha256";
+/**
+ * Digest canonical contract JSON text.
+ *
+ * Separate from {@link contractHash} and `deriveWorkflowRevision` so a
+ * caller that already holds a canonical serialization does not serialize
+ * the contract a second time. Which identity the result represents depends
+ * entirely on which canonical serializer produced `canonicalJson` — see this
+ * module's JSDoc.
+ *
+ * @example
+ * ```ts
+ * import { canonicalWorkflowContractJson, digestCanonicalWorkflowContract } from '@lostgradient/weft';
+ *
+ * const canonical = canonicalWorkflowContractJson({ name: 'checkout', workflowVersion: '2.1.0' });
+ * console.log((await digestCanonicalWorkflowContract(canonical)).startsWith('sha256:'));
+ * ```
+ */
+export declare function digestCanonicalWorkflowContract(canonicalJson: string): Promise<string>;
+/**
+ * Compute a workflow contract's payload-only content identity.
+ *
+ * Determined entirely by the payload fields (schemas, signals, updates,
+ * queries, activities, finalizer) plus the `WORKFLOW_CONTRACT_VERSION`
+ * domain separator — two contracts that differ only in `name`,
+ * `workflowVersion`, `description`, or `tags` hash identically, and two
+ * contracts that differ only in key order also hash identically.
+ *
+ * @example
+ * ```ts
+ * import { contractHash } from '@lostgradient/weft';
+ *
+ * const left = await contractHash({ name: 'checkout', workflowVersion: '1.0.0' });
+ * const right = await contractHash({ name: 'checkout', workflowVersion: '2.0.0' });
+ * console.log(left === right); // true — name/workflowVersion are excluded
+ * ```
+ */
+export declare function contractHash(contract: WorkflowContract): Promise<string>;
+/**
+ * Compute one activity's payload-only content identity, independent of the
+ * workflow contract it is declared under.
+ *
+ * @example
+ * ```ts
+ * import { activityContractHash } from '@lostgradient/weft';
+ *
+ * const hash = await activityContractHash({
+ *   inputSchema: { type: 'object', properties: { amount: { type: 'number' } } },
+ * });
+ * console.log(hash.startsWith('sha256:')); // true
+ * ```
+ */
+export declare function activityContractHash(activity: WorkflowActivityContract): Promise<string>;

package/dist/core/contract/hash.js

@@ -0,0 +1,34 @@
+import { sha256Hex } from "../../worker/manifest/content-digest.js";
+import {
+  appendContractRecordField,
+  appendSchemaField,
+  canonicalMessageContractJson
+} from "./normalize.js";
+import { WORKFLOW_CONTRACT_VERSION } from "./types.js";
+export const WORKFLOW_CONTRACT_DIGEST_ALGORITHM = "sha256";
+function canonicalWorkflowContractPayloadJson(contract) {
+  const fields = [`"contractVersion":${JSON.stringify(WORKFLOW_CONTRACT_VERSION)}`];
+  appendSchemaField(fields, "inputSchema", contract.inputSchema);
+  appendSchemaField(fields, "outputSchema", contract.outputSchema);
+  appendContractRecordField(fields, "signals", contract.signals);
+  appendContractRecordField(fields, "updates", contract.updates);
+  appendContractRecordField(fields, "queries", contract.queries);
+  appendContractRecordField(fields, "activities", contract.activities);
+  if (contract.finalizer !== void 0)
+    fields.push(`"finalizer":${canonicalMessageContractJson(contract.finalizer)}`);
+  return `{${fields.join(",")}}`;
+}
+export async function digestCanonicalWorkflowContract(canonicalJson) {
+  return sha256Hex(canonicalJson);
+}
+export async function contractHash(contract) {
+  return digestCanonicalWorkflowContract(canonicalWorkflowContractPayloadJson(contract));
+}
+export async function activityContractHash(activity) {
+  const versionField = `"contractVersion":${JSON.stringify(WORKFLOW_CONTRACT_VERSION)}`, schemaFields = canonicalActivityContractSchemaFields(activity);
+  return digestCanonicalWorkflowContract(`{${[versionField, ...schemaFields].join(",")}}`);
+}
+function canonicalActivityContractSchemaFields(entry) {
+  const stripped = canonicalMessageContractJson(entry).slice(1, -1);
+  return stripped.length === 0 ? [] : [stripped];
+}

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>;