@mida-context/sdk 0.1.0 → 0.1.1

package/dist/index.js

@@ -230,6 +230,11 @@ var MidaError = class extends Error {
 function isMidaError(value, code) {
   return value instanceof MidaError && (code === void 0 || value.code === code);
 }
+var ACCEPTABLE_AGENT_NAME_CHARS = new RegExp(
+  "^[\\p{L}\\p{N}][\\p{L}\\p{M}\\p{N} ._\\-\\u200c\\u200d]*$",
+  "u"
+);
+var STACKED_MARK_RUN = new RegExp("\\p{M}{5}", "u");
 
 // packages/protocol/src/constants.ts
 var PERMISSION = { READ: 1, CREATE: 2, SUPERSEDE_OWN: 4, SUPERSEDE_ANY: 8 };
@@ -4987,6 +4992,38 @@ var REJECT_NAMES = new Map(Object.entries(BATCH_REJECT).map(([name, code]) => [c
 import { zeroHash as zeroHash6 } from "viem";
 var lower = (value) => value.toLowerCase();
 var RECORDS_PER_MULTICALL = 200;
+var multicall3Probes = /* @__PURE__ */ new Map();
+var multicall3AbsentSink;
+var multicall3AbsentSent = /* @__PURE__ */ new Set();
+function multicall3ProbeEntry(context) {
+  const key = `${context.deployment.chainId}:${MULTICALL3_ADDRESS}`;
+  const held = multicall3Probes.get(key);
+  if (held !== void 0) return held;
+  const entry = {
+    size: void 0,
+    // Promise.resolve().then(...) so a client without getCode — a custom transport, a test rig —
+    // throws INSIDE the chain and lands on the same eviction as an RPC that refuses the call.
+    probe: Promise.resolve().then(() => context.publicClient.getCode({ address: MULTICALL3_ADDRESS })).then((code) => {
+      const absent = code === void 0 || code === "0x";
+      if (absent && multicall3AbsentSink !== void 0 && !multicall3AbsentSent.has(context.deployment.chainId)) {
+        multicall3AbsentSent.add(context.deployment.chainId);
+        try {
+          multicall3AbsentSink(context.deployment.chainId);
+        } catch {
+        }
+      }
+      return entry.size = absent ? 1 : RECORDS_PER_MULTICALL;
+    })
+  };
+  entry.probe.catch(() => {
+    if (multicall3Probes.get(key) === entry) multicall3Probes.delete(key);
+  });
+  multicall3Probes.set(key, entry);
+  return entry;
+}
+function sharedMulticall3Probe(context) {
+  return multicall3ProbeEntry(context).probe;
+}
 var RegistryReader = class {
   constructor(context) {
     this.context = context;
@@ -4995,22 +5032,24 @@ var RegistryReader = class {
   #recordBatchSize;
   #recordBatchSizeProbe;
   /**
-   * The probed batch size once known, undefined while unprobed. Lets a BudgetedReader return a
-   * cached answer without charging the request for a chain read that does not happen.
+   * The probed batch size once known, undefined while unprobed. Lets a BudgetedReader answer
+   * without charging the request — but "unprobed" does not mean "no read": on a cold cache
+   * `multicall3ProbeEntry` starts the `getCode` probe right here, the chain answers it in the
+   * background, and the getter reports undefined until that answer lands (in-38 V-3).
    */
   get knownRecordBatchSize() {
-    return this.#recordBatchSize;
+    return this.#recordBatchSize ?? multicall3ProbeEntry(this.context).size;
   }
   /**
    * The most contextIds one `getRecords` call answers in a single chain read: RECORDS_PER_MULTICALL
-   * when the chain carries Multicall3, 1 where it does not. Probed once per reader with `getCode`
-   * and cached; a chain that cannot answer the probe cannot run a multicall either, so a failed
-   * probe also resolves to 1 — the per-row path — rather than breaking reads on an RPC that does
-   * not serve `eth_getCode`.
+   * when the chain carries Multicall3, 1 where it does not. Probed once per PROCESS with `getCode`
+   * — see `multicall3Probes` — and cached per reader once answered; a chain that cannot answer the
+   * probe cannot run a multicall either, so a failed probe resolves to 1 — the per-row path —
+   * rather than breaking reads on an RPC that does not serve `eth_getCode`.
    */
   recordBatchSize() {
     if (this.#recordBatchSize !== void 0) return Promise.resolve(this.#recordBatchSize);
-    this.#recordBatchSizeProbe ??= Promise.resolve().then(() => this.context.publicClient.getCode({ address: MULTICALL3_ADDRESS })).then((code) => this.#recordBatchSize = code === void 0 || code === "0x" ? 1 : RECORDS_PER_MULTICALL).catch(() => this.#recordBatchSize = 1);
+    this.#recordBatchSizeProbe ??= multicall3ProbeEntry(this.context).probe.then((size) => this.#recordBatchSize = size).catch(() => this.#recordBatchSize = 1);
     return this.#recordBatchSizeProbe;
   }
   now() {
@@ -5077,43 +5116,54 @@ var RegistryReader = class {
     }
   }
   /**
-   * `getRecord` for a batch of contextIds. With Multicall3 the batch is ONE `eth_call` — hundreds of
-   * never-anchored uploads can no longer spend a request's read budget a row at a time. The
-   * `ContextNotFound` revert of an orphaned upload comes back as a null entry — "not anchored",
-   * never an error — and it is the ONLY failure that does: an out-of-gas, an undecodable result or
-   * any other revert throws exactly as `getRecord` throws, so a caller can never read a list that
-   * silently dropped a real record. Chains without Multicall3 fall back to one `getRecord` per id,
-   * unchanged.
-   * Callers pass at most `recordBatchSize()` ids per call, so each call costs exactly one unit of
-   * read budget — or `contextIds.length` units on the per-row path, identical to `getRecord`.
+   * `getRecord` for a batch of contextIds. With Multicall3 each `recordBatchSize()`-sized chunk of
+   * the ids is ONE `eth_call` — hundreds of never-anchored uploads can no longer spend a request's
+   * read budget a row at a time. The `ContextNotFound` revert of an orphaned upload comes back as
+   * a null entry — "not anchored", never an error — and it is the ONLY failure that does: an
+   * out-of-gas, an undecodable result or any other revert throws exactly as `getRecord` throws, so
+   * a caller can never read a list that silently dropped a real record. Chains without Multicall3
+   * fall back to one `getRecord` per id, unchanged.
+   * Chunks run in order and a failing chunk fails the whole call. Callers that pass more than
+   * `recordBatchSize()` ids pay one aggregate call per chunk — the budgeted wrapper slices to the
+   * batch size itself, so inside a request each call still costs exactly one unit of read budget
+   * (or `contextIds.length` units on the per-row path, identical to `getRecord`).
    */
   async getRecords(contextIds) {
     if (contextIds.length === 0) return [];
-    if (await this.recordBatchSize() === 1) {
+    const batchSize = await this.recordBatchSize();
+    if (batchSize === 1) {
       return Promise.all(contextIds.map((contextId2) => this.getRecord(contextId2)));
     }
-    const results = await this.context.publicClient.multicall({
-      // batchSize 0 disables viem's calldata chunking (default 1024 bytes): the whole batch is a
-      // single aggregate3 eth_call, which is what one unit of read budget pays for.
-      batchSize: 0,
-      multicallAddress: MULTICALL3_ADDRESS,
-      allowFailure: true,
-      contracts: contextIds.map((contextId2) => ({
-        address: this.context.deployment.contextRegistry,
-        abi: contextRegistryAbi,
-        functionName: "getRecord",
-        args: [contextId2]
-      }))
-    });
-    return results.map((entry) => {
-      if (entry.status === "success") {
-        const record = entry.result;
-        return { ...record, owner: lower(record.owner) };
+    const records = [];
+    for (let offset = 0; offset < contextIds.length; offset += batchSize) {
+      const results = await this.context.publicClient.multicall({
+        // batchSize 0 disables viem's calldata chunking (default 1024 bytes): the whole batch is a
+        // single aggregate3 eth_call, which is what one unit of read budget pays for.
+        batchSize: 0,
+        multicallAddress: MULTICALL3_ADDRESS,
+        allowFailure: true,
+        contracts: contextIds.slice(offset, offset + batchSize).map((contextId2) => ({
+          address: this.context.deployment.contextRegistry,
+          abi: contextRegistryAbi,
+          functionName: "getRecord",
+          args: [contextId2]
+        }))
+      });
+      for (const entry of results) {
+        if (entry.status === "success") {
+          const record = entry.result;
+          records.push({ ...record, owner: lower(record.owner) });
+          continue;
+        }
+        const mapped = toMidaError(entry.error);
+        if (isMidaError(mapped, "NOT_FOUND")) {
+          records.push(null);
+          continue;
+        }
+        throw mapped;
       }
-      const mapped = toMidaError(entry.error);
-      if (isMidaError(mapped, "NOT_FOUND")) return null;
-      throw mapped;
-    });
+    }
+    return records;
   }
   async #capability(functionName, args) {
     try {
@@ -5387,6 +5437,79 @@ function requireAnchor(deployment) {
   }
   return batchAnchor;
 }
+var lowerAddress = (value) => value.toLowerCase();
+async function prefetchBatchedLookups(input) {
+  const batchAnchor = input.deployment.batchAnchor;
+  if (batchAnchor === void 0) return void 0;
+  const batchSize = await sharedMulticall3Probe({ publicClient: input.client, deployment: input.deployment }).catch(() => 1);
+  if (batchSize === 1) return void 0;
+  const owner = input.owner.toLowerCase();
+  const namespaceId2 = input.namespaceId.toLowerCase();
+  const batchIds = /* @__PURE__ */ new Set();
+  const lineageIds = /* @__PURE__ */ new Set();
+  const signers = /* @__PURE__ */ new Set();
+  for (const item of input.items) {
+    const wire2 = item.save.message;
+    if (wire2.owner.toLowerCase() !== owner || wire2.namespaceId.toLowerCase() !== namespaceId2) continue;
+    if (item.state === "ANCHORED") {
+      if (item.batchId !== void 0) batchIds.add(item.batchId.toLowerCase());
+      if (item.lineageId !== void 0) lineageIds.add(item.lineageId.toLowerCase());
+    } else if (item.state !== "QUEUED" && item.state !== "SUBMITTED") {
+      continue;
+    }
+    try {
+      signers.add(
+        lowerAddress(
+          await recoverTypedDataAddress2({
+            ...batchSaveTypedData({ chainId: input.chainId, batchAnchor, message: wireMessage(wire2) }),
+            signature: item.save.signature
+          })
+        )
+      );
+    } catch {
+    }
+  }
+  const batchKeys = [...batchIds];
+  const headKeys = [...lineageIds];
+  const signerKeys = [...signers];
+  const contracts = [
+    ...batchKeys.map((batchId) => ({ address: batchAnchor, abi: batchAnchorAbi, functionName: "batchOf", args: [batchId] })),
+    ...headKeys.map((lineageId) => ({ address: batchAnchor, abi: batchAnchorAbi, functionName: "headCommitOf", args: [lineageId] })),
+    ...signerKeys.map(
+      (signer) => ({
+        address: input.deployment.capabilityRegistry,
+        abi: capabilityRegistryAbi,
+        functionName: "agentIdOfSigner",
+        args: [signer]
+      })
+    )
+  ];
+  const results = [];
+  for (let offset = 0; offset < contracts.length; offset += RECORDS_PER_MULTICALL) {
+    results.push(
+      ...await input.client.multicall({
+        // batchSize 0 disables viem's calldata chunking: the chunk below is one aggregate3 call.
+        batchSize: 0,
+        multicallAddress: MULTICALL3_ADDRESS,
+        allowFailure: false,
+        contracts: contracts.slice(offset, offset + RECORDS_PER_MULTICALL)
+      })
+    );
+  }
+  const batches = /* @__PURE__ */ new Map();
+  const heads = /* @__PURE__ */ new Map();
+  const agents = /* @__PURE__ */ new Map();
+  results.forEach((result, index) => {
+    if (index < batchKeys.length) {
+      batches.set(batchKeys[index], result);
+    } else if (index < batchKeys.length + headKeys.length) {
+      heads.set(headKeys[index - batchKeys.length], result);
+    } else {
+      agents.set(signerKeys[index - batchKeys.length - headKeys.length], result);
+    }
+  });
+  return { batches, heads, signers: agents };
+}
 async function checkSignedSave(input) {
   const { item, chainId, batchAnchor, client } = input;
   const message = wireMessage(item.save.message);
@@ -5413,7 +5536,7 @@ async function checkSignedSave(input) {
   } catch {
     return { ok: false, reason: "signature" };
   }
-  const agentId2 = await client.readContract({
+  const agentId2 = input.lookups?.signers?.get(lowerAddress(signer)) ?? await client.readContract({
     address: input.capabilityRegistry,
     abi: capabilityRegistryAbi,
     functionName: "agentIdOfSigner",
@@ -5435,12 +5558,12 @@ async function checkSignedSave(input) {
 async function verifyBatchedItem(input) {
   const { item, chainId, deployment, client } = input;
   const batchAnchor = requireAnchor(deployment);
-  const checked2 = await checkSignedSave({ item, chainId, batchAnchor, capabilityRegistry: deployment.capabilityRegistry, client });
+  const checked2 = await checkSignedSave({ item, chainId, batchAnchor, capabilityRegistry: deployment.capabilityRegistry, client, lookups: input.lookups });
   if (!checked2.ok) return checked2;
   const { message, agentId: agentId2 } = checked2;
   if (item.state !== "ANCHORED") return { ok: false, reason: "not-anchored" };
   if (item.batchId === void 0) return { ok: false, reason: "unknown-batch" };
-  const [root, blockNumber] = await client.readContract({
+  const [root, blockNumber] = input.lookups?.batches?.get(item.batchId.toLowerCase()) ?? await client.readContract({
     address: batchAnchor,
     abi: batchAnchorAbi,
     functionName: "batchOf",
@@ -5459,7 +5582,7 @@ async function verifyBatchedItem(input) {
   });
   if (!verifyMerkleProof(leaf, item.proof, root)) return { ok: false, reason: "proof" };
   if (input.requireLatest) {
-    const head = await client.readContract({
+    const head = input.lookups?.heads?.get(item.lineageId.toLowerCase()) ?? await client.readContract({
       address: batchAnchor,
       abi: batchAnchorAbi,
       functionName: "headCommitOf",
@@ -5480,7 +5603,7 @@ async function verifyPendingItem(input) {
   const { item, chainId, deployment, client } = input;
   const batchAnchor = requireAnchor(deployment);
   if (item.state !== "QUEUED" && item.state !== "SUBMITTED") return { ok: false, reason: "not-pending" };
-  const checked2 = await checkSignedSave({ item, chainId, batchAnchor, capabilityRegistry: deployment.capabilityRegistry, client });
+  const checked2 = await checkSignedSave({ item, chainId, batchAnchor, capabilityRegistry: deployment.capabilityRegistry, client, lookups: input.lookups });
   if (!checked2.ok) return checked2;
   const { message, agentId: agentId2 } = checked2;
   const hasAuthority = (permission) => client.readContract({
@@ -5662,8 +5785,13 @@ var MidaAgent = class {
     const { deployment } = this.#chain;
     const { objects, partial } = await this.#api.listObjects({ owner: ownerAddress, namespaceId: namespaceId2, capabilityId: capability.capabilityId });
     const epochKeyFor = this.#epochKeyResolver(ownerAddress, namespaceId2, capability.capabilityId);
+    const listed = /* @__PURE__ */ new Map();
+    const batched = await this.#reader.getRecords(objects.map((object) => object.contextId));
+    for (const [index, record] of batched.entries()) {
+      listed.set(objects[index].contextId.toLowerCase(), record);
+    }
     const readObject = async (object) => {
-      const record = await this.#verifiedRecord(ownerAddress, namespaceId2, object);
+      const record = await this.#verifiedRecord(ownerAddress, namespaceId2, object, listed);
       const epochPrivateKey = await epochKeyFor(record.readEpoch);
       const payload = openContextObject({
         manifest: object.manifest,
@@ -5672,7 +5800,7 @@ var MidaAgent = class {
         epochPrivateKey,
         binding: { chainId: deployment.chainId, contextRegistry: deployment.contextRegistry, contextId: record.contextId, namespaceId: namespaceId2, readEpoch: record.readEpoch }
       });
-      await this.#verifyReferences(ownerAddress, record, payload);
+      await this.#verifyReferences(ownerAddress, record, payload, listed);
       return this.#toObject(record, name, payload, { at: record.createdAt });
     };
     const results = new Array(objects.length);
@@ -5735,13 +5863,21 @@ var MidaAgent = class {
       capabilityId: capability.capabilityId
     });
     const epochKeyFor = this.#epochKeyResolver(ownerAddress, namespaceId2, capability.capabilityId);
+    const lookups = await prefetchBatchedLookups({
+      items,
+      owner: ownerAddress,
+      namespaceId: namespaceId2,
+      chainId: deployment.chainId,
+      deployment,
+      client: this.#chain.publicClient
+    });
     const blockTime = blockTimeCache(this.#chain.publicClient);
     const processItem = async (item) => {
       const message = item.save.message;
       if (message.owner.toLowerCase() !== ownerAddress || message.namespaceId.toLowerCase() !== namespaceId2) {
         return { kind: "skipped", skipped: { contextId: item.contextId, reason: "wrong-scope" } };
       }
-      const verdict = item.state === "ANCHORED" ? await verifyBatchedItem({ item, chainId: deployment.chainId, deployment, client: this.#chain.publicClient, requireLatest: true }) : await verifyPendingItem({ item, chainId: deployment.chainId, deployment, client: this.#chain.publicClient });
+      const verdict = item.state === "ANCHORED" ? await verifyBatchedItem({ item, chainId: deployment.chainId, deployment, client: this.#chain.publicClient, requireLatest: true, lookups }) : await verifyPendingItem({ item, chainId: deployment.chainId, deployment, client: this.#chain.publicClient, lookups });
       if (!verdict.ok) {
         return { kind: "skipped", skipped: { contextId: item.contextId, reason: verdict.reason } };
       }
@@ -6269,8 +6405,15 @@ var MidaAgent = class {
       return pending;
     };
   }
-  async #verifiedRecord(owner, namespaceId2, object) {
-    const record = await this.#reader.getRecord(object.contextId);
+  /**
+   * The record the object claims plus every check that claim implies — the same set either way.
+   * `listed` is the one-batch answer readWithStatus fetched: a key present in it (even a null,
+   * the registry's "no such record") is used as-is; an id the batch somehow did not cover falls
+   * back to a lone getRecord rather than skipping verification.
+   */
+  async #verifiedRecord(owner, namespaceId2, object, listed) {
+    const id = object.contextId.toLowerCase();
+    const record = listed.has(id) ? listed.get(id) : await this.#reader.getRecord(object.contextId);
     if (record === null || object.manifest.contextId !== object.contextId || record.owner !== owner || record.namespaceId !== namespaceId2 || record.manifestHash !== manifestHash(object.manifest) || record.ciphertextCommitment !== object.manifest.ciphertextHash) {
       throw new MidaError("COMMITMENT_MISMATCH", `object ${object.contextId} does not match its Monad commitments`);
     }
@@ -6282,7 +6425,7 @@ var MidaAgent = class {
    * acknowledges an agent proposal, which is itself a CONTEXT record. USER_CONFIRMED then needs at least one
    * `confirmed_from` reference, and IMPORTED/EXTERNAL_ATTESTATION at least one evidence-record target.
    */
-  async #verifyReferences(owner, record, payload) {
+  async #verifyReferences(owner, record, payload, listed) {
     const references = payload.provenance.references ?? [];
     const commitment = references.length === 0 ? zeroHash9 : evidenceCommitment(references);
     if (commitment !== record.evidenceCommitment) {
@@ -6290,7 +6433,12 @@ var MidaAgent = class {
     }
     let evidenceTargets = 0;
     let confirmedFrom = 0;
-    const targets = await Promise.all(references.map((reference) => this.#reader.getRecord(reference.recordId)));
+    const targets = await Promise.all(
+      references.map((reference) => {
+        const id = reference.recordId.toLowerCase();
+        return listed.has(id) ? listed.get(id) : this.#reader.getRecord(reference.recordId);
+      })
+    );
     for (const [index, reference] of references.entries()) {
       const target = targets[index];
       if (target === null || target.owner !== owner) {

package/dist/types/api/chain-views.d.ts

@@ -35,6 +35,22 @@ export interface ContextRecordView {
 }
 /** The most contextIds one batched `getRecords` asks about — one Multicall3 `eth_call` per batch. */
 export declare const RECORDS_PER_MULTICALL = 200;
+/** Registers the process-wide absent-Multicall3 reporter; `undefined` removes it. */
+export declare function onMulticall3Absent(sink: ((chainId: bigint) => void) | undefined): void;
+/**
+ * The process-wide Multicall3 probe for readers that are not a RegistryReader — the SDK's
+ * batched-lookup prefetch (in-39 nit 3). Resolves to this chain's record batch size
+ * (RECORDS_PER_MULTICALL where Multicall3 answers, 1 where it does not), asking the chain's
+ * `getCode` at most once per process and chain; a rejected probe is evicted and rejects here
+ * too, so the caller falls back to per-row reads and the next call asks the chain again.
+ */
+export declare function sharedMulticall3Probe(context: ChainContext): Promise<number>;
+/**
+ * Forget one cached probe answer. Production chains never change whether they carry Multicall3;
+ * a test rig or a rebuilt dev chain can install the runtime mid-process (anvil_setCode), and
+ * then the next reader must ask the chain again rather than trust a stale "not here".
+ */
+export declare function evictMulticall3Probe(chainId: bigint): void;
 /**
  * Every Monad read the Context API and SDK make. Nothing here is cached: each call reads current chain state, so no
  * local value can make Monad authorization true (§12, `currentlyAllowedByMonad`).
@@ -44,16 +60,18 @@ export declare class RegistryReader {
     readonly context: ChainContext;
     constructor(context: ChainContext);
     /**
-     * The probed batch size once known, undefined while unprobed. Lets a BudgetedReader return a
-     * cached answer without charging the request for a chain read that does not happen.
+     * The probed batch size once known, undefined while unprobed. Lets a BudgetedReader answer
+     * without charging the request — but "unprobed" does not mean "no read": on a cold cache
+     * `multicall3ProbeEntry` starts the `getCode` probe right here, the chain answers it in the
+     * background, and the getter reports undefined until that answer lands (in-38 V-3).
      */
     get knownRecordBatchSize(): number | undefined;
     /**
      * The most contextIds one `getRecords` call answers in a single chain read: RECORDS_PER_MULTICALL
-     * when the chain carries Multicall3, 1 where it does not. Probed once per reader with `getCode`
-     * and cached; a chain that cannot answer the probe cannot run a multicall either, so a failed
-     * probe also resolves to 1 — the per-row path — rather than breaking reads on an RPC that does
-     * not serve `eth_getCode`.
+     * when the chain carries Multicall3, 1 where it does not. Probed once per PROCESS with `getCode`
+     * — see `multicall3Probes` — and cached per reader once answered; a chain that cannot answer the
+     * probe cannot run a multicall either, so a failed probe resolves to 1 — the per-row path —
+     * rather than breaking reads on an RPC that does not serve `eth_getCode`.
      */
     recordBatchSize(): Promise<number>;
     now(): Promise<bigint>;
@@ -73,15 +91,17 @@ export declare class RegistryReader {
     } | null>;
     getRecord(contextId: Hex): Promise<ContextRecordView | null>;
     /**
-     * `getRecord` for a batch of contextIds. With Multicall3 the batch is ONE `eth_call` — hundreds of
-     * never-anchored uploads can no longer spend a request's read budget a row at a time. The
-     * `ContextNotFound` revert of an orphaned upload comes back as a null entry — "not anchored",
-     * never an error — and it is the ONLY failure that does: an out-of-gas, an undecodable result or
-     * any other revert throws exactly as `getRecord` throws, so a caller can never read a list that
-     * silently dropped a real record. Chains without Multicall3 fall back to one `getRecord` per id,
-     * unchanged.
-     * Callers pass at most `recordBatchSize()` ids per call, so each call costs exactly one unit of
-     * read budget — or `contextIds.length` units on the per-row path, identical to `getRecord`.
+     * `getRecord` for a batch of contextIds. With Multicall3 each `recordBatchSize()`-sized chunk of
+     * the ids is ONE `eth_call` — hundreds of never-anchored uploads can no longer spend a request's
+     * read budget a row at a time. The `ContextNotFound` revert of an orphaned upload comes back as
+     * a null entry — "not anchored", never an error — and it is the ONLY failure that does: an
+     * out-of-gas, an undecodable result or any other revert throws exactly as `getRecord` throws, so
+     * a caller can never read a list that silently dropped a real record. Chains without Multicall3
+     * fall back to one `getRecord` per id, unchanged.
+     * Chunks run in order and a failing chunk fails the whole call. Callers that pass more than
+     * `recordBatchSize()` ids pay one aggregate call per chunk — the budgeted wrapper slices to the
+     * batch size itself, so inside a request each call still costs exactly one unit of read budget
+     * (or `contextIds.length` units on the per-row path, identical to `getRecord`).
      */
     getRecords(contextIds: readonly Hex[]): Promise<(ContextRecordView | null)[]>;
 }

package/dist/types/protocol/errors.d.ts

@@ -13,3 +13,74 @@ export declare class MidaError extends Error {
     constructor(code: MidaErrorCode, detail?: string);
 }
 export declare function isMidaError(value: unknown, code?: MidaErrorCode): value is MidaError;
+/**
+ * The one sentence the owner page shows when a request carries a refused character in a field it renders — a manifest name, a folder root, a project label.
+ * One fixed sentence, with no field name or code, so the refusal itself can never smuggle part
+ * of the request onto the page (in-27 R-1). This string is final copy.
+ */
+export declare const UNACCEPTABLE_REQUEST_TEXT = "This request contains characters Mida does not accept, so this page will not show or sign it.";
+/**
+ * The characters that must never reach a field a page or a terminal renders. The set is wider
+ * than C0+DEL (in-30 T-3): every control character, the Unicode line and paragraph separators,
+ * the zero-width space (200B), the directional marks (200E-200F), the bidirectional controls
+ * (202A-202E, 2066-2069) and the BOM. Each can forge a rendered line or hide inside one.
+ * The joiners are NOT refused (in-31 V-3): the zero-width non-joiner (200C) is part of Persian
+ * and Indic spelling and the zero-width joiner (200D) holds emoji sequences together — neither
+ * can mint or hide a line.
+ */
+export declare const UNACCEPTABLE_REQUEST_CHARS: RegExp;
+/**
+ * A refused character folded to a single space — for a display-only field that is size-checked
+ * but not refused (a manifest's purpose description or scope reason, in-30 T-3). Validation keeps
+ * the bytes untouched so the manifest's hash still matches what was registered; whatever later
+ * renders the field passes it through here first.
+ */
+export declare function displaySafeText(value: string): string;
+/**
+ * The multi-line form of displaySafeText (in-40 L-4) — for text whose own line breaks must
+ * survive, like a handoff shown by `mida task show`. The Unicode line and paragraph separators
+ * become `\n` rather than spaces so a line break can never hide, and `\n` and `\t` stay; every
+ * other refused character still folds to one space. No collapsing, no trimming: the writer's
+ * line structure is the contract.
+ */
+export declare function displaySafeBlock(value: string): string;
+/**
+ * The single-line form of displaySafeText (in-41 U-2) — for text Mida did not write that must
+ * print as ONE line: a checkpoint's stored task name, a reason the store returned, a code an
+ * RPC error carried. Every refused character folds to a space, whitespace runs collapse to one
+ * space, the ends are trimmed, and a line still longer than `maxChars` ends in `…` inside the
+ * cap — no value from a store or a chain can open a control sequence or forge a second line.
+ */
+export declare function displaySafeLine(value: string, maxChars: number): string;
+/**
+ * Five or more combining marks in a row is a Zalgo stack, not a name: a browser piles them
+ * vertically without a limit and lets the ink paint over the lines above — the advisor
+ * verdict and warnings on the same page (in-37, review 3.1). Four stays legal — Tibetan
+ * stacks three, and Devanagari, Hebrew, Arabic and Thai all stay under. The owner-link
+ * parser applies the same run limit to every rendered field, so a stack cannot be carried
+ * in through a label or a root either.
+ */
+export declare const STACKED_MARK_RUN: RegExp;
+/**
+ * The one agent-name rule, shared by the manifest validator, the owner-link parser and /me
+ * (in-32 X-2, in-34; tightened in-37) — an allow-list, not a deny-list. A name renders
+ * inside the summary's `Agent "…"` quotes, so it admits only the characters a name needs
+ * and refuses everything else: a quote shape could close or imitate the quotes, a colon or
+ * bracket could forge a rendered line, a symbol or emoji needs no reason to be in a name at
+ * all. in-37 adds the three refusals a class allow-list cannot express: the first character
+ * is a letter or number — never a combining mark, which would strike the quote itself —
+ * the eight letter-class look-alikes refuse by name, and five or more combining marks in a
+ * row refuse as a Zalgo stack. A name that is empty after trimming, or one that opens with
+ * a space or a joiner, is refused too — it would render as `Agent ""` or smuggle a space
+ * into the first character. The byte-length limit stays where it always lived — in the
+ * manifest validator — not here.
+ */
+export declare function isAcceptableAgentName(name: string): boolean;
+/**
+ * INVALID_WIRE whose message is already the owner-facing sentence. MidaError prefixes its detail
+ * with the code — "INVALID_WIRE: This request…" is not the page's text — so this subclass keeps
+ * the code for API/log handling and the bare sentence for describeError.
+ */
+export declare class UnacceptableCharactersError extends MidaError {
+    constructor();
+}

package/dist/types/sdk/batched.d.ts

@@ -38,6 +38,38 @@ export declare function signBatchSave(input: {
     batchAnchor: Address;
     message: BatchSaveMessage;
 }): Promise<Hex>;
+/**
+ * The chain answers a batched read needs per distinct VALUE rather than per row (in-38 V-4):
+ * every batch's `batchOf` ([root, anchor block]), every lineage's `headCommitOf`, and every
+ * signer's `agentIdOfSigner`, fetched through Multicall3 before the row checks run. The maps live
+ * for ONE `readBatchedWithStatus` call and nothing may outlive it — a lineage head or an
+ * authority can move before the next read.
+ */
+export interface BatchedReadLookups {
+    /** batchId (lowercased) → the `batchOf` answer: [root, blockNumber]. */
+    readonly batches?: ReadonlyMap<Hex, readonly [Hex, bigint]>;
+    /** lineageId (lowercased) → the `headCommitOf` answer. */
+    readonly heads?: ReadonlyMap<Hex, Hex>;
+    /** signer (lowercased) → the `agentIdOfSigner` answer. */
+    readonly signers?: ReadonlyMap<Address, Hex>;
+}
+/**
+ * Fetches the three distinct-value sets one batched read will consult, in aggregate calls of at
+ * most RECORDS_PER_MULTICALL contract reads with `allowFailure: false` — a failed lookup fails
+ * the read exactly as a failed `readContract` does today. Returns undefined where the chain
+ * carries no Multicall3 (no code at the canonical address, or the getCode probe itself fails —
+ * the probe is the process-wide one shared with every RegistryReader, in-38 V-3): the verifiers
+ * then read per row, unchanged. Only rows that would reach a chain check spend a
+ * lookup — wrong-scope rows and states that refuse before the signature check contribute nothing.
+ */
+export declare function prefetchBatchedLookups(input: {
+    items: readonly BatchedReadItem[];
+    owner: Address;
+    namespaceId: Hex;
+    chainId: bigint;
+    deployment: Deployment;
+    client: PublicClient;
+}): Promise<BatchedReadLookups | undefined>;
 /**
  * The five-check anchored read. Chain state is the only authority: the signer→agent lookup, the
  * batch root, and the lineage head all come from the contracts through `client`; the store supplies
@@ -50,6 +82,7 @@ export declare function verifyBatchedItem(input: {
     deployment: Deployment;
     client: PublicClient;
     requireLatest: boolean;
+    lookups?: BatchedReadLookups;
 }): Promise<BatchedVerdict>;
 /**
  * Amendment B.2 pending read: everything checkable without anchor inclusion — bytes, signature,
@@ -65,4 +98,5 @@ export declare function verifyPendingItem(input: {
     chainId: bigint;
     deployment: Deployment;
     client: PublicClient;
+    lookups?: BatchedReadLookups;
 }): Promise<PendingVerdict>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mida-context/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Give your agent the memory a user approved: read and write it through the user's Mida.",
   "type": "module",
   "license": "MIT",