@atbash/sdk 0.16.5-dev.0 → 0.17.0-dev.0

package/dist/index.d.mts

@@ -198,6 +198,11 @@ 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;
@@ -305,6 +310,13 @@ 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
@@ -350,6 +362,16 @@ interface AtbashOptions {
     orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     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"
@@ -400,6 +422,10 @@ interface FromConfigOptions {
     /** 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;
@@ -456,6 +482,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;
@@ -559,6 +589,23 @@ 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;
     /**
      * One exit for every judge failure.
      *
@@ -568,6 +615,12 @@ 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;
     /**
      * Return the current status of a previously submitted judgment.
@@ -1111,6 +1164,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. */
@@ -1133,7 +1188,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;
 }
 /**
@@ -1143,12 +1198,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>;
 
@@ -1178,6 +1234,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.
@@ -1226,6 +1284,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;
@@ -1285,10 +1345,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;`
@@ -1388,9 +1448,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
@@ -1415,6 +1475,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

@@ -198,6 +198,11 @@ 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;
@@ -305,6 +310,13 @@ 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
@@ -350,6 +362,16 @@ interface AtbashOptions {
     orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     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"
@@ -400,6 +422,10 @@ interface FromConfigOptions {
     /** 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;
@@ -456,6 +482,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;
@@ -559,6 +589,23 @@ 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;
     /**
      * One exit for every judge failure.
      *
@@ -568,6 +615,12 @@ 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;
     /**
      * Return the current status of a previously submitted judgment.
@@ -1111,6 +1164,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. */
@@ -1133,7 +1188,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;
 }
 /**
@@ -1143,12 +1198,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>;
 
@@ -1178,6 +1234,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.
@@ -1226,6 +1284,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;
@@ -1285,10 +1345,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;`
@@ -1388,9 +1448,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
@@ -1415,6 +1475,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;