@engramx/idl 0.16.0-rc.5 → 0.16.0-rc.7

package/dist/engram.did

@@ -220,11 +220,16 @@ type Result_8 =
    Err: Error;
    Ok: nat;
  };
-type Result_70 = 
+type Result_71 = 
  variant {
    Err: Error;
    Ok: AgentRecord;
  };
+type Result_70 = 
+ variant {
+   Err: Error;
+   Ok: Eip712Registration;
+ };
 type Result_7 = 
  variant {
    Err: Error;
@@ -233,47 +238,47 @@ type Result_7 =
 type Result_69 = 
  variant {
    Err: Error;
-   Ok: Eip712Registration;
+   Ok: record {activatesAtNs: int;};
  };
 type Result_68 = 
  variant {
    Err: Error;
-   Ok: record {activatesAtNs: int;};
+   Ok: CondenseResult;
  };
 type Result_67 = 
  variant {
    Err: Error;
-   Ok: CondenseResult;
+   Ok: MemoryRangeExport;
  };
-type Result_66 = 
+type Result_65 = 
  variant {
    Err: Error;
-   Ok: MemoryRangeExport;
+   Ok: Page_21;
  };
 type Result_64 = 
  variant {
    Err: Error;
-   Ok: Page_21;
+   Ok: AgentWriteReview;
  };
 type Result_63 = 
  variant {
    Err: Error;
-   Ok: AgentWriteReview;
+   Ok: BackupMetadata;
  };
 type Result_62 = 
  variant {
    Err: Error;
-   Ok: BackupMetadata;
+   Ok: ChildAllowanceRow;
  };
 type Result_61 = 
  variant {
    Err: Error;
-   Ok: ChildAllowanceRow;
+   Ok: ChildOpening;
  };
 type Result_60 = 
  variant {
    Err: Error;
-   Ok: ChildOpening;
+   Ok: blob;
  };
 type Result_6 = 
  variant {
@@ -283,52 +288,52 @@ type Result_6 =
 type Result_59 = 
  variant {
    Err: Error;
-   Ok: blob;
+   Ok: EvmAddresses;
  };
 type Result_58 = 
  variant {
    Err: Error;
-   Ok: EvmAddresses;
+   Ok: AlertStatus;
  };
 type Result_57 = 
  variant {
    Err: Error;
-   Ok: AlertStatus;
+   Ok: MemoryHistory;
  };
 type Result_56 = 
  variant {
    Err: Error;
-   Ok: MemoryHistory;
+   Ok: MemoryRetentionPolicy;
  };
 type Result_55 = 
  variant {
    Err: Error;
-   Ok: MemoryRetentionPolicy;
+   Ok: OwnerConsole;
  };
 type Result_54 = 
  variant {
    Err: Error;
-   Ok: OwnerConsole;
+   Ok: record {paths: vec text;};
  };
 type Result_53 = 
  variant {
    Err: Error;
-   Ok: record {paths: vec text;};
+   Ok: SigningFloorStatus;
  };
 type Result_52 = 
  variant {
    Err: Error;
-   Ok: SigningFloorStatus;
+   Ok: SpendCeiling;
  };
 type Result_51 = 
  variant {
    Err: Error;
-   Ok: SpendCeiling;
+   Ok: SpendingPolicy;
  };
 type Result_50 = 
  variant {
    Err: Error;
-   Ok: SpendingPolicy;
+   Ok: StorageReport;
  };
 type Result_5 = 
  variant {
@@ -338,52 +343,52 @@ type Result_5 =
 type Result_49 = 
  variant {
    Err: Error;
-   Ok: StorageReport;
+   Ok: WalletBalances;
  };
 type Result_48 = 
  variant {
    Err: Error;
-   Ok: WalletBalances;
+   Ok: WorldIdConfig;
  };
 type Result_47 = 
  variant {
    Err: Error;
-   Ok: WorldIdConfig;
+   Ok: WorldIdRpContext;
  };
 type Result_46 = 
  variant {
    Err: Error;
-   Ok: WorldIdRpContext;
+   Ok: opt text;
  };
 type Result_45 = 
  variant {
    Err: Error;
-   Ok: opt text;
+   Ok: bool;
  };
 type Result_44 = 
  variant {
    Err: Error;
-   Ok: bool;
+   Ok: text;
  };
 type Result_43 = 
  variant {
    Err: Error;
-   Ok: text;
+   Ok: Page_20;
  };
 type Result_42 = 
  variant {
    Err: Error;
-   Ok: Page_20;
+   Ok: Page_19;
  };
 type Result_41 = 
  variant {
    Err: Error;
-   Ok: Page_19;
+   Ok: Page_18;
  };
 type Result_40 = 
  variant {
    Err: Error;
-   Ok: Page_18;
+   Ok: Page_17;
  };
 type Result_4 = 
  variant {
@@ -393,52 +398,52 @@ type Result_4 =
 type Result_39 = 
  variant {
    Err: Error;
-   Ok: Page_17;
+   Ok: Page_16;
  };
 type Result_38 = 
  variant {
    Err: Error;
-   Ok: Page_16;
+   Ok: CheckpointPage;
  };
 type Result_37 = 
  variant {
    Err: Error;
-   Ok: CheckpointPage;
+   Ok: Page_14;
  };
 type Result_36 = 
  variant {
    Err: Error;
-   Ok: Page_14;
+   Ok: Page_13;
  };
 type Result_35 = 
  variant {
    Err: Error;
-   Ok: Page_13;
+   Ok: Page_12;
  };
 type Result_34 = 
  variant {
    Err: Error;
-   Ok: Page_12;
+   Ok: Page_11;
  };
 type Result_33 = 
  variant {
    Err: Error;
-   Ok: Page_11;
+   Ok: Page_10;
  };
 type Result_32 = 
  variant {
    Err: Error;
-   Ok: Page_10;
+   Ok: ReceiptPage;
  };
 type Result_31 = 
  variant {
    Err: Error;
-   Ok: ReceiptPage;
+   Ok: Page_8;
  };
 type Result_30 = 
  variant {
    Err: Error;
-   Ok: Page_8;
+   Ok: LogPage;
  };
 type Result_3 = 
  variant {
@@ -448,52 +453,52 @@ type Result_3 =
 type Result_29 = 
  variant {
    Err: Error;
-   Ok: LogPage;
+   Ok: Page_6;
  };
 type Result_28 = 
  variant {
    Err: Error;
-   Ok: Page_6;
+   Ok: Page_5;
  };
 type Result_27 = 
  variant {
    Err: Error;
-   Ok: Page_5;
+   Ok: Page_4;
  };
 type Result_26 = 
  variant {
    Err: Error;
-   Ok: Page_4;
+   Ok: PaymentSignatureCounts;
  };
 type Result_25 = 
  variant {
    Err: Error;
-   Ok: PaymentSignatureCounts;
+   Ok: Page_2;
  };
 type Result_24 = 
  variant {
    Err: Error;
-   Ok: Page_2;
+   Ok: Page_1;
  };
 type Result_23 = 
  variant {
    Err: Error;
-   Ok: Page_1;
+   Ok: Page;
  };
 type Result_22 = 
  variant {
    Err: Error;
-   Ok: Page;
+   Ok: principal;
  };
 type Result_21 = 
  variant {
    Err: Error;
-   Ok: principal;
+   Ok: EngramSessionState;
  };
 type Result_20 = 
  variant {
    Err: Error;
-   Ok: EngramSessionState;
+   Ok: Pairing;
  };
 type Result_2 = 
  variant {
@@ -503,22 +508,22 @@ type Result_2 =
 type Result_19 = 
  variant {
    Err: Error;
-   Ok: Pairing;
+   Ok: CondensePreview;
  };
 type Result_18 = 
  variant {
    Err: Error;
-   Ok: CondensePreview;
+   Ok: vec BatchReadItem;
  };
 type Result_17 = 
  variant {
    Err: Error;
-   Ok: vec BatchReadItem;
+   Ok: MemoryByteChunk;
  };
 type Result_16 = 
  variant {
    Err: Error;
-   Ok: MemoryByteChunk;
+   Ok: EngramEscrowRecovery;
  };
 type Result_15 = 
  variant {
@@ -610,6 +615,7 @@ type RailHealth =
    freezeReservation: nat;
    memoryBytes: nat;
    paidVouchersConsumed: nat;
+   refundOwed: opt nat;
    sendHeadroom: nat;
    sessionsClosed: nat;
    sessionsClosing: nat;
@@ -1139,6 +1145,11 @@ type EngramSessionState =
    status: EngramSessionStatus;
    voucherCount: nat;
  };
+type EngramEscrowRecovery = 
+ record {
+   amountE6: nat;
+   blockIndex: nat;
+ };
 type Engram = 
  service {
    /// ⟨0.16.0⟩ `about()` — the ONE public projection, replacing `status()` and absorbing `metrics()`.
@@ -1170,7 +1181,7 @@ type Engram =
    /// nomination names. That check compares the caller inside the module, where
    /// test/key-replacement.test.mo runs it; this body names no roster gate, because the caller holds
    /// no role here until the move.
-   acceptAgentKeyNomination: (agentKey: principal) -> (Result_70);
+   acceptAgentKeyNomination: (agentKey: principal) -> (Result_71);
    /// Consensus transform for the alert webhook outcall: collapse the response to status-only so
    /// replicas agree regardless of response headers/body (we only care that the POST landed 2xx).
    /// 
@@ -1206,10 +1217,10 @@ type Engram =
                   };
       primaryType: text;
       verifyingContract: text;
-    }) -> (Result_69);
+    }) -> (Result_70);
    /// Owner-managed destination allowlist (D7). Additions LOOSEN and wait 24h; removals TIGHTEN
    /// and apply instantly — the ratified asymmetry, applied to the one mutable policy surface.
-   addEvmWithdrawDestination: (dest: text) -> (Result_68);
+   addEvmWithdrawDestination: (dest: text) -> (Result_69);
    /// ⟨0.16.0, L1⟩ THE ROLE-CONFLICT ARM, and why three refusals here are not the same refusal.
    /// 
    /// This method had five distinct ways to say no through one `text`, and a caller could only tell
@@ -1251,7 +1262,7 @@ type Engram =
    /// Gated on requireWritesNotPaused — unlike the export. This one destroys retained entries, which
    /// is exactly what a guardian pause exists to hold. No action alert is raised: the operation is
    /// owner-initiated, owner-only, and already chained into the audit log.
-   applyCondense: (toSeq: nat) -> (Result_67);
+   applyCondense: (toSeq: nat) -> (Result_68);
    /// Owner-only: activate a guardian who has registered against an invite.
    /// 
    /// Until this call the guardian is `#Pending` and can do NOTHING — registering is a claim, this
@@ -1322,13 +1333,13 @@ type Engram =
    /// 
    /// The write half also refuses while writes are PAUSED.
    backupInit: (dbType: text, backupType: BackupType, parentBackupId:
-    opt text, sha256: text, backupLabel: opt text) -> (Result_43);
+    opt text, sha256: text, backupLabel: opt text) -> (Result_44);
    /// Read one chunk of a finalized backup, by index.
    /// 
    /// ⚠ GATED ON `read_backup`, which is NOT the permission the upload half uses — that one is
    /// `canAppendMemory`. Holding one says nothing about the other, deliberately: taking a backup and
    /// carrying it away are different authorities.
-   backupPullChunk: (backupId: text, chunkIndex: nat) -> (Result_59) query;
+   backupPullChunk: (backupId: text, chunkIndex: nat) -> (Result_60) query;
    backupPushChunk: (backupId: text, chunkIndex: nat, data: blob) ->
     (Result_1);
    /// The OWNER cancels an agent's pending key nomination; the agent keeps its current key. Refused
@@ -1380,7 +1391,7 @@ type Engram =
    /// A principal that is already a GUARDIAN cannot become an agent — a guardian is an
    /// independent check on agents, so one wallet must not hold both.
    createAgentInvite: (name: text, permissions: AgentPermissions) ->
-    (Result_43);
+    (Result_44);
    /// Owner-only: mint an invite for a GUARDIAN — an independent check on agents, not a
    /// co-owner and not a recovery agent.
    /// 
@@ -1403,7 +1414,7 @@ type Engram =
    /// So an invite that fails to redeem for that reason is not a bad code. The rule exists because
    /// a check must be independent of the thing it checks.
    createGuardianInvite: (name: text, permissions: GuardianPermissions) ->
-    (Result_43);
+    (Result_44);
    /// OWNER-ONLY deletion of a stored backup.
    /// 
    /// ⚠ NOT THE SAME GATE AS THE REST OF THE FAMILY, and the asymmetry is deliberate: `backupInit`,
@@ -1459,7 +1470,7 @@ type Engram =
    /// 
    /// ⟨Marker added 2026-08-23; the census row said "L7 mark added per review" and no mark was at
    /// the site.⟩
-   ensureEvmReady: () -> (Result_43);
+   ensureEvmReady: () -> (Result_44);
    /// Record that log entries [fromSeq, toSeq] were served, and return the root that proves it.
    /// 
    /// This is the receipt ledgerfs Q2 requires before any of those entries may be condensed away.
@@ -1473,7 +1484,7 @@ type Engram =
    /// situation rather than a safety measure. It IS gated on requireMemoryAttached: a store that
    /// failed its integrity check must not attest anything it cannot vouch for.
    exportMemoryRange: (fromSeq: nat, toSeq: nat, authorFilter:
-    opt principal) -> (Result_66);
+    opt principal) -> (Result_67);
    /// ⟨0.16.0, L2.2 — renamed from `guardianFreezePayments`⟩ The prefix LIED about who may call it.
    /// The gate is `requireOwnerOrGuardian`, and an owner freezing their own payments is the ordinary
    /// case — the guardian is the exceptional one. A name that says otherwise sends an owner looking
@@ -1505,7 +1516,7 @@ type Engram =
    /// before this one. If any of them is wrong, this comment is where the argument should happen.
    freezePayments: () -> (Result_1);
    /// Delivery status + config readback. Owner-only (the URL is a secret).
-   getActionAlertStatus: () -> (Result_57) query;
+   getActionAlertStatus: () -> (Result_58) query;
    /// Agents need to know what they may revise, so they can read it too. Whole-value config, same
    /// carve-out as getProtectedPaths — and kept a SEPARATE method from it deliberately (L2.2): a
    /// protected path and a revisable path are opposite grants, and one accessor for both would be a
@@ -1513,7 +1524,7 @@ type Engram =
    /// 
    /// Refusal reason preserved from the trap: a grant is a power, and its absence and its
    /// concealment are different facts.
-   getAgentRevisablePaths: () -> (Result_53) query;
+   getAgentRevisablePaths: () -> (Result_54) query;
    /// OWNER-ONLY: every engagement's seat weeks on this engram, with the agent's root — the day it
    /// paired, the days of its first and last payment signature, a 64-week map whose bit 0 is the week
    /// of the last one, and how many were produced. Never an amount, a recipient or a nonce.
@@ -1524,7 +1535,7 @@ type Engram =
    /// order. Anyone else is refused by name (`#Refused getAgentSeatWeeks: …`), never answered with an
    /// empty page. Paged; `total` is every engagement ever paired here (a reset keeps the rows).
    /// Two rows can name one root: an agent paired again after it left is a second engagement.
-   getAgentSeatWeeks: (start: nat, limit: nat) -> (Result_64) query;
+   getAgentSeatWeeks: (start: nat, limit: nat) -> (Result_65) query;
    /// Owner: everything written into this engram by someone other than the owner since the last
    /// markAgentWritesReviewed() — agent appends/revisions AND paid-session appends (see
    /// qualifiesForReview for why those two families are recognised differently).
@@ -1532,7 +1543,7 @@ type Engram =
    /// them — the UI must page (markAgentWritesReviewed(?lastShownId)) and must NOT present 200
    /// as a total. `earliest` discloses ring eviction — if cursor < earliest, entries between them
    /// aged out of the ring (the CHAIN still proves total count; this view can't show their bodies).
-   getAgentWriteReview: () -> (Result_63) query;
+   getAgentWriteReview: () -> (Result_64) query;
    /// Why anchoring is or is not advancing. PUBLIC: ungated on purpose — detecting a stalled
    /// engram is the point, a gated read would fail-to-empty and hand a third party fabricated zeros,
    /// and none of these fields is a secret — `total` is already public via getCertifiedAuditHead.
@@ -1551,7 +1562,7 @@ type Engram =
    /// below serves the same head WITH the subnet certificate for a caller that needs to verify it
    /// was signed rather than asserted.
    getAuditHead: () -> (AuditHead) query;
-   getBackupMetadata: (backupId: text) -> (Result_62) query;
+   getBackupMetadata: (backupId: text) -> (Result_63) query;
    /// The cashier this engram recognises as its rent biller — `null` until the registry pushes one.
    /// 
    /// PUBLIC: a payer about to send money needs to know which cashier this engram will accept credit
@@ -1581,11 +1592,11 @@ type Engram =
    /// query's state writes are discarded when it returns, and the `denied` call first written here
    /// recorded nothing while reading as if it did. The refusal is loud in the reply instead. WHAT
    /// WOULD MAKE THIS WRONG: a reason to record who asked — then this becomes an update that says so.
-   getChildAllowance: (agentPrincipal: principal) -> (Result_61) query;
+   getChildAllowance: (agentPrincipal: principal) -> (Result_62) query;
    /// Owner-only, Billing-class: what opening an engram costs this engram, the balance below which an
    /// agent's request is refused, the balance now, and every agent's allowance. The console's cost
    /// sentence reads it. Cycles are owner-class information, as on the owner's console read.
-   getChildOpening: () -> (Result_60) query;
+   getChildOpening: () -> (Result_61) query;
    /// Derive the shared memory-encryption key, encrypted under the caller's transport
    /// public key. Gated to owner + read-agents (the same principals allowed to read
    /// memory). The client decrypts it locally with its transport secret key.
@@ -1610,7 +1621,7 @@ type Engram =
    /// cost. Stated here because L7 requires the reason be readable from the interface rather than
    /// inferred by opening the body — which is exactly what had to happen to write this line.
    getEncryptedMemoryKey: (epoch: opt nat, transportPublicKey: blob) ->
-    (Result_59);
+    (Result_60);
    /// ⟨0.16.0, owner ruling 2026-08-20 — option (a)⟩ `x402Support` REPORTS THE RAIL, not a constant.
    /// 
    /// The card's config hardcodes `x402Support = true`, answering a buyer's question with a fact
@@ -1709,7 +1720,7 @@ type Engram =
    /// It refuses rather than half-answers: if either address cannot be derived the reply is
    /// `#Err`, never a record carrying an empty string (ic402's `getEvmAddress` answers `""` on a
    /// failed derivation — that is fail-to-empty on a money surface, and it stops here).
-   getEvmAddress: () -> (Result_58);
+   getEvmAddress: () -> (Result_59);
    /// The owner's OWN EVM address, if they registered one — distinct from `getEvmAddress`, which is
    /// the address this canister derives for itself.
    /// 
@@ -1724,7 +1735,7 @@ type Engram =
    /// the management canister's `ecdsa_public_key`. A query cannot await, so the round-trip is the
    /// cost — stated here because L7 requires the reason be readable from the interface rather than
    /// inferred by opening the body.
-   getEvmSignerAddress: () -> (Result_43);
+   getEvmSignerAddress: () -> (Result_44);
    /// PUBLIC: where this chain begins, for the stranger deciding whether to trust it.
    /// 
    /// The fourth of the four evidence methods (`getAuditHead`, `getCertifiedAuditHead`,
@@ -1733,7 +1744,7 @@ type Engram =
    /// cannot verify it, and nothing here identifies anybody.
    getGenesisNote: () -> (GenesisNote) query;
    /// A guardian's own channel status (their URL is their secret — each guardian sees only theirs).
-   getGuardianAlertStatus: () -> (Result_57) query;
+   getGuardianAlertStatus: () -> (Result_58) query;
    /// The market this engram will accept signing requests from — `null` until the registry pushes
    /// one at spawn, which is why `requireMarket` refuses fleet-wide today.
    /// 
@@ -1763,7 +1774,7 @@ type Engram =
    /// never renumbered: the next page starts at the last version returned plus one. Defaults
    /// return the whole history of any file a pre-FD engram could have held.
    getMemoryHistory: (path: text, start: opt nat, max: opt nat) ->
-    (Result_56) query;
+    (Result_57) query;
    /// PUBLIC: the epoch alone, and deliberately nothing else (rotation study D4). A `rotatedAt[]`
    /// history would be a public, fleet-enumerable feed of when each owner terminated a trust
    /// relationship — readable by, among others, the party just terminated.
@@ -1804,7 +1815,7 @@ type Engram =
    /// Refusal reasons of both merge: an empty policy reads as "nothing is capped, every version kept
    /// forever" — a claim about what this engram will DESTROY — and an empty guard list reads as
    /// "nothing is held back".
-   getMemoryRetentionPolicy: () -> (Result_55) query;
+   getMemoryRetentionPolicy: () -> (Result_56) query;
    /// The metrics reader this engram answers — `null` until the spawning registry names one.
    /// 
    /// PUBLIC: an owner deciding whether to switch the read off needs to know who it is, and anyone
@@ -1827,7 +1838,7 @@ type Engram =
    /// was `nat`, then widened to `opt nat` so a refusal could be `null`, which broke every published
    /// client (rule 4) and bought a masked answer nobody had asked for — the census could not even
    /// find a consumer that read the masked `0`. Behind a gate there is nobody to mask it from.
-   getOwnerConsole: () -> (Result_54) query;
+   getOwnerConsole: () -> (Result_55) query;
    /// Owner + agents only (agents need it to avoid writing protected paths).
    /// 
    /// A NAMED RECORD, not a Page: the setter replaces this list wholesale, so there is no window to
@@ -1839,7 +1850,7 @@ type Engram =
    /// path on this engram is protected", and an agent consults this list precisely to avoid
    /// writing one — so a fabricated empty here does not merely misinform, it invites the write the
    /// list exists to prevent.
-   getProtectedPaths: () -> (Result_53) query;
+   getProtectedPaths: () -> (Result_54) query;
    /// Whether the metrics reader's read is answered — `true` from birth.
    /// 
    /// PUBLIC: the promise that an owner can switch this read off can be checked only if the switch
@@ -1848,7 +1859,7 @@ type Engram =
    /// Owner-only, Billing-class: the signing floor, the balance, one signature's price, and how many
    /// payment signatures the balance carries above the floor before `signX402Payment` is refused by
    /// name. The same numbers the check uses, so Billing can say only what the engram enforces.
-   getSigningFloor: () -> (Result_52) query;
+   getSigningFloor: () -> (Result_53) query;
    /// The registry that spawned this engram, if it recorded one.
    /// 
    /// PUBLIC: it is the provenance claim. An engram asserting it is part of a fleet, under that
@@ -1865,7 +1876,7 @@ type Engram =
    /// configuration, and the engram-wide total would also tell one agent how much the others spent.
    /// A refusal names this method (`Gated.gatedResult`) rather than answering null/0 — a ceiling of
    /// "none" and a spend of 0 are both real answers, so a fabricated one would be read as fact.
-   getSpendCeiling: () -> (Result_51) query;
+   getSpendCeiling: () -> (Result_52) query;
    /// Read the caps in force for a caller.
    /// 
    /// OWNER-ONLY, and this is where it diverges from the market's inbound twin, which is public.
@@ -1873,8 +1884,8 @@ type Engram =
    /// Here the engram serves no 402s at all: these caps are the owner's private custody
    /// configuration, and publishing them would tell any caller exactly how large a signing request
    /// can be before it needs an approval nobody is watching for.
-   getSpendPolicy: (caller: opt principal) -> (Result_50) query;
-   getStorageStats: () -> (Result_49) query;
+   getSpendPolicy: (caller: opt principal) -> (Result_51) query;
+   getStorageStats: () -> (Result_50) query;
    /// Timer arm-state. PUBLIC and deliberately so: these timers are self-arming to save cycles,
    /// and an optimisation nobody can verify is an optimisation nobody should trust. Cheap to read,
    /// leaks nothing (booleans about our own scheduling).
@@ -1898,6 +1909,10 @@ type Engram =
    /// because a persistent actor re-runs its init body BEFORE postupgrade restores stable sessions,
    /// so a predicate-gated arm would skip exactly the canisters that have live ones. The first tick
    /// disarms it. Still true minutes after an upgrade is a real bug — report it upstream.
+   /// ⟨2026-10-07, beside the paragraph above⟩ The session sweep's interval is 300 seconds now (the
+   /// owner's decision of that day; set in the actor body), so "one interval" is up to five minutes,
+   /// and true five minutes after an upgrade is still expected. True ten minutes after, with no session
+   /// open, is the bug.
    /// NOT the whole timer story. The hourly CYCLE timer — which also carries audit anchoring — is
    /// deliberately absent: it is a `transient let` armed unconditionally at init, so an "armed"
    /// boolean for it would read true forever and tell you nothing, exactly the false-positive the
@@ -1941,12 +1956,12 @@ type Engram =
    /// ⟨L7⟩ MARKER ADDED 2026-08-23, reasoning above UNCHANGED — this block already said "Stays an
    /// UPDATE, marked per L7: it awaits three ICRC-1 ledgers". It was marked in prose and invisible
    /// to any gate; the glyph is what `scripts/check-update-for-read.mjs` matches.
-   getWalletBalances: () -> (Result_48);
+   getWalletBalances: () -> (Result_49);
    /// Refusal reason preserved, and it is the clearest case of why a masked read is worse than no
    /// read: three empty strings with `configured = false` is a VALID-LOOKING answer meaning "this
    /// engram has no World ID configuration" — handed to a caller who merely lacks a grant. The
    /// fabrication is indistinguishable from the truth by construction.
-   getWorldIdConfig: () -> (Result_47) query;
+   getWorldIdConfig: () -> (Result_48) query;
    /// ⟨L7⟩ UPDATE, NOT QUERY: this awaits THREE system calls — `raw_rand()` for the nonce,
    /// `Call.signWithEcdsa` for the signature, and `worldIdRpPublicKey()` for the derived key. A
    /// query can do none of them.
@@ -1955,7 +1970,7 @@ type Engram =
    /// Valid iff the derived signer address (getWorldIdRpSignerAddress) is registered for this rp_id in
    /// the World Developer Portal. Short-lived (300s TTL, idkit-server's default) and single-purpose —
    /// it authorizes opening one verification request, nothing else.
-   getWorldIdRpContext: () -> (Result_46);
+   getWorldIdRpContext: () -> (Result_47);
    /// Owner-only: the EVM address derived from the engram's dedicated World ID RP signing key (the
    /// "worldid-rp" tECDSA path). Register THIS address as the rp_id's signer in the World Developer
    /// Portal — the engram never holds or exports a private key (only threshold shares exist, on the
@@ -1965,7 +1980,7 @@ type Engram =
    /// awaits `worldIdRpPublicKey()` (management `ecdsa_public_key`), and it calls `denied()` on
    /// refusal — a state write, which a query cannot perform. So even if the key were cached this
    /// could not become a query without silently retiring its denial record (ADR-0002's class).
-   getWorldIdRpSignerAddress: () -> (Result_43);
+   getWorldIdRpSignerAddress: () -> (Result_44);
    /// The verified IDKitResult, verbatim, as World's /api/v4/verify accepted it — the re-checkable
    /// artifact behind verifiedHuman. Role-gated because it carries the NULLIFIER.
    /// `Result<opt Text>` — and the double wrapper is the entire point, not redundancy.
@@ -1984,7 +1999,7 @@ type Engram =
    /// `///`, so the dead name was PUBLISHED in engram.did and pointed every client at a method the
    /// canister does not serve. The tombstones below and at `about()` are historical and correct as
    /// written; this one was present tense, which is the difference that matters.⟩
-   getWorldIdVerification: () -> (Result_45) query;
+   getWorldIdVerification: () -> (Result_46) query;
    /// ⟨0.16.0, L1⟩ THE EMERGENCY FAMILY. Every refusal below is `#Refused` or `#NotFound`, and the
    /// absence of a `#Conflict` here is the point: these are the calls someone makes while something
    /// is going wrong, and the only two answers that help are "you may not do this" and "there is
@@ -2059,7 +2074,7 @@ type Engram =
    /// 
    /// Owner-gated because it reports on custody posture, and answered as a Result so that a
    /// wrong-identity caller gets a refusal rather than a bare `false` that reads as "no address yet".
-   isEvmAddressCached: () -> (Result_44) query;
+   isEvmAddressCached: () -> (Result_45) query;
    /// Issue an OAuth authorization code. Called by an OAuth client's sign-in bridge
    /// (an `/auth/connector`-style route) after II authentication. The client then
    /// redirects the user's browser to `redirectUri` with `?code=<this>` so the
@@ -2067,7 +2082,7 @@ type Engram =
    /// 
    /// Owner-only: only the engram owner can authorize a Connector install.
    issueAuthCode: (redirectUri: text, scope: text, codeChallenge: text,
-    clientId: opt text) -> (Result_43);
+    clientId: opt text) -> (Result_44);
    /// ⟨0.16.0⟩ `getCycleSnapshotSource` DELETED — folded into `CycleSnapshot.source`, one label per
    /// ROW. A single label for a whole ring misattributes every row recorded under the other source,
    /// and the source flips by design (self-call first, balance on fallback). Its documentation of
@@ -2081,7 +2096,7 @@ type Engram =
    /// Refusal reason preserved, and it is the sharpest of this family: a masked `[]` reads as a
    /// DORMANT engram and corrupts retention math — a fabricated empty here does not just misinform a
    /// reader, it feeds a wrong number into a decision about destroying data.
-   listActivitySnapshots: (start: nat, limit: nat) -> (Result_42) query;
+   listActivitySnapshots: (start: nat, limit: nat) -> (Result_43) query;
    /// ⟨0.16.0⟩ THE PAGE EXEMPLAR. Trap → `#Refused`, bare array → `Result<Page<T>>` (L1 + L3).
    /// 
    /// The refusal prose that used to be `gatedTrap`'s `whyNotEmpty` argument is not lost — it is why
@@ -2096,7 +2111,7 @@ type Engram =
    /// 
    /// `withheld` is 0: this roster is owner-only in whole, so there is no partial-visibility case.
    /// A method that filters rows by caller sets it — see L1's row-level honesty rule.
-   listAgents: (start: nat, limit: nat) -> (Result_41) query;
+   listAgents: (start: nat, limit: nat) -> (Result_42) query;
    /// The GUARDIAN-audience projection of the agent roster — three fields, not the full record.
    /// 
    /// Two audiences, two methods (L1/L8), rather than one method masking fields by caller: a
@@ -2108,7 +2123,7 @@ type Engram =
    /// Refusal reason preserved: `[]` reads as "this engram has no agents", and this is the list a
    /// guardian consults BEFORE REVOKING ONE. A fabricated empty here does not merely misinform —
    /// it tells someone acting under emergency powers that there is nothing to act on.
-   listAgentsForGuardian: (start: nat, limit: nat) -> (Result_40) query;
+   listAgentsForGuardian: (start: nat, limit: nat) -> (Result_41) query;
    /// Owner-only: rows carry caller, amount, operation and free-text rationale. The SDK omits it.
    /// 
    /// The optional leading filter SURVIVES the L3 reshape — ratified (census tier-2 #8) rather than
@@ -2121,7 +2136,7 @@ type Engram =
    /// 
    /// Refusal reason preserved: `[]` reads as "nothing is awaiting the owner's decision".
    listApprovalRequests: (statusFilter: opt ApprovalStatus, start: nat,
-    limit: nat) -> (Result_28) query;
+    limit: nat) -> (Result_29) query;
    /// ⟨0.16.0⟩ `total` IS THE HEAD COUNTER, and on this method that is the entire point.
    /// 
    /// The audit log is a bounded RING: it trims its tail, so "rows you can read" and "entries that
@@ -2141,7 +2156,7 @@ type Engram =
    /// For the owner and a guardian `withheld` is 0 and the page is the span. WHAT WOULD MAKE THIS
    /// WRONG: a reader who must see the whole record without being the owner or a guardian — the
    /// public certified head is the answer for integrity, and nothing else is.
-   listAuditEntries: (start: nat, limit: nat) -> (Result_23) query;
+   listAuditEntries: (start: nat, limit: nat) -> (Result_24) query;
    /// ⟨0.16.0, L1 + L3 — census-ruled⟩ THE TWO-MECHANISM EXCEPTION DISSOLVES.
    /// 
    /// This method used to answer THREE ways to one question: a list, an `#Err` text, and a trap,
@@ -2165,7 +2180,7 @@ type Engram =
    /// `dbTypeFilter` DIES on the wire (census). The capability does not: `EngramClient.listBackups`
    /// keeps its optional filter and applies it to the page, so no caller loses the ability to ask
    /// "backups of this database" — it stops being a thing the canister has to page around.
-   listBackups: (start: nat, limit: nat) -> (Result_39) query;
+   listBackups: (start: nat, limit: nat) -> (Result_40) query;
    /// List all bearer tokens — Active, Revoked, and Expired. Owner uses this in
    /// the dashboard to show installed Connectors (claude.ai, Claude Desktop, etc.).
    /// Refusal reason preserved from the trap: `[]` reads as "no connector is installed on this
@@ -2175,7 +2190,7 @@ type Engram =
    /// `bearerTokenStore.list()` already resolves each token's status at read time (a token that
    /// merely stopped being used is reported `#Expired`, not a stale `#Active`), so the page carries
    /// the same honesty the store gained on 2026-08-17.
-   listBearerTokens: (start: nat, limit: nat) -> (Result_38) query;
+   listBearerTokens: (start: nat, limit: nat) -> (Result_39) query;
    /// The condense checkpoints in the retained log at or above `startSeq`, oldest first.
    /// 
    /// ⟨0.16.0, NEW⟩ The other half of the split above. A checkpoint is the only surviving record of a
@@ -2185,25 +2200,25 @@ type Engram =
    /// 
    /// Owner-only like every other archive surface, and for the same structural reason: these rows
    /// carry the chain positions and roots of entries whose paths were inside the hash preimage.
-   listCondenseCheckpoints: (startSeq: nat, max: nat) -> (Result_37) query;
+   listCondenseCheckpoints: (startSeq: nat, max: nat) -> (Result_38) query;
    /// ⟨0.16.0⟩ `metrics()` DELETED — absorbed by `about()`.
    /// 
    /// Two public projections of one canister (L2.2): `metrics()` and `status()` both answered "what
    /// is this engram like" and disagreed on which counters they carried, so a consumer had to fetch
    /// both and know which one owned each field. Every field here survives on `about()`, day-flooring
    /// included.
-   listCycleSnapshots: (start: nat, limit: nat) -> (Result_36) query;
+   listCycleSnapshots: (start: nat, limit: nat) -> (Result_37) query;
    /// Same `withheld` treatment as listMemoryFiles — the tombstone listing filtered reserved paths
    /// for non-owners just as silently, and a caller could not tell a filtered tombstone list from a
    /// complete one. Counted before slicing, so policy-hidden rows never blur into paging.
-   listDeletedMemoryFiles: (start: nat, limit: nat) -> (Result_35) query;
+   listDeletedMemoryFiles: (start: nat, limit: nat) -> (Result_36) query;
    /// The registered shapes — E3: encodeTypeString is the display artifact, verbatim.
    /// Stays on the engram under B1 (hybrid): EIP-712 signing is custody, and custody does not leave.
    /// 
    /// Refusal reason preserved: `[]` reads as "this engram can sign nothing" — a claim about SIGNING
    /// AUTHORITY, which is not a thing to hand an unauthorized reader. The public trail of every
    /// registration remains the audit chain under getCertifiedAuditHead.
-   listEip712Types: (start: nat, limit: nat) -> (Result_34) query;
+   listEip712Types: (start: nat, limit: nat) -> (Result_35) query;
    /// Stays on the engram under B1 (hybrid): withdrawal custody does not leave.
    /// 
    /// NAMED item, not a `(Text, Int)` tuple. The Int is an activation time, and a bare Int beside a
@@ -2212,14 +2227,14 @@ type Engram =
    /// Refusal reason preserved, and it has two halves that matter separately: `[]` reads as "this
    /// engram may withdraw nowhere", OR — worse — as "no allowlist is in force", which is the
    /// opposite security posture. It also erases any pending 24h activation from view.
-   listEvmWithdrawDestinations: (start: nat, limit: nat) -> (Result_33) query;
+   listEvmWithdrawDestinations: (start: nat, limit: nat) -> (Result_34) query;
    /// Accessible by owner and guardians.
    /// 
    /// Refusal reason carried over from the trap, because it is the sharpest example of why this
    /// surface may not fail soft: `[]` reads as "this engram has nobody who can freeze payments or
    /// pause writes" — a claim about who can STOP it. A caller who cannot tell that from "you may not
    /// see the roster" has been told the engram is unguarded when it may be fully guarded.
-   listGuardians: (start: nat, limit: nat) -> (Result_32) query;
+   listGuardians: (start: nat, limit: nat) -> (Result_33) query;
    /// The export receipts in the retained log at or above `startSeq`, oldest first.
    /// 
    /// ⟨0.16.0, L3⟩ ONE LIST, ONE QUESTION. This method used to return receipts AND checkpoints
@@ -2235,7 +2250,7 @@ type Engram =
    /// 
    /// Read `MemoryRouter.ReceiptPage` before reading `page.total` as a receipt count. It is not one;
    /// it is the chain's length, and the declaration says why.
-   listMemoryExportReceipts: (startSeq: nat, max: nat) -> (Result_31) query;
+   listMemoryExportReceipts: (startSeq: nat, max: nat) -> (Result_32) query;
    /// ⟨0.16.0⟩ THE `withheld` EXEMPLAR — L1 names this exact method as the defect it fixes.
    /// 
    /// A non-owner's answer silently dropped every `config/` and `secrets/` row. Not "refused the
@@ -2251,7 +2266,7 @@ type Engram =
    /// Note the count is computed from the unfiltered list before slicing, so it reports rows hidden
    /// by POLICY, never rows merely off the end of this page — those are `total`'s job. Conflating
    /// the two would rebuild the ambiguity in a new place.
-   listMemoryFiles: (start: nat, limit: nat) -> (Result_30) query;
+   listMemoryFiles: (start: nat, limit: nat) -> (Result_31) query;
    /// One page of the memory log, seq-ordered, optionally narrowed to one author.
    /// 
    /// THE WINDOW IS THE CURSOR, and the page now states it. The window is
@@ -2277,7 +2292,7 @@ type Engram =
    /// with the disclosures that make the page verifiable — the hidden-bound defect the census itself
    /// names on previewCondense's row.
    listMemoryLog: (startSeq: nat, max: nat, authorFilter: opt principal) ->
-    (Result_29) query;
+    (Result_30) query;
    /// The caller's OWN spend-approval requests. ⟨0.16.0, L1 + L3 — fixed 2026-08-18⟩
    /// 
    /// Two defects in seven lines, and the first is the one this release exists to remove:
@@ -2294,7 +2309,7 @@ type Engram =
    /// to see, so `total` over their own rows is the honest count and nothing is hidden FROM them.
    /// (The unbounded MAP is filed separately — pruning an approval record destroys evidence of what
    /// was asked, which is a retention ruling rather than a shape fix.)
-   listMyApprovalRequests: (start: nat, limit: nat) -> (Result_28) query;
+   listMyApprovalRequests: (start: nat, limit: nat) -> (Result_29) query;
    /// The payer's own sessions, live ones first. PAYER-SCOPED: a caller sees only their own, which
    /// is why this needs no role — a session id is not a secret from the person who paid for it.
    /// 
@@ -2303,7 +2318,7 @@ type Engram =
    /// It took no arguments, and a cursor added after the freeze is an argument-list change every
    /// client would break on — the market paged its own pending withdrawals before its cut for the
    /// same reason. The order is the order sessions were opened.
-   listMySessions: (start: nat, limit: nat) -> (Result_27) query;
+   listMySessions: (start: nat, limit: nat) -> (Result_28) query;
    /// 
    /// ⟨0.16.0, L3⟩ Paged and enveloped like every other `list*`, and the envelope here is uniformity
    /// rather than gating: this method cannot refuse anybody, so `#Err` is unreachable on it. That is
@@ -2316,7 +2331,7 @@ type Engram =
    /// asked by strangers. `verifyEngramActiveOwner` on the registry answers only about the owner
    /// IT recorded, so this chain is what a caller composes with when currency matters — which it
    /// cannot do if it needs a role here.
-   listOwnershipTransfers: (start: nat, limit: nat) -> (Result_26) query;
+   listOwnershipTransfers: (start: nat, limit: nat) -> (Result_27) query;
    /// ⟨2026-09-29, the platform's question from the build review⟩ OWNER-ONLY: how many payment
    /// signatures each agent has obtained today, and the daily limit (200, `PaymentSignCap`). The
    /// owner's console stated the rule and showed no number, because nothing served one; a number it
@@ -2332,7 +2347,7 @@ type Engram =
    /// marketplace's one shared count today is in the reply's `marketplace` field, with the limit this
    /// engram enforces for it — beside the agents, never a row among them
    /// (`PaymentSignCap.marketplaceRow`). Null when no marketplace is set.
-   listPaymentSignatureCounts: (start: nat, limit: nat) -> (Result_25) query;
+   listPaymentSignatureCounts: (start: nat, limit: nat) -> (Result_26) query;
    /// Agent records removed by a reset. Each row is a NAMED record with the fields `principal`,
    /// `name`, `registeredAt` and `purgedAt` — read them BY NAME, never by position.
    /// ⟨2026-09-29, the vocabulary ruling: pairing is the one verb that admits an agent⟩ The field
@@ -2372,7 +2387,7 @@ type Engram =
    /// `invite` its enrolment named, and `ended` — why and on what day its engagement ended (its own
    /// earlier ending, or the reset) — the facts `resyncAgentEdges` re-sends. The stored rows are
    /// served as they are.
-   listPurgedAgents: (start: nat, limit: nat) -> (Result_24) query;
+   listPurgedAgents: (start: nat, limit: nat) -> (Result_25) query;
    /// ⟨0.16.0⟩ ONE ACCESSOR, folding `readReadLog` and `getDenialLog` — and the fold only became
    /// safe because of a change made earlier in this same leg.
    /// 
@@ -2434,7 +2449,7 @@ type Engram =
    /// on the chained record — the same `RecordView` filter, and `withheld` counts what it removed
    /// together with what `successFilter` removed. WHAT WOULD MAKE THIS WRONG: see `listAuditEntries`.
    listReadLog: (successFilter: opt bool, start: nat, limit: nat) ->
-    (Result_23) query;
+    (Result_24) query;
    /// Same visibility as listAuditEntries: the owner, this engram's agents, and ACTIVE guardians
    /// see disputes. An unauthorized read REFUSES — it does not return an empty list, because an
    /// empty list reads as "no disputes have been filed", which is a claim, not an absence of one.
@@ -2449,7 +2464,7 @@ type Engram =
    /// window — which says disputes exist without showing them, never "none have been filed". WHAT
    /// WOULD MAKE THIS WRONG: a ruling that an agent may see the disputes of its own writes; this would
    /// then have to look up each disputed version's writer, which it does not do today.
-   listRepudiations: (start: nat, limit: nat) -> (Result_22) query;
+   listRepudiations: (start: nat, limit: nat) -> (Result_23) query;
    /// Owner: advance the review cursor — "I have seen everything up to and including uptoAuditId"
    /// (null = everything at the current head). Bounded so the attestation can never cover entries
    /// the console did not render; clamped monotonic (the cursor never moves backward) and to the
@@ -2494,8 +2509,8 @@ type Engram =
    /// 
    /// WHAT WOULD MAKE THIS WRONG: an await added between `ChildAllowance.take` and the registry call; the
    /// registry's `CHILD_MIN_ATTACHED_CYCLES` moving without `CHILD_ATTACH_CYCLES`.
-   openChildEngram: () -> (Result_21);
-   openSession: (config: SessionConfig, sig: PaymentSignature) -> (Result_20);
+   openChildEngram: () -> (Result_22);
+   openSession: (config: SessionConfig, sig: PaymentSignature) -> (Result_21);
    /// Withdraw tokens to the owner's principal. This is the ONLY way to
    /// move tokens out of the engram to an external address, and the
    /// destination is always hardcoded to the owner.
@@ -2560,7 +2575,7 @@ type Engram =
    pairAgent: (arg: record {
                       code: text;
                       enrolment: Enrolment;
-                    }) -> (Result_19);
+                    }) -> (Result_20);
    /// ⟨0.16.0, L2.2 — renamed from `guardianPauseWrites`⟩ Same correction as freezePayments above:
    /// owner-or-guardian, and `resumeWrites` never carried the prefix either.
    pauseWrites: () -> (Result_1);
@@ -2582,7 +2597,7 @@ type Engram =
    /// 
    /// `unlocked` is the export-receipt gate ONLY. It is not a promise the condense will land: the
    /// history-budget delta is checked at commit time and can still refuse a short prefix.
-   previewCondense: (toSeq: nat) -> (Result_18) query;
+   previewCondense: (toSeq: nat) -> (Result_19) query;
    /// A quote for a session this caller has not opened and is not committed to — the intent a
    /// buyer signs against. Pure dry run, no state, no funds.
    /// 
@@ -2640,7 +2655,7 @@ type Engram =
    /// Both are now what they are: a single `#Err` for the whole call. `#Ok` still carries a row per
    /// path, each with its own Result — a refused RESERVED path sits beside a readable one, which is
    /// a genuine per-path fact.
-   readMemoryBatch: (paths: vec text) -> (Result_17) query;
+   readMemoryBatch: (paths: vec text) -> (Result_18) query;
    /// ⟨0.16.0⟩ `getMemoryRetentionGuards` DELETED — folded into `getMemoryRetentionPolicy` above.
    /// It was the second L2.1 array-returning `get*`, and separating it from the policy it modifies
    /// was the defect described there. Its own docs are preserved at the fold site.
@@ -2651,7 +2666,7 @@ type Engram =
    /// see it cannot know whether it has the whole range, which is how silent truncation gets
    /// reintroduced. Loop while `more` is true, advancing by the bytes actually returned.
    readMemoryBytes: (path: text, offset: nat, len: nat, version: opt nat) ->
-    (Result_16) query;
+    (Result_17) query;
    /// The escrow exit for a session whose settle cannot pay.
    /// 
    /// PAYER-ONLY, enforced inside the gateway, and deliberately not owner-triggered: the payer's own
@@ -2706,7 +2721,15 @@ type Engram =
    /// the transfer pays its own fee from the escrow. A session still reads `closing` only when its
    /// close trapped after one of its awaits, or an earlier version left it there, and of that one the
    /// line above still holds.
-   recoverEscrow: (sessionId: text, amountE6: nat) -> (Result_8);
+   /// 
+   /// ⟨2026-10-07, the owner's decision of that day⟩ WHAT IT ANSWERS: what came back. `amountE6` is
+   /// the ckUSDC base units transferred to the payer's own account (the amount asked, capped at the
+   /// session's unconsumed deposit; the transfer's fee comes out of the escrow on top), and
+   /// `blockIndex` is the ledger block of that transfer. Until this date it answered a bare `nat` that
+   /// was the block index alone, which read as the amount. If the session's record is removed before
+   /// the amount can be read back — a session closed in the same moment as the recovery and cleaned up
+   /// during its transfer — it answers `#Other` naming the block, never a guessed amount.
+   recoverEscrow: (sessionId: text, amountE6: nat) -> (Result_16);
    /// ⟨0.16.0, L1⟩ A REDEMPTION PATH, where the arm choice is a disclosure decision.
    /// 
    /// Four of these refusals are about the CODE and one is about the caller. The code arms restate
@@ -3373,7 +3396,10 @@ type Engram =
    /// The metrics reader the registry designated reads this engram's paid-rail health, in one call:
    /// the balance and the line it must stay above, the memory that line is computed from, the sessions
    /// by state, the escrow open sessions hold, the vouchers spent and the refused ones
-   /// (`RailHealth.RailHealth` says what each is, and what is never in it).
+   /// (`RailHealth.RailHealth` says what each is, and what is never in it). ⟨2026-10-08, ic402 2.18.0⟩
+   /// And `refundOwed`: the closed sessions whose refund failed and whose payer has not yet recovered
+   /// it — counted from the close, never read from the ledger; `opt` from birth, and null (an engram
+   /// that does not count) is never 0.
    /// 
    /// CALLER: the metrics reader the spawning registry named on this engram (`metricsReaderId`), and
    /// nobody else — the owner reads its balance through `getOwnerConsole`. Answered only while the