@aldus-runtime/release 0.1.0

package/dist/ports.js

@@ -0,0 +1,80 @@
+/**
+ * Ports the release executor reads and writes through.
+ *
+ * Contract §7 requires core models to be independent of physical storage, so this package binds
+ * to interfaces rather than to a store. Each is kept to the operations actually used and tested:
+ * an aspirational method on a port is worse than an absent one, because a second adapter is
+ * written against it and only discovers at runtime that nothing honours it.
+ */
+/**
+ * The most recent receipt per idempotency key.
+ *
+ * Later receipts win, which is what makes a retry after a failure resolve to the retry's outcome
+ * rather than the original failure.
+ */
+export function latestByKey(receipts) {
+    const latest = new Map();
+    for (const receipt of receipts)
+        latest.set(receipt.idempotencyKey, receipt);
+    return latest;
+}
+/** An in-memory {@link ReleaseReceiptStore}, for tests and for dry runs. */
+export class MemoryReleaseReceiptStore {
+    #byRun = new Map();
+    list(runId) {
+        return Promise.resolve([...(this.#byRun.get(runId) ?? [])]);
+    }
+    append(runId, receipt) {
+        const existing = this.#byRun.get(runId);
+        if (existing === undefined)
+            this.#byRun.set(runId, [receipt]);
+        else
+            existing.push(receipt);
+        return Promise.resolve();
+    }
+    /**
+     * Discard every receipt for a Run, as a lost or never-written `release.json` would.
+     *
+     * Exists for the reconciliation tests: losing a receipt whose operation succeeded remotely is
+     * the exact condition §17's reconciliation requirement addresses, and it has to be reproducible
+     * to be tested.
+     */
+    forget(runId) {
+        this.#byRun.delete(runId);
+    }
+}
+/** An in-memory {@link ReleaseEventSink} that retains what it was given, for tests. */
+export class MemoryReleaseEventSink {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+        return Promise.resolve();
+    }
+}
+/**
+ * A {@link ReleaseReceiptStore} backed by `@aldus-runtime/file-store`'s per-Run `release.json` (§7).
+ *
+ * `RunStore.addRecord` takes the Run lock itself, so this must not be called from inside code
+ * that already holds it — file locks are not re-entrant and the acquisition is refused outright
+ * (ADR-0005). The executor therefore holds no Run lock while writing receipts.
+ */
+export function runStoreReceipts(runs) {
+    return {
+        list: (runId) => runs.listRecords(runId, "release"),
+        append: (runId, receipt) => runs.addRecord(runId, "release", receipt),
+    };
+}
+/**
+ * A {@link ReleaseEventSink} backed by `@aldus-runtime/file-store`'s event log (§6.4).
+ *
+ * Carries the same caution as {@link runStoreReceipts}: `EventStore.append` takes the Run lock to
+ * assign a sequence (ADR-0005).
+ */
+export function eventStoreSink(events) {
+    return {
+        emit: async (event) => {
+            await events.append(event.runId, event);
+        },
+    };
+}
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+BH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,QAAmC;IAC7D,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;IACjD,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,yBAAyB;IAC3B,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEtD,IAAI,CAAC,KAAa;QAChB,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,OAAuB;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;;YACzD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAa;QAClB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,OAAO,sBAAsB;IACxB,MAAM,GAAiB,EAAE,CAAC;IAEnC,IAAI,CAAC,KAAiB;QACpB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,OAAO;QACL,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC;QACnD,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC;KACtE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACpB,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@aldus-runtime/release",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Aldus Release \u2014 release bundles, resumable idempotent operations, adapter contracts, and external-state reconciliation.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jamchen/aldus",
+    "directory": "packages/aldus-release"
+  },
+  "homepage": "https://github.com/jamchen/aldus/tree/main/packages/aldus-release#readme",
+  "bugs": {
+    "url": "https://github.com/jamchen/aldus/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck:test": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@aldus-runtime/core": "0.1.0",
+    "@aldus-runtime/file-store": "0.1.0",
+    "@aldus-runtime/gate-engine": "0.1.0"
+  },
+  "devDependencies": {
+    "@aldus-runtime/testkit": "0.1.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,202 @@
+/**
+ * The release adapter contract (architecture contract §17, §4.3).
+ *
+ * This package contains **no platform client, and names no platform.** Contract §4.2 keeps
+ * publishing platforms out of the runtime and §1.2 explicitly rules out prescribing particular
+ * release targets; §4.3 places provider and release configuration in Integration. Contract §22's
+ * own wording for this work package names two platforms, and following that wording literally
+ * would have put an adopter's channel semantics inside the runtime — the dependency direction
+ * §4.3 forbids.
+ *
+ * So what lives here is the shape an adopter implements, plus the resumable machinery that shape
+ * plugs into. The only implementation in this package is {@link RecordingReleaseAdapter}, a test
+ * double.
+ */
+
+import type { ReleaseOperation } from "./operation.js";
+import { ReleaseErrorCodes, releaseError } from "./errors.js";
+
+/** What an adapter is asked to do. */
+export interface ReleaseRequest {
+  /** The operation being performed. */
+  operation: ReleaseOperation;
+  /**
+   * The key that makes this request safe to repeat (contract §17, §19.1).
+   *
+   * An adapter whose platform supports client-supplied idempotency keys SHOULD pass this
+   * through, so that a repeat caused by a lost response is deduplicated remotely as well as
+   * locally.
+   */
+  idempotencyKey: string;
+  /** Run the release belongs to. */
+  runId: string;
+}
+
+/** What an adapter reports back. */
+export type AdapterOutcome =
+  | {
+      status: "succeeded";
+      /** Identifier assigned by the destination, where one is returned. */
+      remoteId?: string;
+      /** Address of the released item, where one is meaningful. */
+      remoteUrl?: string;
+    }
+  | {
+      status: "failed";
+      /** Operator-facing reason, already redacted by the adapter (contract §19.2). */
+      message: string;
+      /** Whether repeating the identical request could plausibly succeed (contract §19.1). */
+      retryable?: boolean;
+    }
+  | {
+      /**
+       * The outcome is genuinely unknown — a timeout, a lost connection after the request was
+       * accepted, a platform that acknowledges asynchronously.
+       *
+       * Distinct from `failed` and the reason `ReleaseReceipt` has a `pending` status: an
+       * unknown outcome MUST be reconciled against the destination rather than retried, because
+       * retrying something that already succeeded is how a double publish happens.
+       */
+      status: "pending";
+      message?: string;
+    };
+
+/** What reconciliation found at the destination. */
+export interface RemoteState {
+  /** Whether the destination holds the result of this operation. */
+  exists: boolean;
+  remoteId?: string;
+  remoteUrl?: string;
+}
+
+/**
+ * An adopter's implementation for one destination.
+ *
+ * Implementations live in an adopter integration, never here (§4.3).
+ */
+export interface ReleaseAdapter {
+  /** The destination this adapter serves, matching `ReleaseOperation.destination`. */
+  readonly destination: string;
+  /** Perform one operation. */
+  execute(request: ReleaseRequest): Promise<AdapterOutcome>;
+  /**
+   * Ask the destination whether an operation already happened (contract §17).
+   *
+   * Optional because §17 qualifies resumability with "where the platform allows it" — a
+   * destination with no way to query prior state genuinely cannot support this. An adapter that
+   * omits it makes reconciliation impossible for its operations, and the executor reports that
+   * rather than guessing; see {@link ReleaseErrorCodes.RECONCILIATION_UNAVAILABLE}.
+   */
+  lookup?(request: ReleaseRequest): Promise<RemoteState>;
+}
+
+/** Adapters by destination. */
+export class AdapterRegistry {
+  readonly #byDestination = new Map<string, ReleaseAdapter>();
+
+  constructor(adapters: readonly ReleaseAdapter[] = []) {
+    for (const adapter of adapters) this.register(adapter);
+  }
+
+  /** Register an adapter, replacing any previous one for its destination. */
+  register(adapter: ReleaseAdapter): void {
+    this.#byDestination.set(adapter.destination, adapter);
+  }
+
+  /** The adapter for a destination, or `undefined`. */
+  find(destination: string): ReleaseAdapter | undefined {
+    return this.#byDestination.get(destination);
+  }
+
+  /**
+   * The adapter for a destination.
+   *
+   * @throws {AldusError} `ALDUS_RELEASE_ADAPTER_NOT_REGISTERED` when none is registered. Refusing
+   * is deliberate: a missing adapter means an operator declared work nothing can perform, and
+   * skipping it would report a complete release that never touched the destination.
+   */
+  require(destination: string): ReleaseAdapter {
+    const adapter = this.#byDestination.get(destination);
+    if (adapter === undefined) {
+      throw releaseError(
+        ReleaseErrorCodes.ADAPTER_NOT_REGISTERED,
+        `No release adapter is registered for destination "${destination}".`,
+        { category: "validation", retryable: false, details: { destination } },
+      );
+    }
+    return adapter;
+  }
+}
+
+/** Scripted behaviour for {@link RecordingReleaseAdapter}. */
+export interface RecordingAdapterOptions {
+  /** Outcome per `operationId`. Anything unlisted succeeds. */
+  outcomes?: Readonly<Record<string, AdapterOutcome>>;
+  /** Remote state per idempotency key, as reconciliation would find it. */
+  remote?: Readonly<Record<string, RemoteState>>;
+  /** Omit `lookup` entirely, modelling a destination that cannot be queried. */
+  withoutLookup?: boolean;
+}
+
+/**
+ * A test double that records what it was asked to do.
+ *
+ * Counting executions is the point: the double-publish tests assert that a *real* second
+ * execution never happened, which a spy on the executor could not establish.
+ */
+export class RecordingReleaseAdapter implements ReleaseAdapter {
+  readonly destination: string;
+  /** Every request passed to {@link execute}, in order. */
+  readonly executed: ReleaseRequest[] = [];
+  /** Every request passed to {@link lookup}, in order. */
+  readonly lookedUp: ReleaseRequest[] = [];
+  readonly #options: RecordingAdapterOptions;
+  /** Remote state, mutable so a test can simulate a destination that already holds a result. */
+  readonly remote: Map<string, RemoteState>;
+
+  /**
+   * Present only when the destination can be queried.
+   *
+   * An own property assigned in the constructor rather than a prototype method, because
+   * `withoutLookup` has to make `lookup` genuinely **absent**. A method that returns "not found"
+   * would be indistinguishable from a destination that was queried and had nothing — and those
+   * are opposite situations: one means the operation still needs to run, the other means nobody
+   * can say. Deleting a prototype method does not remove it from the instance, which is the bug
+   * this shape avoids.
+   */
+  readonly lookup?: (request: ReleaseRequest) => Promise<RemoteState>;
+
+  constructor(destination: string, options: RecordingAdapterOptions = {}) {
+    this.destination = destination;
+    this.#options = options;
+    this.remote = new Map(Object.entries(options.remote ?? {}));
+    if (options.withoutLookup !== true) {
+      this.lookup = (request: ReleaseRequest): Promise<RemoteState> => {
+        this.lookedUp.push(request);
+        return Promise.resolve(this.remote.get(request.idempotencyKey) ?? { exists: false });
+      };
+    }
+  }
+
+  execute(request: ReleaseRequest): Promise<AdapterOutcome> {
+    this.executed.push(request);
+    const scripted = this.#options.outcomes?.[request.operation.operationId];
+    const outcome: AdapterOutcome = scripted ?? {
+      status: "succeeded",
+      remoteId: `remote-${request.operation.operationId}`,
+    };
+    if (outcome.status === "succeeded") {
+      this.remote.set(request.idempotencyKey, {
+        exists: true,
+        ...(outcome.remoteId === undefined ? {} : { remoteId: outcome.remoteId }),
+        ...(outcome.remoteUrl === undefined ? {} : { remoteUrl: outcome.remoteUrl }),
+      });
+    }
+    return Promise.resolve(outcome);
+  }
+
+  /** How many times an operation was actually sent to the destination. */
+  executionCount(operationId: string): number {
+    return this.executed.filter((request) => request.operation.operationId === operationId).length;
+  }
+}

package/src/authorization.ts

@@ -0,0 +1,74 @@
+/**
+ * Release authorization (architecture contract §13.4, §17, §18.1).
+ *
+ * This package does **not** decide whether a release is approved. `@aldus-runtime/gate-engine` already
+ * models §13.4's separation of uploading from making public as two gates granting two
+ * operations, and derives staleness from bound digests (ADR-0009). Re-deciding any of that here
+ * would produce a second approval path — and §3.6 exists because a second path is how an
+ * approval that nobody recorded ends up authorizing something.
+ *
+ * So the executor consumes a verdict through a narrow port, and {@link gateEngineAuthorizer}
+ * wires that port to the real engine.
+ */
+
+import type { GateEngine, SubjectsByGate } from "@aldus-runtime/gate-engine";
+
+/** A verdict on one operation's authority. */
+export interface AuthorityVerdict {
+  authorized: boolean;
+  /** Why not, when refused. Shown to an operator, so it must name the gate. */
+  explanation?: string;
+  /** The gate that granted it, when authorized — recorded for trace (contract §20). */
+  gateId?: string;
+}
+
+/**
+ * Whatever decides if a release operation may proceed.
+ *
+ * A port rather than a direct dependency so that the executor can be tested against a refusal
+ * without constructing a gate graph, and so an adopter with its own authority model can supply
+ * one. The shipped implementation is {@link gateEngineAuthorizer}.
+ */
+export interface ReleaseAuthorizer {
+  /**
+   * Whether `authority` is currently held for this Run.
+   *
+   * `authority` is the operation string a gate grants, e.g. the separate upload and publication
+   * authorities of §13.4.
+   */
+  check(runId: string, authority: string): Promise<AuthorityVerdict>;
+}
+
+/**
+ * A {@link ReleaseAuthorizer} backed by the gate engine (contract §13).
+ *
+ * `subjects` are the current digests of everything the gates bind — the final render, captions,
+ * metadata, destination, and visibility policy of §13.4. They are supplied by the caller and
+ * read afresh on every check, so an approval that was valid when the bundle was assembled and
+ * has since drifted is refused at the moment of release rather than at the moment of planning.
+ */
+export function gateEngineAuthorizer(
+  engine: GateEngine,
+  subjects: SubjectsByGate | (() => SubjectsByGate | Promise<SubjectsByGate>),
+): ReleaseAuthorizer {
+  return {
+    async check(runId: string, authority: string): Promise<AuthorityVerdict> {
+      const current = typeof subjects === "function" ? await subjects() : subjects;
+      const result = await engine.authorize(runId, authority, current);
+      return result.authorized
+        ? { authorized: true, gateId: result.gateId }
+        : { authorized: false, explanation: result.explanation };
+    },
+  };
+}
+
+/**
+ * An authorizer that permits everything.
+ *
+ * For operations that genuinely need no approval, and for tests exercising execution mechanics
+ * rather than authority. Deliberately named for what it does: a default called
+ * `defaultAuthorizer` would be reached for without the reader noticing it approves everything.
+ */
+export function permitAllAuthorizer(): ReleaseAuthorizer {
+  return { check: () => Promise.resolve({ authorized: true }) };
+}

package/src/bundle.ts

@@ -0,0 +1,101 @@
+/**
+ * Release bundles (architecture contract §17).
+ *
+ * A bundle is a **declaration**, not a record of what happened: contract §17 states that
+ * "publishing is a domain, not a single command", and the bundle is the domain's unit of intent.
+ * What happened lives in `ReleaseReceipt`s, one per operation, in the Run's `release.json`
+ * (§7).
+ *
+ * There is deliberately no persisted bundle state. Execution state is derived from the receipts
+ * on every inspection, for the same reason ADR-0009 derives gate state rather than storing it: a
+ * stored "in progress" flag survives a crash that the operation it describes did not, and an
+ * operator then reads a status that was true once and is not true now.
+ */
+
+import { createHash } from "node:crypto";
+
+import { ReleaseErrorCodes, releaseError } from "./errors.js";
+import type { BestEffortOperation, ReleaseOperation, RequiredOperation } from "./operation.js";
+
+/**
+ * A set of release operations for one Run.
+ *
+ * The two lists are the §17 distinction between pre-release hard gates and post-upload
+ * best-effort work. Required operations run first, in order; best-effort operations run only
+ * once every required one has succeeded, because §17 calls them "post-upload".
+ */
+export interface ReleaseBundle {
+  /** Identity of this bundle. Part of every operation's idempotency key. */
+  bundleId: string;
+  /** Run this release belongs to (contract §6). */
+  runId: string;
+  /** Canonical Episode identity, for the emitted events (contract §6.4). */
+  episodeId: string;
+  /** Operations whose failure fails the release, in execution order. */
+  required: readonly RequiredOperation[];
+  /** Operations attempted after the required ones, whose failure is recorded but tolerated. */
+  bestEffort: readonly BestEffortOperation[];
+}
+
+/** Every operation in a bundle, required first, in execution order. */
+export function operationsOf(bundle: ReleaseBundle): readonly ReleaseOperation[] {
+  return [...bundle.required, ...bundle.bestEffort];
+}
+
+/**
+ * Check a bundle's internal consistency.
+ *
+ * @throws {AldusError} `ALDUS_RELEASE_EMPTY_BUNDLE` if it declares no operations.
+ * @throws {AldusError} `ALDUS_RELEASE_DUPLICATE_OPERATION` if an `operationId` repeats.
+ */
+export function assertBundleValid(bundle: ReleaseBundle): void {
+  const operations = operationsOf(bundle);
+  if (operations.length === 0) {
+    throw releaseError(
+      ReleaseErrorCodes.EMPTY_BUNDLE,
+      `Release bundle "${bundle.bundleId}" declares no operations, so executing it would report ` +
+        "a successful release that published nothing.",
+      { category: "validation", details: { bundleId: bundle.bundleId } },
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const operation of operations) {
+    if (seen.has(operation.operationId)) {
+      throw releaseError(
+        ReleaseErrorCodes.DUPLICATE_OPERATION,
+        `Release bundle "${bundle.bundleId}" declares "${operation.operationId}" twice. ` +
+          "Operation ids match receipts back to operations, so a duplicate would let one " +
+          "operation inherit the other's outcome.",
+        {
+          category: "validation",
+          details: { bundleId: bundle.bundleId, operationId: operation.operationId },
+        },
+      );
+    }
+    seen.add(operation.operationId);
+  }
+}
+
+/**
+ * Derive the idempotency key for one operation (contract §17, §19.1).
+ *
+ * §17 requires each operation to be "independently idempotent and resumable where the platform
+ * allows it", and `ReleaseReceipt.idempotencyKey` is the mechanism. The key is **derived, not
+ * supplied**, from the bundle, the operation, its destination, and the digests of what it
+ * releases — so a resumed execution computes the identical key without having to remember one,
+ * and a changed input produces a different key rather than silently reusing an old outcome.
+ *
+ * Input hashes are sorted before digesting: the set of things released is what matters, not the
+ * order a caller happened to list them in.
+ */
+export function deriveIdempotencyKey(bundleId: string, operation: ReleaseOperation): string {
+  const material = JSON.stringify({
+    bundleId,
+    operationId: operation.operationId,
+    kind: operation.kind,
+    destination: operation.destination,
+    inputHashes: [...operation.inputHashes].sort(),
+  });
+  return createHash("sha256").update(material, "utf8").digest("hex");
+}

package/src/errors.ts

@@ -0,0 +1,65 @@
+/**
+ * Failures specific to release execution.
+ *
+ * Aldus Core deliberately keeps no central error-code registry, so that a package can name a new
+ * failure without forking Core. These codes are this package's contribution; they carry the same
+ * `ALDUS_` prefix and `SCREAMING_SNAKE_CASE` shape so production trace (contract §20) stays
+ * uniform across packages.
+ */
+
+import { AldusError, type ErrorCategory } from "@aldus-runtime/core";
+
+/** Error codes raised by the release executor. */
+export const ReleaseErrorCodes = {
+  /**
+   * An operation was attempted that no gate authorizes.
+   *
+   * Contract §13.4 binds release approval to the final render, captions, metadata, destination,
+   * and visibility policy, and §17 requires uploading and making public to be separate
+   * operations. An unauthorized release is refused rather than warned about: a warning that
+   * still publishes is not a gate.
+   */
+  RELEASE_NOT_AUTHORIZED: "ALDUS_RELEASE_NOT_AUTHORIZED",
+  /** No adapter is registered for an operation's destination. */
+  ADAPTER_NOT_REGISTERED: "ALDUS_RELEASE_ADAPTER_NOT_REGISTERED",
+  /** A bundle declared two operations with the same `operationId`. */
+  DUPLICATE_OPERATION: "ALDUS_RELEASE_DUPLICATE_OPERATION",
+  /** A bundle was constructed with no operations at all. */
+  EMPTY_BUNDLE: "ALDUS_RELEASE_EMPTY_BUNDLE",
+  /**
+   * A required operation failed, so the release did not complete.
+   *
+   * Distinct from a best-effort failure, which is recorded and does not fail the release
+   * (contract §17: "Pre-release hard gates and post-upload best-effort operations MUST be
+   * distinguished").
+   */
+  REQUIRED_OPERATION_FAILED: "ALDUS_RELEASE_REQUIRED_OPERATION_FAILED",
+  /**
+   * A stored receipt disagrees with the bundle that produced it.
+   *
+   * The identity of an operation is its `operationId` plus its idempotency key. A receipt whose
+   * key no longer matches describes a different operation than the one about to run, and reusing
+   * it would let changed inputs inherit an old approval's outcome.
+   */
+  RECEIPT_MISMATCH: "ALDUS_RELEASE_RECEIPT_MISMATCH",
+  /**
+   * Reconciliation was required but the adapter cannot look up remote state.
+   *
+   * Contract §17 requires operations to be resumable "where the platform allows it". Where it
+   * does not, the honest outcome is to say so rather than to re-execute and risk a duplicate
+   * publish.
+   */
+  RECONCILIATION_UNAVAILABLE: "ALDUS_RELEASE_RECONCILIATION_UNAVAILABLE",
+} as const;
+
+/** @see ReleaseErrorCodes */
+export type ReleaseErrorCode = (typeof ReleaseErrorCodes)[keyof typeof ReleaseErrorCodes];
+
+/** Construct an {@link AldusError} with a release code. */
+export function releaseError(
+  code: ReleaseErrorCode,
+  message: string,
+  options: { category: ErrorCategory; retryable?: boolean; details?: Record<string, unknown> },
+): AldusError {
+  return new AldusError(code, message, options);
+}