@engramx/client 0.15.0 → 0.16.0-rc.11

package/dist/memoryArchive.js

@@ -0,0 +1,504 @@
+// The memory log's archive surface — the client half of the engram's export → verify → condense
+// contract (ledgerfs build stage S4d: "condense refuses without an export receipt").
+//
+// WHY THIS IS MORE THAN FIVE PASSTHROUGHS. The canister's rule is that log entries may only be
+// dropped after a chain-recorded export proved they were served. That makes the SDK, not the
+// canister, the place where an owner actually ends up holding a verifiable archive — and it makes
+// every shortcut here a way to destroy evidence. Three specific ones are closed below:
+//
+//   1. A SHORT ARCHIVE THAT REPORTS ITSELF COMPLETE. `getMemoryLogPage` clamps a page and
+//      discloses the clamp through `pageCap`; a client that assumed it got `max` would walk the
+//      chain in strides longer than the canister actually served and skip whatever fell between.
+//      assembleMemoryArchive advances by the window the canister CONFIRMED, and then asserts the
+//      range came back whole. It throws rather than return a gap.
+//      ⟨2026-10-07, beside the point above — the owner's decision of that day⟩ The engram serves
+//      `listMemoryLog` now, and its page states the window directly: `items.length + withheld`
+//      entries scanned, starting at `max(startSeq, firstAvailableSeq)`. The walk advances by that,
+//      as the owner's own archive page does. `pageCap` is not served and is not read.
+//   2. A PAGE THE CANISTER CANNOT FIT IN ONE RESPONSE. A `#set`/`#restore` entry carries a full
+//      manifest — up to 40 chunk references, since maxFileBytes is 10 MiB at a frozen 256 KiB
+//      chunkSize (src/engram/LedgerFsInit.mo) — so a manifest-heavy page can exceed the 2 MiB
+//      response limit. The engram already clamps to 256 rows for this (MemoryRouter.LOG_PAGE_MAX,
+//      down from the library's 1024) and DISCLOSES the clamp as `pageCap`; the margin it leaves is
+//      an estimate, not a proof, so a rejection is retried at HALF the page size, down to a single
+//      entry, and is never allowed to end the walk early.
+//   3. AN ARCHIVE NOBODY CHECKED. verifyMemoryArchive recomputes every entry hash and rebuilds
+//      the ops root, reusing ./ledgerfsHash.ts — the same file the `ledgerfs-goldens` cross-lock
+//      pins byte-for-byte against the Motoko encoder. Nothing here reimplements hashing.
+//
+// It also states a CEILING and refuses past it. Assembling an unbounded chain into one JS array
+// is a real failure mode (see ARCHIVE_MAX_RANGE), and splitting is free: each part gets its own
+// receipt, and receipts compose — condense only needs one that covers the prefix being dropped.
+import { CanisterRefusal } from './wire.js';
+import { eventHash, opsRoot as opsRootOverEventHashes, toHex, } from './ledgerfsHash.js';
+// ⟨DELETED 2026-10-05⟩ `MemoryExportReceiptsPage` stood here: "One page of the
+// receipts-and-checkpoints ledger. `next` is the `before` cursor, null = done", with the fields
+// { receipts, checkpoints, firstAvailableSeq, totalEvents, scannedFromSeq, scanTruncated, next }.
+// The 0.16.0 cut split that reply in two. `listMemoryExportReceipts` answers
+// `ReceiptPage = { firstAvailableSeq; page : { items : vec ExportReceiptRow; total; withheld };
+// scannedThroughSeq }`, paged forward by absolute seq, and `listCondenseCheckpoints` is the other
+// half. Six of the seven fields were therefore served by nothing, and nothing in the workspace read
+// the type. Removing the unserved fields would have left a one-field shell, so the type is gone.
+// The rows survive (`MemoryExportReceiptRow`, `MemoryCheckpointRow` above) because they DO mirror
+// the items both lists serve.
+// ── Ceilings ───────────────────────────────────────────────────────────────────────────────────
+/**
+ * How many log entries one assembled archive may span.
+ *
+ * A `#set` entry carries a full manifest, and maxFileBytes / chunkSize = 10 MiB / 256 KiB caps a
+ * manifest at 40 chunk references (src/engram/LedgerFsInit.mo) — several kilobytes of decoded JS
+ * objects for a single entry. Ten thousand of those is already past what a browser tab should
+ * hold, and an owner who runs out of memory mid-walk gets no archive AND no receipt.
+ *
+ * The ceiling is on the RANGE WIDTH, not on the entries kept, so an author-filtered archive is
+ * bounded by the same number: the range is what drives the round trips, and the range is what a
+ * receipt attests. Splitting costs nothing — each part gets its own receipt, and condense needs
+ * only one receipt covering the prefix it drops.
+ */
+export const ARCHIVE_MAX_RANGE = 10000n;
+/**
+ * Entries requested per page before any clamp.
+ *
+ * Set to the engram's own cap (`MemoryRouter.LOG_PAGE_MAX`, 256) so a full page is never left
+ * half-used — the engram clamps the ask to that number anyway and reports the result as
+ * `pageCap`. Asking for the cap is safe rather than optimistic because the fallback below it is
+ * real: a page that will not fit is retried at half the size, and a walk that had to shrink says
+ * so through `smallestPageUsed`.
+ * ⟨2026-10-07, beside "reports the result as `pageCap`"⟩ It reports the window it scanned as
+ * `items.length + withheld` now; `pageCap` is not served.
+ */
+export const ARCHIVE_PAGE_EVENTS = 256n;
+// ── Byte/shape normalization ───────────────────────────────────────────────────────────────────
+// The agent decodes `vec nat8` as a Uint8Array, but a hand-built stub (or an older agent) can
+// hand back a plain number[]. Copying once here means every hash input downstream is the shape
+// ledgerfsHash expects, and a wrong shape fails at the boundary instead of producing a digest
+// over the wrong bytes.
+const asBytes = (v) => v instanceof Uint8Array ? v : Uint8Array.from(v);
+const rawPrincipal = (p) => p.toUint8Array();
+function toHashManifest(m) {
+    return {
+        chunks: m.chunks.map((c) => ({
+            hash: asBytes(c.hash),
+            size: c.size,
+            birthSeq: c.birthSeq,
+        })),
+        totalSize: m.totalSize,
+        contentRoot: asBytes(m.contentRoot),
+    };
+}
+function toHashImportNote(n) {
+    if ('genesis' in n) {
+        const b = n.genesis.boundTo;
+        return { kind: 'genesis', boundTo: b.length === 0 ? null : asBytes(b[0]) };
+    }
+    if ('legacyGap' in n)
+        return { kind: 'legacyGap', firstSurviving: n.legacyGap.firstSurviving };
+    if ('legacyTruncated' in n) {
+        return {
+            kind: 'legacyTruncated',
+            storedBytes: n.legacyTruncated.storedBytes,
+            prefixHash: asBytes(n.legacyTruncated.prefixHash),
+        };
+    }
+    if ('legacyDelete' in n)
+        return { kind: 'legacyDelete' };
+    if ('legacyUnreconstructable' in n) {
+        return {
+            kind: 'legacyUnreconstructable',
+            contentHash: asBytes(n.legacyUnreconstructable.contentHash),
+            reason: n.legacyUnreconstructable.reason,
+        };
+    }
+    // Not reachable through Candid: the decoder rejects a tag the IDL does not declare, so an
+    // unknown note here means the wire shape was hand-built. Refuse rather than hash a guess.
+    throw new Error(`Unrecognized import note in a log entry: ${JSON.stringify(Object.keys(n))}`);
+}
+function toHashOp(op) {
+    if ('append' in op) {
+        return {
+            kind: 'append',
+            deltaHash: asBytes(op.append.deltaHash),
+            deltaSize: op.append.deltaSize,
+            newSize: op.append.newSize,
+        };
+    }
+    if ('set' in op)
+        return { kind: 'set', manifest: toHashManifest(op.set.manifest) };
+    if ('restore' in op) {
+        return {
+            kind: 'restore',
+            toVersion: op.restore.toVersion,
+            manifest: toHashManifest(op.restore.manifest),
+        };
+    }
+    if ('tombstone' in op)
+        return { kind: 'tombstone' };
+    if ('evict' in op) {
+        return {
+            kind: 'evict',
+            fromVersion: op.evict.fromVersion,
+            toVersion: op.evict.toVersion,
+            chunkCount: op.evict.chunkCount,
+            byteCount: op.evict.byteCount,
+            evictedRoot: asBytes(op.evict.evictedRoot),
+        };
+    }
+    if ('condense' in op) {
+        return {
+            kind: 'condense',
+            fromSeq: op.condense.fromSeq,
+            toSeq: op.condense.toSeq,
+            opCount: op.condense.opCount,
+            opsRoot: asBytes(op.condense.opsRoot),
+            headAtBoundary: asBytes(op.condense.headAtBoundary),
+        };
+    }
+    if ('exported' in op) {
+        const f = op.exported.authorFilter;
+        return {
+            kind: 'exported',
+            fromSeq: op.exported.fromSeq,
+            toSeq: op.exported.toSeq,
+            opsRoot: asBytes(op.exported.opsRoot),
+            authorFilterRaw: f.length === 0 ? null : rawPrincipal(f[0]),
+        };
+    }
+    if ('imported' in op)
+        return { kind: 'imported', note: toHashImportNote(op.imported) };
+    throw new Error(`Unrecognized operation in a log entry: ${JSON.stringify(Object.keys(op))}`);
+}
+/**
+ * A decoded log entry in the form the frozen hash contract operates on.
+ *
+ * The store-global sentinel substitution (`#condense`/`#exported` hash with an empty path, zero
+ * version, zero size and a zero content root) is NOT applied here — ledgerfsHash owns it, in the
+ * one place the Motoko encoder is mirrored. Doing it twice is how the two drift.
+ */
+export function toLedgerFsEvent(e) {
+    return {
+        seq: e.seq,
+        path: e.path,
+        version: e.version,
+        op: toHashOp(e.op),
+        byRaw: rawPrincipal(e.by),
+        at: e.atNs,
+        size: e.size,
+        contentRoot: asBytes(e.contentRoot),
+        prev: asBytes(e.prev),
+    };
+}
+/** The canonical hash of one log entry, recomputed from its decoded fields. */
+export const memoryLogEventHash = (e) => eventHash(toLedgerFsEvent(e));
+/**
+ * Whether a failed page looks like the engram could not fit the response, as opposed to refusing
+ * the call.
+ *
+ * Deliberately STRICT. Halving on every error would spend six round trips turning an
+ * authorization refusal into the same refusal, and would report it under a misleading heading;
+ * an unmatched error is rethrown with the cursor attached instead. If a new replica wording slips
+ * past this, the archive fails LOUDLY — the walk stops and throws — which is the safe direction:
+ * the alternative is an archive that is quietly short.
+ */
+export function isResponseTooLarge(err) {
+    // A client-side allocation failure is the same class of problem from the owner's side: the
+    // page was too big to hold. Halving is the same remedy.
+    if (err instanceof RangeError)
+        return true;
+    const text = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+    return /payload size|response size|message size|response is too large|too large|exceeds[^.]{0,60}\b(size|limit|maximum)\b|IC0504/i.test(text);
+}
+const asBig = (v) => (typeof v === 'bigint' ? v : BigInt(v));
+/**
+ * Walk a range of the memory log into one archive, or throw.
+ *
+ * WHAT IT REFUSES TO DO, in order of how badly each would hurt:
+ *  - report a short archive as whole (every seq in an unfiltered range is asserted present);
+ *  - assume it received `max` entries (it advances by the window the engram confirmed via
+ *    `pageCap`, and by the highest seq actually returned when that is further);
+ *  - give up on a page the engram could not fit (halves and retries, down to one entry);
+ *  - start below the retained floor (a condensed prefix is unattestable, so an explicit request
+ *    for it is refused rather than silently raised);
+ *  - assemble more than {@link ARCHIVE_MAX_RANGE} entries in one pass.
+ * ⟨2026-10-07, beside the second point — the owner's decision of that day⟩ The window the engram
+ * confirmed is `page.items.length + page.withheld` now — the entries it scanned for the page,
+ * starting at `max(startSeq, firstAvailableSeq)` — the rule the engram's own `listMemoryLog` doc
+ * states and the owner's archive page walks by. Two refusals join the list: a page whose window is
+ * EMPTY while the range still has entries to serve (the walk would spin, or end short), and a floor
+ * that rises above the cursor mid-walk (a condense ran during the walk, and what it dropped can no
+ * longer be served or attested).
+ *
+ * Termination is structural: the cursor advances by at least one seq per successful page, and the
+ * page size strictly halves per size failure until it reaches one.
+ */
+export async function assembleMemoryArchive(fetchPage, options = {}) {
+    const authorFilter = options.authorFilter;
+    const filterArg = authorFilter === undefined ? [] : [authorFilter];
+    const explicitFrom = options.fromSeq === undefined ? null : asBig(options.fromSeq);
+    const explicitTo = options.toSeq === undefined ? null : asBig(options.toSeq);
+    if (explicitFrom !== null && explicitFrom < 1n) {
+        throw new Error('assembleMemoryArchive: fromSeq starts at 1 — the log has no entry 0.');
+    }
+    const requestedStart = explicitFrom ?? 1n;
+    let requested = options.pageEvents === undefined ? ARCHIVE_PAGE_EVENTS : asBig(options.pageEvents);
+    if (requested < 1n)
+        requested = 1n;
+    // Only ever decreases: the fallback shrinks the page and never grows it back, so one oversized
+    // page slows the rest of the walk rather than re-triggering the same rejection every stride.
+    let smallestPageUsed = requested;
+    const ceiling = (() => {
+        if (options.maxRange === undefined)
+            return ARCHIVE_MAX_RANGE;
+        const asked = asBig(options.maxRange);
+        if (asked < 1n)
+            return 1n;
+        return asked < ARCHIVE_MAX_RANGE ? asked : ARCHIVE_MAX_RANGE;
+    })();
+    const bySeq = new Map();
+    let cursor = requestedStart;
+    let fromSeq = requestedStart;
+    let toSeq = explicitTo;
+    let pagesFetched = 0;
+    // Set from the first page and refreshed by every one after it. No placeholder value: an
+    // uninitialized read would be a bug, and a stand-in zero head or zero total is exactly the
+    // fabricated reading this whole surface exists to avoid.
+    let head;
+    let totalEvents;
+    let firstAvailableSeq;
+    let firstPage = true;
+    for (;;) {
+        // Where THIS request started. Held separately from `cursor` because the first page can move
+        // `fromSeq` up to the retained floor, and the stride must still be measured from where the
+        // engram actually began scanning — not from a raised cursor, which would jump a whole window
+        // past entries the very page in hand did not reach.
+        const pageStart = cursor;
+        let reply;
+        try {
+            reply = await fetchPage(pageStart, requested, filterArg);
+        }
+        catch (err) {
+            if (!isResponseTooLarge(err)) {
+                const why = err instanceof Error ? err.message : String(err);
+                throw new Error(`assembleMemoryArchive: the engram refused the page at seq ${pageStart} (${requested} entries): ${why}. Nothing was assembled.`, { cause: err });
+            }
+            if (requested <= 1n) {
+                const why = err instanceof Error ? err.message : String(err);
+                throw new Error(`assembleMemoryArchive: log entry ${pageStart} could not be served even one at a time: ${why}. The archive stops here rather than skipping it — export the ranges either side of ${pageStart} separately and report this entry.`, { cause: err });
+            }
+            requested = requested / 2n; // bigint division floors; requested > 1 here, so it drops
+            if (requested < 1n)
+                requested = 1n;
+            if (requested < smallestPageUsed)
+                smallestPageUsed = requested;
+            continue;
+        }
+        // A typed refusal is the engram's answer, not a transport failure: it is never halved into
+        // (halving an authorization refusal would spend six round trips arriving at the same answer).
+        if ('Err' in reply) {
+            const refusal = new CanisterRefusal('listMemoryLog', reply.Err);
+            throw new Error(`assembleMemoryArchive: the engram refused the page at seq ${pageStart} (${requested} entries): ${refusal.message}. Nothing was assembled.`, { cause: refusal });
+        }
+        const page = reply.Ok;
+        pagesFetched += 1;
+        head = asBytes(page.head);
+        totalEvents = page.page.total;
+        firstAvailableSeq = page.firstAvailableSeq;
+        if (firstPage) {
+            firstPage = false;
+            if (page.firstAvailableSeq > pageStart) {
+                if (explicitFrom !== null) {
+                    throw new Error(`assembleMemoryArchive: entries below seq ${page.firstAvailableSeq} were condensed away and can no longer be served, so a range starting at ${explicitFrom} cannot be attested. Start at ${page.firstAvailableSeq} or later.`);
+                }
+                // Only `fromSeq` moves. The engram began scanning at the floor, and the stride below is
+                // measured from there.
+                fromSeq = page.firstAvailableSeq;
+            }
+            if (explicitTo !== null && explicitTo > page.page.total) {
+                throw new Error(`assembleMemoryArchive: the log holds ${page.page.total} entries, so seq ${explicitTo} does not exist yet.`);
+            }
+            toSeq = explicitTo ?? page.page.total;
+            // Guard BEFORE subtracting. An empty log answers total = 0 with a floor of 1, so
+            // `toSeq - fromSeq` runs backwards there; in TypeScript that yields a negative BigInt
+            // rather than trapping, which would silently size the ceiling check the wrong way round.
+            const width = toSeq < fromSeq ? 0n : toSeq - fromSeq + 1n;
+            if (width === 0n) {
+                return {
+                    events: [],
+                    fromSeq,
+                    toSeq,
+                    authorFilter: authorFilter ?? null,
+                    totalEvents,
+                    firstAvailableSeq,
+                    head,
+                    pagesFetched,
+                    smallestPageUsed,
+                };
+            }
+            if (width > ceiling) {
+                throw new Error(`assembleMemoryArchive: ${width} log entries (seq ${fromSeq}–${toSeq}) is past the ${ceiling}-entry ceiling for one archive. Export it in parts — each part gets its own receipt, and a condense only needs a receipt covering the prefix it drops.`);
+            }
+        }
+        else if (page.firstAvailableSeq > pageStart) {
+            // The floor rose above the cursor between two pages: a condense ran during the walk, and the
+            // engram clamped this page UP past entries the range still needs. They can no longer be
+            // served, so the range cannot be attested; a filtered walk would otherwise skip them without
+            // noticing. Refused, rather than returned short.
+            throw new Error(`assembleMemoryArchive: entries below seq ${page.firstAvailableSeq} were condensed away while the walk was at seq ${pageStart}, so seq ${pageStart}–${page.firstAvailableSeq - 1n} can no longer be served. Nothing is returned — walk the range again from ${page.firstAvailableSeq}.`);
+        }
+        // THE WINDOW IS THE CURSOR, and the page states it: the entries the engram scanned for this
+        // page, `items.length + withheld`, starting at max(pageStart, the floor). Never the rows alone
+        // — an author filter makes a page short or empty while the chain continues, and striding by
+        // the rows returned would skip every entry the filter removed and stall outright on an empty
+        // page; `withheld` is what the filter removed, so the sum is the scan.
+        const window = BigInt(page.page.items.length) + page.page.withheld;
+        if (window === 0n) {
+            // Nothing scanned at a cursor the range still covers (cursor <= toSeq <= total): the engram
+            // served nothing for entries that exist. Advancing would spin; stopping would return short.
+            throw new Error(`assembleMemoryArchive: the engram scanned no entries at seq ${pageStart} while the log holds ${page.page.total}, so seq ${pageStart}–${toSeq} came back empty. A short archive is not an archive — nothing is returned.`);
+        }
+        let highestSeen = null;
+        for (const e of page.page.items) {
+            if (highestSeen === null || e.seq > highestSeen)
+                highestSeen = e.seq;
+            if (e.seq < fromSeq || e.seq > toSeq)
+                continue; // an overshooting window, not an error
+            if (!bySeq.has(e.seq))
+                bySeq.set(e.seq, e);
+        }
+        // Advance past the window that was actually covered. A request below the retained floor is
+        // clamped UP by the engram, so the window began at max(pageStart, floor). The last clause is
+        // belt-and-braces: if a page ever returns an entry beyond the window it declared, the cursor
+        // still ends up past it. Every clause only raises the cursor, so the walk always moves.
+        const windowStart = pageStart < page.firstAvailableSeq ? page.firstAvailableSeq : pageStart;
+        let next = windowStart + window;
+        if (highestSeen !== null && highestSeen + 1n > next)
+            next = highestSeen + 1n;
+        cursor = next;
+        if (cursor > toSeq)
+            break;
+    }
+    const events = [...bySeq.values()].sort((a, b) => (a.seq < b.seq ? -1 : a.seq > b.seq ? 1 : 0));
+    // The anti-fail-to-empty assertion. Only an UNFILTERED archive can be checked this way: with a
+    // filter, the engram is expected to skip entries, and the client has no way to know which. What
+    // holds in both cases is that every window covering [fromSeq, toSeq] was requested, which the
+    // loop above guarantees by construction — and, since 0.16.0, that every window it covered was
+    // counted by the engram itself (`withheld`).
+    if (authorFilter === undefined) {
+        let expect = fromSeq;
+        for (const e of events) {
+            if (e.seq !== expect) {
+                throw new Error(`assembleMemoryArchive: the walk of seq ${fromSeq}–${toSeq} came back missing entry ${expect} (next entry served was ${e.seq}). A short archive is not an archive — nothing is returned.`);
+            }
+            expect += 1n;
+        }
+        if (expect !== toSeq + 1n) {
+            throw new Error(`assembleMemoryArchive: the walk of seq ${fromSeq}–${toSeq} stopped after entry ${expect - 1n}. A short archive is not an archive — nothing is returned.`);
+        }
+    }
+    return {
+        events,
+        fromSeq,
+        toSeq: toSeq,
+        authorFilter: authorFilter ?? null,
+        totalEvents,
+        firstAvailableSeq,
+        head,
+        pagesFetched,
+        smallestPageUsed,
+    };
+}
+const bytesEqual = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+};
+/**
+ * Rebuild the ops root over a set of log entries exactly as the engram does: the entries in
+ * `[fromSeq, toSeq]` that pass the author filter, in ascending seq order, each hashed with
+ * ledgerfsHash and wrapped as an ops leaf.
+ *
+ * An empty covered set has a DEFINED root — the honest attestation that this author wrote nothing
+ * in the range — so it is computed, never special-cased into a failure.
+ */
+export function recomputeOpsRoot(events, range) {
+    const filter = range.authorFilter && range.authorFilter.length === 1 ? range.authorFilter[0] : null;
+    const filterText = filter === null ? null : filter.toText();
+    const covered = events
+        .filter((e) => e.seq >= range.fromSeq && e.seq <= range.toSeq)
+        .filter((e) => filterText === null || e.by.toText() === filterText)
+        .sort((a, b) => (a.seq < b.seq ? -1 : a.seq > b.seq ? 1 : 0));
+    return { root: opsRootOverEventHashes(covered.map(memoryLogEventHash)), covered };
+}
+/**
+ * Check an archive against the receipt (or checkpoint) that attests it.
+ *
+ * The hashing is ./ledgerfsHash.ts throughout — the file the `ledgerfs-goldens` cross-lock pins
+ * against the Motoko encoder. Nothing is reimplemented here, because a second implementation of
+ * the hash contract is exactly how an owner ends up being told their evidence is bad when the two
+ * copies merely drifted.
+ *
+ * Never throws on a mismatch: a mismatch is a RESULT to read, and the wording of
+ * {@link MemoryArchiveVerification.explanation} deliberately does not accuse the engram.
+ */
+export function verifyMemoryArchive(archive, attestation) {
+    const notes = [];
+    const filtered = (attestation.authorFilter?.length ?? 0) === 1;
+    const { root, covered } = recomputeOpsRoot(archive.events, attestation);
+    const attested = asBytes(attestation.opsRoot);
+    const matches = bytesEqual(root, attested);
+    // Guard before subtracting: an inverted range (toSeq below fromSeq) is a malformed attestation,
+    // not a width of minus one.
+    const expected = filtered || attestation.toSeq < attestation.fromSeq
+        ? null
+        : Number(attestation.toSeq - attestation.fromSeq + 1n);
+    let rangeContiguous = true;
+    if (!filtered) {
+        let expect = attestation.fromSeq;
+        for (const e of covered) {
+            if (e.seq !== expect) {
+                rangeContiguous = false;
+                notes.push(`The archive jumps from seq ${expect - 1n} to ${e.seq}; entries ${expect}–${e.seq - 1n} are not in it.`);
+                break;
+            }
+            expect += 1n;
+        }
+        if (rangeContiguous && expected !== null && covered.length !== expected) {
+            rangeContiguous = false;
+            notes.push(`The attestation covers seq ${attestation.fromSeq}–${attestation.toSeq} (${expected} entries) but the archive holds ${covered.length} of them.`);
+        }
+    }
+    else {
+        notes.push('The attestation is author-filtered, so entry count and continuity cannot be checked from the archive alone — only the ops root can be.');
+    }
+    // Linkage between ADJACENT held entries only. The first entry's `prev` points at something the
+    // archive does not hold, and checking it against nothing would be theatre.
+    let chainLinked = true;
+    for (let i = 1; i < covered.length; i++) {
+        const prev = covered[i - 1];
+        const here = covered[i];
+        if (here.seq !== prev.seq + 1n)
+            continue; // not adjacent in the chain; nothing to link
+        if (!bytesEqual(asBytes(here.prev), memoryLogEventHash(prev))) {
+            chainLinked = false;
+            notes.push(`Entry ${here.seq} does not link back to entry ${prev.seq}.`);
+            break;
+        }
+    }
+    const explanation = matches
+        ? null
+        : "The ops root recomputed from this archive is not the one the receipt records. Read that as a question, not a verdict: the common causes sit on this side of the wire — an archive missing entries, an archive assembled with a different author filter than the receipt used, or a version skew between this SDK's copy of the hash rules and the engram's. Check the counts and notes above first. If they all line up and the roots still differ, keep the archive and report both roots as they stand rather than condensing anything.";
+    return {
+        matches,
+        computedOpsRoot: toHex(root),
+        attestedOpsRoot: toHex(attested),
+        eventsCovered: covered.length,
+        eventsExpected: expected,
+        rangeContiguous,
+        chainLinked,
+        notes,
+        explanation,
+    };
+}
+//# sourceMappingURL=memoryArchive.js.map

package/dist/memoryArchive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryArchive.js","sourceRoot":"","sources":["../src/memoryArchive.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,qFAAqF;AACrF,EAAE;AACF,+FAA+F;AAC/F,6FAA6F;AAC7F,kGAAkG;AAClG,uFAAuF;AACvF,EAAE;AACF,0FAA0F;AAC1F,gGAAgG;AAChG,iGAAiG;AACjG,iGAAiG;AACjG,kEAAkE;AAClE,iGAAiG;AACjG,+FAA+F;AAC/F,mGAAmG;AACnG,sFAAsF;AACtF,gGAAgG;AAChG,8FAA8F;AAC9F,8FAA8F;AAC9F,kGAAkG;AAClG,mGAAmG;AACnG,mGAAmG;AACnG,0DAA0D;AAC1D,+FAA+F;AAC/F,iGAAiG;AACjG,yFAAyF;AACzF,EAAE;AACF,gGAAgG;AAChG,gGAAgG;AAChG,gGAAgG;AAGhG,OAAO,EAAE,eAAe,EAAmB,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,SAAS,EACT,OAAO,IAAI,sBAAsB,EACjC,KAAK,GAMN,MAAM,mBAAmB,CAAC;AA4O3B,+EAA+E;AAC/E,gGAAgG;AAChG,kGAAkG;AAClG,6EAA6E;AAC7E,gGAAgG;AAChG,kGAAkG;AAClG,oGAAoG;AACpG,iGAAiG;AACjG,kGAAkG;AAClG,8BAA8B;AAE9B,kGAAkG;AAElG;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAO,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,kGAAkG;AAElG,8FAA8F;AAC9F,+FAA+F;AAC/F,8FAA8F;AAC9F,wBAAwB;AACxB,MAAM,OAAO,GAAG,CAAC,CAAwB,EAAc,EAAE,CACvD,CAAC,YAAY,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEnD,MAAM,YAAY,GAAG,CAAC,CAAY,EAAc,EAAE,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC;AAEpE,SAAS,cAAc,CAAC,CAAoB;IAC1C,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3B,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;YACrB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,CAAC,CAAC,QAAQ;SACrB,CAAC,CAAC;QACH,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAsB;IAC9C,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;IAC9E,CAAC;IACD,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC;IAC/F,IAAI,iBAAiB,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,CAAC,CAAC,eAAe,CAAC,WAAW;YAC1C,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,UAAU,CAAC;SAClD,CAAC;IACJ,CAAC;IACD,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IACzD,IAAI,yBAAyB,IAAI,CAAC,EAAE,CAAC;QACnC,OAAO;YACL,IAAI,EAAE,yBAAyB;YAC/B,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC,WAAW,CAAC;YAC3D,MAAM,EAAE,CAAC,CAAC,uBAAuB,CAAC,MAAM;SACzC,CAAC;IACJ,CAAC;IACD,0FAA0F;IAC1F,0FAA0F;IAC1F,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAChG,CAAC;AAED,SAAS,QAAQ,CAAC,EAAe;IAC/B,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QACnB,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;YACvC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS;YAC9B,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO;SAC3B,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;IACnF,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS;YAC/B,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;SAC9C,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,IAAI,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACpD,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO;YACL,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW;YACjC,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS;YAC7B,UAAU,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU;YAC/B,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS;YAC7B,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC;SAC3C,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,IAAI,EAAE,EAAE,CAAC;QACrB,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO;YAC5B,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK;YACxB,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO;YAC5B,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;YACrC,cAAc,EAAE,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;SACpD,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,IAAI,EAAE,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;QACnC,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO;YAC5B,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK;YACxB,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;YACrC,eAAe,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;SAC7D,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,IAAI,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,gBAAgB,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;IACvF,MAAM,IAAI,KAAK,CAAC,0CAA0C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,CAAiB;IAC/C,OAAO;QACL,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAClB,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACzB,EAAE,EAAE,CAAC,CAAC,IAAI;QACV,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;QACnC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;KACtB,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAiB,EAAQ,EAAE,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AA4E7F;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,2FAA2F;IAC3F,wDAAwD;IACxD,IAAI,GAAG,YAAY,UAAU;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChF,OAAO,2HAA2H,CAAC,IAAI,CACrI,IAAI,CACL,CAAC;AACJ,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,CAAkB,EAAU,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAA+B,EAC/B,UAAkC,EAAE;IAEpC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,MAAM,SAAS,GAAqB,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACrF,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7E,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,GAAG,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,cAAc,GAAG,YAAY,IAAI,EAAE,CAAC;IAE1C,IAAI,SAAS,GACX,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACrF,IAAI,SAAS,GAAG,EAAE;QAAE,SAAS,GAAG,EAAE,CAAC;IACnC,+FAA+F;IAC/F,6FAA6F;IAC7F,IAAI,gBAAgB,GAAG,SAAS,CAAC;IAEjC,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE;QACpB,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,iBAAiB,CAAC;QAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,KAAK,GAAG,EAAE;YAAE,OAAO,EAAE,CAAC;QAC1B,OAAO,KAAK,GAAG,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC;IAC/D,CAAC,CAAC,EAAE,CAAC;IAEL,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAChD,IAAI,MAAM,GAAG,cAAc,CAAC;IAC5B,IAAI,OAAO,GAAG,cAAc,CAAC;IAC7B,IAAI,KAAK,GAAkB,UAAU,CAAC;IACtC,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,wFAAwF;IACxF,2FAA2F;IAC3F,yDAAyD;IACzD,IAAI,IAAiB,CAAC;IACtB,IAAI,WAAoB,CAAC;IACzB,IAAI,iBAA0B,CAAC;IAC/B,IAAI,SAAS,GAAG,IAAI,CAAC;IAErB,SAAS,CAAC;QACR,4FAA4F;QAC5F,2FAA2F;QAC3F,6FAA6F;QAC7F,oDAAoD;QACpD,MAAM,SAAS,GAAG,MAAM,CAAC;QACzB,IAAI,KAAgC,CAAC;QACrC,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7D,MAAM,IAAI,KAAK,CACb,6DAA6D,SAAS,KAAK,SAAS,cAAc,GAAG,0BAA0B,EAC/H,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;YACD,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;gBACpB,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7D,MAAM,IAAI,KAAK,CACb,oCAAoC,SAAS,4CAA4C,GAAG,uFAAuF,SAAS,oCAAoC,EAChO,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;YACD,SAAS,GAAG,SAAS,GAAG,EAAE,CAAC,CAAC,0DAA0D;YACtF,IAAI,SAAS,GAAG,EAAE;gBAAE,SAAS,GAAG,EAAE,CAAC;YACnC,IAAI,SAAS,GAAG,gBAAgB;gBAAE,gBAAgB,GAAG,SAAS,CAAC;YAC/D,SAAS;QACX,CAAC;QACD,2FAA2F;QAC3F,8FAA8F;QAC9F,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;YACnB,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,eAAe,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;YAChE,MAAM,IAAI,KAAK,CACb,6DAA6D,SAAS,KAAK,SAAS,cAAc,OAAO,CAAC,OAAO,0BAA0B,EAC3I,EAAE,KAAK,EAAE,OAAO,EAAE,CACnB,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QACtB,YAAY,IAAI,CAAC,CAAC;QAClB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAC9B,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAE3C,IAAI,SAAS,EAAE,CAAC;YACd,SAAS,GAAG,KAAK,CAAC;YAClB,IAAI,IAAI,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC;gBACvC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;oBAC1B,MAAM,IAAI,KAAK,CACb,4CAA4C,IAAI,CAAC,iBAAiB,4EAA4E,YAAY,iCAAiC,IAAI,CAAC,iBAAiB,YAAY,CAC9N,CAAC;gBACJ,CAAC;gBACD,wFAAwF;gBACxF,uBAAuB;gBACvB,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC;YACnC,CAAC;YACD,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACxD,MAAM,IAAI,KAAK,CACb,wCAAwC,IAAI,CAAC,IAAI,CAAC,KAAK,oBAAoB,UAAU,sBAAsB,CAC5G,CAAC;YACJ,CAAC;YACD,KAAK,GAAG,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;YACtC,iFAAiF;YACjF,sFAAsF;YACtF,yFAAyF;YACzF,MAAM,KAAK,GAAG,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC;YAC1D,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBACjB,OAAO;oBACL,MAAM,EAAE,EAAE;oBACV,OAAO;oBACP,KAAK;oBACL,YAAY,EAAE,YAAY,IAAI,IAAI;oBAClC,WAAW;oBACX,iBAAiB;oBACjB,IAAI;oBACJ,YAAY;oBACZ,gBAAgB;iBACjB,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CACb,0BAA0B,KAAK,qBAAqB,OAAO,IAAI,KAAK,iBAAiB,OAAO,wJAAwJ,CACrP,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,CAAC,iBAAiB,GAAG,SAAS,EAAE,CAAC;YAC9C,6FAA6F;YAC7F,wFAAwF;YACxF,6FAA6F;YAC7F,iDAAiD;YACjD,MAAM,IAAI,KAAK,CACb,4CAA4C,IAAI,CAAC,iBAAiB,kDAAkD,SAAS,YAAY,SAAS,IAAI,IAAI,CAAC,iBAAiB,GAAG,EAAE,6EAA6E,IAAI,CAAC,iBAAiB,GAAG,CACxR,CAAC;QACJ,CAAC;QAED,4FAA4F;QAC5F,+FAA+F;QAC/F,4FAA4F;QAC5F,6FAA6F;QAC7F,uEAAuE;QACvE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;QACnE,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAClB,4FAA4F;YAC5F,4FAA4F;YAC5F,MAAM,IAAI,KAAK,CACb,+DAA+D,SAAS,wBAAwB,IAAI,CAAC,IAAI,CAAC,KAAK,YAAY,SAAS,IAAI,KAAK,4EAA4E,CAC1N,CAAC;QACJ,CAAC;QAED,IAAI,WAAW,GAAkB,IAAI,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,WAAW,KAAK,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,WAAW;gBAAE,WAAW,GAAG,CAAC,CAAC,GAAG,CAAC;YACrE,IAAI,CAAC,CAAC,GAAG,GAAG,OAAO,IAAI,CAAC,CAAC,GAAG,GAAG,KAAM;gBAAE,SAAS,CAAC,uCAAuC;YACxF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7C,CAAC;QAED,2FAA2F;QAC3F,6FAA6F;QAC7F,6FAA6F;QAC7F,wFAAwF;QACxF,MAAM,WAAW,GAAG,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5F,IAAI,IAAI,GAAG,WAAW,GAAG,MAAM,CAAC;QAChC,IAAI,WAAW,KAAK,IAAI,IAAI,WAAW,GAAG,EAAE,GAAG,IAAI;YAAE,IAAI,GAAG,WAAW,GAAG,EAAE,CAAC;QAC7E,MAAM,GAAG,IAAI,CAAC;QACd,IAAI,MAAM,GAAG,KAAM;YAAE,MAAM;IAC7B,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhG,+FAA+F;IAC/F,gGAAgG;IAChG,8FAA8F;IAC9F,8FAA8F;IAC9F,6CAA6C;IAC7C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,MAAM,GAAG,OAAO,CAAC;QACrB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CACb,0CAA0C,OAAO,IAAI,KAAK,4BAA4B,MAAM,2BAA2B,CAAC,CAAC,GAAG,6DAA6D,CAC1L,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,EAAE,CAAC;QACf,CAAC;QACD,IAAI,MAAM,KAAK,KAAM,GAAG,EAAE,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,0CAA0C,OAAO,IAAI,KAAK,wBAAwB,MAAM,GAAG,EAAE,4DAA4D,CAC1J,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM;QACN,OAAO;QACP,KAAK,EAAE,KAAM;QACb,YAAY,EAAE,YAAY,IAAI,IAAI;QAClC,WAAW;QACX,iBAAiB;QACjB,IAAI;QACJ,YAAY;QACZ,gBAAgB;KACjB,CAAC;AACJ,CAAC;AA2CD,MAAM,UAAU,GAAG,CAAC,CAAa,EAAE,CAAa,EAAW,EAAE;IAC3D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAiC,EACjC,KAA0E;IAE1E,MAAM,MAAM,GACV,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxF,MAAM,UAAU,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC5D,MAAM,OAAO,GAAG,MAAM;SACnB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,UAAU,CAAC;SAClE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,EAAE,IAAI,EAAE,sBAAsB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAsC,EACtC,WAA+B;IAE/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,CAAC,WAAW,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/D,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAE3C,gGAAgG;IAChG,4BAA4B;IAC5B,MAAM,QAAQ,GACZ,QAAQ,IAAI,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,OAAO;QACjD,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IAE3D,IAAI,eAAe,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,EAAE,CAAC;gBACrB,eAAe,GAAG,KAAK,CAAC;gBACxB,KAAK,CAAC,IAAI,CACR,8BAA8B,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,MAAM,IAAI,CAAC,CAAC,GAAG,GAAG,EAAE,iBAAiB,CACxG,CAAC;gBACF,MAAM;YACR,CAAC;YACD,MAAM,IAAI,EAAE,CAAC;QACf,CAAC;QACD,IAAI,eAAe,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxE,eAAe,GAAG,KAAK,CAAC;YACxB,KAAK,CAAC,IAAI,CACR,8BAA8B,WAAW,CAAC,OAAO,IAAI,WAAW,CAAC,KAAK,KAAK,QAAQ,mCAAmC,OAAO,CAAC,MAAM,WAAW,CAChJ,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CACR,wIAAwI,CACzI,CAAC;IACJ,CAAC;IAED,+FAA+F;IAC/F,2EAA2E;IAC3E,IAAI,WAAW,GAAG,IAAI,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,GAAG,EAAE;YAAE,SAAS,CAAC,6CAA6C;QACvF,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC9D,WAAW,GAAG,KAAK,CAAC;YACpB,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,GAAG,gCAAgC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;YACzE,MAAM;QACR,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,OAAO;QACzB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,2gBAA2gB,CAAC;IAEhhB,OAAO;QACL,OAAO;QACP,eAAe,EAAE,KAAK,CAAC,IAAI,CAAC;QAC5B,eAAe,EAAE,KAAK,CAAC,QAAQ,CAAC;QAChC,aAAa,EAAE,OAAO,CAAC,MAAM;QAC7B,cAAc,EAAE,QAAQ;QACxB,eAAe;QACf,WAAW;QACX,KAAK;QACL,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/migrate.js

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { EngramClient } from './EngramClient.js';
+import { NPX_CLIENT } from './version.js';
 function getOpenClawDir() {
     return process.env['OPENCLAW_CONFIG_DIR'] || path.join(process.env['HOME'] || '', '.openclaw');
 }
@@ -107,8 +108,34 @@ export async function hasValidPairing(options) {
             sessionKeyPath: options.sessionKeyPath,
             host: options.host,
         });
-        // Lightweight authenticated query — succeeds only if the operator is registered
-        await client.listBackups();
+        // Ask the engram directly whether it recognises this session key, rather than inferring it
+        // from whether some gated read happened to come back.
+        //
+        // This probe used to call listBackups() and read any resolved promise as "paired". It reached
+        // the right verdict only via a carve-out: every unpaired caller — anonymous, revoked,
+        // unrelated — already trapped, while a PAIRED agent that merely lacked canReadBackup
+        // was handed `[]` and so looked like a paired agent with no backups. That carve-out closed on
+        // 2026-08-16; the same agent now gets a refusal, the SDK throws it, and the old probe
+        // would call a genuinely paired agent UNPAIRED and send the user back through pairing.
+        //
+        // ⟨0.16.0, L2.2 — fixed 2026-08-25⟩ getOwnerConsole(), NOT `status().authorized`.
+        //
+        // The paragraph this replaces was true of v0.15.0 and is false in BOTH halves at HEAD. The
+        // engram's `status()` is gone (it split into public `about()` + gated `getOwnerConsole()`),
+        // and `About` carries no `authorized` — `grep authorized src/engram/engram.did` finds only
+        // prose and an unrelated `authorizedBy`. So the read DECODED FINE and answered `undefined`,
+        // and every caller — owner, agent, guardian alike — was told they were UNPAIRED
+        // immediately after pairing successfully. This shipped: dist/migrate.js carried it too.
+        //
+        // `getOwnerConsole` is the gated half of that split, and its gate is #anyRole DESPITE the name
+        // (main.mo: `#anyRole, "getOwnerConsole"`; Gated.mo: "owner | active agent | active
+        // guardian") — exactly the audience the old flag answered `true` for. Reaching the record AT
+        // ALL is the authorization, so an `Ok` IS the recognition and the SDK throws on `#Err`, which
+        // the catch below turns into `false`. No sibling flag survives for a caller to misread.
+        //
+        // This is still a question put to the CANISTER rather than a string-match on refusal copy,
+        // which is what the replaced paragraph was rightly defending.
+        await client.getOwnerConsole();
         return true;
     }
     catch {
@@ -300,7 +327,7 @@ export function listCheckpoints() {
 export function rollbackCheckpoint(checkpointId) {
     const checkpoints = listCheckpoints();
     if (checkpoints.length === 0) {
-        throw new Error('No checkpoints to roll back. Run "npx @engramx/client pair" first to create a checkpoint.');
+        throw new Error(`No checkpoints to roll back. Run "${NPX_CLIENT} pair" first to create a checkpoint.`);
     }
     let target;
     if (checkpointId) {
@@ -861,7 +888,7 @@ export async function recoverOpenClaw(options) {
     const latestByType = new Map();
     for (const backup of finalized) {
         const existing = latestByType.get(backup.dbType);
-        if (!existing || backup.createdAt > existing.createdAt) {
+        if (!existing || backup.createdAtNs > existing.createdAtNs) {
             latestByType.set(backup.dbType, backup);
         }
     }