@visiq/core-wasm 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @visiq/core-wasm
+
+The VisIQ governance **evaluation core** (`experiments/matrix-v2/visiq-core-rs`, the ONE
+compiled Rust engine) exposed to JavaScript/TypeScript via WebAssembly — so the TS SDK
+evaluates through the **same core** the Go / Java / Ruby / Python bindings use, instead
+of a parallel TS implementation that can drift.
+
+```js
+const { evaluate } = require('@visiq/core-wasm');
+const decisionJson = evaluate(JSON.stringify(event), JSON.stringify(bundle));
+```
+
+- **Synchronous, no async init.** `--target nodejs` glue instantiates the wasm from bytes
+  at `require` time (`new WebAssembly.Module`/`Instance`) — a drop-in for a sync call.
+  (Node/server only; a browser build would need `--target web` + async init.)
+- **`evaluate(eventJson, bundleJson) → decisionJson`** is the language-neutral seam
+  (`evaluate_json` in the core). Fail-closed (G001) on malformed input — never throws.
+- **Faithful.** `node conformance.mjs` proves it reproduces the frozen golden corpus
+  (`sdk-corpus/GOLDEN-oracle-vectors.json`) — the same vectors every other binding
+  reproduces. **85/85, 0 diverge.**
+
+## Rebuild
+
+`./build.sh` (needs rustup + `wasm32-unknown-unknown` + `wasm-bindgen-cli` **=0.2.100**;
+the crate pins `wasm-bindgen = "=0.2.100"` so CLI/schema versions match).
+
+## Scope / what this is NOT
+
+This emits the **decision tuple** `{decision, allowed, action:{decision,argRedactionRules},
+retrieval:{action,redactionRules}}`. It does **not** emit rule attribution (`ruleCode`,
+`reason` prose, `decisionId`) — those are out-of-core (#25) and still computed in TS. A
+full `@visiq/harness` cutover to this core therefore needs the core extended to return
+matched-rule attribution; until then this package is the proven, corpus-gated binding.
+See `experiments/matrix-v2/visiq-core-rs/PARITY-GAPS.md`.

package/index.d.ts

@@ -0,0 +1,95 @@
+// Typed surface for @visiq/core-wasm — the ONE Rust governance core, bound to JS.
+// Decision/session shapes mirror @visiq/rego-evaluator + @visiq/runtime (kept in
+// lockstep by the whole-object differential corpus; see conformance.mjs).
+
+export interface CoreActionSub {
+  decision: 'permit' | 'deny' | 'approval_required' | 'mask' | null;
+  allowed: boolean;
+  argRedactionRules?: unknown[];
+  hitlFallback?: 'mask' | 'deny';
+}
+export interface CoreRetrievalSub {
+  action: 'allow' | 'deny' | 'redact' | 'escalate' | null;
+  redactionRules?: unknown[];
+  hitlFallback?: 'mask' | 'deny';
+}
+export interface CoreDecision {
+  decision: 'permit' | 'deny' | 'approval_required' | 'redact' | 'escalate' | 'mask';
+  allowed: boolean;
+  reason: string;
+  ruleId: string | null;
+  ruleCode: string | null;
+  enforced: boolean;
+  agentMode: 'enforce' | 'monitor' | 'off';
+  action: CoreActionSub;
+  retrieval: CoreRetrievalSub;
+  /** Per-op TELEMETRY would-be verdict — present ONLY when agent_mode_by_operation is set. */
+  wouldBe?: Omit<CoreDecision, 'wouldBe'>;
+}
+export interface CoreRawResult {
+  matched: boolean;
+  decision: string;
+  reason: string;
+  reasonCode: string | null;
+  ruleId: string | null;
+  ruleCode: string | null;
+  ruleDescription: string | null;
+  redactionRules: unknown[] | null;
+  hitlFallback: 'mask' | 'deny' | null;
+}
+export interface CoreHitlResolution {
+  decision: string;
+  redactionRules?: unknown[] | null;
+  maskedFallback: boolean;
+  reason?: string;
+}
+export interface CoreNoCoverage {
+  decision: 'permit' | 'deny' | 'approval_required';
+  rule_code: string;
+  reason: string;
+  hitlCategory: 'engineer' | 'enduser' | null;
+  autopilot: boolean;
+  enduserHitlBypassed: boolean;
+}
+export type SessionEvalState = Record<string, unknown>;
+
+export function evaluate(event: unknown, bundle: unknown): CoreDecision;
+export function evaluateUnifiedRulesRaw(
+  op: 'action' | 'retrieval' | 'delegation',
+  event: unknown,
+  bundle: unknown,
+): CoreRawResult;
+/**
+ * Evaluate a backend-shaped `UnifiedEvaluationInput` (facets/agent/session/
+ * operation/surface/query already marshalled) against `{ rules: rawRows[] }` —
+ * the Hono backend cutover seam. Returns the SAME `CoreRawResult` shape as
+ * `evaluateUnifiedRulesRaw`. Pass `now = Date.now()` for emergency-bypass expiry.
+ */
+export function evaluateUnifiedFromInput(
+  input: unknown,
+  bundle: unknown,
+  now?: number | null,
+): CoreRawResult;
+export function resolveHitlOutcome(
+  result: unknown,
+  state: 'approved' | 'rejected' | 'timeout' | 'pending',
+): CoreHitlResolution;
+export function resolveNoCoverage(args: {
+  action: string;
+  targetApp: string;
+  mode: 'enforce' | 'monitor' | 'off';
+  config: unknown;
+  agentNoCoverage?: 'open' | 'closed' | null;
+}): CoreNoCoverage;
+export function emptySessionState(): SessionEvalState;
+export function mergeSessionEvent(state: SessionEvalState, evidence: unknown): SessionEvalState;
+export function toSessionEvalState(raw: unknown): SessionEvalState;
+export function flattenEvent(event: unknown): Record<string, unknown>;
+export function expandFlatToNested(flat: unknown): Record<string, unknown>;
+export function applyMapping(event: unknown, mappings: unknown, derivations?: unknown): Record<string, unknown>;
+export function computeActionSchemaId(event: unknown, opts?: unknown): string;
+export function computeFingerprint(event: unknown): string;
+export function recursiveKeyPaths(event: unknown): string[];
+export function deriveDeclaredCore(samples: unknown[], opts?: unknown): { requiredPaths: string[]; optionalPaths: string[] };
+export function shouldMintNewVersion(prev: string[] | null | undefined, next: string[]): boolean;
+export function sanitizeAgentReason(reason: string | null | undefined): string;

package/index.js

@@ -0,0 +1,84 @@
+'use strict';
+// Typed wrappers over the ONE narrow WASM seam (`dispatch(op, payload_json)`), so
+// consumers get real signatures instead of hand-marshalling JSON. Everything is
+// synchronous (the wasm is instantiated at require-time in ./pkg/visiq_core.js).
+// Fail-closed: the core never throws; a malformed input yields a G001 deny / error.
+const core = require('./pkg/visiq_core.js');
+
+const call = (op, payload) => JSON.parse(core.dispatch(op, JSON.stringify(payload)));
+
+/** Evaluate an event against a bundle → the full UnifiedDecision. */
+function evaluate(event, bundle) {
+  return JSON.parse(core.evaluate(JSON.stringify(event), JSON.stringify(bundle)));
+}
+
+/** Raw single-facet UnifiedEvaluationResult (matched/reason/reasonCode/ruleId/
+ *  ruleCode/ruleDescription/redactionRules/hitlFallback) — for the backend. */
+function evaluateUnifiedRulesRaw(op, event, bundle) {
+  return call('evaluate_unified_rules_raw', { op, event, bundle });
+}
+
+/** Raw UnifiedEvaluationResult from a backend-shaped UnifiedEvaluationInput (the
+ *  Hono backend cutover seam — no event remarshalling; the SAME shape as
+ *  `evaluateUnifiedRulesRaw`). `bundle` = { rules: rawRows[] }. Pass `now =
+ *  Date.now()` so emergency-bypass expiry resolves against the caller's clock. */
+function evaluateUnifiedFromInput(input, bundle, now) {
+  return call('evaluate_unified_from_input', { input, bundle, now: now ?? null });
+}
+
+/** Resolve a HITL result given the human-review state → terminal outcome. */
+function resolveHitlOutcome(result, state) {
+  return call('resolve_hitl_outcome', { result, state });
+}
+
+/** Full NoCoverageDecision for an uncovered action. */
+function resolveNoCoverage(args) {
+  return call('resolve_no_coverage', args);
+}
+
+/** The empty session-trajectory state of a fresh session. */
+function emptySessionState() {
+  return call('empty_session_state', {});
+}
+
+/** Fold one event's evidence into the accumulated session state (pure). */
+function mergeSessionEvent(state, evidence) {
+  return call('merge_session_event', { state, evidence });
+}
+
+/** Defensive hydration of a persisted/untrusted session row. */
+function toSessionEvalState(raw) {
+  return call('to_session_eval_state', { raw });
+}
+
+// ── identity / normalization (server-side) ──
+const flattenEvent = (event) => call('flatten_event', { event });
+const expandFlatToNested = (flat) => call('expand_flat_to_nested', { flat });
+const applyMapping = (event, mappings, derivations) =>
+  call('apply_mapping', { event, mappings, derivations: derivations ?? null });
+const computeActionSchemaId = (event, opts) => call('compute_action_schema_id', { event, opts: opts ?? {} });
+const computeFingerprint = (event) => call('compute_fingerprint', { event });
+const recursiveKeyPaths = (event) => call('recursive_key_paths', { event });
+const deriveDeclaredCore = (samples, opts) => call('derive_declared_core', { samples, opts: opts ?? {} });
+const shouldMintNewVersion = (prev, next) => call('should_mint_new_version', { prev: prev ?? null, next });
+const sanitizeAgentReason = (reason) => call('sanitize_agent_reason', { reason });
+
+module.exports = {
+  evaluate,
+  evaluateUnifiedRulesRaw,
+  evaluateUnifiedFromInput,
+  resolveHitlOutcome,
+  resolveNoCoverage,
+  emptySessionState,
+  mergeSessionEvent,
+  toSessionEvalState,
+  flattenEvent,
+  expandFlatToNested,
+  applyMapping,
+  computeActionSchemaId,
+  computeFingerprint,
+  recursiveKeyPaths,
+  deriveDeclaredCore,
+  shouldMintNewVersion,
+  sanitizeAgentReason,
+};

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@visiq/core-wasm",
+  "version": "0.1.0",
+  "description": "VisIQ governance core (visiq-core-rs) compiled to WASM — the ONE Rust evaluation core, bound to JS. Same core the Go/Java/Ruby/Python SDKs use. evaluate(eventJson, bundleJson) -> decisionJson.",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "pkg/visiq_core.js",
+    "pkg/visiq_core.d.ts",
+    "pkg/visiq_core_bg.wasm",
+    "pkg/visiq_core_bg.wasm.d.ts"
+  ],
+  "sideEffects": [
+    "pkg/visiq_core.js"
+  ]
+}

package/pkg/visiq_core.d.ts

@@ -0,0 +1,13 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * WASM binding for the granular `dispatch` seam.
+ */
+export function dispatch(op: string, payload_json: string): string;
+/**
+ * WASM binding (for `@visiq/core-wasm` → the TS SDK / harness). The SAME
+ * `evaluate_json` core, exposed to JS through wasm-bindgen so the TypeScript SDK
+ * evaluates through the ONE compiled core exactly like the Go/Java/Ruby bindings.
+ * `evaluate_json` is fail-closed (G001) on malformed input, so this never throws.
+ */
+export function evaluate(event_json: string, bundle_json: string): string;

package/pkg/visiq_core.js

@@ -0,0 +1,149 @@
+
+let imports = {};
+imports['__wbindgen_placeholder__'] = module.exports;
+let wasm;
+const { TextEncoder, TextDecoder } = require(`util`);
+
+let WASM_VECTOR_LEN = 0;
+
+let cachedUint8ArrayMemory0 = null;
+
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+let cachedTextEncoder = new TextEncoder('utf-8');
+
+const encodeString = (typeof cachedTextEncoder.encodeInto === 'function'
+    ? function (arg, view) {
+    return cachedTextEncoder.encodeInto(arg, view);
+}
+    : function (arg, view) {
+    const buf = cachedTextEncoder.encode(arg);
+    view.set(buf);
+    return {
+        read: arg.length,
+        written: buf.length
+    };
+});
+
+function passStringToWasm0(arg, malloc, realloc) {
+
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = encodeString(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+
+cachedTextDecoder.decode();
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+/**
+ * WASM binding for the granular `dispatch` seam.
+ * @param {string} op
+ * @param {string} payload_json
+ * @returns {string}
+ */
+module.exports.dispatch = function(op, payload_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(op, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(payload_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.dispatch(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+};
+
+/**
+ * WASM binding (for `@visiq/core-wasm` → the TS SDK / harness). The SAME
+ * `evaluate_json` core, exposed to JS through wasm-bindgen so the TypeScript SDK
+ * evaluates through the ONE compiled core exactly like the Go/Java/Ruby bindings.
+ * `evaluate_json` is fail-closed (G001) on malformed input, so this never throws.
+ * @param {string} event_json
+ * @param {string} bundle_json
+ * @returns {string}
+ */
+module.exports.evaluate = function(event_json, bundle_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(event_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(bundle_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.evaluate(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+};
+
+module.exports.__wbindgen_init_externref_table = function() {
+    const table = wasm.__wbindgen_export_0;
+    const offset = table.grow(4);
+    table.set(0, undefined);
+    table.set(offset + 0, undefined);
+    table.set(offset + 1, null);
+    table.set(offset + 2, true);
+    table.set(offset + 3, false);
+    ;
+};
+
+const path = require('path').join(__dirname, 'visiq_core_bg.wasm');
+const bytes = require('fs').readFileSync(path);
+
+const wasmModule = new WebAssembly.Module(bytes);
+const wasmInstance = new WebAssembly.Instance(wasmModule, imports);
+wasm = wasmInstance.exports;
+module.exports.__wasm = wasm;
+
+wasm.__wbindgen_start();
+

package/pkg/visiq_core_bg.wasm.d.ts

@@ -0,0 +1,12 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const dispatch: (a: number, b: number, c: number, d: number) => [number, number];
+export const evaluate: (a: number, b: number, c: number, d: number) => [number, number];
+export const visiq_evaluate: (a: number, b: number) => number;
+export const visiq_free: (a: number) => void;
+export const __wbindgen_export_0: WebAssembly.Table;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_start: () => void;