@atbash/sdk 0.9.0-dev.0 → 0.9.1

package/dist/index.d.ts

@@ -11,8 +11,34 @@ interface ValidatedEndpoint {
     policy: "default" | "self-hosted";
     verifyPubKey: string | null;
 }
+/**
+ * Builds the trusted judge host set.
+ *
+ * The compiled-in default is always trusted: a `prod` build resolves it to
+ * atbash.ai, a dev build to whatever DEV_ENDPOINT was set at build time. No
+ * dev host is spelled out in source, and dev builds still validate their own
+ * default.
+ *
+ * Exported for tests only. The set is a build-time value and is deliberately
+ * never read from the process environment — an env var would let anyone widen
+ * the allowlist of an already-shipped artifact, which is the silent-redirection
+ * attack the allowlist exists to prevent (F-003). Asserting that requires
+ * calling this with the environment set, so it cannot stay module-private.
+ *
+ * @internal
+ */
+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 PUBLIC_CHAIN: ChainConfig;
+declare const PRIVATE_CHAIN: ChainConfig;
+declare function chainForNetwork(network: Network): ChainConfig;
+
 /**
  * User-facing types. Two groups:
  *  - Core types — the exact shapes the Rust core emits across the NAPI
@@ -143,6 +169,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;
@@ -171,6 +202,8 @@ interface JudgeResult {
 interface JudgmentStatus {
     status: JudgmentState;
     verdict: Verdict;
+    /** Same canonical executable permission as {@link JudgeResult.allow}. */
+    allow: boolean;
     reason: string;
     judgmentId: string;
     onChain?: boolean;
@@ -257,6 +290,13 @@ interface AgentPolicy {
     isCustom: boolean;
     defaultPolicy: string;
 }
+/** Options for agent metadata and policy lookups. */
+interface AgentLookupOptions {
+    /** Resolve the agent's network from this organization's active network. */
+    orgName?: string;
+    /** Explicit per-call chain override. `network` selects the dashboard chain. */
+    chainOpts?: ChainOpts;
+}
 /** Optional structured logger. */
 interface AtbashLogger {
     info?(...args: unknown[]): void;
@@ -266,7 +306,24 @@ interface AtbashLogger {
 interface AtbashOptions {
     endpoint?: string;
     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 — `"public"` or `"private"`. 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
@@ -293,6 +350,12 @@ interface AtbashOptions {
     orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     failClosed?: 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"
+     * and knowing why it failed. Opt-in because that body can echo the action.
+     */
+    debug?: boolean;
     logger?: AtbashLogger;
 }
 /** Canonical decision returned by `auditToolCall`. */
@@ -327,20 +390,24 @@ 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.debug}. */
+    debug?: boolean;
     logger?: AtbashLogger;
 }
 /** Options accepted by `judgeAction`. */
 interface JudgeOptions {
     toolName?: string;
     toolArgsJson?: string;
-    provider?: string;
-    model?: string;
     verifyPubKey?: string;
     /** Per-call override of {@link AtbashOptions.orgEncryptionPubKey}. */
     orgEncryptionPubKey?: string;
@@ -376,12 +443,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;
@@ -395,6 +456,9 @@ declare class Atbash {
     readonly orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     readonly failClosed: boolean;
+    /** Org key learned from the last agent-exists check, for this agent only. */
+    private _orgKeyFromChain;
+    private readonly debug;
     private readonly logger;
     private readonly http;
     /**
@@ -402,13 +466,57 @@ 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
+     * data that hasn't changed. The `org_encryption_pubkey` field CAN change
+     * — an org toggling encryption mid-session — so the TTL is deliberately
+     * short (see `AGENT_EXISTS_TTL_MS`). Keyed by (pubkey, network) so
+     * cross-agent / cross-network calls don't collide.
+     */
+    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 _authBearer;
+    private _authBearers;
+    /** Guards `logEnvironmentOnce` — hosts construct several clients. */
+    private static environmentLogged;
     constructor(privkey: string, options?: AtbashOptions);
+    /**
+     * Say which environment this build talks to, once per process.
+     *
+     * The endpoint and both chain RIDs are compiled in, chosen by the npm tag,
+     * and no configuration repoints a released build. So installing the build
+     * for the wrong environment is invisible: the plugin loads, the hook fires,
+     * and every judge call fails because the agent does not exist on the chain
+     * this build targets. Organisation names are not unique across environments
+     * either, so an org resolving is not evidence the build is right.
+     */
+    private logEnvironmentOnce;
     /**
      * Construct from resolved config: explicit overrides → env vars → the
      * `~/.config/atbash/config.json` file (see userConfig.resolve). The private
@@ -451,8 +559,27 @@ declare class Atbash {
      * explicitly false.
      */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
+    /**
+     * One exit for every judge failure.
+     *
+     * Status and reason go in the *message*, not only in the meta object: hosts
+     * print the message and drop the meta, which is why this read as a bare
+     * "judge API failed" while the judge was answering with a precise reason.
+     * The response body follows only under `debug`, since it can echo the action.
+     */
+    private failJudge;
     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
+     * server's GET /api/v1/judge routes to that chain when the SDK sends
+     * a `brid` query param; without it, the server falls back to public.
+     * Callers on the private chain must pass a `chainOpts` (or configure
+     * the client on the private chain) — otherwise polling a POSTed
+     * judgment on the private chain 404s at the server.
+     */
+    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[]>;
@@ -461,8 +588,8 @@ declare class Atbash {
     getOrgTierInfo(orgName: string): Promise<TierInfo | null>;
     getPendingHeldActions(orgName: string, maxCount: number): Promise<HeldAction[]>;
     getHeldActionReviews(orgName: string, maxCount: number): Promise<HeldActionReview[]>;
-    getAgentDetail(agentPubkey: string): Promise<Record<string, unknown>>;
-    getAgentPolicy(agentPubkey: string): Promise<AgentPolicy>;
+    getAgentDetail(agentPubkey: string, options?: AgentLookupOptions): Promise<Record<string, unknown>>;
+    getAgentPolicy(agentPubkey: string, options?: AgentLookupOptions): Promise<AgentPolicy>;
     getSafetyStats(): Promise<Record<string, unknown>>;
     /**
      * Org's subscription on a specific chain. The `network` arg selects
@@ -485,7 +612,9 @@ declare class Atbash {
      *   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.
+     * A lookup that names exactly one chain wins outright. Where it names
+     * neither (a brand-new org) or cannot choose between them, the client's
+     * configured default decides.
      */
     resolveChainForOrg(orgName: string): Promise<ChainConfig>;
     /**
@@ -497,6 +626,8 @@ declare class Atbash {
     private resolveChainFromMap;
     /** Drop any cached chain resolutions. Useful in tests. */
     clearChainCache(): void;
+    /** Drop the short-TTL `/api/ai/exists` cache. Useful in tests. */
+    clearAgentExistsCache(): void;
     /**
      * Wrap an SDK method body in telemetry — records the call at start
      * and a success/error duration at end. Re-throws on failure so the
@@ -511,6 +642,14 @@ declare class Atbash {
      * chains; otherwise the client's default.
      */
     private bridFromChainOpts;
+    /**
+     * Resolve the dashboard chain used by agent metadata/policy reads.
+     * Explicit per-call network overrides win; otherwise use the supplied org
+     * or the client's configured default org. A custom BRID is intentionally
+     * left untouched because it cannot be represented by the dashboard's
+     * public/private query selector.
+     */
+    private resolveAgentLookupNetwork;
     /**
      * Get-or-create a Bearer token for dashboard reads. The token is a
      * signed `log_tool_call` op (locally signed, never submitted) — the
@@ -523,10 +662,46 @@ declare class Atbash {
     private riskEngineGet;
     private riskEnginePost;
     private riskEngineRecords;
+    /**
+     * BRID for an org — one round-trip to the map, honoring the client's chain
+     * 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;
-    /** Wrap a *transport* failure (fetch threw, no response) as an AtbashAPIError. */
+    /**
+     * Wrap a transport failure (fetch threw, no response) as an AtbashAPIError.
+     *
+     * `HttpTransportError.kind` names the cause; the message is already
+     * human-readable. `debug` echoes the original exception so operators can
+     * cross-reference with node / undici logs when a class doesn't match.
+     */
     private transportError;
     private json;
     static generateKeypair(): KeyPair;
@@ -546,15 +721,79 @@ declare class AtbashAPIError extends Error {
     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);
 }
 
+/**
+ * Thin typed fetch wrapper.
+ *
+ * openapi-typescript emits types only (no runtime client), so this is the
+ * single hand-written transport — generic `get`/`post` over global `fetch`
+ * with a per-request timeout. The endpoint-specific request/response *shapes*
+ * are pulled from the generated `schema.ts` at the call sites in client.ts, so
+ * the wire contract still lives in spec/openapi.yaml. Methods return the raw
+ * `Response` so the caller can read the exact bytes the server signed before
+ * any decode (judge signature verification) — mirroring the Python surface's
+ * use of raw httpx (DECISIONS 2026-05-22).
+ */
+type QueryValue = string | number | boolean | undefined | null;
+declare class HttpClient {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(baseUrl: string, timeoutMs: number);
+    buildUrl(path: string, query?: Record<string, QueryValue>): string;
+    get(path: string, query?: Record<string, QueryValue>, headers?: Record<string, string>): Promise<Response>;
+    post(path: string, body: unknown, headers?: Record<string, string>): Promise<Response>;
+    private fetch;
+}
+/**
+ * A transport failure the SDK can act on. Every real cause the platform surfaces
+ * lands as one of these — the message names the cause in plain language so a
+ * plugin can show it to a user without decoding httpx / fetch internals.
+ *
+ * `cause` preserves the original error for debug logging; consumers that want
+ * the raw exception (e.g. tests) read it there.
+ */
+declare class HttpTransportError extends Error {
+    readonly kind: "timeout" | "aborted" | "dns" | "connect_refused" | "connection_reset" | "unknown";
+    constructor(kind: HttpTransportError["kind"], message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+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;
@@ -563,9 +802,22 @@ 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;
 }
 declare function getConfigDir(): string;
 declare function getConfigPath(): string;
@@ -576,6 +828,26 @@ declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): strin
 declare function resolveKeyPath(input?: string): string;
 declare function loadAgentFromFile(keyPath?: string): AgentAuth;
 
+/**
+ * Accepted key filenames, in precedence order.
+ *
+ * `guard-client-key` stays first: it is the name every existing install
+ * already has, and changing which file wins would silently switch agent
+ * identity for anyone holding both. `atbash-client-key` is accepted because
+ * it is the name people actually create — the old one carries retired
+ * branding — and hitting ENOENT on a key you just wrote, from a plugin that
+ * still reports itself installed, is a miserable first run.
+ */
+declare const KEY_FILENAMES: readonly ["guard-client-key", "atbash-client-key"];
+/** Every path checked when no explicit key path is given, in order. */
+declare function keyPathCandidates(): string[];
+/**
+ * Pick the key path: an explicit input wins untouched; otherwise the first
+ * accepted filename that exists, falling back to the preferred name so the
+ * error names something recognisable when nothing is there.
+ */
+declare function chooseKeyPath(input: string | undefined, exists: (p: string) => boolean): string;
+
 /**
  * Canonical secret kinds reported by the Rust core in `SecretMatch.kind`.
  * Wire is permissive (modelled as a free string in {@link SecretMatch})
@@ -594,6 +866,42 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
     reason?: string;
 };
 
+/**
+ * The boot memory-sync failure line.
+ *
+ * Split out of `guard-manager.ts` so it can be asserted without constructing a
+ * guard manager, which needs the native addon. The message is the whole point
+ * of AT-304: hosts print the message and drop the structured meta, so a cause
+ * that lives only in meta never reaches the operator.
+ */
+/** Advice, not a diagnosis — appended only when the cause is unhelpful. */
+declare const BOOT_SYNC_HINT = "check the chain endpoint and orgName if the cause above does not explain it";
+/**
+ * Lead with the real cause.
+ *
+ * The previous wording named the chain endpoint and orgName as the things to
+ * check, which sent operators to verify configuration that was already correct
+ * while the actual cause (a node answering `404 Can't find blockchain with
+ * blockchainRID: …` for a chain it does not host) stayed hidden.
+ */
+declare function bootSyncFailureLine(cause: unknown): string;
+
+/**
+ * Make a chain query result crossable at the NAPI boundary.
+ *
+ * `postchain-client` decodes a Rell `byte_array` into a Node `Buffer`. The
+ * core's `parse*` functions take `serde_json::Value`, and NAPI-RS cannot
+ * convert a `Buffer` into one — it reaches the methods every `Uint8Array`
+ * inherits and fails with "JS functions cannot be represented as a
+ * serde_json::Value", which names functions for what is a plain Buffer.
+ *
+ * The conversion has to happen here because the failure is in the argument
+ * conversion, before any core code runs. Of the shapes the core accepts —
+ * hex string, `[u8]`, `{ data: [...] }` — hex is the cheapest to produce.
+ */
+/** Recursively rewrite byte containers to hex, leaving everything else as-is. */
+declare function gtvToFfiSafe(value: unknown): unknown;
+
 /** Derive the 32-byte AES key from an agent's secp256k1 privkey (hex). Deterministic — same privkey always yields the same key. */
 declare function deriveMemoryKey(privkey: string): Promise<Buffer>;
 /** Encrypt UTF-8 plaintext. `ciphertext` has the 16-byte GCM auth tag appended, matching the SDK's on-chain byte layout. */
@@ -608,8 +916,8 @@ declare function decryptMemoryContent(ciphertext: Buffer, nonce: Buffer, key: Bu
  * Scan a single memory entry for poisoning.
  *
  * `auth` is the agent that signs the on-chain audit log for the
- * LLM-judge call. The LLM is authoritative; unicode-evasion presence
- * is surfaced to the prompt so the LLM can weight suspicion accordingly.
+ * LLM-judge call. Unicode-evasion presence is surfaced to the prompt
+ * so the LLM can weight suspicion accordingly.
  */
 declare function scanMemory(entry: MemoryEntry, auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult>;
 /**
@@ -623,15 +931,26 @@ 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. */
     endpoint?: string;
+    /** Self-hosted judge response-signing pubkey; required with a non-allowlisted `endpoint`. */
+    verifyPubKey?: string;
     chainOpts?: ChainOpts;
 }
 interface RollbackMemoryOptions {
     orgName?: string;
     endpoint?: string;
+    /** Self-hosted judge response-signing pubkey; required with a non-allowlisted `endpoint`. */
+    verifyPubKey?: string;
     chainOpts?: ChainOpts;
 }
 /**
@@ -640,9 +959,7 @@ interface RollbackMemoryOptions {
  * deactivated on-chain.
  *
  * The caller is responsible for running `scanMemory` first when
- * appropriate — this function does not gate on the verdict. The
- * `score` parameter is the only metadata that flows in alongside
- * the ciphertext.
+ * appropriate — this function does not gate on the verdict.
  */
 declare function commitMemoryVersion(plaintext: string, auth: AgentAuth, opts?: CommitMemoryOptions): Promise<void>;
 /**
@@ -655,6 +972,7 @@ declare function commitMemoryVersion(plaintext: string, auth: AgentAuth, opts?:
  */
 interface AgentMemoryEntry {
     id: number;
+    filePath: string;
     content: string;
     decryptError?: string;
     score: number;
@@ -666,6 +984,7 @@ interface AgentMemoryEntry {
 interface MemoryRollbackEvent {
     fromId: number;
     toId: number;
+    filePath: string;
     reason: string;
     signer: string;
     createdAt: number;
@@ -674,71 +993,53 @@ interface MemoryRollbackEvent {
  * Cheap version-pointer probe. Returns just the id of the current
  * active memory (or null if none). No ciphertext is transferred — the
  * response is a single integer, so this is safe to call on every
- * memory-read hot path. Callers that hold a decrypted local copy can
- * compare against a stored pointer and only refetch the full row via
- * `getActiveMemory` when the id has changed.
+ * 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` (10 days at time of
- * writing). Intended for prompt injection at agent runtime, where
- * stale memory is worse than missing memory. For a time-unbounded
- * view of every currently active version, use `getAllAgentMemory`.
+ * by the chain's `MEMORY_RECENT_WINDOW_MS`. For a time-unbounded view
+ * 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 — e.g., a
- * dashboard listing, or a long-running agent whose oldest active
- * versions may have fallen outside `getActiveMemory`'s recent window.
+ * 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[]>;
 /**
- * Full version history — active + inactive, most recent first.
- * Used by rollback UX to choose a target version.
+ * Full version history — active + inactive, most recent first. Used
+ * by rollback UX to choose a target version.
  */
-declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
 /**
  * Fetch a single memory entry by version id, including its current
- * `is_active` state. Useful for inspecting a historical version
- * before rolling back to it.
+ * `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>;
 
-/**
- * Classify a plugin tool-call event as a memory write.
- *
- * Plugins receive `before_tool_call` events from their host runtime
- * (openclaw, Claude API, MCP, etc.) with varying argument shapes. This
- * module normalizes across shapes and returns a `MemoryEntry` when the
- * call is writing to a memory-like path, or `null` when the SDK should
- * skip the memory-scan path entirely.
- *
- * `event` and `ctx` are typed `unknown` so any plugin can pass its
- * native hook payloads without adaptation — the classifier probes
- * common key names at runtime.
- */
-
 /**
  * Tool names that indicate a memory write. Lowercase — matched
- * case-insensitively so both OpenClaw (lowercase) and Claude API
- * family (TitleCase) hit.
+ * case-insensitively so OpenClaw (lowercase) and Claude API family
+ * (TitleCase) both hit.
  */
 declare const DEFAULT_MEMORY_WRITE_TOOL_NAMES: ReadonlyArray<string>;
 /**
  * File path substrings that indicate a memory-shaped target. Callers
- * can extend or override this list via `classifyMemoryWrite` options.
+ * extend or override via `classifyMemoryWrite` options.
  */
 declare const DEFAULT_MEMORY_PATH_PATTERNS: ReadonlyArray<string>;
 /**
@@ -778,21 +1079,15 @@ interface ClassifyMemoryWriteOptions {
  *
  * Empty-content writes return `null`: they can't carry a poisoning
  * payload, and the regular audit path still sees them.
- */
-declare function classifyMemoryWrite(event: unknown, ctx: unknown, opts?: ClassifyMemoryWriteOptions): MemoryEntry | null;
-
-/**
- * Plugin-agnostic memory-write guard.
- *
- * A single call that replaces the plugin's usual memory-write branch:
- *   classify → scan (Layer 1 regex + Layer 2 LLM) → gate on verdict →
- *   persist to chain (fire-and-forget when allowed) → return decision.
  *
- * Plugins call this from their `before_tool_call` hook. When it returns
- * `{ handled: false }` the call wasn't a memory write and the plugin
- * should fall through to its regular tool-call audit. When
- * `{ handled: true }` the plugin returns `decision` directly.
+ * 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;
 
 /**
  * Minimal logger accepted by `guardMemoryWrite`. Plugins pass their
@@ -888,12 +1183,19 @@ interface SyncMemoryOptions {
  * `drifted: false` — pointer is still valid; caller can keep serving the local copy.
  * `drifted: true`  — active id changed on chain; `current` is the fresh decrypted row
  *                    (or `null` if active memory was removed entirely).
+ *
+ * `checked` — whether this call actually queried chain. `false` means the TTL
+ * window was still open and the pointer was trusted without contacting chain, so
+ * `drifted: false` carries no evidence about the current state. Callers that
+ * vouch for content to a third party must not treat an unchecked result as proof.
  */
 type SyncMemoryResult = {
     drifted: false;
+    checked: boolean;
     pointer: MemoryPointer;
 } | {
     drifted: true;
+    checked: true;
     current: AgentMemoryEntry | null;
     pointer: MemoryPointer;
 };
@@ -934,7 +1236,7 @@ declare function createFileLogger(filePath: string, upstream?: UpstreamLogger):
 /** Default log-file location — `<workspaceDir>/.atbash/plugin.log`. */
 declare function defaultPluginLogPath(workspaceDir?: string): string;
 
-/** Dedicated memory-read tool names, matched case-insensitively. Extend via options. */
+/** Dedicated memory-read tool names, matched case-insensitively. */
 declare const DEFAULT_MEMORY_READ_TOOL_NAMES: ReadonlyArray<string>;
 interface ClassifyMemoryReadOptions {
     /** Tool names that always count as memory reads. Merged with defaults. */
@@ -948,15 +1250,56 @@ interface ClassifyMemoryReadOptions {
  * Returns `true` when this tool call is a memory read — either a
  * dedicated memory-read tool from `readToolNames`, or a generic read
  * tool (`read` / `read_file`) targeting a memory-shaped path.
+ *
+ * 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;
 
-/** Decision the manager returns to the plugin's `before_tool_call` handler. */
+/**
+ * Decision the manager returns to the plugin's `before_tool_call` handler.
+ *
+ * `allow: true` alone is NOT evidence that anything was checked. Read `audited`
+ * to tell the two apart, and route un-audited calls to your own judge — see the
+ * field docs below.
+ */
 interface HookDecision {
     allow?: boolean;
     block?: boolean;
     blockReason?: string;
     reason?: string;
+    /**
+     * Whether the guard reached an enforcement decision about *this* call.
+     *
+     * Note this describes whether the guard **decided**, not whether it allowed.
+     * Every `block` is `audited: true` — a blocked call is the most thoroughly
+     * checked outcome the guard produces (a red scan, a ciphertext integrity
+     * 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.
+     *
+     * So the host rule is:
+     *   `if (d.block) deny;  else if (d.audited) allow;  else judge it yourself;`
+     *
+     * Treating a bare `allow: true` as a completed audit is what this field exists
+     * to prevent. A host that ignores it and returns the decision verbatim will
+     * execute unaudited tool calls.
+     */
+    audited?: boolean;
+    /** Scan verdict when one was produced (`green` | `yellow` | `red`). Absent when no scan ran. */
+    verdict?: string;
 }
 interface MemoryGuardManagerOptions {
     auth: AgentAuth;
@@ -979,6 +1322,13 @@ interface MemoryGuardManagerOptions {
     rollbackMinScore?: number;
     /** True → return `{block:true}` on defense triggers. False → log and return `null` (audit-only). Default true. */
     enforce?: boolean;
+    /**
+     * Chain targeting for the pointer sync (network, blockchainRid, nodeUrls).
+     * Defaults to the SDK's configured chain. Without this the manager could only
+     * ever talk to the default chain, which left the whole memory-read path
+     * untestable — `syncLocalMemory` already accepted these options.
+     */
+    chainOpts?: ChainOpts;
     /** Host-specific tuning of what counts as a memory read. */
     memoryReadClassifier?: ClassifyMemoryReadOptions;
     /** Passed through to `guardMemoryWrite`. Host memory-write tool names override. */
@@ -1007,7 +1357,29 @@ declare class MemoryGuardManager {
     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);
+    /**
+     * 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
@@ -1015,12 +1387,33 @@ declare class MemoryGuardManager {
      */
     runBootProbe(): Promise<void>;
     /**
-     * Returns a `HookDecision` when the event is a memory read or write
-     * (host returns it verbatim to its runtime). Returns `null` when the
-     * event isn't memory-related — host falls through to its own audit.
+     * 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.
+     *
+     * 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.
      */
     handleBeforeToolCall(event: unknown, ctx: unknown): Promise<HookDecision | null>;
     private mapGuardResult;
+    /**
+     * Whether the pointer state this manager tracks actually describes the file
+     * this call is about to read.
+     *
+     * The classifier fires on nine patterns — including the bare tokens
+     * `"memory/"`, `"CLAUDE.md"` and `"AGENTS.md"` — but the sync path only ever
+     * reads, refreshes, or vouches for `this.memoryFilePath`. Without this check a
+     * read of `/repo/CLAUDE.md` (or any path merely containing `memory/`) would
+     * receive an `audited: true` for a file the guard never opened.
+     *
+     * Conservative on purpose: every path-shaped value found must resolve to the
+     * managed file. If none is found, or any one differs, the answer is no. That
+     * also covers events carrying two different path keys, where the classifier
+     * and the host could otherwise disagree about which one is authoritative.
+     */
+    private vouchesForTarget;
     private handleMemoryRead;
     private writeMemoryAtomic;
 }
@@ -1029,13 +1422,17 @@ declare function createMemoryGuardManager(opts: MemoryGuardManagerOptions): Memo
 /**
  * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
  *
- * Tracks: function call counts, latency, source (CLI/plugin/SDK),
- * and agent identity. ON by default.
+ * Metrics are POSTed to the Atbash-owned `/api/telemetry` proxy, which
+ * verifies the bearer, injects the Honeycomb ingest key server-side, and
+ * forwards to Honeycomb. The ingest credential never enters the SDK.
+ *
+ * Environment opt-out (recommended for air-gapped deployments):
+ * ATBASH_TELEMETRY_DISABLED=1
  *
  * Opt-out: create ~/.config/atbash/telemetry.json with { "enabled": false }
  * The file must be readable by the SDK process. If missing, corrupted, or
- * unreadable → telemetry stays ON. Environment variables cannot disable
- * telemetry (prevents agent bypass via env-var injection).
+ * unreadable, telemetry remains eligible to start unless the environment
+ * opt-out is set.
  */
 type ClientSource = "cli" | "sdk" | "plugin:openclaw" | "plugin:langchain" | "plugin:langgraph" | "plugin:hermes" | "plugin:eliza" | "plugin:crewai" | "plugin:mcp" | "plugin:autogen" | "plugin:jeenai" | (string & {});
 interface TelemetryConfig {
@@ -1045,6 +1442,13 @@ interface TelemetryConfig {
     source?: ClientSource;
     /** Flush interval in ms. Default: 60000 */
     exportIntervalMs?: number;
+    /** Atbash endpoint that hosts /api/telemetry. Required to actually export. */
+    endpoint?: string;
+    /**
+     * Called on every export to obtain fresh auth headers (typically
+     * `{ Authorization: "Bearer <hex>" }`). Required to actually export.
+     */
+    getAuthHeaders?: () => Record<string, string>;
 }
 declare function setupTelemetry(config: TelemetryConfig): void;
 /**
@@ -1068,126 +1472,33 @@ declare function flushTelemetry(): Promise<void>;
 declare function shutdownTelemetry(): Promise<void>;
 
 /**
- * Signs `log_encrypted_tool_call` — the ciphertext-only counterpart of
- * `log_tool_call`.
- *
- * Why this is not in the Rust core like the other signing helpers: the operation
- * takes a `byte_array` argument, and the only consumer today is the dashboard,
- * which loads the browser bundle where Rust is unreachable by construction. This
- * module is plain TypeScript so the node and browser builds share one
- * implementation and cannot drift. The Rust core gets the same operation when the
- * native/Python/Go callers need it — the wire format is pinned by `crypto/ecies.ts`.
- *
- * The contract refuses plaintext once an org registers an encryption key
- * (`log_tool_call` → "Organization requires encrypted payloads"), so for those
- * orgs this is the only way to log a tool call at all.
- */
-/**
- * Commitment to the plaintext claims a caller sends alongside the ciphertext.
- *
- * The judge server reads tool_name / action / context / tool_args_json from the
- * request body and feeds them to policy evaluation, but it holds no org key, so
- * it cannot check them against content_cipher. This hash is a signed operation
- * argument, which makes it the one thing it can check them against.
- *
- * An array, not an object: key order is not part of a JSON array, so the two
- * implementations cannot drift on serialization. Must stay identical to
- * `claimHashHex` in the dashboard (`src/lib/api/judge/action-hash.ts`).
- */
-declare function claimHashHex(toolName: string, action: string, context: string, toolArgsJson: string): string;
-/** Plaintext fields of a tool call, sealed into a single ECIES payload. */
-interface ToolCallPlaintext {
-    tool_name: string;
-    action: string;
-    context: string;
-    tool_args_json: string;
-}
-/**
- * Canonical form of an action for the retry-cache hash.
- *
- * Must stay identical to `normalizeActionForHash` in the dashboard
- * (`src/lib/api/judge/on-chain.ts`): both write the same
- * `tool_call_log.normalized_action_hash` column, and `get_resolved_hold_by_action_hash`
- * matches a YELLOW hold retry against it. Diverging here silently breaks
- * hold resolution rather than failing loudly.
+ * Rust core does the work; `browser/encrypted-toolcall.ts` mirrors it for the
+ * browser and must produce the same columns.
  */
+/** Must match `column_aad` in the core — the label binds a ciphertext to its column. */
+declare function columnAad(toolCallId: string, column: string): string;
+/** Byte-identical to the dashboard's copy — diverging breaks hold-retry resolution. */
 declare function normalizeActionForHash(action: string): string;
-/**
- * Sign a `log_encrypted_tool_call` operation.
- *
- * Everything the agent did — action, context, tool name and args — goes into a
- * single ECIES payload readable only with the org's private key. Nothing
- * identifying the action is left in the operation arguments, which are permanent
- * block data.
- *
- * `actionHash` is the one exception, and it is deliberate: it is a SHA-256 over
- * the normalized action, so the chain can match a held action against its retry
- * without being able to read it.
- *
- * @returns hex-encoded signed transaction, ready to POST as `signed_log_tool_call`.
- */
+/** Lets the judge check the request body against the ciphertext without an org key. */
+declare function claimHashHex(toolName: string, action: string, context: string, toolArgsJson: string): string;
+/** @returns hex-encoded signed tx, ready to POST as `signed_log_tool_call`. */
 declare function signEncryptedToolCall(toolCallId: string, action: string, context: string, toolName: string, toolArgsJson: string, orgEncryptionPubKey: string, privkeyHex: string, blockchainRidHex: string): string;
 
 /**
- * ECIES over secp256k1 — encrypts on-chain payloads to an organization's public key.
- *
- * Only the holder of the org's private key can decrypt. Everyone else — including
- * anyone querying the Chromia node directly, and Atbash itself — sees ciphertext.
- * The recipient key is a dedicated encryption keypair the org generates in the
- * dashboard and registers via `org_set_encryption_key`; it is read back with the
- * `get_org_encryption_pubkey` query.
- *
- * ─── WIRE FORMAT (normative) ────────────────────────────────────────────────
- * This exact layout is mirrored in the Atbash dashboard
- * (`src/lib/chromia/ecies.ts`) and must stay byte-for-byte identical: the SDK
- * encrypts tool calls, the dashboard decrypts them.
- *
- *   version           1 byte   = 0x01
- *   ephemeral_pubkey  33 bytes   compressed secp256k1 point
- *   nonce             12 bytes   random, per message
- *   ciphertext+tag    N bytes    AES-256-GCM output (16-byte tag appended)
- *
- * Version 0x01 is FROZEN, not provisional. Records encrypted under it already
- * exist on the deployed chains, and the ledger is immutable — redefining 0x01
- * would make them permanently unreadable, not merely stale. Evolving the format
- * means emitting a NEW version byte and keeping a 0x01 decrypt path, in both
- * repos, forever.
- *
- * Raw bytes, not base64: the on-chain columns are `byte_array`, so encoding to
- * text would add ~33% to what are the largest columns in the schema.
- *
- * Key agreement, per message:
- *   shared_x = ECDH(ephemeral_privkey, org_pubkey).x            // 32 bytes
- *   key      = HKDF-SHA256(ikm=shared_x, salt=ephemeral_pubkey, info=domain, len=32)
- *   aad      = "<domain>|<record_id>"
- *
- * A fresh ephemeral keypair is generated for every message and its private half is
- * discarded immediately. This is what makes the scheme forward-secret with respect
- * to the *sender*: leaking an agent's long-term signing key later does not expose
- * anything it encrypted in the past. (Deriving the shared secret from the agent's
- * static key instead would let anyone recompute every past shared secret, since the
- * org's public key is public by definition.)
- *
- * Three separate bindings, each closing a different substitution:
- *   salt = ephemeral pubkey  — ties the key to this exact handshake
- *   info = domain            — a verdict payload cannot be read as a tool call
- *   aad  = domain|record_id  — a payload cannot be lifted onto another row
- */
-/**
- * Cryptographic domain per payload kind. Fed to HKDF `info`, so each kind derives
- * a different key from the same handshake — a verdict payload handed to the
- * tool-call reader fails authentication rather than decoding to an empty struct.
+ * Cryptographic domain per payload kind. Each kind derives a distinct
+ * key from the same handshake — a verdict payload handed to the
+ * tool-call reader fails authentication rather than silently decoding.
  *
- * Must match `EciesDomain` in the dashboard's src/lib/chromia/ecies.ts exactly:
- * the string is an input to key derivation, so any difference makes the two sides
- * mutually unreadable.
+ * Values here are the SHORT domain names the Rust core recognizes.
+ * The full HKDF `info` strings (`atbash:chain-encryption:v1:<kind>`)
+ * live inside the core and never surface at the API boundary.
  */
 declare const EciesDomain: {
-    readonly toolCall: "atbash:chain-encryption:v1:toolcall";
-    readonly verdict: "atbash:chain-encryption:v1:verdict";
-    readonly note: "atbash:chain-encryption:v1:note";
-    readonly policy: "atbash:chain-encryption:v1:policy";
-    readonly raw: "atbash:chain-encryption:v1:raw";
+    readonly toolCall: "toolcall";
+    readonly verdict: "verdict";
+    readonly note: "note";
+    readonly policy: "policy";
+    readonly raw: "raw";
 };
 type EciesDomain = (typeof EciesDomain)[keyof typeof EciesDomain];
 /**
@@ -1202,9 +1513,9 @@ declare function encryptForOrg(plaintext: string, orgPubKeyHex: string, aad: str
 /**
  * Decrypt a payload produced by {@link encryptForOrg}.
  *
- * Throws if the key is wrong, the `aad` does not match the one used at encrypt
- * time, or the ciphertext was tampered with — GCM authentication makes all three
- * indistinguishable by design.
+ * Throws if the key is wrong, the `aad` does not match the one used at
+ * encrypt time, or the ciphertext was tampered with — GCM authentication
+ * makes all three indistinguishable by design.
  *
  * @param payload        Value read from the on-chain `byte_array` column.
  * @param orgPrivKeyHex  Org's secp256k1 private key (32 bytes hex).
@@ -1212,12 +1523,36 @@ declare function encryptForOrg(plaintext: string, orgPubKeyHex: string, aad: str
  */
 declare function decryptForOrg(payload: Uint8Array, orgPrivKeyHex: string, aad: string, domain?: EciesDomain): string;
 /**
- * Size in bytes of the encrypted payload for a given plaintext length. Lets
- * callers check against the on-chain column cap (MAX_CONTENT_CIPHER_SIZE)
- * before submitting a transaction the contract would reject.
+ * Size in bytes of the encrypted payload for a given plaintext length.
+ * Lets callers check against the on-chain column cap
+ * (`MAX_CONTENT_CIPHER_SIZE`) before submitting a transaction the
+ * contract would reject.
  */
 declare function encryptedLength(plaintextByteLength: number): number;
 
+/**
+ *   atb1.<key-fingerprint>.<claim-hash>.<base64 ciphertext>
+ *
+ * Normative spec: `core/src/crypto_envelope.rs`. This mirrors it for the browser.
+ */
+interface Envelope {
+    /** First 8 bytes of the recipient public key, hex. May be empty. */
+    keyFingerprint: string;
+    /** Commitment to the accompanying plaintext claims. May be empty. */
+    claimHash: string;
+    /** Raw ECIES payload. */
+    payload: Uint8Array;
+}
+declare function packEnvelope(payload: Uint8Array, keyFingerprint?: string, claimHash?: string): string;
+/**
+ * Stays true for a truncated envelope that `parseEnvelope` rejects — a severed
+ * ciphertext is not plaintext, so callers must show a placeholder.
+ */
+declare function isEnvelope(value: string): boolean;
+/** Null, not a throw — pre-encryption records are plaintext. */
+declare function parseEnvelope(value: string): Envelope | null;
+declare function keyFingerprintOf(pubKeyHex: string): string;
+
 declare function isValidPrivateKey(hex: string): boolean;
 declare function derivePublicKey(privkey: string): string;
 declare function generateKeypair(): KeyPair;
@@ -1233,4 +1568,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 AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, 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 FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, 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 ToolCallPlaintext, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, claimHashHex, classifyMemoryRead, classifyMemoryWrite, 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, isValidPrivateKey, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, 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_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, PRIVATE_CHAIN, PUBLIC_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, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, gtvToFfiSafe, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeActionType, 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 };