@watchlight/sdk 0.2.0 → 0.5.0

package/README.md

@@ -108,6 +108,78 @@ const search = governTool(
 mutated); `governTools(tools, { intentFor })` maps an array. Intent defaults to
 the tool's name. Fail-closed. `@langchain/core` is a peer dependency.
 
+## Gate a consequential action — runtime context, per-user, human-in-the-loop
+
+For money-moving (or any high-stakes) tool calls, pass **runtime facts** into the
+policy, attribute the decision to the **acting user**, get a **correlation id**
+back, and route the risky ones to a **human**.
+
+```ts
+import { govern, NeedsApproval } from "@watchlight/sdk";
+
+// principal / resource / context can each be a value or (args) => value
+const book = govern.tool(bookTrip, {
+  intent: "book",
+  principal: (o) => `User::"${o.userId}"`,
+  resource:  (o) => `trip/${o.tripId}`,
+  context:   (o) => ({ amount: o.amount, limit: o.perActionLimit, refundable: o.refundable }),
+  onNeedsApproval: async ({ decisionId }) => askUser(decisionId), // one-tap human confirm
+});
+```
+```
+permit(principal, action == Action::"book", resource)
+when { context.amount <= context.limit && context.refundable };
+```
+
+Or use the low-level primitive directly (any framework):
+
+```ts
+const d = await govern.authorize({
+  principal: `User::"${userId}"`, action: "wire", resource: `acct/${to}`, context: { amount },
+});
+// d.decision → "Allow" | "Deny" | "NeedsApproval"
+// d.decisionId → store next to your booking row for reconstruction
+
+if (d.decision === "NeedsApproval") {
+  await getHumanConfirmation();
+  const token = govern.mintApproval({ action: "wire", resource: `acct/${to}` }); // single-use, TTL, bound
+  await govern.authorize({ principal: `User::"${userId}"`, action: "wire", resource: `acct/${to}`, context: { amount }, approval: token });
+}
+```
+
+- **Three-state verdict** — `NeedsApproval` is surfaced when a matched permit is
+  annotated `@enforcement_effect("require_approval")`.
+- **Correlation id** — every decision returns `decisionId` (also in the audit
+  line), so you can join it to your own records.
+- The audit line now carries `decision_id` + the resolved `principal`, and stays
+  value-free (no context values).
+
+## Strip PII before the agent reads a document
+
+Redact PII from text before it reaches the agent — deterministic, in-process,
+fail-closed. Extract your document to text first (never hand the agent the
+original PDF — its hidden layers leak), then sanitize:
+
+```ts
+import { govern } from "@watchlight/sdk";
+
+const text = await extractPdfText("statement.pdf"); // your extractor
+const { text: safe, report } = govern.sanitize(text, { resource: "statement.pdf" });
+
+// safe → "Card on file: <CREDIT_CARD_1>  SSN: <SSN_1>  ..."
+// report → { mode:"tag", counts:{ CREDIT_CARD:1, SSN:1, ... }, total, ... }  (value-free)
+await agent.read(safe);
+```
+
+The deterministic detector covers structured PII — email, phone, SSN, credit card
+(Luhn-validated), IBAN, IPv4, API keys. Modes: `tag` (consistent `<EMAIL_1>`
+placeholders, default), `mask` (`[EMAIL]`), `hash`. `govern.sanitize` records a
+**value-free** audit entry (counts by type + mode — never the values).
+
+A pure `sanitize(text, opts)` is also exported. Fail-closed: it throws
+`SanitizeError` rather than return partially-redacted text. Names/addresses need
+NER (Enterprise); recall is bounded by the enabled detectors.
+
 ## Value-free audit
 
 `.watchlight/audit.jsonl` records **who / what intent / which tool / the

package/dist/backend.d.ts

@@ -8,7 +8,16 @@ export interface AuthorizeRequest {
 export interface Decision {
     decision: string;
     reason: string;
+    /** Per-decision correlation id (the engine's `request_id`) — join to your own
+     *  records. */
+    decisionId?: string;
+    /** True when a matched permit carries the `require_approval` enforcement
+     *  effect: the action is permitted only after a human confirmation. */
+    needsApproval?: boolean;
 }
+/** Derive `needsApproval` from a decision's details: a permitting policy result
+ *  annotated `@enforcement_effect("require_approval")`. */
+export declare function deriveNeedsApproval(details: unknown): boolean;
 export interface GovernanceBackend {
     readonly kind: "in-process" | "networked";
     /** A short human label for the dev announce line. */

package/dist/backend.js

@@ -14,8 +14,20 @@
 // Fail-closed everywhere: any transport/engine error resolves to Deny.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NetworkedBackend = exports.InProcessBackend = void 0;
+exports.deriveNeedsApproval = deriveNeedsApproval;
 exports.selectBackend = selectBackend;
 const engine_1 = require("@watchlight/engine");
+/** Derive `needsApproval` from a decision's details: a permitting policy result
+ *  annotated `@enforcement_effect("require_approval")`. */
+function deriveNeedsApproval(details) {
+    const results = details?.policy_results;
+    // Only the policy that actually matched this request (`applicable: true`)
+    // counts — a non-matching require_approval policy elsewhere in the set must not
+    // flag this decision.
+    return Array.isArray(results)
+        ? results.some((r) => r?.applicable === true && r?.enforcement_effect === "require_approval")
+        : false;
+}
 /** DE default — the compiled engine in-process. */
 class InProcessBackend {
     constructor() {
@@ -40,13 +52,18 @@ class InProcessBackend {
     }
     async authorize(req) {
         const engine = await this._ready();
-        const resp = await engine.authorize({
+        const resp = (await engine.authorize({
             principal: req.principal,
             action: req.action,
             resource: req.resource,
             context: req.context ?? {},
-        });
-        return { decision: resp.decision ?? "Deny", reason: resp.reason ?? "" };
+        }));
+        return {
+            decision: resp.decision ?? "Deny",
+            reason: resp.reason ?? "",
+            decisionId: resp.request_id,
+            needsApproval: deriveNeedsApproval(resp.details),
+        };
     }
     engine() {
         return this._ready();
@@ -91,7 +108,12 @@ class NetworkedBackend {
             if (!resp.ok)
                 return { decision: "Deny", reason: `APDP error: ${resp.status}` };
             const data = (await resp.json());
-            return { decision: data.decision ?? "Deny", reason: data.reason ?? "" };
+            return {
+                decision: data.decision ?? "Deny",
+                reason: data.reason ?? "",
+                decisionId: data.request_id,
+                needsApproval: deriveNeedsApproval(data.details),
+            };
         }
         catch (e) {
             // Fail-closed: an unreachable control plane denies.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"use strict";
+// The `watchlight` command for the Node/TypeScript lane.
+//
+//   npx watchlight policy test <suite.json>
+//
+// Runs a policy test suite (golden fixtures → expected Allow/Deny/NeedsApproval)
+// against the DE engine and exits non-zero if any fixture fails — drop it into
+// CI to gate a policy change before it can gate a real action. The suite file is
+//
+//   { "policyFile": "watchlight.policy.json",       // and/or inline "policies"
+//     "tests": [ { "name": "...", "action": "book",
+//                  "context": { "amount": 200, "limit": 500 },
+//                  "expect": "Allow" } ] }
+//
+// The dashboard lives in the Python package (`watchlight dev`); this Node CLI is
+// scoped to policy testing.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("node:path"));
+const index_1 = require("./index");
+const policytest_1 = require("./policytest");
+const USAGE = `watchlight — Watchlight Developer Edition (Node)
+
+usage:
+  watchlight policy test <suite.json>   run policy fixtures, exit 1 on failure
+
+suite.json:
+  { "policyFile": "watchlight.policy.json",
+    "policies":   [ { "name": "...", "code": "permit(...);" } ],
+    "tests":      [ { "name": "under limit", "action": "book",
+                      "principal": "User::\\"alice\\"", "resource": "trip/42",
+                      "context": { "amount": 200, "limit": 500 },
+                      "expect": "Allow" } ] }
+`;
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
+const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
+const dim = (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
+function printReport(file, report) {
+    console.log(`watchlight policy test — ${file}\n`);
+    for (const r of report.results) {
+        if (r.ok) {
+            console.log(`  ${green("✓")} ${r.name} ${dim("→ " + r.actual)}`);
+        }
+        else {
+            const why = r.reason ? dim(`  (${r.reason})`) : "";
+            console.log(`  ${red("✗")} ${r.name} ${red(`— expected ${r.expected}, got ${r.actual}`)}${why}`);
+        }
+    }
+    const summary = `${report.passed} passed, ${report.failed} failed (${report.total} total)`;
+    console.log("\n" + (report.failed ? red(summary) : green(summary)));
+}
+async function policyTest(file) {
+    if (!file) {
+        console.error("watchlight policy test: missing <suite.json>\n");
+        console.error(USAGE);
+        return 2;
+    }
+    let suite;
+    try {
+        suite = (0, policytest_1.loadTestSuite)(file);
+    }
+    catch (e) {
+        console.error(`watchlight: could not read suite '${file}': ${e.message}`);
+        return 2;
+    }
+    // Fresh, policy-free governor (fail-closed); load only what the suite declares.
+    // No audit is written — `test()` uses the engine's decision core directly.
+    const gov = new index_1.Watchlight({ agent: "policy-test" });
+    if (suite.policyFile) {
+        gov.load(path.resolve(path.dirname(file), suite.policyFile));
+    }
+    for (const p of suite.policies ?? [])
+        gov.allow(p.code, p.name);
+    if (!suite.tests || suite.tests.length === 0) {
+        console.error(`watchlight: suite '${file}' has no tests`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await gov.test(suite.tests);
+    }
+    catch (e) {
+        // malformed fixture (missing action/expect)
+        console.error(`watchlight: ${e.message}`);
+        return 2;
+    }
+    printReport(file, report);
+    return report.failed > 0 ? 1 : 0;
+}
+async function main(argv) {
+    const [cmd, sub, ...rest] = argv;
+    if (cmd === "policy" && sub === "test")
+        return policyTest(rest[0]);
+    if (cmd === "--help" || cmd === "-h" || cmd === undefined) {
+        console.log(USAGE);
+        return 0;
+    }
+    console.error(`watchlight: unknown command '${[cmd, sub].filter(Boolean).join(" ")}'\n`);
+    console.error(USAGE);
+    return 2;
+}
+main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((e) => {
+    console.error(`watchlight: ${e?.message ?? e}`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -1,11 +1,17 @@
 import { Scope } from "./attenuation";
+import { type SanitizeOptions, type SanitizeResult } from "./sanitize";
+import { type PolicyTestCase, type PolicyTestReport } from "./policytest";
 export { Scope, DE_MAX_DEPTH, AttenuationDenied, DevEditionCeiling } from "./attenuation";
 export { governedHooks } from "./claude-agent";
 export type { GovernedHooksOptions, GovernedHooksResult } from "./claude-agent";
 export { governTool, governTools } from "./langchain";
 export type { LangChainToolLike, GovernToolOptions, GovernToolsOptions, } from "./langchain";
+export { sanitize, SanitizeError, DETECTOR_VERSION } from "./sanitize";
+export type { PiiType, RedactMode, SanitizeOptions, SanitizeReport, SanitizeResult, } from "./sanitize";
 export type { GovernanceBackend, Decision, AuthorizeRequest } from "./backend";
 export { InProcessBackend, NetworkedBackend } from "./backend";
+export { runPolicyTests, loadTestSuite } from "./policytest";
+export type { PolicyTestCase, PolicyTestReport, PolicyTestResult, PolicyTestSuite, } from "./policytest";
 /** Raised when the policy engine refuses a governed tool call (fail-closed). */
 export declare class Denied extends Error {
     readonly tool: string;
@@ -13,6 +19,32 @@ export declare class Denied extends Error {
     readonly reason: string;
     constructor(tool: string, intent: string, reason: string);
 }
+/** Raised when a governed call is permitted only after a human confirmation
+ *  (the matched permit carries the `require_approval` enforcement effect) and no
+ *  valid approval was supplied. Fail-closed: the tool body did NOT run. */
+export declare class NeedsApproval extends Error {
+    readonly tool: string;
+    readonly intent: string;
+    readonly decisionId?: string;
+    readonly reason: string;
+    constructor(tool: string, intent: string, decisionId: string | undefined, reason: string);
+}
+/** A per-call binding: a fixed value, or a function of the tool's arguments. */
+export type Binding<A extends unknown[]> = string | ((...args: A) => string);
+/** A record of attributes passed into Cedar `context.*`, or a function of args. */
+export type ContextBinding<A extends unknown[]> = Record<string, unknown> | ((...args: A) => Record<string, unknown>);
+/** Full result of {@link Watchlight.authorize}. */
+export interface AuthorizeResult {
+    /** `"Allow"` | `"Deny"` | `"NeedsApproval"`. */
+    decision: "Allow" | "Deny" | "NeedsApproval";
+    allowed: boolean;
+    needsApproval: boolean;
+    /** True when a valid approval token downgraded a NeedsApproval to Allow. */
+    approved: boolean;
+    /** Per-decision correlation id (engine `request_id`) — join to your records. */
+    decisionId?: string;
+    reason: string;
+}
 /** A function governed by {@link Watchlight.tool} — always async (the engine's
  *  authorize path is async in WebAssembly). */
 export type Governed<A extends unknown[], R> = (...args: A) => Promise<Awaited<R>>;
@@ -77,6 +109,24 @@ export declare class Watchlight {
      */
     tool<A extends unknown[], R>(fn: (...args: A) => R, opts: {
         intent: string;
+        /** Acting principal, e.g. `User::"u1"` — value or `(args) => value`.
+         *  Defaults to the agent. */
+        principal?: Binding<A>;
+        /** Cedar resource entity — value or `(args) => value`. Defaults to
+         *  `tool/<name>`. */
+        resource?: Binding<A>;
+        /** Attributes for Cedar `context.*` — object or `(args) => object`. */
+        context?: ContextBinding<A>;
+        /** Human-in-the-loop hook. Called when the decision is `NeedsApproval`;
+         *  return `true` to proceed (records an approval), `false`/absent to hold
+         *  (throws `NeedsApproval`). */
+        onNeedsApproval?: (info: {
+            intent: string;
+            resource: string;
+            principal: string;
+            decisionId?: string;
+            reason: string;
+        }) => boolean | Promise<boolean>;
     }): Governed<A, R>;
     /**
      * Authorize a raw `(intent, tool)` pair, audit the decision, and return it.
@@ -88,8 +138,70 @@ export declare class Watchlight {
         allowed: boolean;
         decision: string;
         reason: string;
+        decisionId?: string;
     }>;
-    private _authorize;
+    /**
+     * Authorize an action with full control — per-call `principal`, `resource`,
+     * and Cedar `context` — and get a correlation id back. The low-level primitive
+     * behind {@link tool}; use it directly for any consequential action.
+     *
+     * Returns a three-state verdict: `Allow` / `Deny` / `NeedsApproval`. A
+     * `NeedsApproval` (matched permit annotated `require_approval`) is downgraded
+     * to `Allow` when a valid single-use `approval` token — from
+     * {@link mintApproval}, minted after a human confirms — is supplied.
+     * Fail-closed and audited (value-free).
+     */
+    authorize(req: {
+        action: string;
+        principal?: string;
+        resource?: string;
+        context?: Record<string, unknown>;
+        /** A token from {@link mintApproval} (after human confirmation). */
+        approval?: string;
+    }): Promise<AuthorizeResult>;
+    /**
+     * The pure decision core behind {@link authorize}: run the engine, apply the
+     * approval-token downgrade, and compute the three-state verdict — WITHOUT
+     * writing to the audit trail. Used by {@link authorize} (which then audits)
+     * and by {@link test} (which must not pollute the trail with fixture runs).
+     */
+    private _decide;
+    /**
+     * Run a list of policy fixtures against the loaded policies and report which
+     * pass — a golden-test harness for CI, so a policy change is verified before
+     * it gates real actions. Each case asserts the expected verdict
+     * (`Allow` / `Deny` / `NeedsApproval`) for a `(principal, action, resource,
+     * context)`; set `approved: true` to mint a valid approval token and assert
+     * the human-confirmed downgrade. Does NOT write to the audit trail. A verdict
+     * mismatch is a failed result (inspect `report.failed` and assert on it in
+     * your test runner); a malformed fixture missing `action`/`expect` throws.
+     */
+    test(cases: readonly PolicyTestCase[]): Promise<PolicyTestReport>;
+    /**
+     * Mint a single-use approval token for a specific `(principal, action,
+     * resource)`, to pass to {@link authorize} after a human confirms a
+     * `NeedsApproval` decision. Local HMAC, TTL-bounded (default 2 min). In
+     * Enterprise these are KMS-signed and recorded in signed lineage.
+     */
+    mintApproval(challenge: {
+        action: string;
+        principal?: string;
+        resource?: string;
+    }, opts?: {
+        ttlMs?: number;
+    }): string;
+    /**
+     * Strip PII from text before an agent reads it (governed data minimization).
+     * Deterministic, fail-closed. Writes a value-free `sanitization` record to the
+     * audit trail (counts by PII type + mode — never the values) and returns the
+     * redacted text plus the report. Operates on extracted text — extract a
+     * document to text first (never hand the agent a "redacted PDF").
+     */
+    sanitize(content: string, opts?: SanitizeOptions & {
+        intent?: string;
+        resource?: string;
+    }): SanitizeResult;
+    private _auditSanitize;
     private _announce;
     private _audit;
 }

package/dist/index.js

@@ -49,11 +49,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.govern = exports.Watchlight = exports.Denied = exports.NetworkedBackend = exports.InProcessBackend = exports.governTools = exports.governTool = exports.governedHooks = exports.DevEditionCeiling = exports.AttenuationDenied = exports.DE_MAX_DEPTH = exports.Scope = void 0;
+exports.govern = exports.Watchlight = exports.NeedsApproval = exports.Denied = exports.loadTestSuite = exports.runPolicyTests = exports.NetworkedBackend = exports.InProcessBackend = exports.DETECTOR_VERSION = exports.SanitizeError = exports.sanitize = exports.governTools = exports.governTool = exports.governedHooks = exports.DevEditionCeiling = exports.AttenuationDenied = exports.DE_MAX_DEPTH = exports.Scope = void 0;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const attenuation_1 = require("./attenuation");
 const backend_1 = require("./backend");
+const sanitize_1 = require("./sanitize");
+const policytest_1 = require("./policytest");
 var attenuation_2 = require("./attenuation");
 Object.defineProperty(exports, "Scope", { enumerable: true, get: function () { return attenuation_2.Scope; } });
 Object.defineProperty(exports, "DE_MAX_DEPTH", { enumerable: true, get: function () { return attenuation_2.DE_MAX_DEPTH; } });
@@ -64,9 +67,16 @@ Object.defineProperty(exports, "governedHooks", { enumerable: true, get: functio
 var langchain_1 = require("./langchain");
 Object.defineProperty(exports, "governTool", { enumerable: true, get: function () { return langchain_1.governTool; } });
 Object.defineProperty(exports, "governTools", { enumerable: true, get: function () { return langchain_1.governTools; } });
+var sanitize_2 = require("./sanitize");
+Object.defineProperty(exports, "sanitize", { enumerable: true, get: function () { return sanitize_2.sanitize; } });
+Object.defineProperty(exports, "SanitizeError", { enumerable: true, get: function () { return sanitize_2.SanitizeError; } });
+Object.defineProperty(exports, "DETECTOR_VERSION", { enumerable: true, get: function () { return sanitize_2.DETECTOR_VERSION; } });
 var backend_2 = require("./backend");
 Object.defineProperty(exports, "InProcessBackend", { enumerable: true, get: function () { return backend_2.InProcessBackend; } });
 Object.defineProperty(exports, "NetworkedBackend", { enumerable: true, get: function () { return backend_2.NetworkedBackend; } });
+var policytest_2 = require("./policytest");
+Object.defineProperty(exports, "runPolicyTests", { enumerable: true, get: function () { return policytest_2.runPolicyTests; } });
+Object.defineProperty(exports, "loadTestSuite", { enumerable: true, get: function () { return policytest_2.loadTestSuite; } });
 /** Raised when the policy engine refuses a governed tool call (fail-closed). */
 class Denied extends Error {
     constructor(tool, intent, reason) {
@@ -78,6 +88,63 @@ class Denied extends Error {
     }
 }
 exports.Denied = Denied;
+/** Raised when a governed call is permitted only after a human confirmation
+ *  (the matched permit carries the `require_approval` enforcement effect) and no
+ *  valid approval was supplied. Fail-closed: the tool body did NOT run. */
+class NeedsApproval extends Error {
+    constructor(tool, intent, decisionId, reason) {
+        super(`watchlight requires human approval for intent '${intent}' on tool/${tool}`);
+        this.name = "NeedsApproval";
+        this.tool = tool;
+        this.intent = intent;
+        this.decisionId = decisionId;
+        this.reason = reason;
+    }
+}
+exports.NeedsApproval = NeedsApproval;
+// ── approval tokens (DE: local, single-use, HMAC, TTL) ───────────────
+// Enterprise mints these KMS-signed and records them in signed lineage.
+const APPROVAL_SECRET = (0, node_crypto_1.randomBytes)(32);
+const USED_APPROVALS = new Set();
+const approvalPayload = (principal, action, resource, exp, nonce) => `${principal} ${action} ${resource} ${exp} ${nonce}`;
+function mintApprovalToken(principal, action, resource, ttlMs) {
+    const exp = Date.now() + ttlMs;
+    // A per-mint nonce makes every token unique, so two approvals for the same
+    // (principal, action, resource) minted in the same millisecond never collide
+    // — and "single-use" is genuinely per-mint, not per-(challenge, exp).
+    const nonce = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const sig = (0, node_crypto_1.createHmac)("sha256", APPROVAL_SECRET)
+        .update(approvalPayload(principal, action, resource, exp, nonce))
+        .digest("hex");
+    return `${exp}.${nonce}.${sig}`;
+}
+/** Verify + CONSUME an approval token (single-use). Bound to the exact
+ *  (principal, action, resource); rejects expired, tampered, or reused tokens. */
+function consumeApprovalToken(token, principal, action, resource) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    const [expStr, nonce, sig] = parts;
+    const exp = Number(expStr);
+    if (!Number.isFinite(exp) || Date.now() > exp)
+        return false;
+    const expected = (0, node_crypto_1.createHmac)("sha256", APPROVAL_SECRET)
+        .update(approvalPayload(principal, action, resource, exp, nonce))
+        .digest("hex");
+    if (sig.length !== expected.length)
+        return false;
+    if (!(0, node_crypto_1.timingSafeEqual)(Buffer.from(sig, "hex"), Buffer.from(expected, "hex")))
+        return false;
+    if (USED_APPROVALS.has(token))
+        return false;
+    USED_APPROVALS.add(token);
+    return true;
+}
+function resolveBinding(b, args) {
+    if (b === undefined)
+        return undefined;
+    return typeof b === "function" ? b(...args) : b;
+}
 const norm = (x) => (x ? [...x] : []);
 /**
  * An in-process policy decision point for a single agent. Wraps the
@@ -160,14 +227,32 @@ class Watchlight {
     tool(fn, opts) {
         const intent = opts.intent;
         const name = fn.name || "anonymous";
-        const resource = `tool/${name}`;
         return async (...args) => {
-            const [decision, reason] = await this._authorize(intent, resource);
-            this._audit(intent, resource, decision, reason);
-            if (decision !== "Allow") {
-                throw new Denied(name, intent, reason || "no matching policy");
+            const principal = resolveBinding(opts.principal, args) ?? this.agent;
+            const resource = resolveBinding(opts.resource, args) ?? `tool/${name}`;
+            const context = typeof opts.context === "function" ? opts.context(...args) : opts.context ?? {};
+            const d = await this.authorize({ principal, action: intent, resource, context });
+            if (d.allowed)
+                return (await fn(...args));
+            if (d.needsApproval) {
+                if (opts.onNeedsApproval) {
+                    const ok = await opts.onNeedsApproval({
+                        intent,
+                        resource,
+                        principal,
+                        decisionId: d.decisionId,
+                        reason: d.reason,
+                    });
+                    if (ok) {
+                        const token = this.mintApproval({ principal, action: intent, resource });
+                        const d2 = await this.authorize({ principal, action: intent, resource, context, approval: token });
+                        if (d2.allowed)
+                            return (await fn(...args));
+                    }
+                }
+                throw new NeedsApproval(name, intent, d.decisionId, d.reason);
             }
-            return (await fn(...args));
+            throw new Denied(name, intent, d.reason || "no matching policy");
         };
     }
     /**
@@ -177,20 +262,135 @@ class Watchlight {
      * decision is identical to {@link tool}, just without running a body.
      */
     async check(intent, toolName) {
-        const resource = `tool/${toolName}`;
-        const [decision, reason] = await this._authorize(intent, resource);
-        this._audit(intent, resource, decision, reason);
-        return { allowed: decision === "Allow", decision, reason };
+        const d = await this.authorize({ action: intent, resource: `tool/${toolName}` });
+        return { allowed: d.allowed, decision: d.decision, reason: d.reason, decisionId: d.decisionId };
     }
-    // ── internals ─────────────────────────────────────────────────────
-    async _authorize(intent, resource) {
-        const { decision, reason } = await this._backend.authorize({
-            principal: this.agent,
-            action: intent,
+    /**
+     * Authorize an action with full control — per-call `principal`, `resource`,
+     * and Cedar `context` — and get a correlation id back. The low-level primitive
+     * behind {@link tool}; use it directly for any consequential action.
+     *
+     * Returns a three-state verdict: `Allow` / `Deny` / `NeedsApproval`. A
+     * `NeedsApproval` (matched permit annotated `require_approval`) is downgraded
+     * to `Allow` when a valid single-use `approval` token — from
+     * {@link mintApproval}, minted after a human confirms — is supplied.
+     * Fail-closed and audited (value-free).
+     */
+    async authorize(req) {
+        const { result, principal, resource, decisionId } = await this._decide(req);
+        this._audit(req.action, resource, result.decision, result.reason, {
+            principal,
+            decisionId,
+            approved: result.approved,
+        });
+        return result;
+    }
+    /**
+     * The pure decision core behind {@link authorize}: run the engine, apply the
+     * approval-token downgrade, and compute the three-state verdict — WITHOUT
+     * writing to the audit trail. Used by {@link authorize} (which then audits)
+     * and by {@link test} (which must not pollute the trail with fixture runs).
+     */
+    async _decide(req) {
+        const principal = req.principal ?? this.agent;
+        const resource = req.resource ?? "resource";
+        const raw = await this._backend.authorize({
+            principal,
+            action: req.action,
             resource,
-            context: {},
+            context: req.context ?? {},
         });
-        return [decision, reason];
+        let allowed = raw.decision === "Allow";
+        let needsApproval = allowed && !!raw.needsApproval;
+        let approved = false;
+        if (needsApproval) {
+            if (req.approval && consumeApprovalToken(req.approval, principal, req.action, resource)) {
+                approved = true;
+                needsApproval = false; // human-confirmed → proceed
+            }
+            else {
+                allowed = false; // hold for approval
+            }
+        }
+        const decision = allowed
+            ? "Allow"
+            : needsApproval
+                ? "NeedsApproval"
+                : "Deny";
+        return {
+            result: {
+                decision,
+                allowed,
+                needsApproval,
+                approved,
+                decisionId: raw.decisionId,
+                reason: raw.reason,
+            },
+            principal,
+            resource,
+            decisionId: raw.decisionId,
+        };
+    }
+    /**
+     * Run a list of policy fixtures against the loaded policies and report which
+     * pass — a golden-test harness for CI, so a policy change is verified before
+     * it gates real actions. Each case asserts the expected verdict
+     * (`Allow` / `Deny` / `NeedsApproval`) for a `(principal, action, resource,
+     * context)`; set `approved: true` to mint a valid approval token and assert
+     * the human-confirmed downgrade. Does NOT write to the audit trail. A verdict
+     * mismatch is a failed result (inspect `report.failed` and assert on it in
+     * your test runner); a malformed fixture missing `action`/`expect` throws.
+     */
+    async test(cases) {
+        return (0, policytest_1.runPolicyTests)((req) => this._decide(req).then((d) => d.result), (challenge) => this.mintApproval(challenge), cases);
+    }
+    /**
+     * Mint a single-use approval token for a specific `(principal, action,
+     * resource)`, to pass to {@link authorize} after a human confirms a
+     * `NeedsApproval` decision. Local HMAC, TTL-bounded (default 2 min). In
+     * Enterprise these are KMS-signed and recorded in signed lineage.
+     */
+    mintApproval(challenge, opts = {}) {
+        return mintApprovalToken(challenge.principal ?? this.agent, challenge.action, challenge.resource ?? "resource", opts.ttlMs ?? 120000);
+    }
+    /**
+     * Strip PII from text before an agent reads it (governed data minimization).
+     * Deterministic, fail-closed. Writes a value-free `sanitization` record to the
+     * audit trail (counts by PII type + mode — never the values) and returns the
+     * redacted text plus the report. Operates on extracted text — extract a
+     * document to text first (never hand the agent a "redacted PDF").
+     */
+    sanitize(content, opts = {}) {
+        const { intent = "read", resource = "document", mode, types } = opts;
+        const result = (0, sanitize_1.sanitize)(content, { mode, types });
+        this._auditSanitize(intent, resource, result);
+        return result;
+    }
+    // ── internals ─────────────────────────────────────────────────────
+    _auditSanitize(intent, resource, result) {
+        this._announce();
+        const { report } = result;
+        // eslint-disable-next-line no-console
+        console.log(`watchlight: SANIT ${intent.padEnd(9)} ${resource}     redacted ${report.total} (${report.mode})`);
+        // Value-free: counts by PII type + mode only — never the PII values.
+        const record = {
+            ts: new Date().toISOString(),
+            agent: this.agent,
+            intent,
+            event: "sanitization",
+            resource,
+            mode: report.mode,
+            detector: report.detectorVersion,
+            counts: report.counts,
+            total: report.total,
+        };
+        try {
+            fs.mkdirSync(path.dirname(this._auditPath), { recursive: true });
+            fs.appendFileSync(this._auditPath, JSON.stringify(record) + "\n", "utf8");
+        }
+        catch {
+            // Best-effort in dev mode.
+        }
     }
     _announce() {
         if (!this._announced) {
@@ -199,22 +399,26 @@ class Watchlight {
             this._announced = true;
         }
     }
-    _audit(intent, resource, decision, reason) {
+    _audit(intent, resource, decision, reason, extra = {}) {
         this._announce();
-        const allowed = decision === "Allow";
-        const tag = allowed ? "ALLOW" : "DENY";
-        const trailer = allowed ? "" : `     ${reason || "no matching policy"}`;
+        const tag = decision === "Allow" ? (extra.approved ? "OK✓" : "ALLOW") : decision === "NeedsApproval" ? "APPRV?" : "DENY";
+        const trailer = decision === "Allow" ? "" : `     ${reason || "no matching policy"}`;
         // eslint-disable-next-line no-console
-        console.log(`watchlight: ${tag.padEnd(5)} ${intent.padEnd(9)} ${resource}${trailer}`);
+        console.log(`watchlight: ${tag.padEnd(6)} ${intent.padEnd(9)} ${resource}${trailer}`);
         // Value-free audit: argument VALUES never enter the trail — only the
-        // governance decision. Mirrors the production audit contract.
+        // governance decision + correlation id. Mirrors the production audit contract.
         const record = {
             ts: new Date().toISOString(),
             agent: this.agent,
+            principal: extra.principal ?? this.agent,
             intent,
             resource,
             decision,
         };
+        if (extra.decisionId)
+            record.decision_id = extra.decisionId;
+        if (extra.approved)
+            record.approved = true;
         try {
             fs.mkdirSync(path.dirname(this._auditPath), { recursive: true });
             fs.appendFileSync(this._auditPath, JSON.stringify(record) + "\n", "utf8");

package/dist/policytest.d.ts

@@ -0,0 +1,80 @@
+/** A single policy fixture: an input and the verdict it must produce. */
+export interface PolicyTestCase {
+    /** Human-readable label (defaults to `"<action> on <resource>"`). */
+    name?: string;
+    /** The intent / action being authorized (Cedar `action == Action::"<action>"`). */
+    action: string;
+    /** Acting principal, e.g. `User::"alice"`. Defaults to the governor's agent. */
+    principal?: string;
+    /** Cedar resource entity. Defaults to `"resource"`. */
+    resource?: string;
+    /** Attributes exposed to Cedar `context.*`. */
+    context?: Record<string, unknown>;
+    /** Mint a valid single-use approval token for this case and assert the
+     *  human-confirmed downgrade (turns a `NeedsApproval` into `Allow`). */
+    approved?: boolean;
+    /** The verdict this case must produce. Case-insensitive. */
+    expect: "Allow" | "Deny" | "NeedsApproval";
+}
+/** The outcome of one fixture. */
+export interface PolicyTestResult {
+    name: string;
+    expected: "Allow" | "Deny" | "NeedsApproval";
+    actual: "Allow" | "Deny" | "NeedsApproval";
+    ok: boolean;
+    /** Engine reason — surfaced to explain an unexpected verdict. */
+    reason: string;
+}
+/** The aggregate report. `failed === 0` means the suite passed. */
+export interface PolicyTestReport {
+    total: number;
+    passed: number;
+    failed: number;
+    results: PolicyTestResult[];
+}
+/** A suite file: inline policies and/or a policy file, plus the fixtures. */
+export interface PolicyTestSuite {
+    /** Inline Cedar policies. */
+    policies?: {
+        name?: string;
+        code: string;
+    }[];
+    /** Path to a `watchlight.policy.json` (resolved relative to the suite file). */
+    policyFile?: string;
+    /** The fixtures to run. */
+    tests: PolicyTestCase[];
+}
+type Verdict = "Allow" | "Deny" | "NeedsApproval";
+/** The pure decision function the harness drives — the same core `authorize`
+ *  uses, minus the audit write. */
+export type DecideFn = (req: {
+    action: string;
+    principal?: string;
+    resource?: string;
+    context?: Record<string, unknown>;
+    approval?: string;
+}) => Promise<{
+    decision: Verdict;
+    reason: string;
+}>;
+/** Mints a single-use approval token bound to a challenge — used when a fixture
+ *  sets `approved: true` to exercise the human-confirmed path. */
+export type MintFn = (challenge: {
+    action: string;
+    principal?: string;
+    resource?: string;
+}) => string;
+/**
+ * Run policy fixtures through a decision function and report pass/fail. A
+ * verdict mismatch is recorded as a failed result rather than thrown — inspect
+ * {@link PolicyTestReport.failed}. A fixture missing a required key (`action` or
+ * `expect`) is a malformed suite and throws.
+ */
+export declare function runPolicyTests(decide: DecideFn, mint: MintFn, cases: readonly PolicyTestCase[]): Promise<PolicyTestReport>;
+/**
+ * Load a suite file. Accepts `{ policies?, policyFile? | policy_file?, tests }`
+ * (a bare array of tests is also accepted). Throws on malformed JSON so a broken
+ * suite fails the CI step rather than silently passing.
+ */
+export declare function loadTestSuite(file: string): PolicyTestSuite;
+export {};

package/dist/policytest.js

@@ -0,0 +1,123 @@
+"use strict";
+// Policy test harness — golden tests for DE policies.
+//
+// A policy is the only thing standing between an agent and a real action, so it
+// deserves the same unit-testing discipline as the code around it. This module
+// runs a list of fixtures against the loaded policies and reports which pass:
+// each case asserts the expected verdict (Allow / Deny / NeedsApproval) for a
+// `(principal, action, resource, context)`. It contains ZERO decision logic —
+// every verdict comes from the engine, via the same decision core `authorize`
+// uses — and it never writes to the audit trail, so CI runs leave no residue.
+//
+//   import { govern } from "@watchlight/sdk";
+//   govern.load("watchlight.policy.json");
+//   const r = await govern.test([
+//     { name: "under limit allows", action: "book",
+//       context: { amount: 200, limit: 500, refundable: true }, expect: "Allow" },
+//   ]);
+//   if (r.failed) throw new Error(`${r.failed} policy tests failed`);
+//
+// Or from CI, with the `watchlight` CLI:  npx watchlight policy test suite.json
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPolicyTests = runPolicyTests;
+exports.loadTestSuite = loadTestSuite;
+const fs = __importStar(require("node:fs"));
+/** Normalize a caller-supplied verdict string to the canonical spelling.
+ *  Anything unrecognized is returned verbatim so a typo fails loudly. */
+function normalizeVerdict(v) {
+    const s = String(v ?? "").trim().toLowerCase();
+    if (s === "allow" || s === "permit")
+        return "Allow";
+    if (s === "deny")
+        return "Deny";
+    if (s === "needsapproval" || s === "needs_approval" || s === "approve" || s === "approval")
+        return "NeedsApproval";
+    return v ?? "Deny";
+}
+/**
+ * Run policy fixtures through a decision function and report pass/fail. A
+ * verdict mismatch is recorded as a failed result rather than thrown — inspect
+ * {@link PolicyTestReport.failed}. A fixture missing a required key (`action` or
+ * `expect`) is a malformed suite and throws.
+ */
+async function runPolicyTests(decide, mint, cases) {
+    const results = [];
+    let index = 0;
+    for (const c of cases) {
+        for (const required of ["action", "expect"]) {
+            if (c[required] === undefined) {
+                throw new Error(`fixture ${index} (${c.name ?? "?"}): missing required key '${required}'`);
+            }
+        }
+        index += 1;
+        const expected = normalizeVerdict(c.expect);
+        const approval = c.approved
+            ? mint({ action: c.action, principal: c.principal, resource: c.resource })
+            : undefined;
+        const d = await decide({
+            action: c.action,
+            principal: c.principal,
+            resource: c.resource,
+            context: c.context,
+            approval,
+        });
+        const actual = normalizeVerdict(d.decision);
+        results.push({
+            name: c.name ?? `${c.action} on ${c.resource ?? "resource"}`,
+            expected,
+            actual,
+            ok: actual === expected,
+            reason: d.reason ?? "",
+        });
+    }
+    const passed = results.filter((r) => r.ok).length;
+    return { total: results.length, passed, failed: results.length - passed, results };
+}
+/**
+ * Load a suite file. Accepts `{ policies?, policyFile? | policy_file?, tests }`
+ * (a bare array of tests is also accepted). Throws on malformed JSON so a broken
+ * suite fails the CI step rather than silently passing.
+ */
+function loadTestSuite(file) {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (Array.isArray(data))
+        return { tests: data };
+    return {
+        policies: data.policies,
+        policyFile: data.policyFile ?? data.policy_file,
+        tests: data.tests ?? data.cases ?? [],
+    };
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,36 @@
+/** PII categories the deterministic detector recognizes. */
+export type PiiType = "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IBAN" | "IPV4" | "API_KEY";
+/** How a detected value is replaced. */
+export type RedactMode = "tag" | "mask" | "hash";
+export declare const DETECTOR_VERSION = "de-rules-1";
+/** Raised when sanitization cannot complete — fail-closed: the caller must NOT
+ *  fall back to raw content. */
+export declare class SanitizeError extends Error {
+    constructor(message: string);
+}
+export interface SanitizeOptions {
+    /** Replacement strategy. Default `"tag"` (consistent `<EMAIL_1>` placeholders). */
+    mode?: RedactMode;
+    /** Restrict to these PII types. Default: all deterministic types. */
+    types?: PiiType[];
+}
+export interface SanitizeReport {
+    mode: RedactMode;
+    detectorVersion: string;
+    /** Count of redactions per type. Value-free by construction — never the values. */
+    counts: Partial<Record<PiiType, number>>;
+    /** Total redactions. */
+    total: number;
+}
+export interface SanitizeResult {
+    /** The redacted text, safe to hand to an agent. */
+    text: string;
+    /** Value-free summary of what was redacted (for the audit trail). */
+    report: SanitizeReport;
+}
+/**
+ * Redact PII from `text`. Pure and deterministic. Fail-closed: throws
+ * {@link SanitizeError} on any internal error rather than returning partially
+ * processed (potentially leaking) text.
+ */
+export declare function sanitize(text: string, opts?: SanitizeOptions): SanitizeResult;

package/dist/sanitize.js

@@ -0,0 +1,155 @@
+"use strict";
+// govern.sanitize — governed data minimization at the agent boundary.
+//
+// Strip PII from text BEFORE an agent reads it. Deterministic, in-process,
+// fail-closed. This is the Developer-Edition baseline detector: high-precision
+// STRUCTURED PII via rules (email, phone, SSN, credit card w/ Luhn, IBAN, IPv4,
+// API keys). Names/addresses need NER — an opt-in / Enterprise stage — so recall
+// is honestly bounded by the enabled detectors and surfaced in the report.
+//
+// Operates on extracted TEXT. Document extraction (PDF/docx → text, across all
+// layers) is a separate step: you never hand the agent a "redacted PDF" (its
+// hidden layers leak) — you hand it redacted text.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SanitizeError = exports.DETECTOR_VERSION = void 0;
+exports.sanitize = sanitize;
+const node_crypto_1 = require("node:crypto");
+exports.DETECTOR_VERSION = "de-rules-1";
+/** Raised when sanitization cannot complete — fail-closed: the caller must NOT
+ *  fall back to raw content. */
+class SanitizeError extends Error {
+    constructor(message) {
+        super(`sanitize failed (fail-closed): ${message}`);
+        this.name = "SanitizeError";
+    }
+}
+exports.SanitizeError = SanitizeError;
+// ── deterministic detectors ─────────────────────────────────────────
+// Each returns [start, end) match spans over the input. High precision first;
+// CREDIT_CARD is Luhn-validated to cut false positives.
+const luhnOk = (digits) => {
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (d < 0 || d > 9)
+            return false;
+        if (alt) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+};
+const DETECTORS = [
+    { type: "EMAIL", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+    // API keys / tokens with well-known prefixes (before generic patterns).
+    { type: "API_KEY", re: /\b(?:sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16})\b/g },
+    { type: "SSN", re: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g },
+    {
+        type: "CREDIT_CARD",
+        re: /\b(?:\d[ -]?){13,19}\b/g,
+        valid: (m) => {
+            const d = m.replace(/[ -]/g, "");
+            return d.length >= 13 && d.length <= 19 && luhnOk(d);
+        },
+    },
+    { type: "IBAN", re: /\b[A-Z]{2}\d{2}(?:[ ]?[A-Za-z0-9]{4}){2,7}(?:[ ]?[A-Za-z0-9]{1,3})?\b/g },
+    {
+        type: "IPV4",
+        re: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+        valid: (m) => m.split(".").every((o) => Number(o) <= 255),
+    },
+    {
+        type: "PHONE",
+        re: /(?<!\d)(?:\+?\d{1,3}[ .-]?)?(?:\(\d{2,4}\)[ .-]?)?\d{3}[ .-]?\d{4}(?!\d)/g,
+        // Require at least 10 digits total to avoid matching short number runs.
+        valid: (m) => (m.replace(/\D/g, "").length >= 10),
+    },
+];
+function detect(text, types) {
+    const enabled = new Set(types);
+    const spans = [];
+    for (const det of DETECTORS) {
+        if (!enabled.has(det.type))
+            continue;
+        det.re.lastIndex = 0;
+        let m;
+        while ((m = det.re.exec(text)) !== null) {
+            const value = m[0];
+            if (det.valid && !det.valid(value))
+                continue;
+            spans.push({ start: m.index, end: m.index + value.length, type: det.type, value });
+            if (m.index === det.re.lastIndex)
+                det.re.lastIndex++; // guard zero-width
+        }
+    }
+    // Resolve overlaps: sort by start, then longest; drop any span overlapping one
+    // already kept (first detector wins by the DETECTORS order via stable sort).
+    spans.sort((a, b) => a.start - b.start || b.end - b.start - (a.end - a.start));
+    const kept = [];
+    let lastEnd = -1;
+    for (const s of spans) {
+        if (s.start >= lastEnd) {
+            kept.push(s);
+            lastEnd = s.end;
+        }
+    }
+    return kept;
+}
+function replacement(span, mode, counters, perType) {
+    if (mode === "mask")
+        return `[${span.type}]`;
+    if (mode === "hash") {
+        const h = (0, node_crypto_1.createHash)("sha256").update(span.value).digest("hex").slice(0, 8);
+        return `<${span.type}_${h}>`;
+    }
+    // tag: consistent per value (same value → same tag within this call).
+    const key = `${span.type}:${span.value}`;
+    let tag = counters.get(key);
+    if (!tag) {
+        const n = (perType.get(span.type) ?? 0) + 1;
+        perType.set(span.type, n);
+        tag = `<${span.type}_${n}>`;
+        counters.set(key, tag);
+    }
+    return tag;
+}
+/**
+ * Redact PII from `text`. Pure and deterministic. Fail-closed: throws
+ * {@link SanitizeError} on any internal error rather than returning partially
+ * processed (potentially leaking) text.
+ */
+function sanitize(text, opts = {}) {
+    const mode = opts.mode ?? "tag";
+    const types = opts.types ?? DETECTORS.map((d) => d.type);
+    if (typeof text !== "string") {
+        throw new SanitizeError("input must be a string (extract document text first)");
+    }
+    try {
+        const spans = detect(text, types);
+        const counters = new Map();
+        const perTypeTag = new Map();
+        const counts = {};
+        // Rebuild the string, replacing spans left→right.
+        let out = "";
+        let cursor = 0;
+        for (const s of spans) {
+            out += text.slice(cursor, s.start);
+            out += replacement(s, mode, counters, perTypeTag);
+            cursor = s.end;
+            counts[s.type] = (counts[s.type] ?? 0) + 1;
+        }
+        out += text.slice(cursor);
+        return {
+            text: out,
+            report: { mode, detectorVersion: exports.DETECTOR_VERSION, counts, total: spans.length },
+        };
+    }
+    catch (e) {
+        throw new SanitizeError(String(e?.message ?? e));
+    }
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@watchlight/sdk",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Watchlight Developer Edition govern glue for Node/TypeScript — declare intent, govern a tool with a fail-closed in-process policy decision, and get a value-free audit trail. Glue over @watchlight/engine; zero decision logic in JS.",
   "type": "commonjs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "watchlight": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "LICENSE",
@@ -15,7 +18,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/govern.test.mjs && node test/claude-agent.test.mjs && node test/graduation.test.mjs && node test/langchain.test.mjs",
+    "test": "npm run build && for t in govern claude-agent graduation langchain sanitize action-gate policytest; do node test/$t.test.mjs || exit 1; done",
     "prepublishOnly": "npm run build"
   },
   "keywords": [