@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/catalog/workflow-catalog.js

@@ -0,0 +1,198 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { compareCodepoint } from "../compare-codepoint.js";
+import {
+  checkWorkflowCompatibility,
+  DEFAULT_WORKFLOW_COMPATIBILITY_POLICY
+} from "../contract/compatibility.js";
+import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+import { encodeActivePointer, manifestsAreByteIdentical } from "./codec.js";
+import {
+  WorkflowCatalogActivationConflictError,
+  WorkflowCatalogActiveEntryMissingError,
+  WorkflowCatalogConflictError
+} from "./errors.js";
+import { removeCatalogEntry } from "./removal.js";
+import {
+  readActivePointer,
+  readCatalogEntry,
+  scanCatalogEntriesForName,
+  writeCatalogEntry
+} from "./storage-io.js";
+const MAX_ACTIVATE_REGISTERED_ATTEMPTS = 5;
+
+export class WorkflowCatalog {
+  #storage;
+  #entries;
+  #active;
+  constructor(storage, seed) {
+    this.#storage = storage;
+    this.#entries = seed?.entries ?? new Map;
+    this.#active = seed?.active ?? new Map;
+  }
+  getEntry(name, revision) {
+    return this.#entries.get(name)?.get(revision);
+  }
+  listRevisions(name) {
+    const byName = this.#entries.get(name);
+    return byName === void 0 ? [] : [...byName.values()];
+  }
+  resolveActive(name) {
+    return this.#active.get(name);
+  }
+  async resolveEntry(name, revision) {
+    const cached = this.getEntry(name, revision);
+    if (cached !== void 0)
+      return { manifest: cached.manifest, installedAt: cached.installedAt };
+    const durable = await readCatalogEntry(this.#storage, name, revision);
+    if (durable === null)
+      return;
+    this.#cacheEntry(name, revision, durable);
+    return durable;
+  }
+  async listInstalledRevisions(name) {
+    return (await scanCatalogEntriesForName(this.#storage, name)).toSorted((a, b) => compareCodepoint(a.manifest.revision, b.manifest.revision));
+  }
+  async hasInstalled(name, revision) {
+    if (this.getEntry(name, revision) !== void 0)
+      return !0;
+    return await readCatalogEntry(this.#storage, name, revision) !== null;
+  }
+  async resolveActiveDurable(name) {
+    return await readActivePointer(this.#storage, name) ?? void 0;
+  }
+  async remove(name, revision) {
+    requireStorageCapability(this.#storage, "conditionalBatch", "workflow catalog removal");
+    const result = await removeCatalogEntry(this.#storage, name, revision);
+    if (result.outcome === "removed")
+      this.#entries.get(name)?.delete(revision);
+    return result;
+  }
+  async install(manifest, definition) {
+    validateWorkflowOrActivityName(manifest.name, "workflow");
+    const existing = this.getEntry(manifest.name, manifest.revision);
+    if (existing !== void 0) {
+      if (!manifestsAreByteIdentical(existing.manifest, manifest))
+        throw new WorkflowCatalogConflictError(manifest.name, manifest.revision);
+      return existing;
+    }
+    const durable = await readCatalogEntry(this.#storage, manifest.name, manifest.revision);
+    if (durable !== null)
+      return this.#adoptDurableEntry(manifest, durable, definition);
+    const installedAt = Date.now();
+    if (!await writeCatalogEntry(this.#storage, manifest, installedAt)) {
+      const raced = await readCatalogEntry(this.#storage, manifest.name, manifest.revision);
+      if (raced === null)
+        throw new WorkflowCatalogConflictError(manifest.name, manifest.revision);
+      return this.#adoptDurableEntry(manifest, raced, definition);
+    }
+    return this.#cacheEntry(manifest.name, manifest.revision, {
+      manifest,
+      installedAt,
+      ...definition === void 0 ? {} : { definition }
+    });
+  }
+  #adoptDurableEntry(manifest, durable, definition) {
+    if (!manifestsAreByteIdentical(durable.manifest, manifest))
+      throw new WorkflowCatalogConflictError(manifest.name, manifest.revision);
+    return this.#cacheEntry(manifest.name, manifest.revision, {
+      manifest: durable.manifest,
+      installedAt: durable.installedAt,
+      ...definition === void 0 ? {} : { definition }
+    });
+  }
+  #cacheEntry(name, revision, entry) {
+    let byName = this.#entries.get(name);
+    if (byName === void 0) {
+      byName = new Map;
+      this.#entries.set(name, byName);
+    }
+    byName.set(revision, entry);
+    return entry;
+  }
+  async activateRegistered(name, manifest, definition) {
+    requireStorageCapability(this.#storage, "conditionalBatch", "workflow catalog activation");
+    await this.install(manifest, definition);
+    for (let attempt = 1;attempt <= MAX_ACTIVATE_REGISTERED_ATTEMPTS; attempt++) {
+      const current = await readActivePointer(this.#storage, name);
+      if (current !== null && current.revision === manifest.revision) {
+        this.#active.set(name, current);
+        return current;
+      }
+      const nextGeneration = current === null ? 1 : current.generation + 1, nextPointer = {
+        revision: manifest.revision,
+        generation: nextGeneration,
+        activatedAt: Date.now()
+      };
+      if (await storageConditionalBatch(this.#storage, [
+        {
+          key: KEYS.catalogActive(name),
+          expectedValue: current === null ? null : encodeActivePointer(current)
+        }
+      ], [{ type: "put", key: KEYS.catalogActive(name), value: encodeActivePointer(nextPointer) }])) {
+        this.#active.set(name, nextPointer);
+        return nextPointer;
+      }
+    }
+    throw new WorkflowCatalogActivationConflictError(name, MAX_ACTIVATE_REGISTERED_ATTEMPTS);
+  }
+  async activateCandidate(name, candidateManifest, options) {
+    requireStorageCapability(this.#storage, "conditionalBatch", "workflow catalog activation");
+    await this.install(candidateManifest);
+    const currentPointer = await readActivePointer(this.#storage, name), refusal = await this.#refuseIncompatibleOrStaleCandidate(name, candidateManifest, currentPointer, options);
+    if (refusal !== void 0)
+      return refusal;
+    const nextGeneration = currentPointer === null ? 1 : currentPointer.generation + 1, nextPointer = {
+      revision: candidateManifest.revision,
+      generation: nextGeneration,
+      activatedAt: Date.now()
+    };
+    if (!await storageConditionalBatch(this.#storage, [
+      {
+        key: KEYS.catalogActive(name),
+        expectedValue: currentPointer === null ? null : encodeActivePointer(currentPointer)
+      }
+    ], [{ type: "put", key: KEYS.catalogActive(name), value: encodeActivePointer(nextPointer) }]))
+      return { applied: !1, reason: "conflict" };
+    this.#active.set(name, nextPointer);
+    return { applied: !0, pointer: nextPointer };
+  }
+  async#refuseIncompatibleOrStaleCandidate(name, candidateManifest, currentPointer, options) {
+    if (currentPointer === null)
+      return this.#refuseStaleFirstActivation(options);
+    const generationRefusal = this.#refuseMissingOrStaleGeneration(currentPointer, options);
+    if (generationRefusal !== void 0)
+      return generationRefusal;
+    return this.#refuseIncompatibleCandidate(name, candidateManifest, currentPointer, options);
+  }
+  #refuseStaleFirstActivation(options) {
+    if (options?.expectedGeneration !== void 0 && options.expectedGeneration !== 0)
+      return { applied: !1, reason: "stale-generation", currentGeneration: 0 };
+    return;
+  }
+  #refuseMissingOrStaleGeneration(currentPointer, options) {
+    if (options?.expectedGeneration === void 0)
+      return {
+        applied: !1,
+        reason: "expected-generation-required",
+        currentGeneration: currentPointer.generation
+      };
+    if (options.expectedGeneration !== currentPointer.generation)
+      return {
+        applied: !1,
+        reason: "stale-generation",
+        currentGeneration: currentPointer.generation
+      };
+    return;
+  }
+  async#refuseIncompatibleCandidate(name, candidateManifest, currentPointer, options) {
+    const currentEntry = await this.resolveEntry(name, currentPointer.revision);
+    if (currentEntry === void 0)
+      throw new WorkflowCatalogActiveEntryMissingError(name, currentPointer.revision);
+    const verdict = checkWorkflowCompatibility(currentEntry.manifest, candidateManifest, options?.policy ?? DEFAULT_WORKFLOW_COMPATIBILITY_POLICY);
+    return verdict.compatible ? void 0 : { applied: !1, reason: "incompatible", verdict };
+  }
+}

package/dist/core/compare-codepoint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Order two strings by codepoint rather than `localeCompare` (project rule:
+ * deterministic comparisons in runtime logic). A standalone leaf module so
+ * every codepoint sort across the registry-snapshot family of modules —
+ * `registry-snapshot.ts`'s `sortedWorkflows`/`sortedActivities` and
+ * `registry-workflow-manifest.ts`'s scoped-activity sort — shares one
+ * implementation of the unreachable-in-isolation tie branch, rather than
+ * each defining its own uncovered copy, without creating an import cycle
+ * between those two modules.
+ *
+ * @module core/compare-codepoint
+ */
+export declare function compareCodepoint(a: string, b: string): number;

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