@engramx/client 0.15.0-rc.3 → 0.16.0-rc.2

package/dist/EngramClient.d.ts

@@ -1,10 +1,11 @@
 import { type CertifiedAuditHead, type VerifiedAuditHead } from './certifiedAudit.js';
+import { Ed25519KeyIdentity } from '@icp-sdk/core/identity';
 import { Principal } from '@icp-sdk/core/principal';
-import { Ic402Client, type SessionHandle } from '@ic402/client';
-import type { RawMemoryFile, MemoryHistory, MemoryRangePage, MemoryFile, MemoryFileInfo, SessionContext, OperatorRecord, AuditEntry, EngramStatus, GuardianRecord, WorldIdProof, BackupMetadata, BackupType, StorageStats, PaymentRequirement, PaymentSignature, PaymentResult, SessionIntent, SessionConfig, SessionState, Voucher, SpendingPolicy, ContentEntry, ContentDelivery, AgentCard, ApprovalRequest, EndpointType, EndpointStatus, X402Endpoint, PurchaseRecord, RevenueSummary } from './types.js';
+import { idlFactory } from './idl.js';
+import type { MemoryHistory, MemoryRangePage, MemoryFile, MemoryFileInfo, SessionContext, Pairing, AuditPage, AgentRecord, ChildAllowanceRow, EngramStatus, OwnerConsole, GuardianRecord, BackupMetadata, BackupType, ApprovalRequest } from './types.js';
 /**
  * Source class declared on an append — recorded permanently in the engram's audit chain beside
- * this operator's principal. Declared by the caller, NOT verified by the canister; a false
+ * this agent's principal. Declared by the caller, NOT verified by the canister; a false
  * declaration is itself attributable. Omit (undefined) when none applies: untagged is honest,
  * a guessed tag is not.
  */
@@ -20,29 +21,22 @@ export type MemorySource = 'human' | 'agentDerived' | 'sessionTranscript' | 'fil
  * first four unchanged.
  */
  | 'deterministic';
-/** A disputed memory write — marked, never deleted. */
-export interface Repudiation {
-    path: string;
+/**
+ * The evidence a write actually landed.
+ *
+ * Returned by every write method as of the 2026-08-16 canister release. Previously these returned
+ * a bare version number and the receipt — which the canister had already computed — was discarded,
+ * so a writer could learn THAT their write succeeded but not be handed the proof. `head` is the
+ * audit-chain head after this write, hex-encoded; it transitively commits to the content root, so a
+ * third party can verify the write against the chain and its anchor without trusting the writer.
+ */
+export interface MemoryReceipt {
+    /** Version of this path after the write. */
     version: bigint;
-    reason: string;
-    at: bigint;
-    auditId: bigint;
-}
-/** One reviewed-surface row: machine fields parsed canister-side from its own audit format. */
-export interface OperatorWriteRow {
-    entry: AuditEntry;
-    path: [] | [string];
-    version: [] | [bigint];
-    source: [] | [string];
-    connector: [] | [string];
-}
-export interface OperatorWriteReview {
-    cursor: bigint;
-    head: bigint;
-    earliest: bigint;
-    /** true ⇒ exactly 200 rows returned AND more unreviewed writes exist — page via markOperatorWritesReviewed(lastShownId); never present 200 as a total. */
-    capped: boolean;
-    rows: OperatorWriteRow[];
+    /** Position in the engram's event sequence. */
+    seq: bigint;
+    /** Chain head after this write, hex. The thing to hand a verifier. */
+    head: string;
 }
 export interface EngramClientConfig {
     /** The engram canister ID */
@@ -64,14 +58,15 @@ export interface EngramClientConfig {
      *  legacy plaintext keep working regardless. */
     encryptMemory?: boolean;
     /** Opt-in persistent key cache path (Node only; or set ENGRAMX_KEY_CACHE). The cache file is
-     *  plaintext-equivalent key material: a host that persisted the key keeps it after revocation.
-     *  Destroy the file when decommissioning a host. */
+     *  plaintext-equivalent key material: a machine that persisted the key keeps it after revocation.
+     *  Destroy the file when retiring the machine the agent runs on. */
     keyCachePath?: string;
     /** Label identifying this host in the engram's distinct-reader set (drives cross-model reuse
      *  metrics). Sent by `startSession()`. Default: 'sdk'. Use your product name, e.g. 'openclaw'. */
     clientLabel?: string;
 }
-export declare const idlFactory: ({ IDL }: {
+export { idlFactory };
+export declare const icrc2LedgerIdlFactory: ({ IDL }: {
     IDL: any;
 }) => any;
 export declare class EngramClient {
@@ -84,31 +79,66 @@ export declare class EngramClient {
     private encryption;
     private encryptionModeSynced;
     private clientLabel;
+    /**
+     * ⟨0.16.0⟩ Delegates to the shared unwrap, because `Err` is a VARIANT now, not a string.
+     *
+     * The old body was `throw new Error(result.Err)`, which under the new envelope stringifies a
+     * six-armed object to **"[object Object]"** — it compiles, it runs, and it destroys the message.
+     * On this codebase that is the product: the refusals exist to tell a caller what to do next, and
+     * this line decides whether they ever read one. See wire.ts.
+     */
     private unwrap;
     constructor(config: EngramClientConfig);
     readMemory(path: string): Promise<MemoryFile>;
+    /**
+     * Does this path hold content already?
+     *
+     * A whole-file read is the obvious way to answer this and the wrong one. The engram refuses a
+     * whole-file read above 512 KiB, and files above that ceiling exist: the write cap sat at
+     * 1.5 MB until it was lowered to the same 512 KiB on 2026-08-15, so anything grown past the
+     * read ceiling under the old cap is still stored, still appendable, and still unreadable
+     * whole. Treating that refusal as absence is not a missing newline — it silently concatenates
+     * onto the previous line, and in encrypted mode it skips the framing check that exists to stop
+     * an unparseable mixed blob.
+     *
+     * So ask for a byte instead. A one-byte ranged read answers the question without ever hitting
+     * the whole-file ceiling, and it is the cheaper question at ANY size — there is no reason to
+     * pull a whole file to learn whether it is empty. That reason outlives the legacy files.
+     */
+    private hasContent;
     /**
      * Append `content` to a memory file (append-only; the canister concatenates the delta).
      *
-     * @returns the new on-chain version. **Special case:** if an `offlineQueue` is configured and the
-     * network call fails with a transport error, the encoded delta is queued for a later
-     * `syncOfflineQueue()` and this returns `0n` — a "deferred, not yet committed" sentinel, NOT a real
-     * version. Callers that surface a version to users should treat `0n` as "queued". Deterministic
+     * @returns the write {@link MemoryReceipt}. **Special case:** if an `offlineQueue` is configured
+     * and the network call fails with a transport error, the encoded delta is queued for a later
+     * `syncOfflineQueue()` and this returns `null` — there is no receipt for a write that has not
+     * happened, and a caller that surfaces one must say "queued", not report a version. Deterministic
      * errors (validation, permission, writes-paused, non-framed base in encrypted mode) always throw.
      */
+    appendMemory(path: string, content: string, source?: MemorySource): Promise<MemoryReceipt | null>;
     /**
-     * Does this path hold content already?
+     * The engram's file listing.
      *
-     * The engram refuses a whole-file read above 512 KiB while still ACCEPTING appends up to
-     * 1.5 MB, so between those two numbers "read it to see if it is empty" fails on a file that
-     * very much exists. Treating that refusal as absence is not a missing newline — it silently
-     * concatenates onto the previous line, and in encrypted mode it skips the framing check that
-     * exists to stop an unparseable mixed blob. So ask for a byte instead: a one-byte ranged read
-     * answers the question without ever hitting the whole-file ceiling.
+     * ⟨0.16.0, L1 + L3⟩ Paged and enveloped. Two things this signature deliberately does NOT hide:
+     * a refusal throws rather than returning [], and `withheld` — the rows policy removed from the
+     * page — is surfaced on the thrown/returned shape's sibling accessor rather than silently
+     * dropped. `listMemoryFilesPage` is there for callers that must render "N hidden"; this one
+     * returns the rows because most callers render a list.
      */
-    private hasContent;
-    appendMemory(path: string, content: string, source?: MemorySource): Promise<bigint>;
-    listMemoryFiles(): Promise<MemoryFileInfo[]>;
+    listMemoryFiles(opts?: {
+        start?: number;
+        limit?: number;
+    }): Promise<MemoryFileInfo[]>;
+    /** The same read, keeping `total` and `withheld` — a filtered listing that looks complete is
+     *  the defect the page shape exists to fix, and only the caller can decide whether to say so. */
+    listMemoryFilesPage(opts?: {
+        start?: number;
+        limit?: number;
+    }): Promise<{
+        items: MemoryFileInfo[];
+        total: bigint;
+        withheld: bigint;
+    }>;
     readMemoryBatch(paths: string[]): Promise<[string, MemoryFile | Error][]>;
     /**
      * Load the engram's memory for injection at the START of an agent session — the automatic
@@ -138,7 +168,7 @@ export declare class EngramClient {
      * `startSession()` yourself if you need the structured files instead. Accepts the same `onError`
      * option as `startSession`.
      *
-     * SECURITY: memory content is written by operators (AI hosts) and is UNTRUSTED input, not host
+     * SECURITY: memory content is written by agents and is UNTRUSTED input, not system
      * instructions. Each file is wrapped in a delimited `<engram-memory>` block and the header tells the
      * model to treat the blocks as data — so appended memory cannot masquerade as system-level directives
      * (prompt-injection boundary). Do not strip the fences when embedding this in your own prompt.
@@ -187,34 +217,55 @@ export declare class EngramClient {
     /**
      * Replace the whole content of an EXISTING file.
      *
-     * Operators may call this only on paths the owner listed in `operatorRevisablePaths`, and
+     * Agents may call this only on paths the owner listed in `agentRevisablePaths`, and
      * never on a path classed `#vault` — those stay append-only for anyone but the owner. It never
      * creates a path: a revise grant is permission to change what is there.
      *
      * The prior version is superseded, not overwritten: it stays readable via
      * {@link readMemoryAt} and its hash stays committed.
      */
-    reviseMemory(path: string, content: string | Uint8Array): Promise<bigint>;
+    reviseMemory(path: string, content: string | Uint8Array): Promise<MemoryReceipt>;
+    /** ⟨0.16.0, L2.1⟩ `getWalletBalances` answers `Result<WalletBalances>` — a RECORD
+     *  {icpE8s; ckusdcE6s; ckusdtE6s; cycles}, not a Nat. `unwrap<bigint>` is an unchecked
+     *  assertion over `ActorSubclass<any>`, so the record flowed straight through while the
+     *  signature still said bigint: the stdio MCP tool emitted
+     *  {"cyclesBalance":{"icpE8s":"0",...,"cycles":"40717306348548"}} against a catalog that
+     *  promises "no ckUSDC/ICP amounts", and OpenClaw printed "Cycles: [object Object]".
+     *  Same class as the readAuditLog envelope defect corrected 2026-08-20 two methods below,
+     *  and caught the same way: by a live call, because tsc has nothing to check here.
+     *  This method is the CYCLES projection its name and both MCP catalogs promise.
+     *  Corrected 2026-08-25. */
     walletBalance(): Promise<bigint>;
-    /**
-     * OWNER: disavow a specific memory write, in the open. Never deletes — the content and the
-     * original audit entry stay; this appends a chained `memory.repudiate` entry and lists the
-     * dispute. Returns the repudiation's audit id.
-     */
-    repudiateMemoryWrite(path: string, version: bigint | number, reason: string): Promise<bigint>;
-    /** Disputed writes (same visibility as the audit log; unauthorized reads see []). */
-    getRepudiations(): Promise<Repudiation[]>;
-    /**
-     * OWNER: operator writes since the last markOperatorWritesReviewed() — capped at 200 per call
-     * (advance the cursor and re-call to page). `earliest` discloses audit-ring eviction.
-     */
-    getOperatorWriteReview(): Promise<OperatorWriteReview>;
-    /**
-     * OWNER: "I have seen everything up to and including uptoAuditId" (omit = everything at head).
-     * Bounded so the attestation can never cover entries that were not rendered; monotonic; logged.
-     */
-    markOperatorWritesReviewed(uptoAuditId?: bigint | number): Promise<bigint>;
-    readAuditLog(fromIndex?: number, limit?: number): Promise<AuditEntry[]>;
+    /** ⟨0.16.0, L1 + L3⟩ Paged and enveloped. The wire method moved to `listAuditEntries` and the
+     *  CALL followed it, but the RESULT HANDLING did not: this returned the raw
+     *  `{Ok:{items,total,withheld}} | {Err}` envelope while still declaring `AuditEntry[]`, so a
+     *  caller's `.forEach` threw "not a function" and a REFUSAL arrived as a truthy object instead
+     *  of an exception — the failure mode L1 exists to end, reintroduced by a half-finished rename.
+     *  `this.actor` is `ActorSubclass<any>`, so the declared type is an unchecked assertion and tsc
+     *  had nothing to catch it with: the rename compiled and looked done.
+     *  Corrected 2026-08-20 to the idiom every sibling here already uses.
+     *
+     *  ⟨CORRECTED 2026-09-29, owner ruling follow-up 16 (B)⟩ Returns the PAGE, not `.items`. An agent
+     *  now reads only the entries it caused, so a window of the record comes back with `withheld`
+     *  counting what it was not shown; handing back the bare array would let an agent mistake its part
+     *  of the record for the whole. `limit` is the window's span, not a row count. */
+    readAuditLog(fromIndex?: number, limit?: number): Promise<AuditPage>;
+    /** How many entries the chained audit log currently holds — the page bound for
+     *  {@link readAuditLog}.
+     *
+     *  SERVES `status().auditLogSize`. The canister's own `auditLogSize()` was removed by the surface
+     *  diet (R3, 2026-08-17): it was `auditLogger.size()` behind an #anyRole gate, while `status()`
+     *  and `getCertifiedAuditHead()` both publish the identical Nat from the identical accessor to an
+     *  anonymous caller. This wrapper keeps its name and its `bigint`, and only changes which door it
+     *  knocks on.
+     *
+     *  WHY status() AND NOT getCertifiedAuditHead(). Two reasons, both about this method's one job.
+     *  The head surface additionally returns the CBOR IC certificate and a `total` — bytes every
+     *  caller of a bare count discards, and a second, differently-meaning number (cumulative across
+     *  ring trims) sitting next to the one that is right. Paging `readAuditLog` off `.total` reads
+     *  past the ring; `status().auditLogSize` offers no such wrong field to pick. Callers who want
+     *  the head — and its certificate — already have {@link getCertifiedAuditHead} and
+     *  {@link getVerifiedAuditHead}, which is the other half of why this one does not duplicate it. */
     auditLogSize(): Promise<bigint>;
     /** The chained audit-log head plus the IC certificate over it (raw, unverified). Use
      *  getVerifiedAuditHead() to verify it against the IC root key. */
@@ -223,77 +274,89 @@ export declare class EngramClient {
      *  head bytes and whether the replica's claim agrees, WITHOUT trusting this replica. */
     getVerifiedAuditHead(): Promise<VerifiedAuditHead>;
     status(): Promise<EngramStatus>;
-    listGuardians(): Promise<GuardianRecord[]>;
-    rotateOperatorKey(newPublicKeyHash: string): Promise<void>;
-    getWorldIdProof(): Promise<WorldIdProof | null>;
-    /** The verified IDKitResult, verbatim, as World's /api/v4/verify accepted it (null if unverified). */
-    getWorldIdVerification(): Promise<string | null>;
-    getPaymentRequirements(amount: bigint): Promise<PaymentRequirement[]>;
-    requestSession(): Promise<SessionIntent>;
-    openSession(config: SessionConfig, sig: PaymentSignature, rationale?: string, approvalId?: string): Promise<SessionState | {
-        approvalPending: {
-            requestId: string;
-            reason: string;
-        };
-    }>;
-    sessionReadMemory(voucher: Voucher, path: string): Promise<RawMemoryFile>;
-    sessionAppendMemory(voucher: Voucher, path: string, content: Uint8Array): Promise<bigint>;
-    endSession(sessionId: string): Promise<PaymentResult>;
-    forceCloseSession(sessionId: string): Promise<PaymentResult>;
-    private ownerAuthFor;
-    /**
-     * Withdraw a token balance to the owner's own principal (owner-only, destination-locked).
-     * Pass `{ receipt: true }` to attach an exportable owner-signed authorization (D1).
-     */
-    ownerWithdraw(token: string, amount: bigint, options?: {
-        receipt?: boolean;
-        nonce?: bigint;
-    }): Promise<{
-        Ok: bigint;
-    } | {
-        Err: string;
-    }>;
-    uploadContent(id: string, mimeType: string, data: Uint8Array): Promise<void>;
-    /**
-     * E8: upload content larger than the ~2 MB single-shot ingress limit by streaming it through the
-     * canister's chunked path (uploadContentInit + uploadContentChunk). Chunk size is 1.5 MB — the
-     * ContentStore MAX_CHUNK_SIZE, enforced as a hard cap and safely under ICP's 2 MB ingress limit once
-     * Candid framing is added.
+    /** ⟨0.16.0, L2.2⟩ The GATED half of the `status()` split, and the only "does this engram
+     *  recognise me" question left after `about()` shed the `authorized` discriminator.
      *
-     * There is NO finalize step: content is complete and readable once every chunk is written (the store
-     * reassembles on read). Chunks are write-once server-side (CTR keystream-reuse guard), so a mid-upload
-     * failure leaves a stuck, un-overwritable entry; on any error this helper best-effort deletes the
-     * partial entry so the caller can retry from scratch (set cleanupOnError=false to keep it for a manual
-     * resume). Payloads at or under one chunk delegate to single-shot uploadContent.
-     */
-    uploadContentChunked(id: string, mimeType: string, data: Uint8Array, cleanupOnError?: boolean): Promise<void>;
-    listContent(): Promise<ContentEntry[]>;
-    getContent(contentId: string, paymentSig?: PaymentSignature, rationale?: string, approvalId?: string): Promise<{
-        paymentRequired?: PaymentRequirement[];
-        delivery?: ContentDelivery;
-        error?: string;
-        approvalPending?: {
-            requestId: string;
-            reason: string;
-        };
-    }>;
-    deleteContent(id: string): Promise<void>;
-    createEndpoint(name: string, description: string, endpointType: EndpointType, contentId: string | null, suggestedPrice: bigint): Promise<X402Endpoint>;
-    listEndpoints(statusFilter?: EndpointStatus): Promise<X402Endpoint[]>;
-    getEndpointPurchases(endpointId: string, fromIndex: bigint, limit: bigint): Promise<PurchaseRecord[]>;
-    getRevenueSummary(): Promise<RevenueSummary>;
-    getPaymentPolicy(): Promise<SpendingPolicy>;
-    getAgentCard(): Promise<AgentCard>;
-    getEvmAddress(): Promise<string>;
-    getOwnerEvmAddress(): Promise<string | null>;
+     *  DESPITE THE NAME THE GATE IS #anyRole, not owner-only — main.mo reads
+     *  `Gated.gatedResult<Types.OwnerConsole>(gateCtx(msg.caller), #anyRole, "getOwnerConsole", …)`,
+     *  and Gated.mo spells #anyRole as "owner | active agent | active guardian". An agent SDK
+     *  is entitled to it, which is why migrate.ts's pairing probe may call it.
+     *
+     *  THROWS on refusal, like every other gated wrapper here. That is the whole point: REACHING the
+     *  record is the authorization, so `Ok` is the recognition and `#Err(#Refused …)` is the denial.
+     *  There is no sibling flag left for a consumer to forget to check — which is exactly the defect
+     *  that made `status().authorized` answer `undefined` to everyone. */
+    getOwnerConsole(): Promise<OwnerConsole>;
+    /** ⟨0.16.0, L1 + L3⟩ Paged and enveloped. A refusal here used to arrive as [], which reads as
+     *  "this engram has nobody who can freeze payments or pause writes" — a claim about who can STOP
+     *  it, handed to a caller who merely lacks a grant. It throws now. */
+    listGuardians(opts?: {
+        start?: number;
+        limit?: number;
+    }): Promise<GuardianRecord[]>;
+    rotateAgentKeyHash(newPublicKeyHash: string): Promise<void>;
+    /** ⟨2026-09-28⟩ End THIS agent's own engagement with the engram — a resignation, recorded by
+     *  the registry under its own reason so an agent's track record tells a clean exit from a firing.
+     *  Terminal for this principal on this engram: pairing is one-shot, so working for it again
+     *  needs a new principal and a fresh invite. Throws on a refusal (not an agent, already ended). */
+    resignAgent(): Promise<void>;
+    /** ⟨2026-09-29, the owner's ruling of that date (follow-up 10, option A)⟩ Step one of replacing
+     *  THIS agent's key on the engram: the key this client signs with nominates `newKey`. Nothing
+     *  moves until the new key accepts (`acceptAgentKeyNomination`, called by a client that signs with
+     *  the new key) within 24 hours. The engagement stays open, the track record does not move, and
+     *  the agent's limits carry over. A new nomination replaces an earlier one. Throws on a refusal. */
+    nominateAgentKey(newKey: Principal): Promise<void>;
+    /** ⟨2026-09-29, follow-up 10⟩ Step two: the key this client signs with accepts the nomination the
+     *  agent's current key (`agentKey`) made of it, and takes over the agent's record on this engram.
+     *  From then on `agentKey` is refused as an agent. Returns the record as the new key holds it.
+     *  Throws on a refusal (no pending nomination of this key, expired, or an ended engagement). */
+    acceptAgentKeyNomination(agentKey: Principal): Promise<AgentRecord>;
+    /** ⟨2026-10-01, the owner's ruling 2 A⟩ How many engrams of its own the agent holding
+     *  `agentKey` may still open through this engram, and its lasting key (`root`) — the key that
+     *  would own what it opens. The engram answers the owner, or the agent asking about its own key
+     *  (`agentKey` = the key this client signs with); anyone else is refused, never told 0.
+     *  Named caller: the `open-engram` command (openEngram.ts), before it asks the engram to open. */
+    getChildAllowance(agentKey: Principal): Promise<ChildAllowanceRow>;
+    /** ⟨2026-10-01, the owner's ruling 2 A⟩ Ask this engram to open an engram of the agent's own.
+     *  The engram attaches its own cycles to the registry's call and the agent's LASTING key owns
+     *  what is opened — approving is giving: it is the agent's from the moment it exists. Answers the
+     *  new engram's canister id. Throws a `CanisterRefusal` carrying the engram's sentence (no
+     *  allowance, payments frozen, too little balance, or the registry refused) — each names what to
+     *  do. Named caller: the `open-engram` command (openEngram.ts). */
+    openChildEngram(): Promise<Principal>;
+    /** ⟨2026-10-01⟩ The registry that opened this engram, or null when it records none — a public
+     *  read. Named caller: the `open-engram` command, which prints the owner kit's command with
+     *  `--registry` filled in, so whoever runs the agent never has to find the id. */
+    getSpawnedBy(): Promise<Principal | null>;
+    /** The verified IDKitResult, verbatim, as World's /api/v4/verify accepted it (null if
+     *  unverified). `Result<opt Text>` is TWO WRAPPERS: an envelope around an option. Unwrap the
+     *  envelope, THEN take the option — reading `result.length` on `{Ok:[…]}` gives `undefined`,
+     *  which silently reads as "absent" for a verified engram and a refused caller alike. */
+    getWorldIdVerification(): Promise<string | null>;
     initBackup(dbType: string, backupType: BackupType, parentBackupId: string | null, sha256: string, backupLabel: string | null): Promise<string>;
     pushBackupChunk(backupId: string, chunkIndex: number, data: Uint8Array): Promise<void>;
     finalizeBackup(backupId: string): Promise<void>;
     abortBackup(backupId: string): Promise<void>;
+    /**
+     * Every backup this engram holds, newest-first as the store orders them.
+     *
+     * Throws on refusal rather than returning []. An empty backup list is a claim about the engram;
+     * "you may not read this" is a claim about the caller, and conflating them here is how a
+     * destructive restore gets invited.
+     *
+     * ⟨0.16.0, L3⟩ `dbTypeFilter` LEFT THE WIRE and stayed in this signature. The census retired the
+     * canister-side filter; keeping the parameter here means no caller loses the ability to ask
+     * "backups of this database", and the filtering happens over a page that already contains every
+     * backup — the store's own cap is far below one page, so a local filter cannot hide a row on a
+     * page nobody fetched. If that ever stops being true, this must page rather than filter.
+     */
     listBackups(dbTypeFilter?: string): Promise<BackupMetadata[]>;
     pullBackupChunk(backupId: string, chunkIndex: number): Promise<Uint8Array>;
+    /** One backup's metadata by id. Kept alongside listBackups/pullBackupChunk because
+     *  RECOVERY-RUNBOOK §"Restore" names exactly that chain: list or fetch the metadata, pull each
+     *  chunk, then check the reassembled sha256 against it before applying anything. A restore that
+     *  cannot state the hash it expected is not a restore. */
     getBackupMetadata(backupId: string): Promise<BackupMetadata>;
-    deleteBackup(backupId: string): Promise<void>;
     latestBackupMatchesHash(dbType: string, sha256: string): Promise<BackupMetadata | null>;
     /** Encrypt a backup payload IFF this engram is in Private mode — the SAME toggle that governs
      *  memory files governs backups (encrypt files ⇒ encrypt backups). Produces a whole-blob
@@ -304,16 +367,30 @@ export declare class EngramClient {
      *  Content-driven (not flag-driven), so a plaintext / legacy backup passes through unchanged
      *  regardless of the current mode. Returns the original DB bytes, ready to write to disk. */
     decryptBackupPayload(bytes: Uint8Array): Promise<Uint8Array>;
-    storageStats(): Promise<StorageStats>;
     /** Warm the vetKeys memory-encryption key cache (one vetKD derivation). Optional —
      *  read/append derive lazily on first use. */
     initEncryption(): Promise<void>;
     /** Drops in-memory AND persisted key material (the "assume compromise" lever). */
     clearEncryptionCache(): Promise<void>;
     /** Sync the write-time encryption mode from the canister flag (once, cached),
-     *  unless an explicit `encryptMemory` was given at construction. */
+     *  unless an explicit `encryptMemory` was given at construction.
+     *
+     *  READS `status().encryptionEnabled`, not the former `isEncryptionEnabled()` — the surface diet
+     *  (R3, 2026-08-17) removed that method because `status()` already returns the SAME
+     *  `memoryEncryptionEnabled` variable, unconditionally, to the same anonymous audience: status()
+     *  redacts only `owner` and `cyclesBalance` behind its `isAuthorized` check, and
+     *  `encryptionEnabled` sits outside that branch.
+     *
+     *  THE EXTRA BYTES ARE PAID ONCE PER CLIENT, NOT ONCE PER WRITE. This is the sync-ONCE path:
+     *  `encryptionModeSynced` short-circuits every later call, and it is already true at
+     *  construction when `encryptMemory` was passed — so a client that writes a thousand times
+     *  fetches the status record at most once, where before it fetched a bool at most once. Caching
+     *  the record itself would buy nothing here and would make every OTHER status field silently
+     *  stale for the client's lifetime. */
     private ensureEncryptionMode;
-    /** Whether this engram has memory encryption enabled (reads the canister flag). */
+    /** Whether this engram has memory encryption enabled (reads the canister flag, uncached).
+     *  Serves `status().encryptionEnabled` — see ensureEncryptionMode for why the singleton read is
+     *  gone. Deliberately NOT cached: this method's whole job is to answer "what is it now". */
     isMemoryEncryptionEnabled(): Promise<boolean>;
     /** Owner-only: turn memory encryption on/off on the canister. Updates the local
      *  write mode immediately. Turning ON does not re-encrypt existing files — call
@@ -344,108 +421,37 @@ export declare class EngramClient {
         synced: number;
         failed: number;
     }>;
-    registerOperator(inviteCode: string): Promise<OperatorRecord>;
-    getProtectedPaths(): Promise<string[]>;
-    /** The caller's OWN payment approval requests (not owner-only listApprovalRequests). Poll this after an
-     *  over-limit payment returns approvalPending: when the owner raises the spending limit, the request
-     *  flips to `Approved` and the operation can be retried. Operator-safe (returns only your own requests). */
-    getMyApprovalRequests(): Promise<ApprovalRequest[]>;
-    /**
-     * Create a pre-configured Ic402Client for auto-payment operations.
-     * The client handles 402 → ICRC-2 approve → retry automatically.
-     */
-    createPaymentClient(options?: {
-        autoPayment?: boolean;
-        ledger?: string;
-    }): Ic402Client;
     /**
-     * Auto-pay bridge for the engramx x402 methods. The stock ic402 client injects the
-     * payment signature into the LAST argument, but the engramx canister appends
-     * `rationale` + `approvalId` AFTER `paymentSig` (for the owner approval workflow), so the
-     * signature must land at a FIXED index, not last. Flow: call with no sig → on
-     * #paymentRequired, icrc2_approve the amount (+ fee buffer) → build the ICP payment
-     * signature (a nonce-carrier; the real authorization is the ICRC-2 allowance the canister
-     * spends via transfer_from) → retry with the sig at `sigIndex`. Returns the raw canister
-     * result; the caller unwraps ok/error/approvalPending.
-     */
-    private payAndCall;
-    /**
-     * Get paid content with auto-payment. Handles #paymentRequired → approve → retry.
-     * @param contentId Content identifier
-     * @param options Optional ledger override
-     */
-    getContentWithPayment(contentId: string, options?: {
-        ledger?: string;
-    }): Promise<ContentDelivery>;
-    /**
-     * Open a streaming payment session with auto-escrow and voucher signing.
-     * Returns a SessionHandle that auto-signs vouchers on each call.
+     * Redeem an invite as the key for this engram, enrolled under the agent's lasting key (`root`).
      *
-     * Usage:
-     *   const session = await engram.openPaymentSession({ maxDeposit: 50_000n });
-     *   const file = await session.call('sessionReadMemory', ['SOUL.md']);
-     *   const receipt = await session.close();
-     */
-    openPaymentSession(options?: {
-        maxDeposit?: bigint;
-        autoClose?: boolean;
-        ledger?: string;
-    }): Promise<SessionHandle>;
-    registerService(name: string, description: string, serviceType: {
-        Sync: null;
-    } | {
-        Async: null;
-    }, pricing: {
-        Exact: bigint;
-    } | {
-        Upto: bigint;
-    } | {
-        Session: null;
-    }, verificationMethod: string, delivery: {
-        Poll: null;
-    } | {
-        Callback: null;
-    } | {
-        Both: null;
-    }, timeout: bigint, verifierCanisterId?: string, verificationKey?: Uint8Array, bindResult?: boolean): Promise<string>;
-    listServices(): Promise<unknown[]>;
-    /** Owner/operator view — includes disabled service drafts (others get enabled-only). */
-    listAllServices(): Promise<unknown[]>;
-    submitServiceRequest(serviceId: string, params: Uint8Array, paymentSig?: unknown, rationale?: string, approvalId?: string): Promise<{
-        jobId: string;
-    } | {
-        approvalPending: unknown;
-    }>;
-    /**
-     * Submit a paid service request with auto-payment (the marketplace counterpart of
-     * getContentWithPayment). Handles #paymentRequired → approve → retry, injecting the
-     * signature at the correct index for the engramx submitServiceRequest signature
-     * (serviceId, params, paymentSig, rationale, approvalId). Returns the jobId, or an
-     * approval-pending handle when the charge exceeds policy and the owner must approve.
-     */
-    submitServiceRequestWithPayment(serviceId: string, params: Uint8Array, options?: {
-        ledger?: string;
-        rationale?: string;
-    }): Promise<{
-        jobId: string;
-    } | {
-        approvalPending: unknown;
-    }>;
-    claimJob(jobId: string): Promise<void>;
-    submitJobResult(jobId: string, result: Uint8Array, proof?: Uint8Array, actualCost?: bigint): Promise<void>;
-    confirmJob(jobId: string): Promise<void>;
-    disputeJob(jobId: string, reason: string): Promise<void>;
-    getJobStatus(jobId: string): Promise<unknown | null>;
-    getJob(jobId: string): Promise<unknown | null>;
-    /**
-     * E1: enumerate a service's job summaries. Owner OR the service's own operator only — any other
-     * caller gets []. Summaries omit params/result/proof blobs (use getJob(jobId) for a full payload).
-     * Pass a statusFilter like `{ Pending: null }` to filter, or omit for all statuses.
+     * ⟨RESHAPED 2026-09-28, owner decision: one root key per agent, with an enrolled key per client⟩
+     * The root signs a statement naming this engram, this session key and this invite code
+     * (`signEnrolment`); the engram verifies it, stores the root on the agent record, and the
+     * registry keeps the agent's track record under the root — one record however many engrams.
+     * The root must NOT be this session key (the engram refuses a root enrolling itself): keep it off
+     * every engram and pair a fresh session key per engram.
+     *
+     * ⟨RESHAPED 2026-09-29⟩ Returns `{ agent, trackRecord }`. `trackRecord` is `{ NotRecorded }`
+     * with a plain sentence when the registry refused or could not be reached, so the engagement is
+     * not (yet) on the agent's track record; the pairing has succeeded either way.
+     *
+     * ⟨2026-09-29, ic402 2.16.1⟩ One statement, one call. The re-signing `pairEnrolled` this used
+     * went with the verifier fault it worked around: the engram's Ed25519 check no longer refuses
+     * valid signatures, so a refusal is final and is returned as it is.
      */
-    listJobs(serviceId: string, statusFilter?: unknown): Promise<unknown[]>;
-    getJobResult(jobId: string): Promise<Uint8Array | null>;
-    pollJobResult(jobId: string, maxAttempts?: number, intervalMs?: number): Promise<unknown>;
-    keccak256(data: number[]): Promise<number[]>;
+    pairAgent(inviteCode: string, root: Ed25519KeyIdentity): Promise<Pairing>;
+    /** ⟨0.16.0, L1⟩ Enveloped, and the unwrap was missing — same defect as `readAuditLog` above,
+     *  found by the same sweep. Returned `{Ok:{paths}} | {Err}` while declaring `string[]`, so a
+     *  caller iterating the result got nothing iterable and a refusal read as a truthy value.
+     *  The Ok arm is a RECORD (`{paths}`), not a bare vec, so the field is named here. */
+    getProtectedPaths(): Promise<string[]>;
+    /** The caller's OWN payment approval requests (not owner-only listApprovalRequests). Poll this after an
+     *  over-limit payment returns approvalPending: when the owner raises the spending limit, the request
+     *  flips to `Approved` and the operation can be retried. Agent-safe (returns only your own requests). */
+    getMyApprovalRequests(opts?: {
+        start?: number;
+        limit?: number;
+    }): Promise<ApprovalRequest[]>;
     clearCache(): void;
     getPrincipal(): Principal;
 }