@engramx/client 0.15.0 → 0.16.0-rc.4

package/README.md

@@ -4,9 +4,9 @@ TypeScript SDK for EngramX — persistent, decentralized memory for AI agents on
 
 ## What is this
 
-EngramX (Engram Externalized) stores your AI agent's memory, identity, session history, and wallet in an ICP canister. If the host machine dies, gets hacked, or moves — the agent resumes on a new machine with full state intact.
+EngramX (Engram Externalized) keeps an engram — its owner's memory, session history, wallet and record — in an ICP canister, and an AI agent paired with it reads and appends there. If the machine the agent runs on dies, gets hacked, or is replaced, the agent resumes on a new machine with the engram intact.
 
-This package is the client SDK that agents use to read and write their engram.
+This package is the SDK an agent uses to read and write the engram it is paired with.
 
 ## Install
 
@@ -14,6 +14,10 @@ This package is the client SDK that agents use to read and write their engram.
 pnpm add @engramx/client
 ```
 
+⟨2026-10-02⟩ A release candidate is published under npm's `next` tag — `pnpm add @engramx/client@next`
+— and `latest` is the last final release. A release candidate of 0.16.0 pairs only with a 0.16.0
+engram (see "What you can actually call today" below).
+
 ## Quickstart
 
 ```typescript
@@ -22,7 +26,7 @@ import { EngramClient } from '@engramx/client';
 const engram = new EngramClient({
   canisterId: 'xxxxx-xxxxx-xxxxx-xxxxx-xxx',
   sessionKeyPath: '~/.engramx/session.key',
-  clientLabel: 'my-agent', // identifies this host in the engram's cross-model reuse set
+  clientLabel: 'my-agent', // identifies this agent in the engram's cross-model reuse set
 });
 
 // At the START of a session: load everything the agent remembers, ready to inject as a
@@ -35,31 +39,99 @@ const ctx = await engram.startSession();
 console.log(`loaded ${ctx.includedFiles}/${ctx.totalFiles} files`);
 
 // AS THE AGENT WORKS: append (append-only; the canister concatenates the delta)
-const version = await engram.appendMemory('memory/daily.md', '## Notes\nSomething happened.');
+const receipt = await engram.appendMemory('memory/daily.md', '## Notes\nSomething happened.');
+// receipt = { version, seq, head }. `head` is the audit-chain head this write advanced to, hex —
+// the evidence the write landed, verifiable by a third party against the chain and its anchor.
+// Carry it forward: reading the file back later returns content, not proof.
 
 // Point reads: one file, or several at once
 const file = await engram.readMemory('MEMORY.md');
 const files = await engram.readMemoryBatch(['MEMORY.md', 'memory/daily.md']);
 
-// Wallet reads need canReadWallet, which the DEFAULT operator grant does NOT include — the
+// Wallet reads need canReadWallet, which the DEFAULT agent grant does NOT include — the
 // default is read + append memory, no wallet, deliberately. Ask the owner for a grant with
 // wallet access before uncommenting:
 // const balance = await engram.walletBalance();
 ```
 
+### What you can actually call today (2026-08-17)
+
+Two things in the snippet above are worth stating plainly rather than letting you discover them.
+
+**`sessionSystemPrompt()` / `startSession()` work, and nothing in this repository calls them.**
+They shipped in `0.15.0` and are in this release ⟨corrected 2026-10-02: this said 0.15.0 "is the
+current `latest` on npm", which stops being true the moment 0.16.0 is promoted, and this README
+ships inside the package⟩, so a new agent can call them today — notes elsewhere saying the
+published package predates this surface are stale. But every
+reference to them in this repo and in the dashboard is *teaching copy*: the connect guide, the
+landing page snippet, the docs page. Every shipped consumer — the CLI, the stdio MCP server's
+profile tools, the OpenClaw plugin — still reads memory the older way, with `readMemory`,
+`readMemoryBatch` and `listMemoryFiles`. So: the API is real and supported, the on-chain reuse
+accounting behind it is real, and you would be its first production caller. Treat the absence of an
+in-repo consumer as a reason to report what breaks, not as a warning that it does not work.
+
+The 2026-08-17 charter diet (below) deleted a lot of caller-less methods and **deliberately kept
+these two.** Zero in-repo callers was the reason to look at them; it was not the reason to decide.
+Three facts decided it. They are what `npx @engramx/mcp connect` *instructs* whoever builds a new
+SDK-lane agent to call, verbatim, in the guide the dashboard's connect page renders — deleting a method
+while still telling people to call it is the failure this whole exercise exists to prevent.
+`startSession()` is the only read on the **update** path, so it is the only one the canister can
+count toward the engram's cross-model reuse metric; a query read leaves no trace, because the IC
+discards query-path state changes. And they are the difference between "load everything this agent
+remembers" being one call or being a loop written by hand and subtly wrong.
+An entry point with no in-repo caller is unexercised, not dead.
+
+**`appendMemory` returns a receipt in this package, and a bare version number in `0.15.0`.** The
+receipt is part of the 0.16.0 interface break this package carries ⟨corrected 2026-10-02 for the
+0.16.0 release candidate's publish: this paragraph called the receipt a thing of "THIS tree" and the
+break "unreleased", which the publish makes false; on 2026-09-30 it had pointed at a changelog in
+the source, which is private during the beta⟩. Against `@engramx/client@0.15.0` the same call
+answers `Promise<bigint>`, and `listBackups` answers a bare array instead of unwrapping a refusal.
+An SDK from either side of that break does not interoperate with an engram from the other.
+⟨corrected 2026-10-02: this ended "so upgrade the canister first and the SDK second" — there is no
+upgrade across this break; 0.16.0 canisters are installed fresh, so pair this package only with a
+0.16.0 engram, and keep the SDK and the canisters on the same side.⟩
+
 ## Pairing
 
-Register your machine as an operator:
+Pair your agent with an engram:
 
 ```bash
-# Pair this host — register as operator and install the OpenClaw plugin
-pnpm dlx @engramx/client pair <invite-code> --engram <canister-id> --target openclaw
+# Pair the agent on this machine with the engram and install the OpenClaw plugin
+pnpm dlx @engramx/client@0.16.0-rc.4 pair <invite-code> --engram <canister-id> --target openclaw
 
-# Replacement host — after pairing, restore memory from the engram
+# Replacement machine — after pairing, restore memory from the engram
 pnpm dlx @engramx/client migrate --engram <canister-id> --recover
 ```
 
-`pair` generates `~/.engramx/session.key`, registers the operator, and installs the OpenClaw plugin. `migrate` then moves memory, saving a local checkpoint first — run `npx @engramx/client rollback` to undo. Its default direction pushes local memory files to the engram; `--recover` instead restores database backups, and memory files sync automatically on next OpenClaw startup.
+`pair` generates the key for this engram at `~/.engramx/session.key` (and, on the first pairing, the agent's lasting key at `~/.engramx/root.key`), pairs the agent — the CLI prints `Paired as an agent` — and installs the OpenClaw plugin. `migrate` then moves memory, saving a local checkpoint first — run `npx @engramx/client rollback` to undo. Its default direction pushes local memory files to the engram; `--recover` instead restores database backups, and memory files sync automatically on next OpenClaw startup.
+
+⟨2026-09-29⟩ From code, pairing is one call: `EngramClient.pairAgent(inviteCode, root)`, or sign the
+statement with `signEnrolment(root, engramId, key, inviteCode)` and call the engram's `pairAgent`
+yourself. The statement no longer carries a `nonce`, and `pairEnrolled` — which re-signed when the
+engram's signature check wrongly refused a valid statement — is no longer exported: ic402 2.16.1
+fixed that check, so a refusal is final. An invite stops working after three failed checks.
+
+### An engram of the agent's own ⟨2026-10-01⟩
+
+If the owner of the wallet allows it (a standing allowance they set for this agent on the Access
+page), the agent can open an engram of its own through the engram it works in. The owner may be a program. Whoever runs that program is the owner for every purpose on these pages.
+
+```bash
+npx @engramx/client open-engram --engram <canister-id>
+```
+
+The engram it works in pays to open it, from its own balance, and the agent's lasting key
+(`~/.engramx/root.key`, or `--root-key <path>`) owns what is opened. Approving is giving: what was
+paid in is the agent's from the moment the new engram exists, and nothing is taken back. The command
+reads the allowance first and stops, with nothing spent, when there is none; it never creates a
+lasting key; and it prints the engram's own sentence when the engram refuses. It then prints the
+owner kit's command that acts as the new engram's owner with the same file —
+`npx @engramx/owner --connect --key-file <that file> --registry <id>`, with both filled in — which
+mints an invite for an agent to pair into it. The agent's lasting key is an owner key for the engram
+it opened only; on the engram it works in it stays an agent. The agent's work in an engram its own
+key owns is never counted on its track record. From code: `EngramClient.getChildAllowance(key)`,
+`EngramClient.openChildEngram()`, or `openEngram(options, { io })`, which is the whole command.
 
 ## Guardian API
 
@@ -72,10 +144,145 @@ Internet Identity authentication. The SDK exposes the read-only side:
 const guardians = await engram.listGuardians();
 ```
 
-The SDK runs on operator-credentialed agent hosts and intentionally does NOT
-expose owner-only methods (writeMemory, addGuardian, setProtectedPaths,
-setPaymentPolicy, resetMyEngram, etc.). Owner workflows belong in the
-dashboard at engramx.ai.
+## The charter — who this SDK is for
+
+`EngramClient` runs **on the machine an agent runs on, with that agent's key**. An agent is an AI
+agent: a software program, not a person acting on someone's behalf. It is the append-only lane: read
+memory, append to it, run backups, pay for services. The owner lane is a separate package
+(`@engramx/owner`) so that an agent's machine never has owner powers to leak — that split is the
+product, not packaging taste. ⟨2026-10-01⟩ An engram the agent opened with `open-engram` is
+the one exception, and it is the agent's own: its lasting key owns that engram. Over the engram it
+works in, it is still an agent.
+
+The lines that hold, unconditionally:
+
+- The most dangerous owner primitives are **not here and will not be**: `writeMemory` (whole-file
+  overwrite), `addGuardian`, `setProtectedPaths`, `setPaymentPolicy`, `resetMyEngram`. Those live in
+  the dashboard at engramx.ai and in `@engramx/owner`.
+- Nothing on this class can widen its own grant. Every method is still gated in the canister by the
+  agent record the owner minted; the SDK is a convenience over a wire, never an authority.
+
+**The class matched its charter on 2026-08-17.** An audit on 2026-08-16 counted 94 public methods,
+of which 23 had a real (non-test) caller anywhere. The rest had accumulated: roughly two dozen
+owner-console methods and a nearly complete ic402 marketplace library, unused by any shipped surface
+— including the dashboard they deferred to. They were gated in the canister, so their presence
+widened nobody's authority; what it did was make this README's claim about the SDK false. The owner
+ratified the diet and it has landed: **94 public methods → 49**, and the Candid interface this SDK
+declares to the canister went from 108 method names to 39.
+
+**What left, so you can find it if you were calling it.**
+
+> **⟨CORRECTED 2026-08-26.⟩** This paragraph used to say the methods behind *every* name below were
+> "LIVE and unchanged — this removed the SDK's wrapper, not the surface", with `keccak256` as the
+> single exception. Measured against the served `.did` files at 0.16.0, that was wrong for **29 of
+> the 45 names**: 15 moved to the market canister, 14 are gone from both, and of the 16 that are
+> still on the engram some were renamed. A reader following the old sentence would have built a raw
+> Candid actor against methods that reject with `IC0536 method not found`, from a README that told
+> them the surface was untouched. The four groups below are measured, not asserted.
+
+**1. Still on the engram — a raw Candid actor or `@engramx/owner` reaches these.** Only the SDK
+wrapper went. *(16 names)*
+
+`listMemoryLog`, `exportMemoryRange`, `previewCondense`, `applyCondense`, `listMemoryExportReceipts`,
+`listCondenseCheckpoints`, `repudiateMemoryWrite`, `getAgentWriteReview`,
+`markAgentWritesReviewed`, `ownerWithdraw`, `deleteBackup`, `openSession`, `sessionReadMemory`,
+`sessionAppendMemory`, `getEngramCard`, `getEvmAddress`
+
+⟨2026-09-29⟩ Three of these are served under new names since the vocabulary change: the SDK's
+`getOperatorWriteReview`, `markOperatorWritesReviewed` and `getAgentCard` are the engram's
+`getAgentWriteReview`, `markAgentWritesReviewed` and `getEngramCard` (the vocabulary change: owner,
+agent, guardian).
+
+**2. Renamed on the engram — the capability survives under a new name.** *(4 names)*
+
+| you called | call instead |
+|---|---|
+| `getRepudiations` | `listRepudiations` |
+| `storageStats` | `getStorageStats` |
+| `getPaymentRequirements` | `previewOpenSession` |
+| `requestSession` | `previewOpenSession` |
+
+**3. Moved to the MARKET canister — which is NOT DEPLOYED at 0.16.0.** The commerce surface was
+extracted from the engram into a separate canister, and that canister is deliberately withheld from
+this release. **These names are unreachable today at any address**, and two were renamed in the move
+as well, so they will not answer even once a market exists. *(15 names)*
+
+`endSession`, `forceCloseSession`, `uploadContent`, `listContent`, `getContent`, `deleteContent`,
+`createEndpoint`, `listEndpoints`, `getRevenueSummary`, `registerService`, `claimJob`,
+`submitJobResult`, `listJobs`, `getJobStatus`, `getPaymentPolicy`
+— plus `listAllServices` → `listServices` and `getEndpointPurchases` → `listEndpointPurchases`,
+and `uploadContentChunked` / `getContentWithPayment`, whose jobs are now done by `uploadContent`
+and `getContent` there.
+
+**4. Gone entirely — no canister serves these and none is planned.** *(the remainder)*
+
+`assembleMemoryArchive`, `exportMemoryArchive`, `openPaymentSession`, `createPaymentClient`,
+`submitServiceRequest`, `keccak256`. `getOwnerEvmAddress` folded into `getEvmAddress`.
+
+⚠ **`openSession` is on the engram and `endSession` is on the withheld market.** If you open a paid
+session today there is no served method to close it. That asymmetry is a known open issue, not a
+documentation error — do not build a paid flow on it yet.
+
+⟨CORRECTED 2026-09-30⟩ "There is no served method to close it" is untrue: the engram serves
+`closeSession`, called by whoever paid for the session (it settles what was spent and refunds the
+rest), and `sysForceCloseSession`, the owner's close for a session whoever paid for it abandoned. The market's
+`endSession` was never the way to close an engram's session.
+
+| family | removed from this class |
+|---|---|
+| Memory archive (owner-only on the canister) | `listMemoryLog`, `exportMemoryRange`, `previewCondense`, `applyCondense`, `listMemoryExportReceipts`, `listCondenseCheckpoints`, `assembleMemoryArchive`, `exportMemoryArchive` |
+| Dispute + review | `repudiateMemoryWrite`, `getRepudiations`, `getOperatorWriteReview`, `markOperatorWritesReviewed` |
+| Owner money + storage | `ownerWithdraw`, `storageStats`, `deleteBackup` |
+| ic402 sessions | `getPaymentRequirements`, `requestSession`, `openSession`, `sessionReadMemory`, `sessionAppendMemory`, `endSession`, `forceCloseSession`, `openPaymentSession`, `createPaymentClient` |
+| ic402 content store | `uploadContent`, `uploadContentChunked`, `listContent`, `getContent`, `getContentWithPayment`, `deleteContent` |
+| x402 endpoint registry | `createEndpoint`, `listEndpoints`, `getEndpointPurchases`, `getRevenueSummary` |
+| Marketplace seller side | `registerService`, `listAllServices`, `submitServiceRequest`, `claimJob`, `submitJobResult`, `listJobs`, `getJobStatus` |
+| Misc reads | `getPaymentPolicy`, `getAgentCard`, `getEvmAddress`, `getOwnerEvmAddress` |
+| Module exports | `loadBootstrapConfig` / `saveBootstrapConfig` (no importer in either repo; `saveBootstrapConfig` reached `writeMemory` through an `as unknown as` cast around the very surface this class withholds); the `Vault*` deprecation aliases; the blind `@ic402/client` re-export block — depend on `@ic402/client` directly if you want it, and pin its version yourself |
+
+**`keccak256` is the exception: there is no canister method to fall back to** *(corrected
+2026-08-17 — this row sat in the table above under the claim that its canister method was live,
+which was false)*. The engram removed the public `keccak256` query on 2026-08-17 in the same diet.
+It was a consensus round trip, paid for and replicated, to hash bytes the caller already holds, so
+**compute it locally instead** — `import { keccak256 } from 'viem'` (what the EVM e2e suite already
+does), or any keccak library in your language. The Motoko library function
+(`Ic402.EvmAddress.keccak256`) is untouched and still backs the in-canister EIP-191/EIP-712 digests;
+only the public door is gone. Nothing you can compute locally changed value.
+
+One thing was **added**, and it is verification-side: `verifyActionReceipt` (with `actionMessage`,
+`actionFields` and the `ActionAuth` type) is now exported from the package entry point. The party
+who needs to check an owner-action receipt is whoever checks the record, reading the audit log, not
+the party that signed it — and until now the only way to reach that verifier was through `ownerWithdraw`, a
+method for signing one. *⟨2026-10-01⟩* `verifyActionReceipt` checks a receipt exactly as the engram
+does — strict RFC 8032, refusing a small-order key, a non-canonical point and a signature with S ≥ L
+— so a receipt verifies here if and only if the engram would have accepted it.
+
+One thing was **fixed** on the way past. The SDK declares a subset of the engram's Candid interface,
+and `getEncryptedMemoryKeyForEpoch` was missing from it. `encryption.ts` feature-detects that method
+and, not finding it, refused post-key-rotation content with *"this engram predates epoch-aware
+derivation"* — a sentence that was false for every engram, because the absence was in this package,
+not on the canister. Declaring the name makes the detect able to succeed.
+
+**One family that should have gone did not: the encryption owner controls.** `setMemoryEncryption`,
+`migrateMemoryToEncrypted` and `migrateMemoryToPlaintext` are owner-shaped by every test above — the
+toggle is owner-gated and the migrations rewrite whole files through `writeMemory`, which this class
+does not expose. They stayed because the encryption runbook instructs whoever migrates an engram to run
+`EngramClient.migrateMemoryToEncrypted()` **by name**, under a section of cautions worth keeping.
+Deleting a method a runbook tells people to call, while the runbook still tells them to call it, is
+worse than the blemish. Moving the family to `@engramx/owner` is a two-repo change: the doc rider
+first, then the methods.
+
+**The removals are a break.** A method this class no longer has fails at the call site, loudly,
+with a `TypeError`; a method the SDK no longer *declares* to the canister fails as a catchable
+`IC0536` reject rather than a decode trap. Neither corrupts data, and both ride the next interface
+cut rather than a patch release. `@engramx/client@0.15.0` on npm still has all of them.
+
+**What survives, and the rule that keeps it that way.** Memory core, session start, history and
+ranged/versioned reads, `reviseMemory`, the audit and certified-head reads, guardian and
+approval-request reads, an agent's key-hash rotation, the whole backup lane, and the BUYER half of the
+marketplace: `listServices` → `submitServiceRequestWithPayment` → `pollJobResult`/`getJob` →
+`getJobResult`, with `confirmJob`/`disputeJob` to settle. From here, no method returns to this class
+without a named caller. "A seller might want it" is how the last two dozen got here.
 
 ## Backup API
 
@@ -104,6 +311,13 @@ const backups = await engram.listBackups('sqlite');
 const data = await engram.pullBackupChunk(backupId, 0);
 ```
 
+`listBackups` **throws on refusal rather than returning `[]`.** An empty array is a claim about the
+engram ("you have no backups"); a refusal is a claim about the caller ("you may not read this"), and
+conflating them is how a destructive restore gets invited. Note that listing needs `canReadBackup`,
+which the default connect-an-agent grant leaves unset — `initBackup`/`pushBackupChunk` need only
+`canAppendMemory`, so an agent can *write* backups it cannot *list* until the owner widens the grant.
+The refusal names the missing permission.
+
 ## Verify canonical lineage
 
 An engram's own `getSpawnedBy()` is a self-report — any fork can claim any spawner.
@@ -128,24 +342,39 @@ const verdict = await verifyCanonicalLineage(engramId, agent);
 //   false on a managed engram usually just means one release behind, not suspect.
 ```
 
-The canonical registry id ships in the SDK as `CANONICAL_REGISTRY_CANISTER_ID`
-(empty until the production fleet is live — while empty, calls without an explicit
-registry report `'indeterminate'` by design). Pass `{ registryId }` to ask a
-different fleet (e.g. staging); the answer is then _that fleet's_ testimony, not
-canonicity.
+The canonical registry id ships in the SDK as `CANONICAL_REGISTRY_CANISTER_ID`; it is set to the
+live production registry, so a call with no explicit registry asks the canonical fleet. (If it were
+ever empty again, such a call would report `'indeterminate'` by design — the SDK never guesses at
+canonicity.) Pass `{ registryId }` to ask a different fleet (e.g. staging); the answer is then
+_that fleet's_ testimony, not canonicity.
 
 ## OpenClaw Integration
 
-The `--target openclaw` option on `pair` handles plugin installation and `openclaw.json` configuration automatically. For manual setup or customization, see [integrations/openclaw/README.md](../../integrations/openclaw/README.md).
+The `--target openclaw` option on `pair` handles plugin installation and `openclaw.json` configuration automatically. For manual setup or customization, see the README of the `@engramx/openclaw` package on npm.
+
+## Maturity of the payment and identity surfaces
+
+Verified against the canister interface on 2026-08-16. "Stubbed" was doing too much work here, so
+each surface now says what it actually does.
 
-## Roadmap
+| Surface | State |
+|---|---|
+| **x402 payments — Internet Computer rail** | **Not reachable at 0.16.0.** ICRC-2 approve-and-transfer in ckUSDC. `MarketClient.createJob` settles at submit time and is what the stdio MCP money tools call; it addresses the market canister, which is not in this release (section 3 above). |
+| **x402 payments — EVM rail** | **Implemented, unfunded on mainnet.** EIP-3009 USDC across the five chains in `Env.mo`. Signing and settlement paths exist; there is no funded production traffic, so treat it as untested in anger. |
+| **World ID** | **Live**, as shipped: proof submission, RP-context and verification reads, and the HTTP-outcall transform are all on the interface, with a wired dashboard. |
+| **ERC-8004 listing of the engram** | **Sign-only.** The canister signs its own registration transaction (`signEngramRegistration`) for you to broadcast; it lists the engram, never an agent. It does not broadcast, and it does not track registration state. |
+| **Autonomous outbound spending (tECDSA)** | **Served, inside the owner's limits.** The engram signs stablecoin payment authorisations on EVM chains on an agent's request (`signX402Payment`), within the per-agent limits, the engram-wide daily ceiling and the daily signature count; the signing key is a threshold key derived to the canister, so no single party holds it. ⟨Corrected 2026-09-30. This row said "Dormant by choice. Single-key custody is a total-loss risk; not funded on mainnet." — untrue of the code: the path is live and the key is threshold-derived. What is still yours to do is fund the address you mean to pay from.⟩ |
 
-These features are stubbed and available in the canister interface but not yet fully implemented:
+⟨CORRECTED 2026-09-30⟩ The first row said "Live" and listed two tokens besides ckUSDC. The buyer path
+it names moved to `MarketClient`, which pays in ckUSDC (its default ledger is the ckUSDC ledger), and
+the market it pays is enrolled in the local environment only (`icp.yaml`, `environments`).
 
-- **ERC-8004 Agent Identity** — threshold ECDSA-derived Ethereum address
-- **x402 Payment Protocol** — autonomous HTTP-based payments
-- **World ID** — proof-of-personhood for engram owners
+⟨CORRECTED 2026-09-30, same day⟩ The first row then named `MarketClient.submitServiceRequestWithPayment`.
+`MarketClient` has no method of that name: its paying call is `createJob`, and that is what the stdio
+MCP money tools call. `submitServiceRequestWithPayment` and `pollJobResult`, in the charter section
+above, are the buyer path's names from before it moved to `MarketClient`; there they name the family,
+not methods any class serves today.
 
 ## License
 
-MIT
+[Apache-2.0](LICENSE) — the same as every EngramX package.