@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/compare-codepoint.js

@@ -0,0 +1,7 @@
+export function compareCodepoint(a, b) {
+  if (a < b)
+    return -1;
+  if (a > b)
+    return 1;
+  return 0;
+}

package/dist/core/compression.js

@@ -38,6 +38,8 @@ export function createCompressor(algorithm) {
           return data;
         }
       };
+    default:
+      throw Error(`Unknown compression algorithm: ${JSON.stringify(algorithm)}`);
   }
 }
 export async function compressPayload(data, compressor, threshold) {

package/dist/core/context/attributes.d.ts

@@ -3,5 +3,5 @@ import type { ContextInternals } from './internals.ts';
 export declare function validateAttribute(internals: ContextInternals, key: string, value: SearchAttributeValue): void;
 export declare function setAttribute(internals: ContextInternals, key: string, value: SearchAttributeValue): void;
 export declare function setAttributes(internals: ContextInternals, attributes: Record<string, SearchAttributeValue>): void;
-export declare function getAttribute<T extends SearchAttributeValue = SearchAttributeValue>(internals: ContextInternals, key: string): T | undefined;
+export declare function getAttribute(internals: ContextInternals, key: string): SearchAttributeValue | undefined;
 export declare function getAttributes(internals: ContextInternals): Readonly<Record<string, SearchAttributeValue>>;

package/dist/core/context/durable-operations.d.ts

@@ -43,8 +43,8 @@ export declare function readOrInitConditionDeadline(internals: ContextInternals,
  */
 export declare function waitUntil(context: Context, internals: ContextInternals, predicate: () => boolean, timeout?: Duration): Generator<ContextOperationRequest, boolean | void, unknown>;
 export declare function getVersion(_context: Context, internals: ContextInternals, changeId: string, minSupported: number, maxSupported: number): Generator<ContextOperationRequest, number, unknown>;
-export declare function waitForUpdate<T = unknown>(context: Context, internals: ContextInternals, name: string): Generator<ContextOperationRequest, {
-    payload: T;
+export declare function waitForUpdate(context: Context, internals: ContextInternals, name: string): Generator<ContextOperationRequest, {
+    payload: unknown;
     respond: (result: unknown) => void;
 }, unknown>;
 export declare function review(context: Context, internals: ContextInternals, options: HumanReviewOptions): Generator<ContextOperationRequest, HumanReviewResult, unknown>;

package/dist/core/context/index.js

@@ -114,9 +114,11 @@ export class Context {
     if (prepared.cached)
       return;
     const execute = () => durableOperations.completePreparedSleepOperation(this, prepared);
-    if (!internals.workflowInterceptor)
-      return yield* execute();
-    return yield* internals.workflowInterceptor.sleep({
+    if (!internals.workflowInterceptor) {
+      yield* execute();
+      return;
+    }
+    yield* internals.workflowInterceptor.sleep({
       workflowId: this.workflowId,
       duration: prepared.milliseconds,
       headers: new Map

package/dist/core/context/state-namespace.d.ts

@@ -6,7 +6,7 @@ import type { ContextOperationRequest } from './operation-request.ts';
 interface WorkflowAtomicStateOperationCache {
     nextStep(): number;
     has(step: number): boolean;
-    get<TResult>(step: number): TResult;
+    get(step: number): unknown;
     set(step: number, value: unknown): void;
 }
 export declare function createStateNamespace(context: Context, internals: ContextInternals): WorkflowStateNamespace;

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

@@ -0,0 +1,64 @@
+/**
+ * Convert an authoring-time workflow definition into a {@link WorkflowContract}.
+ *
+ * Every `DefinitionSchema` (workflow input/output, every signal/update/query,
+ * every activity, the finalizer) is converted through the existing
+ * `definitionSchemaToJsonSchema()` — this module does not reimplement schema
+ * conversion, and it does not reimplement the "unsupported construct emits
+ * `unknown`" behavior, which lives entirely in `weft codegen`'s emitter.
+ *
+ * @module core/contract/build
+ */
+import { WeftError } from '../weft-error.ts';
+import type { WorkflowContract, WorkflowContractSource } from './types.ts';
+/** Discriminates which part of a workflow contract source failed conversion. */
+type ContractEntityKind = 'workflow' | 'signal' | 'update' | 'query' | 'activity' | 'finalizer';
+/**
+ * Thrown when {@link buildWorkflowContract} cannot convert a registered
+ * `DefinitionSchema` to JSON Schema — no built-in vendor adapter and no
+ * structural `~standard.jsonSchema` converter. Mirrors
+ * `RegistrySchemaConversionError`'s `entityKind`/`entityName`/`direction`
+ * fields; not root-exported, matching that error's precedent (build-tooling
+ * errors surfaced to the caller of the builder, not part of the public error
+ * vocabulary).
+ *
+ * @example
+ * ```ts
+ * import { WorkflowContractConversionError } from '@lostgradient/weft';
+ *
+ * try {
+ *   throw new WorkflowContractConversionError('activity', 'charge', 'inputSchema', new Error('boom'));
+ * } catch (error) {
+ *   console.log(error instanceof WorkflowContractConversionError); // true
+ * }
+ * ```
+ */
+export declare class WorkflowContractConversionError extends WeftError<'WorkflowContractConversionError'> {
+    readonly entityKind: ContractEntityKind;
+    readonly entityName: string;
+    readonly direction: 'inputSchema' | 'outputSchema';
+    constructor(entityKind: ContractEntityKind, entityName: string, direction: 'inputSchema' | 'outputSchema', cause: unknown);
+}
+/**
+ * Build a normalized {@link WorkflowContract} from an authoring-time workflow
+ * definition.
+ *
+ * Accepts anything structurally matching {@link WorkflowContractSource} —
+ * both `WorkflowDefinition` and `BuiltWorkflowDefinition` (the return type
+ * of `workflow({...}).execute(fn)`) satisfy it directly, with no cast.
+ *
+ * Throws {@link WorkflowContractConversionError} if any declared schema
+ * (workflow input/output, a signal/update/query input/output, an activity
+ * input/output, or the finalizer's input/output) cannot be converted to JSON
+ * Schema.
+ *
+ * @example
+ * ```ts
+ * import { buildWorkflowContract } from '@lostgradient/weft';
+ *
+ * const contract = buildWorkflowContract({ name: 'checkout', version: '2.1.0' });
+ * console.log(contract.name, contract.workflowVersion); // checkout 2.1.0
+ * ```
+ */
+export declare function buildWorkflowContract(source: WorkflowContractSource): WorkflowContract;
+export {};

package/dist/core/contract/build.js

@@ -0,0 +1,99 @@
+import { definitionSchemaToJsonSchema } from "../types/definition-schema-to-json.js";
+import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
+import { WeftError } from "../weft-error.js";
+import { normalizeWorkflowContract } from "./normalize.js";
+
+export class WorkflowContractConversionError extends WeftError {
+  entityKind;
+  entityName;
+  direction;
+  constructor(entityKind, entityName, direction, cause) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    super("WorkflowContractConversionError", `Failed to convert ${direction} for ${entityKind} "${entityName}": ${causeMessage}`, { cause });
+    this.entityKind = entityKind;
+    this.entityName = entityName;
+    this.direction = direction;
+  }
+}
+function convertSchema(entityKind, entityName, direction, schema) {
+  try {
+    return definitionSchemaToJsonSchema(schema, direction === "inputSchema" ? "input" : "output");
+  } catch (cause) {
+    throw new WorkflowContractConversionError(entityKind, entityName, direction, cause);
+  }
+}
+function buildMessageContract(entityKind, entityName, source) {
+  const entry = {};
+  if (source.inputSchema !== void 0)
+    entry.inputSchema = convertSchema(entityKind, entityName, "inputSchema", source.inputSchema);
+  if (source.outputSchema !== void 0)
+    entry.outputSchema = convertSchema(entityKind, entityName, "outputSchema", source.outputSchema);
+  return entry;
+}
+function buildActivityContract(workflowName, activityName, source) {
+  return buildMessageContract("activity", `${workflowName}.${activityName}`, source);
+}
+function buildMessageRecord(workflowName, entityKind, sources) {
+  if (sources === void 0)
+    return;
+  const localKeys = Object.keys(sources);
+  if (localKeys.length === 0)
+    return;
+  const built = Object.create(null);
+  for (const localKey of localKeys) {
+    const source = sources[localKey], wireName = source.name;
+    if (Object.hasOwn(built, wireName))
+      throw Error(`Duplicate ${entityKind} runtime name "${wireName}" in workflow "${workflowName}"`);
+    built[wireName] = buildMessageContract(entityKind, `${workflowName}.${entityKind}.${wireName}`, source);
+  }
+  return built;
+}
+function buildActivityRecord(workflowName, sources) {
+  if (sources === void 0)
+    return;
+  const names = Object.keys(sources);
+  if (names.length === 0)
+    return;
+  const built = Object.create(null);
+  for (const name of names)
+    built[name] = buildActivityContract(workflowName, name, sources[name]);
+  return built;
+}
+function applyDescriptionAndTags(draft, source) {
+  if (source.description !== void 0)
+    draft.description = source.description;
+  if (source.tags !== void 0 && source.tags.length > 0)
+    draft.tags = [...source.tags];
+}
+function applySchemas(draft, source) {
+  if (source.inputSchema !== void 0)
+    draft.inputSchema = convertSchema("workflow", source.name, "inputSchema", source.inputSchema);
+  if (source.outputSchema !== void 0)
+    draft.outputSchema = convertSchema("workflow", source.name, "outputSchema", source.outputSchema);
+}
+function applyMessageRecords(draft, source) {
+  const signals = buildMessageRecord(source.name, "signal", source.signals);
+  if (signals !== void 0)
+    draft.signals = signals;
+  const updates = buildMessageRecord(source.name, "update", source.updates);
+  if (updates !== void 0)
+    draft.updates = updates;
+  const queries = buildMessageRecord(source.name, "query", source.queries);
+  if (queries !== void 0)
+    draft.queries = queries;
+}
+export function buildWorkflowContract(source) {
+  const draft = {
+    name: source.name,
+    workflowVersion: source.version ?? DEFAULT_WORKFLOW_VERSION
+  };
+  applyDescriptionAndTags(draft, source);
+  applySchemas(draft, source);
+  applyMessageRecords(draft, source);
+  const activities = buildActivityRecord(source.name, source.activities);
+  if (activities !== void 0)
+    draft.activities = activities;
+  if (source.finalizer !== void 0)
+    draft.finalizer = buildMessageContract("finalizer", `${source.name}.finalizer`, source.finalizer);
+  return normalizeWorkflowContract(draft);
+}

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

@@ -0,0 +1,187 @@
+/**
+ * Structured compatibility verdicts between two workflow revision manifests.
+ *
+ * `checkWorkflowCompatibility()` answers "may `candidate` automatically
+ * activate in place of `current`" as a bounded, machine-readable
+ * {@link WorkflowCompatibilityVerdict} rather than a thrown error or a bare
+ * boolean—a catalog or refresh orchestrator can report every reason a
+ * candidate revision was rejected, but never override one during automatic
+ * activation (the reasons are policy-fixed except for one deliberate knob,
+ * see {@link WorkflowCompatibilityPolicy}).
+ *
+ * The five reasons this module can report mirror, and in one case literally
+ * call, checks that already exist elsewhere in the codebase rather than
+ * reinventing them:
+ *
+ * - `workflow-version-incompatible` calls {@link checkVersionCompatibility}
+ *   from `core/versioning.ts`—the exact primitive
+ *   `derivePreparedExecutionState()` (`core/engine/lifecycle/persist.ts`)
+ *   already uses to reject a stored checkpoint against a re-registered
+ *   workflow. This module never modifies that primitive; it reuses it as-is
+ *   so the two answers can never disagree.
+ * - `contract-hash-mismatch` and `manifest-version-unsupported` reuse the
+ *   same names `parseWorkflowRevisionManifest()`
+ *   (`WorkflowRevisionManifestRejectionReason`, `./failure.ts`) already uses
+ *   for structurally similar situations—hostile-input rejection there,
+ *   activation compatibility here. The two unions are intentionally
+ *   independent; the shared literal is vocabulary reuse, not a coupling.
+ *   `manifest-version-unsupported` specifically is unreachable through this
+ *   module's own type-safe surface today—`WorkflowRevisionManifest.manifestVersion`
+ *   is typed as the single supported literal, and every in-repo producer
+ *   ({@link buildWorkflowRevisionManifest}, {@link parseWorkflowRevisionManifest})
+ *   guarantees it—so it costs nothing to check here and exists for the
+ *   consumer this module is exported for but does not yet have: a future
+ *   catalog or refresh system comparing a manifest it read from storage or
+ *   the wire, which may not have round-tripped through
+ *   `parseWorkflowRevisionManifest()` immediately before the comparison.
+ *   Widening the parameter type to accept that case is deferred to whichever
+ *   catalog work (WFT-9) first needs a type-safe way to trigger it.
+ *
+ * `checkWorkflowCompatibility()` is pure and synchronous: both manifests
+ * already carry their computed `contractHash`/`revision`, so no hashing
+ * happens here.
+ *
+ * @module core/contract/compatibility
+ */
+import type { WorkflowRevisionManifest } from './types.ts';
+/**
+ * One bounded, machine-readable reason `candidate` is not compatible with
+ * `current`. Closed union, safe to use as a metric label—exactly the five
+ * reasons named by the Activation Compatibility issue, in the fixed order
+ * {@link checkWorkflowCompatibility} evaluates and reports them.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowCompatibilityReason } from '@lostgradient/weft';
+ *
+ * const counts = new Map<WorkflowCompatibilityReason, number>();
+ * counts.set('contract-hash-mismatch', 1);
+ * console.log(counts.get('contract-hash-mismatch'));
+ * ```
+ */
+export type WorkflowCompatibilityReason = 'name-mismatch' | 'manifest-version-unsupported' | 'contract-hash-mismatch' | 'workflow-version-incompatible' | 'artifact-revision-mismatch';
+/**
+ * The structured result of {@link checkWorkflowCompatibility}: either fully
+ * compatible, or incompatible with the complete, ordered list of every
+ * applicable {@link WorkflowCompatibilityReason}—never just the first one
+ * found. A refresh orchestrator may report every reason here; it may never
+ * treat an incompatible verdict as compatible during automatic activation.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowCompatibilityVerdict } from '@lostgradient/weft';
+ *
+ * const verdict: WorkflowCompatibilityVerdict = {
+ *   compatible: false,
+ *   reasons: ['contract-hash-mismatch'],
+ * };
+ * console.log(verdict.compatible ? 'ok' : verdict.reasons.join(', '));
+ * ```
+ */
+export type WorkflowCompatibilityVerdict = Readonly<{
+    compatible: true;
+}> | Readonly<{
+    compatible: false;
+    reasons: readonly WorkflowCompatibilityReason[];
+}>;
+/**
+ * Declared compatibility policy accepted by {@link checkWorkflowCompatibility}.
+ *
+ * `requireExactRevision` is the *only* tunable axis. `name-mismatch`,
+ * `manifest-version-unsupported`, `contract-hash-mismatch`, and
+ * `workflow-version-incompatible` can never be loosened by policy—a
+ * refresh system may report those reasons but may not override them during
+ * automatic activation, which is the literal mechanism the Activation
+ * Compatibility issue asks for.
+ *
+ * - `true` (the strict default): a candidate whose `revision` differs from
+ *   `current`'s—even when `contractHash` is identical—reports
+ *   `artifact-revision-mismatch` and is not compatible.
+ * - `false`: a `revision`-only difference is tolerated; `artifact-revision-mismatch`
+ *   is never reported. What that difference *means* depends on how `revision`
+ *   was produced. Under the default content-derived revision
+ *   ({@link deriveWorkflowRevision}), a `revision`-only difference is always a
+ *   documentation-only edit (`contract.description` or `contract.tags`, since
+ *   `contractHash` deliberately excludes both). Under a caller-supplied
+ *   revision (`buildWorkflowRevisionManifest(contract, { revision })`), a
+ *   `revision`-only difference can be any artifact-identity change the caller
+ *   chose to encode there (a build id, a deployment tag)—`false` tolerates
+ *   that too, since this module has no way to distinguish an opaque supplied
+ *   revision from a derived one by inspecting the manifest alone. Do not set
+ *   `false` when your manifests use explicit revisions unless you intend to
+ *   accept any `revision` change as compatible. Under the default
+ *   content-derived revision, a `contractHash` difference always implies a
+ *   `revision` difference too (`revision`'s full-contract digest is a strict
+ *   superset of what `contractHash` covers); under a caller-supplied
+ *   revision, two manifests can share the same `revision` string despite
+ *   different `contractHash` values, since the caller controls that string
+ *   independently of contract content. Either way,
+ *   `contract-hash-mismatch` is unaffected by this setting and still blocks
+ *   activation on its own.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowCompatibilityPolicy } from '@lostgradient/weft';
+ *
+ * const lenient: WorkflowCompatibilityPolicy = { requireExactRevision: false };
+ * console.log(lenient.requireExactRevision);
+ * ```
+ */
+export interface WorkflowCompatibilityPolicy {
+    /**
+     * Whether an exact `revision` match is required for compatibility, on top
+     * of the four never-tunable reasons. Defaults to `true` when omitted or
+     * when the policy object itself omits the field.
+     */
+    requireExactRevision?: boolean;
+}
+/**
+ * The strict default policy `checkWorkflowCompatibility` uses when no
+ * policy argument is supplied. Exported so a catalog can name the default
+ * explicitly—in a log line, a configuration default, a test fixture—rather
+ * than relying on an implicit fallback. Frozen: `checkWorkflowCompatibility`
+ * consults this exact object as the default argument for every call that
+ * omits a policy, so a caller that mutated it would silently change the
+ * default for every other caller in the process.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_WORKFLOW_COMPATIBILITY_POLICY } from '@lostgradient/weft';
+ *
+ * console.log(DEFAULT_WORKFLOW_COMPATIBILITY_POLICY.requireExactRevision); // true
+ * ```
+ */
+export declare const DEFAULT_WORKFLOW_COMPATIBILITY_POLICY: Readonly<Required<WorkflowCompatibilityPolicy>>;
+/**
+ * Compare two workflow revision manifests and report whether `candidate` is
+ * compatible with `current`—the pure comparison behind automatic
+ * activation. Symmetric: `checkWorkflowCompatibility(a, b, policy)` and
+ * `checkWorkflowCompatibility(b, a, policy)` always agree, since every
+ * underlying check is an equality or bounded-value comparison with no
+ * directionality.
+ *
+ * Every applicable reason is collected and returned in the fixed order
+ * `name-mismatch`, `manifest-version-unsupported`, `contract-hash-mismatch`,
+ * `workflow-version-incompatible`, `artifact-revision-mismatch`—the
+ * function never short-circuits on the first reason found.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   buildWorkflowContract,
+ *   buildWorkflowRevisionManifest,
+ *   checkWorkflowCompatibility,
+ * } from '@lostgradient/weft';
+ *
+ * const current = await buildWorkflowRevisionManifest(
+ *   buildWorkflowContract({ name: 'checkout', version: '1.0.0' }),
+ * );
+ * const candidate = await buildWorkflowRevisionManifest(
+ *   buildWorkflowContract({ name: 'checkout', version: '2.0.0' }),
+ * );
+ *
+ * const verdict = checkWorkflowCompatibility(current, candidate);
+ * console.log(verdict.compatible); // false
+ * ```
+ */
+export declare function checkWorkflowCompatibility(current: WorkflowRevisionManifest, candidate: WorkflowRevisionManifest, policy?: WorkflowCompatibilityPolicy): WorkflowCompatibilityVerdict;

package/dist/core/contract/compatibility.js

@@ -0,0 +1,37 @@
+import { checkVersionCompatibility } from "../versioning.js";
+import { WORKFLOW_REVISION_MANIFEST_VERSION } from "./types.js";
+export const DEFAULT_WORKFLOW_COMPATIBILITY_POLICY = Object.freeze({
+  requireExactRevision: !0
+});
+function isSupportedWorkflowRevisionManifestVersion(version) {
+  return version === WORKFLOW_REVISION_MANIFEST_VERSION;
+}
+function isNameMismatch(current, candidate) {
+  return current.name !== candidate.name;
+}
+function isManifestVersionUnsupported(current, candidate) {
+  return !isSupportedWorkflowRevisionManifestVersion(current.manifestVersion) || !isSupportedWorkflowRevisionManifestVersion(candidate.manifestVersion);
+}
+function isContractHashMismatch(current, candidate) {
+  return current.contractHash !== candidate.contractHash;
+}
+function isWorkflowVersionIncompatible(current, candidate) {
+  return checkVersionCompatibility(current.workflowVersion, candidate.workflowVersion) === "incompatible";
+}
+function isArtifactRevisionMismatch(current, candidate) {
+  return current.revision !== candidate.revision;
+}
+export function checkWorkflowCompatibility(current, candidate, policy = DEFAULT_WORKFLOW_COMPATIBILITY_POLICY) {
+  const requireExactRevision = policy.requireExactRevision ?? !0, reasons = [];
+  if (isNameMismatch(current, candidate))
+    reasons.push("name-mismatch");
+  if (isManifestVersionUnsupported(current, candidate))
+    reasons.push("manifest-version-unsupported");
+  if (isContractHashMismatch(current, candidate))
+    reasons.push("contract-hash-mismatch");
+  if (isWorkflowVersionIncompatible(current, candidate))
+    reasons.push("workflow-version-incompatible");
+  if (requireExactRevision && isArtifactRevisionMismatch(current, candidate))
+    reasons.push("artifact-revision-mismatch");
+  return reasons.length === 0 ? { compatible: !0 } : { compatible: !1, reasons };
+}

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];
+}