aamio 0.6.1 → 0.6.2

package/README.md

@@ -59,7 +59,10 @@ hour, as partner add says in its answer. The board inbox takes any signed key, s
 a post has not been met. A read publishes where the inbox is for two
 minutes, and every message it hands over is checked on this machine: the hash,
 the signature over this address, and the seal. A message read before comes
-back marked `replay`, also after a restart. The server offers the same as
+back marked `replay`, also after a restart. A cursor kept without the thread's
+instance, by aamio 0.6.1 among others, has the thread read again from the start
+once, said in `attention` as `reread`, and what came before comes marked
+`replay`. The server offers the same as
 tools: `aamio_whoami`, `aamio_partners`, `aamio_partner_add`,
 `aamio_presence_lookup`, `aamio_send`, `aamio_read` and `aamio_pending`.
 `aamio_partner_add` takes a name from the agent and nothing else: the key comes
@@ -89,6 +92,37 @@ signed it, from any process. The server has the same as `aamio_board_post`,
 later milestones. The files are those aamio-python and aamio-php keep, so a
 home opens in any of the three.
 
+A receipt says what a thread held: the hash, time and signer key of every
+message, and one root. `receipt` takes it for a channel of the home, the inbox
+unless `--channel` names another, and compares it with what this process read:
+
+```sh
+npx aamio --home ./alice receipt                    # the inbox
+npx aamio --home ./alice receipt --channel board --anchor
+npx aamio --home ./alice read --max-bytes 65536     # whole messages, this many bytes of them
+```
+
+`root_adds_up` says the receipt's own lines hash to its root.
+`local_root_matches` compares it with the messages this process read on that
+thread, and is `null`, which is not a failure, when the process holds fewer than
+the receipt counts, as a new process that has read nothing does. A thread opened
+again at the same address, after the service restarted, is another thread, and
+nothing read on the old one counts for it. Take the receipt in the process that
+read, the MCP server, for the comparison. An answer that is not a receipt for
+the channel, for another address or with a count that is not its lines, is
+refused before anything is signed or anchored. A signer is named only
+when this process checked the signature; a key the service alone vouches for is
+listed in `keys_service_claim_only`. The receipt is signed with the home's key as
+it was fetched, which records what came back, not that it is true. `--anchor`
+publishes the root through Verifyum to Solana, which leaves the machine and
+cannot be undone. Its idempotency key is the one aamio-python and aamio-php use,
+so one root anchored from any of the three is one proof. The server has the
+receipt as `aamio_receipt`. A read takes `--max-bytes`, 512 or more, and `aamio_read`
+reads 65536 bytes per channel unless told otherwise, measured as the messages
+are handed over: whole messages only, and what does not fit stays at the
+service and is said in `attention`. A message larger than the budget is named
+with its size, or, when it has already come, handed over on its own and said.
+
 Run one server per home. On Windows and Linux, a running Node, Python or
 Composer client that owns the home blocks a second server. Stop the owner or
 choose a separate `--home DIR`. The operating system releases the lock if
@@ -179,7 +213,13 @@ that local policy. `keptOut` retains the reason a signature or hash failed.
 Without `onKeptOut`, `listen()` appends these entries to `thread.keptOut` and
 warns once per batch. With a callback, the caller owns that reporting and
 retention. `onGone` and `onReset` expose lost threads and cursor resets, with
-warnings by default. `decode(message)` without an address is legacy unchecked
+warnings by default. `open()` keeps the `instance` the service names the thread
+by, and `listen()` reads a thread opened again at its address from the start
+and says it once through `onReset`, in each listener of the thread. A
+listener knows the thread by the instance it had when `listen()` was called. A cursor
+given with a thread that has no `instance`, as one stored by an earlier
+version, is read again from the start once in the same way, and what came
+before it may come again. `decode(message)` without an address is legacy unchecked
 decoding and returns `checked: false`. Use `read()` or provide the address to
 check authorship and destination binding.
 

package/bin/aamio.js

@@ -17,8 +17,10 @@ const help = `Usage: aamio [--home DIR] <command>
   lookup [NAME ...]            Which partners are reachable now, and where
   send TO TEXT [--data JSON] [--re SHA256]
                                Send a partner a message, signed and sealed to its key
-  read [--wait SECONDS] [--limit N]
+  read [--wait SECONDS] [--limit N] [--max-bytes N]
                                Read the inbox: every message checked here first
+  receipt [--channel LABEL] [--anchor]
+                               The receipt for a channel, compared with what this process read
   outbox pending               Sends with no settled outcome on this machine
   board post KIND TITLE TEXT [--tags a,b] [--ttl SECONDS] [--lang TAG] [--deadline ISO]
                                Put a need or an offer on the open board
@@ -43,7 +45,8 @@ const SPEC = {
   "partner list": { positional: [] },
   lookup: { positional: [], rest: true, options: ["--wait"] },
   send: { positional: ["to", "text"], options: ["--data", "--re"] },
-  read: { positional: [], options: ["--wait", "--limit"] },
+  read: { positional: [], options: ["--wait", "--limit", "--max-bytes"] },
+  receipt: { positional: [], options: ["--channel"], switches: ["--anchor"] },
   "outbox pending": { positional: [] },
   "board post": { positional: ["kind", "title", "text"], options: ["--tags", "--ttl", "--lang", "--deadline"] },
   "board find": { positional: [], options: ["--kind", "--tags", "--lang", "--after", "--wait", "--min-work-bits"] },
@@ -84,6 +87,12 @@ function parse(argv) {
       ended = true;
     } else if (!ended && arg.startsWith("--")) {
       const [name, inline] = arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+      // A switch is there or not, and takes no value: receipt --anchor.
+      if ((spec.switches ?? []).includes(name)) {
+        if (inline !== undefined) throw new Error(`${name} takes no value.`);
+        options[name.slice(2)] = true;
+        continue;
+      }
       if (!(spec.options ?? []).includes(name)) throw new Error(`${command} does not take ${name}. Run aamio --help for usage.`);
       const value = inline ?? args[++i];
       if (value === undefined) throw new Error(`${name} needs a value.`);
@@ -98,9 +107,14 @@ function parse(argv) {
   return { command, home: resolve(home ?? (process.env.AAMIO_HOME || join(homedir(), ".aamio"))), positional, options };
 }
 
-function whole(value, name, low, high) {
+function whole(value, name, low, high = null) {
   if (value === undefined) return undefined;
-  if (!/^[0-9]{1,6}$/.test(value) || Number(value) < low || Number(value) > high) throw Object.assign(new Error(`${name} is a whole number from ${low} to ${high}.`), { code: "usage" });
+  // Leading zeros are the number's own business: --limit 0001 was taken before
+  // 10 November 2026 and is again. The digits are capped only to keep the
+  // number exact; the bounds are checked on its value.
+  if (!/^[0-9]{1,15}$/.test(value) || Number(value) < low || (high !== null && Number(value) > high)) {
+    throw Object.assign(new Error(high === null ? `${name} is a whole number, ${low} or more.` : `${name} is a whole number from ${low} to ${high}.`), { code: "usage" });
+  }
   return Number(value);
 }
 
@@ -143,12 +157,19 @@ function plan(command, positional, options) {
       return (runtime) => runtime.send(first, { text: second, data, re: options.re ?? null });
     }
     case "read": {
-      const asked = { wait: whole(options.wait, "--wait", 0, 25) ?? 0, limit: whole(options.limit, "--limit", 1, 200) ?? 50 };
+      // Without --max-bytes the command line asks for no byte budget, as aamio-python's does. With it,
+      // 512 or more, as over MCP: a budget above what the service takes is sent as the largest it takes.
+      const asked = { wait: whole(options.wait, "--wait", 0, 25) ?? 0, limit: whole(options.limit, "--limit", 1, 200) ?? 50, maxBytes: whole(options["max-bytes"], "--max-bytes", 512) ?? null };
       return async (runtime) => {
         const messages = await runtime.read(asked);
         return { messages, count: messages.length, attention: await runtime.attentionTaken() };
       };
     }
+    case "receipt": {
+      const label = options.channel ?? "inbox";
+      if (!label) throw Object.assign(new Error("--channel names a channel, as a message's channel field does: inbox, board or an older generation."), { code: "usage" });
+      return (runtime) => runtime.receipt(label, { anchor: options.anchor === true });
+    }
     case "outbox pending":
       return (runtime) => ({ pending: runtime.outboxPending() });
     case "board post": {
@@ -240,7 +261,7 @@ try {
   } else {
     const known = ["home_not_initialized", "key_unreadable", "home_init_failed", "home_in_use", "lock_unavailable", "state_unreadable", "invalid_name",
       "invalid_key", "invalid_re", "unknown_partner", "ambiguous_partner", "unknown_address", "partner_offline", "too_large", "inbox_unavailable", "runtime_closed",
-      "board_failed", "board_unreachable", "board_inbox_unavailable", "unknown_post", "not_saved"];
+      "board_failed", "board_unreachable", "board_inbox_unavailable", "unknown_post", "not_saved", "unknown_channel", "receipt_failed"];
     process.stderr.write((known.includes(error?.code) ? error.message + (error.fix ? ` ${error.fix}` : "") : "The local Node runtime could not complete this command.") + "\n");
     process.exitCode = 1;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aamio",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "mcpName": "at.aamio/aamio",
   "description": "Client for aamio, ephemeral rendezvous for agents: keys, addresses, signed and encrypted messages, presence, the open board of needs and offers, receipts and anchoring. Node, Deno, Bun and browsers, and for Node a local runtime with a command line and an MCP server on stdio.",
   "type": "module",

package/src/aamio.d.ts

@@ -97,6 +97,13 @@ export interface Thread {
   id: string;
   w: string;
   expireAt?: number;
+  /**
+   * The instance the service named the thread by, kept by open() and by listen(). A thread opened again at
+   * this address has another one, and listen() reads it from the start and says so once, as a reset; so does
+   * a listen() given a cursor and a thread without one, as one stored by an earlier version, since that
+   * cursor cannot be checked. Absent from a service that names none.
+   */
+  instance?: string;
   allow?: string[];
   /** The service's echo when it differs from the requested, locally kept list. null when absent. */
   allowAnswered?: unknown;
@@ -146,6 +153,8 @@ export interface ReadResult {
   exists: boolean;
   created_at?: number;
   expire_at?: number;
+  /** The thread's instance, from a service that names one: another one than before is another thread at this address. */
+  instance?: string;
   count: number;
   allow: string[];
   /** Checked here: verified and from are this client's result, not the service's word. */

package/src/aamio.js

@@ -1191,6 +1191,9 @@ export class Aamio {
     const body = gate ? JSON.stringify({ gate }) : undefined;
     const data = await this.request("PUT", "/" + w, { headers, body });
     const thread = { id, w, expireAt: data.expire_at, allow };
+    // The service names each thread by an instance of its own, and listen()
+    // knows the thread by it.
+    if (typeof data.instance === "string") thread.instance = data.instance;
     if (JSON.stringify(data.allow) !== JSON.stringify(allow)) thread.allowAnswered = data.allow ?? null;
     if (data.gate) thread.gate = data.gate;
     return thread;
@@ -1424,37 +1427,82 @@ export class Aamio {
    * Yield messages as they arrive, long polling with wait seconds per call,
    * until signal aborts or the thread answers 410 (then AamioError is thrown).
    */
-  async *listen(thread, { after = 0, wait = 25, signal, onKeptOut, onGone, onReset } = {}) {
-    let seq = after;
-    while (!(signal && signal.aborted)) {
-      const data = await this.read(thread, { after: seq, wait });
-      // What the thread's own allowlist kept out is not yielded, and it is said.
-      if (data.keptOut?.length) {
-        if (typeof onKeptOut === "function") onKeptOut(data.keptOut);
-        else {
-          (thread.keptOut ??= []).push(...data.keptOut);
-          console.warn("aamio: messages kept out", data.keptOut);
+  listen(thread, { after = 0, wait = 25, signal, onKeptOut, onGone, onReset } = {}) {
+    // The instance this listener last saw the thread by, its own. Two listeners
+    // on one thread object shared the field on it: the first to see a new
+    // thread wrote it, and the second went on past its first message (a review
+    // of 10 November 2026). The field on the thread is kept as well, for a
+    // caller that stores the thread. It is taken when listen() is called, not
+    // when the first message is asked for: a generator starts at its first
+    // next(), and a listener made before the thread changed, asked first after
+    // another listener had written the new instance on the thread, took that
+    // one as its own and went on past the new thread's first message (a review
+    // of 11 November 2026).
+    let known = typeof thread.instance === "string" ? thread.instance : null;
+    const client = this;
+    return (async function* () {
+      let seq = after;
+      while (!(signal && signal.aborted)) {
+        const data = await client.read(thread, { after: seq, wait });
+        // A thread is known by the instance the service names it by. One opened
+        // again at this address, by its owner or by a write after a restart,
+        // that already holds as many messages as the cursor is not reset by the
+        // service, and listen went on from the old cursor past its first messages
+        // without a word (a review of 10 November 2026). So it is read from the
+        // start, and that is said once, as a reset. A cursor that came without
+        // the instance, as with a thread stored by an earlier version, cannot be
+        // checked at all, and is read again from the start once in the same way:
+        // what came before it may come again (the same review).
+        if (data.exists === true && typeof data.instance === "string") {
+          if (data.instance !== known && !data.reset && seq > 0) {
+            const what = known !== null
+              ? `the thread at this address is a new one, instance ${data.instance} where this listener knew instance ${known}, so it is read again from the start`
+              : `this listener's cursor, ${seq}, came without the thread's instance, so it cannot be told whether the thread here is the one it was kept on. It is read again from the start this once, and messages before the cursor may come again.`;
+            const reset = { after: seq, newest: Number.isInteger(data.count) ? data.count : 0, what };
+            known = data.instance;
+            thread.instance = data.instance;
+            if (Number.isInteger(data.expire_at)) thread.expireAt = data.expire_at;
+            thread.reset = reset;
+            client.forgetGate(thread.w);
+            if (typeof onReset === "function") onReset(reset);
+            else console.warn("aamio: the thread cursor was reset", reset);
+            seq = 0;
+            continue;
+          }
+          // The thread that is there, with its own expiry: after the service read
+          // it from the start it may expire at another time than the one opened.
+          if (known !== data.instance && Number.isInteger(data.expire_at)) thread.expireAt = data.expire_at;
+          known = data.instance;
+          thread.instance = data.instance;
         }
+        // What the thread's own allowlist kept out is not yielded, and it is said.
+        if (data.keptOut?.length) {
+          if (typeof onKeptOut === "function") onKeptOut(data.keptOut);
+          else {
+            (thread.keptOut ??= []).push(...data.keptOut);
+            console.warn("aamio: messages kept out", data.keptOut);
+          }
+        }
+        if (data.exists === false) {
+          if (typeof onGone === "function") onGone(data);
+          else if (!thread.gone) console.warn("aamio: the thread is gone", data.note);
+          thread.gone = true;
+        } else if (data.exists === true) thread.gone = false;
+        if (data.reset) {
+          thread.reset = data.reset;
+          client.forgetGate(thread.w);
+          if (typeof onReset === "function") onReset(data.reset);
+          else console.warn("aamio: the thread cursor was reset", data.reset);
+        }
+        for (const message of data.messages) yield message;
+        // The service's next, not the highest seq seen. When a restart takes a
+        // thread and a write opens a new one at the same address, the service
+        // reads from the start and says reset, and next is lower than before.
+        // Keeping the highest seq asked past the new thread on every call and
+        // handed the same messages over each time.
+        if (Number.isInteger(data.next)) seq = data.next;
       }
-      if (data.exists === false) {
-        if (typeof onGone === "function") onGone(data);
-        else if (!thread.gone) console.warn("aamio: the thread is gone", data.note);
-        thread.gone = true;
-      } else if (data.exists === true) thread.gone = false;
-      if (data.reset) {
-        thread.reset = data.reset;
-        this.forgetGate(thread.w);
-        if (typeof onReset === "function") onReset(data.reset);
-        else console.warn("aamio: the thread cursor was reset", data.reset);
-      }
-      for (const message of data.messages) yield message;
-      // The service's next, not the highest seq seen. When a restart takes a
-      // thread and a write opens a new one at the same address, the service
-      // reads from the start and says reset, and next is lower than before.
-      // Keeping the highest seq asked past the new thread on every call and
-      // handed the same messages over each time.
-      if (Number.isInteger(data.next)) seq = data.next;
-    }
+    })();
   }
 
   /** The receipt of a thread you own, with its root recomputed locally. */
@@ -1497,14 +1545,32 @@ export class Aamio {
       headers: { "Content-Type": "application/json", Accept: "application/json", "MCP-Protocol-Version": "2025-11-25" },
       body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "verifyum_anchor_commitment", arguments: { commitment, idempotency_key: idem } } }),
     });
-    const rpc = await response.json();
+    // The status first. A 503 with a proof_id in its body is no anchoring, and a
+    // 503 in plain text is still a 503: the body used to be read as JSON before
+    // the status was looked at (a review of 10 November 2026).
+    // The status came before the body, and it is the answer's even when the body
+    // breaks off: a 503 cut short was reported as 0 (a review of 10 November 2026).
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      throw new AamioError(response.status, String(error?.message ?? error), `anchor failed: Verifyum answered ${response.status} and the answer broke off`);
+    }
+    let rpc = null;
+    try {
+      rpc = JSON.parse(text);
+    } catch {
+      rpc = null;
+    }
+    if (!response.ok) throw new AamioError(response.status, rpc ?? text, `anchor failed: Verifyum answered ${response.status}`);
     let result = {};
     try {
       result = JSON.parse(rpc?.result?.content?.[0]?.text ?? "{}");
     } catch {
       result = {};
     }
-    if (rpc?.result?.isError || !result.proof_id) throw new AamioError(response.status, rpc, "anchor failed");
+    // A proof_id of blanks names no proof (a review of 10 November 2026).
+    if (rpc === null || typeof rpc !== "object" || rpc.result?.isError || typeof result?.proof_id !== "string" || result.proof_id.trim() === "") throw new AamioError(response.status, rpc ?? text, "anchor failed");
     return { proofId: result.proof_id, proofUrl: result.proof_url, status: result.status, commitment };
   }
 

package/src/node-mcp.js

@@ -52,8 +52,12 @@ const RUNTIME_TOOLS = [
   },
   {
     name: "aamio_read",
-    description: "New messages on your inbox. With wait, returns as soon as one arrives or after that many seconds (max 25). Each message says who signed it (a name from your address book, or unknown key), whether the signature verified (checked on this machine, not taken on the service's word), whether it was sealed to you, and whether it is a replay of one read before. What could not be read, or was kept out by the inbox's list, is in attention. No messages and no attention means nobody wrote. limit caps how many come back, fifty by default; the rest wait for the next call.",
-    inputSchema: schema({ wait: { type: "integer", minimum: 0, maximum: 25 }, limit: { type: "integer", minimum: 1, maximum: 200 } }),
+    description: "New messages on your inbox. With wait, returns as soon as one arrives or after that many seconds (max 25). Each message says who signed it (a name from your address book, or unknown key), whether the signature verified (checked on this machine, not taken on the service's word), whether it was sealed to you, and whether it is a replay of one read before. What could not be read, or was kept out by the inbox's list, is in attention. No messages and no attention means nobody wrote. limit caps how many come back, fifty by default; the rest wait for the next call. max_bytes caps how many bytes of them, per channel, measured as they are handed over here, and defaults to 65536: one message's worth, so ordinary traffic never meets it and a backlog arrives a page at a time. Pass a larger number to take more in one go. A message bigger than the budget stays at the service, named in attention with its size, until a read with a larger budget takes it; one that has already come is handed over on its own, and attention says so.",
+    inputSchema: schema({
+      wait: { type: "integer", minimum: 0, maximum: 25 },
+      limit: { type: "integer", minimum: 1, maximum: 200, description: "at most this many messages in the answer" },
+      max_bytes: { type: "integer", minimum: 512, description: "how many bytes of messages to hand over, per channel, 65536 unless you say otherwise: a read across several channels can return that much from each, since a budget split between them would refuse a message that fits. Whole messages only, measured as they are handed over. A message larger than the budget stays at the service and is named in attention, or, when it has already come, is handed over on its own and said in attention." },
+    }),
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
   },
   {
@@ -100,6 +104,12 @@ const RUNTIME_TOOLS = [
     description: "Every tag in use on the board with live counts of needs and offers, dotted children under their branch. Use it to pick where to look before finding or watching.",
     inputSchema: schema(), annotations: { ...READ_ONLY, openWorldHint: true },
   },
+  {
+    name: "aamio_receipt",
+    description: "The receipt for one channel: hashes, times and signer keys of every message in it, and one root. channel is a local channel label, inbox by default, board for answers to your posts, or an older generation such as inbox-1800000000: take it from the channel field of the message you are working with. root_adds_up says the receipt's own lines hash to the root it claims; local_root_matches compares it to what this server read and is null when it holds fewer messages than the receipt counts, which is not a failure. The signer column is the service's record unless compared with locally verified messages. keys_unverified_count and keys_service_claim_only identify unchecked claims; they are never turned into contact names. Observations include kept-out messages. Fewer receipt lines than observed messages is a mismatch; local_differences names changed fields when counts match. Signing or anchoring a fetched root does not endorse its claims. A receipt does not prove that the other side read, understood or acted. With anchor, the root is published to Verifyum and anchored on Solana, which leaves this machine and cannot be undone.",
+    inputSchema: schema({ channel: { type: "string", description: "local channel label, as a message's channel field names it; defaults to inbox" }, anchor: { type: "boolean", description: "publish the root externally" } }),
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  },
   {
     name: "aamio_pending",
     description: "Messages this home sent whose outcome is not settled: in flight, or unknown because no answer came back. Unknown does not mean undelivered. Never compose a replacement for a message whose outcome is unsettled.",
@@ -201,6 +211,8 @@ async function handle(message, session) {
 
 const PARTNER_QUESTION = "aamio_partner_key";
 const CONFIRM_SECONDS = 900;
+// What aamio_read hands over per channel when the caller names no budget: one message's maximum.
+const DEFAULT_MAX_BYTES = 65536;
 const PARTNER_NAME = /^[\p{L}\p{N}][\p{L}\p{N}_.-]{0,31}$/u;
 const CONFIRMATIONS = { secret: randomBytes(32), taken: new Map() };
 
@@ -414,6 +426,7 @@ function wrongArguments(tool, args) {
     if (!want) return `${tool.name} takes no argument called ${name}`;
     const ok = want.type === "string" ? typeof value === "string" && (!want.pattern || new RegExp(want.pattern).test(value)) && value.length >= (want.minLength ?? 0) && value.length <= (want.maxLength ?? Infinity) && (!want.enum || want.enum.includes(value))
       : want.type === "integer" ? Number.isInteger(value) && value >= (want.minimum ?? -Infinity) && value <= (want.maximum ?? Infinity)
+        : want.type === "boolean" ? typeof value === "boolean"
         : want.type === "object" ? object(value)
           : want.type === "array" ? Array.isArray(value) && value.every((item) => typeof item === "string") && value.length <= (want.maxItems ?? Infinity) : false;
     if (!ok) return `${name} is not what ${tool.name} takes: ${JSON.stringify(want)}`;
@@ -451,9 +464,11 @@ async function callRuntimeTool(id, params, session, version, reply, complete) {
         case "aamio_presence_lookup": return runtime.lookup(args.names ?? null, args.wait ?? 0);
         case "aamio_send": return runtime.send(args.to, { text: args.text ?? null, data: args.data ?? null, re: args.re ?? null });
         case "aamio_read": {
-          const messages = await runtime.read({ wait: args.wait ?? 0, limit: args.limit ?? 50 });
+          // One message's maximum per channel unless the caller says otherwise, as aamio-python's server reads.
+          const messages = await runtime.read({ wait: args.wait ?? 0, limit: args.limit ?? 50, maxBytes: args.max_bytes ?? DEFAULT_MAX_BYTES });
           return { messages, count: messages.length, attention: await runtime.attentionTaken() };
         }
+        case "aamio_receipt": return runtime.receipt(args.channel ?? "inbox", { anchor: args.anchor === true });
         case "aamio_pending": return { pending: runtime.outboxPending() };
         case "aamio_board_post": return runtime.boardPost({ kind: args.kind, title: args.title, text: args.text, tags: args.tags ?? [], ttl: args.ttl ?? undefined, lang: args.lang ?? null, deadline: args.deadline ?? null });
         case "aamio_board_find": return runtime.boardFind({ kind: args.kind ?? null, tags: args.tags ?? null, lang: args.lang ?? null, after: args.after ?? 0, wait: args.wait ?? 0, min_work_bits: args.min_work_bits ?? 0 });

package/src/node-runtime.js

@@ -2,7 +2,7 @@ import { open, readFile, rename, unlink } from "node:fs/promises";
 import { constants } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { Aamio, AamioError, BOARD_TTL, DEFAULT_BASE, DEFAULT_BOARD, GateStop, checkMessage, gatePlan, isEnvelope, isKey, keyHash, sha256hex, threadSigningInput } from "./aamio.js";
+import { Aamio, AamioError, BOARD_TTL, DEFAULT_BASE, DEFAULT_BOARD, GateStop, VERIFYUM_MCP, checkMessage, gatePlan, isEnvelope, isKey, keyHash, sha256hex, threadSigningInput } from "./aamio.js";
 import { readKeys } from "./node-identity.js";
 import { takeHome } from "./node-lock.js";
 
@@ -31,6 +31,12 @@ export const ANSWER_MARGIN = 600;
 // the runtime before anything is saved over it: a save is how a broken file
 // becomes a lost one.
 const KEPT_FILES = ["partners.json", "state.json", "outbox.json"];
+// The largest X-Max-Bytes the service takes: one to eight digits.
+const MAX_BYTES_HEADER = 99_999_999;
+// How long after a thread expires what this process read of it is kept for its
+// receipt: the service keeps an expired thread for a best-effort minute of grace
+// for receipts, and the margin is for clocks that differ.
+const RECEIPT_KEEP = 120;
 // Answers that prove a message was not stored: refusals the service will give
 // again, and a rate window, which it decides before it reads the body.
 const SEND_DETERMINISTIC = [400, 403, 410, 413, 415, 422, 428, 501];
@@ -54,6 +60,41 @@ function runtimeError(code, message, extra = {}) {
   return Object.assign(new Error(message), { code, ...extra });
 }
 
+/**
+ * Why a service's answer is not a receipt for the thread at w, or null when it
+ * is one: the v1 schema, the address that was asked for, its times, one line in
+ * order for every message it counts, and a root its commitment names. Checked
+ * before anything is compared, signed or anchored: a receipt for another address,
+ * and one that counted seven messages and listed one, were signed with
+ * root_adds_up true (a review of 10 November 2026).
+ */
+function receiptFault(data, w) {
+  if (!isObject(data)) return "it is not an object";
+  if (data.schema !== "aamio-receipt-v1") return `its schema is ${JSON.stringify(data.schema ?? null)}, not aamio-receipt-v1`;
+  if (data.w !== w) return `it is for ${JSON.stringify(data.w ?? null)}, not for ${w}, the address asked for`;
+  for (const field of ["created_at", "expire_at", "issued_at"]) {
+    if (!Number.isInteger(data[field]) || data[field] < 0) return `its ${field} is not a time`;
+  }
+  if (!Array.isArray(data.messages)) return "it has no list of messages";
+  if (!Number.isInteger(data.count) || data.count !== data.messages.length) return `it counts ${JSON.stringify(data.count ?? null)} messages and has ${data.messages.length} lines`;
+  let previous = 0;
+  for (const [index, m] of data.messages.entries()) {
+    const fine = isObject(m) && Number.isInteger(m.seq) && m.seq > previous && Number.isInteger(m.at) && m.at >= 0
+      && typeof m.sha256 === "string" && HASH.test(m.sha256) && (m.from === undefined || m.from === null || typeof m.from === "string");
+    if (!fine) return `line ${index + 1} is not a message line in order`;
+    previous = m.seq;
+  }
+  if (typeof data.root !== "string" || !HASH.test(data.root)) return "its root is not a sha256 in hex";
+  if (data.commitment !== "sha256:" + data.root) return "its commitment is not sha256: and its root";
+  // The signers are the lines' own: the service lists each key that signed a
+  // line, once. One that left a signer out was signed as if nobody had signed
+  // (a review of 10 November 2026).
+  if (!Array.isArray(data.keys) || data.keys.some((key) => typeof key !== "string") || new Set(data.keys).size !== data.keys.length) return "its keys are not a list of keys";
+  const signers = new Set(data.messages.map((m) => m.from).filter((from) => typeof from === "string"));
+  if (data.keys.length !== signers.size || data.keys.some((key) => !signers.has(key))) return "its keys are not the signers of its lines";
+  return null;
+}
+
 function isObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -76,10 +117,10 @@ function messageShape(body, envelope) {
 
 export class NodeRuntime {
   /** Takes the home, reads its key and its files. Close it to let go. */
-  static async open({ home, host = process.env.AAMIO_HOST || DEFAULT_BASE, board = process.env.AAMIO_BOARD || DEFAULT_BOARD, fetch = globalThis.fetch, clock = () => Date.now() / 1000 } = {}) {
+  static async open({ home, host = process.env.AAMIO_HOST || DEFAULT_BASE, board = process.env.AAMIO_BOARD || DEFAULT_BOARD, verifyum = process.env.AAMIO_VERIFYUM || VERIFYUM_MCP, fetch = globalThis.fetch, clock = () => Date.now() / 1000 } = {}) {
     const owner = await takeHome(home, { host });
     try {
-      const runtime = new NodeRuntime({ home, host, board, keys: await readKeys(home), owner, fetch, clock });
+      const runtime = new NodeRuntime({ home, host, board, verifyum, keys: await readKeys(home), owner, fetch, clock });
       await runtime.load();
       return runtime;
     } catch (error) {
@@ -88,9 +129,15 @@ export class NodeRuntime {
     }
   }
 
-  constructor({ home, host, board = DEFAULT_BOARD, keys, owner, fetch, clock }) {
+  constructor({ home, host, board = DEFAULT_BOARD, verifyum = VERIFYUM_MCP, keys, owner, fetch, clock }) {
     this.home = home;
     this.host = host.replace(/\/+$/, "");
+    // Where a receipt's root is anchored, as aamio-python reads it: AAMIO_VERIFYUM.
+    this.verifyum = String(verifyum).replace(/\/+$/, "");
+    // What this process read of each thread, by write address and seq: the
+    // lines a receipt is compared with. In memory only, as in aamio-python, so
+    // a process that did not read a message cannot vouch for it.
+    this.observed = new Map();
     this.keys = keys;
     this.owner = owner;
     this.clock = clock;
@@ -405,7 +452,7 @@ export class NodeRuntime {
     const before = this.state.channels.map((channel) => (isObject(channel) ? [channel, channel.label, channel.muted] : null));
     const noted = this.attention.length;
     if (old) old.label = this.freeLabel(`inbox-${old.expire_at}`);
-    const inbox = { label: "inbox", read_key: thread.id, w: thread.w, expire_at: thread.expireAt, allow: wanted ?? [], after: 0, created_at: null, gone: false, muted: false, seen: [] };
+    const inbox = { label: "inbox", read_key: thread.id, w: thread.w, expire_at: thread.expireAt, allow: wanted ?? [], after: 0, created_at: null, instance: null, gone: false, muted: false, seen: [] };
     this.state.channels.push(inbox);
     const muted = this.muteGenerations(reason);
     try {
@@ -759,7 +806,7 @@ export class NodeRuntime {
     }
     const label = held?.label;
     if (held) held.label = this.freeLabel(`board-${held.expire_at}`);
-    const channel = { label: "board", read_key: thread.id, w: thread.w, expire_at: thread.expireAt, allow: ["*"], after: 0, created_at: null, gone: false, muted: false, seen: [] };
+    const channel = { label: "board", read_key: thread.id, w: thread.w, expire_at: thread.expireAt, allow: ["*"], after: 0, created_at: null, instance: null, gone: false, muted: false, seen: [] };
     this.state.channels.push(channel);
     try {
       await this.saveState();
@@ -957,17 +1004,26 @@ export class NodeRuntime {
     };
   }
 
-  /** A verified message that names an address binds its signer's key to it, once. A different key later is a conflict, and the binding stays. */
-  bindClaimedAddress(channel, entry, field, address, senderKey) {
-    if (typeof address !== "string" || !ADDRESS.test(address)) return;
+  /**
+   * What a verified message that names an address in this field would bind: its
+   * signer's key to the address, once, or a conflict when the address is bound to
+   * another key, and the binding stays. Nothing is changed here: the binding is
+   * made when the message is taken.
+   */
+  bindingFor(field, address, senderKey) {
+    if (typeof address !== "string" || !ADDRESS.test(address)) return null;
     const bound = this.state.peers[address];
-    if (bound === undefined) {
-      this.state.peers[address] = senderKey;
-      return;
-    }
-    if (bound === senderKey) return;
-    (entry.binding_conflicts ??= []).push({ field, address, claimed_by: senderKey, bound_to: bound });
-    this.note(channel.label, "binding_conflict", `message ${entry.seq} names ${address} as ${field}, signed by ${this.nameForKey(senderKey) ?? senderKey}, and that address is already bound to ${this.nameForKey(bound) ?? bound}. The binding is kept.`, channel.w);
+    if (bound === undefined) return { field, address, conflict: null };
+    if (bound === senderKey) return null;
+    return { field, address, conflict: { field, address, claimed_by: senderKey, bound_to: bound } };
+  }
+
+  /** The cursor and what was read belonged to a thread that is not there now. The hashes are the reader's and stay. */
+  forgetThread(channel) {
+    channel.after = 0;
+    channel.created_at = null;
+    channel.instance = null;
+    this.observed.delete(channel.w);
   }
 
   /**
@@ -975,17 +1031,17 @@ export class NodeRuntime {
    * before the caller sees a message: a crash after that redelivers nothing, and
    * one before it redelivers what the stored hashes then mark as replays.
    */
-  async poll(channel, wait = 0, limit = null) {
+  async poll(channel, wait = 0, limit = null, maxBytes = null) {
     if (channel.muted) return [];
-    const before = { after: channel.after, created_at: channel.created_at, gone: channel.gone, seen: [...channel.seen], peers: { ...this.state.peers } };
+    const before = { after: channel.after, created_at: channel.created_at, instance: channel.instance ?? null, expire_at: channel.expire_at, gone: channel.gone, seen: [...channel.seen], peers: { ...this.state.peers } };
     try {
-      return await this.pollOnce(channel, wait, limit, true);
+      return await this.pollOnce(channel, wait, limit, true, maxBytes);
     } catch (error) {
       if (!error?.notSaved) throw error;
       // What this read changed is undone in memory too: the cursor, the hashes
       // and the bindings stay as the file has them, and the messages wait at
       // the service for the next read, which hands them over.
-      Object.assign(channel, { after: before.after, created_at: before.created_at, gone: before.gone, seen: before.seen });
+      Object.assign(channel, { after: before.after, created_at: before.created_at, instance: before.instance, expire_at: before.expire_at, gone: before.gone, seen: before.seen });
       this.state.peers = before.peers;
       this.note(channel.label, "not_saved", `what this read found here could not be written down (${error.cause?.code || error.cause?.message}), so nothing from this channel was handed over. It is still there for the next read, and nothing was skipped.`, channel.w);
       return [];
@@ -1000,12 +1056,39 @@ export class NodeRuntime {
     }
   }
 
-  async pollOnce(channel, wait, limit, again) {
+  /**
+   * One message this process read on a channel, kept for the receipt: the
+   * service's line for it as this process saw it, and what was checked here.
+   * The rows belong to the thread they were read on, the one opened at
+   * created_at at this address. A thread opened at the same address after the
+   * service restarted is another thread, and its receipt is never compared with
+   * them (a review of 10 November 2026).
+   */
+  observe(channel, raw, entry) {
+    if (!Number.isInteger(entry.seq) || entry.seq < 1) return;
+    let held = this.observed.get(channel.w);
+    const created = channel.created_at ?? null;
+    const expires = Number.isInteger(channel.expire_at) ? channel.expire_at : null;
+    const instance = typeof channel.instance === "string" ? channel.instance : null;
+    if (!held || held.created_at !== created || held.expire_at !== expires || held.instance !== instance) {
+      this.observed.set(channel.w, (held = { created_at: created, expire_at: expires, instance, rows: new Map() }));
+    }
+    const message = isObject(raw) ? raw : {};
+    held.rows.set(entry.seq, { seq: entry.seq, at: entry.at, sha256: entry.sha256, from: typeof message.from === "string" ? message.from : null, verified: entry.verified === true, from_key: entry.from_key ?? null });
+  }
+
+  async pollOnce(channel, wait, limit, again, maxBytes = null) {
     let path = "/" + channel.w;
     if (channel.after > 0 || wait > 0) path += "/after/" + channel.after;
     if (wait > 0) path += "/wait/" + Math.min(25, wait);
     const headers = { "X-Read": channel.read_key };
     if (limit !== null) headers["X-Limit"] = String(limit);
+    // Whole messages only, and this many bytes of them at most: the service
+    // keeps the rest, and says so with more or too_large. It takes the header
+    // as at most eight digits and holds any budget to the thread's maximum, a
+    // megabyte, so a larger one is sent as the largest it takes: nine digits
+    // were answered 400 and the channel went unread.
+    if (maxBytes !== null) headers["X-Max-Bytes"] = String(Math.min(maxBytes, MAX_BYTES_HEADER));
     let data;
     try {
       data = await this.client.request("GET", path, { headers, expect: [200] });
@@ -1025,39 +1108,126 @@ export class NodeRuntime {
       if (!channel.gone) this.note(channel.label, "gone", "there is no thread at this address any more: it expired and was swept, or the service restarted and it went with it" + (channel.label === "inbox" ? ", so a new inbox is opened for the partners" : ""), channel.w);
       channel.gone = true;
       // The cursor belonged to that thread. The hashes are the reader's and stay.
-      channel.after = 0;
-      channel.created_at = null;
+      this.forgetThread(channel);
       await this.saveRead();
       return [];
     }
     channel.gone = false;
     const created = data.created_at ?? null;
-    if (again && channel.created_at !== null && created !== null && created !== channel.created_at && !data.reset) {
-      this.note(channel.label, "restarted", `the thread at this address is a new one, opened at ${created} where this channel knew one opened at ${channel.created_at}, so it is read again from the start`, channel.w);
+    const expires = Number.isInteger(data.expire_at) ? data.expire_at : null;
+    const instance = typeof data.instance === "string" ? data.instance : null;
+    // A thread is known by its instance, which the service gives each thread
+    // when it is opened: a thread opened again at the same address in the same
+    // second, with the same lifetime and list, looked the same in every other
+    // field, and a cursor taken from the old one passed over its first messages
+    // (a review of 10 November 2026). A service that names no instance is read
+    // by when the thread was opened and when it expires, as before.
+    const known = typeof channel.instance === "string" && instance !== null;
+    const another = known
+      ? instance !== channel.instance
+      : channel.created_at !== null && ((created !== null && created !== channel.created_at) || (expires !== null && Number.isInteger(channel.expire_at) && expires !== channel.expire_at));
+    if (again && another && !data.reset) {
+      this.note(channel.label, "restarted", known
+        ? `the thread at this address is a new one, instance ${instance} where this channel knew instance ${channel.instance}, so it is read again from the start`
+        : `the thread at this address is a new one, opened at ${created} and expiring at ${expires}, where this channel knew one opened at ${channel.created_at} and expiring at ${channel.expire_at}, so it is read again from the start`, channel.w);
+      // What was read of the old thread is no line of the new one's receipt.
+      this.forgetThread(channel);
+      return this.pollOnce(channel, 0, limit, false, maxBytes);
+    }
+    // A cursor kept by a client that did not keep the thread's instance, aamio
+    // 0.6.1 among them, cannot be checked against it: a thread opened again at
+    // this address in the same second, with the same lifetime and list, looks
+    // the same in every other field, and its first messages were passed over
+    // without a word (a review of 10 November 2026). So the thread is read again
+    // from the start, once, and all of it is handed over: what this channel
+    // handed over before comes again marked replay, as after a restart. Nothing
+    // is passed over by its hash, which is the hash of the text alone: another
+    // sender's message with the same text has it too (the same review).
+    if (!another && !data.reset && channel.after > 0 && typeof channel.instance !== "string" && instance !== null) {
+      this.note(channel.label, "reread", `this channel's cursor, ${channel.after}, was kept by a client that did not keep the thread's instance, so it cannot be told whether the thread here is the one that cursor was kept on. It is read again from the start this once: what this channel handed over before comes again, marked replay, and nothing is passed over.`, channel.w);
       channel.after = 0;
-      channel.created_at = null;
-      return this.pollOnce(channel, 0, limit, false);
+      return this.pollOnce(channel, 0, limit, false, maxBytes);
+    }
+    if (data.reset) {
+      this.note(channel.label, "restarted", (isObject(data.reset) && data.reset.what) || "the service read this thread from the start", channel.w);
+      this.observed.delete(channel.w);
     }
-    if (data.reset) this.note(channel.label, "restarted", (isObject(data.reset) && data.reset.what) || "the service read this thread from the start", channel.w);
+    // The channel follows the thread that is there, all of it at once: one
+    // taken up after its cursor was forgotten, or read from the start by the
+    // service after a restart, may expire at another time than the one opened.
+    // A channel that took the new instance and kept the old expiry chose an
+    // inbox that had expired, and one that expired later was given up early
+    // (a review of 10 November 2026). The list this channel was opened with is
+    // its own, and stays.
+    if ((channel.created_at === null || another || data.reset) && expires !== null) channel.expire_at = expires;
     channel.created_at = created;
+    if (instance !== null) channel.instance = instance;
+    // What the service kept back. It answers a byte budget with whole messages
+    // only, so a message larger than the budget is named here and stays at the
+    // service, with what came after it waiting behind it.
+    if (isObject(data.too_large)) {
+      this.note(channel.label, "too_large", `message ${data.too_large.seq} on this channel is ${data.too_large.bytes} bytes and does not fit the byte budget this read asked for, so it was not sent. It is still there, what was written after it waits behind it, and every read at this budget will leave it. Read again with a larger budget to take it: max_bytes over MCP, or --max-bytes on the command line.`, channel.w);
+    }
 
     const entries = [];
     const keptOut = [];
     let lastSeq = null;
+    // The budget is kept here as well, for what is handed over, measured as it
+    // is handed over. The service counts its own form of each message, which is
+    // not the size of the message opened here, and a service without read
+    // limits sends everything: 512 bytes asked for, 628 handed over (a review of
+    // 10 November 2026). A row that does not fit is not taken at all. It is not
+    // observed for the receipt, not remembered as read and binds no address, and
+    // the cursor stays before it, so the next read asks the service for it.
+    let used = 0;
+    let stoppedAtBudget = false;
+    let oversized = null;
     for (const raw of data.messages) {
       if (limit !== null && entries.length >= limit) break;
       const entry = this.readEntry(channel, raw);
-      lastSeq = lastSeq === null ? entry.seq : Math.max(lastSeq, entry.seq);
       const allow = channel.allow || [];
       const excluded = allow.length > 0 && !(entry.verified && (allow.includes("*") || allow.includes(entry.from_key)));
+      // What the message's addresses would bind is worked out before it is
+      // weighed, so a conflict it carries is counted with it, and bound only when
+      // it is taken: a conflict added after the weighing let 1146 bytes through a
+      // budget of 900 (a review of 10 November 2026).
+      const bindings = [];
+      if (!excluded) {
+        this.takeScopeShare(entry);
+        if (isObject(entry.body) && entry.verified && entry.from_key) {
+          for (const field of ["reply_to", "channel"]) {
+            const planned = this.bindingFor(field, entry.body[field], entry.from_key);
+            if (planned !== null) bindings.push(planned);
+          }
+          const conflicts = bindings.filter((planned) => planned.conflict !== null).map((planned) => planned.conflict);
+          if (conflicts.length) entry.binding_conflicts = conflicts;
+        }
+        if (maxBytes !== null) {
+          const weight = Buffer.byteLength(JSON.stringify(entry), "utf8");
+          if (entries.length > 0 && used + weight > maxBytes) {
+            stoppedAtBudget = true;
+            break;
+          }
+          // Alone and still over the budget: it has come, so it is handed over
+          // on its own rather than kept back for ever, and that is said.
+          if (entries.length === 0 && weight > maxBytes) oversized = { seq: entry.seq, weight };
+          used += weight;
+        }
+      }
+      // Every message read counts for the receipt, the ones the list keeps out too.
+      this.observe(channel, raw, entry);
+      lastSeq = lastSeq === null ? entry.seq : Math.max(lastSeq, entry.seq);
       if (excluded) {
         keptOut.push(entry.seq);
         continue;
       }
       if (entry.sha256 !== null && !channel.seen.includes(entry.sha256)) channel.seen.push(entry.sha256);
-      this.takeScopeShare(entry);
-      if (isObject(entry.body) && entry.verified && entry.from_key) {
-        for (const field of ["reply_to", "channel"]) this.bindClaimedAddress(channel, entry, field, entry.body[field], entry.from_key);
+      for (const planned of bindings) {
+        if (planned.conflict === null) {
+          this.state.peers[planned.address] = entry.from_key;
+        } else {
+          this.note(channel.label, "binding_conflict", `message ${entry.seq} names ${planned.address} as ${planned.field}, signed by ${this.nameForKey(entry.from_key) ?? entry.from_key}, and that address is already bound to ${this.nameForKey(planned.conflict.bound_to) ?? planned.conflict.bound_to}. The binding is kept.`, channel.w);
+        }
       }
       entries.push(entry);
     }
@@ -1065,39 +1235,199 @@ export class NodeRuntime {
       const openedFor = (channel.allow || []).includes("*") ? "any key, signed only" : `${channel.allow.length} named key(s)`;
       this.note(channel.label, "kept_out", `${keptOut.length} message(s) (seq ${keptOut.join(", ")}): this channel was opened for ${openedFor}, and these did not satisfy that list as checked here. They are not handed over.`, channel.w);
     }
-    const stoppedEarly = limit !== null && entries.length >= limit && data.messages.length > entries.length + keptOut.length;
-    if (stoppedEarly && lastSeq !== null) channel.after = lastSeq;
-    else if (Number.isInteger(data.next)) channel.after = data.next;
+    if (oversized) {
+      this.note(channel.label, "over_budget", `message ${oversized.seq} on this channel is ${oversized.weight} bytes as handed over here, larger than the whole byte budget of ${maxBytes} this read asked for. It had already come, so it is handed over on its own rather than kept back for ever, and this read is over its budget on purpose.`, channel.w);
+    }
+    // Rows the service sent that this read left because its own limit was
+    // reached: a service that does not take X-Limit sends them all, and the read
+    // that stopped on its own said nothing (a review of 10 November 2026).
+    const leftHere = !stoppedAtBudget && limit !== null && entries.length >= limit && data.messages.length > entries.length + keptOut.length;
+    if (stoppedAtBudget) {
+      this.note(channel.label, "more", `this read stopped at the byte budget it asked for, ${maxBytes} bytes of messages as they are handed over here, and left the rest at the service. Nothing was passed over: the cursor stands at the last message handed over, so read again for the rest.`, channel.w);
+    } else if (leftHere || (data.more === true && !isObject(data.too_large))) {
+      // The service says more both when the count this read asked for was
+      // reached and when the byte budget was. A note that blamed a budget
+      // nobody set would send the reader looking for the wrong cause.
+      const atLimit = leftHere || (limit !== null && data.messages.length >= limit);
+      this.note(channel.label, "more", atLimit
+        ? "this read handed over as many messages as its limit allows, and the service has more waiting on this channel. Nothing was passed over: the cursor stands at the last message handed over, so read again for the rest."
+        : maxBytes !== null
+          ? "the service had more waiting on this channel than the byte budget this read asked for, so it sent what fits and kept the rest. Read again for it: the cursor stands at the last message handed over."
+          : "the service says it has more waiting on this channel than it sent. Nothing was passed over: the cursor stands at the last message handed over, so read again for the rest.", channel.w);
+    }
+    // A read that stopped early moves the cursor to the last row it took and
+    // no further: next would skip the rest of the page.
+    const stoppedEarly = stoppedAtBudget || leftHere;
+    if (stoppedEarly) {
+      if (lastSeq !== null) channel.after = lastSeq;
+    } else if (Number.isInteger(data.next)) channel.after = data.next;
     else if (lastSeq !== null) channel.after = Math.max(channel.after, lastSeq);
     await this.saveRead();
     return entries;
   }
 
+  /**
+   * The receipt for one channel, and two checks of it that are not one. Whether
+   * its own lines hash to the root it claims can always be checked:
+   * root_adds_up. Whether it agrees with what this process read can be, when
+   * this process holds every message it counts: local_root_matches, null when
+   * it holds fewer, which is not a failure, and false when it holds more. A
+   * signer the service names is shown by name only when this process checked
+   * that signature itself. The receipt is signed with this home's key as it
+   * was fetched, which records what was taken, not that its claims are true.
+   * With anchor, and only then, its root goes to Verifyum, with the same
+   * idempotency key aamio-python and aamio-php use.
+   */
+  async receipt(label = "inbox", { anchor = false } = {}) {
+    const channel = this.channel(String(label));
+    if (!isObject(channel)) {
+      const labels = this.state.channels.filter(isObject).map((c) => c.label);
+      throw runtimeError("unknown_channel", `no channel called ${label} in this home. It has ${labels.length ? labels.join(", ") : "none yet: a read opens the inbox"}. A message names the channel it came on.`);
+    }
+    let data;
+    try {
+      ({ receipt: data } = await this.client.receipt({ id: channel.read_key, w: channel.w }));
+    } catch (error) {
+      throw runtimeError("receipt_failed", `the receipt could not be taken: ${error.status ?? 0} ${JSON.stringify(error.body ?? error.message)}`, { status: error.status ?? 0 });
+    }
+    // Checked as a receipt for this channel before anything is compared,
+    // signed or anchored.
+    const fault = receiptFault(data, channel.w);
+    if (fault !== null) {
+      throw runtimeError("receipt_failed", `the service's answer is not a receipt for this channel: ${fault}. Nothing was compared, signed or anchored.`);
+    }
+    // What this process read counts only for the thread it was read on. After
+    // the service restarted, a new thread at the same address was compared with
+    // what was read of the old one, and its signer named as checked here.
+    const observed = this.observed.get(channel.w);
+    // The same thread by its instance where the service names one, and by when
+    // it was opened and expires where it does not.
+    const sameThread = observed !== undefined && (typeof data.instance === "string" && observed.instance !== null
+      ? observed.instance === data.instance
+      : observed.created_at !== null && observed.created_at === data.created_at && (observed.expire_at === null || observed.expire_at === data.expire_at));
+    const earlier = observed !== undefined && !sameThread && observed.rows.size > 0 ? observed : null;
+    const entries = sameThread ? [...observed.rows.values()].sort((a, b) => a.seq - b.seq) : [];
+    const which = (thread) => (typeof thread.instance === "string" ? `instance ${thread.instance}, ` : "the one ") + `opened at ${thread.created_at} and expiring at ${thread.expire_at}`;
+    const held = entries.length;
+    const line = (m) => `${m.seq}\t${m.at}\t${m.sha256}\t${m.from ?? "-"}\n`;
+    const listed = data.messages.map(line).join("");
+    const ours = entries.map(line).join("");
+    const comparable = held === data.count;
+    // A signer is named only for a row this process checked and the receipt
+    // lists as it was read: the same seq, time, hash and signer. A row read on a
+    // thread the fields cannot tell from this one is not taken for it (a review
+    // of 10 November 2026).
+    const listedBySeq = new Map(data.messages.map((m) => [m.seq, m]));
+    const asListed = (e) => {
+      const m = listedBySeq.get(e.seq);
+      return m !== undefined && m.at === e.at && m.sha256 === e.sha256 && (m.from ?? null) === (e.from ?? null);
+    };
+    const verifiedKeys = new Set(entries.filter((e) => e.verified && typeof e.from_key === "string" && asListed(e)).map((e) => e.from_key));
+    const claimed = Array.isArray(data.keys) ? data.keys : [];
+    const unverified = claimed.filter((key) => typeof key !== "string" || !verifiedKeys.has(key));
+    const attestation = `aamio-receipt-v1\n${channel.w}\n${data.root}\n${data.count}\n${data.issued_at ?? 0}`;
+    const result = {
+      label: channel.label, w: channel.w, root: data.root, commitment: data.commitment ?? null, count: data.count,
+      keys: claimed.map((key) => (typeof key === "string" && verifiedKeys.has(key) ? this.nameForKey(key) ?? key : key)),
+      keys_unverified_count: unverified.length, keys_service_claim_only: unverified,
+      root_adds_up: sha256hex(listed) === data.root, held_locally: held,
+      local_root_matches: comparable ? sha256hex(ours) === data.root : held > data.count ? false : null,
+      signed_by: this.keys.public, signature: this.keys.sign(attestation), signed_text: attestation, receipt: data,
+    };
+    if (comparable) {
+      const local = new Map(entries.map((e) => [e.seq, e]));
+      result.local_differences = (data.messages ?? []).map((m) => {
+        const seen = local.get(m.seq);
+        return { seq: m.seq, fields: ["at", "sha256", "from"].filter((field) => !seen || (seen[field] ?? null) !== (m[field] ?? null)) };
+      }).filter((difference) => difference.fields.length);
+      result.signers_not_verified_locally = entries.filter((e) => e.from && !e.verified).map((e) => e.seq);
+    }
+    if (held > data.count) {
+      result.local_check = "Mismatch: the receipt counts fewer messages than this process read. The thread was replaced or the service lost messages.";
+    } else if (!comparable) {
+      result.local_check = `Not compared: this process holds ${held} of the ${data.count} messages the receipt counts, so a local root would differ for a reason that is not the receipt's.`
+        + (earlier !== null ? ` What this process read at this address was on another thread, ${which(earlier)}; this receipt is for ${which(data)}, so none of that counts here.` : "")
+        + " root_adds_up checks only the receipt's arithmetic; our signature records what was fetched, not that its claims are true. For the independent check, take the receipt in the process that read the messages.";
+    }
+    if (anchor === true) {
+      const idempotencyKey = sha256hex(`aamio-listen:${this.keys.hash}:${data.root}`).slice(0, 32);
+      try {
+        const proof = await this.client.anchor(`sha256:${data.root}`, { endpoint: this.verifyum, idempotencyKey });
+        result.anchor = { proof_id: proof.proofId, proof_url: proof.proofUrl ?? null, status: proof.status ?? null, commitment: proof.commitment };
+      } catch (error) {
+        // The receipt stands; only the anchoring failed, and it says how: the
+        // HTTP status, 0 when nothing answered, and Verifyum's own words when
+        // its tool answered with an error.
+        const said = error.body?.result?.content?.[0]?.text;
+        result.anchor = { error: error.status ?? 0, detail: typeof said === "string" ? said : error.body ?? error.message };
+      }
+    }
+    return result;
+  }
+
   /** Messages on every channel still read, the inbox first. The inbox is opened and presence published as the read starts. */
-  async read({ wait = 0, limit = 50 } = {}) {
+  async read({ wait = 0, limit = 50, maxBytes = null } = {}) {
+    const noted = this.attention.length;
     await this.ensureInbox();
     await this.publishPresence();
     const now = this.now();
+    // What was read of a thread is kept for its receipt while the receipt can
+    // still be taken, and no longer: a server that ran for days held the rows
+    // of every inbox it had read (a review of 10 November 2026).
+    for (const w of [...this.observed.keys()]) {
+      const known = this.state.channels.find((c) => isObject(c) && c.w === w);
+      if (!known || Number(known.expire_at) + RECEIPT_KEEP < now) this.observed.delete(w);
+    }
     const channels = this.state.channels.filter((c) => isObject(c) && !c.muted && Number(c.expire_at) > now)
       .sort((a, b) => (a.label === "inbox" ? -1 : b.label === "inbox" ? 1 : 0));
     const messages = [];
+    // A channel this read had no room left to ask is named, as aamio-python
+    // names it: what waits there was not looked at, and a read that stopped at
+    // its limit is not a read of everything.
+    const notAsked = [];
+    const notAskedAfter = [];
     // Every channel without waiting first: a message on an older inbox that
     // is still read is handed over at once, not after a wait on the new one.
+    // The byte budget is per channel, as in aamio-python: one split between
+    // them would refuse a message that fits.
     for (const channel of channels) {
-      if (messages.length >= limit) break;
-      messages.push(...(await this.poll(channel, 0, limit - messages.length)));
+      if (messages.length >= limit) {
+        notAsked.push(channel);
+        continue;
+      }
+      messages.push(...(await this.poll(channel, 0, limit - messages.length, maxBytes)));
     }
     const inbox = this.channel("inbox");
     if (!messages.length && wait > 0 && inbox && !inbox.muted) {
-      messages.push(...(await this.poll(inbox, wait, limit)));
+      messages.push(...(await this.poll(inbox, wait, limit, maxBytes)));
       // What reached the other channels during the wait comes with this
       // answer, as in aamio-python: only the inbox can end the wait early. It
       // used to wait for the next read (a review of 9 November 2026).
       for (const channel of channels) {
-        if (channel === inbox || messages.length >= limit) continue;
-        messages.push(...(await this.poll(channel, 0, limit - messages.length)));
+        if (channel === inbox) continue;
+        if (messages.length >= limit) {
+          notAskedAfter.push(channel);
+          continue;
+        }
+        messages.push(...(await this.poll(channel, 0, limit - messages.length, maxBytes)));
       }
     }
+    for (const channel of notAsked) {
+      this.note(channel.label, "more", `this read reached its limit of ${limit} message(s) before it asked this channel, so what waits here was not looked at. Nothing was passed over: read again for it.`, channel.w);
+    }
+    for (const channel of notAskedAfter) {
+      this.note(channel.label, "more", `this read reached its limit of ${limit} message(s) during the wait, so this channel was asked before the wait and not after it. What reached it meanwhile comes with the next read.`, channel.w);
+    }
+    // A read says a thing once. A channel asked before a wait and in it gave
+    // the same too_large twice (a review of 10 November 2026).
+    const said = new Set();
+    const fresh = this.attention.slice(noted).filter((note) => {
+      const key = `${note.w}\u0000${note.state}\u0000${note.what}`;
+      if (said.has(key)) return false;
+      said.add(key);
+      return true;
+    });
+    this.attention.splice(noted, this.attention.length - noted, ...fresh);
     return messages;
   }
 }