@aldus-runtime/release 0.2.0-next.20 → 0.2.0-next.21

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 ` +
@@ -456,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>>;
 }