kcp-harness 0.1.0

package/dist/temporal-watch.js

@@ -0,0 +1,147 @@
+// Temporal watch — detect plan drift when time changes governance outcomes.
+//
+// The temporal watcher periodically re-evaluates approved plans against their
+// manifests to detect when temporal gates (valid_from, valid_until, supersession)
+// would produce a different plan than the one currently approved. When drift is
+// detected, it emits a plan diff and optionally invalidates the stale plan.
+//
+// This is the "temporal governance" layer: it ensures that approved plans don't
+// outlive their temporal validity. A plan approved at 09:00 might become stale
+// at midnight when a superseding unit activates.
+//
+// Usage:
+// 1. Register plans with the watcher (automatic via governor)
+// 2. Call `check()` to evaluate all plans against current time
+// 3. Drifted plans emit audit events and are optionally invalidated
+//
+// The watcher is pure: it re-runs the kcp-agent planner with the current
+// date and diffs against the stored plan. No mutation unless `invalidate` is set.
+import { planTree, plans, diffPlans, } from "kcp-agent";
+/** Temporal plan watcher. */
+export class TemporalWatch {
+    watched = new Map();
+    /** Register a plan for temporal watching. */
+    register(manifest, task, plan, followOptions) {
+        this.watched.set(manifest, {
+            manifest,
+            task,
+            plan,
+            followOptions,
+            registeredAt: new Date().toISOString(),
+        });
+    }
+    /** Remove a plan from watching (e.g., after invalidation). */
+    unregister(manifest) {
+        this.watched.delete(manifest);
+    }
+    /** Check all watched plans for temporal drift. */
+    async check() {
+        const drifted = [];
+        const errors = [];
+        let stable = 0;
+        for (const [manifest, watched] of this.watched) {
+            try {
+                const result = await this.checkOne(watched);
+                watched.lastChecked = result.checkedAt;
+                if (result.drifted) {
+                    drifted.push(result);
+                }
+                else {
+                    stable++;
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                errors.push({ manifest, error: msg });
+            }
+        }
+        return { checked: this.watched.size, drifted, stable, errors };
+    }
+    /** Check a single plan for temporal drift. */
+    async checkOne(watched) {
+        const now = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+        // Re-plan with current date
+        const freshOptions = {
+            ...watched.followOptions,
+            planOptions: {
+                ...watched.followOptions.planOptions,
+                asOf: now, // Force current date
+            },
+        };
+        const tree = await planTree(watched.manifest, watched.task, freshOptions);
+        if (tree.error) {
+            throw new Error(`manifest error: ${tree.error}`);
+        }
+        const freshPlans = Array.from(plans(tree));
+        const freshPlan = freshPlans[0];
+        if (!freshPlan) {
+            throw new Error("re-plan returned no plan");
+        }
+        // Diff against the stored plan
+        const diff = diffPlans(watched.plan, freshPlan);
+        const checkedAt = new Date().toISOString();
+        if (diff.identical) {
+            return {
+                manifest: watched.manifest,
+                task: watched.task,
+                drifted: false,
+                summary: `plan is stable (checked at ${now})`,
+                checkedAt,
+            };
+        }
+        // Build a human-readable summary of what changed
+        const summary = summarizeDrift(diff);
+        return {
+            manifest: watched.manifest,
+            task: watched.task,
+            drifted: true,
+            diff,
+            newPlan: freshPlan,
+            summary,
+            checkedAt,
+        };
+    }
+    /** Get all watched plans. */
+    getWatched() {
+        return this.watched;
+    }
+    /** Get a watched plan by manifest. */
+    get(manifest) {
+        return this.watched.get(manifest);
+    }
+}
+/** Build a human-readable summary of plan drift. */
+function summarizeDrift(diff) {
+    const parts = [];
+    if (diff.moves.length > 0) {
+        const sel2skip = diff.moves.filter((m) => m.direction === "selected_to_skipped");
+        const skip2sel = diff.moves.filter((m) => m.direction === "skipped_to_selected");
+        if (sel2skip.length > 0) {
+            parts.push(`${sel2skip.length} unit(s) dropped: ${sel2skip.map((m) => m.id).join(", ")}`);
+        }
+        if (skip2sel.length > 0) {
+            parts.push(`${skip2sel.length} unit(s) activated: ${skip2sel.map((m) => m.id).join(", ")}`);
+        }
+    }
+    if (diff.scoreChanges.length > 0) {
+        parts.push(`${diff.scoreChanges.length} score change(s)`);
+    }
+    if (diff.presence.length > 0) {
+        const added = diff.presence.filter((p) => p.side === "b_only");
+        const removed = diff.presence.filter((p) => p.side === "a_only");
+        if (added.length > 0)
+            parts.push(`${added.length} new unit(s)`);
+        if (removed.length > 0)
+            parts.push(`${removed.length} removed unit(s)`);
+    }
+    if (diff.reasonChanges.length > 0) {
+        parts.push(`${diff.reasonChanges.length} reason change(s)`);
+    }
+    if (diff.budgetShifts.length > 0) {
+        parts.push(`${diff.budgetShifts.length} budget shift(s)`);
+    }
+    const temporal = diff.a.asOf !== diff.b.asOf
+        ? ` (${diff.a.asOf} → ${diff.b.asOf})`
+        : "";
+    return `temporal drift detected${temporal}: ${parts.join("; ") || "structural change"}`;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "kcp-harness",
+  "version": "0.1.0",
+  "description": "KCP Compliance Harness — MCP proxy that enforces deterministic knowledge governance for any agent",
+  "type": "module",
+  "bin": {
+    "kcp-harness": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "kcp-agent": "^0.11.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "kcp",
+    "knowledge-context-protocol",
+    "mcp",
+    "compliance",
+    "harness",
+    "governance",
+    "agent",
+    "ai",
+    "audit"
+  ],
+  "homepage": "https://cantara.github.io/kcp-harness/",
+  "author": "eXOReaction AS",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cantara/kcp-harness.git"
+  }
+}