@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/engine/source-registration.js

@@ -0,0 +1,36 @@
+import { utf8ByteLength } from "../../worker/manifest/utf8.js";
+import { MAX_CONTRACT_IDENTIFIER_BYTES } from "../contract/limits.js";
+import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+function assertWellFormedSourceDescriptor(source) {
+  const { kind, name, revision } = source.descriptor;
+  if (typeof kind !== "string" || kind.length === 0)
+    throw TypeError("registerSource(): source.descriptor.kind must be a non-empty string");
+  if (typeof name !== "string" || name.length === 0)
+    throw TypeError("registerSource(): source.descriptor.name must be a non-empty string");
+  if (typeof revision !== "string" || revision.length === 0)
+    throw TypeError("registerSource(): source.descriptor.revision must be a non-empty string");
+  const revisionBytes = utf8ByteLength(revision);
+  if (revisionBytes > MAX_CONTRACT_IDENTIFIER_BYTES)
+    throw TypeError(`registerSource(): source.descriptor.revision is ${revisionBytes} bytes, exceeding the maximum identifier size of ${MAX_CONTRACT_IDENTIFIER_BYTES}`);
+}
+export function registerSource(internals, source) {
+  assertWellFormedSourceDescriptor(source);
+  const { name, revision } = source.descriptor;
+  validateWorkflowOrActivityName(name, "workflow");
+  Object.freeze(source.descriptor);
+  if (internals.registrations.has(name))
+    throw Error(`Cannot registerSource("${name}"): "${name}" is already registered as an eager workflow via engine.register(). A workflow name may not be both eagerly registered and a dynamic source.`);
+  let byRevision = internals.workflowSourcesByName.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    internals.workflowSourcesByName.set(name, byRevision);
+  }
+  const existing = byRevision.get(revision);
+  if (existing === void 0) {
+    byRevision.set(revision, source);
+    return;
+  }
+  if (existing === source)
+    return;
+  throw Error(`Cannot registerSource("${name}", "${revision}"): a different source handle is already registered for this exact (name, revision) key.`);
+}

package/dist/core/engine/source-resolution.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `resolveWorkflowSource()` — the async, single-flight entry point that
+ * loads, validates, and installs one dynamic workflow source revision
+ * (WFT-13/14).
+ *
+ * Single-flight per `(name, revision)`: the underlying load+validate+install
+ * work is shared by every concurrent caller for the same key via
+ * `internals.sourceResolutionsInFlight`, but each caller races that shared
+ * work against its OWN per-call cancellation interest — a cancelled waiter
+ * never aborts a load another waiter still needs, and the shared load
+ * itself is never tied to any individual caller's lifetime. Disposal aborts
+ * every outstanding waiter (rejecting each pending `resolveWorkflowSource()`
+ * call) without touching the shared load, which keeps running to whatever
+ * point it naturally settles.
+ *
+ * @module core/engine/source-resolution
+ */
+import type { WorkflowRevisionRecord } from '../catalog/index.ts';
+import type { Engine } from './index.ts';
+/**
+ * Options accepted by {@link resolveWorkflowSource}.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import type { ResolveWorkflowSourceOptions } from '@lostgradient/weft';
+ *
+ * declare const engine: Engine;
+ * const options: ResolveWorkflowSourceOptions = { signal: AbortSignal.timeout(5_000) };
+ * const record = await engine.resolveWorkflowSource('checkout', 'r1', options);
+ * console.log(record.manifest.revision);
+ * ```
+ */
+export type ResolveWorkflowSourceOptions = {
+    /** When aborted, this caller's own `resolveWorkflowSource()` call rejects; a load already in flight for other callers is unaffected. */
+    signal?: AbortSignal;
+};
+/**
+ * Load, validate, and install one dynamic workflow source revision
+ * previously recorded via `engine.registerSource()`. Returns the installed
+ * {@link WorkflowRevisionRecord} immediately, without invoking the loader
+ * at all, when `(name, revision)` is already durably installed — including
+ * a revision installed by a different process. When that is the case,
+ * `internals.resolvedWorkflowSources` is NOT populated for this key (there
+ * is no locally-loaded `WorkflowDefinition` to stash — only the durable
+ * manifest was ever read) even though the catalog itself considers the
+ * revision installed; a later batch reading `resolvedWorkflowSources` must
+ * account for that gap rather than assuming every installed revision has a
+ * live definition available in this process. This fast path still requires
+ * `registerSource()` to have been called for this exact key first (see
+ * {@link resolveCachedOrHandle}), and still validates a pinned
+ * `workflowVersion`/`contractHash` against the cached manifest — the ONLY
+ * thing it skips is re-invoking the loader and re-running
+ * {@link import('../source/index.ts').validateResolvedWorkflowSource}.
+ *
+ * Single-flight per `(name, revision)` — see the module doc for the full
+ * cancellation contract. Throws a plain `Error` when `registerSource()` was
+ * never called for this exact key (a programmer error, not untrusted-input
+ * rejection); throws {@link WorkflowSourceValidationError} when the loaded
+ * module fails validation, OR when a cached manifest contradicts a pinned
+ * `workflowVersion`/`contractHash`; throws {@link EngineDisposedError} when
+ * the engine is disposed, either already or during the call; propagates
+ * {@link import('../catalog/index.ts').WorkflowCatalogConflictError}
+ * unwrapped on a genuine content conflict with an already-installed
+ * revision.
+ *
+ * @example
+ * ```ts
+ * import { Engine, workflowSource } from '@lostgradient/weft';
+ *
+ * declare const engine: Engine;
+ * declare const loadCheckout: () => Promise<{
+ *   checkout: import('@lostgradient/weft').WorkflowDefinition<unknown, unknown, 'checkout'>;
+ * }>;
+ * engine.registerSource(
+ *   workflowSource(
+ *     { name: 'checkout', location: './checkout.ts', exportName: 'checkout', revision: 'r1' },
+ *     loadCheckout,
+ *   ),
+ * );
+ * const record = await engine.resolveWorkflowSource('checkout', 'r1');
+ * console.log(record.manifest.revision);
+ * ```
+ */
+export declare function resolveWorkflowSource(engine: Engine, name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;

package/dist/core/engine/source-resolution.js

@@ -0,0 +1,119 @@
+import {
+  checkWorkflowCompatibility,
+  DEFAULT_WORKFLOW_COMPATIBILITY_POLICY
+} from "../contract/compatibility.js";
+import {
+  buildExpectedManifest,
+  resolveSourceModule,
+  validateResolvedWorkflowSource,
+  WorkflowSourceValidationError
+} from "../source/index.js";
+import { ensureWorkflowCatalogReady, isWorkflowCatalogReady } from "./catalog-readiness.js";
+import { EngineDisposedError } from "./errors.js";
+import { getInternals, getWorkflowCatalog } from "./internals.js";
+function toAbortError(signal) {
+  const reason = signal.reason;
+  return reason instanceof Error ? reason : Error("resolveWorkflowSource() aborted");
+}
+function abortRejection(signal) {
+  return new Promise((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(toAbortError(signal)), { once: !0 });
+  });
+}
+async function runSharedSourceLoad(engine, internals, name, revision, handle) {
+  const resolved = await resolveSourceModule(handle.descriptor, handle);
+  if (!resolved.ok)
+    throw new WorkflowSourceValidationError(name, revision, [resolved.reason]);
+  const outcome = await validateResolvedWorkflowSource(handle.descriptor, resolved.moduleValue);
+  if (!outcome.ok)
+    throw new WorkflowSourceValidationError(name, revision, outcome.reasons);
+  if (internals.disposed)
+    throw new EngineDisposedError;
+  const installed = await getWorkflowCatalog(engine).install(outcome.manifest, outcome.definition);
+  if (!internals.disposed) {
+    let resolvedByRevision = internals.resolvedWorkflowSources.get(name);
+    if (resolvedByRevision === void 0) {
+      resolvedByRevision = new Map;
+      internals.resolvedWorkflowSources.set(name, resolvedByRevision);
+    }
+    resolvedByRevision.set(revision, {
+      definition: outcome.loadedDefinition,
+      activityRegistry: outcome.activityRegistry
+    });
+  }
+  return { manifest: installed.manifest, installedAt: installed.installedAt };
+}
+function getOrCreateSharedSourceLoad(engine, internals, name, revision, handle) {
+  let byRevision = internals.sourceResolutionsInFlight.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    internals.sourceResolutionsInFlight.set(name, byRevision);
+  }
+  const existing = byRevision.get(revision);
+  if (existing !== void 0)
+    return existing;
+  const shared = runSharedSourceLoad(engine, internals, name, revision, handle).finally(() => {
+    const currentByRevision = internals.sourceResolutionsInFlight.get(name);
+    if (currentByRevision?.get(revision) !== shared)
+      return;
+    currentByRevision.delete(revision);
+    if (currentByRevision.size === 0)
+      internals.sourceResolutionsInFlight.delete(name);
+  });
+  shared.catch(() => {});
+  byRevision.set(revision, shared);
+  return shared;
+}
+function createWaiterAbort(options) {
+  const controller = new AbortController, forwardAbort = () => controller.abort(options?.signal?.reason);
+  if (options?.signal?.aborted)
+    forwardAbort();
+  else
+    options?.signal?.addEventListener("abort", forwardAbort, { once: !0 });
+  return { controller, detach: () => options?.signal?.removeEventListener("abort", forwardAbort) };
+}
+async function resolveCachedOrHandle(engine, internals, name, revision) {
+  const handle = internals.workflowSourcesByName.get(name)?.get(revision);
+  if (handle === void 0)
+    throw Error(`resolveWorkflowSource("${name}", "${revision}") was called before registerSource() ` + "registered this exact (name, revision) \u2014 call engine.registerSource() first.");
+  if (!isWorkflowCatalogReady(engine))
+    await ensureWorkflowCatalogReady(engine);
+  const existing = await getWorkflowCatalog(engine).resolveEntry(name, revision);
+  if (existing !== void 0) {
+    const expectedManifest = buildExpectedManifest(handle.descriptor, existing.manifest), verdict = checkWorkflowCompatibility(expectedManifest, existing.manifest, DEFAULT_WORKFLOW_COMPATIBILITY_POLICY);
+    if (!verdict.compatible)
+      throw new WorkflowSourceValidationError(name, revision, verdict.reasons);
+    return { cached: existing };
+  }
+  return { handle };
+}
+export async function resolveWorkflowSource(engine, name, revision, options) {
+  const internals = getInternals(engine), waiter = createWaiterAbort(options);
+  if (waiter.controller.signal.aborted) {
+    waiter.detach();
+    throw toAbortError(waiter.controller.signal);
+  }
+  if (internals.disposed) {
+    waiter.detach();
+    throw new EngineDisposedError;
+  }
+  internals.sourceResolutionWaiterControllers.add(waiter.controller);
+  try {
+    const cachedOrHandle = resolveCachedOrHandle(engine, internals, name, revision), cachedOrHandleAbort = abortRejection(waiter.controller.signal);
+    cachedOrHandleAbort.catch(() => {});
+    let outcome;
+    try {
+      outcome = await Promise.race([cachedOrHandle, cachedOrHandleAbort]);
+    } finally {
+      cachedOrHandle.catch(() => {});
+    }
+    if (outcome.cached !== void 0)
+      return outcome.cached;
+    const shared = getOrCreateSharedSourceLoad(engine, internals, name, revision, outcome.handle), waiterAbort = abortRejection(waiter.controller.signal);
+    waiterAbort.catch(() => {});
+    return await Promise.race([shared, waiterAbort]);
+  } finally {
+    waiter.detach();
+    internals.sourceResolutionWaiterControllers.delete(waiter.controller);
+  }
+}

package/dist/core/engine/validation.js

@@ -121,7 +121,7 @@ export function decodeWorkflowState(bytes) {
     liftFlatVersionTuple(decodedRecord);
   const state = decoded;
   if (!isValidDecodedTags(state.tags)) {
-    console.warn(`[weft] Decoded workflow state for "${String(state.id)}" has invalid tags; dropping the malformed tag list from the decoded state.`);
+    console.warn(`[weft] Decoded workflow state for "${state.id}" has invalid tags; dropping the malformed tag list from the decoded state.`);
     delete state.tags;
   }
   if (state.failureCategory !== void 0 && state.failureCategory !== null) {
@@ -135,7 +135,7 @@ export function decodeWorkflowState(bytes) {
     try {
       coerceStartWorkflowId(state.executionStateOwnerId, "executionStateOwnerId");
     } catch {
-      console.warn(`[weft] Decoded workflow state for "${String(state.id)}" has an invalid executionStateOwnerId field; falling back to the workflow id as the execution owner. This usually indicates corruption or tampering of the storage record.`);
+      console.warn(`[weft] Decoded workflow state for "${state.id}" has an invalid executionStateOwnerId field; falling back to the workflow id as the execution owner. This usually indicates corruption or tampering of the storage record.`);
       delete state.executionStateOwnerId;
     }
   sanitizeDecodedParentLineage(state);

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

@@ -0,0 +1,117 @@
+import type { WorkflowCompatibilityReason } from '../contract/compatibility.ts';
+/**
+ * Fired on the {@link Engine} when a `(name, revision)` is durably installed
+ * into the workflow catalog for the first time. Never fired for a
+ * byte-identical reinstall of an already-installed revision. Read
+ * `e.workflowType` and `e.revision` directly off the event.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionInstalledEvent, workflow } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowRevisionInstalledEvent.type, (event) => {
+ *   console.log('installed:', event.workflowType, event.revision);
+ * });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * ```
+ */
+export declare class WorkflowRevisionInstalledEvent extends Event {
+    static readonly type: "catalog:revision-installed";
+    readonly workflowType: string;
+    readonly revision: string;
+    constructor(workflowType: string, revision: string);
+}
+/**
+ * Fired on the {@link Engine} when a `(name, revision)` becomes the active
+ * revision for its name — bumping the catalog's per-name `generation`
+ * counter. `previousRevision` is `undefined` on a name's first-ever
+ * activation, and set to the revision this activation replaced otherwise.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionActivatedEvent, workflow } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowRevisionActivatedEvent.type, (event) => {
+ *   console.log('activated:', event.workflowType, event.revision, 'gen', event.generation);
+ * });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * ```
+ */
+export declare class WorkflowRevisionActivatedEvent extends Event {
+    static readonly type: "catalog:revision-activated";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly generation: number;
+    readonly previousRevision: string | undefined;
+    constructor(workflowType: string, revision: string, generation: number, previousRevision: string | undefined);
+}
+/**
+ * Fired on the {@link Engine} when a candidate activation
+ * (`activateCatalogRevisionCandidate`, the guarded primitive) is refused.
+ * `reason` is a closed, low-cardinality union safe to use as a metric label;
+ * `incompatibilityReasons` is populated only when `reason === 'incompatible'`,
+ * carrying every applicable {@link WorkflowCompatibilityReason} — never the
+ * full compatibility verdict object.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionActivationRejectedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowRevisionActivationRejectedEvent.type, (event) => {
+ *   console.log('rejected:', event.workflowType, event.candidateRevision, event.reason);
+ * });
+ * ```
+ */
+export declare class WorkflowRevisionActivationRejectedEvent extends Event {
+    static readonly type: "catalog:activation-rejected";
+    readonly workflowType: string;
+    readonly candidateRevision: string;
+    readonly reason: 'incompatible' | 'stale-generation' | 'conflict' | 'expected-generation-required';
+    readonly incompatibilityReasons: readonly WorkflowCompatibilityReason[] | undefined;
+    constructor(workflowType: string, candidateRevision: string, reason: 'incompatible' | 'stale-generation' | 'conflict' | 'expected-generation-required', incompatibilityReasons?: readonly WorkflowCompatibilityReason[]);
+}
+/**
+ * Fired on the {@link Engine} alongside {@link WorkflowRevisionActivatedEvent}
+ * when activating a new revision displaces a previously active one for the
+ * same name. Never fired on a name's first-ever activation (there is
+ * nothing to drain).
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionDrainingEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowRevisionDrainingEvent.type, (event) => {
+ *   console.log('draining:', event.workflowType, event.revision);
+ * });
+ * ```
+ */
+export declare class WorkflowRevisionDrainingEvent extends Event {
+    static readonly type: "catalog:revision-draining";
+    readonly workflowType: string;
+    readonly revision: string;
+    constructor(workflowType: string, revision: string);
+}
+/**
+ * Fired on the {@link Engine} when a `(name, revision)` is durably removed
+ * from the workflow catalog via `removeWorkflowRevision`.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionRemovedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowRevisionRemovedEvent.type, (event) => {
+ *   console.log('removed:', event.workflowType, event.revision);
+ * });
+ * ```
+ */
+export declare class WorkflowRevisionRemovedEvent extends Event {
+    static readonly type: "catalog:revision-removed";
+    readonly workflowType: string;
+    readonly revision: string;
+    constructor(workflowType: string, revision: string);
+}

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

@@ -0,0 +1,62 @@
+export class WorkflowRevisionInstalledEvent extends Event {
+  static type = "catalog:revision-installed";
+  workflowType;
+  revision;
+  constructor(workflowType, revision) {
+    super(WorkflowRevisionInstalledEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+  }
+}
+
+export class WorkflowRevisionActivatedEvent extends Event {
+  static type = "catalog:revision-activated";
+  workflowType;
+  revision;
+  generation;
+  previousRevision;
+  constructor(workflowType, revision, generation, previousRevision) {
+    super(WorkflowRevisionActivatedEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.generation = generation;
+    this.previousRevision = previousRevision;
+  }
+}
+
+export class WorkflowRevisionActivationRejectedEvent extends Event {
+  static type = "catalog:activation-rejected";
+  workflowType;
+  candidateRevision;
+  reason;
+  incompatibilityReasons;
+  constructor(workflowType, candidateRevision, reason, incompatibilityReasons) {
+    super(WorkflowRevisionActivationRejectedEvent.type);
+    this.workflowType = workflowType;
+    this.candidateRevision = candidateRevision;
+    this.reason = reason;
+    this.incompatibilityReasons = incompatibilityReasons;
+  }
+}
+
+export class WorkflowRevisionDrainingEvent extends Event {
+  static type = "catalog:revision-draining";
+  workflowType;
+  revision;
+  constructor(workflowType, revision) {
+    super(WorkflowRevisionDrainingEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+  }
+}
+
+export class WorkflowRevisionRemovedEvent extends Event {
+  static type = "catalog:revision-removed";
+  workflowType;
+  revision;
+  constructor(workflowType, revision) {
+    super(WorkflowRevisionRemovedEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+  }
+}

package/dist/core/events/event-map.d.ts

@@ -1,6 +1,7 @@
 import type { ReviewCompletedEvent, ReviewRequestedEvent } from '../review/events.ts';
 import type { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent, TaskResultDeadLetteredEvent } from './activity-events.ts';
 import type { AttributesChangedEvent } from './attribute-events.ts';
+import type { WorkflowRevisionActivatedEvent, WorkflowRevisionActivationRejectedEvent, WorkflowRevisionDrainingEvent, WorkflowRevisionInstalledEvent, WorkflowRevisionRemovedEvent } from './catalog-events.ts';
 import type { ScheduleFiredEvent, ScheduleMissedFireEvent } from './schedule-events.ts';
 import type { SignalDeliveredEvent, SignalReceivedEvent } from './signal-events.ts';
 import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent, WorkerConnectedEvent, WorkerDisconnectedEvent } from './system-events.ts';
@@ -57,6 +58,11 @@ export type WeftEventMap = {
     'alert:fired': AlertFiredEvent;
     'alert:resolved': AlertResolvedEvent;
     'constraint:violated': ConstraintViolatedEvent;
+    'catalog:revision-installed': WorkflowRevisionInstalledEvent;
+    'catalog:revision-activated': WorkflowRevisionActivatedEvent;
+    'catalog:activation-rejected': WorkflowRevisionActivationRejectedEvent;
+    'catalog:revision-draining': WorkflowRevisionDrainingEvent;
+    'catalog:revision-removed': WorkflowRevisionRemovedEvent;
 };
 /**
  * Typed version of the `EventTarget` interface that constrains

package/dist/core/events/index.d.ts

@@ -1,5 +1,6 @@
 export * from './activity-events.ts';
 export * from './attribute-events.ts';
+export * from './catalog-events.ts';
 export * from './event-map.ts';
 export * from './schedule-events.ts';
 export * from './signal-events.ts';

package/dist/core/events/index.js

@@ -1,5 +1,6 @@
 export * from "./activity-events.js";
 export * from "./attribute-events.js";
+export * from "./catalog-events.js";
 export * from "./event-map.js";
 export * from "./schedule-events.js";
 export * from "./signal-events.js";

package/dist/core/mailbox-admission.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Admission for the application command mailbox (WFT-84): validating an offered
+ * command, resolving its idempotency identity, enforcing backlog capacity, and
+ * committing the record with its indexes and fleet event.
+ *
+ * Admission is the one transition that also allocates: it advances the mailbox
+ * header's FIFO sequence and open count in the same conditional batch as the
+ * record itself, so backlog accounting can never drift from the records it
+ * describes.
+ *
+ * @module core/mailbox-admission
+ */
+import type { ApplicationCommandAdmission, ApplicationCommandInput, MailboxCapacity } from './mailbox-contract.ts';
+import { type MailboxRuntime } from './mailbox-internals.ts';
+/** Backlog accounting, shared by admission rejection and the public `capacity()`. */
+export declare function capacityOf(runtime: MailboxRuntime, open: number, admitted: number): MailboxCapacity;
+/**
+ * Offer a command to the mailbox.
+ *
+ * An exact retry of the same idempotency identity returns the original
+ * receipt without creating a second command. Reusing the key with a different
+ * caller, target, kind, or payload digest returns a conflict and leaves the
+ * original command untouched. A full backlog is rejected before anything is
+ * persisted.
+ */
+export declare function admitCommand(runtime: MailboxRuntime, command: ApplicationCommandInput): Promise<ApplicationCommandAdmission>;

package/dist/core/mailbox-admission.js

@@ -0,0 +1,130 @@
+import { computeIdentityDigest } from "./application-payload-digest.js";
+import {
+  encodeApplicationCommandIdempotencyRecord,
+  encodeApplicationReadyEntry
+} from "./mailbox-index-codec.js";
+import {
+  describeCommandTransition,
+  MailboxContentionError,
+  MAX_MAILBOX_TRANSITION_ATTEMPTS,
+  toApplicationCommandReceipt
+} from "./mailbox-internals.js";
+import {
+  commitMailboxTransition,
+  headerOperation,
+  loadCommand,
+  loadIdempotencyBinding,
+  loadMailboxHeader,
+  planCommandTransition
+} from "./mailbox-storage.js";
+import { createAdmittedCommandRecord } from "./mailbox-transitions.js";
+import { MAILBOX_RECORD_VERSION } from "./mailbox-types.js";
+import {
+  ApplicationCommandValidationError,
+  requireGeneratedIdentifier,
+  validateCommandInput
+} from "./mailbox-validation.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+export function capacityOf(runtime, open, admitted) {
+  const limit = runtime.policy.maxBacklog;
+  return Object.freeze({ open, limit, remaining: Math.max(0, limit - open), admitted });
+}
+export async function admitCommand(runtime, command) {
+  const input = await validateCommandInput(command, runtime.policy), identityDigest = await computeIdentityDigest([
+    input.caller,
+    input.target,
+    input.kind,
+    input.payloadDigest
+  ]);
+  for (let attempt = 1;attempt <= MAX_MAILBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    let expectedBinding = null;
+    if (input.idempotencyKey !== void 0) {
+      const resolved = await resolveIdempotency(runtime, input.idempotencyKey, identityDigest);
+      if (resolved.admission !== null)
+        return resolved.admission;
+      expectedBinding = resolved.staleBindingBytes;
+    }
+    const header = await loadMailboxHeader(runtime.storage, runtime.keys, runtime.policy.namespace, runtime.policy.resourceId);
+    if (header.record.openCount >= runtime.policy.maxBacklog)
+      return {
+        status: "rejected",
+        reason: "backlog-full",
+        capacity: capacityOf(runtime, header.record.openCount, header.record.admittedCount)
+      };
+    if (header.record.nextSequence >= Number.MAX_SAFE_INTEGER)
+      throw new ApplicationCommandValidationError("This mailbox has exhausted its FIFO sequence allocator; no further commands can be admitted under this namespace and resource id.");
+    const now = runtime.now(), record = createAdmittedCommandRecord(input, {
+      namespace: runtime.policy.namespace,
+      resourceId: runtime.policy.resourceId,
+      commandId: requireGeneratedIdentifier(runtime.generateId(), "commandId"),
+      sequence: header.record.nextSequence,
+      now
+    });
+    if (!await commitMailboxTransition(runtime.storage, runtime.events, planCommandTransition(runtime.keys, {
+      previous: null,
+      expectedBytes: null,
+      next: record,
+      event: describeCommandTransition(null, record),
+      now,
+      extraConditions: [
+        { key: runtime.keys.header, expectedValue: header.bytes },
+        ...input.idempotencyKey === void 0 ? [] : [
+          {
+            key: runtime.keys.idempotency(input.idempotencyKey),
+            expectedValue: expectedBinding
+          }
+        ]
+      ],
+      extraOperations: [
+        {
+          type: "put",
+          key: runtime.keys.bySequence(record.sequence),
+          value: encodeApplicationReadyEntry(record.commandId)
+        },
+        headerOperation(runtime.keys, {
+          ...header.record,
+          nextSequence: header.record.nextSequence + 1,
+          openCount: header.record.openCount + 1,
+          admittedCount: header.record.admittedCount + 1
+        }),
+        ...input.idempotencyKey === void 0 ? [] : [
+          {
+            type: "put",
+            key: runtime.keys.idempotency(input.idempotencyKey),
+            value: encodeApplicationCommandIdempotencyRecord({
+              recordVersion: MAILBOX_RECORD_VERSION,
+              commandId: record.commandId,
+              identityDigest
+            })
+          }
+        ]
+      ]
+    })))
+      continue;
+    return { status: "admitted", receipt: toApplicationCommandReceipt(record) };
+  }
+  throw new MailboxContentionError("admit", null);
+}
+async function resolveIdempotency(runtime, idempotencyKey, identityDigest) {
+  const binding = await loadIdempotencyBinding(runtime.storage, runtime.keys, idempotencyKey);
+  if (binding === null)
+    return { admission: null, staleBindingBytes: null };
+  const loaded = await loadCommand(runtime.storage, runtime.keys, binding.record.commandId);
+  if (loaded === null)
+    return { admission: null, staleBindingBytes: binding.bytes };
+  const ownDigest = await computeIdentityDigest([
+    loaded.record.caller,
+    loaded.record.target,
+    loaded.record.kind,
+    loaded.record.payloadDigest
+  ]);
+  if (loaded.record.idempotencyKey !== idempotencyKey || ownDigest !== binding.record.identityDigest)
+    throw new PersistedDataCorruptError(runtime.keys.idempotency(idempotencyKey));
+  const receipt = toApplicationCommandReceipt(loaded.record);
+  if (binding.record.identityDigest !== identityDigest)
+    return {
+      admission: { status: "conflict", receipt, reason: "idempotency-identity-mismatch" },
+      staleBindingBytes: null
+    };
+  return { admission: { status: "duplicate", receipt }, staleBindingBytes: null };
+}