@engramx/client 0.15.0 → 0.16.0-rc.2

package/dist/memoryArchive.d.ts

@@ -0,0 +1,384 @@
+import { Principal } from '@icp-sdk/core/principal';
+import { type Event as LedgerFsEvent, type Hash } from './ledgerfsHash.js';
+export interface MemoryLogChunkRef {
+    hash: Uint8Array;
+    size: bigint;
+    birthSeq: bigint;
+}
+export interface MemoryLogManifest {
+    chunks: MemoryLogChunkRef[];
+    totalSize: bigint;
+    contentRoot: Uint8Array;
+}
+/** Why an imported entry exists — the pre-ledgerfs migration seam. All five classes. */
+export type MemoryLogImportNote = {
+    genesis: {
+        boundTo: [] | [Uint8Array];
+    };
+} | {
+    legacyGap: {
+        firstSurviving: bigint;
+    };
+} | {
+    legacyTruncated: {
+        storedBytes: bigint;
+        prefixHash: Uint8Array;
+    };
+} | {
+    legacyDelete: null;
+} | {
+    legacyUnreconstructable: {
+        contentHash: Uint8Array;
+        reason: string;
+    };
+};
+/** The operation one log entry records. `condense` and `exported` are store-global. */
+export type MemoryLogOp = {
+    append: {
+        deltaHash: Uint8Array;
+        deltaSize: bigint;
+        newSize: bigint;
+    };
+} | {
+    set: {
+        manifest: MemoryLogManifest;
+    };
+} | {
+    restore: {
+        toVersion: bigint;
+        manifest: MemoryLogManifest;
+    };
+} | {
+    tombstone: null;
+} | {
+    evict: {
+        fromVersion: bigint;
+        toVersion: bigint;
+        chunkCount: bigint;
+        byteCount: bigint;
+        evictedRoot: Uint8Array;
+    };
+} | {
+    condense: {
+        fromSeq: bigint;
+        toSeq: bigint;
+        opCount: bigint;
+        opsRoot: Uint8Array;
+        headAtBoundary: Uint8Array;
+    };
+} | {
+    exported: {
+        fromSeq: bigint;
+        toSeq: bigint;
+        opsRoot: Uint8Array;
+        authorFilter: [] | [Principal];
+    };
+} | {
+    imported: MemoryLogImportNote;
+};
+/**
+ * One entry in the engram's single memory log.
+ *
+ * `path` is carried verbatim, which is why the whole surface is owner-only: a path is inside the
+ * entry's hash preimage, so it cannot be redacted for a lesser caller without breaking the very
+ * hash the archive exists to prove.
+ */
+export interface MemoryLogEvent {
+    seq: bigint;
+    path: string;
+    version: bigint;
+    op: MemoryLogOp;
+    /** Attribution — who wrote it. Never authorization. */
+    by: Principal;
+    /**
+     * When the entry was chained, in nanoseconds. ⟨RENAMED 2026-10-05⟩ This said `at`. The engram
+     * renamed every wire instant to carry its unit on 2026-10-02 (`at` → `atNs` on this record,
+     * `MemoryRangeExport`, `ExportReceiptRow` and `CondenseCheckpointRow`), and the four mirrors in
+     * this file kept the old name. `toLedgerFsEvent` then read `e.at`, which a served entry no
+     * longer carries, and `sle64(undefined)` throws "TypeError: Cannot convert undefined to a BigInt".
+     * So `memoryLogEventHash` and `verifyMemoryArchive` threw on the first real entry. They never
+     * returned a wrong verdict, but they could not check a single entry (measured 2026-10-05 with
+     * node). The hash contract's own field (`Event.at` in ledgerfsHash.ts) keeps its name, because
+     * the hashed body carries the value and never the name.
+     */
+    atNs: bigint;
+    size: bigint;
+    contentRoot: Uint8Array;
+    /** Hash of the previous entry under the canonical (non-Candid) encoding. */
+    prev: Uint8Array;
+}
+/**
+ * One page of the memory log.
+ *
+ * `pageCap` is the width of the window the engram actually covered — its clamp on `max`, which
+ * sits at 256 rather than the library's 1024. It is DISCLOSED for exactly one reason: a caller
+ * that cannot see the cap cannot know whether it has the whole window. Read it, never `max`.
+ *
+ * ⚠ ⟨STALE 2026-10-05 — measured, not fixed⟩ This envelope no longer mirrors the wire, and the
+ * difference goes beyond a field name. 0.16.0 renamed `getMemoryLogPage` to `listMemoryLog`, and it
+ * answers `LogPage = { firstAvailableSeq; head; page : { items; total; withheld } }`, so `events`,
+ * `totalEvents` and `pageCap` are not served. `assembleMemoryArchive` walks by `pageCap`, and the
+ * served page has no field with that meaning. A caller therefore has to adapt `listMemoryLog` into
+ * this shape, and the adaptation decides how wide each window really was. That is a design call
+ * for the walk, not a rename. It is left open and named in test/wire-mirror.test.ts, which fails
+ * once this envelope matches, so the exception cannot outlive the drift. The entries themselves
+ * (`MemoryLogEvent`) do mirror the wire.
+ */
+export interface MemoryLogPage {
+    events: MemoryLogEvent[];
+    /** Entries EVER chained, not the retained count — a condensed prefix never shortens this. */
+    totalEvents: bigint;
+    /** The floor below which entries are no longer served: a condensed prefix, made visible. */
+    firstAvailableSeq: bigint;
+    head: Uint8Array;
+    pageCap: bigint;
+}
+/** What `exportMemoryRange` writes into the chain and hands back. */
+export interface MemoryExportReceipt {
+    /** Chain position of the receipt entry itself — always above every entry it covers. */
+    seq: bigint;
+    head: Uint8Array;
+    fromSeq: bigint;
+    toSeq: bigint;
+    opsRoot: Uint8Array;
+    authorFilter: [] | [Principal];
+    /** ⟨RENAMED 2026-10-05⟩ was `at` — see `MemoryLogEvent.atNs`. */
+    atNs: bigint;
+}
+/** What `condenseMemoryLog` returns: the checkpoint that replaced the dropped prefix. */
+export interface MemoryCondenseResult {
+    seq: bigint;
+    head: Uint8Array;
+    fromSeq: bigint;
+    toSeq: bigint;
+    opCount: bigint;
+    opsRoot: Uint8Array;
+    /** The head attested at the boundary — what a verifier seeds from once the prefix is gone. */
+    headAtBoundary: Uint8Array;
+    newFirstAvailableSeq: bigint;
+    /**
+     * SIGNED, and that is the point: a condense drops entries but adds a checkpoint back, so a
+     * short condense can cost more history bytes than it frees. A positive delta is a real,
+     * representable outcome, not an error.
+     */
+    historyBytesDelta: bigint;
+}
+/** A receipt or checkpoint named by a preview, enough to go fetch or explain it. */
+export interface MemoryReceiptRef {
+    seq: bigint;
+    fromSeq: bigint;
+    toSeq: bigint;
+}
+/** What a condense WOULD do, and whether the export gate is open. Reads nothing destructive. */
+export interface MemoryCondensePreview {
+    firstAvailableSeq: bigint;
+    totalEvents: bigint;
+    proposedToSeq: bigint;
+    opCountInRange: bigint;
+    /** True when an unfiltered receipt already covers the whole proposed prefix. */
+    unlocked: boolean;
+    coveringReceipt: [] | [MemoryReceiptRef];
+    /** The nearest miss, so a refusal says what is still needed rather than only "no". */
+    bestUnfilteredReceipt: [] | [MemoryReceiptRef];
+    /**
+     * Author-filtered receipts seen while scanning. They are counted, never credited: a filtered
+     * ops root cannot witness that every entry in the range was served.
+     */
+    filteredReceiptsSeen: bigint;
+    maxUnlockableToSeq: bigint;
+    scannedFromSeq: bigint;
+    /** True ⇒ the scan hit its bound; the answer describes what was scanned, not the whole chain. */
+    scanTruncated: boolean;
+}
+export interface MemoryExportReceiptRow {
+    seq: bigint;
+    /** ⟨RENAMED 2026-10-05⟩ was `at` — see `MemoryLogEvent.atNs`. */
+    atNs: bigint;
+    by: Principal;
+    fromSeq: bigint;
+    toSeq: bigint;
+    opsRoot: Uint8Array;
+    authorFilter: [] | [Principal];
+}
+export interface MemoryCheckpointRow {
+    seq: bigint;
+    /** ⟨RENAMED 2026-10-05⟩ was `at` — see `MemoryLogEvent.atNs`. */
+    atNs: bigint;
+    by: Principal;
+    fromSeq: bigint;
+    toSeq: bigint;
+    opCount: bigint;
+    opsRoot: Uint8Array;
+    headAtBoundary: Uint8Array;
+}
+/**
+ * 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 declare 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`.
+ */
+export declare const ARCHIVE_PAGE_EVENTS = 256n;
+/**
+ * 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 declare function toLedgerFsEvent(e: MemoryLogEvent): LedgerFsEvent;
+/** The canonical hash of one log entry, recomputed from its decoded fields. */
+export declare const memoryLogEventHash: (e: MemoryLogEvent) => Hash;
+/**
+ * Fetches one page.
+ *
+ * The caller supplies it, and after 2026-08-17 that is the only way it arrives: `EngramClient`
+ * used to carry a `getMemoryLogPage` wrapper that satisfied this shape, and the charter diet
+ * removed it — `getMemoryLogPage` is owner-only on the canister and the class is the agent SDK.
+ * Nothing about the WALK changed. An owner tool passes its own authenticated actor's
+ * `getMemoryLogPage` here and gets the same paging, the same halving on an over-large response,
+ * and the same refusal to return a short archive; the tests pass their own fetcher and always did.
+ *
+ * ⟨CORRECTED 2026-10-05⟩ An owner tool can no longer pass the actor's method straight in. 0.16.0
+ * serves `listMemoryLog`, not `getMemoryLogPage`, and its reply is not a `MemoryLogPage` (see the
+ * note there). Until the walk is adapted, a fetcher has to translate the served page into this
+ * shape. That translation is open, not done.
+ */
+export type MemoryLogPageFetcher = (startSeq: bigint, max: bigint, authorFilter?: Principal) => Promise<MemoryLogPage>;
+export interface AssembleArchiveOptions {
+    /** Default: the engram's retained floor, learned from the first page. */
+    fromSeq?: bigint | number;
+    /** Default: the last entry ever chained, learned from the first page. */
+    toSeq?: bigint | number;
+    /** Restrict to one author. A filtered archive can only be checked against a filtered receipt. */
+    authorFilter?: Principal;
+    /** Starting page size. Only ever shrinks from here — never grows toward `pageCap`. */
+    pageEvents?: bigint | number;
+    /** Lower the range ceiling for this call. Values above {@link ARCHIVE_MAX_RANGE} are clamped. */
+    maxRange?: bigint | number;
+}
+export interface MemoryArchive {
+    /** Entries in ascending seq order, deduplicated. */
+    events: MemoryLogEvent[];
+    fromSeq: bigint;
+    toSeq: bigint;
+    authorFilter: Principal | null;
+    totalEvents: bigint;
+    firstAvailableSeq: bigint;
+    /** The engram's chain head as of the last page fetched. */
+    head: Uint8Array;
+    /** The cap the engram disclosed on the last page. */
+    pageCap: bigint;
+    pagesFetched: number;
+    /**
+     * The smallest page size the walk had to fall back to. Below the requested size ⇒ at least one
+     * page did not fit in a response and was retried smaller. Surfaced because "it worked, slowly"
+     * and "it worked" are different facts about the engram's log.
+     */
+    smallestPageUsed: bigint;
+}
+/**
+ * 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 declare function isResponseTooLarge(err: unknown): boolean;
+/**
+ * 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.
+ *
+ * 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 declare function assembleMemoryArchive(fetchPage: MemoryLogPageFetcher, options?: AssembleArchiveOptions): Promise<MemoryArchive>;
+/**
+ * The part of a receipt or checkpoint verification needs. Both an `exportMemoryRange` receipt and
+ * a `condenseMemoryLog` checkpoint satisfy it — they commit to an ops root over the same
+ * construction, which is why one verifier covers both.
+ */
+export interface OpsRootAttestation {
+    fromSeq: bigint;
+    toSeq: bigint;
+    opsRoot: Uint8Array;
+    /** Absent or `[]` ⇒ the attestation covers every author in the range. */
+    authorFilter?: [] | [Principal];
+}
+export interface MemoryArchiveVerification {
+    /** The single question: does this archive reproduce the root the engram committed to? */
+    matches: boolean;
+    computedOpsRoot: string;
+    attestedOpsRoot: string;
+    /** Entries the ops root is built over, after applying the attestation's author filter. */
+    eventsCovered: number;
+    /** Entries the attestation's range implies, when it can be known (unfiltered only). */
+    eventsExpected: number | null;
+    /** Every seq in the range present exactly once. Only meaningful for an unfiltered attestation. */
+    rangeContiguous: boolean;
+    /** Each held entry's `prev` equals the recomputed hash of the entry before it. */
+    chainLinked: boolean;
+    /** Facts found while checking, in the order found. Empty when everything lined up. */
+    notes: string[];
+    /**
+     * Present only on a mismatch. Written to describe the situation without assigning blame — the
+     * likeliest causes are on the reader's side, and an owner told "your engram is corrupt" acts on
+     * it.
+     */
+    explanation: string | null;
+}
+/**
+ * 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 declare function recomputeOpsRoot(events: readonly MemoryLogEvent[], range: {
+    fromSeq: bigint;
+    toSeq: bigint;
+    authorFilter?: [] | [Principal];
+}): {
+    root: Hash;
+    covered: MemoryLogEvent[];
+};
+/**
+ * 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 declare function verifyMemoryArchive(archive: Pick<MemoryArchive, 'events'>, attestation: OpsRootAttestation): MemoryArchiveVerification;