@aldus-runtime/release 0.2.0-next.4 → 0.2.0-next.40

package/src/adapter.ts

@@ -40,6 +40,21 @@ export type AdapterOutcome =
       remoteId?: string;
       /** Address of the released item, where one is meaningful. */
       remoteUrl?: string;
+      /**
+       * Something an operator needs to know about a success (§20; #169 item 4).
+       *
+       * `failed` has `message` and `pending` has `message?`; `succeeded` had nowhere to put a
+       * sentence at all. An adapter that removed a marker from one video of several, or that found
+       * no marker and therefore removed nothing, succeeded — and had to discard the only part an
+       * operator would have wanted.
+       *
+       * **Not a channel for a qualified absence.** An adapter that cannot establish remote state
+       * returns {@link cannotEstablish} from `lookup`; using this to footnote a fabricated
+       * `exists: false` would be the same false record with better documentation (#169 item 3).
+       *
+       * Already redacted by the adapter (§19.2), like every other adapter-supplied string.
+       */
+      note?: string;
     }
   | {
       status: "failed";
@@ -61,14 +76,83 @@ export type AdapterOutcome =
       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;
+/** @see CannotEstablish */
+declare const CANNOT_ESTABLISH: unique symbol;
+
+/**
+ * Authorities this process minted. A cast cannot manufacture membership.
+ *
+ * The same runtime proof `SynthesisPermit` uses, and for the same reason: the brand above is a
+ * phantom, absent at runtime, so a `RemoteState` narrowing that trusted it would trust a type
+ * assertion. #170 has the longer version of this argument — a check that assumes the type it is
+ * checking is not a check.
+ */
+const ISSUED_CANNOT_ESTABLISH = new WeakSet<object>();
+
+/**
+ * The destination could not be queried, so whether it holds the operation is unknown (#169).
+ *
+ * Distinct from `exists: false` in the way that matters: **`exists: false` is the answer only a
+ * completed search can give.** Before this, an adapter that could not establish the answer had two
+ * options — return `false` and assert a search nobody performed, or throw and abort the whole
+ * reconciliation pass before a single operation executed. Both were forced, and adopters took the
+ * first.
+ *
+ * Minted by {@link cannotEstablish} and not assemblable, because a state that suppresses a
+ * publish-safety check must not be reachable by writing an object literal.
+ */
+export interface CannotEstablish {
+  readonly [CANNOT_ESTABLISH]: "cannot_establish";
+  /**
+   * Why the answer could not be established, for the operator (§20).
+   *
+   * **Required.** An adapter that cannot establish something and cannot say why has produced a
+   * finding nobody can act on — a rate limit, a permission, and a destination that does not retain
+   * what would identify the operation are three different problems with three different responses.
+   */
+  readonly reason: string;
 }
 
+/**
+ * Declare that the destination could not be queried (§17, §19.1; #169).
+ *
+ * @throws {AldusError} when the reason is empty.
+ */
+export function cannotEstablish(reason: string): CannotEstablish {
+  if (typeof reason !== "string" || reason.trim().length === 0) {
+    throw releaseError(
+      ReleaseErrorCodes.OPERATION_INVALID,
+      "An unestablished remote state must say why. A rate limit, a permission problem and a " +
+        "destination that does not retain what identifies the operation call for three different " +
+        "responses, and an operator cannot tell them apart from the absence of an answer (§17).",
+      { category: "validation", retryable: false, details: {} },
+    );
+  }
+  const state = { reason } as CannotEstablish;
+  ISSUED_CANNOT_ESTABLISH.add(state);
+  return state;
+}
+
+/** Whether a remote state is an issued {@link CannotEstablish}. Membership, not shape. */
+export function isCannotEstablish(state: RemoteState): state is CannotEstablish {
+  return typeof state === "object" && state !== null && ISSUED_CANNOT_ESTABLISH.has(state);
+}
+
+/** What reconciliation found at the destination. */
+export type RemoteState =
+  | {
+      /**
+       * Whether the destination holds the result of this operation.
+       *
+       * `false` asserts a **completed search**. An adapter that did not or could not search
+       * returns {@link cannotEstablish} instead.
+       */
+      exists: boolean;
+      remoteId?: string;
+      remoteUrl?: string;
+    }
+  | CannotEstablish;
+
 /**
  * An adopter's implementation for one destination.
  *
@@ -129,13 +213,52 @@ export class AdapterRegistry {
 }
 
 /** Scripted behaviour for {@link RecordingReleaseAdapter}. */
+/**
+ * Build the remote-state map from either accepted shape, and refuse anything else.
+ *
+ * Refusing rather than tolerating, because the failure this replaces was silence: a mis-seeded
+ * harness answered every lookup as a completed search finding nothing, and a test written against
+ * it would assert the wrong behaviour and pass. A double that lies quietly is worse than one that
+ * will not start.
+ */
+function seedRemote(remote: RecordingAdapterOptions["remote"]): Map<string, RemoteState> {
+  if (remote === undefined) return new Map();
+  if (remote instanceof Map) return new Map(remote);
+  if (typeof remote === "object" && remote !== null && !Array.isArray(remote)) {
+    return new Map(Object.entries(remote));
+  }
+  throw releaseError(
+    ReleaseErrorCodes.OPERATION_INVALID,
+    "A recording adapter's `remote` seed must be a plain object or a Map keyed by idempotency " +
+      "key. Anything else seeds nothing, and every lookup then answers as a completed search " +
+      "that found nothing — which is the defect this double is used to test for.",
+    { category: "validation", retryable: false, details: {} },
+  );
+}
+
 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>>;
+  /**
+   * Remote state per idempotency key, as reconciliation would find it.
+   *
+   * A plain object or a `Map`, because the field it becomes is a `Map` and seeding it with one is
+   * the natural mistake. `Object.entries(aMap)` is `[]`, so a `Map` used to seed **nothing**, with
+   * no error — and every lookup then fell through to `{ exists: false }`, which reads as a
+   * completed search finding nothing. The same trap as an adapter returning `{ present: false }`:
+   * an input accepted quietly and answered as though nothing was there.
+   */
+  remote?: Readonly<Record<string, RemoteState>> | ReadonlyMap<string, RemoteState>;
   /** Omit `lookup` entirely, modelling a destination that cannot be queried. */
   withoutLookup?: boolean;
+  /**
+   * Make `lookup` throw for these `operationId`s, modelling an unanticipated query failure.
+   *
+   * Distinct from returning {@link cannotEstablish}: an adapter that knows it cannot answer says
+   * so, and this is the adapter that does not know — a quota error, a dropped connection. The
+   * executor has to survive both (#169).
+   */
+  lookupThrowsFor?: readonly string[];
 }
 
 /**
@@ -169,10 +292,13 @@ export class RecordingReleaseAdapter implements ReleaseAdapter {
   constructor(destination: string, options: RecordingAdapterOptions = {}) {
     this.destination = destination;
     this.#options = options;
-    this.remote = new Map(Object.entries(options.remote ?? {}));
+    this.remote = seedRemote(options.remote);
     if (options.withoutLookup !== true) {
       this.lookup = (request: ReleaseRequest): Promise<RemoteState> => {
         this.lookedUp.push(request);
+        if (options.lookupThrowsFor?.includes(request.operation.operationId) === true) {
+          return Promise.reject(new Error("destination query failed"));
+        }
         return Promise.resolve(this.remote.get(request.idempotencyKey) ?? { exists: false });
       };
     }

package/src/bundle.ts

@@ -74,6 +74,44 @@ export function assertBundleValid(bundle: ReleaseBundle): void {
       );
     }
     seen.add(operation.operationId);
+
+    // Checked at runtime, because the type is not the enforcement. `repeatable()` refuses an empty
+    // reason and nothing stops a caller writing `{ reason: "" } as RepeatableDeclaration` — and
+    // the code that will assemble operations from configuration is exactly the code that does
+    // that. Without this the operation was treated as repeatable and the warning ended in a bare
+    // colon where the justification should be.
+    //
+    // Higher stakes than the usual version of this argument: the declaration licenses performing
+    // an external effect more than once, and §13.4 binds a release approval to the bundle, so a
+    // blank reason is an approval of nothing.
+    //
+    // The **shape** as well as the emptiness. The first version read `repeatable.reason.trim()`,
+    // which assumes `reason` is a string — the assumption this check exists because it cannot
+    // make. `repeatable: true` is the single most likely thing someone writes in a config file
+    // when they mean this, and it threw a bare `TypeError` with no code, no bundle or operation
+    // id, and no sentence saying what was wrong. Fail-closed, so nothing unsafe happened; what was
+    // lost was the refusal, arriving from exactly the source the paragraph above names.
+    const declaration: unknown = (operation as { repeatable?: unknown }).repeatable;
+    if (declaration !== undefined) {
+      const reason =
+        typeof declaration === "object" && declaration !== null
+          ? (declaration as { reason?: unknown }).reason
+          : undefined;
+      if (typeof reason !== "string" || reason.trim().length === 0) {
+        throw releaseError(
+          ReleaseErrorCodes.OPERATION_INVALID,
+          `Release bundle "${bundle.bundleId}" declares "${operation.operationId}" safe to ` +
+            "repeat without a usable reason. Repeating an external effect is something an " +
+            "approver accepts, and neither a blank justification nor a value that is not a " +
+            "declaration is something anyone can approve. Build it with `repeatable(reason)` " +
+            "(contract §13.4, §17).",
+          {
+            category: "validation",
+            details: { bundleId: bundle.bundleId, operationId: operation.operationId },
+          },
+        );
+      }
+    }
   }
 }
 
@@ -88,10 +126,20 @@ export function assertBundleValid(bundle: ReleaseBundle): void {
  *
  * Input hashes are sorted before digesting: the set of things released is what matters, not the
  * order a caller happened to list them in.
+ *
+ * **The bundle's identity is deliberately not part of the key** (ADR-0033). It was, and that
+ * defeated the sentence above: nothing stores a `ReleaseBundle`, so a caller resuming after a
+ * crash reassembles one — and a reassembled bundle with a fresh `bundleId` produced a fresh key
+ * for every operation, matched no receipt, and re-executed the lot. Measured before the change:
+ * an equivalent bundle under a new id re-ran all three operations, including the media upload and
+ * the visibility transition (#40).
+ *
+ * What identifies an operation is what it does: this kind of operation, against this destination,
+ * over these exact bytes. Two bundles agreeing on all three are asking for the same external
+ * effect, and §19.1 requires that effect to happen once.
  */
-export function deriveIdempotencyKey(bundleId: string, operation: ReleaseOperation): string {
+export function deriveIdempotencyKey(operation: ReleaseOperation): string {
   const material = JSON.stringify({
-    bundleId,
     operationId: operation.operationId,
     kind: operation.kind,
     destination: operation.destination,

package/src/errors.ts

@@ -26,6 +26,13 @@ export const ReleaseErrorCodes = {
   DUPLICATE_OPERATION: "ALDUS_RELEASE_DUPLICATE_OPERATION",
   /** A bundle was constructed with no operations at all. */
   EMPTY_BUNDLE: "ALDUS_RELEASE_EMPTY_BUNDLE",
+  /**
+   * An operation declaration is not usable as written (#169).
+   *
+   * Today: a repeatable declaration with no reason. It licenses performing an external effect more
+   * than once, and an approver cannot accept that from a bare flag (§13.4, §17).
+   */
+  OPERATION_INVALID: "ALDUS_RELEASE_OPERATION_INVALID",
   /**
    * A required operation failed, so the release did not complete.
    *

package/src/executor.ts

@@ -26,7 +26,8 @@
 import type { ActorRef, AldusEvent, ReleaseReceipt } from "@aldus-runtime/core";
 import { SCHEMA_VERSION, newEventId, newReleaseId } from "@aldus-runtime/core";
 
-import type { AdapterRegistry, AdapterOutcome, ReleaseRequest } from "./adapter.js";
+import { cannotEstablish, isCannotEstablish } from "./adapter.js";
+import type { AdapterRegistry, AdapterOutcome, ReleaseRequest, RemoteState } from "./adapter.js";
 import { assertBundleValid, deriveIdempotencyKey, type ReleaseBundle } from "./bundle.js";
 import { ReleaseErrorCodes, releaseError } from "./errors.js";
 import type { OperationCriticality, ReleaseOperation } from "./operation.js";
@@ -78,6 +79,37 @@ export interface BundleStatus {
 }
 
 /** What reconciliation did about one operation. */
+/**
+ * Which reconciliation findings an operator is warned about (§20; #169).
+ *
+ * An **allow-list**, keyed on the action. It was a deny-list — any finding carrying an explanation
+ * except `confirmed_absent` — so every action added later was opted in by default, with nobody
+ * deciding. `not_reconciled_repeatable` was opted in exactly that way, and appeared in the
+ * warnings of every ordinary release of a bundle holding a repeatable operation, reporting that
+ * the expected thing had happened.
+ *
+ * Membership answers the question a warning asks: **did something go differently than intended?**
+ *
+ * - `repaired` — yes. The local record was wrong and had to be corrected.
+ * - `unavailable` — yes. Reconciliation could not run, so an operator is being told that a
+ *   protection they may assume is absent.
+ * - `confirmed_absent` — no. The ordinary path; most operations in a fresh bundle are absent, and
+ *   one line each would bury the two above.
+ * - `not_reconciled_repeatable` — no. The declared, approved state of the bundle. The reason is in
+ *   the reconciliation report for anyone reading it.
+ *
+ * Adding an action now requires either adding it here or leaving it out, and both are decisions.
+ * Neither happens by default.
+ */
+const OPERATOR_FACING_FINDINGS: ReadonlySet<ReconciliationFinding["action"]> = new Set([
+  "repaired",
+  "unavailable",
+  // Yes. The operation may or may not have happened and nobody can tell — the state an operator
+  // most needs to see, and the one the deny-list would have surfaced by accident rather than by
+  // decision (#169).
+  "cannot_establish",
+]);
+
 export interface ReconciliationFinding {
   operationId: string;
   idempotencyKey: string;
@@ -89,7 +121,21 @@ export interface ReconciliationFinding {
     /** The destination does not hold it, so the operation genuinely still needs to run. */
     | "confirmed_absent"
     /** The adapter cannot query the destination (contract §17 "where the platform allows it"). */
-    | "unavailable";
+    | "unavailable"
+    /**
+     * The operation declares its effect safe to repeat, so it was not queried (#169).
+     *
+     * Deliberately its own action rather than folded into `confirmed_absent`. Nothing was
+     * searched for, and saying it was absent would be the false statement this exists to stop.
+     */
+    | "not_reconciled_repeatable"
+    /**
+     * The adapter was asked and could not establish whether the operation happened (#169).
+     *
+     * Distinct from `unavailable`, which is a destination that cannot be queried at all, and from
+     * `confirmed_absent`, which is a completed search. This one asked and got no answer.
+     */
+    | "cannot_establish";
   explanation?: string;
 }
 
@@ -218,7 +264,7 @@ export class ReleaseExecutor {
     const findings: ReconciliationFinding[] = [];
     const repaired: ReleaseReceipt[] = [];
 
-    for (const { operation, idempotencyKey } of this.#plan(bundle)) {
+    for (const { operation, criticality, idempotencyKey } of this.#plan(bundle)) {
       const receipt = latest.get(idempotencyKey);
       if (receipt !== undefined && receipt.status !== "pending") {
         findings.push({
@@ -229,6 +275,23 @@ export class ReleaseExecutor {
         continue;
       }
 
+      // Asked of nothing, because the answer would change nothing. A repeatable operation may be
+      // performed again whatever the destination holds, so querying it buys no decision — and
+      // where reconciliation runs before execution, as it does inside `execute`, a "not there"
+      // reading can mean "the operation before it has not run yet" rather than "it did not
+      // happen". An adapter forced to answer that question has to invent one (#169).
+      if (operation.repeatable !== undefined) {
+        findings.push({
+          operationId: operation.operationId,
+          idempotencyKey,
+          action: "not_reconciled_repeatable",
+          explanation:
+            `"${operation.operationId}" declares its effect safe to repeat, so the destination ` +
+            `was not queried: ${operation.repeatable.reason}`,
+        });
+        continue;
+      }
+
       const adapter = this.#adapters.require(operation.destination);
       if (adapter.lookup === undefined) {
         findings.push({
@@ -247,8 +310,106 @@ export class ReleaseExecutor {
         idempotencyKey,
         runId: bundle.runId,
       };
-      const remote = await adapter.lookup(request);
+      // Guarded, and the guard is criticality-aware. `reconcile` used to `await` this bare, so a
+      // throw from any operation's `lookup` aborted the whole pass before a single `execute` —
+      // a quota error raised while asking about a tidy-up blocked the upload beside it (#169).
+      //
+      // A required operation's throw still aborts. Fail-closed belongs where a mistake publishes
+      // twice; it does not belong where a best-effort tidy-up could not be queried.
+      let remote: RemoteState;
+      try {
+        remote = await adapter.lookup(request);
+      } catch (thrown) {
+        if (criticality === "required") throw thrown;
+        remote = cannotEstablish(
+          `querying destination "${operation.destination}" failed: ${
+            thrown instanceof Error ? thrown.message : String(thrown)
+          }`,
+        );
+      }
+
+      if (isCannotEstablish(remote)) {
+        // Asked, and no answer. What happens next depends on what the operation is for.
+        if (criticality === "required") {
+          // Unknown must never license a publish. A required operation whose prior outcome cannot
+          // be established is refused before anything executes, because performing it might
+          // repeat it and skipping it might drop it, and neither is a choice to make blind.
+          throw releaseError(
+            ReleaseErrorCodes.RECONCILIATION_UNAVAILABLE,
+            `Whether required operation "${operation.operationId}" already happened could not be ` +
+              `established: ${remote.reason}. Executing would risk performing it twice and ` +
+              "skipping it would risk dropping it, so the bundle is refused until the outcome is " +
+              "known (contract §17).",
+            {
+              category: "conflict",
+              retryable: false,
+              details: {
+                runId: bundle.runId,
+                operationId: operation.operationId,
+                destination: operation.destination,
+              },
+            },
+          );
+        }
+
+        // Best-effort: **no receipt**, and not performed this pass.
+        //
+        // Writing a `skipped` receipt was the obvious thing and it was wrong in the way this whole
+        // issue is about. `skipped` is terminal in both directions — `execute` skips it and
+        // `reconcile` treats it as already recorded — so one momentary query failure permanently
+        // retired the operation for that bundle. At the destination that produced #169 quota
+        // exhaustion is routine, so a rate limit while *asking about* a tidy-up would silently
+        // drop it forever, and the record would say `skipped`: a decision, when what happened was
+        // an unanswered question.
+        //
+        // A durable record of a transient failure is the same defect as a durable record of a
+        // search nobody performed. So the not-performing lives in this pass only — the finding and
+        // the warning say what happened now, and the next pass asks again.
+        //
+        // Not performed either, because executing on an unknown prior state is the other half of
+        // the trap: it might repeat an operation that already happened.
+        findings.push({
+          operationId: operation.operationId,
+          idempotencyKey,
+          action: "cannot_establish",
+          explanation:
+            `Whether "${operation.operationId}" already happened could not be established, so it ` +
+            `was not attempted: ${remote.reason}`,
+        });
+        continue;
+      }
+
+      // Not an issued cannot-establish, so it must be the other arm — and that has to be checked
+      // rather than assumed. An assembled `{ reason: "..." }` is not an issued state, so
+      // `isCannotEstablish` correctly rejects it, and it would then reach `!remote.exists` with
+      // `exists` undefined and be recorded as `confirmed_absent`: a completed search, asserted
+      // from a value that is not a `RemoteState` at all.
+      //
+      // Fifth instance of the same lesson in this contract (#170 has the other four). A narrowing
+      // that trusts the declared type is not a narrowing.
+      if (typeof remote.exists !== "boolean") {
+        throw releaseError(
+          ReleaseErrorCodes.OPERATION_INVALID,
+          `The adapter for destination "${operation.destination}" answered the lookup for ` +
+            `"${operation.operationId}" with a value that is neither a remote state nor an ` +
+            "issued `cannotEstablish`. Reading it as absent would record a completed search that " +
+            "did not happen (contract §17).",
+          {
+            category: "validation",
+            retryable: false,
+            details: {
+              runId: bundle.runId,
+              operationId: operation.operationId,
+              destination: operation.destination,
+            },
+          },
+        );
+      }
+
       if (!remote.exists) {
+        // Reserved to a `lookup` that actually returned `exists: false`. Every other reason an
+        // operation might not have been found now has its own action, so this one means what it
+        // says: a completed search established that the destination does not hold it (#169).
         findings.push({
           operationId: operation.operationId,
           idempotencyKey,
@@ -292,11 +453,17 @@ export class ReleaseExecutor {
     const warnings: string[] = [];
     const written: ReleaseReceipt[] = [];
 
+    // Operations this pass must not attempt, held in memory and never written down. A best-effort
+    // operation whose prior state could not be established is not performed now — executing on an
+    // unknown prior state might repeat something that already happened — and leaves no durable
+    // trace, so the next pass asks again rather than finding a terminal receipt (#169).
+    const unestablished = new Set<string>();
     if (options.reconcile !== false) {
       const report = await this.reconcile(bundle, { actor: options.actor });
       written.push(...report.repaired);
       for (const finding of report.findings) {
-        if (finding.explanation !== undefined && finding.action !== "confirmed_absent") {
+        if (finding.action === "cannot_establish") unestablished.add(finding.operationId);
+        if (finding.explanation !== undefined && OPERATOR_FACING_FINDINGS.has(finding.action)) {
           warnings.push(finding.explanation);
         }
       }
@@ -318,13 +485,28 @@ export class ReleaseExecutor {
         continue;
       }
 
+      // Skipped for this pass only. No receipt was written, so a later pass reaches the same
+      // operation with the same undecided state and asks the destination again.
+      if (unestablished.has(operation.operationId)) continue;
+
       const existing = latest.get(idempotencyKey);
       if (existing?.status === "succeeded" || existing?.status === "skipped") continue;
 
       // An operation whose outcome was never confirmed must not be retried (contract §17). If
       // reconciliation could have resolved it, it already ran above and this receipt would be
       // terminal; reaching here means the destination cannot be queried.
-      if (existing?.status === "pending") {
+      //
+      // Unless the operation says repeating it is safe, which is exactly the fact this refusal
+      // needs and previously had no way to hear. Without it a best-effort tidy-up whose outcome
+      // was once unconfirmed refused **every later release of that bundle** — the same operation
+      // whose failure `execute` treats as a warning, blocking the release forever because one
+      // past attempt went unanswered (#169).
+      if (existing?.status === "pending" && operation.repeatable !== undefined) {
+        warnings.push(
+          `"${operation.operationId}" has an unconfirmed earlier outcome and declares its effect ` +
+            `safe to repeat, so it is being performed again: ${operation.repeatable.reason}`,
+        );
+      } else if (existing?.status === "pending") {
         throw releaseError(
           ReleaseErrorCodes.RECONCILIATION_UNAVAILABLE,
           `"${operation.operationId}" was attempted and its outcome was never confirmed, and ` +
@@ -425,7 +607,7 @@ export class ReleaseExecutor {
     ];
     return entries.map((entry) => ({
       ...entry,
-      idempotencyKey: deriveIdempotencyKey(bundle.bundleId, entry.operation),
+      idempotencyKey: deriveIdempotencyKey(entry.operation),
     }));
   }
 
@@ -442,6 +624,9 @@ export class ReleaseExecutor {
       schemaVersion: SCHEMA_VERSION,
       releaseId: this.#nextReleaseId(),
       runId: bundle.runId,
+      // Recorded, never keyed on (ADR-0033). The trace can now say which release produced this
+      // receipt; matching still happens on what the operation does, so a resumed bundle finds it.
+      bundleId: bundle.bundleId,
       destination: operation.destination,
       operation: operation.kind,
       idempotencyKey,
@@ -453,6 +638,11 @@ export class ReleaseExecutor {
       ...(outcome.status === "succeeded" && outcome.remoteUrl !== undefined
         ? { remoteUrl: outcome.remoteUrl }
         : {}),
+      // Carried through to the durable record. A field an adapter can set and nothing reads is
+      // the defect #107 reported, one contract over.
+      ...(outcome.status === "succeeded" && outcome.note !== undefined
+        ? { note: outcome.note }
+        : {}),
       // `pending` is not terminal, so it carries no completion time (contract §17).
       ...(outcome.status === "pending" ? {} : { completedAt: at }),
       ...(outcome.status === "failed"

package/src/index.ts

@@ -18,7 +18,10 @@
 export {
   AdapterRegistry,
   RecordingReleaseAdapter,
+  cannotEstablish,
+  isCannotEstablish,
   type AdapterOutcome,
+  type CannotEstablish,
   type RecordingAdapterOptions,
   type ReleaseAdapter,
   type ReleaseRequest,
@@ -56,7 +59,9 @@ export {
 
 export {
   bestEffortOperation,
+  repeatable,
   requiredOperation,
+  type RepeatableDeclaration,
   type BestEffortOperation,
   type OperationCriticality,
   type ReleaseOperation,

package/src/operation.ts

@@ -20,8 +20,55 @@
  * constructor below. A caller cannot hand-write an object literal that satisfies
  * {@link RequiredOperation}.
  */
+import { ReleaseErrorCodes, releaseError } from "./errors.js";
+
 declare const CRITICALITY: unique symbol;
 
+/** @see RepeatableDeclaration */
+declare const REPEATABILITY: unique symbol;
+
+/**
+ * A statement that an operation's effect may be performed more than once (§17, §19.1; #169).
+ *
+ * Minted by {@link repeatable} and not writable as an object literal, for the same reason
+ * `RequiredOperation` is not: this licenses re-performing a real external effect, and a shape a
+ * caller can assemble is a shape that gets assembled from configuration by someone who has not
+ * thought about it.
+ *
+ * The reason is **required**. An operation that may be repeated is one an approver is being asked
+ * to accept the repetition of, and "safe to repeat" with no account of why is not something anyone
+ * can approve or audit.
+ */
+export interface RepeatableDeclaration {
+  readonly [REPEATABILITY]: "repeatable";
+  /**
+   * Why repeating this effect is safe, for the approver and for the operator.
+   *
+   * Shown in the reconciliation finding that records the operation was not queried, so a reader
+   * sees the justification rather than only the outcome.
+   */
+  readonly reason: string;
+}
+
+/**
+ * Declare that repeating this operation's effect is safe (§17, §19.1; #169).
+ *
+ * @throws {AldusError} when the reason is empty. A declaration that licenses repetition and says
+ * nothing about why is the thing this exists to prevent.
+ */
+export function repeatable(reason: string): RepeatableDeclaration {
+  if (reason.trim().length === 0) {
+    throw releaseError(
+      ReleaseErrorCodes.OPERATION_INVALID,
+      "A repeatable declaration must say why repeating the effect is safe. It licenses performing " +
+        "an external effect more than once, and an approver cannot accept that from a bare flag " +
+        "(contract §13.4, §17).",
+      { category: "validation", retryable: false, details: {} },
+    );
+  }
+  return { reason } as RepeatableDeclaration;
+}
+
 /** Fields shared by both categories. */
 export interface ReleaseOperationBase {
   /**
@@ -65,6 +112,23 @@ export interface ReleaseOperationBase {
    * The gate engine decides whether the authority is held; this package never re-decides it.
    */
   requiresAuthority?: string;
+  /**
+   * Declares that repeating this operation's effect is safe (§17, §19.1; #169).
+   *
+   * **Absent means one-shot**, which is the conservative reading and the behaviour every existing
+   * bundle already has. Repetition is licensed only by saying so.
+   *
+   * In the **bundle**, not on the adapter and not in `RemoteState`. §13.4 binds a release approval
+   * to the bundle, so a fact that licenses re-performing an effect has to be visible in the
+   * artifact an approver approved — an adapter-side flag would let an adapter license repeating an
+   * operation the approver believed happened once.
+   *
+   * Not inferable from {@link ReleaseOperationBase} either. `deriveIdempotencyKey` documents its
+   * result as the key that makes re-running safe, and that holds only where the destination
+   * honours the key; plenty do not. A key's presence is a request, not a guarantee, so
+   * repeatability has to be stated.
+   */
+  repeatable?: RepeatableDeclaration;
   /** Opaque parameters passed through to the adapter. Never inspected here. */
   parameters?: Readonly<Record<string, unknown>>;
 }

package/src/ports.ts

@@ -16,7 +16,7 @@ import type { EventStore, RunStore } from "@aldus-runtime/file-store";
  * 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.
+ * explains the retry. {@link latestByKey} resolves the current outcome by reading them in order.
  */
 export interface ReleaseReceiptStore {
   /** Every receipt recorded for a Run, in the order they were appended. */