@atbash/sdk 0.10.13-dev.0 → 0.11.0

package/dist/browser.d.mts

@@ -1,3 +1,6 @@
+import nodePath from 'node:path';
+import { Logger } from '@opentelemetry/api-logs';
+
 type JudgeEndpointConfig = {
     policy?: "default";
     endpoint?: string;
@@ -30,6 +33,19 @@ interface ValidatedEndpoint {
 declare function buildAllowedJudgeHosts(): ReadonlySet<string>;
 declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
 
+interface ChainConfig {
+    readonly network: Network;
+    readonly blockchainRid: string;
+    readonly nodeUrls: readonly string[];
+}
+declare const PRIVATE_CHAIN: ChainConfig;
+/**
+ * The chain a network name selects. Only `"private"` exists; any other value,
+ * including `"public"` from an untyped caller, is refused with the same
+ * message the config switch gives, never routed to private in silence.
+ */
+declare function chainForNetwork(network: Network): ChainConfig;
+
 /**
  * User-facing types. Two groups:
  *  - Core types — the exact shapes the Rust core emits across the NAPI
@@ -118,23 +134,31 @@ interface MemoryScanOptions {
     toolArgsJson?: string;
 }
 /**
- * Which Atbash chain an action runs against. `public` is the shared
- * testnet (Free plan); `private` is reserved for Private / Swarm /
- * Enterprise tier subscribers. The SDK resolves which one to use from
- * the org's subscription via `orgName` — callers normally don't need
- * to pass this manually.
+ * Chain selector. Only `"private"` exists: the public testnet chains are
+ * retired. The SDK resolves an org's chain through the Dashboard via
+ * `orgName` — callers normally don't need to pass this manually.
  */
-type Network = "public" | "private";
+type Network = "private";
 /**
  * Per-call chain overrides. Pass exactly what you need to override —
- * `network` selects between the SDK's known chains, `blockchainRid` /
- * `nodeUrls` pin a fully custom chain. Pass none of these to fall back
- * to the SDK's defaults (or to org-resolved chain when `orgName` is set).
+ * `network` selects between the SDK's known chains, `blockchainRid` pins a
+ * custom one, and `endpoint` names the Dashboard the calls travel over. Pass
+ * none of these to fall back to the SDK's defaults (or to the org-resolved
+ * chain when `orgName` is set).
  */
 interface ChainOpts {
     network?: Network;
     blockchainRid?: string;
+    /**
+     * No longer dialled: memory reaches the chain through the Dashboard. Kept
+     * because callers and the other bindings still carry it as chain config.
+     */
     nodeUrls?: readonly string[];
+    /**
+     * Dashboard base URL. Memory reaches the chain through it, so this is where
+     * those requests go; defaults to the endpoint compiled into the core.
+     */
+    endpoint?: string;
 }
 /** Canonical verdict after normalization. */
 type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
@@ -160,6 +184,11 @@ interface LogToolCallResult {
 }
 interface JudgeResult {
     verdict: Verdict;
+    /**
+     * Canonical executable permission, computed by `canonicalAllow` — see that
+     * function for the rule. Never more permissive than `auditToolCall`.
+     */
+    allow: boolean;
     actionType: string;
     reason: string;
     confidence: number;
@@ -173,6 +202,8 @@ interface JudgeResult {
      * Whether the org's protection mode actually acts on a HOLD/BLOCK verdict.
      * `false` in Monitor mode (verdict is logged for observation, agent is NOT
      * jailed and the action is not held); `true` in Enforce mode.
+     * A plain boolean: an omitted field reads as `false`. `Decision.enforced`
+     * keeps "unknown" apart; gate on that, not on this.
      */
     enforced: boolean;
     /** Server-reported protection mode: `off`, `monitor`, or `enforce`. */
@@ -184,10 +215,17 @@ interface JudgeResult {
      * missing" — never infer the former from a null verdict alone.
      */
     status: string;
+    /**
+     * The judge's explicit refusal in the raw body (`explicitRefusal`): "BLOCK",
+     * "HOLD", or "" when it neither refused nor is a known refusal shape.
+     */
+    refusal?: "" | "BLOCK" | "HOLD";
 }
 interface JudgmentStatus {
     status: JudgmentState;
     verdict: Verdict;
+    /** Same canonical executable permission as {@link JudgeResult.allow}. */
+    allow: boolean;
     reason: string;
     judgmentId: string;
     onChain?: boolean;
@@ -289,8 +327,32 @@ interface AtbashLogger {
 /** Options accepted by the `Atbash` constructor. */
 interface AtbashOptions {
     endpoint?: string;
+    /**
+     * Overall deadline for one `auditToolCall` decision, across every request
+     * it makes (org lookup, exists check, judge). Default 60 000 ms. When it
+     * passes the decision is an ERROR (denied unless `failClosed` is false).
+     * `timeoutMs` still bounds each single request.
+     */
+    decisionTimeoutMs?: number;
     timeoutMs?: number;
+    /**
+     * Full chain override — BRID + nodeUrls in one object. Wins over every
+     * other chain selector. Prefer this over paired `nodeUrls`/`blockchainRid`
+     * for anything but backwards compatibility.
+     */
+    chain?: ChainConfig;
+    /**
+     * Preset chain selector — `"private"` is the only value. Resolves to the
+     * matching `ChainConfig` via `chainForNetwork()`. Overridden by `chain`,
+     * overrides env `ATBASH_DEFAULT_CHAIN_NETWORK` and the config file.
+     */
+    network?: Network;
+    /**
+     * Explicit node URLs. Must be paired with `blockchainRid`. Passing one
+     * without the other throws — a BRID/nodes mismatch 404s every request.
+     */
     nodeUrls?: readonly string[];
+    /** Explicit BRID. Must be paired with `nodeUrls`. See {@link nodeUrls}. */
     blockchainRid?: string;
     /**
      * Default org name. When set, `judgeAction` / `auditToolCall` resolve
@@ -315,8 +377,27 @@ interface AtbashOptions {
      * `orgEncryptionPubKey` overrides this, same as `verifyPubKey`.
      */
     orgEncryptionPubKey?: string;
-    /** When true (default), `auditToolCall` denies on any error. */
+    /**
+     * When true (default), `auditToolCall` denies on any error. When false, it
+     * allows only when Atbash could not be reached or could not answer: a
+     * transport failure, a timeout, a 5xx or a 408 (and a readable reply that
+     * neither grants nor refuses). Atbash's own refusals still deny: an
+     * unregistered agent, any other 4xx (no policy, billing suspended, quota
+     * exhausted or rate limited, unauthorized), and a 2xx reply that is not a
+     * JSON object. Direct `judgeAction` callers get a `JudgeRefusalError` for
+     * an unregistered agent or an unreadable reply.
+     */
     failClosed?: boolean;
+    /**
+     * When true (the default), an answer that carries no enforcement decision
+     * (the audit tier's `{status:"logged"}` with no verdict) is refused:
+     * `auditToolCall` returns `{allow:false, verdict:"ERROR"}` whatever
+     * `failClosed` says, and `judgeAction().allow` / `getJudgmentStatus().allow`
+     * are false. Set it to `false` only to run deliberately in log-only mode
+     * (security review 2026-09-30, H6: an unsigned marker switched enforcement
+     * off).
+     */
+    requireEnforcement?: boolean;
     /**
      * Verbose diagnostics. Off by default. When on, a failed judge call also
      * logs the response body, which is the difference between "judge API failed"
@@ -332,6 +413,15 @@ interface Decision {
     verdict: DecisionVerdict;
     reason?: string;
     toolCallId?: string;
+    /**
+     * Whether the organisation acts on a HOLD/BLOCK verdict; false under Monitor mode and per-agent Shadow Mode. Absent means unknown: a
+     * transport error, or a judge that stated no mode. Test `=== false`, never
+     * `!decision.enforced`, or every outage counts as a would-block.
+     * Informational only; `allow` remains the gate.
+     */
+    enforced?: boolean;
+    /** Server-reported protection mode (`off`, `monitor`, `enforce`); absent when unknown. */
+    enforcementMode?: string;
 }
 /** Input to `auditToolCall`. */
 interface ToolCallInput {
@@ -357,12 +447,20 @@ interface FromConfigOptions {
     keyPath?: string;
     /** Judge endpoint config — validated against the allowlist / self-hosted policy. */
     judge?: JudgeEndpointConfig;
+    /** See {@link AtbashOptions.chain}. */
+    chain?: ChainConfig;
+    /** See {@link AtbashOptions.network}. */
+    network?: Network;
     blockchainRid?: string;
     timeoutMs?: number;
     nodeUrls?: readonly string[];
     /** Default org name — see {@link AtbashOptions.orgName}. */
     orgName?: string;
     failClosed?: boolean;
+    /** See {@link AtbashOptions.requireEnforcement}. Default true. */
+    requireEnforcement?: boolean;
+    /** See {@link AtbashOptions.decisionTimeoutMs}. Default 60 000 ms. */
+    decisionTimeoutMs?: number;
     /** See {@link AtbashOptions.debug}. */
     debug?: boolean;
     logger?: AtbashLogger;
@@ -371,8 +469,6 @@ interface FromConfigOptions {
 interface JudgeOptions {
     toolName?: string;
     toolArgsJson?: string;
-    provider?: string;
-    model?: string;
     verifyPubKey?: string;
     /** Per-call override of {@link AtbashOptions.orgEncryptionPubKey}. */
     orgEncryptionPubKey?: string;
@@ -408,12 +504,6 @@ interface LogToolCallOptions {
     orgEncryptionPubKey?: string;
 }
 
-interface ChainConfig {
-    readonly network: Network;
-    readonly blockchainRid: string;
-    readonly nodeUrls: readonly string[];
-}
-
 declare class Atbash {
     readonly auth: AgentAuth;
     readonly endpoint: string;
@@ -427,6 +517,10 @@ declare class Atbash {
     readonly orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     readonly failClosed: boolean;
+    /** When true (default), an unenforced (audit-tier) answer is refused. */
+    readonly requireEnforcement: boolean;
+    /** Overall deadline for one auditToolCall decision, in ms. */
+    readonly decisionTimeoutMs: number;
     /** Org key learned from the last agent-exists check, for this agent only. */
     private _orgKeyFromChain;
     private readonly debug;
@@ -437,6 +531,27 @@ declare class Atbash {
      * calls don't re-hit the dashboard. Cleared by `clearChainCache()`.
      */
     private readonly _chainCache;
+    /**
+     * The chain the constructor settled on. Used only where a lookup returns no
+     * answer — see {@link resolveChainFromMap}.
+     */
+    private readonly _defaultChain;
+    /**
+     * True when the caller named a chain outright — `chain`, `network`, or the
+     * paired `blockchainRid` + `nodeUrls`.
+     *
+     * Such a client is never re-pointed: not by the migration switch, and not by
+     * where an org turns out to live. Naming a chain is the caller saying "talk
+     * to this one", and silently routing elsewhere would make the argument a
+     * suggestion. A client that names nothing is the one that follows the org.
+     */
+    private readonly _explicitChain;
+    /**
+     * The fleet-wide chain switch, read once at construction. `resolve()` hits
+     * the config file on disk, so re-reading it per call would put a file read
+     * on every judge.
+     */
+    private readonly _forcedNetwork;
     /**
      * Short-TTL cache for `/api/ai/exists`. The `registered` field is
      * monotonic (once true, stays true), so most calls in a burst re-fetch
@@ -447,12 +562,6 @@ declare class Atbash {
      */
     private _agentExistsCache;
     private static readonly AGENT_EXISTS_TTL_MS;
-    /**
-     * Cached bearer token for risk-engine / insurance read calls. Built
-     * lazily as a signed `log_tool_call` tx and refreshed every 4 min so
-     * server-side replay protection windows never expire it mid-session.
-     */
-    private _authBearers;
     /** Guards `logEnvironmentOnce` — hosts construct several clients. */
     private static environmentLogged;
     constructor(privkey: string, options?: AtbashOptions);
@@ -475,6 +584,48 @@ declare class Atbash {
      * validated against the trusted allowlist / self-hosted policy; a
      * self-hosted endpoint's `verifyPubKey` becomes the client default.
      */
+    /**
+     * Decide which key this client signs as.
+     *
+     * Most specific wins: a key passed in code, then a key file the host named,
+     * then the environment, then the default key file. `config.json` is absent
+     * from that list on purpose — it is a settings file, writable by anything
+     * that can write the user's home and read by every Atbash integration on the
+     * machine, so letting it name the key meant one stray value silently
+     * re-pointed who each of them signed as.
+     *
+     * A named `keyPath` that does not exist throws rather than falling through.
+     * The caller said which file holds its identity; quietly signing as a
+     * different one is the outcome worth refusing.
+     *
+     * @param options - The `fromConfig` options, read for `agentKey` and `keyPath`.
+     * @returns The resolved agent identity.
+     * @throws When a named key file is missing, or no identity can be found.
+     */
+    private static resolveIdentity;
+    /**
+     * Add the one thing a machine with no key file needs to hear.
+     *
+     * This is the only path where the operator cannot see what happened: no key
+     * file, and the key they are looking for sits in `config.json`, which no
+     * longer selects the identity. A bare "key file not found" sends them hunting
+     * for a key they already have. Only this branch gets the hint — a caller who
+     * named a `keyPath` is told about that path, where a stranded key is noise.
+     *
+     * @param err - The "key file not found" error from the default lookup.
+     * @returns The same error, or one that also names the key in config.json.
+     */
+    private static explainStrandedKey;
+    /**
+     * Say so when `config.json` still holds an agent key.
+     *
+     * Nothing signs with it any more, and silence would leave an operator
+     * believing one identity is in force while another is. The pubkey is named,
+     * not the key, so the line is safe in a log.
+     *
+     * @param logger - The host logger, when one was supplied.
+     */
+    private static warnOnStrandedKey;
     static fromConfig(options?: FromConfigOptions): Atbash;
     get pubkey(): string;
     get privkey(): string;
@@ -494,6 +645,13 @@ declare class Atbash {
      * return the signed tx hex. The server broadcasts to chain.
      */
     logToolCall(action: string, context?: string, options?: LogToolCallOptions): Promise<LogToolCallResult>;
+    /**
+     * `raisePreflightErrors` (the judge path, like Python's
+     * `raise_preflight_errors`): a failed registration check throws instead of
+     * becoming `{ success: false }`, so the caller can tell Atbash's "no"
+     * (not registered, or a 4xx) from an outage.
+     */
+    private _logToolCall;
     /**
      * Sign log_tool_call + optionally judge_action, POST /api/v1/judge.
      *
@@ -502,6 +660,15 @@ declare class Atbash {
      */
     judgeAction(action: string, context?: string, options?: JudgeOptions): Promise<JudgeResult>;
     private _judgeAction;
+    /**
+     * Start a local hold on an enforced, on-chain BLOCK (the verdict that jails).
+     * Refuse any other result that lands while the agent is held, or whose
+     * request was already in flight when the block arrived: the server judged it
+     * on pre-jail state.
+     */
+    private applyJailHold;
+    /** The server's jailed refusal, produced locally while the agent is held. */
+    private localJailBlock;
     /**
      * High-level guard: redact secrets, submit for judgement, and collapse the
      * result into an allow/deny `Decision`. Fails closed by default — any error
@@ -509,6 +676,24 @@ declare class Atbash {
      * explicitly false.
      */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
+    /**
+     * The verify key for one call (R4, governor tier-2 review). A per-call key
+     * may only narrow what the client accepts: on a client pinned to a judge
+     * key it must be that same key, never a replacement; on an unpinned client
+     * it adds the check.
+     */
+    private effectiveVerifyKey;
+    /**
+     * Collapse a judge result into a {@link Decision}. The most restrictive
+     * signal wins (security review 2026-09-30, H1): `action_type`, `verdict`
+     * and the canonical `allow` are each able to deny, and only a result where
+     * all three agree may execute. A present `allow` / `decision.allow` that is
+     * not exactly `true` is the judge declining to grant permission, so it
+     * denies even under `failClosed: false` — that option relaxes *errors*, it
+     * never overrides a refusal.
+     */
+    private decide;
+    private decideInner;
     /**
      * One exit for every judge failure.
      *
@@ -518,8 +703,24 @@ declare class Atbash {
      * The response body follows only under `debug`, since it can echo the action.
      */
     private failJudge;
+    /**
+     * The canonical permission for a response body under this client's
+     * settings: {@link canonicalAllow}, minus the audit tier when
+     * `requireEnforcement` is on. Never more permissive than `auditToolCall`.
+     */
+    private executable;
     private fail;
-    getJudgmentStatus(judgmentId: string, agentPubkey?: string): Promise<JudgmentStatus>;
+    /**
+     * Return the current status of a previously submitted judgment.
+     *
+     * `chainOpts` names which chain the judgment was signed against; the SDK
+     * sends it as the `brid` query param the server routes by. Without it the
+     * read uses the same chain `judgeAction` signs for (see `callBrid`): the
+     * client's org chain when it has an `orgName`, else the client default.
+     * A judgment signed with an explicit per-call `chainOpts` (or a per-call
+     * `orgName` on another chain) must be polled with that same `chainOpts`.
+     */
+    getJudgmentStatus(judgmentId: string, agentPubkey?: string, chainOpts?: ChainOpts): Promise<JudgmentStatus>;
     getToolCalls(maxCount: number): Promise<ToolCallRecord[]>;
     getOrgToolCalls(orgName: string, maxCount: number): Promise<ToolCallRecord[]>;
     getAgentToolCalls(agentPubkey: string, maxCount: number): Promise<ToolCallRecord[]>;
@@ -549,10 +750,9 @@ declare class Atbash {
      * Resolve which chain an org's actions should run against. Cached
      * per-client by orgName. Resolution order:
      *   1. `org_networks` map (authoritative).
-     *   2. Per-chain subscription fallback — public + private records
-     *      are fetched in parallel, with `is_private_blockchain` and
-     *      `assigned_at` reconciling mixed states.
-     * Defaults to the public chain when nothing else resolves.
+     *   2. Subscription fallback — the org's subscription row on the chain.
+     * A lookup that finds the org wins outright. Where it finds nothing (a
+     * brand-new org), the client's configured default decides.
      */
     resolveChainForOrg(orgName: string): Promise<ChainConfig>;
     /**
@@ -580,6 +780,13 @@ declare class Atbash {
      * chains; otherwise the client's default.
      */
     private bridFromChainOpts;
+    /**
+     * The chain one call's transactions are signed for: the per-call override
+     * when given, otherwise the client's org, otherwise the client default.
+     * log_tool_call, judge_action and the judgment-status read all use this, so
+     * a request never pairs transactions signed for two different chains.
+     */
+    private callBrid;
     /**
      * Resolve the dashboard chain used by agent metadata/policy reads.
      * Explicit per-call network overrides win; otherwise use the supplied org
@@ -602,10 +809,34 @@ declare class Atbash {
     private riskEngineRecords;
     /**
      * BRID for an org — one round-trip to the map, honoring the client's chain
-     * cache. Returns undefined when the org is unknown, so the caller falls
-     * back to the client default (best-effort discovery).
+     * cache. A "brand-new org" (nothing anywhere names its chain) is not an
+     * error — `resolveChainForOrg` returns the client default for that case and
+     * this helper returns its BRID. A transport failure or non-200 from
+     * `/api/org-network` IS an error and propagates: the caller cannot fall
+     * back to the default chain on outage, because with multi-chain live that
+     * silently reads from the wrong chain. Matches the Python binding's
+     * `_brid_for_org` semantics.
      */
     private bridForOrg;
+    /**
+     * BRID for the client's configured default org, if it has one.
+     *
+     * Calls that carry no `orgName` argument are not chain-less: they still
+     * belong to `this.orgName`, and that org lives on exactly one chain. Routing
+     * them by the constructor's chain instead means a client configured
+     * `network: "private"` reads the private chain for an org that lives on
+     * public, and gets an empty answer rather than an error. So where an org is
+     * known the org decides the chain, and the constructor's chain is what is
+     * left when no org is known at all — the order `resolveAgentLookupNetwork`
+     * already applies to agent metadata reads, and the order the dashboard
+     * applies in `resolveChainForWallet`.
+     *
+     * Undefined when there is no default org, so callers keep falling back to
+     * the client default.
+     */
+    /** The switch's chain, unless this client named one of its own. */
+    private forcedNetwork;
+    private defaultOrgBrid;
     private raiseIfError;
     /** Wrap a failed HTTP *response* (non-2xx / non-200) as an AtbashAPIError. */
     private httpError;
@@ -626,20 +857,48 @@ declare class Atbash {
     static containsEvasionCharacters(text: string): boolean;
 }
 
+declare const DEFAULTS: {
+    ceilingMs: number;
+    pollMs: number;
+};
+/** Whether `pubkey` is currently held. */
+declare function isJailHeld(pubkey: string): boolean;
+/** Forget every hold and stop its poll; tests and hosts that reset state. */
+declare function releaseJailHolds(): void;
+/** Override the ceiling or poll interval; an empty object restores defaults. */
+declare function configureJailHold(next: Partial<typeof DEFAULTS>): void;
+
 declare const DEFAULT_ENDPOINT: string;
-declare const DEFAULT_CHROMIA_NODE_URLS: readonly string[];
-declare const DEFAULT_BLOCKCHAIN_RID: string;
 
 declare class AtbashAPIError extends Error {
     /** HTTP status code (or 0 if the request never completed). */
     readonly status: number;
     /** Raw response body text (may be empty). */
     readonly body: string;
-    constructor(status: number, body: string, statusText?: string, endpoint?: string);
+    /**
+     * Request path this status came from, e.g. `/api/v1/judge` — absent when the
+     * request never reached a response (transport failures carry status 0).
+     *
+     * A status alone does not say what failed. Several routes answer one call, and
+     * more than one of them can 404: a caller reading only `404` cannot tell "this
+     * agent is not registered" from "the chain-routing lookup did not resolve", and
+     * has to guess from the body's prose — which a 404 raised before any handler
+     * ran does not carry. The path is the fact that settles it.
+     */
+    readonly path?: string;
+    constructor(status: number, body: string, statusText?: string, endpoint?: string, path?: string);
 }
 declare class SignatureVerificationError extends Error {
     constructor(message: string);
 }
+/**
+ * Atbash answered, and the answer was not a grant: the agent is not
+ * registered, or the reply could not be read. Unlike an unreachable judge this
+ * always denies, whatever `failClosed` says.
+ */
+declare class JudgeRefusalError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Thin typed fetch wrapper.
@@ -678,9 +937,25 @@ declare class HttpTransportError extends Error {
     });
 }
 
+declare function canonicalAllow(data: Record<string, unknown>): boolean;
+
 /** Normalize wire shapes (verdict casing, status, pubkey) to canonical forms. */
 
 declare function normalizeVerdict(raw: unknown): Verdict;
+/**
+ * Canonicalize `action_type` at the wire boundary, the way
+ * {@link normalizeVerdict} already canonicalizes `verdict`.
+ *
+ * `verdict` has been normalized here since the beginning and has never
+ * drifted between consumers. `action_type` was passed through raw, so every
+ * reader invented its own folding policy — `auditToolCall` compared exactly
+ * while `memory/scan.ts` trimmed and case-folded, and the same `" ALLOW "`
+ * was therefore an error on one path and permission on the other.
+ *
+ * Trim and case-fold only. Zero-width and homoglyph variants survive
+ * untouched, stay outside the known set, and still fail closed.
+ */
+declare function normalizeActionType(raw: unknown): string;
 declare function normalizeStatus(raw: unknown): JudgmentState;
 /** Wire pubkey may be a hex string, a Buffer/Uint8Array, or `{ data: [...] }`. */
 declare function pubkeyToHex(val: unknown): string;
@@ -689,9 +964,20 @@ interface AtbashUserConfig {
     agentKey?: string;
     orgName?: string;
     judgeEndpoint?: string;
-    blockchainRid?: string;
-    provider?: string;
-    providerModel?: string;
+    /**
+     * Response-signing pubkey of a self-hosted judge (66 hex). Setting it makes
+     * `fromConfig` use the self-hosted policy for `judgeEndpoint`, which is the
+     * only way a non-allowlisted judge host is accepted.
+     */
+    judgeVerifyPubKey?: string;
+    /**
+     * `"private"` pins every org to the private chain regardless of where the
+     * dashboard says it lives — the migration switch. Leave it unset for the
+     * normal mode, where each org's own chain decides. There is no `"public"`
+     * value; a caller that wants one specific chain passes `chain` or `network`
+     * at construction instead.
+     */
+    defaultChainNetwork?: Network;
     /** "1" / "true" turns on verbose diagnostics. See AtbashOptions.debug. */
     debug?: string;
 }
@@ -791,15 +1077,27 @@ declare function scanMemoryBatch(entries: MemoryEntry[], auth: AgentAuth, opts?:
 interface CommitMemoryOptions {
     /** Score in [1, 10]. Defaults to 5 (matches the Rell entity default). */
     score?: number;
+    /**
+     * Which memory file this commit targets. Defaults to `""` — the
+     * un-pathed slot, matching Rell's `file_path: text = ""` default.
+     * Pass an explicit filename (e.g. `"AGENTS.md"`) to keep files
+     * versioned independently on chain.
+     */
+    filePath?: string;
     /** Org name — when set, the SDK resolves which chain the agent lives on. */
     orgName?: string;
-    /** Atbash service endpoint for org→chain lookup. */
+    /** Atbash service endpoint — where memory reaches the chain, and the org→chain lookup. */
     endpoint?: string;
+    /** Self-hosted judge response-signing pubkey; required with a non-allowlisted `endpoint`. */
+    verifyPubKey?: string;
     chainOpts?: ChainOpts;
 }
 interface RollbackMemoryOptions {
     orgName?: string;
+    /** Atbash service endpoint — where memory reaches the chain, and the org→chain lookup. */
     endpoint?: string;
+    /** Self-hosted judge response-signing pubkey; required with a non-allowlisted `endpoint`. */
+    verifyPubKey?: string;
     chainOpts?: ChainOpts;
 }
 /**
@@ -821,6 +1119,7 @@ declare function commitMemoryVersion(plaintext: string, auth: AgentAuth, opts?:
  */
 interface AgentMemoryEntry {
     id: number;
+    filePath: string;
     content: string;
     decryptError?: string;
     score: number;
@@ -832,6 +1131,7 @@ interface AgentMemoryEntry {
 interface MemoryRollbackEvent {
     fromId: number;
     toId: number;
+    filePath: string;
     reason: string;
     signer: string;
     createdAt: number;
@@ -842,36 +1142,46 @@ interface MemoryRollbackEvent {
  * response is a single integer, so this is safe to call on every
  * memory-read hot path.
  */
-declare function getActiveMemoryId(auth: AgentAuth, chainOpts?: ChainOpts): Promise<number | null>;
+declare function getActiveMemoryId(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<number | null>;
 /**
  * Recent active memory entries — subset of active versions filtered
  * by the chain's `MEMORY_RECENT_WINDOW_MS`. For a time-unbounded view
- * of every currently active version, use `getAllAgentMemory`.
+ * of every currently active version, use `getActiveAgentMemory`.
  */
-declare function getActiveMemory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getRecentAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
 /**
  * All currently-active memory entries with no time cutoff. Use this
  * when you need every active version regardless of age.
  */
-declare function getAllAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getActiveAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
+interface MemoryHistoryPage {
+    /** Most versions to return, at most 200. Omit for the full history. */
+    maxCount?: number;
+    /** Return only versions with a lower id: the last id of the previous page. */
+    beforeId?: number;
+}
 /**
  * Full version history — active + inactive, most recent first. Used
- * by rollback UX to choose a target version.
+ * by rollback UX to choose a target version. Pass `page` to read it in
+ * pages; this needs a Dashboard and chain that support paging.
  */
-declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null, page?: MemoryHistoryPage): Promise<AgentMemoryEntry[]>;
 /**
  * Fetch a single memory entry by version id, including its current
- * `is_active` state.
+ * `is_active` state. Version ids are agent-unique on chain (not
+ * per-file), so `id` alone resolves the target row.
  */
 declare function getMemoryById(id: number, auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry>;
 /**
  * Audit trail of rollback events for this agent, most recent first.
+ * Scope by file with `filePath`; omit for a cross-file view.
  */
-declare function getRollbackHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<MemoryRollbackEvent[]>;
+declare function getRollbackHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<MemoryRollbackEvent[]>;
 /**
  * Roll back to a previously-committed memory version. The target
- * `toId` must exist and be currently inactive. `reason` is required
- * and is recorded on-chain in `memory_rollback_log`.
+ * `toId` must exist and be currently inactive. The chain resolves the
+ * target row's `file_path` from `toId` — no file path is passed in.
+ * `reason` is required and is recorded on-chain in `memory_rollback_log`.
  */
 declare function rollbackMemory(toId: number, reason: string, auth: AgentAuth, opts?: RollbackMemoryOptions): Promise<void>;
 
@@ -923,6 +1233,13 @@ interface ClassifyMemoryWriteOptions {
  *
  * Empty-content writes return `null`: they can't carry a poisoning
  * payload, and the regular audit path still sees them.
+ *
+ * THROWS on host input it cannot read without side effects: a proxy, an accessor where a data
+ * property is expected, a value with no safe projection, or one past the size bounds. Refusing is
+ * deliberate - a silent `null` would report "not a memory write" for a call nobody could classify,
+ * and memory protection would be skipped exactly where the input was strange. Callers that sit in a
+ * host hook MUST catch it and turn it into a decision; `guardMemoryWrite` and
+ * `MemoryGuardManager.handleBeforeToolCall` already do.
  */
 declare function classifyMemoryWrite(event: unknown, ctx: unknown, opts?: ClassifyMemoryWriteOptions): MemoryEntry | null;
 
@@ -948,6 +1265,8 @@ interface GuardMemoryWriteInput extends ClassifyMemoryWriteOptions {
     verifyPubKey?: string;
     /** Org name for chain resolution (public vs org-private chain). */
     orgName?: string;
+    /** Explicit chain target when the host already resolved and verified it. */
+    chainOpts?: ChainOpts;
     /** LLM confidence threshold for yellow escalation. Default 0.6. */
     threshold?: number;
     /** When false, red verdicts log but don't block. Default true. */
@@ -956,8 +1275,17 @@ interface GuardMemoryWriteInput extends ClassifyMemoryWriteOptions {
     debug?: boolean;
     /** Optional logger for debug probe + persist-failure warnings. */
     logger?: GuardLogger;
-    /** Absolute path of the agent's managed memory file. Required for chain commits — omitted skips them. */
-    memoryFilePath?: string;
+    /** Agent home directory names to accept beyond the built-in list. */
+    agentHomeDirs?: string[];
+    /**
+     * Root the caller keeps memory under, when it is not an agent home.
+     *
+     * Only pass a value the host stated outright. A root defaulted from the
+     * process working directory would make whichever directory the host happened
+     * to start in look like a memory store — which is how a stray MEMORY.md once
+     * ended up inside a plugin checkout.
+     */
+    memoryRoot?: string;
 }
 /** Plugin-facing decision. Shape mirrors what plugins return from `before_tool_call`. */
 interface GuardMemoryDecision {
@@ -972,25 +1300,57 @@ interface GuardMemoryWriteResult {
     decision?: GuardMemoryDecision;
     /** Present when handled and scan ran. Absent when scan threw. */
     scanResult?: MemoryScanResult;
-    /** Present when handled. True when a chain-commit was dispatched (fire-and-forget). */
+    /** Present when handled. True only after the chain transaction confirms. */
     committed?: boolean;
 }
 /**
- * Guarded memory-write flow. Returns `{ handled: false }` when the tool
- * call isn't a memory write, otherwise returns a `decision` the plugin
- * should return from its hook.
+ * Guard a memory write, and record what was decided.
+ *
+ * Wraps the decision rather than threading telemetry through its eight exits,
+ * so a later return added inside cannot quietly stop being counted.
  *
- * Verdict handling:
- * - `red`  → not persisted to chain; decision blocks (unless `enforce: false`)
- * - `yellow` → persisted with LLM score; decision allows
- * - `green`  → persisted with LLM score; decision allows
+ * Only a call this guard actually handled is recorded. A tool call that was
+ * never a memory write is not a memory operation, and counting it would put
+ * every unrelated edit into the number a memory migration reads.
  *
- * Chain commit is fire-and-forget: network errors are logged via
- * `logger.warn` but never surfaced to the caller. This mirrors the
- * existing plugin behaviour — chain is for audit/recovery, not gating.
+ * @param input - The tool call and the agent to judge it for.
+ * @returns What the guard decided; unchanged by the recording.
  */
 declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
 
+/**
+ * The chain slot of a memory file, computed the same way everywhere.
+ *
+ * The Rust core finds the slot by stripping the agent's home from the file's
+ * path, as an exact string prefix. The file path arrives resolved
+ * (`path.resolve`), but the home did not: on Windows `HOME=/home/agent`
+ * resolves the file to `C:\home\agent\...` and never matches, and a host that
+ * spells the drive or the user folder differently (`c:\users\me` against
+ * `C:\Users\Me`, both the same folder) did not match either. A file with no
+ * slot is scanned but never recorded on chain, silently, so the on-chain
+ * version record and its rollback/read checks were skipped for it.
+ *
+ * Here the home (and the memory root) is resolved like the file, and on a
+ * case-insensitive file system it is passed to the core spelled the way the
+ * file path spells it. The slot itself, the part below the agent home, keeps
+ * the file's own spelling, so slots recorded before this change still match.
+ *
+ * Known limit: a folder with NTFS per-directory case sensitivity enabled
+ * (`fsutil file setCaseSensitiveInfo`, or one created from WSL) can hold both
+ * `Me` and `me`; there ASCII case does separate folders, and a sibling spelled
+ * in another case would share the home's slots. Creating one needs write
+ * access to the home's parent. A follow-up can confirm the same folder on disk
+ * when the spellings differ.
+ */
+
+/** Path semantics: `node:path` here, `path.win32` / `path.posix` in tests. */
+type PathImpl = typeof nodePath;
+/**
+ * The chain slot for `target`, or null when it gets no chain record. `p`
+ * selects path semantics (tests pass `path.win32` to check Windows anywhere).
+ */
+declare function memorySlotOf(target: string, home: string, root?: string, extraHomes?: string[], p?: PathImpl): string | null;
+
 /**
  * Aligns a local `MemoryPointer` with chain's active memory version
  * via a TTL-cached pointer check. Inside the TTL window: no-op.
@@ -1017,6 +1377,8 @@ interface SyncMemoryOptions {
     /** Skip the TTL gate and force a chain check this call. Default false. */
     force?: boolean;
     chainOpts?: ChainOpts;
+    /** Exact chain slot for the managed file; omission keeps the cross-file API behavior. */
+    filePath?: string;
 }
 /**
  * `drifted: false` — pointer is still valid; caller can keep serving the local copy.
@@ -1050,10 +1412,19 @@ declare class PointerStore {
     private cache;
     private loading;
     constructor(filePath: string);
-    /** Resolves the pointer for `agentPubkeyHex`, or a zero-pointer that will force a sync on first use. */
-    get(agentPubkeyHex: string): Promise<MemoryPointer>;
-    /** Persists an updated pointer. Failures are swallowed to a logger callback (if provided) so sync never blocks the caller. */
-    set(agentPubkeyHex: string, pointer: MemoryPointer, onError?: (err: Error) => void): Promise<void>;
+    /**
+     * The pointer for one agent's file, or a zero-pointer forcing a sync.
+     *
+     * @param filePath - The file's chain slot, i.e. its basename.
+     */
+    get(agentPubkeyHex: string, filePath: string): Promise<MemoryPointer>;
+    /**
+     * Persist one file's pointer, leaving the agent's other files alone.
+     *
+     * Write failures are reported to `onError` rather than thrown: a cache that
+     * cannot be written must not take down the read it was speeding up.
+     */
+    set(agentPubkeyHex: string, filePath: string, pointer: MemoryPointer, onError?: (err: Error) => void): Promise<void>;
     private ensureLoaded;
     private loadOnce;
     private persist;
@@ -1065,6 +1436,8 @@ declare function defaultPointerPath(workspaceDir?: string): string;
 interface WrappedLogger {
     info(message: string, meta?: Record<string, unknown>): void;
     warn(message: string, meta?: Record<string, unknown>): void;
+    /** Wait for queued writes and surface any lost log entry. */
+    flush(): Promise<void>;
 }
 interface UpstreamLogger {
     info: (...args: unknown[]) => void;
@@ -1093,6 +1466,13 @@ interface ClassifyMemoryReadOptions {
  * Caller-supplied `patterns` are MERGED with the defaults (matches
  * Node's original behavior — extending in one plugin doesn't disable
  * standard coverage).
+ *
+ * THROWS on host input it cannot read without side effects: a proxy, an accessor where a data
+ * property is expected, a value with no safe projection, or one past the size bounds. Refusing is
+ * deliberate - a silent `null` would report "not a memory write" for a call nobody could classify,
+ * and memory protection would be skipped exactly where the input was strange. Callers that sit in a
+ * host hook MUST catch it and turn it into a decision; `guardMemoryWrite` and
+ * `MemoryGuardManager.handleBeforeToolCall` already do.
  */
 declare function classifyMemoryRead(event: unknown, ctx: unknown, opts?: ClassifyMemoryReadOptions): boolean;
 
@@ -1117,10 +1497,10 @@ interface HookDecision {
      * failure, a rolled-back version), and a host must never re-judge its way past
      * one.
      *
-     * Absent or false means the guard reached no decision — it was inside its cache
-     * window, chain was unreachable, the scan never ran, the file it can vouch for
-     * is not the file being read, or it is in observe mode. Those calls are
-     * unaudited: fall through to your own judge exactly as for a `null` return.
+   * Absent or false means the guard reached no decision — for example, the scan
+   * never ran or this manager does not own the requested file. In enforce mode,
+   * failed chain verification of the managed file is a block, never an unaudited
+   * allow. In observe mode unverified calls remain unaudited.
      *
      * So the host rule is:
      *   `if (d.block) deny;  else if (d.audited) allow;  else judge it yourself;`
@@ -1139,6 +1519,17 @@ interface MemoryGuardManagerOptions {
     workspaceDir: string;
     /** Absolute MEMORY.md path. Default `<workspaceDir>/MEMORY.md`. */
     memoryFilePath?: string;
+    /**
+     * Root this host keeps memory under, when it is not an agent home.
+     *
+     * Only set this from a value the host stated outright — never from
+     * `process.cwd()`. A guessed root makes whichever directory the host started
+     * in look like a memory store, which is how a stray MEMORY.md once ended up
+     * inside a plugin checkout.
+     */
+    memoryRoot?: string;
+    /** Agent home directory names to accept beyond the built-in list. */
+    agentHomeDirs?: string[];
     /** Persistent pointer file. Default `<workspaceDir>/.atbash/memory-pointer.json`. */
     pointerFilePath?: string;
     /** File-backed log. Default `<workspaceDir>/.atbash/plugin.log`. */
@@ -1185,11 +1576,45 @@ declare class MemoryGuardManager {
     private readonly pointerStore;
     private readonly logger;
     private readonly memoryFilePath;
+    /** Base for resolving the relative paths a host sends. */
+    private readonly workspaceDir;
+    /** Set by `verifyOneFile` when the file it checked was actually on chain. */
+    private lastVerified;
     private readonly ttlMs;
     private readonly rollbackMinScore;
     private readonly enforce;
     private readonly agentPubkeyHex;
+    /**
+     * Memoized org→chain resolution. Reads have to hit the SAME chain
+     * writes did, so an org-scoped guard must resolve `orgName` to
+     * network exactly like `commitMemoryVersion` does. Without this
+     * cache the read path would either (a) hit the SDK-default chain
+     * every time — silently returning "no active memory on chain" when
+     * writes landed on the org's actual chain, or (b) hammer
+     * `/api/org-network` on every read. `undefined` means "not yet
+     * resolved"; a resolved `null` means "no org / use raw chainOpts".
+     */
+    private _resolvedChainOpts;
+    private _resolveChainInflight?;
     constructor(opts: MemoryGuardManagerOptions);
+    /**
+     * Carry this manager's host into `chainOpts`.
+     *
+     * Memory reads reach the chain through that host, and they are handed only
+     * `chainOpts` — without this a self-hosted deployment would read from the
+     * compiled-in default host while writing to its own.
+     */
+    private withEndpoint;
+    /**
+     * Resolve `orgName` → chain once, cache forever. `commitMemoryVersion`
+     * already does this for writes; without the same call on the read
+     * path, a client on the SDK's baked default chain reads from the wrong
+     * chain and reports "no active memory" for an agent whose writes did
+     * land — on the org's actual chain. An explicit `chainOpts.blockchainRid`
+     * still wins (caller vouched for it); everything else honors the
+     * dashboard's `org_networks` map.
+     */
+    private resolveChainOpts;
     /**
      * One-shot chain probe at plugin registration. Refreshes MEMORY.md
      * from chain when drifted and score passes threshold. Fire-and-forget
@@ -1197,15 +1622,27 @@ declare class MemoryGuardManager {
      */
     runBootProbe(): Promise<void>;
     /**
-     * Returns a `HookDecision` when the guard reached a decision about this event.
-     * Returns `null` when it did not — either the event isn't memory-related, or it
-     * is but the guard could not check it. In both cases the host falls through to
-     * its own audit.
+     * Bring one chain file into step with its local counterpart.
+     *
+     * Only a file that already exists locally is touched. Restoring one that is
+     * absent would mean choosing where to create it, and the root is a guess the
+     * moment more than one could apply — the same guess that once wrote a
+     * MEMORY.md into a plugin checkout.
+     *
+     * @returns What happened, for the single summary line the caller logs.
+     */
+    private syncOneAtBoot;
+    /**
+     * Where a chain slot's file lives locally, or null when we do not have it.
      *
-     * A returned decision carries `audited` (see `HookDecision`). Only
-     * `{ allow: true, audited: true }` means "checked and cleared"; anything else
-     * that allows is a call the host still needs to judge.
+     * A stated root is tried first, then each agent home that actually exists in
+     * the user's home directory — the same rule that produced the slot, run
+     * backwards. Only an existing file is returned: creating one would mean
+     * picking a root, and picking is guessing.
      */
+    private locate;
+    /** Roots a chain slot may be joined to, most specific first. */
+    private memoryRoots;
     handleBeforeToolCall(event: unknown, ctx: unknown): Promise<HookDecision | null>;
     private mapGuardResult;
     /**
@@ -1223,9 +1660,70 @@ declare class MemoryGuardManager {
      * also covers events carrying two different path keys, where the classifier
      * and the host could otherwise disagree about which one is authoritative.
      */
-    private vouchesForTarget;
+    /**
+     * The memory files this tool call reads, as absolute paths.
+     *
+     * Relative paths resolve against the workspace, not `process.cwd()`. The host
+     * sends paths relative to the agent's workspace; resolving them against the
+     * process's own directory made the guard protect whichever directory the host
+     * happened to start in, which on one machine was a plugin checkout.
+     *
+     * @returns Every named target, de-duplicated; empty when the call names none.
+     */
+    private readTargets;
+    /**
+     * Say what the read classifier saw and what it concluded.
+     *
+     * The write path has `emitDebugProbe`; this is its counterpart, so a tool
+     * call can be followed across the fork instead of only after it. `false` here
+     * is the normal answer for a write — it means the call goes to the write
+     * classifier next, not that it was ignored.
+     *
+     * @param isMemoryRead - What `classifyMemoryRead` returned.
+     */
+    private emitReadProbe;
+    /**
+     * The chain slot for a path, or null when the file gets no chain record.
+     *
+     * One helper so the boot probe and every read agree: taking a basename in one
+     * place and a relative path in the other would verify a file against a record
+     * that is not its own.
+     */
+    private slotFor;
+    /**
+     * Verify every memory file this call reads, each against its own chain slot.
+     *
+     * A call naming several files is only cleared when all of them are, so one
+     * unverifiable file cannot ride along with a verified one.
+     *
+     * @returns A block for the first file that fails, an audited allow when all
+     *   were verified, or null when none of them is on chain.
+     */
     private handleMemoryRead;
+    /**
+     * Check one memory file against the chain slot of the same name.
+     *
+     * A file with no chain version is passed through rather than blocked: there
+     * is no claim to protect, so refusing would only stop an agent reading memory
+     * it has never committed. A file that IS on chain must match, or the read is
+     * refused — that is the whole guarantee.
+     *
+     * @returns A decision when the read must not proceed, else null.
+     */
+    private verifyOneFile;
+    /** Complete queued audit-log writes before a host shuts down or removes its workspace. */
+    flushLogs(): Promise<void>;
+    /**
+     * A read this guard could not verify.
+     *
+     * Enforcing, that is a block. Observing, the host audits it as usual — but
+     * the reason is said out loud either way, or an unverified read looks
+     * identical to a clean one in the log.
+     */
+    private unverifiedRead;
     private writeMemoryAtomic;
+    /** Replace `target` in one step, so a reader never sees a half-written file. */
+    private writeFileAtomic;
 }
 declare function createMemoryGuardManager(opts: MemoryGuardManagerOptions): MemoryGuardManager;
 
@@ -1259,6 +1757,20 @@ interface TelemetryConfig {
      * `{ Authorization: "Bearer <hex>" }`). Required to actually export.
      */
     getAuthHeaders?: () => Record<string, string>;
+    /**
+     * Hashes the agent key before it is emitted on a wide event.
+     *
+     * Defaults to an unsalted SHA-256, which is de-identification rather than
+     * anonymisation: agent pubkeys are public on chain and can be enumerated, so
+     * the mapping is recoverable by anyone holding that list. Supply a salted
+     * hasher to make it uncorrelatable, at the cost of joining across
+     * deployments.
+     *
+     * Injected rather than imported so the telemetry modules need nothing from
+     * the native addon. Left unset, the agent field is dropped from events
+     * rather than falling back to the raw key.
+     */
+    hashAgentKey?: (pubkeyHex: string) => string;
 }
 declare function setupTelemetry(config: TelemetryConfig): void;
 /**
@@ -1281,6 +1793,111 @@ declare function flushTelemetry(): Promise<void>;
  */
 declare function shutdownTelemetry(): Promise<void>;
 
+/**
+ * Wide events: one row per SDK operation, alongside the counters.
+ *
+ * The counters in `telemetry.ts` are aggregated inside this process before
+ * export, so Honeycomb never receives a per-operation row. That is fine for
+ * "is it up" and useless for everything else: a question nobody attached an
+ * attribute for in advance cannot be answered later, because the data to
+ * answer it never existed. "Which org sees the most failures", "what preceded
+ * a fail-closed", "is the new release slower" are all that shape.
+ *
+ * So each operation also emits one event carrying its whole context. The
+ * counters stay — they are the right tool for health boards and alerts, and
+ * they are not sampled.
+ *
+ * TWO RULES SHAPE THIS MODULE.
+ *
+ * The payload is METADATA ONLY, and the allowlist below is the whole of it:
+ * function name, outcome, latency, error class, error status and path, SDK
+ * version, chain, and a hash of the agent key. Action text, tool arguments, policy text, organisation
+ * names and keys never appear — not as a field that is emptied, but as a field
+ * that does not exist, so there is nothing to forget to strip.
+ *
+ * The agent key is hashed, never sent raw, and the hasher is INJECTED rather
+ * than imported: this module needs nothing from the native addon. With no
+ * hasher supplied the field is DROPPED rather than falling back to the raw
+ * key, so the guarantee does not depend on wiring somebody could forget.
+ *
+ * NOTE on what hashing does and does not buy. Agent pubkeys are public on
+ * chain and can be enumerated, so an UNSALTED hash is reversible by anyone who
+ * can read the chain: it is de-identification, not anonymisation. A salted
+ * hasher makes it uncorrelatable and costs cross-deployment joins. Which one
+ * is wanted is the caller's decision; this module only guarantees the raw key
+ * never leaves.
+ *
+ * And the richer payload has its own switch. Counters carry a function name
+ * and a source. These events carry agent and org identity off a customer's
+ * machine, which is a different proposition for a security product, so
+ * `ATBASH_TELEMETRY_EVENTS_DISABLED=1` turns them off while leaving the health
+ * counters on. Both remain subject to the existing global opt-out.
+ */
+
+/** Attributes an event may carry. Anything not listed here cannot be emitted. */
+interface OperationEvent {
+    /** SDK function, matching the counter's `function.name` so the two join. */
+    functionName: string;
+    durationMs: number;
+    status: "success" | "error";
+    /**
+     * Hex pubkey of the agent the call was made as. Hashed before it is emitted,
+     * and omitted entirely when no hasher is configured.
+     */
+    agentPubkey?: string;
+    /**
+     * Blockchain RID of the chain this call concerned.
+     *
+     * The RID rather than a network label: it is public infrastructure, it is
+     * unambiguous, and it identifies the deployment without naming a customer.
+     */
+    chain?: string;
+    /** Constructor name of the thrown error, e.g. `AtbashAPIError`. */
+    errorClass?: string;
+    /** HTTP status, or 0 when the request never completed. */
+    errorStatus?: number;
+    /**
+     * Request path the status came from, e.g. `/api/v1/judge`.
+     *
+     * The class alone does not say what failed: several routes answer one call
+     * and more than one can 404, so `AtbashAPIError` cannot distinguish "this
+     * agent is not registered" from "the chain-routing lookup did not resolve".
+     * The path settles it.
+     *
+     * Carries no query string — `requestPath` strips it at the point the error
+     * is built, because a query string carries org names, tool call ids and the
+     * agent pubkey. Structured and already sanitised, so this stays inside the
+     * metadata rule where an error message would not.
+     */
+    errorPath?: string;
+    /**
+     * Short categorical result, when "success" is too coarse — e.g. a memory
+     * write that scanned clean but never reached the chain.
+     *
+     * Categorical by contract: a value a caller chooses from a fixed vocabulary,
+     * never free text and never anything derived from user content.
+     */
+    outcome?: string;
+}
+/** Hashes an agent key for emission. Supplied by `setupTelemetry`. */
+type AgentKeyHasher = (pubkeyHex: string) => string;
+declare function configureEvents(next: Logger | null, opts?: {
+    version?: string;
+    source?: string;
+    hashAgentKey?: AgentKeyHasher;
+}): void;
+/** True when an event would actually be emitted. Exported for tests and callers that build context lazily. */
+declare function eventsAreOn(): boolean;
+/**
+ * Emit one wide event for a completed operation.
+ *
+ * Never throws and never blocks: telemetry failing must not change what the
+ * caller observes. Does nothing when events are off.
+ *
+ * @param e - The completed operation.
+ */
+declare function recordEvent(e: OperationEvent): void;
+
 /**
  * Rust core does the work; `browser/encrypted-toolcall.ts` mirrors it for the
  * browser and must produce the same columns.
@@ -1378,4 +1995,4 @@ declare function containsSecret(text: string): boolean;
 declare function createMemorySnapshot(entries: MemoryEntry[], takenAt: number): MemorySnapshot;
 declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
 
-export { type ActionType, type AgentAuth, type AgentLookupOptions, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };
+export { type ActionType, type AgentAuth, type AgentLookupOptions, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, JudgeRefusalError, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, type MemoryHistoryPage, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OperationEvent, type OrgSubscription, PRIVATE_CHAIN, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, canonicalAllow, chainForNetwork, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, configureEvents, configureJailHold, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, eventsAreOn, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, guardMemoryWrite, isEnvelope, isJailHeld, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, memorySlotOf, normalizeActionForHash, normalizeActionType, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, recordEvent, redactJsonStrings, redactSecrets, releaseJailHolds, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };