@loomwork/event-runtime 0.0.0-stage → 0.1.1

package/dist/archive.d.ts

@@ -0,0 +1,68 @@
+import { type EventEnvelope } from "@loomwork/core";
+import { type ArchiveExecutionPage, type ArchiveSegment, type ArchiveSegmentKind, type ArchiveStore } from "./archiveSpi";
+/**
+ * The digest of a run of envelopes: SHA-256 (hex) over their canonical JSON (sorted keys, so a
+ * backend that reorders object keys on a JSON round trip, such as Postgres `jsonb`, still agrees).
+ */
+export declare function segmentDigest(envelopes: readonly EventEnvelope[]): string;
+/** Build a segment from the envelopes a compaction removes. `envelopes` must be non-empty and ascending. */
+export declare function buildSegment(envelopes: readonly EventEnvelope[], incarnation: string, from?: number, through?: number, kind?: ArchiveSegmentKind): ArchiveSegment;
+/** `payload.sender` after the sender was erased (sealed under their subject and shredded, or redacted). */
+export declare const SENDER_ERASED: Readonly<{
+    erased: true;
+}>;
+/**
+ * The erased-sender marker carrying a STABLE, NON-IDENTIFYING per-sender reference (ADR 0139 N3): the sealed
+ * sender's opaque handle, or a random one a plaintext redaction minted per erased subject. Two messages
+ * from one erased sender still share it and two different erased senders do not, so the owner's dedupe
+ * (which keyed on the identity before the erasure) keeps telling them apart; it names nobody.
+ */
+export declare function senderErasedMarker(ref?: string): {
+    erased: true;
+    ref?: string;
+};
+/** Whether a stored `sender` value is the {@link SENDER_ERASED} marker. */
+export declare function isSenderErased(v: unknown): boolean;
+/**
+ * The envelope with an inbox message's `payload.sender` masked (`null`). The digest of a RESERVED
+ * stream's segment is taken over this form, so the one thing an erasure may change afterwards - the
+ * sender's identity, sealed under THEIR subject and shredded with it, or redacted in a plaintext archive
+ * (a recorded redaction, ADR 0139 D12) - does not turn into a digest mismatch on the audit read. Every
+ * other byte stays covered, and a live envelope is compared with its archived copy by
+ * {@link sameReservedEnvelope}, which still tells two DIFFERENT live senders apart.
+ */
+export declare function maskSender(e: EventEnvelope): EventEnvelope;
+/** {@link segmentDigest} over {@link maskSender}-masked envelopes (the digest of a reserved-stream segment). */
+export declare function reservedSegmentDigest(envelopes: readonly EventEnvelope[]): string;
+/**
+ * ADR 0139 N7 - the digest of the SENDERS of a run of reserved-stream envelopes (SHA-256 over the canonical
+ * JSON of each envelope's `payload.sender`, `null` for one without). A plaintext reserved segment carries it
+ * beside its (sender-masked) `digest`, so the one field an erasure may redact still has bit-rot detection;
+ * a redaction recomputes it in the same atomic replace.
+ */
+export declare function senderDigestOf(envelopes: readonly EventEnvelope[]): string;
+/** {@link buildSegment} with the reserved-stream digest. */
+export declare function buildReservedSegment(envelopes: readonly EventEnvelope[], incarnation: string, from?: number, through?: number): ArchiveSegment;
+/** {@link assertSegmentDigest} for a reserved-stream segment. */
+export declare function assertReservedSegmentDigest(executionId: string, segment: ArchiveSegment): void;
+/**
+ * Are `live` and `archived` the same inbox envelope? Equal masked digests, and the senders either equal
+ * or at least one of them erased (an erased sender is the same fact with its identity removed).
+ */
+export declare function sameReservedEnvelope(live: EventEnvelope, archived: EventEnvelope): boolean;
+/** One page of ids from an ascending list, keyset by exclusive cursor (shared by the backends' tests and memory store). */
+export declare function pageIds(sorted: readonly string[], opts?: {
+    cursor?: string;
+    limit?: number;
+}): ArchiveExecutionPage;
+/** Throws {@link ArchiveDigestError} when `segment`'s envelopes do not hash to its digest. */
+export declare function assertSegmentDigest(executionId: string, segment: ArchiveSegment): void;
+/**
+ * The ids of the reserved streams of `chainId` the archive holds segments for (keyset prefix scans, ADR
+ * 0139): the chain's inbox (legacy, per-topic, registry) and quarantine streams, and the late runs split
+ * from them. The late keys all sit under one prefix, so their scan walks every late run of every chain
+ * (they exist only after a raced send or a node without an archive floor: a handful at most); the listing
+ * is paged by 200.
+ */
+export declare function archivedReservedStreams(archive: Pick<ArchiveStore, "listExecutions">, chainId: string): Promise<string[]>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAElB,MAAM,cAAc,CAAC;AAyBtB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAOzE;AAED,4GAA4G;AAC5G,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,MAA+B,EACrC,OAAO,GAAE,MAAkD,EAC3D,IAAI,CAAC,EAAE,kBAAkB,GACxB,cAAc,CAUhB;AAID,2GAA2G;AAC3G,eAAO,MAAM,aAAa;;EAA2C,CAAC;AAEtE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAE/E;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,aAAa,CAK1D;AAED,gHAAgH;AAChH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAa1E;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,MAA+B,EACrC,OAAO,GAAE,MAAkD,GAC1D,cAAc,CAMhB;AAED,iEAAiE;AACjE,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CA2B9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAM1F;AAED,2HAA2H;AAC3H,wBAAgB,OAAO,CACrB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,oBAAoB,CAUtB;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAWtF;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,gBAAgB,CAAC,EAC7C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBnB"}

package/dist/archive.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENDER_ERASED = void 0;
+exports.segmentDigest = segmentDigest;
+exports.buildSegment = buildSegment;
+exports.senderErasedMarker = senderErasedMarker;
+exports.isSenderErased = isSenderErased;
+exports.maskSender = maskSender;
+exports.reservedSegmentDigest = reservedSegmentDigest;
+exports.senderDigestOf = senderDigestOf;
+exports.buildReservedSegment = buildReservedSegment;
+exports.assertReservedSegmentDigest = assertReservedSegmentDigest;
+exports.sameReservedEnvelope = sameReservedEnvelope;
+exports.pageIds = pageIds;
+exports.assertSegmentDigest = assertSegmentDigest;
+exports.archivedReservedStreams = archivedReservedStreams;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@loomwork/core");
+const archiveSpi_1 = require("./archiveSpi");
+const executionIdOrder_1 = require("./executionIdOrder");
+const types_1 = require("./types");
+/**
+ * The JSON form of the envelopes, which is what every backend stores and returns (a `Date` becomes
+ * its ISO string, `toJSON` runs, `undefined` members drop). Digesting the round-tripped value makes
+ * the digest the same on the write side and on a read that came back through any JSON store, and a
+ * value that cannot be JSON (circular, BigInt, a nesting JSON cannot hold) a typed refusal at
+ * archive time instead of a `TypeError` mid-compaction or a false digest mismatch on audit.
+ */
+function jsonForm(envelopes) {
+    try {
+        return JSON.parse(JSON.stringify(envelopes));
+    }
+    catch (err) {
+        throw new archiveSpi_1.ArchiveUnserializableError(err);
+    }
+}
+/**
+ * The digest of a run of envelopes: SHA-256 (hex) over their canonical JSON (sorted keys, so a
+ * backend that reorders object keys on a JSON round trip, such as Postgres `jsonb`, still agrees).
+ */
+function segmentDigest(envelopes) {
+    const form = jsonForm(envelopes);
+    try {
+        return (0, node_crypto_1.createHash)("sha256").update((0, core_1.canonicalJson)(form)).digest("hex");
+    }
+    catch (err) {
+        throw new archiveSpi_1.ArchiveUnserializableError(err);
+    }
+}
+/** Build a segment from the envelopes a compaction removes. `envelopes` must be non-empty and ascending. */
+function buildSegment(envelopes, incarnation, from = envelopes[0].sequence, through = envelopes[envelopes.length - 1].sequence, kind) {
+    return {
+        from,
+        through,
+        count: envelopes.length,
+        digest: segmentDigest(envelopes),
+        incarnation,
+        ...(kind !== undefined && kind !== "events" && { kind }),
+        envelopes,
+    };
+}
+// ── ADR 0139 D12 - the sender field of an archived inbox envelope is the one erasable part ──────────
+/** `payload.sender` after the sender was erased (sealed under their subject and shredded, or redacted). */
+exports.SENDER_ERASED = Object.freeze({ erased: true });
+/**
+ * The erased-sender marker carrying a STABLE, NON-IDENTIFYING per-sender reference (ADR 0139 N3): the sealed
+ * sender's opaque handle, or a random one a plaintext redaction minted per erased subject. Two messages
+ * from one erased sender still share it and two different erased senders do not, so the owner's dedupe
+ * (which keyed on the identity before the erasure) keeps telling them apart; it names nobody.
+ */
+function senderErasedMarker(ref) {
+    return ref === undefined ? { erased: true } : { erased: true, ref };
+}
+/** Whether a stored `sender` value is the {@link SENDER_ERASED} marker. */
+function isSenderErased(v) {
+    return typeof v === "object" && v !== null && v.erased === true;
+}
+/**
+ * The envelope with an inbox message's `payload.sender` masked (`null`). The digest of a RESERVED
+ * stream's segment is taken over this form, so the one thing an erasure may change afterwards - the
+ * sender's identity, sealed under THEIR subject and shredded with it, or redacted in a plaintext archive
+ * (a recorded redaction, ADR 0139 D12) - does not turn into a digest mismatch on the audit read. Every
+ * other byte stays covered, and a live envelope is compared with its archived copy by
+ * {@link sameReservedEnvelope}, which still tells two DIFFERENT live senders apart.
+ */
+function maskSender(e) {
+    if (e.eventType !== "INBOX_MESSAGE")
+        return e;
+    const p = e.payload;
+    if (p === null || typeof p !== "object" || p.sender === undefined)
+        return e;
+    return { ...e, payload: { ...p, sender: null } };
+}
+/** {@link segmentDigest} over {@link maskSender}-masked envelopes (the digest of a reserved-stream segment). */
+function reservedSegmentDigest(envelopes) {
+    return segmentDigest(envelopes.map(maskSender));
+}
+/**
+ * ADR 0139 N7 - the digest of the SENDERS of a run of reserved-stream envelopes (SHA-256 over the canonical
+ * JSON of each envelope's `payload.sender`, `null` for one without). A plaintext reserved segment carries it
+ * beside its (sender-masked) `digest`, so the one field an erasure may redact still has bit-rot detection;
+ * a redaction recomputes it in the same atomic replace.
+ */
+function senderDigestOf(envelopes) {
+    const senders = envelopes.map((e) => e.eventType === "INBOX_MESSAGE"
+        ? (e.payload?.sender ?? null)
+        : null);
+    try {
+        return (0, node_crypto_1.createHash)("sha256")
+            .update((0, core_1.canonicalJson)(JSON.parse(JSON.stringify(senders))))
+            .digest("hex");
+    }
+    catch (err) {
+        throw new archiveSpi_1.ArchiveUnserializableError(err);
+    }
+}
+/** {@link buildSegment} with the reserved-stream digest. */
+function buildReservedSegment(envelopes, incarnation, from = envelopes[0].sequence, through = envelopes[envelopes.length - 1].sequence) {
+    return {
+        ...buildSegment(envelopes, incarnation, from, through),
+        digest: reservedSegmentDigest(envelopes),
+        senderDigest: senderDigestOf(envelopes),
+    };
+}
+/** {@link assertSegmentDigest} for a reserved-stream segment. */
+function assertReservedSegmentDigest(executionId, segment) {
+    // The sender digest is verified ONLY WHEN PRESENT: a segment written before ARCHIVE_STORE_SPI 1.1.0 (or by
+    // an archive that does not persist the field) has none, and still reads - its sender field simply has no
+    // bit-rot detection of its own (ADR 0139 D19; pre-1.1.0 compatibility path, not a downgrade to exploit:
+    // a writer of the archive could equally rewrite the segment).
+    const actual = reservedSegmentDigest(segment.envelopes);
+    if (segment.senderDigest !== undefined &&
+        senderDigestOf(segment.envelopes) !== segment.senderDigest) {
+        throw new archiveSpi_1.ArchiveDigestError(executionId, segment.from, segment.through, `sender:${segment.senderDigest}`, `sender:${senderDigestOf(segment.envelopes)}`);
+    }
+    if (actual !== segment.digest || segment.envelopes.length !== segment.count) {
+        throw new archiveSpi_1.ArchiveDigestError(executionId, segment.from, segment.through, segment.digest, actual);
+    }
+}
+/**
+ * Are `live` and `archived` the same inbox envelope? Equal masked digests, and the senders either equal
+ * or at least one of them erased (an erased sender is the same fact with its identity removed).
+ */
+function sameReservedEnvelope(live, archived) {
+    if (segmentDigest([maskSender(live)]) !== segmentDigest([maskSender(archived)]))
+        return false;
+    const a = live.payload?.sender;
+    const b = archived.payload?.sender;
+    if (isSenderErased(a) || isSenderErased(b))
+        return true;
+    return segmentDigest([{ ...live, payload: a }]) === segmentDigest([{ ...archived, payload: b }]);
+}
+/** One page of ids from an ascending list, keyset by exclusive cursor (shared by the backends' tests and memory store). */
+function pageIds(sorted, opts = {}) {
+    const limit = opts.limit ?? 500;
+    const start = opts.cursor === undefined
+        ? 0
+        : sorted.findIndex((id) => (0, executionIdOrder_1.compareExecutionIds)(id, opts.cursor) > 0);
+    if (start === -1)
+        return { executionIds: [] };
+    const page = sorted.slice(start, start + limit);
+    const more = start + limit < sorted.length;
+    return more ? { executionIds: page, nextCursor: page[page.length - 1] } : { executionIds: page };
+}
+/** Throws {@link ArchiveDigestError} when `segment`'s envelopes do not hash to its digest. */
+function assertSegmentDigest(executionId, segment) {
+    const actual = segmentDigest(segment.envelopes);
+    if (actual !== segment.digest || segment.envelopes.length !== segment.count) {
+        throw new archiveSpi_1.ArchiveDigestError(executionId, segment.from, segment.through, segment.digest, actual);
+    }
+}
+/**
+ * The ids of the reserved streams of `chainId` the archive holds segments for (keyset prefix scans, ADR
+ * 0139): the chain's inbox (legacy, per-topic, registry) and quarantine streams, and the late runs split
+ * from them. The late keys all sit under one prefix, so their scan walks every late run of every chain
+ * (they exist only after a raced send or a node without an archive floor: a handful at most); the listing
+ * is paged by 200.
+ */
+async function archivedReservedStreams(archive, chainId) {
+    const found = [];
+    const own = [`${types_1.INBOX_STREAM_PREFIX}${chainId}`, `${types_1.QUARANTINE_STREAM_PREFIX}${chainId}`];
+    const prefixes = [...own, ...own.map((p) => `${types_1.RESERVED_LATE_PREFIX}${p}`)];
+    for (const prefix of prefixes) {
+        // The cursor is EXCLUSIVE and the stream whose id IS the prefix must be listed, so start one
+        // character short of it and skip what sorts before the prefix.
+        let cursor = prefix.slice(0, -1);
+        for (;;) {
+            const page = await archive.listExecutions({ cursor, limit: 200 });
+            let past = false;
+            for (const id of page.executionIds) {
+                if (!id.startsWith(prefix)) {
+                    if ((0, executionIdOrder_1.compareExecutionIds)(id, prefix) < 0)
+                        continue;
+                    past = true;
+                    break;
+                }
+                if ((0, types_1.isReservedStream)(id) && (0, types_1.archiveChainOf)(id) === chainId)
+                    found.push(id);
+            }
+            if (past || page.nextCursor === undefined || page.nextCursor === cursor)
+                break;
+            cursor = page.nextCursor;
+        }
+    }
+    return found;
+}
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

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

package/dist/archiveSpi.d.ts

@@ -0,0 +1,165 @@
+import type { EventEnvelope } from "@loomwork/core";
+/**
+ * SPI version of {@link ArchiveStore} (ADR 0138). Pinned by `runArchiveStoreConformance`.
+ *
+ * 1.0.0: `append` / `headers` / `read` / `listExecutions` (paged) / optional `deleteExecution` /
+ * `close`; every segment header carries the log `incarnation` it belongs to and an optional `kind`.
+ *
+ * 1.1.0 (ADR 0139 N1/N7, additive): the optional `replaceSegments(key, expected, next)`, an ATOMIC
+ * compare-and-swap of a key's whole segment list (a concurrent `append` makes it fail with
+ * {@link ArchiveConflictError}; nothing is written), and the optional header field `senderDigest`
+ * (a digest of the senders of a PLAINTEXT reserved-stream segment, which the digest itself masks). A
+ * 1.0.0 store conforms; the erasure that needs `replaceSegments` refuses an archive without it.
+ */
+export declare const ARCHIVE_STORE_SPI_VERSION = "1.1.0";
+/**
+ * What a segment holds. Absent / `"events"`: the exact envelopes a compaction removed. `"legacy-checkpoint"`:
+ * ONE synthetic envelope carrying a checkpoint (snapshot) written before the archive existed, byte-exact:
+ * its folded state is the only copy of the settled steps' inputs the pre-0138 compactions removed.
+ */
+export type ArchiveSegmentKind = "events" | "legacy-checkpoint";
+/** The `eventType` of the synthetic envelope inside a `"legacy-checkpoint"` segment. */
+export declare const ARCHIVE_LEGACY_CHECKPOINT_EVENT = "ARCHIVE_LEGACY_CHECKPOINT";
+/** What a segment says about itself without its envelopes. */
+export interface ArchiveSegmentHeader {
+    /** The lowest sequence this segment covers (inclusive). */
+    readonly from: number;
+    /** The highest sequence it covers (inclusive): the compaction checkpoint's sequence. */
+    readonly through: number;
+    /** How many envelopes it holds (sequences inside `[from, through]` a compaction kept are absent). */
+    readonly count: number;
+    /** {@link segmentDigest} of the envelopes, in order. Stored and returned verbatim. */
+    readonly digest: string;
+    /**
+     * The incarnation of the log this segment came from: the {@link segmentDigest} of its bootstrap
+     * event (sequence 0, which survives every compaction; the id alone is `<executionId>-0` and says
+     * nothing). A segment of another incarnation under the same execution id (an id REUSED after a
+     * delete) is refused with {@link ArchiveIncarnationError}, never inherited. Two runs whose
+     * bootstrap envelopes are byte-identical (same input, same millisecond) are not told apart here;
+     * their later events then disagree, which the compaction and the audit read catch byte-for-byte.
+     */
+    readonly incarnation: string;
+    /** Absent means `"events"`. Stored and returned verbatim. */
+    readonly kind?: ArchiveSegmentKind;
+    /**
+     * SPI 1.1.0 (ADR 0139 N7), PLAINTEXT reserved-stream segments only: the sender digest of the
+     * envelopes' senders. The segment `digest` masks `payload.sender` (an erasure may redact it), so
+     * without this the sender field would have no bit-rot detection; a redaction recomputes it in the same
+     * atomic {@link ArchiveStore.replaceSegments}. Stored and returned verbatim; absent on every other segment
+     * (a sealing archive authenticates the sender with AEAD instead and never stores it).
+     */
+    readonly senderDigest?: string;
+}
+/** One contiguous range of removed envelopes. */
+export interface ArchiveSegment extends ArchiveSegmentHeader {
+    /** The exact envelopes the log held, ascending by sequence. */
+    readonly envelopes: readonly EventEnvelope[];
+    /**
+     * Opaque sealed form. A sealing decorator (`EncryptingArchiveStore`) stores its ciphertext here
+     * and an EMPTY `envelopes`; a plain backend persists it verbatim and never looks inside.
+     */
+    readonly sealed?: unknown;
+}
+/**
+ * Where compaction puts the events it removes (ADR 0138). Append-only: there is no per-segment
+ * delete, only {@link ArchiveStore.deleteExecution} for the existing whole-execution retention path.
+ *
+ * Contract (pinned by the conformance kit):
+ *  - `append` is IDEMPOTENT for an identical segment (same `from`, `through`, `digest`): a crash
+ *    between "archive" and "truncate" is retried by re-compaction, and the retry must not fail.
+ *  - Any other segment must start strictly after the last one's `through`; an overlap or a rewind
+ *    rejects with {@link ArchiveConflictError} and writes NOTHING.
+ *  - `headers` and `read` return segments in ascending `from`. `read` returns every segment that
+ *    overlaps the range, WHOLE (the caller trims), exactly what was appended.
+ *  - An unknown execution reads as `[]`.
+ */
+export interface ArchiveStore {
+    append(executionId: string, segment: ArchiveSegment): Promise<void>;
+    /** The segment headers, ascending. Cheap: no envelopes are read. */
+    headers(executionId: string): Promise<ArchiveSegmentHeader[]>;
+    /**
+     * One page of the execution ids that hold at least one segment, ascending in code point order,
+     * keyset-paged like `EventStore.listExecutionsPage`: pass the previous page's `nextCursor`
+     * (exclusive); no `nextCursor` means the end. Lets a sweep enumerate what the archive cites.
+     */
+    listExecutions(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<ArchiveExecutionPage>;
+    read(executionId: string, range?: {
+        readonly from?: number;
+        readonly through?: number;
+    }): Promise<ArchiveSegment[]>;
+    /** OPTIONAL. The whole-execution delete of the retention path (`LogLifecycle.applyRetention`). */
+    deleteExecution?(executionId: string): Promise<void>;
+    /**
+     * OPTIONAL (SPI 1.1.0, ADR 0139 N1). Atomically replace ALL of `executionId`'s segments with `next`, IF
+     * its current headers are exactly `expected` (ascending, as {@link ArchiveStore.headers} returned
+     * them, `senderDigest` included): one compare-and-swap, so a concurrent writer (a trim on another node
+     * appending a segment after the caller read) makes it reject with {@link ArchiveConflictError} and
+     * write NOTHING, and the caller re-reads and retries. Used by erasure to redact a sender in place; the
+     * `next` segments must be ascending and non-overlapping, and of the incarnation `expected` holds.
+     */
+    replaceSegments?(executionId: string, expected: readonly ArchiveSegmentHeader[], next: readonly ArchiveSegment[]): Promise<void>;
+    close(): Promise<void>;
+}
+/** One page of {@link ArchiveStore.listExecutions}. */
+export interface ArchiveExecutionPage {
+    readonly executionIds: string[];
+    readonly nextCursor?: string;
+}
+/** The names of the OPTIONAL {@link ArchiveStore} methods, for the decorator plan. */
+export declare const OPTIONAL_ARCHIVE_STORE_METHODS: readonly ["deleteExecution", "replaceSegments"];
+/** A segment that overlaps or rewinds past what the archive already holds (nothing was written). */
+export declare class ArchiveConflictError extends Error {
+    readonly executionId: string;
+    readonly attempted: ArchiveSegmentHeader;
+    readonly lastThrough: number;
+    /** Set by {@link ArchiveStore.replaceSegments}: why the compare-and-swap failed. */
+    readonly replaceReason?: string | undefined;
+    readonly retryable = false;
+    constructor(executionId: string, attempted: ArchiveSegmentHeader, lastThrough: number, 
+    /** Set by {@link ArchiveStore.replaceSegments}: why the compare-and-swap failed. */
+    replaceReason?: string | undefined);
+}
+/**
+ * The archive holds segments of another incarnation of this execution id (the id was deleted and
+ * REUSED): appending to or reading them as this run's history would mix two runs. Nothing was
+ * written. Never retryable.
+ */
+export declare class ArchiveIncarnationError extends Error {
+    readonly executionId: string;
+    readonly archived: string;
+    readonly current: string;
+    readonly retryable = false;
+    constructor(executionId: string, archived: string, current: string);
+}
+/** A segment's envelopes cannot be serialized to JSON (circular, BigInt, too deep): it cannot be archived or verified. */
+export declare class ArchiveUnserializableError extends Error {
+    readonly retryable = false;
+    constructor(cause: unknown);
+}
+/** The envelopes of a segment do not hash to the digest it recorded: the archive was altered. */
+export declare class ArchiveDigestError extends Error {
+    readonly executionId: string;
+    readonly from: number;
+    readonly through: number;
+    readonly expected: string;
+    readonly actual: string;
+    readonly retryable = false;
+    constructor(executionId: string, from: number, through: number, expected: string, actual: string);
+}
+export declare const headerOf: (s: ArchiveSegmentHeader) => ArchiveSegmentHeader;
+/**
+ * The shared `replaceSegments` rule for a backend, given the headers stored now: throws
+ * {@link ArchiveConflictError} unless they are exactly `expected`, and a `RangeError` for a `next` list
+ * that is not ascending, non-overlapping and well-formed. Nothing is written by this check.
+ */
+export declare function assertReplaceable(executionId: string, stored: readonly ArchiveSegmentHeader[], expected: readonly ArchiveSegmentHeader[], next: readonly ArchiveSegmentHeader[]): void;
+/**
+ * The shared `append` rule for a backend, given the headers already stored (ascending): `"noop"`
+ * for an exact repeat of a stored segment, `"append"` when the segment starts after the last one,
+ * else throws {@link ArchiveConflictError}.
+ */
+export declare function classifyAppend(executionId: string, stored: readonly ArchiveSegmentHeader[], segment: ArchiveSegmentHeader): "append" | "noop";
+//# sourceMappingURL=archiveSpi.d.ts.map

package/dist/archiveSpi.d.ts.map

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

package/dist/archiveSpi.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.headerOf = exports.ArchiveDigestError = exports.ArchiveUnserializableError = exports.ArchiveIncarnationError = exports.ArchiveConflictError = exports.OPTIONAL_ARCHIVE_STORE_METHODS = exports.ARCHIVE_LEGACY_CHECKPOINT_EVENT = exports.ARCHIVE_STORE_SPI_VERSION = void 0;
+exports.assertReplaceable = assertReplaceable;
+exports.classifyAppend = classifyAppend;
+// ── ADR 0138 — the compaction archive SPI ────────────────────────────────────────────────────────
+//
+// `LogLifecycle.compact` removes the prefix of a log below its checkpoint. Under ADR 0138 it MOVES
+// that prefix: the removed envelopes are appended here first, then truncated. Nothing in loom
+// deletes a fact the log held, so an auditor can recover `archive ∪ surviving log == original log`.
+//
+// The archive is deliberately NOT an EventStore and NOT the content store: `readRange` of the log
+// never sees it (replay and resume cannot read it), no sweep enumerates it, and per-subject erasure
+// is a property of ONE store (a sealing wrapper over the same KeyStore as the event store).
+/**
+ * SPI version of {@link ArchiveStore} (ADR 0138). Pinned by `runArchiveStoreConformance`.
+ *
+ * 1.0.0: `append` / `headers` / `read` / `listExecutions` (paged) / optional `deleteExecution` /
+ * `close`; every segment header carries the log `incarnation` it belongs to and an optional `kind`.
+ *
+ * 1.1.0 (ADR 0139 N1/N7, additive): the optional `replaceSegments(key, expected, next)`, an ATOMIC
+ * compare-and-swap of a key's whole segment list (a concurrent `append` makes it fail with
+ * {@link ArchiveConflictError}; nothing is written), and the optional header field `senderDigest`
+ * (a digest of the senders of a PLAINTEXT reserved-stream segment, which the digest itself masks). A
+ * 1.0.0 store conforms; the erasure that needs `replaceSegments` refuses an archive without it.
+ */
+exports.ARCHIVE_STORE_SPI_VERSION = "1.1.0";
+/** The `eventType` of the synthetic envelope inside a `"legacy-checkpoint"` segment. */
+exports.ARCHIVE_LEGACY_CHECKPOINT_EVENT = "ARCHIVE_LEGACY_CHECKPOINT";
+/** The names of the OPTIONAL {@link ArchiveStore} methods, for the decorator plan. */
+exports.OPTIONAL_ARCHIVE_STORE_METHODS = ["deleteExecution", "replaceSegments"];
+/** A segment that overlaps or rewinds past what the archive already holds (nothing was written). */
+class ArchiveConflictError extends Error {
+    executionId;
+    attempted;
+    lastThrough;
+    replaceReason;
+    retryable = false;
+    constructor(executionId, attempted, lastThrough, 
+    /** Set by {@link ArchiveStore.replaceSegments}: why the compare-and-swap failed. */
+    replaceReason) {
+        super(replaceReason !== undefined
+            ? `archive "${executionId}": replaceSegments refused - ${replaceReason}. Nothing was written; re-read the headers and retry.`
+            : `archive "${executionId}": segment [${attempted.from}..${attempted.through}] does not start after the archive's last sequence ${lastThrough}, and is not an exact repeat of an archived segment. Segments are append-only and contiguous; nothing was written.`);
+        this.executionId = executionId;
+        this.attempted = attempted;
+        this.lastThrough = lastThrough;
+        this.replaceReason = replaceReason;
+        this.name = "ArchiveConflictError";
+        Object.setPrototypeOf(this, ArchiveConflictError.prototype);
+    }
+}
+exports.ArchiveConflictError = ArchiveConflictError;
+/**
+ * The archive holds segments of another incarnation of this execution id (the id was deleted and
+ * REUSED): appending to or reading them as this run's history would mix two runs. Nothing was
+ * written. Never retryable.
+ */
+class ArchiveIncarnationError extends Error {
+    executionId;
+    archived;
+    current;
+    retryable = false;
+    constructor(executionId, archived, current) {
+        super(`archive "${executionId}": the archive holds segments of a DIFFERENT run (incarnation ${archived}) than the log's (${current}) — the execution id was reused after its earlier run was deleted. The old run's archive was not removed with it, so it is not this run's history and is neither read as such nor extended. Remove the previous run's segments with the retention path (ArchiveStore.deleteExecution), or use a fresh execution id.`);
+        this.executionId = executionId;
+        this.archived = archived;
+        this.current = current;
+        this.name = "ArchiveIncarnationError";
+        Object.setPrototypeOf(this, ArchiveIncarnationError.prototype);
+    }
+}
+exports.ArchiveIncarnationError = ArchiveIncarnationError;
+/** A segment's envelopes cannot be serialized to JSON (circular, BigInt, too deep): it cannot be archived or verified. */
+class ArchiveUnserializableError extends Error {
+    retryable = false;
+    constructor(cause) {
+        super(`archive: the envelopes cannot be serialized to JSON (${cause instanceof Error ? cause.message : String(cause)}) — an archived event must be plain JSON data, byte-exact.`, { cause });
+        this.name = "ArchiveUnserializableError";
+        Object.setPrototypeOf(this, ArchiveUnserializableError.prototype);
+    }
+}
+exports.ArchiveUnserializableError = ArchiveUnserializableError;
+/** The envelopes of a segment do not hash to the digest it recorded: the archive was altered. */
+class ArchiveDigestError extends Error {
+    executionId;
+    from;
+    through;
+    expected;
+    actual;
+    retryable = false;
+    constructor(executionId, from, through, expected, actual) {
+        super(`archive "${executionId}": segment [${from}..${through}] does not match its recorded digest (expected ${expected}, computed ${actual}) — the archived events were altered or corrupted.`);
+        this.executionId = executionId;
+        this.from = from;
+        this.through = through;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "ArchiveDigestError";
+        Object.setPrototypeOf(this, ArchiveDigestError.prototype);
+    }
+}
+exports.ArchiveDigestError = ArchiveDigestError;
+const headerOf = (s) => ({
+    from: s.from,
+    through: s.through,
+    count: s.count,
+    digest: s.digest,
+    incarnation: s.incarnation,
+    ...(s.kind !== undefined && { kind: s.kind }),
+    ...(s.senderDigest !== undefined && { senderDigest: s.senderDigest }),
+});
+exports.headerOf = headerOf;
+const sameHeader = (a, b) => a.from === b.from &&
+    a.through === b.through &&
+    a.count === b.count &&
+    a.digest === b.digest &&
+    a.incarnation === b.incarnation &&
+    (a.kind ?? "events") === (b.kind ?? "events") &&
+    (a.senderDigest ?? null) === (b.senderDigest ?? null);
+/**
+ * The shared `replaceSegments` rule for a backend, given the headers stored now: throws
+ * {@link ArchiveConflictError} unless they are exactly `expected`, and a `RangeError` for a `next` list
+ * that is not ascending, non-overlapping and well-formed. Nothing is written by this check.
+ */
+function assertReplaceable(executionId, stored, expected, next) {
+    const attempted = next[0] ?? expected[0] ?? stored[0] ?? { from: 0, through: 0 };
+    const last = stored[stored.length - 1]?.through ?? -1;
+    if (stored.length !== expected.length) {
+        throw new ArchiveConflictError(executionId, attempted, last, `the key now holds ${stored.length} segment(s), the caller read ${expected.length}`);
+    }
+    for (let i = 0; i < stored.length; i++) {
+        if (!sameHeader(stored[i], expected[i])) {
+            throw new ArchiveConflictError(executionId, attempted, last, `segment ${i} [${stored[i].from}..${stored[i].through}] changed since the caller read it`);
+        }
+    }
+    let prev = Number.NEGATIVE_INFINITY;
+    for (const h of next) {
+        if (!Number.isSafeInteger(h.from) || !Number.isSafeInteger(h.through) || h.from > h.through) {
+            throw new RangeError(`archive segment [${h.from}..${h.through}] is malformed`);
+        }
+        if (h.from <= prev) {
+            throw new RangeError(`replaceSegments: segments must be ascending and non-overlapping ([${h.from}..${h.through}] follows ${prev})`);
+        }
+        prev = h.through;
+    }
+    const incarnation = expected[0]?.incarnation;
+    if (incarnation !== undefined) {
+        for (const h of next) {
+            if (h.incarnation !== incarnation) {
+                throw new ArchiveIncarnationError(executionId, incarnation, h.incarnation);
+            }
+        }
+    }
+}
+/**
+ * The shared `append` rule for a backend, given the headers already stored (ascending): `"noop"`
+ * for an exact repeat of a stored segment, `"append"` when the segment starts after the last one,
+ * else throws {@link ArchiveConflictError}.
+ */
+function classifyAppend(executionId, stored, segment) {
+    if (!Number.isSafeInteger(segment.from) || !Number.isSafeInteger(segment.through)) {
+        throw new RangeError("archive segment bounds must be safe integers");
+    }
+    if (segment.from > segment.through) {
+        throw new RangeError(`archive segment [${segment.from}..${segment.through}] is inverted`);
+    }
+    for (const h of stored) {
+        if (h.incarnation !== segment.incarnation) {
+            throw new ArchiveIncarnationError(executionId, h.incarnation, segment.incarnation);
+        }
+    }
+    for (const h of stored) {
+        if (h.from === segment.from && h.through === segment.through && h.digest === segment.digest) {
+            return "noop";
+        }
+    }
+    const last = stored[stored.length - 1];
+    if (last !== undefined && segment.from <= last.through) {
+        throw new ArchiveConflictError(executionId, segment, last.through);
+    }
+    return "append";
+}
+//# sourceMappingURL=archiveSpi.js.map