@lostgradient/weft 0.19.0 → 0.21.0

package/dist/core/engine/wake-ownership-check.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `wakeOwnershipCheck` — the read-only re-read of `wf-owner-holder:<id>`
+ * specified in
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions)
+ * (the paragraph immediately after the transitions table).
+ *
+ * **Why this exists.** Under `ownership: 'workflow-lease'`, every code path
+ * that is about to resolve an in-memory waiter or drive a generator for a
+ * parked workflow — a fired sleep timer, a re-evaluated `ctx.waitUntil()`
+ * condition, a delivered signal, an async-activity completion/failure, a
+ * child workflow's termination, or a deferred inline macrotask drive — must
+ * first confirm THIS engine still holds the claim generation it parked the
+ * workflow under. Skipping that check would let a stale in-memory resolver
+ * from a prior generation drive a workflow this engine no longer owns.
+ *
+ * **Why the FULL generation, not just the engine id.** When an engine
+ * releases a workflow and later reacquires the same id, its `engineId` is
+ * unchanged while `epoch` names a new generation. An engine-id-only check
+ * would let a delayed wake or a stale in-memory resolver from the PRIOR
+ * generation drive the NEW one — the exact ABA hazard the epoch exists to
+ * close. This check therefore compares `engineId` AND `epoch` together,
+ * never `engineId` alone.
+ *
+ * **What a match does and does not prove.** A match is a cheap pre-check,
+ * not the safety mechanism itself — the durable write that follows still
+ * carries the epoch as a `conditionalBatch` precondition, and that CAS is
+ * the actual backstop. A mismatch means this engine no longer holds the
+ * generation it parked under: the caller must discard its in-memory
+ * resolver without driving the generator. This module emits
+ * `WeftWorkflowWakeDiscardedWarning` on every mismatch; it does not decide
+ * what the caller does next (that decision, and the actual discard, belong
+ * to the wake call sites this check is wired into — a later stage).
+ *
+ * **Scope.** This module is the check alone: read the holder record, decide
+ * match or discard, warn on discard. It is NOT wired into any of the wake
+ * call sites named above — that wiring is a later stage's responsibility.
+ *
+ * @module core/engine/wake-ownership-check
+ */
+import { type Storage } from '../../storage/interface.ts';
+import { type EmitWorkflowLeaseWarning, type WorkflowWakeKind } from './lease-deposition.ts';
+/** Parameters for {@link wakeOwnershipCheck}. */
+export type WakeOwnershipCheckParams = {
+    /** Durable storage to re-read `wf-owner-holder:<workflowId>` from. */
+    storage: Storage;
+    /** The workflow whose parked wake is about to be resolved or driven. */
+    workflowId: string;
+    /** Which wake path is asking — folded into the discard warning for operator diagnosis. */
+    wakeKind: WorkflowWakeKind;
+    /** The `engineId` this engine parked the workflow under. */
+    expectedEngineId: string;
+    /** The `epoch` this engine parked the workflow under. */
+    expectedEpoch: number;
+    /** Operator-warning seam; defaults to `process.emitWarning` via `lease-deposition.ts`. */
+    warn?: EmitWorkflowLeaseWarning;
+};
+/** Why a re-read holder record failed to match the expected generation. */
+export type WakeOwnershipDiscardReason = 'holder-absent' | 'holder-undecodable' | 'generation-mismatch';
+/** Result of {@link wakeOwnershipCheck}. */
+export type WakeOwnershipCheckResult = {
+    status: 'match';
+} | {
+    status: 'discarded';
+    reason: WakeOwnershipDiscardReason;
+    /** The `engineId` actually found on re-read, or `null` when the holder was absent/undecodable. */
+    observedEngineId: string | null;
+    /** The `epoch` actually found on re-read, or `null` when the holder was absent/undecodable. */
+    observedEpoch: number | null;
+};
+/**
+ * Re-read `wf-owner-holder:<workflowId>` and compare it against the full
+ * generation (`engineId` + `epoch`) this engine parked the workflow under.
+ *
+ * Returns `{ status: 'match' }` when both fields agree — the caller may
+ * proceed to resolve its in-memory waiter or drive the generator (the
+ * following durable write still carries the epoch as the real backstop).
+ * Returns `{ status: 'discarded', reason }` and emits
+ * `WeftWorkflowWakeDiscardedWarning` in every other case: the holder key is
+ * absent (`'holder-absent'`), the stored bytes do not decode to a valid
+ * holder record (`'holder-undecodable'`), or a holder record was found but
+ * its `engineId`/`epoch` do not both match what was expected
+ * (`'generation-mismatch'`) — including the stale-generation case where
+ * `engineId` matches but `epoch` does not, the exact hazard this check
+ * exists to close.
+ */
+export declare function wakeOwnershipCheck(params: WakeOwnershipCheckParams): Promise<WakeOwnershipCheckResult>;

package/dist/core/engine/wake-ownership-check.js

@@ -0,0 +1,19 @@
+import { KEYS } from "../../storage/interface.js";
+import {
+  emitWorkflowWakeDiscardedWarning
+} from "./lease-deposition.js";
+import { decodeWorkflowClaimHolder } from "./workflow-claim-codec.js";
+export async function wakeOwnershipCheck(params) {
+  const { storage, workflowId, wakeKind, expectedEngineId, expectedEpoch, warn } = params, discard = (reason, observedEngineId, observedEpoch) => {
+    emitWorkflowWakeDiscardedWarning(workflowId, wakeKind, warn);
+    return { status: "discarded", reason, observedEngineId, observedEpoch };
+  }, raw = await storage.get(KEYS.workflowOwnerHolder(workflowId));
+  if (raw === null)
+    return discard("holder-absent", null, null);
+  const holder = decodeWorkflowClaimHolder(raw);
+  if (holder === null)
+    return discard("holder-undecodable", null, null);
+  if (holder.engineId !== expectedEngineId || holder.epoch !== expectedEpoch)
+    return discard("generation-mismatch", holder.engineId, holder.epoch);
+  return { status: "match" };
+}

package/dist/core/engine/wake-ownership-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `confirmWakeOwnership` — the single call-site helper every claim-requiring
+ * wake path (sleep, wait-condition, async-activity, inline-macrotask-drive)
+ * uses to run `wakeOwnershipCheck` before resolving an in-memory waiter or
+ * driving a generator for a parked workflow, per
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions).
+ *
+ * **Why a wrapper instead of calling `wakeOwnershipCheck` directly at each
+ * site.** `wakeOwnershipCheck` requires a non-null `expectedEngineId` /
+ * `expectedEpoch` pair — it has no opinion on how a caller obtains those. Every
+ * wake site needs the exact same three-way decision tree first:
+ *
+ * - `internals.workflowClaimRegistry` is `null` (ownership is `'none'` or
+ *   `'lease'`): this check is a no-op. Proceed — byte-identical to every
+ *   pre-ADR-0002 deployment. This is the property every wake site must
+ *   preserve above all else.
+ * - The registry is present but tracks no epoch for this workflow id
+ *   (`currentEpoch(workflowId)` is `null` — e.g. a `renew()` loss already
+ *   dropped this engine's local claim entry): there is nothing to compare
+ *   against, so this is itself a discard. `wakeOwnershipCheck` cannot be
+ *   called with a null epoch, so this module emits
+ *   `WeftWorkflowWakeDiscardedWarning` itself rather than skipping the
+ *   operator diagnostic.
+ * - The registry tracks an epoch: re-read the durable holder record and
+ *   compare the full generation via `wakeOwnershipCheck`.
+ *
+ * **A thrown storage read is `'proceed'`, not `'discard'`.** This helper is a
+ * cheap pre-check; the epoch-conditioned durable write that follows every
+ * proceed path is the real backstop (`EngineDeposedError` if it has actually
+ * lost the claim). A storage blip during the pre-check must not permanently
+ * strand a wake — a fired sleep timer or a signalled `waitUntil` deadline is
+ * not retried — so a thrown read is treated the same as a match and the
+ * caller proceeds to its normal (already-fenced) write path.
+ *
+ * @module core/engine/wake-ownership-guard
+ */
+import type { EngineInternals } from './internals.ts';
+import { type WorkflowWakeKind } from './lease-deposition.ts';
+/** Outcome of {@link confirmWakeOwnership}: whether the caller may proceed with this wake. */
+export type WakeOwnershipDecision = 'proceed' | 'discard';
+/**
+ * Decide whether a claim-requiring wake path may resolve its in-memory
+ * waiter / drive its generator for `workflowId`. See the module doc for the
+ * three-way decision tree and the thrown-read policy.
+ */
+export declare function confirmWakeOwnership(internals: EngineInternals, workflowId: string, wakeKind: WorkflowWakeKind): Promise<WakeOwnershipDecision>;

package/dist/core/engine/wake-ownership-guard.js

@@ -0,0 +1,23 @@
+import { emitWorkflowWakeDiscardedWarning } from "./lease-deposition.js";
+import { wakeOwnershipCheck } from "./wake-ownership-check.js";
+export async function confirmWakeOwnership(internals, workflowId, wakeKind) {
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return "proceed";
+  const expectedEpoch = registry.currentEpoch(workflowId);
+  if (expectedEpoch === null) {
+    emitWorkflowWakeDiscardedWarning(workflowId, wakeKind);
+    return "discard";
+  }
+  try {
+    return (await wakeOwnershipCheck({
+      storage: internals.storage,
+      workflowId,
+      wakeKind,
+      expectedEngineId: registry.engineId,
+      expectedEpoch
+    })).status === "match" ? "proceed" : "discard";
+  } catch {
+    return "proceed";
+  }
+}

package/dist/core/engine/workflow-claim-codec.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure codecs for the per-workflow ownership claim keys (`wf-owner-epoch:<id>`
+ * and `wf-owner-holder:<id>`) and for the store-wide `ownership-mode-marker`.
+ *
+ * These back the `ownership: 'workflow-lease'` mode described in
+ * [ADR 0002](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md).
+ * The epoch codec itself is shared with the global lease — `encodeEpoch` and
+ * `decodeEpoch` are imported from `lease-codec.ts` rather than reimplemented, so
+ * both fencing tokens stay byte-identical in representation.
+ *
+ * Only the holder record differs: the global lease holds three fields for one
+ * store-wide lease, while a per-workflow claim holds four, adding `claimedAt`
+ * for operator visibility and carrying `engineId` rather than `holderId`.
+ *
+ * Every decoder is fail-closed: any structurally invalid, foreign, or corrupt
+ * value decodes to `null` rather than throwing, matching `lease-codec.ts`.
+ *
+ * @module core/engine/workflow-claim-codec
+ */
+import { decodeEpoch, encodeEpoch } from './lease-codec.ts';
+export { decodeEpoch, encodeEpoch };
+/** The ownership modes that fence engine work and therefore stamp the store-wide marker. */
+export type FencingOwnershipMode = 'lease' | 'workflow-lease';
+/** The decoded `wf-owner-holder:<workflowId>` record. */
+export type WorkflowClaimHolderRecord = {
+    /** Identity of the owning engine process, minted once per engine. */
+    engineId: string;
+    /** The claim generation this holder owns. Mirrors `wf-owner-epoch:<workflowId>`. */
+    epoch: number;
+    /** Engine-clock ms after which the claim becomes eligible for takeover. */
+    expiresAt: number;
+    /** Engine-clock ms when this epoch was first claimed. Unchanged across renewals. */
+    claimedAt: number;
+};
+/** The decoded store-wide `ownership-mode-marker` record. */
+export type OwnershipModeMarkerRecord = {
+    /** The fencing mode the first fencing-mode engine stamped on this store. */
+    mode: FencingOwnershipMode;
+    /** Engine-clock ms when the marker was established. Diagnostics only. */
+    establishedAt: number;
+};
+/** Encode a per-workflow claim holder record to its stored JSON bytes. */
+export declare function encodeWorkflowClaimHolder(record: WorkflowClaimHolderRecord): Uint8Array;
+/**
+ * Decode a stored per-workflow claim holder record, tolerating any
+ * malformed or foreign value as `null`.
+ *
+ * An empty `engineId` is rejected: it can never match a real engine's identity,
+ * so admitting it would produce a holder that no engine can renew or release.
+ */
+export declare function decodeWorkflowClaimHolder(raw: Uint8Array): WorkflowClaimHolderRecord | null;
+/** Encode the store-wide ownership-mode marker to its stored JSON bytes. */
+export declare function encodeOwnershipModeMarker(record: OwnershipModeMarkerRecord): Uint8Array;
+/**
+ * Decode the store-wide ownership-mode marker, tolerating any malformed or
+ * foreign value as `null`.
+ *
+ * An unrecognized `mode` decodes to `null` rather than being preserved. The
+ * marker exists to make a mode mismatch detectable, and a mode this build does
+ * not understand cannot be compared meaningfully; treating it as absent lets the
+ * reader fail closed on its own terms instead of comparing against a string it
+ * cannot interpret.
+ */
+export declare function decodeOwnershipModeMarker(raw: Uint8Array): OwnershipModeMarkerRecord | null;

package/dist/core/engine/workflow-claim-codec.js

@@ -0,0 +1,44 @@
+import { decodeEpoch, encodeEpoch } from "./lease-codec.js";
+
+export { decodeEpoch, encodeEpoch };
+const textEncoder = new TextEncoder, textDecoder = new TextDecoder;
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isUsableTimestamp(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isUsableEpoch(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value < Number.MAX_SAFE_INTEGER;
+}
+function parseJsonBytes(raw) {
+  try {
+    return JSON.parse(textDecoder.decode(raw));
+  } catch {
+    return null;
+  }
+}
+export function encodeWorkflowClaimHolder(record) {
+  return textEncoder.encode(JSON.stringify(record));
+}
+export function decodeWorkflowClaimHolder(raw) {
+  const parsed = parseJsonBytes(raw);
+  if (!isRecord(parsed))
+    return null;
+  const { engineId, epoch, expiresAt, claimedAt } = parsed;
+  if (typeof engineId !== "string" || engineId.length === 0 || !isUsableEpoch(epoch) || !isUsableTimestamp(expiresAt) || !isUsableTimestamp(claimedAt))
+    return null;
+  return { engineId, epoch, expiresAt, claimedAt };
+}
+export function encodeOwnershipModeMarker(record) {
+  return textEncoder.encode(JSON.stringify(record));
+}
+export function decodeOwnershipModeMarker(raw) {
+  const parsed = parseJsonBytes(raw);
+  if (!isRecord(parsed))
+    return null;
+  const { mode, establishedAt } = parsed;
+  if (mode !== "lease" && mode !== "workflow-lease" || !isUsableTimestamp(establishedAt))
+    return null;
+  return { mode, establishedAt };
+}

package/dist/core/engine/workflow-claim-cooldown.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-workflow-id anti-thrash takeover cooldown, specified in
+ * [ADR 0002 § Ownership transitions](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#ownership-transitions)
+ * (the `takeover` row's "A per-workflow-id anti-thrash cooldown" sentence).
+ *
+ * **The problem this dampens.** Without it, a reclaim scan and the engine
+ * that just lost a claim can thrash: this engine loses `workflowId` via a
+ * failed `renew`, its own recurring reclaim scan later judges the same
+ * holder stale (a genuine race — the deposing engine can itself stall or
+ * crash right after depositing this one), and this engine immediately steals
+ * it back, only to lose it again the same way. The cooldown makes that loop
+ * back off instead of spinning.
+ *
+ * **Shape.** In-memory, per-engine-process, keyed by workflow id — not
+ * durable and not shared across engines; a restart forgets every cooldown,
+ * which is safe, since a fresh process has not just been deposed from
+ * anything yet. `WorkflowClaimRegistry` owns one instance and drives it from
+ * exactly three points: a failed `renew` calls {@link recordDeposition}, a
+ * successful `acquire`/`takeover`/folded-acquire calls {@link clear}, and
+ * `takeover` consults {@link isActive} before attempting its CAS.
+ *
+ * **Curve.** A fixed window of `workflowClaimRenewInterval`, not exponential.
+ * Through `WorkflowClaimRegistry`'s real call graph, a second
+ * `recordDeposition` for the same id is only reachable after an intervening
+ * successful (re)acquire has already {@link clear}ed the tracked entry — this
+ * class never observes consecutive depositions for the same id without a
+ * clear between them, so a growing window would never actually grow. An
+ * exponential curve was tried here and found unreachable in review; keep this
+ * simple until a call-graph change (preserving loss history across successful
+ * reacquisition) makes a growing window meaningful.
+ *
+ * @module core/engine/workflow-claim-cooldown
+ */
+/** Options for {@link WorkflowClaimTakeoverCooldown}. Mirrors `WorkflowClaimRegistryOptions`'s same-named field, so the caller need not compute the window itself. */
+export type WorkflowClaimTakeoverCooldownOptions = {
+    /** Cooldown window (ms) — `workflowClaimRenewInterval`. */
+    claimRenewIntervalMs: number;
+};
+/**
+ * Tracks one engine's per-workflow-id takeover cooldown. See the module doc
+ * for the mechanism and curve.
+ */
+export declare class WorkflowClaimTakeoverCooldown {
+    #private;
+    constructor(options: WorkflowClaimTakeoverCooldownOptions);
+    /**
+     * Whether `workflowId` is currently within its cooldown window at `now`.
+     * The boundary itself (`now === untilMs`) is NOT active — matches
+     * `isWorkflowClaimExpired`'s "strictly earlier" convention for the sibling
+     * expiry judgment.
+     */
+    isActive(workflowId: string, now: number): boolean;
+    /**
+     * Record that this engine just lost ownership of `workflowId` via a failed
+     * `renew`. Starts (or restarts) a fixed-length cooldown window.
+     */
+    recordDeposition(workflowId: string, now: number): void;
+    /** Clear any tracked cooldown for `workflowId` — call on a successful (re)acquire or takeover. */
+    clear(workflowId: string): void;
+}

package/dist/core/engine/workflow-claim-cooldown.js

@@ -0,0 +1,17 @@
+export class WorkflowClaimTakeoverCooldown {
+  #windowMs;
+  #untilMsByWorkflowId = new Map;
+  constructor(options) {
+    this.#windowMs = options.claimRenewIntervalMs;
+  }
+  isActive(workflowId, now) {
+    const untilMs = this.#untilMsByWorkflowId.get(workflowId);
+    return untilMs !== void 0 && now < untilMs;
+  }
+  recordDeposition(workflowId, now) {
+    this.#untilMsByWorkflowId.set(workflowId, now + this.#windowMs);
+  }
+  clear(workflowId) {
+    this.#untilMsByWorkflowId.delete(workflowId);
+  }
+}

package/dist/core/engine/workflow-claim-fold.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared "fold `acquire` into an enabling write" helper for ADR 0002's
+ * CLAIM-ACQUIRING entry points this stage owns: workflow start
+ * (`lifecycle/start-commit.ts` — the create batch), delayed-start timer fire
+ * (`operations-time.ts`), and bulk retry reactivation (`bulk-operations.ts`).
+ * Scheduled runs and child-workflow launches funnel through `startWorkflow`
+ * (`lifecycle/start.ts`) and inherit the fold from there — see
+ * [ADR 0002 § Entry point classification](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#entry-point-classification),
+ * the `startWorkflow`/`buildAndCommitStartBatch` row, which explicitly groups
+ * `ctx.startChild` and `startScheduledRun` with it.
+ *
+ * A claim-acquiring write establishes a claim THIS commit has never held
+ * before, so it can never be fenced through `commitFencedEngineWrite` (which
+ * requires an ALREADY-tracked epoch in `EngineInternals.workflowClaimRegistry`
+ * — see `fenced-write.ts`'s `fencedCommitForWorkflow`). Instead, the claim's
+ * OWN `acquire` conditions (holder absent, epoch matches what was just read)
+ * ARE the fence for this first write: {@link prepareWorkflowClaimFold} reads
+ * fresh `wf-owner-epoch:<id>` bytes and builds the pure acquire fragment via
+ * `WorkflowClaimRegistry.prepareAcquireFragment`, the caller merges the
+ * fragment's conditions/operations into its own enabling write, and
+ * {@link commitWithWorkflowClaimFold} commits ONE atomic
+ * `storageConditionalBatch`. Only after that commit succeeds does it call
+ * `WorkflowClaimRegistry.recordFoldedAcquire`, installing the tracking entry
+ * every later `commitFencedEngineWrite` for this workflow needs.
+ *
+ * Under `ownership: 'none'`/`'lease'`, or `'workflow-lease'` with no registry
+ * constructed yet (Gate 1/Gate 2 wiring is a parallel/later stage) —
+ * {@link prepareWorkflowClaimFold} returns `undefined` and every caller's
+ * pre-existing code path runs byte-for-byte unchanged. It also returns
+ * `undefined` when this engine already tracks a claim for `workflowId`: bulk
+ * retry folds `acquire` into its own reactivation write, then calls
+ * `engine.resume()`, which must not attempt a second acquire for the same
+ * workflow (see `lifecycle/resume.ts`).
+ *
+ * @module core/engine/workflow-claim-fold
+ */
+import { type BatchOperation, type ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+import type { WorkflowClaimAcquirePreparation, WorkflowClaimRegistry } from './workflow-claim-registry.ts';
+/** A prepared, not-yet-committed claim-acquire fold for one workflow id. */
+export type WorkflowClaimFold = {
+    registry: WorkflowClaimRegistry;
+    workflowId: string;
+    preparation: WorkflowClaimAcquirePreparation;
+    conditions: ConditionalBatchCondition[];
+    operations: BatchOperation[];
+};
+/**
+ * Prepare a claim-acquire fold for `workflowId`, or `undefined` when folding
+ * does not apply — see the module doc for the three cases that return
+ * `undefined`. Call again on every retry attempt of the caller's own
+ * enabling-write loop; never reuse a preparation across attempts, since a
+ * stale epoch read dooms the retry's CAS.
+ */
+export declare function prepareWorkflowClaimFold(internals: EngineInternals, workflowId: string): Promise<WorkflowClaimFold | undefined>;
+/** Outcome of {@link commitWithWorkflowClaimFold}. */
+export type WorkflowClaimFoldCommitResult = {
+    status: 'committed';
+} | {
+    status: 'lost-race';
+    /** Whether the fold's OWN conditions (not the caller's) were the ones that lost the CAS. */
+    claimConflict: boolean;
+};
+/**
+ * Commit `operations`/`conditions` merged with `fold`'s own acquire
+ * fragment, as ONE atomic `storageConditionalBatch`. On success, installs
+ * the fold's tracking entry via `WorkflowClaimRegistry.recordFoldedAcquire`.
+ * On a lost CAS, re-reads the fold's own conditions to report whether THEY
+ * were the ones that failed — distinct from the caller's own conditions
+ * (idempotency mapping, workflow-concurrency admission) — so the caller can
+ * raise `WorkflowClaimUnavailableError` instead of misreporting a claim loss
+ * as an unrelated precondition conflict, or vice versa.
+ */
+export declare function commitWithWorkflowClaimFold(internals: EngineInternals, fold: WorkflowClaimFold, operations: BatchOperation[], conditions: ConditionalBatchCondition[], featureName: string): Promise<WorkflowClaimFoldCommitResult>;
+/**
+ * Raise `WorkflowClaimUnavailableError` for `workflowId`, re-reading its
+ * current holder for the `heldBy` field — the shared shape every explicit,
+ * single-workflow claim-acquiring call site (start, bulk retry reactivation)
+ * uses on a confirmed claim conflict, instead of each repeating the
+ * re-read-then-throw.
+ */
+export declare function throwWorkflowClaimUnavailable(internals: EngineInternals, workflowId: string): Promise<never>;

package/dist/core/engine/workflow-claim-fold.js

@@ -0,0 +1,53 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch,
+  storageValuesEqual
+} from "../../storage/interface.js";
+import { WorkflowClaimUnavailableError } from "./lease-errors.js";
+import { decodeWorkflowClaimHolder } from "./workflow-claim-codec.js";
+export async function prepareWorkflowClaimFold(internals, workflowId) {
+  if (internals.options.ownershipMode !== "workflow-lease")
+    return;
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return;
+  if (registry.currentEpoch(workflowId) !== null)
+    return;
+  const preparation = await registry.prepareAcquireFragment(workflowId);
+  return {
+    registry,
+    workflowId,
+    preparation,
+    conditions: preparation.fragment.conditions,
+    operations: preparation.fragment.operations
+  };
+}
+export async function commitWithWorkflowClaimFold(internals, fold, operations, conditions, featureName) {
+  requireStorageCapability(internals.storage, "conditionalBatch", featureName);
+  if (await storageConditionalBatch(internals.storage, [...conditions, ...fold.conditions], [...operations, ...fold.operations])) {
+    fold.registry.recordFoldedAcquire(fold.workflowId, fold.preparation);
+    return { status: "committed" };
+  }
+  return {
+    status: "lost-race",
+    claimConflict: await hasWorkflowClaimFoldConflict(internals, fold)
+  };
+}
+async function hasWorkflowClaimFoldConflict(internals, fold) {
+  for (const condition of fold.conditions) {
+    const currentValue = await internals.storage.get(condition.key);
+    if (!storageValuesEqual(currentValue, condition.expectedValue))
+      return !0;
+  }
+  return !1;
+}
+async function resolveWorkflowClaimHolder(internals, workflowId) {
+  const raw = await internals.storage.get(KEYS.workflowOwnerHolder(workflowId));
+  if (raw === null)
+    return null;
+  return decodeWorkflowClaimHolder(raw)?.engineId ?? null;
+}
+export async function throwWorkflowClaimUnavailable(internals, workflowId) {
+  throw new WorkflowClaimUnavailableError(workflowId, await resolveWorkflowClaimHolder(internals, workflowId));
+}

package/dist/core/engine/workflow-claim-metrics.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Bounded-cardinality observability recorder for the `ownership: 'workflow-lease'`
+ * per-workflow claim protocol described in
+ * [ADR 0002 § Observability](../../../documentation/contributing/architecture-decisions/0002-multiengine-per-workflow-ownership.md#observability).
+ *
+ * This module is a standalone recorder, not wired into
+ * `src/observability/metrics.ts`/`metrics-catalog.ts` — those files already
+ * document a "keeping this as an interface" plug-point idiom for exactly this
+ * situation (see `PrometheusExporter` there), and the existing `METRICS`
+ * catalogue and `MetricsCollector` have no concept of a labelled series at
+ * all: every entry is a flat, unlabelled name. Folding `outcome` into that
+ * shape would require editing `metrics-catalog.ts` and `metrics.ts`, which is
+ * out of scope for this stage (see the module-level follow-up note below).
+ * Instead this module defines the same three signals as a small, injectable,
+ * structurally-typed recorder that a later stage can either back the existing
+ * exporter with directly, or bridge into `MetricsCollector` by fanning
+ * `snapshot().attempts` out into five unlabelled counter names.
+ *
+ * The ADR states twice that workflow ids are never Prometheus metric labels.
+ * That is enforced here at the type level, not by convention: the only value
+ * {@link WorkflowClaimMetricsRecorder.recordClaimAttempt} accepts is
+ * {@link WorkflowClaimAttemptOutcome}, a closed union of exactly five string
+ * literals. A workflow id — an arbitrary `string` — is not a member of that
+ * union, so passing one is a compile error, not a runtime cardinality bug
+ * waiting to happen. See `workflow-claim-metrics.test-d.ts` for the pinned
+ * proof.
+ *
+ * **Follow-up (not built here):** wiring this recorder's snapshot into the
+ * server's `/v1/metrics` `PrometheusExporter` (`src/observability/metrics.ts`)
+ * requires editing that file, which is owned by a different in-flight patch
+ * for this stage. {@link WorkflowClaimMetricsRecorder} is deliberately
+ * structural so that wiring can happen later without reshaping this module.
+ *
+ * @module core/engine/workflow-claim-metrics
+ */
+/**
+ * The exact, closed set of outcomes {@link WorkflowClaimMetricsRecorder.recordClaimAttempt}
+ * accepts. Matches `weft_workflow_claim_attempts_total`'s `outcome` label
+ * value set in ADR 0002 § Observability — five fixed values, nothing else.
+ */
+export type WorkflowClaimAttemptOutcome = 'acquired' | 'takeover' | 'lost_race' | 'deposed' | 'backoff_skipped';
+/**
+ * Every {@link WorkflowClaimAttemptOutcome} value, in declaration order. The
+ * single source of truth for the label's cardinality bound — both the
+ * recorder's internal counter map and the Prometheus serializer iterate this
+ * tuple rather than re-listing the five values.
+ */
+export declare const WORKFLOW_CLAIM_ATTEMPT_OUTCOMES: readonly ["acquired", "takeover", "lost_race", "deposed", "backoff_skipped"];
+/** One count per {@link WorkflowClaimAttemptOutcome}, always present (zero-filled when never recorded). */
+export type WorkflowClaimAttemptCounts = Readonly<Record<WorkflowClaimAttemptOutcome, number>>;
+/** A point-in-time read of everything this module tracks. */
+export type WorkflowClaimMetricsSnapshot = {
+    /** Per-outcome attempt counts. Mirrors `weft_workflow_claim_attempts_total{outcome="..."}`. */
+    attempts: WorkflowClaimAttemptCounts;
+    /** Mirrors `weft_workflow_claims_active` — workflows this engine currently holds a claim for. */
+    activeClaims: number;
+    /** Mirrors `weft_workflow_claim_renewal_failures_total`. */
+    renewalFailures: number;
+};
+/**
+ * Structural recorder interface for the three ADR 0002 observability signals.
+ * Defined as an interface — not just the concrete {@link WorkflowClaimMetricsCollector}
+ * class — so a caller can satisfy it with any implementation (a bridge into
+ * `MetricsCollector`, an OpenTelemetry adapter, a test double) without
+ * depending on this module's storage choices.
+ *
+ * `recordClaimAttempt`'s parameter type is the whole point of this interface:
+ * it is impossible to express "pass a workflow id here" without a type error,
+ * because the parameter is {@link WorkflowClaimAttemptOutcome}, not `string`.
+ */
+export interface WorkflowClaimMetricsRecorder {
+    /** Record one claim-attempt outcome. Increments only that outcome's series. */
+    recordClaimAttempt(outcome: WorkflowClaimAttemptOutcome): void;
+    /**
+     * Set the absolute count of workflows this engine currently holds a claim
+     * for. An absolute set (not a delta), matching the existing
+     * `MetricsCollector.gauge()` idiom in `src/observability/metrics.ts`. Must
+     * be a safe, non-negative integer.
+     */
+    setActiveClaims(count: number): void;
+    /** Record one renewal-failure occurrence. */
+    recordClaimRenewalFailure(): void;
+}
+/**
+ * In-memory implementation of {@link WorkflowClaimMetricsRecorder}, one per
+ * engine process — matching the ADR's "single counter/gauge per engine
+ * process" cardinality note for these three signals.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowClaimMetricsCollector } from './workflow-claim-metrics.ts';
+ *
+ * const collector = new WorkflowClaimMetricsCollector();
+ * collector.recordClaimAttempt('acquired');
+ * collector.setActiveClaims(1);
+ * console.log(collector.snapshot().attempts.acquired); // 1
+ * ```
+ */
+export declare class WorkflowClaimMetricsCollector implements WorkflowClaimMetricsRecorder {
+    #private;
+    constructor();
+    recordClaimAttempt(outcome: WorkflowClaimAttemptOutcome): void;
+    setActiveClaims(count: number): void;
+    recordClaimRenewalFailure(): void;
+    /** Return a point-in-time snapshot of all three signals. */
+    snapshot(): WorkflowClaimMetricsSnapshot;
+    /** Clear all collected values back to zero. */
+    reset(): void;
+}
+/**
+ * Serialize a {@link WorkflowClaimMetricsSnapshot} as Prometheus text format,
+ * using the exact metric names ADR 0002 § Observability specifies. Every
+ * outcome always emits a line — including zero-valued ones — so a scraper
+ * sees a stable schema regardless of which outcomes have occurred yet,
+ * matching the stable-schema behavior of
+ * `serializeMetricsSnapshotForPrometheus` in `src/observability/metrics.ts`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   WorkflowClaimMetricsCollector,
+ *   serializeWorkflowClaimMetricsForPrometheus,
+ * } from './workflow-claim-metrics.ts';
+ *
+ * const collector = new WorkflowClaimMetricsCollector();
+ * collector.recordClaimAttempt('acquired');
+ * const body = serializeWorkflowClaimMetricsForPrometheus(collector.snapshot());
+ * console.log(body.includes('weft_workflow_claim_attempts_total{outcome="acquired"} 1'));
+ * ```
+ */
+export declare function serializeWorkflowClaimMetricsForPrometheus(snapshot: WorkflowClaimMetricsSnapshot): string;