@kya-os/checkpoint-wasm-runtime 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,220 @@
 # @kya-os/checkpoint-wasm-runtime
 
+## 1.6.0 — 2026-05-26 — `./reporter` subpath
+
+**Minor release** — adds the detection reporter consumed by the
+engine-backed host wrappers in `@kya-os/checkpoint-express@1.4.0` and
+`@kya-os/checkpoint-nextjs@1.4.0`.
+
+### Added
+
+- **`./reporter` subpath** exports `makeDetectionReporter(config)` and
+  `buildLogDetectionPayload(result, ctx)`. The reporter is a
+  fire-and-forget POST to `${baseUrl}/api/v1/log-detection` (default
+  `https://kya.vouched.id`) with `Authorization: Bearer ${apiKey}`.
+  Maps the engine's `VerifyResult` into the dashboard's
+  `LogDetectionRequestSchema` (detection + context + source=middleware
+  - enforcement + engine). Errors are swallowed unless `debug: true`.
+- Runtime-agnostic (uses global `fetch` + `AbortController`); works
+  under Node 18+ and the Edge runtime without polyfills.
+
+### Why
+
+The two engine-backed host wrappers (`withCheckpoint` in express +
+nextjs) ran verification locally via WASM but had no path to ship the
+`VerifyResult` back to the dashboard. Customers installed the SDK,
+deployed, and the onboarding "Verify connection" check failed forever
+because the `detections` table never received a row. The reporter
+closes that loop without re-introducing the legacy gateway round-trip.
+
+## Unreleased — Phase-D.9b.1 — `initEngineEdge` switched to `--target bundler`
+
+**Production-incident hotfix (2026-05-24).** `initEngineEdge()` previously
+loaded the `wasm-pack --target web` artifact, which falls back to
+`new URL('<wasm>', import.meta.url)` when no `moduleOrPath` is passed.
+Cloudflare Workers don't materialise `import.meta.url` the way browsers do,
+so the URL construction threw `TypeError: Invalid URL string` at engine
+init — taking down the post-D.9b production gateway deploy twice in ~1h
+(rolled back via `wrangler rollback` both times; captured in dev tail
+run 26352287112).
+
+Fix: switch `engine/edge.ts` to import the `--target bundler` artifact
+(`@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-bundler/kya_os_engine.js`).
+The bundler target embeds the WASM inline via the host bundler's `.wasm`
+import mechanism + initialises synchronously on module load. No URL
+construction, no `import.meta.url` dependency, no `default()` init call.
+
+### Behaviour change (no API surface change)
+
+- `moduleOrPath` parameter is now reserved/ignored. The bundler target
+  loads the WASM at module-load time via the host bundler, so the
+  caller has no opportunity to inject a pre-fetched `WebAssembly.Module`.
+  Parameter retained in the signature for type-compat; the value is
+  intentionally unused.
+- The `engine-edge.smoke.test.ts` "failed init recovery" regression
+  test was skipped (with a TODO for re-expressing the rejection-
+  caching guard via a dynamic-import mock) since the bundler target
+  can't be made to fail on caller input. The cache-clearing logic in
+  `ensureReady` is unchanged + still protects the same shape for OTHER
+  failure modes (e.g., dynamic import errors).
+
+### Consumer compatibility
+
+All known `initEngineEdge` consumers run inside a bundler that supports
+`.wasm` imports — `@kya-os/gateway-worker` (wrangler), `@kya-os/checkpoint-
+nextjs/middleware-edge` (webpack), `@kya-os/checkpoint-wasm-runtime/src/
+engine/orchestrator/verify-request-edge` (consumed by both above). No
+browser-direct consumer exists, so switching off the web target is safe.
+
+### Version
+
+Workspace-internal change; npm publish deferred until the next
+coordinated cut. Workspace consumers (gateway worker, checkpoint-nextjs)
+pick up the fix immediately via `pnpm` symlinks.
+
+## Unreleased — Phase-D.9b — engine-only publish path
+
+Internal-only change (no consumer-visible API removal). The
+`rust/crates/agentshield-wasm` Rust crate was deleted as part of
+Phase-D.9b after the Cloudflare gateway worker migrated onto
+`./orchestrator/edge`. Build/publish plumbing follows:
+
+- **Removed `copy-wasm` script** from `package.json`. The
+  `prepublishOnly` chain no longer copies the legacy
+  `agentshield_wasm_bg.wasm` artifact from the now-deleted crate —
+  publishing 1.4.4 against this tree would have failed at that step.
+- **Removed `./wasm/agentshield_wasm_bg.wasm` subpath export.** The
+  legacy artifact is no longer shipped with the npm package.
+- **Removed `wasm/agentshield_wasm*` files** from the package's `wasm/`
+  directory. Only the three `kya-os-engine*` artifact directories
+  (Node, web, bundler targets) remain.
+
+### Orchestrator legacy header parser — compact-JWS shape accepted
+
+`tryBuildMcpIFromLegacyHeader` (`engine/orchestrator/build-agent-request.ts`)
+now accepts **two** wire shapes in the `KYA-Delegation` header when
+`legacyEnvelopeFallback: true`:
+
+1. JSON envelope `{"protected":"…","payload":"…","signature":"…"}`
+   (the pre-Envelope-1 TS bouncer form). Unchanged behavior.
+2. Compact JWS `<protected>.<payload>.<signature>` (the form
+   consumed by the legacy `agentshield-wasm` `verify_mcp_i_proof`
+   function on the gateway worker). New in this release.
+
+Why: the gateway-worker cutover in Phase-D.9b moves MCP-I parsing
+from `verify_mcp_i_proof` (compact-JWS only) onto the orchestrator
+(JSON-envelope only pre-this-release). Third-party agents or custom
+integrations shipping compact JWS in the header would have silently
+fallen through to PlainHttp post-cutover; this extension preserves
+the parse path so they keep producing `McpI` agent requests.
+
+JSON parse runs first because a compact JWS is never valid JSON.
+A JSON object that's not envelope-shaped does NOT fall through to
+the compact-JWS branch — it's unambiguously a malformed envelope
+attempt, returns null. Coverage: 4 new fixtures in
+`build-agent-request.test.ts` (19/19 pass).
+
+The package's runtime API surface is unchanged. The legacy
+`./edge` entry (`StaticWasmLoader`, `WasmDetector`,
+`src/wasm-bindgen/agentshield_wasm.{js,d.ts}`) is still present in
+source — its upstream consumers (`@kya-os/checkpoint-nextjs/edge`,
+`@kya-os/checkpoint/wasm/loader-factory`) are throw-stubbed at the
+public API layer, so the legacy WASM glue never executes at runtime.
+A future cleanup will delete those source files; this release just
+unblocks deleting the underlying Rust crate.
+
+Phase-D.9b PR adds a structural deletion gate
+(`packages/checkpoint-nextjs/src/__tests__/d9b-deletion-gate.test.ts`)
+that re-asserts these conditions on every test run.
+
+## 1.5.1 — 2026-05-20
+
+**Tier 1 verification is now observable from the wire.** Closes the
+diagnostic gap Bench-Detection-Delta V3 (2026-05-20) surfaced: although
+Tier 1 RFC 9421 cryptographic verification was engaging correctly in
+1.5.0, the response headers only exposed `Decision`-level info — operators
+couldn't tell whether the engine had verified the request OR what tier
+fired. Required a bench-side `onResult` callback to see
+`detectionDetail.metadata.verified_*`. This patch surfaces the same
+information on the wire.
+
+Patch bump (not minor) because both changes are additive observability
+improvements — no public API surface change, no behavior change for any
+existing consumer:
+
+| Change                                                                                                 | Type     | Consumer impact                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `X-Checkpoint-Verified-Tier` / `-Vendor` / `-Protocol` response headers                                | Additive | New headers only emitted when `detectionDetail.metadata.verified_*` populated. No existing consumer parsed these (they didn't exist).                                                                                                                                                                                  |
+| `ruleset_hash` `t1:` slot now populates with vendor-keys SHA-256 (`t1:<64-hex>` instead of `t1:unset`) | Additive | The structured format documented `unset` / `disabled` / `<64-hex>` as valid slot values per [[Engine-Tier-Ruleset-Hash-1]]. Operators pinning on the literal `t1:unset` string would see breakage — but doing so was always against the documented contract (the slot was documented as a placeholder pending wiring). |
+
+### Added
+
+- **`X-Checkpoint-Verified-Tier` response header.** Emitted when
+  `detectionDetail.metadata.verified_tier` is a finite number or non-empty
+  string. Value is the stringified tier (`"1"` for Tier 1 RFC 9421 today;
+  `"2"` reserved for Tier 2 IP+UA cross-match attribution when that path
+  populates `verified_*`).
+- **`X-Checkpoint-Verified-Vendor` response header.** Emitted when
+  `detectionDetail.metadata.verified_vendor` is a non-empty string.
+  Today: `openai` (the only Tier 1 vendor with a bundled JWK). Future
+  Anthropic / Google RFC 9421 signers will add `anthropic` / `google`
+  values without a SemVer event.
+- **`X-Checkpoint-Verified-Protocol` response header.** Emitted when
+  `detectionDetail.metadata.verified_protocol` is a non-empty string.
+  Today: `rfc9421` (HTTP Message Signatures). Future MCP-I JWS envelope
+  verifications will emit `mcp-i` / `did-jws`.
+- **`X-Checkpoint-Ruleset-Hash`'s `t1:` slot now populates.** Computed
+  at engine build time as SHA-256 of the canonical concat of every
+  `data/vendor-keys/*.json` file (sorted by filename, `\n--\n`
+  separator). Build-time panic gate on empty dir / empty file prevents
+  shipping a misleading empty-input hash (mirrors Tier 2/3 discipline).
+  The `cargo:rustc-env=KYA_OS_ENGINE_TIER1_KEYS_SHA256` producer in
+  `kya-os-engine/build.rs` is the single source of truth; `api.rs`
+  consumes via `env!()`.
+
+### Defensive guards (PR #2718 reviewer feedback)
+
+- `X-Checkpoint-Verified-Tier` number path uses `Number.isFinite` to
+  reject `NaN` / `±Infinity` (`typeof NaN === 'number'` is true in JS,
+  so a plain typeof check would emit `Verified-Tier: NaN`).
+- `X-Checkpoint-Verified-Tier` string path requires `length > 0`
+  (mirrors `Verified-Vendor` / `Verified-Protocol` defensive guards).
+
+### Tests
+
+- New Rust drift gate `ruleset_hash_tier1_slot_resolves_to_vendor_keys_sha`
+  re-reads `data/vendor-keys/*.json` at test time + asserts the `t1:`
+  slot matches the computed SHA. Mirrors the existing Tier 2 YAML drift
+  gate. 96/96 lib tests pass.
+- 6 new vitest cases on `render-decision.test.ts` cover the
+  `Verified-*` header emission (presence, absence, partial metadata,
+  Block-path co-emission, observe-mode co-emission, empty-string +
+  NaN + ±Infinity defensive guards, number-vs-string acceptance).
+  26/26 render-decision tests pass.
+
+### What this DOESN'T change
+
+- Engine verify-dispatch behavior — unchanged. Tier 1 was already
+  engaging in 1.5.0; this release only makes that visible.
+- Public API surface — unchanged. No new exports, no new types, no
+  removed exports.
+- Existing response headers — unchanged. `X-Checkpoint-Decision`,
+  `-Reason`, `-Engine`, `-Engine-Version` emit exactly as before.
+- Ruleset-hash format — unchanged. The structured-prefix format
+  pinned by `ruleset_hash_matches_structured_per_tier_format` still
+  matches `sha256:t1:<slot>:t2:<slot>:t3:<slot>:t4:<slot>` where
+  each slot is one of `unset`/`disabled`/`[0-9a-f]{64}`. Only the
+  `t1:` slot's runtime value changed from `unset` to `<64-hex>`.
+
+### Pin guidance
+
+- Customers pinning `^1.5.0` (caret) → auto-pick up 1.5.1 on next
+  install. No action needed.
+- Customers pinning `~1.5.0` (tilde) → auto-pick up 1.5.1 on next
+  install. No action needed.
+- Customers pinning `1.5.0` (exact) → no auto-pickup. Bump to
+  `^1.5.1` to see Tier 1 attribution on the wire.
+
 ## 1.5.0 — 2026-05-19
 
 **Formal announcement of HTTP-Sig-Verifier-1 — Tier 1 RFC 9421 HTTP

package/dist/engine-edge.d.mts

@@ -11,11 +11,44 @@ export { DetectionDetail, McpIPayload } from '@kya-os/checkpoint-shared';
  * no sync wasm load).
  *
  * This module loads the `wasm-pack --target web` artifact via the
- * async `__wbg_init` default export, then exposes the same typed
- * `engineVerifyEdge(input, ctx) → Promise<VerifyResult>` shape with
- * a small lazy-init wrapper. First call awaits initialisation;
- * subsequent calls resolve synchronously on the JS side (the
- * underlying wasm `verify` is sync).
+ * async `__wbg_init` default export. The web target's `init()`
+ * accepts a pre-instantiated `WebAssembly.Module` argument — the
+ * canonical Cloudflare-Workers + wasm-bindgen pattern.
+ *
+ * # Why the caller MUST pass `wasmModule` on Cloudflare Workers
+ *
+ * Both `--target web` (URL fetch) and `--target bundler` (auto-
+ * instantiated `__wbg_set_wasm(wasm)`) have failure modes on wrangler:
+ *
+ *   - `--target web` falls back to `new URL('<wasm>', import.meta.url)`
+ *     when `init()` is called with no arg. Cloudflare Workers don't
+ *     materialise `import.meta.url` the way browsers do → throws
+ *     `TypeError: Invalid URL string`. (Broke production 2026-05-23,
+ *     captured via dev tail in run 26352287112.)
+ *
+ *   - `--target bundler` expects the host bundler to AUTO-INSTANTIATE
+ *     `import * as wasm from './foo.wasm'` so `wasm` is the
+ *     `Instance.exports` object. Webpack does this. **Wrangler does
+ *     NOT** — wrangler gives you a raw `WebAssembly.Module`, and the
+ *     bundler-target shim's `__wbg_set_wasm(rawModule)` happily
+ *     accepts it, then every export lookup (`wasm.__wbindgen_add_
+ *     to_stack_pointer`, etc.) returns undefined → throws
+ *     `TypeError: wasm.__wbindgen_add_to_stack_pointer is not a function`.
+ *     (Broke production 2026-05-24 after switching to bundler target
+ *     in PR #2785; captured via prod tail.)
+ *
+ * The fix is the standard Cloudflare-Workers + wasm-bindgen pattern:
+ * the consumer statically imports the `.wasm` file (wrangler then
+ * bundles it + hands the worker a `WebAssembly.Module`), then passes
+ * it to `init(wasmModule)`. The web target's init detects the Module
+ * input + calls `WebAssembly.instantiate(Module, imports)` internally
+ * to produce a real `Instance` whose exports populate the JS shim's
+ * `wasm` binding correctly.
+ *
+ * Vercel Edge / webpack consumers MAY omit the argument — webpack's
+ * async-WASM support handles the URL fetch correctly. But the typed
+ * signature here marks `wasmModule` optional for backward compat;
+ * Cloudflare-Workers consumers MUST pass it.
  *
  * **Why this matters for the consolidation narrative.** Phase A
  * shipped Node-only. Without an edge build, the first Vercel-edge
@@ -29,18 +62,21 @@ export { DetectionDetail, McpIPayload } from '@kya-os/checkpoint-shared';
 
 /**
  * Initialise the edge wasm module. Idempotent — subsequent calls
- * return the same in-flight or resolved promise. Host wrappers can
- * call this at startup to eagerly load the wasm and avoid first-
- * request latency, but it's not required: `engineVerifyEdge`
- * lazily initialises on first call.
- *
- * @param moduleOrPath  Optional pre-fetched `WebAssembly.Module` or
- *                      a URL / Request the wasm-bindgen loader will
- *                      fetch. Defaults to the bundled artifact via
- *                      `import.meta.url`. Cloudflare Workers / Vercel
- *                      Edge typically pass a pre-bundled `Module`.
+ * return the same in-flight or resolved promise. Host wrappers
+ * should call this once at startup with the `wasmModule` they
+ * statically imported from the package's `./wasm/kya-os-engine-web/`
+ * subpath (see CLAUDE.md for the wrangler/webpack import pattern).
+ *
+ * @param wasmModule  REQUIRED on Cloudflare Workers (wrangler hands
+ *                    the consumer a `WebAssembly.Module` from the
+ *                    static `.wasm` import; pass it here so the
+ *                    web-target's `init()` instantiates it). OPTIONAL
+ *                    on Vercel Edge / webpack — webpack's async-WASM
+ *                    support resolves the URL fetch correctly, but
+ *                    passing the module explicitly is recommended
+ *                    for cross-runtime consistency.
  */
-declare function initEngineEdge(moduleOrPath?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
+declare function initEngineEdge(wasmModule?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
 /**
  * Edge-runtime async equivalent of `engineVerify`.
  *

package/dist/engine-edge.d.ts

@@ -11,11 +11,44 @@ export { DetectionDetail, McpIPayload } from '@kya-os/checkpoint-shared';
  * no sync wasm load).
  *
  * This module loads the `wasm-pack --target web` artifact via the
- * async `__wbg_init` default export, then exposes the same typed
- * `engineVerifyEdge(input, ctx) → Promise<VerifyResult>` shape with
- * a small lazy-init wrapper. First call awaits initialisation;
- * subsequent calls resolve synchronously on the JS side (the
- * underlying wasm `verify` is sync).
+ * async `__wbg_init` default export. The web target's `init()`
+ * accepts a pre-instantiated `WebAssembly.Module` argument — the
+ * canonical Cloudflare-Workers + wasm-bindgen pattern.
+ *
+ * # Why the caller MUST pass `wasmModule` on Cloudflare Workers
+ *
+ * Both `--target web` (URL fetch) and `--target bundler` (auto-
+ * instantiated `__wbg_set_wasm(wasm)`) have failure modes on wrangler:
+ *
+ *   - `--target web` falls back to `new URL('<wasm>', import.meta.url)`
+ *     when `init()` is called with no arg. Cloudflare Workers don't
+ *     materialise `import.meta.url` the way browsers do → throws
+ *     `TypeError: Invalid URL string`. (Broke production 2026-05-23,
+ *     captured via dev tail in run 26352287112.)
+ *
+ *   - `--target bundler` expects the host bundler to AUTO-INSTANTIATE
+ *     `import * as wasm from './foo.wasm'` so `wasm` is the
+ *     `Instance.exports` object. Webpack does this. **Wrangler does
+ *     NOT** — wrangler gives you a raw `WebAssembly.Module`, and the
+ *     bundler-target shim's `__wbg_set_wasm(rawModule)` happily
+ *     accepts it, then every export lookup (`wasm.__wbindgen_add_
+ *     to_stack_pointer`, etc.) returns undefined → throws
+ *     `TypeError: wasm.__wbindgen_add_to_stack_pointer is not a function`.
+ *     (Broke production 2026-05-24 after switching to bundler target
+ *     in PR #2785; captured via prod tail.)
+ *
+ * The fix is the standard Cloudflare-Workers + wasm-bindgen pattern:
+ * the consumer statically imports the `.wasm` file (wrangler then
+ * bundles it + hands the worker a `WebAssembly.Module`), then passes
+ * it to `init(wasmModule)`. The web target's init detects the Module
+ * input + calls `WebAssembly.instantiate(Module, imports)` internally
+ * to produce a real `Instance` whose exports populate the JS shim's
+ * `wasm` binding correctly.
+ *
+ * Vercel Edge / webpack consumers MAY omit the argument — webpack's
+ * async-WASM support handles the URL fetch correctly. But the typed
+ * signature here marks `wasmModule` optional for backward compat;
+ * Cloudflare-Workers consumers MUST pass it.
  *
  * **Why this matters for the consolidation narrative.** Phase A
  * shipped Node-only. Without an edge build, the first Vercel-edge
@@ -29,18 +62,21 @@ export { DetectionDetail, McpIPayload } from '@kya-os/checkpoint-shared';
 
 /**
  * Initialise the edge wasm module. Idempotent — subsequent calls
- * return the same in-flight or resolved promise. Host wrappers can
- * call this at startup to eagerly load the wasm and avoid first-
- * request latency, but it's not required: `engineVerifyEdge`
- * lazily initialises on first call.
- *
- * @param moduleOrPath  Optional pre-fetched `WebAssembly.Module` or
- *                      a URL / Request the wasm-bindgen loader will
- *                      fetch. Defaults to the bundled artifact via
- *                      `import.meta.url`. Cloudflare Workers / Vercel
- *                      Edge typically pass a pre-bundled `Module`.
+ * return the same in-flight or resolved promise. Host wrappers
+ * should call this once at startup with the `wasmModule` they
+ * statically imported from the package's `./wasm/kya-os-engine-web/`
+ * subpath (see CLAUDE.md for the wrangler/webpack import pattern).
+ *
+ * @param wasmModule  REQUIRED on Cloudflare Workers (wrangler hands
+ *                    the consumer a `WebAssembly.Module` from the
+ *                    static `.wasm` import; pass it here so the
+ *                    web-target's `init()` instantiates it). OPTIONAL
+ *                    on Vercel Edge / webpack — webpack's async-WASM
+ *                    support resolves the URL fetch correctly, but
+ *                    passing the module explicitly is recommended
+ *                    for cross-runtime consistency.
  */
-declare function initEngineEdge(moduleOrPath?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
+declare function initEngineEdge(wasmModule?: WebAssembly.Module | URL | string | Request | BufferSource): Promise<void>;
 /**
  * Edge-runtime async equivalent of `engineVerify`.
  *

package/dist/engine-edge.js

@@ -2,20 +2,27 @@
 
 // src/engine/edge.ts
 var initialised = null;
-function initEngineEdge(moduleOrPath) {
-  return ensureReady(moduleOrPath).then(() => void 0);
+var providedModule;
+function initEngineEdge(wasmModule) {
+  if (wasmModule !== void 0 && providedModule === void 0) {
+    providedModule = wasmModule;
+  }
+  return ensureReady().then(() => void 0);
 }
-function ensureReady(moduleOrPath) {
+function ensureReady() {
   if (initialised) return initialised;
   const pending = (async () => {
     const mod = await import('@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-web/kya_os_engine.js');
-    await mod.default(moduleOrPath !== void 0 ? { module_or_path: moduleOrPath } : void 0);
+    await mod.default(
+      providedModule !== void 0 ? { module_or_path: providedModule } : void 0
+    );
     return mod.verify;
   })();
   initialised = pending;
   pending.catch(() => {
     if (initialised === pending) {
       initialised = null;
+      providedModule = void 0;
     }
   });
   return initialised;

package/dist/engine-edge.mjs

@@ -1,19 +1,26 @@
 // src/engine/edge.ts
 var initialised = null;
-function initEngineEdge(moduleOrPath) {
-  return ensureReady(moduleOrPath).then(() => void 0);
+var providedModule;
+function initEngineEdge(wasmModule) {
+  if (wasmModule !== void 0 && providedModule === void 0) {
+    providedModule = wasmModule;
+  }
+  return ensureReady().then(() => void 0);
 }
-function ensureReady(moduleOrPath) {
+function ensureReady() {
   if (initialised) return initialised;
   const pending = (async () => {
     const mod = await import('@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-web/kya_os_engine.js');
-    await mod.default(moduleOrPath !== void 0 ? { module_or_path: moduleOrPath } : void 0);
+    await mod.default(
+      providedModule !== void 0 ? { module_or_path: providedModule } : void 0
+    );
     return mod.verify;
   })();
   initialised = pending;
   pending.catch(() => {
     if (initialised === pending) {
       initialised = null;
+      providedModule = void 0;
     }
   });
   return initialised;

package/dist/index.d.mts

@@ -1,3 +1,7 @@
+import { D as Decision } from './types-C3RniIOM.mjs';
+export { B as BlockReason } from './types-C3RniIOM.mjs';
+import '@kya-os/checkpoint-shared';
+
 /**
  * AgentShield WASM Runtime Types
  *
@@ -598,6 +602,119 @@ declare class RulesDetector implements IDetector {
  */
 declare function createRulesDetector(): RulesDetector;
 
+/**
+ * Cedar policy-evaluator bridge — Node fallback.
+ *
+ * Surfaces the `PolicyEvaluator` class exported by the cedar-enabled
+ * `kya-os-engine` WASM artifact (built by
+ * `rust/scripts/build-engine-cedar-wasm.sh`, gated on the Rust
+ * `wasm,cedar` features). A JS host (the gateway) compiles a tenant
+ * policy bundle once and authorizes many requests against it in-process,
+ * with no round-trip to a separate policy service.
+ *
+ * The cedar artifact is a SEPARATE, larger binary than the lean
+ * detection artifact — it pulls in `cedar-policy`. Detection-only
+ * consumers load `./engine` (the lean `verify()` glue); only callers that
+ * need in-process authorization reach for this bridge.
+ *
+ * ## Lazy loading
+ *
+ * The cedar `--target nodejs` glue instantiates the ~2 MB cedar WASM the
+ * moment it is `require`d (it `fs.readFileSync`s its `.wasm` sibling at
+ * module load). To keep the separate-artifact promise — detection-only
+ * consumers must NOT pay cedar's memory/startup — the glue is loaded
+ * LAZILY: nothing happens on `import`; the artifact is `require`d (and
+ * memoised) only on the first {@link createPolicyEvaluator} call. This is
+ * also why cedar lives behind the dedicated `./policy` subpath and is NOT
+ * re-exported from the `./node` barrel.
+ *
+ * `createRequire(__filename)` resolves the glue at call time in both
+ * builds — native `require` under CJS, the tsup `shims` / `createRequire`
+ * banner under ESM. The glue stays external (regex
+ * `wasm/kya-os-engine-cedar/` in tsup's `commonOpts.external`), so its
+ * `__dirname` resolves against `node_modules/.../wasm/kya-os-engine-cedar/`
+ * where the `.wasm` lives, and `"type": "commonjs"` on the artifact's
+ * package.json keeps Node from throwing `ERR_REQUIRE_ESM`.
+ *
+ * Direct .wasm path (for callers building their own loaders):
+ *   `@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm`
+ */
+
+/**
+ * Owned, plain-data request the host hands to
+ * {@link PolicyEvaluatorRuntime.authorize}. Mirrors the Rust
+ * `AuthorizeInput` (`rust/crates/kya-os-engine/src/policy/authorize.rs`);
+ * keys are camelCase across the wasm-bindgen boundary, matching every
+ * other engine wire type.
+ *
+ * The evaluator is **synchronous over pre-resolved facts** (H-1 Kickoff
+ * § 4.5): the host pre-fetches the agent's delegation chain, reputation,
+ * etc. and ships the results here — no JS callbacks cross the boundary.
+ *
+ * `agentDid` and `reputation` are optional (omit or pass `undefined` for
+ * an anonymous or reputation-less request); `grantedScopes` defaults to an
+ * empty list when omitted.
+ */
+interface AuthorizeInput {
+    /** Agent DID if identity has been established, otherwise omitted. */
+    agentDid?: string;
+    /** The action being requested (e.g., `"book_flight"`). */
+    action: string;
+    /** The resource being acted on (e.g., `"travel_api"`). */
+    resource: string;
+    /** Scopes granted by the agent's delegation chain. Defaults to `[]`. */
+    grantedScopes?: string[];
+    /** Agent's reputation score in `[0.0, 1.0]`, if computed. */
+    reputation?: number;
+    /** Tenant identifier. */
+    tenantId: string;
+}
+/**
+ * Structural type of the WASM `PolicyEvaluator` class the cedar glue
+ * exports. Pinned here so this bridge type-checks against the artifact's
+ * `.d.ts` (`constructor(policy_text: string)`, `authorize(input): any`,
+ * `free()`).
+ */
+interface WasmPolicyEvaluator {
+    authorize(input: AuthorizeInput): unknown;
+    free(): void;
+}
+/**
+ * Host-facing wrapper around one compiled Cedar policy bundle.
+ *
+ * Construction compiles the bundle once; every {@link authorize} call
+ * evaluates a single owned request against it without re-parsing policy
+ * text (the compile-once / evaluate-many contract the engine upholds,
+ * carried across the boundary).
+ */
+declare class PolicyEvaluatorRuntime {
+    private readonly inner;
+    /**
+     * @param inner - The compiled WASM `PolicyEvaluator` handle. Built in
+     *   {@link createPolicyEvaluator}; reused by every {@link authorize}
+     *   call for the lifetime of this wrapper.
+     */
+    constructor(inner: WasmPolicyEvaluator);
+    /**
+     * Authorize one owned request against the compiled policy bundle.
+     *
+     * The evaluator owns the fail-closed posture — a request it cannot
+     * marshal into Cedar, or one matching no `permit`, comes back as a
+     * {@link Decision} `Block` (not a thrown error). Authorization
+     * *verdicts* never throw; they surface inside the returned value.
+     *
+     * @throws {Error} only for boundary faults the WASM glue rejects: a
+     *   malformed `input` that fails `AuthorizeInput` deserialisation, or a
+     *   failure serialising the resulting `Decision`.
+     */
+    authorize(input: AuthorizeInput): Decision;
+    /**
+     * Release the compiled bundle's WASM memory. Call when the evaluator is
+     * no longer needed; after this the wrapper must not be reused.
+     */
+    free(): void;
+}
+
 /**
  * Create a detector with automatic runtime selection
  *
@@ -650,4 +767,4 @@ declare function createEdgeDetector(wasmModule: WebAssembly.Module, options?: ID
  */
 declare function createFallbackDetector(): IDetector;
 
-export { CONFIDENCE, type DetectionClass, DynamicWasmLoader, type ForgeabilityRisk, type ICustomerPolicy, type IDetectedAgent, type IDetectionInput, type IDetectionResult, type IDetector, type IDetectorOptions, type IPathRule, type IPolicyLoader, type IWasmBindings, type IWasmLoader, PolicyLoadError, PolicyLoader, type PolicyLoaderConfig, RulesDetector, StaticWasmLoader, type VerificationMethod, WasmDetector, createDetector, createDynamicLoader, createEdgeDetector, createFallbackDetector, createPolicyLoader, createRulesDetector, createStaticLoader };
+export { type AuthorizeInput, CONFIDENCE, Decision, type DetectionClass, DynamicWasmLoader, type ForgeabilityRisk, type ICustomerPolicy, type IDetectedAgent, type IDetectionInput, type IDetectionResult, type IDetector, type IDetectorOptions, type IPathRule, type IPolicyLoader, type IWasmBindings, type IWasmLoader, PolicyEvaluatorRuntime, PolicyLoadError, PolicyLoader, type PolicyLoaderConfig, RulesDetector, StaticWasmLoader, type VerificationMethod, WasmDetector, createDetector, createDynamicLoader, createEdgeDetector, createFallbackDetector, createPolicyLoader, createRulesDetector, createStaticLoader };