@lostgradient/weft 0.23.1 → 0.24.0

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

@@ -0,0 +1,97 @@
+/**
+ * Deterministic normalization and canonical serialization for workflow
+ * contracts.
+ *
+ * Two contracts that describe the same workflow must produce byte-identical
+ * canonical output regardless of how their object keys were ordered in the
+ * source, so `contractHash()` and `deriveWorkflowRevision()` identify the
+ * *content* rather than an accident of construction. Serialization walks the
+ * declared contract shape explicitly instead of generically stringifying the
+ * input, which means an unknown extra property can never leak into the
+ * canonical bytes and change a hash.
+ *
+ * @module core/contract/normalize
+ */
+import type { WorkflowContract, WorkflowMessageContract } from './types.ts';
+/**
+ * Normalize a workflow contract into its canonical in-memory form.
+ *
+ * Field order follows the declared shape, every open-ended record is
+ * rebuilt with its keys sorted (and omitted entirely when empty), and every
+ * schema fragment is deep-cloned onto a null-prototype object. The result is
+ * a fresh value; the input is not mutated.
+ *
+ * @example
+ * ```ts
+ * import { normalizeWorkflowContract } from '@lostgradient/weft';
+ *
+ * const normalized = normalizeWorkflowContract({
+ *   name: 'checkout',
+ *   workflowVersion: '2.1.0',
+ *   signals: {
+ *     zeta: {},
+ *     alpha: {},
+ *   },
+ * });
+ * console.log(Object.keys(normalized.signals ?? {})); // ['alpha', 'zeta']
+ * ```
+ */
+export declare function normalizeWorkflowContract(contract: WorkflowContract): WorkflowContract;
+/**
+ * Serialize one signal/update/query/activity contract's schema pair.
+ * Shared between {@link canonicalWorkflowContractJson} (the full-identity
+ * form) and `hash.ts`'s payload-only serialization, since both walk the same
+ * `{ inputSchema?, outputSchema? }` shape — the only difference between the
+ * two identities is which *top-level* fields are included, not how a single
+ * message/activity entry serializes.
+ *
+ * @internal Exported for reuse within `core/contract/*`; not part of the
+ * package's public API.
+ */
+export declare function canonicalMessageContractJson(entry: WorkflowMessageContract): string;
+/**
+ * @internal Exported for reuse within `core/contract/*`; not part of the
+ * package's public API.
+ */
+export declare function canonicalContractRecordJson(record: Readonly<Record<string, WorkflowMessageContract>>): string;
+/**
+ * @internal Exported for reuse within `core/contract/*` (`hash.ts`'s
+ * payload-only serialization shares this field-appending logic); not part of
+ * the package's public API.
+ */
+export declare function appendContractRecordField(fields: string[], label: 'signals' | 'updates' | 'queries' | 'activities', record: Readonly<Record<string, WorkflowMessageContract>> | undefined): void;
+/**
+ * @internal Exported for reuse within `core/contract/*`; not part of the
+ * package's public API.
+ */
+export declare function appendSchemaField(fields: string[], label: 'inputSchema' | 'outputSchema', schema: Record<string, unknown> | undefined): void;
+/**
+ * Serialize a workflow contract to its canonical, full-identity JSON string
+ * — the digest input {@link deriveWorkflowRevision} uses, and the value
+ * returned as `WorkflowRevisionManifestParseSuccess.canonicalJson`.
+ *
+ * This is a *different* identity from {@link contractHash}'s payload-only
+ * serialization: it includes `name`, `workflowVersion`, `description`, and
+ * `tags`, so a documentation edit changes this output (and therefore
+ * `revision`) without changing `contractHash`. The output is byte-identical
+ * for equivalent contracts regardless of source key order, and every field
+ * this project cares about changes it.
+ *
+ * @example
+ * ```ts
+ * import { canonicalWorkflowContractJson } from '@lostgradient/weft';
+ *
+ * const left = canonicalWorkflowContractJson({
+ *   name: 'checkout',
+ *   workflowVersion: '2.1.0',
+ *   signals: { alpha: {}, zeta: {} },
+ * });
+ * const right = canonicalWorkflowContractJson({
+ *   name: 'checkout',
+ *   workflowVersion: '2.1.0',
+ *   signals: { zeta: {}, alpha: {} },
+ * });
+ * console.log(left === right); // true
+ * ```
+ */
+export declare function canonicalWorkflowContractJson(contract: WorkflowContract): string;

package/dist/core/contract/normalize.js

@@ -0,0 +1,127 @@
+import { canonicalJsonStringify } from "../../worker/manifest/canonical-json.js";
+import { WORKFLOW_CONTRACT_VERSION } from "./types.js";
+function sortedKeys(record) {
+  return Object.keys(record).toSorted();
+}
+function cloneSchemaFragment(value) {
+  if (value === null || typeof value !== "object")
+    return value;
+  if (Array.isArray(value))
+    return value.map((entry) => cloneSchemaFragment(entry));
+  const record = value, cloned = Object.create(null);
+  for (const key of Object.keys(record))
+    cloned[key] = cloneSchemaFragment(record[key]);
+  return cloned;
+}
+function cloneSchemaRecord(value) {
+  return value === void 0 ? void 0 : cloneSchemaFragment(value);
+}
+function normalizeMessageContract(entry) {
+  const normalized = {}, inputSchema = cloneSchemaRecord(entry.inputSchema);
+  if (inputSchema !== void 0)
+    normalized.inputSchema = inputSchema;
+  const outputSchema = cloneSchemaRecord(entry.outputSchema);
+  if (outputSchema !== void 0)
+    normalized.outputSchema = outputSchema;
+  return normalized;
+}
+function normalizeActivityContract(entry) {
+  return normalizeMessageContract(entry);
+}
+function sortedContractRecord(record, normalizeValue) {
+  if (record === void 0)
+    return;
+  const keys = sortedKeys(record);
+  if (keys.length === 0)
+    return;
+  const normalized = Object.create(null);
+  for (const key of keys)
+    normalized[key] = normalizeValue(record[key]);
+  return normalized;
+}
+function applyDescriptionAndTags(draft, contract) {
+  if (contract.description !== void 0)
+    draft.description = contract.description;
+  if (contract.tags !== void 0 && contract.tags.length > 0)
+    draft.tags = [...contract.tags].toSorted();
+}
+function applySchemas(draft, contract) {
+  const inputSchema = cloneSchemaRecord(contract.inputSchema);
+  if (inputSchema !== void 0)
+    draft.inputSchema = inputSchema;
+  const outputSchema = cloneSchemaRecord(contract.outputSchema);
+  if (outputSchema !== void 0)
+    draft.outputSchema = outputSchema;
+}
+function applyMessageRecords(draft, contract) {
+  const signals = sortedContractRecord(contract.signals, normalizeMessageContract);
+  if (signals !== void 0)
+    draft.signals = signals;
+  const updates = sortedContractRecord(contract.updates, normalizeMessageContract);
+  if (updates !== void 0)
+    draft.updates = updates;
+  const queries = sortedContractRecord(contract.queries, normalizeMessageContract);
+  if (queries !== void 0)
+    draft.queries = queries;
+}
+export function normalizeWorkflowContract(contract) {
+  const draft = {
+    name: contract.name,
+    workflowVersion: contract.workflowVersion
+  };
+  applyDescriptionAndTags(draft, contract);
+  applySchemas(draft, contract);
+  applyMessageRecords(draft, contract);
+  const activities = sortedContractRecord(contract.activities, normalizeActivityContract);
+  if (activities !== void 0)
+    draft.activities = activities;
+  if (contract.finalizer !== void 0)
+    draft.finalizer = normalizeActivityContract(contract.finalizer);
+  return draft;
+}
+export function canonicalMessageContractJson(entry) {
+  const fields = [];
+  if (entry.inputSchema !== void 0)
+    fields.push(`"inputSchema":${canonicalJsonStringify(entry.inputSchema)}`);
+  if (entry.outputSchema !== void 0)
+    fields.push(`"outputSchema":${canonicalJsonStringify(entry.outputSchema)}`);
+  return `{${fields.join(",")}}`;
+}
+export function canonicalContractRecordJson(record) {
+  return `{${sortedKeys(record).map((key) => `${JSON.stringify(key)}:${canonicalMessageContractJson(record[key])}`).join(",")}}`;
+}
+export function appendContractRecordField(fields, label, record) {
+  if (record === void 0 || Object.keys(record).length === 0)
+    return;
+  fields.push(`"${label}":${canonicalContractRecordJson(record)}`);
+}
+export function appendSchemaField(fields, label, schema) {
+  if (schema === void 0)
+    return;
+  fields.push(`"${label}":${canonicalJsonStringify(schema)}`);
+}
+function appendTagsField(fields, tags) {
+  if (tags === void 0 || tags.length === 0)
+    return;
+  const sortedTags = [...tags].toSorted().map((tag) => JSON.stringify(tag));
+  fields.push(`"tags":[${sortedTags.join(",")}]`);
+}
+export function canonicalWorkflowContractJson(contract) {
+  const fields = [
+    `"contractVersion":${JSON.stringify(WORKFLOW_CONTRACT_VERSION)}`,
+    `"name":${JSON.stringify(contract.name)}`,
+    `"workflowVersion":${JSON.stringify(contract.workflowVersion)}`
+  ];
+  if (contract.description !== void 0)
+    fields.push(`"description":${JSON.stringify(contract.description)}`);
+  appendTagsField(fields, contract.tags);
+  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(",")}}`;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Content-derived workflow revision identity.
+ *
+ * `revision` is the broader identity companion to `contractHash`: it hashes
+ * the *entire* normalized contract — `name`, `workflowVersion`,
+ * `description`, and `tags` included — so it changes whenever anything
+ * about the definition changes, including documentation. This is the same
+ * formula the (now-refactored) `buildWorkerManifestFromRegistry()` used for
+ * its `workflowRevision` field before this module existed.
+ *
+ * @module core/contract/revision
+ */
+import type { WorkflowContract } from './types.ts';
+/**
+ * Derive a content-addressed revision identity for a workflow contract.
+ *
+ * Two calls on an equivalent contract (regardless of source key order)
+ * produce the same revision, and any field the full canonical serialization
+ * carries — including `description` and `tags` — changes it.
+ *
+ * @example
+ * ```ts
+ * import { deriveWorkflowRevision } from '@lostgradient/weft';
+ *
+ * const revision = await deriveWorkflowRevision({ name: 'checkout', workflowVersion: '2.1.0' });
+ * console.log(revision.startsWith('sha256:')); // true
+ * ```
+ */
+export declare function deriveWorkflowRevision(contract: WorkflowContract): Promise<string>;

package/dist/core/contract/revision.js

@@ -0,0 +1,5 @@
+import { digestCanonicalWorkflowContract } from "./hash.js";
+import { canonicalWorkflowContractJson } from "./normalize.js";
+export async function deriveWorkflowRevision(contract) {
+  return digestCanonicalWorkflowContract(canonicalWorkflowContractJson(contract));
+}

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

@@ -0,0 +1,274 @@
+/**
+ * Canonical, normalized workflow contract vocabulary.
+ *
+ * A `WorkflowContract` is the single normalized representation that feeds
+ * both TypeScript code generation (`weft codegen`) and `contractHash()` — the
+ * same data, described once, rather than two independent derivations that
+ * could silently drift apart. `WorkflowRevisionManifest` pairs that contract
+ * with the two identity questions a consumer asks about a workflow revision:
+ *
+ * | Field          | Question answered                                    | Stability                    |
+ * | -------------- | ----------------------------------------------------- | ----------------------------- |
+ * | `contractHash` | Which public payload contract does this revision use? | Deterministic, payload-only   |
+ * | `revision`     | Which contract-metadata identity (name, version, docs) is this? | Deterministic or author-set   |
+ *
+ * `contractHash` deliberately excludes `name`, `workflowVersion`,
+ * `description`, and `tags` — those identify *which* workflow and *how it is
+ * documented*, not *what callers may send and expect back*. `revision` is the
+ * broader identity: it changes on a documentation edit even when the payload
+ * contract does not, which is what lets a caller detect "the same contract,
+ * redeployed" versus "a genuinely different definition was loaded."
+ *
+ * @module core/contract/types
+ */
+import type { DefinitionSchema } from '../types/definition-schema.ts';
+/**
+ * Domain separator folded into every `contractHash()`/`deriveWorkflowRevision()`
+ * digest. Bumping this constant is how a future normalization change is
+ * guaranteed to produce a different hash rather than silently colliding with
+ * one computed under the old rules.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_CONTRACT_VERSION } from '@lostgradient/weft';
+ *
+ * console.log(WORKFLOW_CONTRACT_VERSION); // 1
+ * ```
+ */
+export declare const WORKFLOW_CONTRACT_VERSION = 1;
+/**
+ * Normalized JSON Schema pair carried by one workflow signal, update, or
+ * query.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowMessageContract } from '@lostgradient/weft';
+ *
+ * const approval: WorkflowMessageContract = {
+ *   inputSchema: { type: 'object', properties: { approved: { type: 'boolean' } } },
+ * };
+ * console.log(approval.inputSchema?.['type']);
+ * ```
+ */
+export type WorkflowMessageContract = Readonly<{
+    /** Normalized JSON Schema describing accepted input, when the message accepts one. */
+    inputSchema?: Record<string, unknown>;
+    /** Normalized JSON Schema describing the returned value, when the message returns one. */
+    outputSchema?: Record<string, unknown>;
+}>;
+/**
+ * Normalized JSON Schema pair carried by one activity a workflow contract
+ * exposes.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowActivityContract } from '@lostgradient/weft';
+ *
+ * const charge: WorkflowActivityContract = {
+ *   inputSchema: { type: 'object', properties: { amount: { type: 'number' } } },
+ *   outputSchema: { type: 'object', properties: { id: { type: 'string' } } },
+ * };
+ * console.log(charge.inputSchema?.['type']);
+ * ```
+ */
+export type WorkflowActivityContract = Readonly<{
+    /** Normalized JSON Schema describing accepted input, when the activity accepts one. */
+    inputSchema?: Record<string, unknown>;
+    /** Normalized JSON Schema describing the returned value, when the activity returns one. */
+    outputSchema?: Record<string, unknown>;
+}>;
+/**
+ * Canonical, normalized representation of one workflow's public contract —
+ * everything callers may send it and expect back, plus enough identity
+ * metadata (`name`, `workflowVersion`, `description`, `tags`) to describe
+ * which workflow this is. This is the single input to both TypeScript
+ * emission and `contractHash()`.
+ *
+ * Every open-ended record (`signals`, `updates`, `queries`, `activities`) is
+ * omitted entirely rather than present-but-empty, matching the registry
+ * snapshot's "absent fields omitted, never `null` or `{}`" convention — see
+ * {@link normalizeWorkflowContract}.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowContract } from '@lostgradient/weft';
+ *
+ * const checkout: WorkflowContract = {
+ *   name: 'checkout',
+ *   workflowVersion: '2.1.0',
+ *   inputSchema: { type: 'object', properties: { cartId: { type: 'string' } } },
+ *   activities: {
+ *     charge: { inputSchema: { type: 'object', properties: { amount: { type: 'number' } } } },
+ *   },
+ * };
+ * console.log(checkout.name);
+ * ```
+ */
+export type WorkflowContract = Readonly<{
+    /** Wire-safe workflow name. */
+    name: string;
+    /** Semantic replay-compatibility boundary declared by the workflow author. */
+    workflowVersion: string;
+    /** User-facing description. Excluded from `contractHash()`; included in `revision`. */
+    description?: string;
+    /** User-facing grouping tags. Excluded from `contractHash()`; included in `revision`. */
+    tags?: ReadonlyArray<string>;
+    /** Normalized JSON Schema describing accepted workflow input, when declared. */
+    inputSchema?: Record<string, unknown>;
+    /** Normalized JSON Schema describing the workflow result, when declared. */
+    outputSchema?: Record<string, unknown>;
+    /** Signal contracts keyed by canonical signal name. */
+    signals?: Readonly<Record<string, WorkflowMessageContract>>;
+    /** Update contracts keyed by canonical update name. */
+    updates?: Readonly<Record<string, WorkflowMessageContract>>;
+    /** Query contracts keyed by canonical query name. */
+    queries?: Readonly<Record<string, WorkflowMessageContract>>;
+    /** Activity contracts keyed by canonical activity name. */
+    activities?: Readonly<Record<string, WorkflowActivityContract>>;
+    /** Contract of the workflow's definition-level finalizer activity, when declared. */
+    finalizer?: WorkflowActivityContract;
+}>;
+/**
+ * Structural shape one signal, update, or query source must satisfy for
+ * {@link buildWorkflowContract} to convert it. Deliberately narrower than
+ * `SignalDefinition`/`UpdateDefinition`/`QueryDefinition` — only the schema
+ * metadata those conversions need — so any of the three handle types (and
+ * any structurally equivalent value) satisfies it without a cast.
+ *
+ * @example
+ * ```ts
+ * import { signal } from '@lostgradient/weft';
+ * import type { WorkflowContractMessageSource } from '@lostgradient/weft';
+ *
+ * const approval = signal('approval');
+ * const source: WorkflowContractMessageSource = approval;
+ * console.log(source.inputSchema === undefined);
+ * ```
+ */
+export interface WorkflowContractMessageSource {
+    /**
+     * The message's own wire name, as recorded by `signal()`/`update()`/`query()`
+     * and used by `normalizeMessageDefinitions()` (`core/engine/registration.ts`)
+     * to key the registered message — not necessarily the JS object key the
+     * caller used in `.signals({...})`/`.updates({...})`/`.queries({...})`,
+     * which may alias a different local name. {@link buildWorkflowContract}
+     * keys `WorkflowContract.signals`/`updates`/`queries` by this field so the
+     * built contract matches what the registry and codegen actually expose.
+     */
+    readonly name: string;
+    readonly inputSchema?: DefinitionSchema;
+    readonly outputSchema?: DefinitionSchema;
+}
+/**
+ * Structural shape one activity or finalizer source must satisfy for
+ * {@link buildWorkflowContract} to convert it. Requires `name` — shared with
+ * every real activity source type — specifically so a `WorkflowDefinition`'s
+ * `finalizer` field (declared as the narrower `AnyActivityDefinition`, which
+ * does not itself declare `inputSchema`/`outputSchema`) remains structurally
+ * assignable here: TypeScript's weak-type check requires at least one
+ * property in common between source and target when every target property is
+ * optional, and `name` is that shared property.
+ *
+ * @example
+ * ```ts
+ * import { activity } from '@lostgradient/weft';
+ * import type { WorkflowContractActivitySource } from '@lostgradient/weft';
+ *
+ * const charge = activity({ name: 'charge', execute: async (input: number) => input });
+ * const source: WorkflowContractActivitySource = charge;
+ * console.log(source.name);
+ * ```
+ */
+export interface WorkflowContractActivitySource {
+    readonly name: string;
+    readonly inputSchema?: DefinitionSchema;
+    readonly outputSchema?: DefinitionSchema;
+}
+/**
+ * Authoring-time input accepted by {@link buildWorkflowContract} — the
+ * narrowest structural shape that both `WorkflowDefinition` and
+ * `BuiltWorkflowDefinition` already satisfy, so neither type is imported here
+ * and no coupling is introduced between this module and the workflow builder.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from '@lostgradient/weft';
+ * import type { WorkflowContractSource } from '@lostgradient/weft';
+ *
+ * const greet = workflow({ name: 'greet', version: '1.0.0' }).execute(
+ *   async function* (_ctx, input: string) {
+ *     return `hello ${input}`;
+ *   },
+ * );
+ * const source: WorkflowContractSource = greet;
+ * console.log(source.name);
+ * ```
+ */
+export interface WorkflowContractSource {
+    readonly name: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly tags?: ReadonlyArray<string>;
+    readonly inputSchema?: DefinitionSchema;
+    readonly outputSchema?: DefinitionSchema;
+    readonly signals?: Readonly<Record<string, WorkflowContractMessageSource>>;
+    readonly updates?: Readonly<Record<string, WorkflowContractMessageSource>>;
+    readonly queries?: Readonly<Record<string, WorkflowContractMessageSource>>;
+    readonly activities?: Readonly<Record<string, WorkflowContractActivitySource>>;
+    readonly finalizer?: WorkflowContractActivitySource;
+}
+/**
+ * Current workflow revision manifest schema version. An unknown value is
+ * rejected by {@link parseWorkflowRevisionManifest} before any other field is
+ * read, the same "reject rather than best-effort parse" contract
+ * `WORKER_MANIFEST_VERSION` uses.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_REVISION_MANIFEST_VERSION } from '@lostgradient/weft';
+ *
+ * console.log(WORKFLOW_REVISION_MANIFEST_VERSION); // 1
+ * ```
+ */
+export declare const WORKFLOW_REVISION_MANIFEST_VERSION = 1;
+/**
+ * A workflow contract paired with its two identity answers: the
+ * payload-only `contractHash` and the broader `revision`.
+ *
+ * `revision` is an opaque label: content-derived by {@link deriveWorkflowRevision}
+ * by default, or explicitly supplied. {@link parseWorkflowRevisionManifest}
+ * recomputes and checks `contractHash` on every parse, but never recomputes
+ * `revision` — an explicitly supplied revision is a caller assertion, not a
+ * value this module can verify.
+ *
+ * @example
+ * ```ts
+ * import { WORKFLOW_REVISION_MANIFEST_VERSION, buildWorkflowContract } from '@lostgradient/weft';
+ * import type { WorkflowRevisionManifest } from '@lostgradient/weft';
+ *
+ * const contract = buildWorkflowContract({ name: 'checkout', version: '2.1.0' });
+ * const manifest: WorkflowRevisionManifest = {
+ *   manifestVersion: WORKFLOW_REVISION_MANIFEST_VERSION,
+ *   name: contract.name,
+ *   workflowVersion: contract.workflowVersion,
+ *   revision: 'sha256:placeholder',
+ *   contractHash: 'sha256:placeholder',
+ *   contract,
+ * };
+ * console.log(manifest.name);
+ * ```
+ */
+export type WorkflowRevisionManifest = Readonly<{
+    /** Manifest schema version; unknown values are rejected, not tolerated. */
+    manifestVersion: typeof WORKFLOW_REVISION_MANIFEST_VERSION;
+    /** Wire-safe workflow name; must equal `contract.name`. */
+    name: string;
+    /** Semantic replay-compatibility boundary; must equal `contract.workflowVersion`. */
+    workflowVersion: string;
+    /** Content-derived or explicitly supplied opaque revision identity. */
+    revision: string;
+    /** Deterministic payload-only contract identity, verified on every parse. */
+    contractHash: string;
+    /** The normalized workflow contract this manifest describes. */
+    contract: WorkflowContract;
+}>;

package/dist/core/contract/types.js

@@ -0,0 +1 @@
+export const WORKFLOW_CONTRACT_VERSION = 1, WORKFLOW_REVISION_MANIFEST_VERSION = 1;

package/dist/core/engine/catalog-activation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `activateCatalogRevisionCandidate` — a thin engine-level wrapper around
+ * `WorkflowCatalog.activateCandidate()`, the guarded activation primitive
+ * (WFT-9/WFT-10). Awaits catalog readiness, reads pre-activation state,
+ * calls the guarded primitive, dispatches the correct catalog event(s), and
+ * returns the primitive's own structured result verbatim:
+ * the shared installed/activated/draining helper on success, or
+ * `WorkflowRevisionActivationRejectedEvent` directly on refusal.
+ *
+ * `engine.workflows.activate()` (WFT-11,
+ * `core/engine/engine-workflows-namespace.ts`) is this wrapper's production
+ * caller — the only practical way an external caller reaches the guarded
+ * candidate-activation primitive, so routing it through here (rather than
+ * calling `WorkflowCatalog.activateCandidate()` directly) is what makes a
+ * manual activation dispatch `catalog:revision-installed`/
+ * `catalog:revision-activated`/`catalog:revision-draining`/
+ * `catalog:activation-rejected` the same way `engine.register()`'s
+ * drain path already does.
+ *
+ * Never imports `./index.ts` as a value (only as a type, matching
+ * `catalog-readiness.ts`'s own import-cycle discipline for itself) — the
+ * `Engine` class import here is `import type`, erased at build time.
+ *
+ * @module core/engine/catalog-activation
+ */
+import type { ActivateCandidateOptions, WorkflowCatalogActivationResult } from '../catalog/index.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { Engine } from './index.ts';
+/**
+ * Activate `candidateManifest` for `name` through the catalog's guarded
+ * primitive (`checkWorkflowCompatibility`-gated, single-shot CAS), and
+ * return its structured result verbatim. On success, dispatches
+ * `catalog:revision-installed` (when genuinely new content),
+ * `catalog:revision-draining` (when displacing a prior active revision),
+ * and `catalog:revision-activated`. On refusal, dispatches
+ * `catalog:activation-rejected` carrying only the bounded `reason` code
+ * (and, for `'incompatible'`, the bounded `incompatibilityReasons` array) —
+ * never the full `WorkflowCompatibilityVerdict` object.
+ */
+export declare function activateCatalogRevisionCandidate(engine: Engine, name: string, candidateManifest: WorkflowRevisionManifest, options?: ActivateCandidateOptions): Promise<WorkflowCatalogActivationResult>;

package/dist/core/engine/catalog-activation.js

@@ -0,0 +1,17 @@
+import { WorkflowRevisionActivationRejectedEvent } from "../events/catalog-events.js";
+import { dispatchCatalogInstallAndActivatedEvents } from "./catalog-events.js";
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./catalog-readiness.js";
+export async function activateCatalogRevisionCandidate(engine, name, candidateManifest, options) {
+  await ensureWorkflowCatalogReady(engine);
+  const catalog = getWorkflowCatalog(engine), preExisting = await catalog.hasInstalled(name, candidateManifest.revision), pointerBefore = await catalog.resolveActiveDurable(name) ?? null, result = await catalog.activateCandidate(name, candidateManifest, options);
+  if (result.applied) {
+    dispatchCatalogInstallAndActivatedEvents(engine, name, candidateManifest.revision, preExisting, pointerBefore, result.pointer);
+    return result;
+  }
+  if (result.reason === "incompatible") {
+    engine.dispatchEvent(new WorkflowRevisionActivationRejectedEvent(name, candidateManifest.revision, result.reason, result.verdict.compatible ? void 0 : result.verdict.reasons));
+    return result;
+  }
+  engine.dispatchEvent(new WorkflowRevisionActivationRejectedEvent(name, candidateManifest.revision, result.reason));
+  return result;
+}

package/dist/core/engine/catalog-events.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared installed/activated/draining event-dispatch helper (WFT-12), used
+ * by BOTH producers of catalog activation: `catalog-readiness.ts`'s
+ * `drainPendingCatalogInstalls` (the `engine.register()`-drain path) and
+ * `catalog-activation.ts`'s `activateCatalogRevisionCandidate` (the guarded
+ * primitive). The two producers return different result shapes
+ * (`activateRegistered` always succeeds and returns a bare pointer;
+ * `activateCandidate` returns a union that can also refuse) — this helper
+ * takes already-normalized before/after pointer values instead of either
+ * raw return type, so it stays agnostic to which producer called it.
+ * `activation-rejected` is NOT dispatched here — only `activateCandidate`
+ * can refuse, so its one caller dispatches that event itself.
+ *
+ * @module core/engine/catalog-events
+ */
+import type { WorkflowCatalogActivePointer } from '../catalog/index.ts';
+import type { Engine } from './index.ts';
+/**
+ * Dispatch `catalog:revision-installed` (only when `preExisting` is
+ * `false` — genuinely new content, not a byte-identical reinstall or a
+ * cross-process durable adoption of already-present content), then decide
+ * activated/draining from how `pointerBefore` and `pointerAfter` compare:
+ *
+ * - Identical `revision` AND `generation` (a true no-op — nothing was
+ *   durably written, e.g. `activateRegistered`'s own no-op branch): neither
+ *   fires.
+ * - Same `revision`, different `generation` (a reactivation that still
+ *   bumped the fencing counter, e.g. `activateCandidate` re-activating the
+ *   currently active revision): `catalog:revision-activated` fires with
+ *   `previousRevision: undefined` — nothing was actually displaced, so
+ *   there is nothing to drain.
+ * - Different `revision`: `catalog:revision-draining` for `pointerBefore`
+ *   (when it existed) followed by `catalog:revision-activated` for
+ *   `pointerAfter`, `previousRevision` set to the displaced revision.
+ */
+export declare function dispatchCatalogInstallAndActivatedEvents(engine: Engine, name: string, revision: string, preExisting: boolean, pointerBefore: WorkflowCatalogActivePointer | null, pointerAfter: WorkflowCatalogActivePointer): void;

package/dist/core/engine/catalog-events.js

@@ -0,0 +1,15 @@
+import {
+  WorkflowRevisionActivatedEvent,
+  WorkflowRevisionDrainingEvent,
+  WorkflowRevisionInstalledEvent
+} from "../events/catalog-events.js";
+export function dispatchCatalogInstallAndActivatedEvents(engine, name, revision, preExisting, pointerBefore, pointerAfter) {
+  if (!preExisting)
+    engine.dispatchEvent(new WorkflowRevisionInstalledEvent(name, revision));
+  if (pointerBefore !== null && pointerBefore.revision === pointerAfter.revision && pointerBefore.generation === pointerAfter.generation)
+    return;
+  const previousRevision = pointerBefore !== null && pointerBefore.revision !== pointerAfter.revision ? pointerBefore.revision : void 0;
+  if (previousRevision !== void 0)
+    engine.dispatchEvent(new WorkflowRevisionDrainingEvent(name, previousRevision));
+  engine.dispatchEvent(new WorkflowRevisionActivatedEvent(name, pointerAfter.revision, pointerAfter.generation, previousRevision));
+}