@atbash/sdk 0.9.0 → 0.9.2

package/dist/index.d.mts

@@ -721,7 +721,18 @@ 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);
@@ -1068,6 +1079,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;
 
@@ -1093,6 +1111,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. */
@@ -1115,7 +1135,7 @@ 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;
 }
 /**
@@ -1125,12 +1145,13 @@ interface GuardMemoryWriteResult {
  *
  * 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
+ * - `yellow` → persisted with its LLM score; decision allows once the chain confirms
+ * - `green`  → persisted with its LLM score; decision allows once the chain confirms
+ * - anything else → not persisted; decision blocks (unless `enforce: false`)
  *
- * 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.
+ * A write is acknowledged only after the chain transaction confirms, for
+ * yellow exactly as for green. An unconfirmed write blocks in enforce mode
+ * and remains unaudited in observe mode.
  */
 declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
 
@@ -1160,6 +1181,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.
@@ -1208,6 +1231,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;
@@ -1236,6 +1261,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;
 
@@ -1260,10 +1292,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;`
@@ -1363,9 +1395,9 @@ 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.
+     * Returns `null` for non-memory events, other files this manager does not
+     * own, or unverified observe-mode reads. An enforced read of the managed
+     * file blocks when verification cannot complete.
      *
      * A returned decision carries `audited` (see `HookDecision`). Only
      * `{ allow: true, audited: true }` means "checked and cleared"; anything else
@@ -1390,6 +1422,9 @@ declare class MemoryGuardManager {
      */
     private vouchesForTarget;
     private handleMemoryRead;
+    /** Complete queued audit-log writes before a host shuts down or removes its workspace. */
+    flushLogs(): Promise<void>;
+    private unverifiedRead;
     private writeMemoryAtomic;
 }
 declare function createMemoryGuardManager(opts: MemoryGuardManagerOptions): MemoryGuardManager;

package/dist/index.d.ts

@@ -721,7 +721,18 @@ 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);
@@ -1068,6 +1079,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;
 
@@ -1093,6 +1111,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. */
@@ -1115,7 +1135,7 @@ 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;
 }
 /**
@@ -1125,12 +1145,13 @@ interface GuardMemoryWriteResult {
  *
  * 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
+ * - `yellow` → persisted with its LLM score; decision allows once the chain confirms
+ * - `green`  → persisted with its LLM score; decision allows once the chain confirms
+ * - anything else → not persisted; decision blocks (unless `enforce: false`)
  *
- * 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.
+ * A write is acknowledged only after the chain transaction confirms, for
+ * yellow exactly as for green. An unconfirmed write blocks in enforce mode
+ * and remains unaudited in observe mode.
  */
 declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
 
@@ -1160,6 +1181,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.
@@ -1208,6 +1231,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;
@@ -1236,6 +1261,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;
 
@@ -1260,10 +1292,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;`
@@ -1363,9 +1395,9 @@ 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.
+     * Returns `null` for non-memory events, other files this manager does not
+     * own, or unverified observe-mode reads. An enforced read of the managed
+     * file blocks when verification cannot complete.
      *
      * A returned decision carries `audited` (see `HookDecision`). Only
      * `{ allow: true, audited: true }` means "checked and cleared"; anything else
@@ -1390,6 +1422,9 @@ declare class MemoryGuardManager {
      */
     private vouchesForTarget;
     private handleMemoryRead;
+    /** Complete queued audit-log writes before a host shuts down or removes its workspace. */
+    flushLogs(): Promise<void>;
+    private unverifiedRead;
     private writeMemoryAtomic;
 }
 declare function createMemoryGuardManager(opts: MemoryGuardManagerOptions): MemoryGuardManager;