@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/application-primitive-abort.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Racing an in-flight storage observation against abort signals (WFT-84, WFT-85).
+ *
+ * Storage has no cancellation contract, so a stalled remote read cannot be
+ * cut short. What can be cut short is the caller's wait: the moment any of the
+ * signals fires, or the wait's own budget runs out, the observation is
+ * reported as aborted and the read is left to settle on its own. Kept to the
+ * fewest promise hops, because the deterministic fake-timer tests drain a
+ * fixed number of microtask turns between ticks.
+ *
+ * @module core/application-primitive-abort
+ */
+import { WeftError } from './weft-error.ts';
+/** The outcome of racing an in-flight observation against abort signals. */
+export type Raced<T> = {
+    readonly aborted: false;
+    readonly value: T;
+} | {
+    readonly aborted: true;
+    readonly reason: unknown;
+};
+/**
+ * Thrown by `Mailbox.awaitCleanup()` when a positive budget runs out
+ * while the FIRST cleanup-state read is still in flight — there is no
+ * observation yet to report as `pending`. Nothing durable changed; the wait is
+ * simply over.
+ *
+ * @example
+ * ```ts
+ * import { WaitBudgetElapsedError } from '@lostgradient/weft';
+ *
+ * const error = new WaitBudgetElapsedError();
+ * console.log(error.code); // 'WaitBudgetElapsedError'
+ * ```
+ */
+export declare class WaitBudgetElapsedError extends WeftError<'WaitBudgetElapsedError'> {
+    constructor();
+}
+/**
+ * Run an observation unless any of the signals is, or becomes, aborted while
+ * it is in flight. `undefined` signals are ignored.
+ */
+export declare function raceAbort<T>(run: () => Promise<T>, ...signals: readonly (AbortSignal | undefined)[]): Promise<Raced<T>>;
+/**
+ * `raceAbort` with a budget: when `budgetMs` is a positive number, a timer of
+ * that length also ends the race, with `WaitBudgetElapsedError` as the reason.
+ * A bounded wait is bounded by this even while a remote read is stalled; the
+ * sleeps between observations are not the only place a budget can run out.
+ */
+export declare function raceAbortWithin<T>(run: () => Promise<T>, budgetMs: number | null, ...signals: readonly (AbortSignal | undefined)[]): Promise<Raced<T>>;

package/dist/core/application-primitive-abort.js

@@ -0,0 +1,40 @@
+import { WeftError } from "./weft-error.js";
+
+export class WaitBudgetElapsedError extends WeftError {
+  constructor() {
+    super("WaitBudgetElapsedError", "The wait budget elapsed while a storage observation was still in flight.");
+  }
+}
+export function raceAbort(run, ...signals) {
+  return raceAbortWithin(run, null, ...signals);
+}
+export function raceAbortWithin(run, budgetMs, ...signals) {
+  const live = signals.filter((signal) => signal !== void 0), fired = live.find((signal) => signal.aborted);
+  if (fired !== void 0)
+    return Promise.resolve({ aborted: !0, reason: fired.reason });
+  return new Promise((resolve, reject) => {
+    const cleanup = new AbortController, timer = budgetMs === null || budgetMs <= 0 ? null : setTimeout(() => {
+      cleanup.abort();
+      resolve({ aborted: !0, reason: new WaitBudgetElapsedError });
+    }, budgetMs), settle = () => {
+      cleanup.abort();
+      if (timer !== null)
+        clearTimeout(timer);
+    };
+    for (const signal of live)
+      signal.addEventListener("abort", () => {
+        settle();
+        resolve({ aborted: !0, reason: signal.reason });
+      }, { once: !0, signal: cleanup.signal });
+    (async () => {
+      try {
+        const value = await run();
+        settle();
+        resolve({ aborted: !1, value });
+      } catch (error) {
+        settle();
+        reject(error);
+      }
+    })();
+  });
+}

package/dist/core/application-primitive-attempt-registry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The process-local registry of live claim attempts for one scope of an
+ * application primitive (WFT-84, WFT-85), and the lease-commit serial that
+ * fences reconciliation against it.
+ *
+ * Registrations live here rather than in durable storage because an
+ * `AbortSignal` is process-local by construction; the registry is what lets a
+ * cancellation, settlement, or maintenance pass in this process reach a
+ * claimant in this process. Another process learns from renewal instead.
+ *
+ * @module core/application-primitive-attempt-registry
+ */
+import type { Storage } from '../storage/interface.ts';
+/**
+ * One live attempt in this process: its abort controller plus the callback that
+ * forgets it from the handle that claimed it.
+ *
+ * Carrying the release alongside the controller is what lets a *sibling* handle
+ * — one running maintenance, or settling with a token it was handed — release
+ * ownership from the handle that actually owns it. Without that, the claiming
+ * handle's ownership set leaks one entry per attempt settled elsewhere.
+ */
+export type AttemptRegistration = {
+    readonly controller: AbortController;
+    readonly release: () => void;
+    /**
+     * The subject (command, delivery) the attempt belongs to, so a caller-supplied
+     * token cannot release another subject's attempt.
+     */
+    readonly subjectId: string;
+    /**
+     * The process-local lease-commit serial this attempt's lease landed under, or
+     * `null` while its compare-and-swap is still in flight. A reconciliation from
+     * a durable snapshot releases only attempts that committed BEFORE the
+     * snapshot was read: a snapshot cannot speak for a lease that landed after it.
+     */
+    committedSerial: number | null;
+};
+/**
+ * The process-local attempt registry for one scope: a map from attempt token
+ * to registration, with a secondary index from subject id to the tokens
+ * registered for it, so reconciling one subject costs its own attempts rather
+ * than a walk over every live claim in the scope.
+ */
+export declare class AttemptRegistry extends Map<string, AttemptRegistration> {
+    #private;
+    constructor();
+    set(attemptToken: string, registration: AttemptRegistration): this;
+    delete(attemptToken: string): boolean;
+    clear(): void;
+    /** The tokens currently registered for one subject, as a snapshot safe to release from. */
+    tokensFor(subjectId: string): string[];
+}
+/** Record one more lease committed by this process and return its serial. */
+export declare function nextLeaseCommitSerial(): number;
+/** The serial of the latest lease this process committed; read before a snapshot to fence reconciliation. */
+export declare function leaseCommitSerial(): number;
+/**
+ * Acquire the shared attempt-controller registry for one scope in this process.
+ * Every acquisition is balanced by {@link releaseAttemptControllerRegistry}
+ * from the handle's `dispose()`.
+ */
+export declare function attemptControllerRegistry(storage: Storage, primitive: string, namespace: string, scopeId: string): AttemptRegistry;
+/**
+ * Release one handle's hold on a scope registry.
+ *
+ * The scope is forgotten once no handle holds it and no attempt is live in it.
+ * A service that creates short-lived handles for many resource ids over one
+ * long-lived storage would otherwise retain a map per historical resource. A
+ * live attempt owned by a sibling handle keeps the scope until it settles.
+ */
+export declare function releaseAttemptControllerRegistry(storage: Storage, primitive: string, namespace: string, scopeId: string): void;
+/** Whether this process still tracks a registry for the scope. Diagnostics and tests. */
+export declare function hasAttemptControllerScope(storage: Storage, primitive: string, namespace: string, scopeId: string): boolean;

package/dist/core/application-primitive-attempt-registry.js

@@ -0,0 +1,73 @@
+export class AttemptRegistry extends Map {
+  #bySubject;
+  constructor() {
+    super();
+    this.#bySubject = new Map;
+  }
+  set(attemptToken, registration) {
+    super.set(attemptToken, registration);
+    let tokens = this.#bySubject.get(registration.subjectId);
+    if (tokens === void 0) {
+      tokens = new Set;
+      this.#bySubject.set(registration.subjectId, tokens);
+    }
+    tokens.add(attemptToken);
+    return this;
+  }
+  delete(attemptToken) {
+    const registration = this.get(attemptToken);
+    if (registration === void 0)
+      return !1;
+    super.delete(attemptToken);
+    const tokens = this.#bySubject.get(registration.subjectId);
+    tokens?.delete(attemptToken);
+    if (tokens?.size === 0)
+      this.#bySubject.delete(registration.subjectId);
+    return !0;
+  }
+  clear() {
+    super.clear();
+    this.#bySubject.clear();
+  }
+  tokensFor(subjectId) {
+    return [...this.#bySubject.get(subjectId) ?? []];
+  }
+}
+let localLeaseCommits = 0;
+export function nextLeaseCommitSerial() {
+  localLeaseCommits += 1;
+  return localLeaseCommits;
+}
+export function leaseCommitSerial() {
+  return localLeaseCommits;
+}
+const ATTEMPT_CONTROLLERS_BY_STORAGE = new WeakMap;
+function scopeKey(primitive, namespace, scopeId) {
+  return `${primitive}:${encodeURIComponent(namespace)}:${encodeURIComponent(scopeId)}`;
+}
+export function attemptControllerRegistry(storage, primitive, namespace, scopeId) {
+  let byScope = ATTEMPT_CONTROLLERS_BY_STORAGE.get(storage);
+  if (byScope === void 0) {
+    byScope = new Map;
+    ATTEMPT_CONTROLLERS_BY_STORAGE.set(storage, byScope);
+  }
+  const scope = scopeKey(primitive, namespace, scopeId);
+  let entry = byScope.get(scope);
+  if (entry === void 0) {
+    entry = { controllers: new AttemptRegistry, handles: 0 };
+    byScope.set(scope, entry);
+  }
+  entry.handles += 1;
+  return entry.controllers;
+}
+export function releaseAttemptControllerRegistry(storage, primitive, namespace, scopeId) {
+  const byScope = ATTEMPT_CONTROLLERS_BY_STORAGE.get(storage), scope = scopeKey(primitive, namespace, scopeId), entry = byScope?.get(scope);
+  if (byScope === void 0 || entry === void 0)
+    return;
+  entry.handles = Math.max(0, entry.handles - 1);
+  if (entry.handles === 0 && entry.controllers.size === 0)
+    byScope.delete(scope);
+}
+export function hasAttemptControllerScope(storage, primitive, namespace, scopeId) {
+  return ATTEMPT_CONTROLLERS_BY_STORAGE.get(storage)?.has(scopeKey(primitive, namespace, scopeId)) === !0;
+}

package/dist/core/application-primitive-codec.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Fail-closed readers shared by the application primitives' codecs (WFT-84, WFT-85).
+ *
+ * Every reader raises `PersistedDataCorruptError` for the key being decoded
+ * rather than coercing a damaged value into something plausible. The record
+ * codec and the index codec are built from these.
+ *
+ * @module core/application-primitive-codec
+ */
+export declare function isRecordObject(value: unknown): value is Record<string, unknown>;
+export declare function fail(key: string): never;
+export declare function readString(source: Record<string, unknown>, field: string, key: string): string;
+export declare function readOptionalString(source: Record<string, unknown>, field: string, key: string): string | undefined;
+export declare function readInteger(source: Record<string, unknown>, field: string, key: string): number;
+/**
+ * Admission requires these to be positive, so a persisted zero is corruption:
+ * a zero visibility timeout would hand out a lease that is reclaimable the
+ * instant it is granted, and zero attempts would deliver work that is already
+ * exhausted.
+ */
+export declare function readPositiveInteger(source: Record<string, unknown>, field: string, key: string): number;
+export declare function readOptionalInteger(source: Record<string, unknown>, field: string, key: string): number | undefined;
+export declare function readVersion(source: Record<string, unknown>, key: string, expected?: number): void;
+/**
+ * Rebuild the key a record's own identity names. Key construction percent-encodes
+ * each component and throws a raw `URIError` on an unpaired surrogate; a
+ * persisted identity that malformed is corruption and must surface as such.
+ */
+export declare function ownKey(build: () => string, key: string): string;
+/**
+ * A persisted command id is handed straight to key construction by `claim()`,
+ * `list()`, the waits, and idempotency lookups; an unpaired surrogate or an
+ * oversized value there would escape as a raw `URIError` rather than the
+ * corruption it is.
+ */
+export declare function readIdentifier(value: unknown, key: string): string;

package/dist/core/application-primitive-codec.js

@@ -0,0 +1,56 @@
+import { MAX_APPLICATION_IDENTITY_BYTES, isWellFormedString } from "./mailbox-guards.js";
+import { MAILBOX_RECORD_VERSION } from "./mailbox-types.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+export function isRecordObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function fail(key) {
+  throw new PersistedDataCorruptError(key);
+}
+export function readString(source, field, key) {
+  const value = source[field];
+  if (typeof value !== "string" || value.length === 0)
+    fail(key);
+  return value;
+}
+export function readOptionalString(source, field, key) {
+  const value = source[field];
+  if (value === void 0)
+    return;
+  if (typeof value !== "string")
+    fail(key);
+  return value;
+}
+export function readInteger(source, field, key) {
+  const value = source[field];
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    fail(key);
+  return value;
+}
+export function readPositiveInteger(source, field, key) {
+  const value = readInteger(source, field, key);
+  if (value === 0)
+    fail(key);
+  return value;
+}
+export function readOptionalInteger(source, field, key) {
+  if (source[field] === void 0)
+    return;
+  return readInteger(source, field, key);
+}
+export function readVersion(source, key, expected = MAILBOX_RECORD_VERSION) {
+  if (source.recordVersion !== expected)
+    fail(key);
+}
+export function ownKey(build, key) {
+  try {
+    return build();
+  } catch {
+    return fail(key);
+  }
+}
+export function readIdentifier(value, key) {
+  if (typeof value !== "string" || value.length === 0 || !isWellFormedString(value) || new TextEncoder().encode(value).byteLength > MAX_APPLICATION_IDENTITY_BYTES)
+    fail(key);
+  return value;
+}

package/dist/core/application-primitive-commit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Committing one durable state transition of an application primitive,
+ * atomically with the fleet event that describes it (WFT-84, WFT-85).
+ *
+ * A transition is a compare-and-swap plan: the conditions it was decided
+ * against and the operations that carry it out. Without an event sink the plan
+ * is a plain conditional batch. With one, the sink is asked to append the event
+ * under the same conditions and operations, and the FIRST commit through a sink
+ * also writes a single-use probe key that is read back afterwards: nothing else
+ * ever writes that key, so a concurrent transition on the record between the
+ * commit and the read cannot be mistaken for a sink that committed to a
+ * different backend.
+ *
+ * @module core/application-primitive-commit
+ */
+import type { BatchOperation, ConditionalBatchCondition, Storage } from '../storage/interface.ts';
+/**
+ * What a primitive needs from a fleet event feed: append one event atomically
+ * with the transition's conditions and operations. Structural on purpose, so
+ * the core never imports the server's feed.
+ */
+export type ApplicationEventSink = {
+    append(event: {
+        readonly kind: string;
+        readonly emittedAtMs: number;
+        readonly payload: unknown;
+    }, transaction: {
+        readonly conditions: readonly ConditionalBatchCondition[];
+        readonly operations: readonly BatchOperation[];
+    }): Promise<unknown>;
+};
+/** One durable state transition, optionally paired with the fleet event that describes it. */
+export type ApplicationCommitPlan = {
+    readonly conditions: readonly ConditionalBatchCondition[];
+    readonly operations: readonly BatchOperation[];
+    readonly event: {
+        readonly kind: string;
+        readonly payload: unknown;
+    } | null;
+    readonly now: number;
+    /**
+     * Where the first commit through an event sink writes its verification
+     * probe. Unique per plan, so a concurrent transition on the record can never
+     * be mistaken for a sink that committed somewhere else.
+     */
+    readonly sinkProbeKey: string;
+};
+/**
+ * Whether every compare-and-swap condition still matches durable state.
+ *
+ * Used to classify a failed event-sink append: if the caller's own conditions
+ * still hold, the append failed for the feed's own reasons and the error must
+ * propagate; if one moved, another actor won the race and the caller retries.
+ */
+export declare function conditionsStillHold(storage: Storage, conditions: readonly ConditionalBatchCondition[]): Promise<boolean>;
+/** Byte-for-byte equality of two values, as `conditionalBatch` compares them. */
+export declare function bytesEqual(left: Uint8Array, right: Uint8Array): boolean;
+/**
+ * Commit one transition, atomically with its fleet event when a sink is
+ * configured.
+ *
+ * Returns `false` when a compare-and-swap condition was lost, which means
+ * another actor transitioned the record first and the caller should re-read and
+ * re-decide. Any other failure throws. `subject` names the primitive in the
+ * misconfiguration diagnostic ("application mailbox", "application outbox").
+ */
+export declare function commitApplicationTransition(storage: Storage, events: ApplicationEventSink | undefined, plan: ApplicationCommitPlan, subject: string): Promise<boolean>;

package/dist/core/application-primitive-commit.js

@@ -0,0 +1,66 @@
+import { storageConditionalBatch } from "../storage/interface.js";
+export async function conditionsStillHold(storage, conditions) {
+  for (const condition of conditions) {
+    const current = await storage.get(condition.key);
+    if (condition.expectedValue === null) {
+      if (current !== null)
+        return !1;
+      continue;
+    }
+    if (current === null || !bytesEqual(current, condition.expectedValue))
+      return !1;
+  }
+  return !0;
+}
+export function bytesEqual(left, right) {
+  if (left.byteLength !== right.byteLength)
+    return !1;
+  for (let index = 0;index < left.byteLength; index += 1)
+    if (left[index] !== right[index])
+      return !1;
+  return !0;
+}
+export async function commitApplicationTransition(storage, events, plan, subject) {
+  if (events === void 0 || plan.event === null)
+    return storageConditionalBatch(storage, [...plan.conditions], [...plan.operations]);
+  const probe = isSinkVerified(storage, events) ? null : { key: plan.sinkProbeKey, value: new TextEncoder().encode(plan.sinkProbeKey) };
+  try {
+    await events.append({ kind: plan.event.kind, emittedAtMs: plan.now, payload: plan.event.payload }, {
+      conditions: plan.conditions,
+      operations: probe === null ? plan.operations : [...plan.operations, { type: "put", key: probe.key, value: probe.value }]
+    });
+  } catch (error) {
+    if (await conditionsStillHold(storage, plan.conditions))
+      throw error;
+    return !1;
+  }
+  if (probe !== null)
+    await assertSinkCommittedLocally(storage, events, probe, subject);
+  return !0;
+}
+const VERIFIED_SINK_BACKENDS = new WeakMap;
+function verifiedBackendsFor(events) {
+  let verified = VERIFIED_SINK_BACKENDS.get(events);
+  if (verified === void 0) {
+    verified = new WeakSet;
+    VERIFIED_SINK_BACKENDS.set(events, verified);
+  }
+  return verified;
+}
+function isSinkVerified(storage, events) {
+  return verifiedBackendsFor(events).has(storage);
+}
+async function assertSinkCommittedLocally(storage, events, probe, subject) {
+  let stored;
+  try {
+    stored = await storage.get(probe.key);
+  } catch {
+    return;
+  }
+  if (stored === null || !bytesEqual(stored, probe.value))
+    throw Error(`The configured ${subject} event sink committed to a different storage backend than the ${subject}. Build the fleet event feed over the same Storage instance the ${subject} uses.`);
+  verifiedBackendsFor(events).add(storage);
+  try {
+    await storage.delete(probe.key);
+  } catch {}
+}

package/dist/core/application-primitive-guards.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Field-level guards shared by the durable application primitives (the
+ * command mailbox, WFT-84, and the delivery outbox, WFT-85): identity
+ * components, durable JSON metadata, injected clock readings, generated
+ * identifiers, derived instants, and wait budgets.
+ *
+ * Every guard rejects at the boundary that owns the contract rather than letting
+ * a bad value reach durable storage — a record the decoder cannot read back
+ * would surface much later as corruption on an unrelated read.
+ *
+ * The guards are produced by a factory bound to the primitive's own validation
+ * error class, so a mailbox caller sees `ApplicationCommandValidationError` and
+ * an outbox caller sees its own, while the checks themselves are written once.
+ *
+ * @module core/application-primitive-guards
+ */
+import { type JSONValue } from './json.ts';
+/** Maximum bytes in any opaque identity component (namespace, resource, owner, caller, target, kind). */
+export declare const MAX_APPLICATION_IDENTITY_BYTES = 256;
+/** Maximum encoded bytes for durable JSON metadata such as an outcome, progress, or failure details. */
+export declare const MAX_DURABLE_METADATA_BYTES = 65536;
+/**
+ * The largest delay `setTimeout` schedules faithfully (a signed 32-bit
+ * millisecond count). A larger value is clamped to a tick by the runtime, which
+ * would turn a rare poll into a tight loop against durable storage.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Default gap between durable polls for the bounded waits. */
+export declare const DEFAULT_WAIT_POLL_INTERVAL_MS = 50;
+/** The UTF-8 length of a string. */
+export declare function byteLengthOf(value: string): number;
+/** Whether a string contains no unpaired surrogate. */
+export declare function isWellFormedString(value: string): boolean;
+/** A validation error class a primitive binds its guards to. */
+export type ApplicationValidationErrorClass = new (message: string, options?: ErrorOptions) => Error;
+/** The guard set produced by {@link createApplicationGuards}. */
+export type ApplicationGuards = {
+    readonly requireIdentity: (value: unknown, field: string, maxBytes: number) => string;
+    readonly optionalIdentityOf: (value: unknown, field: string, maxBytes: number) => string | undefined;
+    readonly requirePositiveInteger: (value: unknown, field: string, maximum: number) => number;
+    readonly requireNonNegativeInteger: (value: unknown, field: string, maximum: number) => number;
+    readonly validateDurableJSONValue: (value: unknown, field: string) => JSONValue | undefined;
+    readonly requireGeneratedIdentifier: (value: string, field: string) => string;
+    readonly requireClockInstant: (now: number, source?: string) => number;
+    readonly requireDerivedInstant: (instant: number, field: string) => number;
+    readonly requireMaintenanceInstant: (now: number) => number;
+    readonly requireWaitBudget: (options: {
+        readonly timeoutMs?: number | undefined;
+        readonly pollIntervalMs?: number | undefined;
+    }) => {
+        readonly timeoutMs: number;
+        readonly pollIntervalMs: number;
+    };
+};
+/**
+ * Bind the shared guards to one primitive's validation error class.
+ *
+ * Every guard throws an instance of `ValidationError`, so callers and tests of
+ * the mailbox keep matching `ApplicationCommandValidationError` while the
+ * outbox matches its own class.
+ */
+export declare function createApplicationGuards(ValidationError: ApplicationValidationErrorClass): ApplicationGuards;

package/dist/core/application-primitive-guards.js

@@ -0,0 +1,89 @@
+import { decode, encode } from "./codec.js";
+import { isJSONValue } from "./json.js";
+export const MAX_APPLICATION_IDENTITY_BYTES = 256, MAX_DURABLE_METADATA_BYTES = 65536, MAX_TIMER_DELAY_MS = 2147483647, DEFAULT_WAIT_POLL_INTERVAL_MS = 50;
+export function byteLengthOf(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+export function isWellFormedString(value) {
+  return value.isWellFormed();
+}
+export function createApplicationGuards(ValidationError) {
+  const requireIdentity = (value, field, maxBytes) => {
+    if (typeof value !== "string" || value.length === 0)
+      throw new ValidationError(`${field} must be a non-empty string.`);
+    if (!isWellFormedString(value))
+      throw new ValidationError(`${field} must be well-formed Unicode: it contains an unpaired surrogate that cannot be encoded into a storage key.`);
+    if (byteLengthOf(value) > maxBytes)
+      throw new ValidationError(`${field} must encode to at most ${maxBytes} bytes.`);
+    return value;
+  };
+  return {
+    requireIdentity,
+    optionalIdentityOf: (value, field, maxBytes) => {
+      if (value === void 0)
+        return;
+      return requireIdentity(value, field, maxBytes);
+    },
+    requirePositiveInteger: (value, field, maximum) => {
+      if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new ValidationError(`${field} must be a safe integer between 1 and ${maximum}.`);
+      return value;
+    },
+    requireNonNegativeInteger: (value, field, maximum) => {
+      if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximum)
+        throw new ValidationError(`${field} must be a safe integer between 0 and ${maximum}.`);
+      return value;
+    },
+    validateDurableJSONValue: (value, field) => {
+      if (value === void 0)
+        return;
+      let snapshot, encoded;
+      try {
+        encoded = encode(value);
+        snapshot = decode(encoded);
+      } catch (cause) {
+        throw new ValidationError(`${field} is not encodable by the structured-clone codec.`, {
+          cause
+        });
+      }
+      if (!isJSONValue(snapshot))
+        throw new ValidationError(`${field} must be a JSON-safe value: durable records reject anything the record decoder cannot read back.`);
+      if (encoded.byteLength > MAX_DURABLE_METADATA_BYTES)
+        throw new ValidationError(`${field} encodes to ${encoded.byteLength} bytes, over the ${MAX_DURABLE_METADATA_BYTES}-byte durable metadata ceiling.`);
+      return snapshot;
+    },
+    requireGeneratedIdentifier: (value, field) => {
+      if (typeof value !== "string" || value.length === 0)
+        throw new ValidationError(`The configured generateId() returned an empty ${field}; durable keys require a non-empty identifier.`);
+      if (!isWellFormedString(value))
+        throw new ValidationError(`The configured generateId() returned a ${field} containing an unpaired surrogate.`);
+      if (byteLengthOf(value) > MAX_APPLICATION_IDENTITY_BYTES)
+        throw new ValidationError(`The configured generateId() returned a ${field} over ${MAX_APPLICATION_IDENTITY_BYTES} bytes.`);
+      return value;
+    },
+    requireClockInstant: (now, source = "now()") => {
+      if (typeof now !== "number" || !Number.isSafeInteger(now) || now < 0)
+        throw new ValidationError(`The configured ${source} returned ${String(now)}; durable records require a non-negative safe-integer millisecond timestamp.`);
+      return now;
+    },
+    requireDerivedInstant: (instant, field) => {
+      if (!Number.isSafeInteger(instant) || instant < 0)
+        throw new ValidationError(`${field} computed to ${String(instant)}, outside the safe-integer millisecond range durable records accept.`);
+      return instant;
+    },
+    requireMaintenanceInstant: (now) => {
+      if (typeof now !== "number" || !Number.isSafeInteger(now) || now < 0)
+        throw new ValidationError("runMaintenance() requires a non-negative safe-integer timestamp in milliseconds.");
+      return now;
+    },
+    requireWaitBudget: (options) => {
+      const timeoutMs = options.timeoutMs ?? 0;
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_TIMER_DELAY_MS)
+        throw new ValidationError(`timeoutMs must be a non-negative safe integer of at most ${MAX_TIMER_DELAY_MS} milliseconds, the largest delay a timer can schedule; the in-flight budget is scheduled as one timer.`);
+      const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_WAIT_POLL_INTERVAL_MS;
+      if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 1 || pollIntervalMs > MAX_TIMER_DELAY_MS)
+        throw new ValidationError(`pollIntervalMs must be a positive safe integer of at most ${MAX_TIMER_DELAY_MS} milliseconds, the largest delay a timer can schedule.`);
+      return { timeoutMs, pollIntervalMs };
+    }
+  };
+}

package/dist/core/application-primitive-payload.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Payload and causation validation shared by the durable application
+ * primitives (the command mailbox, WFT-84, and the delivery outbox, WFT-85).
+ *
+ * Both primitives carry the same inline-or-reference payload and the same
+ * causal metadata, bound to the same content digest, so the checks are written
+ * once and bound to each primitive's own validation error class.
+ *
+ * @module core/application-primitive-payload
+ */
+import { type ApplicationValidationErrorClass } from './application-primitive-guards.ts';
+import type { ApplicationCommandCausation, ApplicationCommandPayload } from './mailbox-types.ts';
+/** Maximum bytes in a content-addressed payload reference. */
+export declare const MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES = 2048;
+/** A validated payload with its digest. */
+export type ValidatedPayload = {
+    readonly payload: ApplicationCommandPayload;
+    readonly digest: string;
+};
+/** The validator set produced by {@link createPayloadValidators}. */
+export type PayloadValidators = {
+    readonly validatePayload: (payload: unknown, maxInlinePayloadBytes: number) => Promise<ValidatedPayload>;
+    readonly validateCausation: (causation: ApplicationCommandCausation | undefined) => ApplicationCommandCausation | undefined;
+};
+/**
+ * Bind the shared payload validators to one primitive's validation error
+ * class.
+ */
+export declare function createPayloadValidators(ValidationError: ApplicationValidationErrorClass): PayloadValidators;