@kashscript/hudhud 0.1.0

package/src/privacy/index.ts

@@ -0,0 +1,123 @@
+// ============================================================================
+// @kashscript/hudhud/privacy — PII + secret redaction interceptor
+// ----------------------------------------------------------------------------
+// Scans tool arguments (and any JSON tree) for embedded secrets (API keys,
+// JWTs, bearer tokens) and PII (SSN, PAN, CNIC, …). Returns a redacted copy +
+// a violation list. RECALL-biased: over-redact rather than leak; the redaction
+// marker `[REDACTED:<pattern-id>]` names the detector without exposing the raw
+// value. Pure — never mutates the input. Ported verbatim from the
+// oreoasis-core-host engine (M5, ADR-0016).
+// ============================================================================
+
+export interface PrivacyPattern {
+  readonly id: string;
+  readonly description: string;
+  readonly regex: RegExp;
+}
+
+/** Built-in catalogue. Append-only — callers extend via `scanAndRedact`'s 2nd arg. */
+export const BUILTIN_PRIVACY_PATTERNS: ReadonlyArray<PrivacyPattern> = [
+  // ── secret formats ─────────────────────────────────────────────
+  { id: "openai-key", description: "OpenAI / Anthropic-style API key", regex: /\bsk-[A-Za-z0-9_-]{20,}\b/ },
+  { id: "anthropic-key", description: "Anthropic API key (explicit prefix)", regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+  { id: "github-pat", description: "GitHub personal access token", regex: /\bghp_[A-Za-z0-9]{36}\b/ },
+  { id: "github-app-token", description: "GitHub app installation token", regex: /\bgh[sou]_[A-Za-z0-9]{36}\b/ },
+  { id: "aws-access-key-id", description: "AWS access key id", regex: /\b(?:AKIA|ASIA|AROA|AIDA)[A-Z0-9]{16}\b/ },
+  { id: "google-api-key", description: "Google Cloud API key", regex: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { id: "jwt-token", description: "JWT-shaped string (three base64url segments)", regex: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+  { id: "bearer-token", description: "Authorization: Bearer header value", regex: /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/i },
+  { id: "slack-token", description: "Slack workspace / bot token", regex: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
+  { id: "private-key-pem", description: "Embedded PEM private key header", regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |)PRIVATE KEY-----/ },
+  // ── PII formats ────────────────────────────────────────────────
+  { id: "us-ssn", description: "US Social Security Number (NNN-NN-NNNN)", regex: /\b\d{3}-\d{2}-\d{4}\b/ },
+  { id: "credit-card-16", description: "16-digit grouped credit card number", regex: /\b(?:\d{4}[- ]){3}\d{4}\b/ },
+  { id: "in-pan", description: "Indian PAN card number", regex: /\b[A-Z]{5}\d{4}[A-Z]\b/ },
+  { id: "in-aadhaar-grouped", description: "Indian Aadhaar number (12 digits, optional grouping)", regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}\b/ },
+  { id: "pk-cnic", description: "Pakistan CNIC (13 digits, 5-7-1 grouping)", regex: /\b\d{5}-\d{7}-\d\b/ },
+  { id: "pk-mobile", description: "Pakistan mobile number (03XX-XXXXXXX)", regex: /\b03\d{2}-?\d{7}\b/ },
+];
+
+export interface PrivacyViolation {
+  readonly path: string;
+  readonly patternId: string;
+  readonly patternDescription: string;
+}
+
+export interface PrivacyScanResult {
+  readonly ok: boolean;
+  readonly redacted: Readonly<Record<string, unknown>>;
+  readonly violations: ReadonlyArray<PrivacyViolation>;
+  readonly redactionCount: number;
+}
+
+/** Scan the input tree; return a redacted copy + the violation list. Pure. */
+export function scanAndRedact(
+  input: Record<string, unknown>,
+  extraPatterns: ReadonlyArray<PrivacyPattern> = [],
+): PrivacyScanResult {
+  const patterns = [...BUILTIN_PRIVACY_PATTERNS, ...extraPatterns];
+  const violations: PrivacyViolation[] = [];
+  const redacted = scanNode(input, "$", patterns, violations) as Record<string, unknown>;
+  return {
+    ok: violations.length === 0,
+    redacted: Object.freeze(redacted),
+    violations: Object.freeze(violations),
+    redactionCount: violations.length,
+  };
+}
+
+function firstMatch(s: string, patterns: ReadonlyArray<PrivacyPattern>): PrivacyPattern | null {
+  for (const pattern of patterns) {
+    if (pattern.regex.test(s)) return pattern;
+  }
+  return null;
+}
+
+function scanNode(
+  node: unknown,
+  path: string,
+  patterns: ReadonlyArray<PrivacyPattern>,
+  violations: PrivacyViolation[],
+): unknown {
+  if (typeof node === "string") {
+    const m = firstMatch(node, patterns);
+    if (m) {
+      violations.push({ path, patternId: m.id, patternDescription: m.description });
+      return `[REDACTED:${m.id}]`;
+    }
+    return node;
+  }
+  // audit r1 F4: a numeric/bigint LEAF can itself be a secret (e.g. a PAN or a
+  // 12-digit Aadhaar carried as a JS number) — test its string form, don't skip it.
+  if (typeof node === "number" || typeof node === "bigint") {
+    const m = firstMatch(String(node), patterns);
+    if (m) {
+      violations.push({ path, patternId: m.id, patternDescription: m.description });
+      return `[REDACTED:${m.id}]`;
+    }
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return node.map((el, i) => scanNode(el, `${path}[${i}]`, patterns, violations));
+  }
+  if (node !== null && typeof node === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(node)) {
+      const scannedValue = scanNode(v, `${path}.${k}`, patterns, violations);
+      // audit r1 F4: a secret can hide in a KEY position, not just a value — a
+      // matching key is redacted so it never survives into the signed ledger.
+      const km = firstMatch(k, patterns);
+      if (km) {
+        violations.push({ path: `${path}.${k}`, patternId: km.id, patternDescription: `${km.description} (object key)` });
+        let redKey = `[REDACTED-KEY:${km.id}]`;
+        let n = 2;
+        while (redKey in out) redKey = `[REDACTED-KEY:${km.id}#${n++}]`;
+        out[redKey] = scannedValue;
+      } else {
+        out[k] = scannedValue;
+      }
+    }
+    return out;
+  }
+  return node;
+}

package/src/runtime/dispatcher.ts

@@ -0,0 +1,96 @@
+// ============================================================================
+// @kashscript/hudhud/runtime — NeuronToolDispatcher
+// ----------------------------------------------------------------------------
+// The seam where neuron's DAGExecutor reaches the host's real MCP tool
+// transport, with the accountability append done INLINE on the awaited dispatch
+// path. Neuron's `onEvent` is synchronous fire-and-forget (no back-pressure) —
+// so the signed ledger row is appended HERE, inside the awaited `dispatch`, so
+// a failed append fails the node and the run can never observe an unrecorded
+// tool result. Ported from the oreoasis-core-host engine (M5); telemetry dropped.
+// ============================================================================
+
+import { ToolDispatchError } from "@kashscript/neuron/kernel";
+import type { DispatchInput, DispatchResult, ToolDispatcher } from "@kashscript/neuron/kernel";
+import type { ToolManifest } from "@kashscript/neuron/schemas";
+
+import type { McpClientPoolManager } from "../mcp";
+import type { ForensicLedgerService } from "../ledger/writer";
+
+/** Binds one tool (by manifest) to the MCP endpoint that executes it. */
+export interface NeuronToolBinding {
+  readonly manifest: ToolManifest;
+  readonly mcpEndpointUrl: string;
+  readonly mcpToolName?: string;
+}
+
+export interface NeuronToolDispatcherDeps {
+  readonly mcpClientPool: McpClientPoolManager;
+  readonly forensicLedger: ForensicLedgerService;
+  /** Session whose ledger chain every dispatch in this run appends to. */
+  readonly sessionId: string;
+  readonly bindings: ReadonlyMap<string, NeuronToolBinding>;
+}
+
+export class NeuronToolDispatcher implements ToolDispatcher {
+  constructor(private readonly deps: NeuronToolDispatcherDeps) {}
+
+  /** Resolve a tool name to its manifest, or null when unbound. */
+  resolve(toolName: string): ToolManifest | null {
+    return this.deps.bindings.get(toolName)?.manifest ?? null;
+  }
+
+  /** Execute one tool call: resolve binding → real transport → (on JSON-RPC
+   *  error) EXECUTOR_FAILED (no row) → INLINE signed ledger append → return. */
+  async dispatch(input: DispatchInput): Promise<DispatchResult> {
+    const toolName = input.tool.name;
+    const binding = this.deps.bindings.get(toolName);
+    if (binding === undefined) {
+      throw new ToolDispatchError(
+        `NeuronToolDispatcher: no binding registered for tool '${toolName}' (dagNodeId=${input.dagNodeId})`,
+        "TOOL_NOT_FOUND",
+      );
+    }
+
+    const mcpToolName = binding.mcpToolName ?? toolName;
+    const transport = await this.deps.mcpClientPool.executeMcpToolCall(binding.mcpEndpointUrl, mcpToolName, input.parameters);
+
+    if (!transport.ok) {
+      // audit r1 F8: a money-moving tool can fail AFTER a partial side-effect, so
+      // record the FAILED dispatch on the signed ledger BEFORE throwing — every
+      // dispatch (success or application-error) leaves an accountable row.
+      await this.deps.forensicLedger.appendActorTransition({
+        sessionId: this.deps.sessionId,
+        payloadMutation: {
+          event: "tool.failed",
+          tool: toolName,
+          dagNodeId: input.dagNodeId,
+          jsonRpcId: transport.jsonRpcId,
+          errorCode: String(transport.error.code),
+          errorMessage: transport.error.message,
+        },
+      });
+      throw new ToolDispatchError(
+        `NeuronToolDispatcher: MCP tool '${mcpToolName}' returned a JSON-RPC error (code=${transport.error.code}): ${transport.error.message}`,
+        "EXECUTOR_FAILED",
+      );
+    }
+
+    // INLINE accountability append — BEFORE returning. A throw here fails the
+    // node (the executor awaits us), so no unrecorded result can be observed.
+    await this.deps.forensicLedger.appendActorTransition({
+      sessionId: this.deps.sessionId,
+      payloadMutation: {
+        event: "tool.dispatch",
+        tool: toolName,
+        dagNodeId: input.dagNodeId,
+        jsonRpcId: transport.jsonRpcId,
+        result: transport.result,
+      },
+    });
+
+    return {
+      output: transport.result,
+      cost: { usdMicros: input.tool.costHint.usdMicros, latencyMs: transport.latencyMs },
+    };
+  }
+}

package/src/runtime/escalation.ts

@@ -0,0 +1,292 @@
+// ============================================================================
+// @kashscript/hudhud/runtime — escalation: two-key suspend/resume
+// ----------------------------------------------------------------------------
+// When an autonomous run reaches a RESTRICTED tool it SUSPENDS; a human must
+// sign off before it may RESUME. Two artifacts make "the host cannot forge
+// human judgment" literally true:
+//   1. buildHumanApprovalEnvelope — the TWO-KEY envelope: the AGENT key (which
+//      the host holds) attests the proposed action; a SEPARATE OPERATOR key
+//      signs the challenge. The host cannot mint the invoker signature.
+//   2. appendOperatorSignoff — a SIGNED ledger row on the OPERATOR key
+//      (actorClass OPERATOR_ADMIN) + the mandatory exception classification;
+//      forensicConsistencyScan re-verifies it.
+//   3. ResumeGuard — a one-way claim() so a retried resume can't re-fire a tool.
+// Ported from the oreoasis-core-host engine (M5); telemetry dropped, ledger +
+// exception + neuron/handshake reused.
+// ============================================================================
+
+import { deriveDid, signEvent, verifyEvent } from "@kashscript/identity-core";
+import { KASH_DID_PATTERN, signLedgerBlock } from "@kashscript/attest";
+import {
+  PermissionGate,
+  assembleEnvelope,
+  stripDerivedFields,
+} from "@kashscript/neuron/handshake";
+import type { DID, KashEventSignature, Sha256Hex, SignedActionEnvelope, ToolCall } from "@kashscript/neuron/handshake";
+import { NEURON_DST } from "@kashscript/neuron/schemas";
+
+import {
+  assertFailureClass,
+  buildSignedClassification,
+} from "../exception";
+import type { ExceptionClassificationInput, ExceptionClassificationRecord, ExceptionClassificationStore } from "../exception";
+import { resolvePreviousBlockHash } from "../ledger/store";
+import type { LedgerStore } from "../ledger/store";
+import type { ForensicLedgerService } from "../ledger/writer";
+
+// Both identities are ordinary `did:kash` keys (base58btc, attest's
+// KASH_DID_PATTERN) so the operator sign-off is a first-class ledger actor.
+// The two-key guarantee comes from DISTINCTNESS, not a DID namespace: the agent
+// key is the one the host holds; the operator key is SEPARATE, so the host
+// cannot mint the operator (invoker) signature. Enforced below by requiring
+// agent.did ≠ operator.did (their derived DIDs differ because their keys do).
+
+export type EscalationErrorCode =
+  | "AGENT_DID_INVALID"
+  | "OPERATOR_DID_INVALID"
+  | "AGENT_OPERATOR_NOT_DISTINCT"
+  | "RESUME_ALREADY_CLAIMED";
+
+export class EscalationError extends Error {
+  readonly code: EscalationErrorCode;
+  readonly detail: Readonly<Record<string, unknown>>;
+  constructor(code: EscalationErrorCode, message: string, detail: Readonly<Record<string, unknown>> = {}) {
+    super(`[${code}] ${message}`);
+    this.name = "EscalationError";
+    this.code = code;
+    this.detail = Object.freeze({ ...detail });
+  }
+}
+
+/** Coerce a 64-hex-ish id to the neuron schema's `0x`-prefixed lowercase-hex form. */
+function asSha256Hex(s: string): Sha256Hex {
+  const lower = s.toLowerCase();
+  const hex = lower.startsWith("0x") ? lower.slice(2) : lower;
+  return `0x${hex}` as unknown as Sha256Hex;
+}
+
+/** Derive the real `did:kash:` binding for a public key (schema-valid DID). */
+function deriveKashDid(publicKey: Uint8Array): DID {
+  return deriveDid(publicKey) as unknown as DID;
+}
+
+export interface BuildHumanApprovalEnvelopeInput {
+  readonly pendingCall: ToolCall;
+  readonly dagId: string;
+  readonly blueprintId: string;
+  /** The AGENT identity — the host's own key. `did` is the ledger DID (the
+   *  signature `kid`); `publicKey` derives the schema-valid challenge binding. */
+  readonly agent: { readonly did: string; readonly privateKey: Uint8Array; readonly publicKey: Uint8Array };
+  /** The OPERATOR identity — the SEPARATE human key. */
+  readonly operator: { readonly did: string; readonly privateKey: Uint8Array; readonly publicKey: Uint8Array };
+  readonly ttlMs?: number;
+}
+
+/**
+ * Build the two-key `SignedActionEnvelope` that authorizes a resume of a
+ * restricted tool. The two signature `kid`s DIFFER by construction (agent vs
+ * operator), so forging human judgment would require the operator private key.
+ */
+export async function buildHumanApprovalEnvelope(input: BuildHumanApprovalEnvelopeInput): Promise<SignedActionEnvelope> {
+  if (!KASH_DID_PATTERN.test(input.agent.did)) {
+    throw new EscalationError("AGENT_DID_INVALID", "agent.did must be a valid did:kash identifier");
+  }
+  if (!KASH_DID_PATTERN.test(input.operator.did)) {
+    throw new EscalationError("OPERATOR_DID_INVALID", "operator.did must be a valid did:kash identifier");
+  }
+  if (input.agent.did === input.operator.did) {
+    throw new EscalationError(
+      "AGENT_OPERATOR_NOT_DISTINCT",
+      "agent.did and operator.did must differ — the two-key guarantee requires a SEPARATE operator key",
+    );
+  }
+
+  // 1. AGENT attests the challenge body (proves the agent proposed it).
+  const attest = async (body: Readonly<Record<string, unknown>>): Promise<KashEventSignature> => {
+    const signed = await signEvent({}, body, input.agent.privateKey, { dst: NEURON_DST.HANDSHAKE, encoding: "hex", kid: input.agent.did });
+    return { alg: "ed25519", sig: signed.sig, dst: NEURON_DST.HANDSHAKE, encoding: "hex", kid: input.agent.did };
+  };
+
+  const gate = new PermissionGate();
+  const challenge = await gate.buildChallenge(
+    input.pendingCall,
+    {
+      agentId: deriveKashDid(input.agent.publicKey),
+      invokerId: deriveKashDid(input.operator.publicKey),
+      blueprintId: asSha256Hex(input.blueprintId),
+    },
+    attest,
+    { dagId: asSha256Hex(input.dagId), ...(input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {}) },
+  );
+
+  // 2. OPERATOR signs the SAME stripped body with the SEPARATE key.
+  const operatorSigned = await signEvent({}, stripDerivedFields(challenge), input.operator.privateKey, {
+    dst: NEURON_DST.HANDSHAKE,
+    encoding: "hex",
+    kid: input.operator.did,
+  });
+  const invokerSignature: KashEventSignature = {
+    alg: "ed25519",
+    sig: operatorSigned.sig,
+    dst: NEURON_DST.HANDSHAKE,
+    encoding: "hex",
+    kid: input.operator.did,
+  };
+
+  return assembleEnvelope(challenge, invokerSignature);
+}
+
+export interface AppendOperatorSignoffInput {
+  readonly forensicLedger: ForensicLedgerService;
+  readonly ledgerStore: LedgerStore;
+  readonly sessionId: string;
+  readonly operator: { readonly did: string; readonly privateKey: Uint8Array };
+  readonly escalation: { readonly suspendedStepId: string; readonly toolName: string; readonly escalationId?: string };
+  /** MANDATORY classification (required `failureClass`, no "unclassified"). */
+  readonly classification: ExceptionClassificationInput;
+  readonly exceptionClassificationStore: ExceptionClassificationStore;
+}
+
+/**
+ * Append a SIGNED ledger row recording the operator's sign-off (OPERATOR key,
+ * actorClass OPERATOR_ADMIN) + persist the signed exception classification.
+ * The mandatory `failureClass` gate fails-fast before any row is written.
+ */
+export async function appendOperatorSignoff(
+  input: AppendOperatorSignoffInput,
+): Promise<{ stepIndex: number; classification: ExceptionClassificationRecord }> {
+  if (!KASH_DID_PATTERN.test(input.operator.did)) {
+    throw new EscalationError("OPERATOR_DID_INVALID", "operator.did must be a valid did:kash identifier");
+  }
+  assertFailureClass(input.classification.failureClass);
+
+  const payloadMutation: Readonly<Record<string, unknown>> = {
+    event: "escalation.signoff",
+    suspendedStepId: input.escalation.suspendedStepId,
+    tool: input.escalation.toolName,
+    failureClass: input.classification.failureClass,
+    failureTag: input.classification.failureTag,
+  };
+
+  const { previousBlockHash, nextStepIndex } = await resolvePreviousBlockHash(input.ledgerStore, input.sessionId);
+  const signature = await signLedgerBlock(
+    { sessionId: input.sessionId, stepIndex: nextStepIndex, actorDid: input.operator.did, previousBlockHash, payloadMutation },
+    input.operator.privateKey,
+  );
+
+  const block = await input.forensicLedger.appendTransitionLog({
+    sessionId: input.sessionId,
+    stepIndex: nextStepIndex,
+    actorDid: input.operator.did,
+    actorClass: "OPERATOR_ADMIN",
+    payloadMutation,
+    signature,
+  });
+
+  const classification = await buildSignedClassification(input.classification, input.operator, {
+    escalationId: input.escalation.escalationId ?? null,
+    signoffLedgerStepIndex: block.stepIndex,
+  });
+  await input.exceptionClassificationStore.append(classification);
+
+  return { stepIndex: block.stepIndex, classification };
+}
+
+export interface VerifyApprovalEnvelopeInput {
+  readonly envelope: SignedActionEnvelope;
+  /** The AGENT public key (the host's own key) that attested the challenge. */
+  readonly agentPublicKey: Uint8Array;
+  /** The OPERATOR public key — the SEPARATE human key the host cannot mint. */
+  readonly operatorPublicKey: Uint8Array;
+  /** If given, the envelope's proposed tool MUST equal this (bind to the suspended call). */
+  readonly expectedToolName?: string;
+  /** If given, the challenge must not be expired at this wall-clock (ms since epoch). */
+  readonly nowMs?: number;
+}
+
+export type ApprovalVerificationReason =
+  | "MISSING_SIGNATURE_KID"
+  | "KEYS_NOT_DISTINCT"
+  | "TOOL_MISMATCH"
+  | "WRONG_DST"
+  | "EXPIRED"
+  | "AGENT_ATTESTATION_INVALID"
+  | "OPERATOR_SIGNATURE_INVALID";
+
+export interface ApprovalVerification {
+  readonly ok: boolean;
+  readonly reason: ApprovalVerificationReason | null;
+}
+
+function toSignedEvent(body: unknown, sig: KashEventSignature) {
+  // The envelope's signatures were minted with `encoding: "hex"` + a `kid`; the
+  // neuron type marks both optional, so default them for identity-core's verifier.
+  return {
+    header: {} as Readonly<Record<string, unknown>>,
+    body,
+    signature: { alg: sig.alg, sig: sig.sig, dst: sig.dst, encoding: sig.encoding ?? "hex", kid: sig.kid ?? "" },
+  };
+}
+
+/**
+ * CRYPTOGRAPHICALLY verify a two-key human-approval envelope before a suspended
+ * run may resume (audit r1 F1). The security-critical check is the OPERATOR
+ * (invoker) signature over `stripDerivedFields(challenge)` under a key the host
+ * does NOT hold — so the host cannot forge human judgment by merely PRESENTING an
+ * envelope. Also re-checks: the AGENT attestation, the two kids differ, the DST is
+ * the handshake DST, the proposed tool matches, and (optionally) the challenge
+ * has not expired. Returns `{ok:false, reason}` on any failure — never throws.
+ */
+export async function verifyApprovalEnvelope(input: VerifyApprovalEnvelopeInput): Promise<ApprovalVerification> {
+  const { envelope, agentPublicKey, operatorPublicKey } = input;
+  const challenge = envelope.challenge;
+  const agentAttestation = challenge.agentAttestation;
+  const invokerSignature = envelope.invokerSignature;
+
+  const agentKid = agentAttestation?.kid;
+  const invokerKid = invokerSignature?.kid;
+  if (typeof agentKid !== "string" || typeof invokerKid !== "string") return { ok: false, reason: "MISSING_SIGNATURE_KID" };
+  // Two-key: the operator key is SEPARATE from the agent key the host holds.
+  if (agentKid === invokerKid) return { ok: false, reason: "KEYS_NOT_DISTINCT" };
+  if (input.expectedToolName !== undefined && challenge.proposedAction.toolName !== input.expectedToolName) {
+    return { ok: false, reason: "TOOL_MISMATCH" };
+  }
+  if (agentAttestation.dst !== NEURON_DST.HANDSHAKE || invokerSignature.dst !== NEURON_DST.HANDSHAKE) {
+    return { ok: false, reason: "WRONG_DST" };
+  }
+  if (input.nowMs !== undefined) {
+    const expiresMs = Date.parse(challenge.expiresAt);
+    if (Number.isFinite(expiresMs) && input.nowMs > expiresMs) return { ok: false, reason: "EXPIRED" };
+  }
+
+  const signable = stripDerivedFields(challenge);
+  const agentOk = await verifyEvent(toSignedEvent(signable, agentAttestation), agentPublicKey);
+  if (!agentOk) return { ok: false, reason: "AGENT_ATTESTATION_INVALID" };
+  // SECURITY-CRITICAL: the operator signed the SAME stripped body with the key
+  // the host cannot mint. This is what makes "the host cannot forge human
+  // judgment" literally true at RESUME time (not just at build time).
+  const operatorOk = await verifyEvent(toSignedEvent(signable, invokerSignature), operatorPublicKey);
+  if (!operatorOk) return { ok: false, reason: "OPERATOR_SIGNATURE_INVALID" };
+
+  return { ok: true, reason: null };
+}
+
+/** One-way claim guard — an escalation/resume key may be claimed AT MOST ONCE,
+ *  so a retried resume can't double-execute a money-moving tool. In-memory
+ *  (single process); a durable CAS is a venture concern. */
+export class ResumeGuard {
+  private readonly claimed = new Set<string>();
+
+  /** Claim `escalationKey`. Throws `EscalationError("RESUME_ALREADY_CLAIMED")`
+   *  if already claimed — the throw is the defense. */
+  claim(escalationKey: string): void {
+    if (this.claimed.has(escalationKey)) {
+      throw new EscalationError("RESUME_ALREADY_CLAIMED", `resume key '${escalationKey}' was already claimed — refusing to re-execute`, { escalationKey });
+    }
+    this.claimed.add(escalationKey);
+  }
+
+  isClaimed(escalationKey: string): boolean {
+    return this.claimed.has(escalationKey);
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,14 @@
+// @kashscript/hudhud/runtime — the accountable execution runtime: the neuron
+// tool dispatcher (inline signed ledger append per tool call), the work-item
+// runner (owns the neuron DAGExecutor lifecycle), and the two-key escalation
+// mechanic. Ventures import hudhud + define tool bindings; they never touch raw
+// neuron (ECOSYSTEM #12). The SPI types ventures implement are re-exported here.
+
+export * from "./dispatcher";
+export * from "./runner";
+export * from "./escalation";
+
+// Re-export the neuron SPI surface ventures need (so they import it via hudhud).
+export type { ToolManifest, TaskDAG, AgenticSpec } from "@kashscript/neuron/schemas";
+export type { LLMProvider, DispatchInput, DispatchResult, StepOutcome } from "@kashscript/neuron/kernel";
+export type { SignedActionEnvelope, ToolCall } from "@kashscript/neuron/handshake";