@intutic/cli 1.10.0 → 1.10.1

package/dist/commands/policy.js

@@ -4,19 +4,46 @@ import * as os from 'node:os';
 import { createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { log } from '../lib/logger.js';
+import { NOT_AUTHENTICATED } from '../lib/authMessages.js';
+import { WASM_HOST_IMPORTS, unsupportedWasmImports, explainWasmImport, } from '@intutic/shared-types';
 import { loadCredentials, loadConfig } from '../config/store.js';
 import { resolveControlPlaneUrl } from '../config/paths.js';
 import { createApiClient } from '../lib/api.js';
-async function getClient(dev) {
+import { resolveSnapshotRulesPath, SNAPSHOT_RULES_FILE } from '../lib/policySnapshot.js';
+/**
+ * Message of a caught value.
+ *
+ * `catch` binds `unknown` — a thrown non-Error (or an Error subclass with no
+ * message) is not hypothetical here, since `abort` below and the WASM runtime
+ * both throw across the host boundary.
+ */
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The control plane these commands talk to, and the credentials for it.
+ *
+ * Lifted out of `getClient` because `policy snapshot` needs the workspace id and
+ * the raw key rather than an API client — and resolving them a second way is how
+ * one command ends up pointed at production while its neighbour is on --dev.
+ */
+async function resolveTarget(dev) {
     const creds = await loadCredentials();
     if (!creds) {
-        log.error('Not authenticated. This command needs an Intutic control plane, which open core does not include. To run the proxy without one: `intutic start`.');
+        log.error(NOT_AUTHENTICATED);
         process.exit(1);
     }
     const config = loadConfig();
     const devMode = dev || config?.devMode || process.env.INTUTIC_DEV === '1';
-    const controlPlaneUrl = resolveControlPlaneUrl(devMode);
-    return createApiClient(controlPlaneUrl, creds.apiKey);
+    return {
+        controlPlaneUrl: resolveControlPlaneUrl(devMode),
+        apiKey: creds.apiKey,
+        workspaceId: creds.workspaceId,
+    };
+}
+async function getClient(dev) {
+    const { controlPlaneUrl, apiKey } = await resolveTarget(dev);
+    return createApiClient(controlPlaneUrl, apiKey);
 }
 export async function runPolicyEnable(policyId, opts) {
     log.header(`Intutic — Enable Policy: ${policyId}`);
@@ -35,7 +62,7 @@ export async function runPolicyEnable(policyId, opts) {
         }
     }
     catch (err) {
-        log.error(`Failed to enable policy: ${err.message}`);
+        log.error(`Failed to enable policy: ${errMessage(err)}`);
         process.exit(1);
     }
 }
@@ -56,7 +83,7 @@ export async function runPolicyDisable(policyId, opts) {
         }
     }
     catch (err) {
-        log.error(`Failed to disable policy: ${err.message}`);
+        log.error(`Failed to disable policy: ${errMessage(err)}`);
         process.exit(1);
     }
 }
@@ -82,7 +109,7 @@ export async function runPolicyRollback(policyId, opts) {
         }
     }
     catch (err) {
-        log.error(`Failed to rollback policy: ${err.message}`);
+        log.error(`Failed to rollback policy: ${errMessage(err)}`);
         process.exit(1);
     }
 }
@@ -102,10 +129,55 @@ export async function runPolicyExport(opts) {
         }
     }
     catch (err) {
-        log.error(`Failed to export policies: ${err.message}`);
+        log.error(`Failed to export policies: ${errMessage(err)}`);
         process.exit(1);
     }
 }
+/**
+ * `intutic policy snapshot` — compile this workspace's policy to disk.
+ *
+ * The snapshot is the dynamic tier: every harness gate reads
+ * `~/.intutic/hooks/policy-snapshot.rules` and enforces the compiled floor and
+ * nothing else when it is missing. Until this command existed the only thing
+ * that ever wrote it was `intutic connect`, so arming the gates meant running a
+ * daemon that also rewrites five harnesses' hook configs, starts a drift
+ * watcher and provisions Valkey. This does the one thing.
+ */
+export async function runPolicySnapshot(opts) {
+    log.header('Intutic — Refresh Policy Snapshot');
+    const { controlPlaneUrl, apiKey, workspaceId } = await resolveTarget(opts.dev);
+    // The gates consult INTUTIC_SNAPSHOT_RULES before the default path, so writing
+    // to the default while they read elsewhere would produce a snapshot nothing
+    // enforces — the precise silent failure this command exists to end.
+    const rulesPath = resolveSnapshotRulesPath();
+    const snapshotDir = path.dirname(rulesPath);
+    if (path.basename(rulesPath) !== SNAPSHOT_RULES_FILE) {
+        log.warn(`INTUTIC_SNAPSHOT_RULES names "${path.basename(rulesPath)}", but the writer always produces ` +
+            `"${SNAPSHOT_RULES_FILE}" — the gates will read a file this command does not write.`);
+    }
+    // Imported here rather than at module scope: @intutic/sync-daemon pulls in ws,
+    // ioredis and chokidar, and every other `intutic policy` subcommand would pay
+    // that startup cost without ever touching a snapshot.
+    const { refreshPolicySnapshot } = await import('@intutic/sync-daemon');
+    const result = await refreshPolicySnapshot({ controlPlaneUrl, apiKey, workspaceId, snapshotDir });
+    // `refreshPolicySnapshot` never throws — policy refresh must not be able to
+    // take down the daemon's sync loop — so null is the only failure signal it
+    // has. Reporting that as success is how a machine comes to enforce nothing
+    // while the command meant to arm it said it worked.
+    if (!result) {
+        log.error('Snapshot NOT written — GET /api/v1/policy/resolve returned nothing usable.');
+        log.field('Control plane', controlPlaneUrl);
+        log.field('Workspace', workspaceId);
+        log.info('Any previous snapshot is untouched and still enforced.');
+        log.info('Check the control plane is reachable and the key is still valid: `intutic whoami`.');
+        process.exit(1);
+    }
+    log.success(`Policy snapshot written — ${result.ruleCount} rule(s) now enforced by every gate.`);
+    log.field('Digest', result.digest);
+    log.field('Workspace', workspaceId);
+    log.field('Path', path.join(snapshotDir, SNAPSHOT_RULES_FILE));
+    log.info('Confirm the gates accept it with `intutic doctor`.');
+}
 /**
  * Minimal RequestContext used to validate a rule instantiates and evaluates
  * before install. Mirrors packages/wasm-sdk/assembly/mock_context_allow.json
@@ -123,125 +195,276 @@ export const DEFAULT_ALLOW_MOCK = JSON.stringify({
     risk_tier: 'Low',
     dlp_findings: []
 });
+/**
+ * Every host function the proxy registers, declared once on this side.
+ *
+ * `tools/scripts/check-wasm-host-imports.js` asserts this equals
+ * `HOST_IMPORTS` in `packages/proxy/src/wasm/host.rs`. The two had already
+ * drifted — this side offered `seed`, the proxy never has — and the drift was
+ * invisible because it only surfaced as a per-request warning in a process
+ * nobody was reading.
+ */
+export const HOST_IMPORT_NAMES = WASM_HOST_IMPORTS;
+/**
+ * A callable export, or null when the module does not export that name (or
+ * exports it as a global/table/memory instead of a function).
+ *
+ * The variadic signature is the widest thing every guest function here fits;
+ * `resolveGuestAbi` immediately narrows each one to its real arity by way of
+ * the `WasmGuestAbi` members it assigns them to.
+ */
+function exportedFunction(exports, name) {
+    const value = exports[name];
+    return typeof value === 'function' ? value : null;
+}
+/** Resolve the guest ABI, throwing a message that names the missing export. */
+function resolveGuestAbi(instance) {
+    const { exports } = instance;
+    const memory = exports.memory;
+    if (!(memory instanceof WebAssembly.Memory)) {
+        // Previously read as `exports.memory as WebAssembly.Memory` and dereferenced,
+        // so a module without a memory export failed with "Cannot read properties of
+        // undefined (reading 'buffer')" instead of saying what was wrong.
+        throw new Error("WASM module does not export 'memory'. Compile with AssemblyScript's " +
+            'default settings (`--exportRuntime`) so the host can read what the rule returns.');
+    }
+    // Accept exactly the allocator exports the proxy runner accepts
+    // (packages/proxy/src/wasm/runner.rs: `allocate`, then `__new`) — anything
+    // looser would validate rules the proxy then silently fails open on.
+    let allocate;
+    const allocateExport = exportedFunction(exports, 'allocate');
+    if (allocateExport) {
+        allocate = allocateExport;
+    }
+    else {
+        const newExport = exportedFunction(exports, '__new');
+        if (!newExport) {
+            throw new Error("WASM module is missing 'allocate' or '__new' memory helpers.");
+        }
+        allocate = (size) => newExport(size, 0);
+    }
+    const evaluate = exportedFunction(exports, 'evaluate');
+    if (!evaluate) {
+        throw new Error("WASM module is missing 'evaluate' function export.");
+    }
+    return { memory, allocate, evaluate };
+}
+/**
+ * Read `len` UTF-8 bytes at `ptr` out of guest memory, or null if that range is
+ * not wholly inside it.
+ */
+function readGuestUtf8(memory, ptr, len) {
+    const size = memory.buffer.byteLength;
+    if (!Number.isInteger(ptr) || !Number.isInteger(len) || ptr < 0 || len < 0 || ptr + len > size) {
+        return null;
+    }
+    return Buffer.from(memory.buffer, ptr, len).toString('utf-8');
+}
+/**
+ * Read an AssemblyScript string — UTF-16LE, with a 4-byte little-endian byte
+ * length in the header immediately before the pointer — out of guest memory.
+ * Returns null if the pointer or the length it declares is out of bounds.
+ *
+ * That bounds check is the point of the helper. The two copies of this loop it
+ * replaces trusted the header, which is a value the guest writes: a rule
+ * aborting with a bogus pointer could name a 4 GB string and send the CLI into
+ * a multi-billion-iteration loop building it one char at a time. The proxy host
+ * checks the same range and logs the raw pointer when it does not fit
+ * (`packages/proxy/src/wasm/host.rs`).
+ */
+function readGuestString(memory, ptr) {
+    const size = memory.buffer.byteLength;
+    if (!Number.isInteger(ptr) || ptr < 4 || ptr > size)
+        return null;
+    const byteLength = new DataView(memory.buffer).getUint32(ptr - 4, true);
+    if (byteLength % 2 !== 0 || ptr + byteLength > size)
+        return null;
+    return Buffer.from(memory.buffer, ptr, byteLength).toString('utf16le');
+}
 /**
  * Instantiate a compiled WASM rule with the standard host imports and run
  * `evaluate` against a JSON-serialized RequestContext. Returns the raw
- * verdict code (0=ALLOW, 1=BLOCK, 2=REDACT). Throws on any instantiation or
+ * verdict code (0=ALLOW, 1=BLOCK, 3=REASK; 2 is a deprecated block). Throws on any instantiation or
  * ABI failure — callers decide how to surface it.
  */
-export async function instantiateAndEvaluate(wasmBuffer, mockStr, opts = {}) {
+/**
+ * Re-exported so existing callers and tests keep one import site.
+ *
+ * The implementations live in `@intutic/shared-types` because three surfaces
+ * need them — this CLI, the control plane's upload endpoint, and the SDK test
+ * harness — and each having its own copy is precisely how `seed` came to be
+ * offered here and never registered by the proxy.
+ */
+export const unsupportedImports = unsupportedWasmImports;
+export const explainUnsupportedImport = explainWasmImport;
+/**
+ * Instantiates a compiled rule with the proxy's host imports and evaluates it
+ * against one mock context, returning the raw verdict code.
+ *
+ * The import set here is the proxy's, not a convenient superset: a rule that
+ * links in this sandbox must link in the proxy, or install validation passes
+ * something the proxy then silently bypasses.
+ */
+export async function instantiateAndEvaluate(wasmBuffer, mockStr) {
     let instanceRef = null;
+    /**
+     * Guest memory, or null before `WebAssembly.instantiate` has resolved.
+     *
+     * The null is load-bearing, not defensive padding: AssemblyScript's start
+     * function runs during instantiation and can call `abort` or `trace` from
+     * there, so a host import can be invoked before there is an instance to read
+     * memory from.
+     */
+    const guestMemory = () => {
+        const memory = instanceRef?.exports.memory;
+        return memory instanceof WebAssembly.Memory ? memory : null;
+    };
     const imports = {
         env: {
             // Mirrors the proxy's host import set (packages/proxy/src/wasm/host.rs)
             // — a rule that links in the proxy must link here too, or install
             // validation would reject rules the sandbox runs fine (and vice versa).
             log_info(message, len) {
-                if (instanceRef && message) {
-                    const memory = instanceRef.exports.memory;
-                    const bytes = new Uint8Array(memory.buffer, message, len);
-                    console.log(`[WASM Log] ${Buffer.from(bytes).toString('utf-8')}`);
-                }
+                const memory = guestMemory();
+                if (!memory || !message)
+                    return;
+                const text = readGuestUtf8(memory, message, len);
+                console.log(text === null
+                    ? `[WASM Log] <out of bounds: ptr=${message} len=${len}>`
+                    : `[WASM Log] ${text}`);
             },
+            // `fileName` is part of AssemblyScript's fixed abort ABI and deliberately
+            // unused: it points at the source path, which is only populated under
+            // --debug and is a bare pointer otherwise. Not renamed to `_fileName`
+            // because it is a real parameter of a foreign ABI and the name documents
+            // the slot; `args: 'after-used'` means an unused parameter before two used
+            // ones is not reported anyway.
             abort(message, fileName, line, column) {
-                let errorMsg = 'AssemblyScript abort';
-                if (instanceRef && message) {
-                    const memory = instanceRef.exports.memory;
-                    const size = new Uint32Array(memory.buffer, message - 4, 1)[0];
-                    const memView16 = new Uint16Array(memory.buffer);
-                    const chars = [];
-                    for (let i = 0; i < size / 2; i++) {
-                        chars.push(String.fromCharCode(memView16[(message / 2) + i]));
-                    }
-                    errorMsg = chars.join('');
-                }
-                throw new Error(`WASM Abort: ${errorMsg} (at line ${line}, col ${column})`);
+                const memory = guestMemory();
+                const text = memory && message ? readGuestString(memory, message) : null;
+                throw new Error(`WASM Abort: ${text ?? 'AssemblyScript abort'} (at line ${line}, col ${column})`);
             },
-            trace(message, n) {
-                if (instanceRef && message) {
-                    const memory = instanceRef.exports.memory;
-                    const size = new Uint32Array(memory.buffer, message - 4, 1)[0];
-                    const memView16 = new Uint16Array(memory.buffer);
-                    const chars = [];
-                    for (let i = 0; i < size / 2; i++) {
-                        chars.push(String.fromCharCode(memView16[(message / 2) + i]));
-                    }
-                    console.log(`[WASM Trace] ${chars.join('')}`);
+            /**
+             * AssemblyScript's `trace(message, n, a0..a4)`: `n` says how many of the
+             * five f64 slots carry a value.
+             *
+             * The five slots were absent from this signature and `n` was accepted and
+             * dropped, so a rule calling `trace("tokens left", 1, remaining)` printed
+             * "tokens left" here and nothing else — the number the author was tracing
+             * never reached the output of the command whose whole job is to show them
+             * what their rule does. The proxy at least logs `n`
+             * (`packages/proxy/src/wasm/host.rs`).
+             */
+            trace(message, n, a0, a1, a2, a3, a4) {
+                const memory = guestMemory();
+                const text = memory && message ? readGuestString(memory, message) : null;
+                // A module may declare a narrower `env.trace`, in which case JS passes
+                // undefined for the slots it did not declare; drop anything non-finite.
+                const count = Number.isInteger(n) ? Math.min(Math.max(n, 0), 5) : 0;
+                const values = [a0, a1, a2, a3, a4].slice(0, count).filter((v) => Number.isFinite(v));
+                const suffix = values.length > 0 ? ` ${values.join(' ')}` : '';
+                if (text === null) {
+                    console.log(`[WASM Trace Pointer] ${message} (n=${n})${suffix}`);
                 }
                 else {
-                    console.log(`[WASM Trace Pointer] ${message}`);
+                    console.log(`[WASM Trace] ${text}${suffix}`);
                 }
             },
-            seed() {
-                return Math.random();
-            }
+            /**
+             * `env.read_referenced_file(pathPtr, pathLen, outPtr, outCap) -> i32`
+             *
+             * Always refuses here, and that is the honest answer rather than a gap:
+             * the proxy builds its readable-file table from the tool calls of a live
+             * request, and `intutic policy test` has a mock context, not a request.
+             * Pretending otherwise — serving the mock's paths off the developer's own
+             * disk — would make this harness disagree with production in the
+             * permissive direction, which is the failure the `runOnnxInference` mock
+             * below was removed for.
+             *
+             * -2 is ERR_REFUSED from `packages/proxy/src/wasm/referenced_files.rs`.
+             * A rule exercised here therefore takes its no-manifest-available branch,
+             * which is the branch worth checking anyway: it is what runs in any
+             * deployment that has not configured a manifest root.
+             */
+            read_referenced_file(_pathPtr, _pathLen, _outPtr, _outCap) {
+                return -2;
+            },
+            // `seed()` used to be here, and the comment above — asserting this set
+            // mirrors the proxy's — was false two lines later. `host.rs` has never
+            // registered it. AssemblyScript emits `env.seed` for anything reaching
+            // `Math.random()`, so a rule using randomness validated here, installed,
+            // and then failed to link in the proxy on every request, where fail-open
+            // turned it into a silent allow. Removing it cannot make enforcement
+            // worse: such a rule was already fully bypassed, and now it is refused
+            // loudly at install instead of quietly at runtime.
+            //
+            // Not added to the proxy instead, deliberately: a governance verdict that
+            // samples is not a verdict. The same request would get different answers.
         },
-        onnx_rules: {
-            runOnnxInference(modelNamePtr, inputDataPtr) {
-                if (instanceRef && opts.forceAnomaly) {
-                    const memory = instanceRef.exports.memory;
-                    // TypedArray layout in AssemblyScript: buffer at offset 0, dataStart at offset 4
-                    const dataStart = new Uint32Array(memory.buffer, inputDataPtr + 4, 1)[0];
-                    // Mutate the backing buffer floats to trigger MSE reconstruction error
-                    const floats = new Float32Array(memory.buffer, dataStart, 180);
-                    for (let i = 0; i < floats.length; i++) {
-                        floats[i] = 99.0; // force large difference from one-hot 0.0/1.0
-                    }
-                }
-                return inputDataPtr;
-            }
-        }
+        // The `onnx_rules.runOnnxInference` mock lived here and is gone with the host
+        // import it imitated.
+        //
+        // It was worse than the production stub it stood for. The proxy's version returned
+        // the input pointer unchanged, so the rule it backed could never fire; this one,
+        // under --force-anomaly, rewrote the input buffer to 99.0 so the reconstruction
+        // error was enormous and the rule DID fire. A rule author could watch their
+        // sequence-anomaly rule block a request in `policy test`, ship it, and have it
+        // never block anything in production. A harness that disagrees with production in
+        // the permissive direction is worse than no harness.
     };
-    const { instance } = (await WebAssembly.instantiate(wasmBuffer, imports));
+    // `Uint8Array` means `Uint8Array<ArrayBufferLike>`, and `BufferSource` demands
+    // `ArrayBufferView<ArrayBuffer>` — a view over a SharedArrayBuffer is not one,
+    // so the parameter type callers actually use (`Buffer` from `fs.readFile`) does
+    // not fit `WebAssembly.instantiate`. The old `as any` on the result hid that
+    // mismatch by silently selecting the `Module` overload instead, which returns a
+    // bare `Instance` with no `.instance` property: the destructuring below was
+    // reading a field the declared type does not have. Copy into a plainly-backed
+    // array rather than narrowing the parameter, which would reject `Buffer`. One
+    // copy of a rule binary, once per validation.
+    // Compile first and inspect the import section, so an unprovided import is
+    // named rather than surfacing as V8's "Import #3 module=env function=seed
+    // error: function import requires a callable". Same outcome either way — the
+    // instantiate below would throw — but a rule author needs to know it was
+    // `Math.random()`.
+    const compiled = await WebAssembly.compile(new Uint8Array(wasmBuffer));
+    const unsupported = unsupportedImports(compiled);
+    if (unsupported.length > 0) {
+        throw new Error(`rule imports ${unsupported.length} function(s) the proxy sandbox does not provide:\n` +
+            unsupported.map((n) => `    ${explainUnsupportedImport(n)}`).join('\n') +
+            `\n  Available: ${HOST_IMPORT_NAMES.map((n) => `env.${n}`).join(', ')}.`);
+    }
+    const instance = await WebAssembly.instantiate(compiled, imports);
     instanceRef = instance;
+    const abi = resolveGuestAbi(instance);
     const jsonBytes = Buffer.from(mockStr);
-    // Accept exactly the allocator exports the proxy runner accepts
-    // (packages/proxy/src/wasm/runner.rs: `allocate`, then `__new`) — anything
-    // looser would validate rules the proxy then silently fails open on.
-    let offset = 0;
-    if (typeof instance.exports.allocate === 'function') {
-        offset = instance.exports.allocate(jsonBytes.length);
-    }
-    else if (typeof instance.exports.__new === 'function') {
-        offset = instance.exports.__new(jsonBytes.length, 0);
-    }
-    else {
-        throw new Error("WASM module is missing 'allocate' or '__new' memory helpers.");
-    }
-    const memory = instance.exports.memory;
-    const memView = new Uint8Array(memory.buffer, offset, jsonBytes.length);
+    const offset = abi.allocate(jsonBytes.length);
+    // Re-read `abi.memory.buffer` here rather than caching a view: `allocate` can
+    // grow the memory, which detaches every ArrayBuffer taken before the call.
+    const memView = new Uint8Array(abi.memory.buffer, offset, jsonBytes.length);
     memView.set(jsonBytes);
-    const evaluate = instance.exports.evaluate;
-    if (typeof evaluate !== 'function') {
-        throw new Error("WASM module is missing 'evaluate' function export.");
-    }
-    return evaluate(offset, jsonBytes.length);
+    return abi.evaluate(offset, jsonBytes.length);
 }
 export async function runPolicyTest(opts) {
     log.header('Intutic — Test Local WASM Policy Rule');
     let wasmBuffer;
     let mockStr;
-    let forceAnomaly = false;
     try {
         wasmBuffer = await fs.readFile(opts.wasm);
     }
     catch (err) {
-        log.error(`Failed to read WASM file at "${opts.wasm}": ${err.message}`);
+        log.error(`Failed to read WASM file at "${opts.wasm}": ${errMessage(err)}`);
         process.exit(1);
     }
     try {
         mockStr = await fs.readFile(opts.mock, 'utf-8');
-        const parsed = JSON.parse(mockStr); // syntax check
-        if (parsed && parsed.mock_anomaly === true) {
-            forceAnomaly = true;
-        }
+        JSON.parse(mockStr); // syntax check
     }
     catch (err) {
-        log.error(`Failed to read or parse mock context JSON at "${opts.mock}": ${err.message}`);
+        log.error(`Failed to read or parse mock context JSON at "${opts.mock}": ${errMessage(err)}`);
         process.exit(1);
     }
     try {
-        const verdict = await instantiateAndEvaluate(wasmBuffer, mockStr, { forceAnomaly });
+        const verdict = await instantiateAndEvaluate(wasmBuffer, mockStr);
         log.info(`Dry-run evaluation executed successfully.`);
         log.field('WASM Verdict Code', String(verdict));
         if (verdict === 0) {
@@ -250,15 +473,23 @@ export async function runPolicyTest(opts) {
         else if (verdict === 1) {
             log.warn('Result: BLOCK / KILL');
         }
+        else if (verdict === 3) {
+            log.warn('Result: REASK — the agent is told why and may retry');
+        }
         else if (verdict === 2) {
-            log.warn('Result: REDACT / BLOCK');
+            log.warn('Result: BLOCK (deprecated code 2)');
+            log.info('  2 was specified as REDACT and never could be: a rule is not given');
+            log.info('  the request body, so there is nothing to redact. The proxy treats it');
+            log.info('  as a block. Return 1 to block, or 3 to reask.');
         }
         else {
-            log.error(`Result: Unknown verdict code ${verdict}`);
+            log.error(`Result: unmapped verdict code ${verdict}`);
+            log.info('  Valid codes are 0 (allow), 1 (block) and 3 (reask). The proxy allows');
+            log.info('  anything else, so a rule returning this enforces nothing.');
         }
     }
     catch (err) {
-        log.error(`Execution error during WASM policy test: ${err.message}`);
+        log.error(`Execution error during WASM policy test: ${errMessage(err)}`);
         process.exit(1);
     }
 }
@@ -312,10 +543,123 @@ export function buildCompileArgs(opts) {
     }
     return args;
 }
+/** Where a fetched candidate source is written: two directories below the project root, which is what its `../../assembly/index` import needs. */
+export function candidateSourcePath(candidateId) {
+    return path.join('generated', 'candidates', `${candidateId}.ts`);
+}
+export function candidateOutPath(candidateId) {
+    return path.join('build', `${candidateId}.wasm`);
+}
+export function sourceSha256Of(source) {
+    return createHash('sha256').update(source, 'utf8').digest('hex');
+}
+/**
+ * Fetch a candidate's source of record and check it against the hash the
+ * server states. A body that does not hash to its own `sourceSha256` is not
+ * compiled: `/bundle` would refuse the result anyway, and a mismatch here
+ * means something between the control plane and this process changed bytes.
+ */
+export async function fetchCandidateSource(client, candidateId) {
+    const { status, body } = await client.getWithStatus(`/api/v1/rule-candidates/${encodeURIComponent(candidateId)}/source`);
+    if (status === 404) {
+        log.error(`Rule candidate "${candidateId}" was not found in this workspace.`);
+        process.exit(1);
+    }
+    if (status === 409) {
+        log.error(`Refused: ${body.error ?? 'conflict'}${body.detail ? ` — ${body.detail}` : ''}`);
+        process.exit(1);
+    }
+    if (status !== 200 || typeof body.source !== 'string' || typeof body.sourceSha256 !== 'string') {
+        log.error(`Could not fetch the candidate's source (HTTP ${status}): ${body.error ?? 'unexpected response'}`);
+        process.exit(1);
+    }
+    const local = sourceSha256Of(body.source);
+    if (local !== body.sourceSha256.toLowerCase()) {
+        log.error(`The served source hashes to ${local}, not the ${body.sourceSha256} the server states; refusing to compile it.`);
+        process.exit(1);
+    }
+    return {
+        candidateId: body.candidateId ?? candidateId,
+        guardrailId: body.guardrailId ?? null,
+        status: body.status ?? 'unknown',
+        source: body.source,
+        sourceSha256: body.sourceSha256.toLowerCase(),
+    };
+}
+/**
+ * Upload a compiled bundle to its candidate together with the hash of the
+ * source it was compiled from, and print the gate results. The server
+ * recomputes the hash from the candidate row; a bundle built from anything
+ * else is refused before a gate runs.
+ */
+export async function uploadCandidateBundle(client, candidateId, wasmPath, sourceSha256) {
+    let bytes;
+    try {
+        bytes = await fs.readFile(wasmPath);
+    }
+    catch (err) {
+        log.error(`Failed to read the compiled bundle at "${wasmPath}": ${errMessage(err)}`);
+        process.exit(1);
+    }
+    const form = new FormData();
+    form.append('file', new Blob([new Uint8Array(bytes)], { type: 'application/wasm' }), path.basename(wasmPath));
+    form.append('source_sha256', sourceSha256);
+    const { status, body } = await client.postForm(`/api/v1/rule-candidates/${encodeURIComponent(candidateId)}/bundle`, form);
+    if (status === 404) {
+        log.error(`Rule candidate "${candidateId}" was not found in this workspace.`);
+        process.exit(1);
+    }
+    if (status === 400 || status === 409) {
+        log.error(`Refused: ${body.error ?? `HTTP ${status}`}${body.detail ? ` — ${body.detail}` : ''}`);
+        process.exit(1);
+    }
+    if (status !== 200 && status !== 201) {
+        log.error(`Upload failed (HTTP ${status}): ${body.error ?? 'unexpected response'}`);
+        process.exit(1);
+    }
+    for (const g of body.gates ?? [])
+        log.info(`  ${g.passed ? '✓' : '✗'} ${g.gate}: ${g.detail}`);
+    if (body.accepted) {
+        log.success(`Accepted: rule ${body.ruleId ?? '?'} is in ${body.mode ?? 'SHADOW'} for candidate ${candidateId}.`);
+        log.info('It reports without acting until a member promotes it on counted shadow evidence.');
+        return;
+    }
+    log.error('The bundle failed verification; the candidate is rejected with the gate named above.');
+    process.exit(1);
+}
 export async function runPolicyCompile(opts) {
     log.header('Intutic — Compile WASM Policy Rule');
-    const args = buildCompileArgs(opts);
-    const out = opts.out ?? 'build/rule.wasm';
+    let src = opts.src;
+    let out = opts.out ?? 'build/rule.wasm';
+    let candidate = null;
+    let client = null;
+    if (opts.candidate) {
+        if (opts.src) {
+            log.error('--candidate compiles the source of record; it cannot be combined with --src.');
+            process.exit(1);
+        }
+        try {
+            await fs.access(path.join('assembly', 'index.ts'));
+        }
+        catch {
+            log.error('Run this from a rule project with assembly/index.ts (the SDK layout): the generated source imports the SDK from two directories up.');
+            process.exit(1);
+        }
+        client = await getClient(opts.dev);
+        candidate = await fetchCandidateSource(client, opts.candidate);
+        src = candidateSourcePath(opts.candidate);
+        if (!opts.out)
+            out = candidateOutPath(opts.candidate);
+        await fs.mkdir(path.dirname(src), { recursive: true });
+        await fs.writeFile(src, candidate.source, 'utf8');
+        log.info(`Source of record for ${candidate.candidateId} (${candidate.status}) → ${src}`);
+        log.info(`source_sha256 ${candidate.sourceSha256}`);
+    }
+    else if (opts.upload) {
+        log.error('--upload needs --candidate: only a candidate has a source of record to upload against.');
+        process.exit(1);
+    }
+    const args = buildCompileArgs({ src, out, debug: opts.debug });
     try {
         await fs.mkdir(path.dirname(out), { recursive: true });
     }
@@ -333,8 +677,16 @@ export async function runPolicyCompile(opts) {
         log.info('  pnpm add -D assemblyscript assemblyscript-json');
         process.exit(1);
     }
-    log.success(`Compiled ${opts.src ?? 'assembly/index.ts'} → ${out}`);
-    log.info('Next: dry-run with `intutic policy test --wasm <out> --mock <mock.json>`');
+    log.success(`Compiled ${src ?? 'assembly/index.ts'} → ${out}`);
+    if (!candidate || !opts.candidate) {
+        log.info('Next: dry-run with `intutic policy test --wasm <out> --mock <mock.json>`');
+        return;
+    }
+    if (!opts.upload) {
+        log.info(`Next: intutic policy compile --candidate ${opts.candidate} --upload (or upload ${out} with source_sha256 ${candidate.sourceSha256})`);
+        return;
+    }
+    await uploadCandidateBundle(client, opts.candidate, out, candidate.sourceSha256);
 }
 export async function runPolicyInstall(opts) {
     log.header('Intutic — Install Local WASM Policy Rule');
@@ -343,16 +695,34 @@ export async function runPolicyInstall(opts) {
         wasmBuffer = await fs.readFile(opts.wasm);
     }
     catch (err) {
-        log.error(`Failed to read WASM file at "${opts.wasm}": ${err.message}`);
+        log.error(`Failed to read WASM file at "${opts.wasm}": ${errMessage(err)}`);
         process.exit(1);
     }
     // Refuse to install a rule that cannot instantiate or evaluate — a broken
     // rule enforces nothing (the proxy sandbox fails open).
     try {
-        await instantiateAndEvaluate(wasmBuffer, DEFAULT_ALLOW_MOCK);
+        const validationVerdict = await instantiateAndEvaluate(wasmBuffer, DEFAULT_ALLOW_MOCK);
+        // Refuse a code the proxy does not map. Everything outside {0,1,2,3} is
+        // allowed at runtime with a warning, so a rule inventing a rung installs
+        // clean and then enforces nothing — the same silent shape as a rule that
+        // cannot link. 2 is accepted here because already-installed rules use it,
+        // but it is deprecated and reported as such.
+        if (validationVerdict === 2) {
+            // Accepted, because refusing it would break reinstalling a rule that
+            // already shipped — but never silently. The guest never receives the
+            // request body, so redaction was never expressible, and the proxy maps 2
+            // to a block. An author who believes they are redacting is blocking.
+            log.warn('Rule returned verdict code 2 (REDACT), which is deprecated. The proxy treats it ' +
+                'as a block. Return 1 to block, or 3 to reask.');
+        }
+        if (![0, 1, 2, 3].includes(validationVerdict)) {
+            log.error(`Rule returned verdict code ${validationVerdict}, which the proxy does not map — ` +
+                'it would be allowed on every request. Valid codes: 0 allow, 1 block, 3 reask.');
+            process.exit(1);
+        }
     }
     catch (err) {
-        log.error(`Rule failed validation and was NOT installed: ${err.message}`);
+        log.error(`Rule failed validation and was NOT installed: ${errMessage(err)}`);
         process.exit(1);
     }
     const priority = parseInt(opts.priority ?? '100', 10);
@@ -369,7 +739,7 @@ export async function runPolicyInstall(opts) {
         await fs.writeFile(dest, wasmBuffer);
     }
     catch (err) {
-        log.error(`Failed to install rule to "${dest}": ${err.message}`);
+        log.error(`Failed to install rule to "${dest}": ${errMessage(err)}`);
         process.exit(1);
     }
     const sha256 = createHash('sha256').update(wasmBuffer).digest('hex');
@@ -380,6 +750,77 @@ export async function runPolicyInstall(opts) {
     log.info('The proxy picks up local rule changes within ~5 s on the next request.');
     log.info('If your proxy config.yaml sets intutic_settings.wasm_local_dir, make sure it matches this path (or set INTUTIC_WASM_DIR for both).');
 }
+const VERDICT_NAMES = {
+    '0': 'allow',
+    '1': 'block',
+    '2': 'block (deprecated code 2)',
+    '3': 'reask',
+};
+/**
+ * `intutic policy replay <ruleId>` — "prove before enforce": run an installed
+ * or not-yet-active rule against a sample of this workspace's own recent
+ * traffic and report what it would have done, without touching enforcement.
+ *
+ * Uses `postWithStatus` rather than `post`: the 422 the route returns for too
+ * little sampled traffic is an answer this command exists to report, not a
+ * request failure to throw past.
+ */
+export async function runPolicyReplay(ruleId, opts) {
+    log.header(`Intutic — Replay Policy Rule: ${ruleId}`);
+    const client = await getClient(opts.dev);
+    const body = {};
+    if (opts.limit !== undefined) {
+        const limit = parseInt(opts.limit, 10);
+        if (isNaN(limit) || limit <= 0) {
+            log.error(`Invalid --limit "${opts.limit}". Must be a positive integer.`);
+            process.exit(1);
+        }
+        body.limit = limit;
+    }
+    if (opts.since !== undefined) {
+        body.since = opts.since;
+    }
+    try {
+        const { status, body: result } = await client.postWithStatus(`/api/v1/wasm-rules/${ruleId}/replay`, body);
+        if (status === 404) {
+            log.error(`Rule "${ruleId}" not found in this workspace.`);
+            process.exit(1);
+        }
+        if (status === 422) {
+            const err = result;
+            if (err.error === 'not_enough_traffic') {
+                log.warn('Not enough sampled traffic to estimate a would-act rate.');
+                log.field('Sampled contexts', String(err.contextCount ?? 0));
+                log.field('Required', String(err.minRequired ?? 0));
+                log.info('Contexts are sampled at WASM_CONTEXT_SNAPSHOT_RATE (default 5%) as traffic flows ' +
+                    'through the proxy — this grows with time and traffic, not with --limit.');
+            }
+            else {
+                log.error(`Replay could not evaluate the rule: ${err.message ?? err.error}`);
+            }
+            process.exit(1);
+        }
+        if (status !== 200) {
+            log.error(`Replay failed (${status}): ${JSON.stringify(result)}`);
+            process.exit(1);
+        }
+        const summary = result;
+        log.success(`Replayed against ${summary.contextCount} sampled context(s).`);
+        log.field('Since', summary.since ?? '(all sampled history)');
+        log.field('Would act (block/reask/other)', `${summary.wouldActCount} (${(summary.wouldActRate * 100).toFixed(1)}%)`);
+        for (const [code, count] of Object.entries(summary.verdictCounts)) {
+            log.field(`  verdict ${code} (${VERDICT_NAMES[code] ?? 'unmapped'})`, String(count));
+        }
+        if (summary.sampleMatches.length > 0) {
+            log.info(`First ${summary.sampleMatches.length} non-allow context(s):`);
+            console.log(JSON.stringify(summary.sampleMatches, null, 2));
+        }
+    }
+    catch (err) {
+        log.error(`Failed to replay rule: ${errMessage(err)}`);
+        process.exit(1);
+    }
+}
 export async function runPolicyListLocal() {
     log.header('Intutic — Local WASM Policy Rules');
     const dir = resolveLocalWasmDir();
@@ -405,7 +846,7 @@ export async function runPolicyListLocal() {
             log.field(name, `priority=${priority} size=${stat.size}B mtime=${stat.mtime.toISOString()} sha256=${sha256.slice(0, 16)}…`);
         }
         catch (err) {
-            log.warn(`${file}: unreadable (${err.message})`);
+            log.warn(`${file}: unreadable (${errMessage(err)})`);
         }
     }
 }