@aldus-runtime/release 0.1.0

package/src/operation.ts

@@ -0,0 +1,112 @@
+/**
+ * Release operations (architecture contract §17).
+ *
+ * §17 requires that "pre-release hard gates and post-upload best-effort operations MUST be
+ * distinguished". The distinction is made **structurally** rather than with a severity field:
+ * a required operation and a best-effort one are different types, produced by different
+ * constructors, and held in different arrays of a {@link ReleaseBundle}.
+ *
+ * A `criticality: "required" | "best_effort"` field would have been smaller, and wrong. A field
+ * is set at a call site, often far from where the consequence lands, and setting it incorrectly
+ * turns a failed thumbnail into a failed release or — far worse — a failed media upload into a
+ * release that reports success. Requiring the caller to *place* the operation in one list or the
+ * other makes the mistake a type error rather than a typo.
+ */
+
+/**
+ * Brand distinguishing the two operation categories at the type level.
+ *
+ * Declared but never exported as a value, so an operation of either kind can only come from the
+ * constructor below. A caller cannot hand-write an object literal that satisfies
+ * {@link RequiredOperation}.
+ */
+declare const CRITICALITY: unique symbol;
+
+/** Fields shared by both categories. */
+export interface ReleaseOperationBase {
+  /**
+   * Identity of this operation within its bundle.
+   *
+   * Stable across resumption: it is how a stored receipt is matched back to the operation that
+   * produced it, so renaming one orphans its receipt.
+   */
+  operationId: string;
+  /**
+   * What kind of operation this is, e.g. a media upload, a caption attachment, or a visibility
+   * transition.
+   *
+   * An OPEN string, never a Core-defined enum. Contract §17 lists candidate operations — media
+   * upload, captions, thumbnail, title and description, privacy transition, playlist, podcast
+   * storage and RSS, notification channels — as an illustration of what an adopter might need,
+   * and §4.2 keeps adopter process out of the runtime. Do not narrow this to a union.
+   */
+  kind: string;
+  /**
+   * Where the operation is directed.
+   *
+   * An OPEN string. Contract §1.2 explicitly rules out prescribing particular release targets,
+   * so a destination is an adopter's name for one of its own, resolved to an adapter at
+   * execution time.
+   */
+  destination: string;
+  /**
+   * Digests of exactly what this operation releases (contract §13.4).
+   *
+   * §13.4 requires release approval to bind to the final render, captions, metadata,
+   * destination, and visibility policy. These digests are what an approval binds, and they feed
+   * the idempotency key, so changing what is released changes the operation's identity.
+   */
+  inputHashes: readonly string[];
+  /**
+   * The authority this operation requires, if any (contract §13.4, §18.1).
+   *
+   * Names an operation string a gate grants — for example the separate upload and publication
+   * authorities §13.4 demands. Left absent only for operations that genuinely need no approval.
+   * The gate engine decides whether the authority is held; this package never re-decides it.
+   */
+  requiresAuthority?: string;
+  /** Opaque parameters passed through to the adapter. Never inspected here. */
+  parameters?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * An operation whose failure fails the release (contract §17 "pre-release hard gates").
+ *
+ * Required operations run in declaration order, and the first failure stops the bundle: a media
+ * upload that failed must not be followed by a visibility transition making nothing public.
+ */
+export interface RequiredOperation extends ReleaseOperationBase {
+  readonly [CRITICALITY]: "required";
+}
+
+/**
+ * An operation whose failure is recorded but does not fail the release (contract §17
+ * "post-upload best-effort operations").
+ *
+ * A failed thumbnail or notification leaves a `failed` receipt and an operator-visible warning;
+ * it does not undo an upload that succeeded.
+ */
+export interface BestEffortOperation extends ReleaseOperationBase {
+  readonly [CRITICALITY]: "best_effort";
+}
+
+/** Either category, where only the shared fields matter. */
+export type ReleaseOperation = RequiredOperation | BestEffortOperation;
+
+/** Declare an operation whose failure fails the release (contract §17). */
+export function requiredOperation(operation: ReleaseOperationBase): RequiredOperation {
+  return { ...operation } as RequiredOperation;
+}
+
+/** Declare an operation whose failure is recorded but tolerated (contract §17). */
+export function bestEffortOperation(operation: ReleaseOperationBase): BestEffortOperation {
+  return { ...operation } as BestEffortOperation;
+}
+
+/**
+ * Which category an operation belongs to.
+ *
+ * Derived from where the bundle holds it rather than read off the operation, because the arrays
+ * are the source of truth — see this module's header.
+ */
+export type OperationCriticality = "required" | "best_effort";

package/src/ports.ts

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+
+import type { AldusEvent, ReleaseReceipt } from "@aldus-runtime/core";
+import type { EventStore, RunStore } from "@aldus-runtime/file-store";
+
+/**
+ * Storage for release receipts (contract §7 `release.json`).
+ *
+ * There is no update in place and no delete. §17's receipts are an audit record of what was
+ * attempted against a destination: an operation retried after a failure produces a second
+ * receipt, not an edit to the first, because the fact that the first attempt failed is what
+ * explains the retry. {@link latestFor} resolves the current outcome by reading them in order.
+ */
+export interface ReleaseReceiptStore {
+  /** Every receipt recorded for a Run, in the order they were appended. */
+  list(runId: string): Promise<ReleaseReceipt[]>;
+  /** Append one receipt. */
+  append(runId: string, receipt: ReleaseReceipt): Promise<void>;
+}
+
+/**
+ * Where lifecycle events go (contract §6.4).
+ *
+ * §6.4 requires **every** state mutation to emit an immutable event, so recording a receipt and
+ * emitting its event are one operation from the executor's point of view.
+ */
+export interface ReleaseEventSink {
+  /** Emit one event. */
+  emit(event: AldusEvent): Promise<void>;
+}
+
+/**
+ * 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: readonly ReleaseReceipt[]): Map<string, ReleaseReceipt> {
+  const latest = new Map<string, ReleaseReceipt>();
+  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 implements ReleaseReceiptStore {
+  readonly #byRun = new Map<string, ReleaseReceipt[]>();
+
+  list(runId: string): Promise<ReleaseReceipt[]> {
+    return Promise.resolve([...(this.#byRun.get(runId) ?? [])]);
+  }
+
+  append(runId: string, receipt: ReleaseReceipt): Promise<void> {
+    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: string): void {
+    this.#byRun.delete(runId);
+  }
+}
+
+/** An in-memory {@link ReleaseEventSink} that retains what it was given, for tests. */
+export class MemoryReleaseEventSink implements ReleaseEventSink {
+  readonly events: AldusEvent[] = [];
+
+  emit(event: AldusEvent): Promise<void> {
+    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: RunStore): ReleaseReceiptStore {
+  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: EventStore): ReleaseEventSink {
+  return {
+    emit: async (event) => {
+      await events.append(event.runId, event);
+    },
+  };
+}