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

package/dist/reporter.d.mts

@@ -0,0 +1,102 @@
+import { V as VerifyResult, f as EngineInfo } from './types-C3RniIOM.mjs';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * Detection reporter — fire-and-forget POST to the dashboard's
+ * `/api/v1/log-detection` ingest endpoint.
+ *
+ * The engine-backed middlewares (`withCheckpoint` in `checkpoint-express`
+ * and `checkpoint-nextjs`) run verification locally via WASM. Without
+ * this reporter the verdict path works in-process but nothing flows
+ * back to the dashboard — the onboarding "Verify" check fails forever
+ * because the `detections` table never sees a row.
+ *
+ * Mirrors the contract of the legacy `CheckpointApiClient.logDetection`
+ * (see `checkpoint-nextjs/src/api-client.ts`) so the server-side
+ * ingest at `/api/v1/log-detection` accepts both paths identically.
+ *
+ * Subpath: `@kya-os/checkpoint-wasm-runtime/reporter`.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Request context the middleware extracts from its framework-native
+ * request object. Shape matches the `ContextSchema` accepted by
+ * `/api/v1/log-detection`.
+ */
+interface ReporterContext {
+    userAgent?: string;
+    ipAddress?: string;
+    path?: string;
+    url?: string;
+    method?: string;
+}
+/**
+ * Configuration for the detection reporter.
+ */
+interface DetectionReporterConfig {
+    /**
+     * Project API key. Resolved server-side at the ingest endpoint into
+     * the project association used to insert the detection row. Required.
+     */
+    apiKey: string;
+    /**
+     * Dashboard base URL. Defaults to `https://kya.vouched.id`. Override
+     * for staging environments or self-hosted dashboards.
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 5000ms. The POST
+     * is fire-and-forget — a timeout aborts the request but never blocks
+     * the verdict path.
+     */
+    timeoutMs?: number;
+    /**
+     * Emit `console.warn` on reporter failures. Defaults to `false` —
+     * fire-and-forget means silent by design. Enable during development
+     * to surface mis-configured `apiKey` / `baseUrl`.
+     */
+    debug?: boolean;
+}
+/**
+ * Self-catching reporter promise. Call after every `verifyRequest`
+ * decision. Callers that can extend request lifetime (for example,
+ * NextFetchEvent.waitUntil) should attach this promise; callers that
+ * cannot may still ignore it safely because errors are swallowed
+ * (unless `debug: true`).
+ */
+type DetectionReporter = (result: VerifyResult, ctx: ReporterContext) => Promise<void>;
+/**
+ * Build a fire-and-forget reporter bound to a single project API key.
+ *
+ * The returned function is safe to call from any verdict path — it
+ * never throws, never awaits the network round-trip, and never affects
+ * the response.
+ */
+declare function makeDetectionReporter(config: DetectionReporterConfig): DetectionReporter;
+/**
+ * Translate the engine's `VerifyResult` into the request body shape
+ * accepted by `/api/v1/log-detection`. Exported for tests + for
+ * advanced consumers wiring a custom transport.
+ */
+declare function buildLogDetectionPayload(result: VerifyResult, ctx: ReporterContext): {
+    detection: {
+        isAgent: boolean;
+        confidence: number;
+        agentName: string | undefined;
+        agentType: string | undefined;
+        detectionClass: string | undefined;
+        verificationMethod: "signature" | "pattern" | "behavioral" | "network" | "mcp_i_handshake" | "none" | "error" | undefined;
+        reasons: string[];
+    };
+    context: ReporterContext;
+    source: "middleware";
+    enforcement: {
+        action: string;
+        reason?: string;
+    };
+    engine: EngineInfo | undefined;
+};
+
+export { type DetectionReporter, type DetectionReporterConfig, type ReporterContext, buildLogDetectionPayload, makeDetectionReporter };

package/dist/reporter.d.ts

@@ -0,0 +1,102 @@
+import { V as VerifyResult, f as EngineInfo } from './types-C3RniIOM.js';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * Detection reporter — fire-and-forget POST to the dashboard's
+ * `/api/v1/log-detection` ingest endpoint.
+ *
+ * The engine-backed middlewares (`withCheckpoint` in `checkpoint-express`
+ * and `checkpoint-nextjs`) run verification locally via WASM. Without
+ * this reporter the verdict path works in-process but nothing flows
+ * back to the dashboard — the onboarding "Verify" check fails forever
+ * because the `detections` table never sees a row.
+ *
+ * Mirrors the contract of the legacy `CheckpointApiClient.logDetection`
+ * (see `checkpoint-nextjs/src/api-client.ts`) so the server-side
+ * ingest at `/api/v1/log-detection` accepts both paths identically.
+ *
+ * Subpath: `@kya-os/checkpoint-wasm-runtime/reporter`.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Request context the middleware extracts from its framework-native
+ * request object. Shape matches the `ContextSchema` accepted by
+ * `/api/v1/log-detection`.
+ */
+interface ReporterContext {
+    userAgent?: string;
+    ipAddress?: string;
+    path?: string;
+    url?: string;
+    method?: string;
+}
+/**
+ * Configuration for the detection reporter.
+ */
+interface DetectionReporterConfig {
+    /**
+     * Project API key. Resolved server-side at the ingest endpoint into
+     * the project association used to insert the detection row. Required.
+     */
+    apiKey: string;
+    /**
+     * Dashboard base URL. Defaults to `https://kya.vouched.id`. Override
+     * for staging environments or self-hosted dashboards.
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 5000ms. The POST
+     * is fire-and-forget — a timeout aborts the request but never blocks
+     * the verdict path.
+     */
+    timeoutMs?: number;
+    /**
+     * Emit `console.warn` on reporter failures. Defaults to `false` —
+     * fire-and-forget means silent by design. Enable during development
+     * to surface mis-configured `apiKey` / `baseUrl`.
+     */
+    debug?: boolean;
+}
+/**
+ * Self-catching reporter promise. Call after every `verifyRequest`
+ * decision. Callers that can extend request lifetime (for example,
+ * NextFetchEvent.waitUntil) should attach this promise; callers that
+ * cannot may still ignore it safely because errors are swallowed
+ * (unless `debug: true`).
+ */
+type DetectionReporter = (result: VerifyResult, ctx: ReporterContext) => Promise<void>;
+/**
+ * Build a fire-and-forget reporter bound to a single project API key.
+ *
+ * The returned function is safe to call from any verdict path — it
+ * never throws, never awaits the network round-trip, and never affects
+ * the response.
+ */
+declare function makeDetectionReporter(config: DetectionReporterConfig): DetectionReporter;
+/**
+ * Translate the engine's `VerifyResult` into the request body shape
+ * accepted by `/api/v1/log-detection`. Exported for tests + for
+ * advanced consumers wiring a custom transport.
+ */
+declare function buildLogDetectionPayload(result: VerifyResult, ctx: ReporterContext): {
+    detection: {
+        isAgent: boolean;
+        confidence: number;
+        agentName: string | undefined;
+        agentType: string | undefined;
+        detectionClass: string | undefined;
+        verificationMethod: "signature" | "pattern" | "behavioral" | "network" | "mcp_i_handshake" | "none" | "error" | undefined;
+        reasons: string[];
+    };
+    context: ReporterContext;
+    source: "middleware";
+    enforcement: {
+        action: string;
+        reason?: string;
+    };
+    engine: EngineInfo | undefined;
+};
+
+export { type DetectionReporter, type DetectionReporterConfig, type ReporterContext, buildLogDetectionPayload, makeDetectionReporter };

package/dist/reporter.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// src/reporter/index.ts
+var DEFAULT_BASE_URL = "https://kya.vouched.id";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var SINGLE_HASH_RULESET_REGEX = /^sha256:[a-f0-9]{64}$/;
+function makeDetectionReporter(config) {
+  if (!config.apiKey) {
+    throw new Error(
+      "makeDetectionReporter: `apiKey` is required. Without it the dashboard cannot associate detections with your project."
+    );
+  }
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const endpoint = `${baseUrl}/api/v1/log-detection`;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const debug = config.debug ?? false;
+  return function reportDetection(result, ctx) {
+    const payload = buildLogDetectionPayload(result, ctx);
+    if (debug && !payload.engine && result.engineInfo?.rulesetHash) {
+      console.warn(
+        `[checkpoint-reporter] dropping engine field \u2014 rulesetHash "${result.engineInfo.rulesetHash}" doesn't match dashboard schema /^sha256:[a-f0-9]{64}$/. Detection row will land with NULL engine_* columns.`
+      );
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+      keepalive: true
+    }).then((response) => {
+      if (!response.ok && debug) {
+        console.warn(
+          `[checkpoint-reporter] log-detection HTTP ${response.status} at ${endpoint}`
+        );
+      }
+    }).catch((err) => {
+      if (debug) {
+        console.warn("[checkpoint-reporter] log-detection failed:", err);
+      }
+    }).finally(() => clearTimeout(timeoutId));
+  };
+}
+function buildLogDetectionPayload(result, ctx) {
+  const detection = result.detectionDetail;
+  return {
+    detection: {
+      isAgent: detection.isAgent,
+      confidence: detection.confidence,
+      agentName: detection.detectedAgent?.name,
+      agentType: detection.detectedAgent?.type ?? detection.agentType,
+      detectionClass: stringifyDetectionClass(detection.detectionClass),
+      verificationMethod: detection.verificationMethod,
+      reasons: detection.reasons
+    },
+    context: ctx,
+    source: "middleware",
+    enforcement: extractEnforcement(result),
+    engine: sanitizeEngineInfo(result.engineInfo)
+  };
+}
+function sanitizeEngineInfo(engine) {
+  if (!engine) return void 0;
+  if (!SINGLE_HASH_RULESET_REGEX.test(engine.rulesetHash)) return void 0;
+  return engine;
+}
+var DETECTION_CLASS_WIRE = {
+  Human: "human",
+  AiAgent: "ai_agent",
+  Automation: "automation",
+  Bot: "bot",
+  IncompleteData: "incomplete_data",
+  Unknown: "unknown"
+};
+function stringifyDetectionClass(detectionClass) {
+  if (!detectionClass) return void 0;
+  if (typeof detectionClass === "string") {
+    return DETECTION_CLASS_WIRE[detectionClass] ?? detectionClass;
+  }
+  if (typeof detectionClass === "object" && "type" in detectionClass) {
+    const variant = String(detectionClass.type);
+    return DETECTION_CLASS_WIRE[variant];
+  }
+  return void 0;
+}
+function extractEnforcement(result) {
+  const decision = result.decision;
+  switch (decision.kind) {
+    case "Permit":
+      return { action: result.enforcementMode === "observe" ? "log" : "allow" };
+    case "Block":
+      return { action: "block", reason: decision.reason.kind };
+    case "Challenge":
+      return { action: "challenge" };
+    case "Redirect":
+      return { action: "redirect" };
+    case "Instruct":
+      return { action: "instruct" };
+  }
+}
+/**
+ * Detection reporter — fire-and-forget POST to the dashboard's
+ * `/api/v1/log-detection` ingest endpoint.
+ *
+ * The engine-backed middlewares (`withCheckpoint` in `checkpoint-express`
+ * and `checkpoint-nextjs`) run verification locally via WASM. Without
+ * this reporter the verdict path works in-process but nothing flows
+ * back to the dashboard — the onboarding "Verify" check fails forever
+ * because the `detections` table never sees a row.
+ *
+ * Mirrors the contract of the legacy `CheckpointApiClient.logDetection`
+ * (see `checkpoint-nextjs/src/api-client.ts`) so the server-side
+ * ingest at `/api/v1/log-detection` accepts both paths identically.
+ *
+ * Subpath: `@kya-os/checkpoint-wasm-runtime/reporter`.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+exports.buildLogDetectionPayload = buildLogDetectionPayload;
+exports.makeDetectionReporter = makeDetectionReporter;

package/dist/reporter.mjs

@@ -0,0 +1,122 @@
+// src/reporter/index.ts
+var DEFAULT_BASE_URL = "https://kya.vouched.id";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var SINGLE_HASH_RULESET_REGEX = /^sha256:[a-f0-9]{64}$/;
+function makeDetectionReporter(config) {
+  if (!config.apiKey) {
+    throw new Error(
+      "makeDetectionReporter: `apiKey` is required. Without it the dashboard cannot associate detections with your project."
+    );
+  }
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const endpoint = `${baseUrl}/api/v1/log-detection`;
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const debug = config.debug ?? false;
+  return function reportDetection(result, ctx) {
+    const payload = buildLogDetectionPayload(result, ctx);
+    if (debug && !payload.engine && result.engineInfo?.rulesetHash) {
+      console.warn(
+        `[checkpoint-reporter] dropping engine field \u2014 rulesetHash "${result.engineInfo.rulesetHash}" doesn't match dashboard schema /^sha256:[a-f0-9]{64}$/. Detection row will land with NULL engine_* columns.`
+      );
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+      keepalive: true
+    }).then((response) => {
+      if (!response.ok && debug) {
+        console.warn(
+          `[checkpoint-reporter] log-detection HTTP ${response.status} at ${endpoint}`
+        );
+      }
+    }).catch((err) => {
+      if (debug) {
+        console.warn("[checkpoint-reporter] log-detection failed:", err);
+      }
+    }).finally(() => clearTimeout(timeoutId));
+  };
+}
+function buildLogDetectionPayload(result, ctx) {
+  const detection = result.detectionDetail;
+  return {
+    detection: {
+      isAgent: detection.isAgent,
+      confidence: detection.confidence,
+      agentName: detection.detectedAgent?.name,
+      agentType: detection.detectedAgent?.type ?? detection.agentType,
+      detectionClass: stringifyDetectionClass(detection.detectionClass),
+      verificationMethod: detection.verificationMethod,
+      reasons: detection.reasons
+    },
+    context: ctx,
+    source: "middleware",
+    enforcement: extractEnforcement(result),
+    engine: sanitizeEngineInfo(result.engineInfo)
+  };
+}
+function sanitizeEngineInfo(engine) {
+  if (!engine) return void 0;
+  if (!SINGLE_HASH_RULESET_REGEX.test(engine.rulesetHash)) return void 0;
+  return engine;
+}
+var DETECTION_CLASS_WIRE = {
+  Human: "human",
+  AiAgent: "ai_agent",
+  Automation: "automation",
+  Bot: "bot",
+  IncompleteData: "incomplete_data",
+  Unknown: "unknown"
+};
+function stringifyDetectionClass(detectionClass) {
+  if (!detectionClass) return void 0;
+  if (typeof detectionClass === "string") {
+    return DETECTION_CLASS_WIRE[detectionClass] ?? detectionClass;
+  }
+  if (typeof detectionClass === "object" && "type" in detectionClass) {
+    const variant = String(detectionClass.type);
+    return DETECTION_CLASS_WIRE[variant];
+  }
+  return void 0;
+}
+function extractEnforcement(result) {
+  const decision = result.decision;
+  switch (decision.kind) {
+    case "Permit":
+      return { action: result.enforcementMode === "observe" ? "log" : "allow" };
+    case "Block":
+      return { action: "block", reason: decision.reason.kind };
+    case "Challenge":
+      return { action: "challenge" };
+    case "Redirect":
+      return { action: "redirect" };
+    case "Instruct":
+      return { action: "instruct" };
+  }
+}
+/**
+ * Detection reporter — fire-and-forget POST to the dashboard's
+ * `/api/v1/log-detection` ingest endpoint.
+ *
+ * The engine-backed middlewares (`withCheckpoint` in `checkpoint-express`
+ * and `checkpoint-nextjs`) run verification locally via WASM. Without
+ * this reporter the verdict path works in-process but nothing flows
+ * back to the dashboard — the onboarding "Verify" check fails forever
+ * because the `detections` table never sees a row.
+ *
+ * Mirrors the contract of the legacy `CheckpointApiClient.logDetection`
+ * (see `checkpoint-nextjs/src/api-client.ts`) so the server-side
+ * ingest at `/api/v1/log-detection` accepts both paths identically.
+ *
+ * Subpath: `@kya-os/checkpoint-wasm-runtime/reporter`.
+ *
+ * @license MIT OR Apache-2.0
+ */
+
+export { buildLogDetectionPayload, makeDetectionReporter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/checkpoint-wasm-runtime",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Checkpoint WASM runtime for AI agent detection across all environments (formerly @kya-os/agentshield-wasm-runtime)",
   "keywords": [
     "ai",
@@ -42,6 +42,11 @@
       "import": "./dist/node.mjs",
       "require": "./dist/node.js"
     },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "import": "./dist/policy.mjs",
+      "require": "./dist/policy.js"
+    },
     "./wasm": {
       "types": "./dist/wasm.d.ts",
       "import": "./dist/wasm.mjs"
@@ -111,10 +116,16 @@
       "import": "./dist/adapters.mjs",
       "require": "./dist/adapters.js"
     },
-    "./wasm/agentshield_wasm_bg.wasm": "./wasm/agentshield_wasm_bg.wasm",
+    "./reporter": {
+      "types": "./dist/reporter.d.ts",
+      "import": "./dist/reporter.mjs",
+      "require": "./dist/reporter.js"
+    },
     "./wasm/kya-os-engine/kya_os_engine_bg.wasm": "./wasm/kya-os-engine/kya_os_engine_bg.wasm",
     "./wasm/kya-os-engine-web/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-web/kya_os_engine_bg.wasm",
     "./wasm/kya-os-engine-bundler/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-bundler/kya_os_engine_bg.wasm",
+    "./wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-cedar/kya_os_engine_bg.wasm",
+    "./wasm/kya-os-engine-cedar-web/kya_os_engine_bg.wasm": "./wasm/kya-os-engine-cedar-web/kya_os_engine_bg.wasm",
     "./wasm/*": "./wasm/*",
     "./package.json": "./package.json"
   },
@@ -140,15 +151,14 @@
     "lint:fix": "eslint src --ext .ts,.tsx --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
     "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\"",
-    "prepublishOnly": "pnpm copy-wasm && pnpm copy-engine-wasm && pnpm copy-engine-wasm-web && pnpm copy-engine-wasm-bundler && pnpm build && pnpm test",
-    "copy-wasm": "mkdir -p ./wasm && cp ../../rust/crates/agentshield-wasm/pkg/agentshield_wasm_bg.wasm ./wasm/",
+    "prepublishOnly": "pnpm copy-engine-wasm && pnpm copy-engine-wasm-web && pnpm copy-engine-wasm-bundler && pnpm build && pnpm test",
     "copy-engine-wasm": "mkdir -p ./wasm/kya-os-engine && cp ../../rust/crates/kya-os-engine/pkg/kya_os_engine_bg.wasm ../../rust/crates/kya-os-engine/pkg/kya_os_engine_bg.wasm.d.ts ../../rust/crates/kya-os-engine/pkg/kya_os_engine.d.ts ../../rust/crates/kya-os-engine/pkg/kya_os_engine.js ./wasm/kya-os-engine/",
     "copy-engine-wasm-web": "mkdir -p ./wasm/kya-os-engine-web && cp ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine_bg.wasm ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine_bg.wasm.d.ts ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine.d.ts ../../rust/crates/kya-os-engine/pkg-web/kya_os_engine.js ./wasm/kya-os-engine-web/",
     "copy-engine-wasm-bundler": "mkdir -p ./wasm/kya-os-engine-bundler && cp ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine_bg.wasm ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine_bg.wasm.d.ts ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine_bg.js ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine.d.ts ../../rust/crates/kya-os-engine/pkg-bundler/kya_os_engine.js ./wasm/kya-os-engine-bundler/ && rm -f ./wasm/kya-os-engine-bundler/.gitignore",
     "wasm:rebuild": "bash ../../rust/scripts/build-engine-wasm.sh"
   },
   "dependencies": {
-    "@kya-os/checkpoint-shared": "1.1.0",
+    "@kya-os/checkpoint-shared": "1.2.0",
     "multiformats": "^13"
   },
   "devDependencies": {

package/wasm/kya-os-engine/package.json

@@ -12,7 +12,8 @@
   },
   "files": [
     "kya_os_engine_bg.wasm",
-    "kya_os_engine.js"
+    "kya_os_engine.js",
+    "kya_os_engine.d.ts"
   ],
   "main": "kya_os_engine.js",
   "keywords": [
@@ -23,5 +24,6 @@
     "did"
   ],
   "type": "commonjs",
-  "_note": "wasm-bindgen --target nodejs output: uses module.exports + require('fs') at module load. The parent wasm/package.json says type:module (for the older agentshield_wasm.js ESM file), which would make Node mis-classify this CJS file and throw ERR_REQUIRE_ESM. This nested package.json overrides per Node's nearest-package.json resolution algorithm. See SDK-WASM-Bundler-Loader-1 (#2613) for the original incident; AIVF-1 Path B (#2639) re-instated this override after a wasm-pack regen silently dropped it, plus a regen-pipeline patcher (rust/scripts/build-engine-wasm.sh) + an integrity test (packages/checkpoint-wasm-runtime/src/__tests__/wasm-artifact-integrity.test.ts) so the next regen can't silently break Node consumers again."
+  "types": "kya_os_engine.d.ts",
+  "_note": "wasm-bindgen --target nodejs output: uses module.exports + require('fs') at module load. The parent wasm/package.json says type:module (for the older agentshield_wasm.js ESM file), which would make Node mis-classify this CJS file and throw ERR_REQUIRE_ESM. This nested package.json overrides per Node's nearest-package.json resolution algorithm. See SDK-WASM-Bundler-Loader-1 (#2613) for the original incident; AIVF-1 Path B (#2639) re-instated this override after a wasm-pack regen silently dropped it, plus a regen-pipeline patcher (rust/scripts/build-engine-wasm.sh) + an integrity test (packages/checkpoint-wasm-runtime/src/__tests__/wasm-artifact-integrity.test.ts) so the next regen can't silently break Node consumers again. Engine-Pattern-Codegen-Retirement-1 extended the patcher to also restore the types/`files` .d.ts references that --no-typescript drops."
 }

package/wasm/kya-os-engine-cedar/README.md

@@ -0,0 +1,26 @@
+# kya-os-engine
+
+Verification engine for the KYA-OS ecosystem. Every TS / .NET / Go / Python /
+Cloudflare-Workers host wrapper is a thin shim around the WASM or WASI build of
+this crate. ADR-001 (Engine-Centric Consolidation) is the architectural
+decision; the locked public API contract is tracked in D-design
+([issue #2484][issue]) and mirrored at
+[`docs/architecture/D-design-ratification.md`][ratification].
+
+`kya-os-engine` is the root of the dependency graph. It depends on
+nothing from `@kya-os/*`, `agentshield-*`, or `checkpoint-*`; the
+direction is the other way.
+
+The public surface is one function (`verify`), one decision vocabulary (`Decision`
+with five variants — `Permit`, `Block`, `Challenge`, `Redirect`, `Instruct`),
+five dependency-injection traits (`DidResolver`, `StatusListCache`,
+`ReputationOracle`, `PolicyEvaluator`, `Clock`), and one canonical-signing-payload
+helper (`canonical_signing_payload`, RFC 8785 / JCS).
+
+This is the **Layer 1 API lock** (D-design, [issue #2484][issue]). The body of
+`verify()` is `todo!()`; trait methods are stubbed. D-impl
+([issue #2485][impl]) satisfies the contract.
+
+[issue]: https://github.com/Know-That-Ai/agent-shield/issues/2484
+[impl]: https://github.com/Know-That-Ai/agent-shield/issues/2485
+[ratification]: ../../../docs/architecture/D-design-ratification.md

package/wasm/kya-os-engine-cedar/kya_os_engine.d.ts

@@ -0,0 +1,77 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Cross-boundary `verify` wrapper. The JS host calls `engine.verify(input,
+ * ctxSpec)`; on success it gets a [`VerifyResult`] JSON object; on
+ * infrastructure failure (or malformed input) it gets a thrown JS error
+ * whose message names the failure mode.
+ *
+ * **Error semantics**:
+ *
+ * - Verification *verdicts* (Block/Challenge/etc.) surface inside the
+ *   returned `VerifyResult` — they are not thrown.
+ * - Engine [`VerifyError`][crate::error::VerifyError] (resolver / cache /
+ *   reputation / policy infra failures) surface as thrown JS errors.
+ * - Serde deserialisation failures (malformed JS input) surface as thrown
+ *   JS errors too, mirroring the typed-vs-thrown split.
+ *
+ * # JS signature
+ *
+ * ```ts
+ * function verify(input: AgentRequest, ctx: ContextSpec): VerifyResult;
+ * ```
+ */
+export function verify(input_js: any, ctx_js: any): any;
+/**
+ * Cross-boundary handle to a compiled Cedar policy bundle.
+ *
+ * Wraps a [`CedarPolicyEvaluator`] so a JS host can compile a tenant
+ * policy once and authorize many requests against it. Construction
+ * compiles the bundle; each [`authorize`][Self::authorize] call evaluates
+ * a single owned request and never re-parses policy text.
+ */
+export class PolicyEvaluator {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Compile `policy_text` into a reusable evaluator.
+   *
+   * The Cedar policy bundle is parsed and compiled exactly once here;
+   * the resulting evaluator is held for the lifetime of the handle and
+   * reused by every [`authorize`][Self::authorize] call.
+   *
+   * # Errors
+   *
+   * Returns a thrown JS error whose message names the failure when
+   * `policy_text` is not syntactically valid Cedar
+   * ([`PolicyEvaluationError::Malformed`][crate::error::PolicyEvaluationError::Malformed]).
+   * A malformed bundle is an infrastructure fault surfaced at
+   * construction, never as a per-request deny.
+   */
+  constructor(policy_text: string);
+  /**
+   * Authorize one owned request against the compiled policy bundle.
+   *
+   * The JS host calls `evaluator.authorize(input)` with an
+   * [`AuthorizeInput`]-shaped object (camelCase keys); it gets back a
+   * [`Decision`][crate::types::Decision] JSON object. The evaluator owns
+   * the fail-closed posture — a request it cannot marshal, or one
+   * matching no `permit`, comes back as a
+   * [`Decision::Block`][crate::types::Decision::Block], not a thrown
+   * error.
+   *
+   * # Errors
+   *
+   * Returns a thrown JS error only for boundary faults: a malformed
+   * `input_js` that fails [`AuthorizeInput`] deserialisation, or a
+   * failure serialising the resulting `Decision`. Authorization
+   * *verdicts* never throw — they surface inside the returned value.
+   *
+   * # JS signature
+   *
+   * ```ts
+   * authorize(input: AuthorizeInput): Decision;
+   * ```
+   */
+  authorize(input_js: any): any;
+}