/** * Pure codecs for the per-workflow ownership claim keys (`wf-owner-epoch:` * and `wf-owner-holder:`) 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:` 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:`. */ 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;