@aldus-runtime/release 0.1.0

package/dist/executor.js

@@ -0,0 +1,342 @@
+/**
+ * Release execution, resumption, and reconciliation (architecture contract §17, §19.1).
+ *
+ * Three properties drive the design, and each rules out the obvious implementation:
+ *
+ * 1. **§17: every operation is independently idempotent and resumable.** So execution is never a
+ *    transaction over a bundle. Each operation carries its own derived idempotency key and its
+ *    own receipt, and a half-executed bundle is resumed by skipping what already succeeded.
+ *
+ * 2. **§17: pre-release hard gates and post-upload best-effort operations are distinguished.**
+ *    The first failure among required operations stops the bundle — a failed media upload must
+ *    not be followed by a visibility transition making nothing public. A best-effort failure is
+ *    recorded and execution continues.
+ *
+ * 3. **§17: external state must be reconciled, not guessed.** A response lost after the
+ *    destination accepted a request leaves local records saying nothing happened while something
+ *    did. Retrying then publishes twice. So an operation whose outcome was recorded as `pending`
+ *    is never retried; it is looked up, and if the destination cannot be queried the executor
+ *    refuses rather than risking the duplicate.
+ *
+ * Nothing about a bundle's progress is stored beyond its receipts. State is derived on every
+ * call, for the reason ADR-0009 derives gate state: a stored progress flag survives a crash that
+ * the work it describes did not.
+ */
+import { SCHEMA_VERSION, newEventId, newReleaseId } from "@aldus-runtime/core";
+import { assertBundleValid, deriveIdempotencyKey } from "./bundle.js";
+import { ReleaseErrorCodes, releaseError } from "./errors.js";
+import { latestByKey } from "./ports.js";
+import { permitAllAuthorizer } from "./authorization.js";
+/** Where one operation stands. */
+export const OPERATION_STATES = [
+    /** No receipt exists; it has not been attempted. */
+    "not_started",
+    /** Attempted, outcome unconfirmed. MUST be reconciled, never retried (contract §17). */
+    "pending",
+    /** Completed at the destination. */
+    "succeeded",
+    /** Attempted and rejected by the destination. */
+    "failed",
+    /** Deliberately not attempted — no authority, or nothing to do. */
+    "skipped",
+];
+/** Executes release bundles, resumably. */
+export class ReleaseExecutor {
+    #adapters;
+    #receipts;
+    #events;
+    #authorizer;
+    #now;
+    #nextReleaseId;
+    #nextEventId;
+    constructor(options) {
+        this.#adapters = options.adapters;
+        this.#receipts = options.receipts;
+        this.#events = options.events;
+        this.#authorizer = options.authorizer ?? permitAllAuthorizer();
+        this.#now = options.now ?? (() => new Date());
+        this.#nextReleaseId = options.nextReleaseId ?? newReleaseId;
+        this.#nextEventId = options.nextEventId ?? newEventId;
+    }
+    /**
+     * Derive where a bundle stands from its receipts (contract §19.1).
+     *
+     * Reads only; safe to call at any time, including on a bundle that has never run.
+     */
+    async status(bundle) {
+        assertBundleValid(bundle);
+        const latest = latestByKey(await this.#receipts.list(bundle.runId));
+        const operations = this.#plan(bundle).map(({ operation, criticality, idempotencyKey }) => toStatus(operation, criticality, idempotencyKey, latest.get(idempotencyKey)));
+        const required = operations.filter((entry) => entry.criticality === "required");
+        const remaining = operations
+            .filter((entry) => entry.state !== "succeeded" && entry.state !== "skipped")
+            .map((entry) => entry.operationId);
+        return {
+            bundleId: bundle.bundleId,
+            runId: bundle.runId,
+            state: bundleState(required),
+            operations,
+            remaining,
+        };
+    }
+    /**
+     * Repair the local record against the destinations (contract §17).
+     *
+     * Only operations without a terminal local receipt are looked up: an operation already
+     * recorded as succeeded or failed has an answer, and asking again would turn reconciliation
+     * into polling.
+     */
+    async reconcile(bundle, options) {
+        assertBundleValid(bundle);
+        const latest = latestByKey(await this.#receipts.list(bundle.runId));
+        const findings = [];
+        const repaired = [];
+        for (const { operation, idempotencyKey } of this.#plan(bundle)) {
+            const receipt = latest.get(idempotencyKey);
+            if (receipt !== undefined && receipt.status !== "pending") {
+                findings.push({
+                    operationId: operation.operationId,
+                    idempotencyKey,
+                    action: "already_recorded",
+                });
+                continue;
+            }
+            const adapter = this.#adapters.require(operation.destination);
+            if (adapter.lookup === undefined) {
+                findings.push({
+                    operationId: operation.operationId,
+                    idempotencyKey,
+                    action: "unavailable",
+                    explanation: `Destination "${operation.destination}" cannot be queried, so whether ` +
+                        `"${operation.operationId}" already happened is unknowable from here.`,
+                });
+                continue;
+            }
+            const request = {
+                operation,
+                idempotencyKey,
+                runId: bundle.runId,
+            };
+            const remote = await adapter.lookup(request);
+            if (!remote.exists) {
+                findings.push({
+                    operationId: operation.operationId,
+                    idempotencyKey,
+                    action: "confirmed_absent",
+                });
+                continue;
+            }
+            const written = await this.#record(bundle, operation, idempotencyKey, {
+                status: "succeeded",
+                ...(remote.remoteId === undefined ? {} : { remoteId: remote.remoteId }),
+                ...(remote.remoteUrl === undefined ? {} : { remoteUrl: remote.remoteUrl }),
+            }, options.actor);
+            repaired.push(written);
+            findings.push({
+                operationId: operation.operationId,
+                idempotencyKey,
+                action: "repaired",
+                explanation: `The destination already holds "${operation.operationId}". The local record was ` +
+                    "repaired rather than the operation repeated.",
+            });
+        }
+        return { bundleId: bundle.bundleId, runId: bundle.runId, findings, repaired };
+    }
+    /**
+     * Execute a bundle, resuming whatever has already succeeded (contract §17, §19.1).
+     *
+     * Reconciles first by default, so the safe path is the one a caller gets without asking.
+     */
+    async execute(bundle, options) {
+        assertBundleValid(bundle);
+        const warnings = [];
+        const written = [];
+        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") {
+                    warnings.push(finding.explanation);
+                }
+            }
+        }
+        let latest = latestByKey(await this.#receipts.list(bundle.runId));
+        let halted = false;
+        let haltState;
+        for (const { operation, criticality, idempotencyKey } of this.#plan(bundle)) {
+            // §17 calls the best-effort operations "post-upload": they run only once every required
+            // one has succeeded. Attempting a notification about a release that failed would announce
+            // something that does not exist.
+            if (halted) {
+                warnings.push(`"${operation.operationId}" was not attempted because a required operation did not ` +
+                    "succeed.");
+                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") {
+                throw releaseError(ReleaseErrorCodes.RECONCILIATION_UNAVAILABLE, `"${operation.operationId}" was attempted and its outcome was never confirmed, and ` +
+                    `destination "${operation.destination}" cannot be queried to find out. Retrying ` +
+                    "would risk performing it twice, so it is refused until the outcome is established.", {
+                    category: "conflict",
+                    retryable: false,
+                    details: {
+                        runId: bundle.runId,
+                        operationId: operation.operationId,
+                        destination: operation.destination,
+                    },
+                });
+            }
+            const verdict = operation.requiresAuthority === undefined
+                ? { authorized: true }
+                : await this.#authorizer.check(bundle.runId, operation.requiresAuthority);
+            if (!verdict.authorized) {
+                const explanation = `"${operation.operationId}" requires authority "${operation.requiresAuthority}", ` +
+                    `which is not held. ${verdict.explanation ?? ""}`.trim();
+                // A required operation without authority is a refusal, not a warning: §13.4 binds
+                // release approval to exact inputs, and continuing past it would publish unapproved.
+                if (criticality === "required") {
+                    throw releaseError(ReleaseErrorCodes.RELEASE_NOT_AUTHORIZED, explanation, {
+                        category: "policy",
+                        retryable: false,
+                        details: {
+                            runId: bundle.runId,
+                            operationId: operation.operationId,
+                            authority: operation.requiresAuthority,
+                        },
+                    });
+                }
+                // A best-effort operation is recorded as skipped rather than failed. It was never
+                // attempted, and a `failed` receipt would claim the destination rejected it.
+                written.push(await this.#record(bundle, operation, idempotencyKey, { status: "skipped", message: explanation }, options.actor));
+                warnings.push(explanation);
+                continue;
+            }
+            const adapter = this.#adapters.require(operation.destination);
+            const outcome = await adapter.execute({ operation, idempotencyKey, runId: bundle.runId });
+            written.push(await this.#record(bundle, operation, idempotencyKey, outcome, options.actor));
+            if (outcome.status === "succeeded")
+                continue;
+            if (criticality === "best_effort") {
+                warnings.push(`Best-effort operation "${operation.operationId}" did not succeed ` +
+                    `(${outcome.status}). The release is unaffected.`);
+                continue;
+            }
+            halted = true;
+            haltState = outcome.status === "pending" ? "pending" : "failed";
+        }
+        latest = latestByKey(await this.#receipts.list(bundle.runId));
+        const status = await this.status(bundle);
+        const state = haltState ?? (status.state === "succeeded" ? "succeeded" : "pending");
+        return { bundleId: bundle.bundleId, runId: bundle.runId, state, status, written, warnings };
+    }
+    /** Operations paired with their category and derived key, in execution order. */
+    #plan(bundle) {
+        const entries = [
+            ...bundle.required.map((operation) => ({
+                operation: operation,
+                criticality: "required",
+            })),
+            ...bundle.bestEffort.map((operation) => ({
+                operation: operation,
+                criticality: "best_effort",
+            })),
+        ];
+        return entries.map((entry) => ({
+            ...entry,
+            idempotencyKey: deriveIdempotencyKey(bundle.bundleId, entry.operation),
+        }));
+    }
+    /** Write a receipt and emit its event (contract §6.4, §17). */
+    async #record(bundle, operation, idempotencyKey, outcome, actor) {
+        const at = this.#now().toISOString();
+        const receipt = {
+            schemaVersion: SCHEMA_VERSION,
+            releaseId: this.#nextReleaseId(),
+            runId: bundle.runId,
+            destination: operation.destination,
+            operation: operation.kind,
+            idempotencyKey,
+            status: outcome.status,
+            inputHashes: [...operation.inputHashes],
+            ...(outcome.status === "succeeded" && outcome.remoteId !== undefined
+                ? { remoteId: outcome.remoteId }
+                : {}),
+            ...(outcome.status === "succeeded" && outcome.remoteUrl !== undefined
+                ? { remoteUrl: outcome.remoteUrl }
+                : {}),
+            // `pending` is not terminal, so it carries no completion time (contract §17).
+            ...(outcome.status === "pending" ? {} : { completedAt: at }),
+            ...(outcome.status === "failed"
+                ? {
+                    error: {
+                        code: "ALDUS_RELEASE_OPERATION_FAILED",
+                        category: "provider",
+                        message: outcome.message,
+                        retryable: outcome.retryable ?? true,
+                        occurredAt: at,
+                    },
+                }
+                : {}),
+        };
+        await this.#receipts.append(bundle.runId, receipt);
+        await this.#events.emit(this.#event(bundle, operation, receipt, at, outcome, actor));
+        return receipt;
+    }
+    /** The §6.4 event for one recorded outcome. */
+    #event(bundle, operation, receipt, at, outcome, actor) {
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            eventId: this.#nextEventId(),
+            occurredAt: at,
+            episodeId: bundle.episodeId,
+            runId: bundle.runId,
+            action: `release.operation.${receipt.status}`,
+            actor,
+            inputRefs: [],
+            outputRefs: [],
+            idempotencyKey: receipt.idempotencyKey,
+            details: {
+                bundleId: bundle.bundleId,
+                operationId: operation.operationId,
+                kind: operation.kind,
+                destination: operation.destination,
+                releaseId: receipt.releaseId,
+                ...("message" in outcome && outcome.message !== undefined
+                    ? { message: outcome.message }
+                    : {}),
+            },
+            ...(receipt.error === undefined ? {} : { error: receipt.error }),
+        };
+    }
+}
+/** Derive one operation's state from its latest receipt. */
+function toStatus(operation, criticality, idempotencyKey, receipt) {
+    return {
+        operationId: operation.operationId,
+        kind: operation.kind,
+        destination: operation.destination,
+        criticality,
+        idempotencyKey,
+        state: receipt === undefined ? "not_started" : receipt.status,
+        ...(receipt === undefined ? {} : { receipt }),
+    };
+}
+/** A bundle's state is the state of its required operations (contract §17). */
+function bundleState(required) {
+    if (required.every((entry) => entry.state === "succeeded" || entry.state === "skipped")) {
+        return "succeeded";
+    }
+    if (required.some((entry) => entry.state === "failed"))
+        return "failed";
+    if (required.some((entry) => entry.state === "pending"))
+        return "pending";
+    if (required.every((entry) => entry.state === "not_started"))
+        return "not_started";
+    return "in_progress";
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@aldus-runtime/release` — release bundles, resumable operations, and external-state reconciliation.
+ *
+ * Implements architecture contract §22 **WP-12 Release adapters** and §17.
+ *
+ * Contract §22's own wording for this work package names two publishing platforms. This package
+ * names none, and that is deliberate: §4.2 keeps publishing platforms out of the runtime, §1.2
+ * explicitly rules out prescribing particular release targets, and §4.3 places release
+ * configuration in Integration. What ships here is the **adapter contract and the resumable
+ * machinery**; an adopter supplies the client that talks to a destination.
+ *
+ * Not implemented here, by design: any real platform client, the CLI (WP-08), the Production MCP
+ * (WP-11), and the TTS ledger (WP-07).
+ *
+ * @packageDocumentation
+ */
+export { AdapterRegistry, RecordingReleaseAdapter, type AdapterOutcome, type RecordingAdapterOptions, type ReleaseAdapter, type ReleaseRequest, type RemoteState, } from "./adapter.js";
+export { gateEngineAuthorizer, permitAllAuthorizer, type AuthorityVerdict, type ReleaseAuthorizer, } from "./authorization.js";
+export { assertBundleValid, deriveIdempotencyKey, operationsOf, type ReleaseBundle, } from "./bundle.js";
+export { ReleaseErrorCodes, releaseError, type ReleaseErrorCode } from "./errors.js";
+export { OPERATION_STATES, ReleaseExecutor, type BundleStatus, type ExecuteOptions, type OperationState, type OperationStatus, type ReconciliationFinding, type ReconciliationReport, type ReleaseExecutorOptions, type ReleaseOutcome, } from "./executor.js";
+export { bestEffortOperation, requiredOperation, type BestEffortOperation, type OperationCriticality, type ReleaseOperation, type ReleaseOperationBase, type RequiredOperation, } from "./operation.js";
+export { MemoryReleaseEventSink, MemoryReleaseReceiptStore, eventStoreSink, latestByKey, runStoreReceipts, type ReleaseEventSink, type ReleaseReceiptStore, } from "./ports.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAErF,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@aldus-runtime/release` — release bundles, resumable operations, and external-state reconciliation.
+ *
+ * Implements architecture contract §22 **WP-12 Release adapters** and §17.
+ *
+ * Contract §22's own wording for this work package names two publishing platforms. This package
+ * names none, and that is deliberate: §4.2 keeps publishing platforms out of the runtime, §1.2
+ * explicitly rules out prescribing particular release targets, and §4.3 places release
+ * configuration in Integration. What ships here is the **adapter contract and the resumable
+ * machinery**; an adopter supplies the client that talks to a destination.
+ *
+ * Not implemented here, by design: any real platform client, the CLI (WP-08), the Production MCP
+ * (WP-11), and the TTS ledger (WP-07).
+ *
+ * @packageDocumentation
+ */
+export { AdapterRegistry, RecordingReleaseAdapter, } from "./adapter.js";
+export { gateEngineAuthorizer, permitAllAuthorizer, } from "./authorization.js";
+export { assertBundleValid, deriveIdempotencyKey, operationsOf, } from "./bundle.js";
+export { ReleaseErrorCodes, releaseError } from "./errors.js";
+export { OPERATION_STATES, ReleaseExecutor, } from "./executor.js";
+export { bestEffortOperation, requiredOperation, } from "./operation.js";
+export { MemoryReleaseEventSink, MemoryReleaseReceiptStore, eventStoreSink, latestByKey, runStoreReceipts, } from "./ports.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,eAAe,EACf,uBAAuB,GAMxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,GAGpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GAEb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAyB,MAAM,aAAa,CAAC;AAErF,OAAO,EACL,gBAAgB,EAChB,eAAe,GAShB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAMlB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,gBAAgB,GAGjB,MAAM,YAAY,CAAC"}

package/dist/operation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 declare function requiredOperation(operation: ReleaseOperationBase): RequiredOperation;
+/** Declare an operation whose failure is recorded but tolerated (contract §17). */
+export declare function bestEffortOperation(operation: ReleaseOperationBase): 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";
+export {};
+//# sourceMappingURL=operation.d.ts.map

package/dist/operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AAEzC,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,oBAAoB;IAC7D,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;CACvC;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAEvE,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,oBAAoB,GAAG,iBAAiB,CAEpF;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,oBAAoB,GAAG,mBAAmB,CAExF;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,aAAa,CAAC"}

package/dist/operation.js

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+/** Declare an operation whose failure fails the release (contract §17). */
+export function requiredOperation(operation) {
+    return { ...operation };
+}
+/** Declare an operation whose failure is recorded but tolerated (contract §17). */
+export function bestEffortOperation(operation) {
+    return { ...operation };
+}
+//# sourceMappingURL=operation.js.map

package/dist/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkFH,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB,CAAC,SAA+B;IAC/D,OAAO,EAAE,GAAG,SAAS,EAAuB,CAAC;AAC/C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CAAC,SAA+B;IACjE,OAAO,EAAE,GAAG,SAAS,EAAyB,CAAC;AACjD,CAAC"}

package/dist/ports.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 declare function latestByKey(receipts: readonly ReleaseReceipt[]): Map<string, ReleaseReceipt>;
+/** An in-memory {@link ReleaseReceiptStore}, for tests and for dry runs. */
+export declare class MemoryReleaseReceiptStore implements ReleaseReceiptStore {
+    #private;
+    list(runId: string): Promise<ReleaseReceipt[]>;
+    append(runId: string, receipt: ReleaseReceipt): Promise<void>;
+    /**
+     * 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;
+}
+/** An in-memory {@link ReleaseEventSink} that retains what it was given, for tests. */
+export declare class MemoryReleaseEventSink implements ReleaseEventSink {
+    readonly events: AldusEvent[];
+    emit(event: AldusEvent): Promise<void>;
+}
+/**
+ * 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 declare function runStoreReceipts(runs: RunStore): ReleaseReceiptStore;
+/**
+ * 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 declare function eventStoreSink(events: EventStore): ReleaseEventSink;
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC/C,0BAA0B;IAC1B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAI5F;AAED,4EAA4E;AAC5E,qBAAa,yBAA0B,YAAW,mBAAmB;;IAGnE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE7C;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5D;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE1B;CACF;AAED,uFAAuF;AACvF,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAM;IAEnC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrC;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,mBAAmB,CAKpE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAMnE"}