@kya-os/checkpoint-nextjs 1.1.0 → 1.1.4

package/CHANGELOG.md

@@ -1,5 +1,183 @@
 # @kya-os/checkpoint-nextjs
 
+## 1.1.4 — 2026-05-18
+
+Companion patch for `@kya-os/checkpoint-wasm-runtime@1.2.0`.
+
+### Changed
+
+- Middleware enforcement now reads the canonical engine
+  `VerifyResult.decision`; descriptive/session metadata reads
+  `VerifyResult.detectionDetail`.
+- Edge runtime detection types now reuse the shared `DetectionDetail`
+  surface instead of maintaining a parallel `DetectionResult` definition.
+- Edge runtime fallback detection now emits canonical 0-100
+  `DetectionDetail.confidence` values. A no-match fallback emits
+  confidence `0` instead of the older legacy `0.85` placeholder.
+
+## 1.1.3 — 2026-05-18
+
+Phase-D.9a (Phase 1 of 2) — convert legacy `agentshield-wasm`-bound
+public APIs to throw-stubs. The underlying `agentshield-wasm` Rust
+crate + its shipped artifacts stay live for one more cycle (Phase-D.9b
+deletes them after migrating the production Cloudflare gateway worker).
+
+### Deprecations as throw-stubs (no engine work; runtime callers must migrate)
+
+- **`edge-wasm-middleware.ts`** — `createEdgeWasmMiddleware`,
+  `initializeEdgeWasm` now `@deprecated` + throw with migration error
+  pointing at `withCheckpoint` from `@kya-os/checkpoint-nextjs/edge`.
+  470 LOC of hand-written wasm-bindgen heap manager removed (the
+  engine path has its own wasm-bindgen output centrally maintained in
+  `@kya-os/checkpoint-wasm-runtime`).
+
+- **`nodejs-wasm-loader.ts`** — `loadWasmNodejs`, `isNodejsRuntime`,
+  `getWasmModule`, `isWasmInitialized` now `@deprecated` + throw with
+  the same migration error. 117 LOC of `fs.readFileSync`-based
+  multi-path WASM-locator logic removed (`@kya-os/checkpoint-wasm-runtime`'s
+  loaders auto-resolve via the `"node"` / `"edge-runtime"` export
+  conditions; no manual `fs` needed).
+
+Net: **−415 LOC** of legacy wasm-bindgen glue / fs-locator code.
+
+### Throw-stub pattern (matches PR #2610's `createWasmAgentShieldMiddleware`)
+
+- One-shot dev-only `console.warn` on first invocation; suppressed in
+  production and after the first emission.
+- Test-only reset helpers exported (`__resetEdgeWasmWarningForTests`,
+  `__resetNodejsWasmWarningForTests`).
+- Migration target named directly in the error message.
+
+### Why throw vs. deprecate-and-keep-working
+
+Unlike PR #2610's `createWasmAgentShieldMiddleware` (which still does
+useful work backed by the legacy `AgentDetector` class), these two
+files depend on the `agentshield-wasm` Rust crate's shipped artifacts.
+The artifacts will be deleted in Phase-D.9b. Keeping these functions
+working until D.9b would mean they'd start silently failing the moment
+the artifact deletion lands. Throwing immediately on call surfaces
+the migration error today, before D.9b's deletion makes it worse.
+
+### Regression tests (20 new across 3 files)
+
+- `edge-wasm-middleware.test.ts` (7 tests): throws with migration
+  error, one-shot warn, no-op in prod, latch shared across both exports
+- `nodejs-wasm-loader.test.ts` (6 tests): same shape across the 4
+  throw-stub exports + shared-latch verification
+- `d9-deletion-gate-scaffold.test.ts` (7 tests): pins what Phase-D.9a
+  achieved structurally — both files exist as compile-time surface;
+  both removed inline wasm-bindgen helpers; both reference
+  `withCheckpoint`; no live imports of `setWasmModule` from the legacy
+  `@kya-os/checkpoint` package
+
+Revert-and-fail verified: removing the `warn*()` call from either
+throw-stub function fails 2 of the warn assertions; restoring re-greens.
+
+### Out of scope for D.9a (deferred to Phase-D.9b)
+
+- `rust/crates/agentshield-wasm/` Rust crate deletion (gateway worker
+  is the last consumer)
+- All 7 shipped `agentshield_wasm_bg.wasm` artifact copies
+- `apps/web/lib/wasm/agentshield-loader.ts` migration (audit found 6
+  production-route consumers using a multi-function WASM API that
+  doesn't map structurally to the engine's single `verify(input, ctx)`
+  entry — needs the same engine-API translation as the gateway worker)
+- Cloudflare gateway worker migration (production-risk; needs Wrangler
+  preview deploy + cold-start measurement; compressed size verified at
+  0.44 MB, well under Workers' 1 MB free-tier limit)
+- `apps/web/public/sw.js` service-worker cache manifest cleanup
+- Top-level ad-hoc `test-wasm.mjs`-style dev scripts at repo root
+- Final deletion-gate test (lands with D.9b)
+
+### Bench safety
+
+TS-only, zero `kya-os-engine` or `agentshield-wasm` Rust changes.
+Ships in parallel with Engineer 1's Express bench pivot + bundler audit.
+
+### Version
+
+`@kya-os/checkpoint-nextjs` 1.1.2 → **1.1.3** (patch — deprecation,
+breaking only for callers that ignored the prior deprecation cycle).
+
+## 1.1.2 — 2026-05-17
+
+AgentDetector-Deletion-1 (Phase 1 of 2) — deprecate the two README-
+documented public APIs that wrap the legacy TS `AgentDetector` class.
+The class itself stays live for one more minor release; this patch is
+the deprecation signal.
+
+### Deprecations (no behavior change)
+
+- **`useAgentDetection`** (`packages/checkpoint-nextjs/src/hooks.ts`)
+  - `@deprecated` JSDoc + one-shot dev-only `console.warn`
+  - Migrate to `withCheckpoint` from `@kya-os/checkpoint-nextjs` for
+    server-side detection, or consume `KNOWN_AGENT_PATTERNS` directly
+    from `@kya-os/checkpoint-shared` for client-side pattern matching.
+  - `useDetectionMonitor` is NOT deprecated — it doesn't depend on
+    `AgentDetector`.
+
+- **`createWasmAgentShieldMiddleware`** (`packages/checkpoint-nextjs/src/wasm-middleware.ts`)
+  - `@deprecated` JSDoc + one-shot dev-only `console.warn`
+  - Migrate to `withCheckpoint` from `@kya-os/checkpoint-nextjs` —
+    engine-backed, runs envelope verification.
+
+### Why
+
+Pattern-Detection-Migration-1 (#2560) moved Stage 1 detection into the
+Rust `kya-os-engine` crate. The legacy TS `AgentDetector` class that
+both APIs wrap duplicates that path. PDM-2 (#2608) consolidated the
+shared pattern table; this patch begins phasing out the legacy class
+itself.
+
+### Removal timeline
+
+- **Now (1.1.2):** deprecation signals — APIs keep working, dev-only
+  `console.warn` fires once per process pointing at the migration
+  target. README banners added.
+- **Next minor:** AgentDetector-Deletion-2 — delete the legacy class,
+  delete these two APIs, deletion-gate test pins absence. Will be a
+  breaking change for any caller that ignored the deprecation.
+
+### Bench safety
+
+TS-only, zero `kya-os-engine` changes. Ships in parallel with
+in-flight Rust bench captures without invalidating them.
+
+## 1.1.1 — 2026-05-17
+
+Companion patch to `@kya-os/checkpoint-wasm-runtime@1.1.0`'s
+SDK-WASM-Bundler-Loader-1 fix. **All 1.1.0 users running under Next.js
+Node runtime should upgrade** — `withCheckpoint` couldn't actually be
+deployed under Next.js Node runtime in 1.1.0 due to a Turbopack-
+incompatible URL trick in the wasm-runtime's orchestrator bundle.
+
+### Internal change
+
+- `@kya-os/checkpoint-wasm-runtime` dep changed from exact `1.0.0`
+  pin (the `workspace:*` default) to `^1.1.0` range (via `workspace:^`).
+  Fresh installs now pull `wasm-runtime@1.1.0+`, which adds the
+  `"node"` export condition routing Next.js Node-runtime bundlers to
+  the bundler-clean `orchestrator-node.mjs` entry.
+
+### No code or config changes
+
+Customer middleware.ts call site is unchanged. Verifying envelopes
+under Next.js Node runtime now works end-to-end:
+
+```typescript
+import { withCheckpoint } from '@kya-os/checkpoint-nextjs';
+
+export default withCheckpoint({
+  tenantHost: 'acme.checkpoint.example',
+  legacyEnvelopeFallback: true,
+});
+```
+
+See `@kya-os/checkpoint-wasm-runtime@1.1.0` CHANGELOG for the
+architectural detail.
+
+---
+
 ## 1.1.0 — 2026-05-17
 
 Closes [SDK-Envelope-Plumbing-1 (#2594)](https://github.com/Know-That-Ai/agent-shield/issues/2594).

package/EDGE_RUNTIME_WASM_SETUP.md

@@ -113,6 +113,7 @@ Create `lib/agentshield-edge.ts`:
 ```typescript
 // lib/agentshield-edge.ts
 import type { NextRequest } from 'next/server';
+import type { EdgeRuntimeDetectionDetail } from '@kya-os/checkpoint-nextjs/edge-runtime-loader';
 import wasmModule from '../wasm/agentshield_wasm_bg.wasm?module';
 
 let wasmInstance: WebAssembly.Instance | null = null;
@@ -167,16 +168,9 @@ function writeString(str: string): [number, number] {
   return [ptr, encoded.length];
 }
 
-export interface DetectionResult {
-  isAgent: boolean;
-  confidence: number;
-  agent?: string;
-  verificationMethod: 'cryptographic' | 'pattern';
-}
-
 export function createAgentShieldMiddleware(options: {
   enableWasm?: boolean;
-  onAgentDetected?: (result: DetectionResult) => void;
+  onAgentDetected?: (result: EdgeRuntimeDetectionDetail) => void;
 }) {
   let initialized = false;
 
@@ -198,7 +192,7 @@ export function createAgentShieldMiddleware(options: {
       }
     },
 
-    async detect(request: NextRequest): Promise<DetectionResult> {
+    async detect(request: NextRequest): Promise<DetectionDetail> {
       const metadata = {
         userAgent: request.headers.get('user-agent') || '',
         ipAddress: request.ip || request.headers.get('x-forwarded-for') || '',
@@ -248,7 +242,7 @@ export function createAgentShieldMiddleware(options: {
 
       for (const { pattern, name } of aiAgentPatterns) {
         if (pattern.test(userAgent)) {
-          const result: DetectionResult = {
+          const result: DetectionDetail = {
             isAgent: true,
             confidence: 0.85,
             agent: name,

package/README.md

@@ -76,6 +76,15 @@ export const config = {
 
 ### React Hooks
 
+> ⚠️ **`useAgentDetection` is deprecated** as of AgentDetector-Deletion-1
+> and slated for removal in the next minor. It wraps the legacy TS
+> `AgentDetector` class; Stage 1 detection now lives in the Rust
+> `kya-os-engine` (PDM-1 #2560). Migrate to server-side detection via
+> `withCheckpoint` from `@kya-os/checkpoint-nextjs`, or consume
+> `KNOWN_AGENT_PATTERNS` directly from `@kya-os/checkpoint-shared` if
+> you genuinely need client-side pattern matching. `useDetectionMonitor`
+> stays — it doesn't depend on `AgentDetector`.
+
 ```javascript
 'use client';
 
@@ -202,6 +211,10 @@ export default agentShield({
 
 ### useAgentDetection
 
+> ⚠️ **Deprecated** — see banner above. Will be removed in the next
+> minor. Migrate to `withCheckpoint` (server-side) or direct
+> `KNOWN_AGENT_PATTERNS` consumption (client-side pattern matching).
+
 Client-side agent detection:
 
 ```javascript

package/bin/setup-edge-wasm.js

@@ -116,14 +116,8 @@ export interface AgentShieldWasm {
   memory: WebAssembly.Memory;
 }
 
-export interface DetectionResult {
-  isAgent: boolean;
-  confidence: number;
-  agent?: string;
-  verificationMethod: 'cryptographic' | 'pattern';
-  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
-  timestamp: string;
-}
+export type EdgeWasmDetectionDetail =
+  import('@kya-os/checkpoint-nextjs/edge-runtime-loader').EdgeRuntimeDetectionDetail;
 `;
 
   const dtsPath = path.join(wasmDir, 'agentshield.d.ts');
@@ -144,8 +138,11 @@ export interface DetectionResult {
  */
 
 import type { NextRequest } from 'next/server';
+import type { EdgeRuntimeDetectionDetail } from '@kya-os/checkpoint-nextjs/edge-runtime-loader';
 import wasmModule from '../wasm/agentshield_wasm_bg.wasm?module';
 
+type EdgeWasmDetectionDetail = EdgeRuntimeDetectionDetail;
+
 let wasmInstance: WebAssembly.Instance | null = null;
 let wasmMemory: WebAssembly.Memory | null = null;
 
@@ -200,18 +197,9 @@ function writeString(str: string): [number, number] {
   return [ptr, encoded.length];
 }
 
-export interface DetectionResult {
-  isAgent: boolean;
-  confidence: number;
-  agent?: string;
-  verificationMethod: 'cryptographic' | 'pattern';
-  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
-  timestamp?: string;
-}
-
 export interface AgentShieldOptions {
   enableWasm?: boolean;
-  onAgentDetected?: (result: DetectionResult) => void;
+  onAgentDetected?: (result: EdgeWasmDetectionDetail) => void;
   blockAgents?: boolean;
   allowedAgents?: string[];
 }
@@ -240,7 +228,7 @@ export function createAgentShieldMiddleware(options: AgentShieldOptions = {}) {
       }
     },
     
-    async detect(request: NextRequest): Promise<DetectionResult> {
+    async detect(request: NextRequest): Promise<EdgeWasmDetectionDetail> {
       const metadata = {
         userAgent: request.headers.get('user-agent') || '',
         ipAddress: request.ip || request.headers.get('x-forwarded-for')?.split(',')[0] || '',
@@ -261,11 +249,23 @@ export function createAgentShieldMiddleware(options: AgentShieldOptions = {}) {
           exports.__wbindgen_free(resultPtr, resultLen);
           
           const result = JSON.parse(resultStr);
-          
-          const detection: DetectionResult = {
+
+          // EdgeWasmDetectionDetail's contract is confidence on a 0-100
+          // scale. The canonical kya-os-engine emits 0-100 natively
+          // (see checkpoint-nextjs/src/edge-runtime-loader.ts's
+          // normalizeEngineConfidence). Clamp + round here as a defensive
+          // measure for malformed WASM output, but do NOT multiply —
+          // multiplying would produce 9500 instead of 95 for any user
+          // who's switched from the legacy agentshield_wasm binding to
+          // the current engine.
+          const detection: EdgeWasmDetectionDetail = {
             ...result,
-            verificationMethod: 'cryptographic',
-            timestamp: new Date().toISOString(),
+            confidence:
+              typeof result.confidence === 'number'
+                ? Math.round(Math.max(0, Math.min(100, result.confidence)))
+                : 0,
+            verificationMethod: 'signature',
+            timestamp: Date.now(),
           };
           
           if (options.onAgentDetected && detection.isAgent) {
@@ -299,7 +299,7 @@ export function createAgentShieldMiddleware(options: AgentShieldOptions = {}) {
 function patternDetection(
   metadata: { userAgent: string; ipAddress: string; headers: Record<string, string> },
   options: AgentShieldOptions
-): DetectionResult {
+): EdgeWasmDetectionDetail {
   const userAgent = metadata.userAgent.toLowerCase();
   
   // Known AI agent patterns with confidence scores
@@ -336,13 +336,18 @@ function patternDetection(
     if (pattern.test(userAgent)) {
       const finalConfidence = Math.min(confidence + headerBoost, 1.0);
       
-      const result: DetectionResult = {
+      const result: EdgeWasmDetectionDetail = {
         isAgent: true,
-        confidence: finalConfidence,
+        confidence: Math.round(finalConfidence * 100),
         agent: name,
+        detectionClass: { type: 'AiAgent', agentType: name },
+        detectedAgent: { type: 'ai_agent', name },
+        agentType: name,
+        reasons: [\`known_pattern:\${name.toLowerCase()}\`],
+        signals: [],
         verificationMethod: 'pattern',
         riskLevel: finalConfidence > 0.9 ? 'high' : 'medium',
-        timestamp: new Date().toISOString(),
+        timestamp: Date.now(),
       };
       
       if (options.onAgentDetected) {
@@ -356,9 +361,12 @@ function patternDetection(
   // Not detected as AI agent
   return {
     isAgent: false,
-    confidence: 0.85,
+    confidence: 0,
+    detectionClass: { type: 'Human' },
+    reasons: ['No known agent indicators matched'],
+    signals: [],
     verificationMethod: 'pattern',
-    timestamp: new Date().toISOString(),
+    timestamp: Date.now(),
   };
 }
 
@@ -380,7 +388,7 @@ import { createAgentShieldMiddleware } from './lib/agentshield-edge';
 const agentShield = createAgentShieldMiddleware({
   enableWasm: true,
   onAgentDetected: (result) => {
-    console.log(\`🤖 AI Agent detected: \${result.agent} (confidence: \${(result.confidence * 100).toFixed(1)}%)\`);
+    console.log(\`🤖 AI Agent detected: \${result.agent} (confidence: \${result.confidence.toFixed(1)}%)\`);
   },
 });
 
@@ -401,8 +409,8 @@ export async function middleware(request: NextRequest) {
     response.headers.set('X-Agent-Confidence', detection.confidence.toString());
     return response;
     
-    // Optional: Block AI agents
-    // if (detection.confidence > 0.9) {
+    // Optional: Block AI agents (confidence is on 0-100 scale)
+    // if (detection.confidence > 90) {
     //   return NextResponse.json(
     //     { error: 'AI agent access denied' },
     //     { status: 403 }

package/dist/api-client.d.mts

@@ -1,4 +1,4 @@
-import { EnforcementAction } from '@kya-os/checkpoint-shared';
+import { EnforcementAction, DetectionDetail } from '@kya-os/checkpoint-shared';
 export { EnforcementAction } from '@kya-os/checkpoint-shared';
 
 /**
@@ -53,20 +53,20 @@ interface EnforcementDecision {
     };
 }
 /**
- * Detection result (optional in response)
+ * Detection detail (optional in response)
  */
-interface DetectionResult {
-    isAgent: boolean;
-    confidence: number;
+type ApiDetectionDetail = Omit<DetectionDetail, 'detectionClass' | 'verificationMethod' | 'reasons' | 'signals' | 'timestamp'> & {
     agentName?: string;
-    agentType?: string;
     /** Detection class: 'human', 'ai_agent', 'bot', 'incomplete_data' */
     detectionClass?: string;
     verificationMethod?: string;
     reasons?: string[];
+    signals?: DetectionDetail['signals'];
+    timestamp?: DetectionDetail['timestamp'];
     /** Detection engine used: 'wasm' or 'javascript-fallback' */
     detectionMethod?: string;
-}
+};
+
 /**
  * Enforce API response
  */
@@ -76,7 +76,7 @@ interface EnforceResponse {
         decision: EnforcementDecision;
         processingTimeMs: number;
         requestId: string;
-        detection?: DetectionResult;
+        detection?: ApiDetectionDetail;
     };
     error?: {
         code: string;
@@ -114,7 +114,7 @@ interface EnforceInput {
  */
 interface LogDetectionInput {
     /** Detection result from Gateway */
-    detection: DetectionResult;
+    detection: ApiDetectionDetail;
     /** Request context */
     context: {
         userAgent?: string;
@@ -201,4 +201,4 @@ declare const getAgentShieldClient: typeof getCheckpointApiClient;
 /** @deprecated Renamed to {@link resetCheckpointApiClient}. */
 declare const resetAgentShieldClient: typeof resetCheckpointApiClient;
 
-export { AgentShieldClient, type AgentShieldClientConfig, CheckpointApiClient, type CheckpointApiClientConfig, type DetectionResult, type EnforceInput, type EnforceResponse, type EnforcementDecision, type LogDetectionInput, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };
+export { AgentShieldClient, type AgentShieldClientConfig, type ApiDetectionDetail, CheckpointApiClient, type CheckpointApiClientConfig, type ApiDetectionDetail as DetectionResult, type EnforceInput, type EnforceResponse, type EnforcementDecision, type LogDetectionInput, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };

package/dist/api-client.d.ts

@@ -1,4 +1,4 @@
-import { EnforcementAction } from '@kya-os/checkpoint-shared';
+import { EnforcementAction, DetectionDetail } from '@kya-os/checkpoint-shared';
 export { EnforcementAction } from '@kya-os/checkpoint-shared';
 
 /**
@@ -53,20 +53,20 @@ interface EnforcementDecision {
     };
 }
 /**
- * Detection result (optional in response)
+ * Detection detail (optional in response)
  */
-interface DetectionResult {
-    isAgent: boolean;
-    confidence: number;
+type ApiDetectionDetail = Omit<DetectionDetail, 'detectionClass' | 'verificationMethod' | 'reasons' | 'signals' | 'timestamp'> & {
     agentName?: string;
-    agentType?: string;
     /** Detection class: 'human', 'ai_agent', 'bot', 'incomplete_data' */
     detectionClass?: string;
     verificationMethod?: string;
     reasons?: string[];
+    signals?: DetectionDetail['signals'];
+    timestamp?: DetectionDetail['timestamp'];
     /** Detection engine used: 'wasm' or 'javascript-fallback' */
     detectionMethod?: string;
-}
+};
+
 /**
  * Enforce API response
  */
@@ -76,7 +76,7 @@ interface EnforceResponse {
         decision: EnforcementDecision;
         processingTimeMs: number;
         requestId: string;
-        detection?: DetectionResult;
+        detection?: ApiDetectionDetail;
     };
     error?: {
         code: string;
@@ -114,7 +114,7 @@ interface EnforceInput {
  */
 interface LogDetectionInput {
     /** Detection result from Gateway */
-    detection: DetectionResult;
+    detection: ApiDetectionDetail;
     /** Request context */
     context: {
         userAgent?: string;
@@ -201,4 +201,4 @@ declare const getAgentShieldClient: typeof getCheckpointApiClient;
 /** @deprecated Renamed to {@link resetCheckpointApiClient}. */
 declare const resetAgentShieldClient: typeof resetCheckpointApiClient;
 
-export { AgentShieldClient, type AgentShieldClientConfig, CheckpointApiClient, type CheckpointApiClientConfig, type DetectionResult, type EnforceInput, type EnforceResponse, type EnforcementDecision, type LogDetectionInput, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };
+export { AgentShieldClient, type AgentShieldClientConfig, type ApiDetectionDetail, CheckpointApiClient, type CheckpointApiClientConfig, type ApiDetectionDetail as DetectionResult, type EnforceInput, type EnforceResponse, type EnforcementDecision, type LogDetectionInput, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };

package/dist/create-middleware.d.mts

@@ -4,8 +4,13 @@ import '@kya-os/checkpoint-shared';
 import '@kya-os/checkpoint';
 
 /**
- * Enhanced middleware creator for Edge Runtime
- * Uses EdgeAgentDetector which doesn't require WASM
+ * Enhanced middleware creator for Edge Runtime.
+ *
+ * NOTE (post-Phase D): this wrapper delegates to
+ * `createAgentShieldMiddleware` from `./middleware`, which is itself a
+ * throw-stub pointing at `withCheckpoint`. Effectively dead code; kept
+ * as a compile-time surface until next-minor cleanup. See `middleware.ts`
+ * for the migration error message + canonical replacement recipe.
  */
 
 /**

package/dist/create-middleware.d.ts

@@ -4,8 +4,13 @@ import '@kya-os/checkpoint-shared';
 import '@kya-os/checkpoint';
 
 /**
- * Enhanced middleware creator for Edge Runtime
- * Uses EdgeAgentDetector which doesn't require WASM
+ * Enhanced middleware creator for Edge Runtime.
+ *
+ * NOTE (post-Phase D): this wrapper delegates to
+ * `createAgentShieldMiddleware` from `./middleware`, which is itself a
+ * throw-stub pointing at `withCheckpoint`. Effectively dead code; kept
+ * as a compile-time surface until next-minor cleanup. See `middleware.ts`
+ * for the migration error message + canonical replacement recipe.
  */
 
 /**

package/dist/edge/index.d.mts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { DetectionResult } from '@kya-os/checkpoint-shared';
-export { DetectionResult } from '@kya-os/checkpoint-shared';
+import { DetectionDetail } from '@kya-os/checkpoint-shared';
+export { DetectionDetail } from '@kya-os/checkpoint-shared';
 
 /**
  * Edge Runtime Middleware with WASM Support
@@ -54,7 +54,7 @@ interface EdgeMiddlewareConfig {
      * Custom handler called when an agent is detected
      * Return a NextResponse to override default behavior
      */
-    onDetection?: (request: NextRequest, result: DetectionResult) => Promise<NextResponse | void> | NextResponse | void;
+    onDetection?: (request: NextRequest, result: DetectionDetail) => Promise<NextResponse | void> | NextResponse | void;
     /**
      * Paths to skip detection (can be string prefixes or RegExp)
      */

package/dist/edge/index.d.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { DetectionResult } from '@kya-os/checkpoint-shared';
-export { DetectionResult } from '@kya-os/checkpoint-shared';
+import { DetectionDetail } from '@kya-os/checkpoint-shared';
+export { DetectionDetail } from '@kya-os/checkpoint-shared';
 
 /**
  * Edge Runtime Middleware with WASM Support
@@ -54,7 +54,7 @@ interface EdgeMiddlewareConfig {
      * Custom handler called when an agent is detected
      * Return a NextResponse to override default behavior
      */
-    onDetection?: (request: NextRequest, result: DetectionResult) => Promise<NextResponse | void> | NextResponse | void;
+    onDetection?: (request: NextRequest, result: DetectionDetail) => Promise<NextResponse | void> | NextResponse | void;
     /**
      * Paths to skip detection (can be string prefixes or RegExp)
      */

package/dist/edge/index.js

@@ -1,7 +1,6 @@
 'use strict';
 
 var server = require('next/server');
-var checkpointShared = require('@kya-os/checkpoint-shared');
 
 // src/edge/index.ts
 
@@ -21,6 +20,20 @@ function getClientIp(request) {
   return void 0;
 }
 
+// src/local-detection-gate.ts
+function isDetectedAgentForLocalGate(result) {
+  return result.isAgent === true;
+}
+function evaluateLocalDetectionGate(result, config) {
+  if (!isDetectedAgentForLocalGate(result)) {
+    return { action: "allow", shouldNotify: false };
+  }
+  if ((result.confidence ?? 0) >= config.confidenceThreshold) {
+    return { action: config.defaultAction, shouldNotify: true };
+  }
+  return { action: "allow", shouldNotify: false };
+}
+
 // src/edge/index.ts
 async function patternDetect(input) {
   const userAgent = input.userAgent?.toLowerCase() || "";
@@ -111,7 +124,7 @@ async function createDetector(config) {
             reasons: result.reasons,
             timestamp: result.timestamp,
             signals: [],
-            // Required by DetectionResult, empty for WASM results
+            // Required by DetectionDetail, empty for WASM results
             shouldBlock: result.shouldBlock,
             blockReason: result.blockReason
           };
@@ -209,7 +222,7 @@ function createEdgeMiddleware(config = {}) {
         );
       }
       if (result.shouldBlock !== false) {
-        const decision = checkpointShared.evaluateEnforcement(result, {
+        const decision = evaluateLocalDetectionGate(result, {
           confidenceThreshold,
           defaultAction: onAgentDetected
         });

package/dist/edge/index.mjs

@@ -1,5 +1,4 @@
 import { NextResponse } from 'next/server';
-import { evaluateEnforcement } from '@kya-os/checkpoint-shared';
 
 // src/edge/index.ts
 
@@ -19,6 +18,20 @@ function getClientIp(request) {
   return void 0;
 }
 
+// src/local-detection-gate.ts
+function isDetectedAgentForLocalGate(result) {
+  return result.isAgent === true;
+}
+function evaluateLocalDetectionGate(result, config) {
+  if (!isDetectedAgentForLocalGate(result)) {
+    return { action: "allow", shouldNotify: false };
+  }
+  if ((result.confidence ?? 0) >= config.confidenceThreshold) {
+    return { action: config.defaultAction, shouldNotify: true };
+  }
+  return { action: "allow", shouldNotify: false };
+}
+
 // src/edge/index.ts
 async function patternDetect(input) {
   const userAgent = input.userAgent?.toLowerCase() || "";
@@ -109,7 +122,7 @@ async function createDetector(config) {
             reasons: result.reasons,
             timestamp: result.timestamp,
             signals: [],
-            // Required by DetectionResult, empty for WASM results
+            // Required by DetectionDetail, empty for WASM results
             shouldBlock: result.shouldBlock,
             blockReason: result.blockReason
           };
@@ -207,7 +220,7 @@ function createEdgeMiddleware(config = {}) {
         );
       }
       if (result.shouldBlock !== false) {
-        const decision = evaluateEnforcement(result, {
+        const decision = evaluateLocalDetectionGate(result, {
           confidenceThreshold,
           defaultAction: onAgentDetected
         });