@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/__tests__/reasoning-quality-route.test.js

@@ -0,0 +1,138 @@
+/**
+ * Verifies the /reasoning-quality routes surface persistent-memory metrics
+ * derived from token-flow events with mechanism: "persistent_memory".
+ */
+import { mkdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createReasoningQualityRoutes } from "../server/routes/reasoning-quality.js";
+import { PersistenceEffectivenessTracker } from "../tracking/persistence-effectiveness.js";
+import { TokenFlowWriter } from "../tracking/token-flow.js";
+async function getGlobal(app) {
+    const res = await app.fetch(new Request("http://localhost/global"));
+    const body = (await res.json());
+    return body.data;
+}
+describe("reasoning-quality route — persistent memory metrics", () => {
+    let tmpDir;
+    let unerrDir;
+    let writer;
+    let tracker;
+    beforeEach(() => {
+        tmpDir = join(os.tmpdir(), `unerr-rq-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        unerrDir = join(tmpDir, ".unerr");
+        mkdirSync(unerrDir, { recursive: true });
+        writer = new TokenFlowWriter(unerrDir, "rq-session");
+        tracker = new PersistenceEffectivenessTracker(writer, { windowTurns: 3 });
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("returns zero memory metrics when no persistent_memory events exist", async () => {
+        writer.record({
+            session_id: "rq-session",
+            turn: 1,
+            mechanism: "graph_query",
+            tool: "search_code",
+            tokens_without: 1000,
+            tokens_with: 200,
+            tokens_saved: 800,
+        });
+        const app = createReasoningQualityRoutes({
+            unerrDir,
+            getTokenFlowWriter: () => writer,
+        });
+        const data = await getGlobal(app);
+        expect(data.memory_signals_fired).toBe(0);
+        expect(data.memory_verdicts_total).toBe(0);
+        expect(data.memory_effectiveness_pct).toBe(0);
+    });
+    it("computes effectiveness when verdicts resolve", async () => {
+        // 1 reinforced (re-fired + no correction)
+        tracker.recordSignalFired({
+            kind: "fact_injected",
+            signal_id: "f-reinforced",
+            entity_key: "EntityR",
+            turn: 1,
+        });
+        tracker.recordSignalFired({
+            kind: "fact_injected",
+            signal_id: "f-reinforced",
+            entity_key: "EntityR",
+            turn: 2,
+        });
+        // 1 acted_on (edit observed + no correction)
+        tracker.recordSignalFired({
+            kind: "convention_injected",
+            signal_id: "c-acted",
+            entity_key: "EntityA",
+            turn: 1,
+        });
+        tracker.recordEdit("EntityA");
+        // 1 caught (negative warning + no correction)
+        tracker.recordSignalFired({
+            kind: "negative_warned",
+            signal_id: "n-caught",
+            entity_key: "EntityN",
+            turn: 1,
+        });
+        // 1 corrected (signal fired + correction observed)
+        tracker.recordSignalFired({
+            kind: "convention_injected",
+            signal_id: "c-corrected",
+            entity_key: "EntityX",
+            turn: 1,
+        });
+        tracker.recordCorrection("EntityX", "circuit_breaker");
+        // 1 ignored
+        tracker.recordSignalFired({
+            kind: "fact_injected",
+            signal_id: "f-ignored",
+            entity_key: "EntityI",
+            turn: 1,
+        });
+        // 1 resume + 1 fact_recalled — verdict counts
+        tracker.recordSignalFired({
+            kind: "resume_injected",
+            signal_id: "resume-1",
+            entity_key: null,
+            turn: 1,
+        });
+        tracker.recordSignalFired({
+            kind: "fact_recalled",
+            signal_id: "r-1",
+            entity_key: "EntityRec",
+            turn: 1,
+        });
+        tracker.recordSignalFired({
+            kind: "fact_recorded",
+            signal_id: "rec-1",
+            entity_key: "EntitySub",
+            turn: 1,
+        });
+        tracker.closeWindow(10);
+        const app = createReasoningQualityRoutes({
+            unerrDir,
+            getTokenFlowWriter: () => writer,
+        });
+        const data = await getGlobal(app);
+        // Fired counts by kind
+        expect(data.facts_surfaced).toBe(2); // f-reinforced, f-ignored
+        expect(data.facts_recalled).toBe(1);
+        expect(data.facts_recorded).toBe(1);
+        expect(data.conventions_surfaced).toBe(2);
+        expect(data.resume_hits).toBe(1);
+        expect(data.negative_warnings).toBe(1);
+        expect(data.memory_signals_fired).toBe(8);
+        // Verdict tallies (8 total verdicts after closeWindow)
+        expect(data.verdicts_reinforced).toBe(1);
+        expect(data.verdicts_acted_on).toBe(1);
+        expect(data.verdicts_caught).toBe(1);
+        expect(data.verdicts_corrected).toBe(1);
+        expect(data.verdicts_ignored).toBe(4); // c-acted no-edit-target, others with no signals
+        expect(data.memory_verdicts_total).toBe(8);
+        // Effectiveness = (reinforced + acted_on + caught) / total = 3/8 = 38%
+        expect(data.memory_effectiveness_pct).toBe(38);
+    });
+});

package/dist/__tests__/redactor.test.js

@@ -0,0 +1,120 @@
+/**
+ * ST-6: Redactor + archive job.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { archiveShadowLedger } from "../tracking/ledger-archiver.js";
+import { redactArgs, redactString } from "../tracking/redactor.js";
+import { ShadowLedger } from "../tracking/shadow-ledger.js";
+describe("redactString", () => {
+    it("redacts Anthropic-style sk-... keys", () => {
+        expect(redactString("API key: sk-abc123def456ghi789jklmno")).toBe("API key: <redacted>");
+    });
+    it("redacts GitHub PATs", () => {
+        expect(redactString("ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")).toBe("<redacted>");
+    });
+    it("redacts Bearer headers", () => {
+        expect(redactString("Authorization: Bearer abc.def.ghi=")).toContain("<redacted>");
+    });
+    it("redacts password assignments", () => {
+        expect(redactString('password="hunter2"')).toContain("<redacted>");
+        expect(redactString("api_key=verysecret123")).toContain("<redacted>");
+    });
+    it("does not touch unrelated text", () => {
+        expect(redactString("just some normal log line")).toBe("just some normal log line");
+    });
+});
+describe("redactArgs", () => {
+    it("walks nested objects", () => {
+        const out = redactArgs({
+            file_path: "src/auth.ts",
+            env: { TOKEN: "ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" },
+            list: ["plain", "Bearer abcdefghijklmno12345"],
+        });
+        expect(out.file_path).toBe("src/auth.ts");
+        expect(out.env.TOKEN).toBe("<redacted>");
+        expect(out.list[1]).toContain("<redacted>");
+    });
+});
+describe("ShadowLedger redacts on record", () => {
+    let tempDir;
+    let unerrDir;
+    beforeEach(() => {
+        tempDir = join(tmpdir(), `unerr-redact-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        unerrDir = join(tempDir, ".unerr");
+        mkdirSync(unerrDir, { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    it("redacts a secret-looking arg before persisting", () => {
+        const ledger = new ShadowLedger(unerrDir);
+        ledger.record("shell", { command: "curl -H 'Authorization: Bearer abcdef0123456789'" }, {}, "main", "x");
+        const line = readFileSync(join(unerrDir, "ledger", "shadow.jsonl"), "utf-8").trim();
+        expect(line).toContain("<redacted>");
+        expect(line).not.toContain("abcdef0123456789");
+    });
+});
+describe("archiveShadowLedger", () => {
+    let tempDir;
+    let unerrDir;
+    beforeEach(() => {
+        tempDir = join(tmpdir(), `unerr-arch-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        unerrDir = join(tempDir, ".unerr");
+        mkdirSync(join(unerrDir, "ledger"), { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    it("splits old entries into a gzipped archive and keeps recent ones", () => {
+        const filePath = join(unerrDir, "ledger", "shadow.jsonl");
+        const now = Date.parse("2026-05-12T00:00:00Z");
+        const old = JSON.stringify({
+            id: "1",
+            ts: new Date(now - 10 * 24 * 60 * 60_000).toISOString(),
+            tool: "file_read",
+        });
+        const recent = JSON.stringify({
+            id: "2",
+            ts: new Date(now - 60_000).toISOString(),
+            tool: "file_read",
+        });
+        writeFileSync(filePath, `${old}\n${recent}\n`, "utf-8");
+        const result = archiveShadowLedger(unerrDir, { nowMs: now });
+        expect(result.archived).toBe(1);
+        expect(result.kept).toBe(1);
+        expect(result.archivePath).not.toBeNull();
+        expect(existsSync(result.archivePath)).toBe(true);
+        const decoded = gunzipSync(readFileSync(result.archivePath)).toString("utf-8");
+        expect(decoded).toContain('"id":"1"');
+        const remaining = readFileSync(filePath, "utf-8").trim();
+        expect(remaining).toContain('"id":"2"');
+        expect(remaining).not.toContain('"id":"1"');
+    });
+    it("is a no-op when nothing is older than the cutoff", () => {
+        const filePath = join(unerrDir, "ledger", "shadow.jsonl");
+        const now = Date.parse("2026-05-12T00:00:00Z");
+        const line = JSON.stringify({
+            id: "1",
+            ts: new Date(now - 60_000).toISOString(),
+            tool: "file_read",
+        });
+        writeFileSync(filePath, `${line}\n`, "utf-8");
+        const result = archiveShadowLedger(unerrDir, { nowMs: now });
+        expect(result.archived).toBe(0);
+        expect(result.archivePath).toBeNull();
+    });
+});

package/dist/__tests__/resource-monitor.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { createResourceMonitor, getDegradationConfig, getResourceSnapshot, } from "../intelligence/indexer/resource-monitor.js";
+describe("Resource Monitor (L2.6)", () => {
+    it("produces a valid resource snapshot", () => {
+        const snap = getResourceSnapshot();
+        expect(snap.heapUsedMB).toBeGreaterThan(0);
+        expect(snap.heapTotalMB).toBeGreaterThan(0);
+        expect(snap.heapPercentage).toBeGreaterThanOrEqual(0);
+        expect(snap.heapPercentage).toBeLessThanOrEqual(1);
+        expect(snap.rss).toBeGreaterThan(0);
+        expect([0, 1, 2, 3]).toContain(snap.degradationLevel);
+    });
+    it("creates and stops monitor without errors", () => {
+        const monitor = createResourceMonitor(60_000);
+        monitor.start();
+        const snap = monitor.getSnapshot();
+        expect(snap.heapUsedMB).toBeGreaterThan(0);
+        monitor.stop();
+    });
+});
+describe("Progressive Degradation (L2.7)", () => {
+    it("level 0: full parallelism", () => {
+        const config = getDegradationConfig(0, 4);
+        expect(config.maxWorkers).toBe(4);
+        expect(config.scipEnabled).toBe(true);
+        expect(config.batchSize).toBe(50);
+    });
+    it("level 1: reduced workers", () => {
+        const config = getDegradationConfig(1, 4);
+        expect(config.maxWorkers).toBe(2);
+        expect(config.scipEnabled).toBe(true);
+        expect(config.batchSize).toBe(25);
+    });
+    it("level 2: single worker, SCIP paused", () => {
+        const config = getDegradationConfig(2, 4);
+        expect(config.maxWorkers).toBe(1);
+        expect(config.scipEnabled).toBe(false);
+        expect(config.batchSize).toBe(10);
+    });
+    it("level 3: emergency mode", () => {
+        const config = getDegradationConfig(3, 4);
+        expect(config.maxWorkers).toBe(1);
+        expect(config.scipEnabled).toBe(false);
+        expect(config.batchSize).toBe(5);
+    });
+    it("degradation callback fires on level change", () => {
+        const monitor = createResourceMonitor(100_000);
+        let lastLevel = null;
+        monitor.onDegradationChange((level) => {
+            lastLevel = level;
+        });
+        monitor.start();
+        const config = monitor.getConfig();
+        expect(config.maxWorkers).toBeGreaterThanOrEqual(1);
+        monitor.stop();
+    });
+});

package/dist/__tests__/response-envelope.test.js

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { createEnvelopePipeline, estimateTokens, wrapResponse, } from "../proxy/response-envelope.js";
+describe("estimateTokens", () => {
+    it("estimates tokens for a short string", () => {
+        const tokens = estimateTokens("hello world");
+        expect(tokens).toBeGreaterThan(0);
+        expect(tokens).toBeLessThan(20);
+    });
+    it("handles objects by serializing to JSON", () => {
+        const obj = { key: "value", nested: { a: 1 } };
+        const tokens = estimateTokens(obj);
+        expect(tokens).toBeGreaterThan(0);
+    });
+    it("returns 0 for null/undefined", () => {
+        expect(estimateTokens(null)).toBe(0);
+        expect(estimateTokens(undefined)).toBe(0);
+    });
+    it("handles empty string", () => {
+        expect(estimateTokens("")).toBe(0);
+    });
+});
+describe("wrapResponse", () => {
+    it("wraps content with _meta fields", async () => {
+        const result = await wrapResponse({ data: "test" }, 5.2);
+        expect(result.content).toEqual({ data: "test" });
+        expect(result._meta["dev.unerr/version"]).toBe("0.1.0");
+        expect(result._meta["dev.unerr/latency_ms"]).toBe(5.2);
+        expect(result._meta["dev.unerr/tokens_saved"]).toBeGreaterThanOrEqual(0);
+    });
+    it("calculates token savings when originalTokens provided", async () => {
+        const result = await wrapResponse("short", 1, 1000);
+        expect(result._meta["dev.unerr/tokens_saved"]).toBeGreaterThan(0);
+    });
+    it("never returns negative token savings", async () => {
+        const result = await wrapResponse("a very long response string", 1, 1);
+        expect(result._meta["dev.unerr/tokens_saved"]).toBe(0);
+    });
+    it("does not include _context when no injectors provide data", async () => {
+        const result = await wrapResponse("test", 1);
+        expect(result._context).toBeUndefined();
+    });
+});
+describe("createEnvelopePipeline", () => {
+    it("runs injectors and merges _context", async () => {
+        const injector = {
+            key: "test",
+            inject: () => ({ "dev.unerr/test": { hello: "world" } }),
+        };
+        const pipeline = createEnvelopePipeline([injector]);
+        const result = await pipeline.wrapResponse("content", 1);
+        expect(result._context).toBeDefined();
+        expect(result._context?.["dev.unerr/test"]).toEqual({ hello: "world" });
+    });
+    it("handles injector returning null", async () => {
+        const injector = {
+            key: "noop",
+            inject: () => null,
+        };
+        const pipeline = createEnvelopePipeline([injector]);
+        const result = await pipeline.wrapResponse("content", 1);
+        expect(result._context).toBeUndefined();
+    });
+    it("swallows injector errors silently", async () => {
+        const injector = {
+            key: "boom",
+            inject: () => {
+                throw new Error("injector crashed");
+            },
+        };
+        const pipeline = createEnvelopePipeline([injector]);
+        const result = await pipeline.wrapResponse("content", 1);
+        expect(result.content).toBe("content");
+        expect(result._meta["dev.unerr/version"]).toBe("0.1.0");
+    });
+    it("merges multiple injectors", async () => {
+        const injectors = [
+            { key: "a", inject: () => ({ alpha: 1 }) },
+            { key: "b", inject: () => ({ beta: 2 }) },
+        ];
+        const pipeline = createEnvelopePipeline(injectors);
+        const result = await pipeline.wrapResponse("content", 1);
+        expect(result._context?.alpha).toBe(1);
+        expect(result._context?.beta).toBe(2);
+    });
+    it("passes tool metadata to injectors", async () => {
+        let capturedArgs;
+        const injector = {
+            key: "spy",
+            inject: (args) => {
+                capturedArgs = args;
+                return null;
+            },
+        };
+        const pipeline = createEnvelopePipeline([injector]);
+        await pipeline.wrapResponse("content", 5, "get_function", { key: "abc" }, 100);
+        const args = capturedArgs;
+        expect(args.toolName).toBe("get_function");
+        expect(args.toolArgs.key).toBe("abc");
+    });
+});

package/dist/__tests__/risk-classifier.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { classifyAllRisks, classifyRisk, detectBridges, } from "../intelligence/risk-classifier.js";
+describe("Risk Classifier (M.4)", () => {
+    it("classifies high fan-in entity as critical", () => {
+        const result = classifyRisk("hub", 60, false, false, false);
+        expect(result.level).toBe("critical");
+        expect(result.score).toBeGreaterThanOrEqual(35);
+        expect(result.reasoning).toContain("chokepoint");
+    });
+    it("classifies bridge entity with elevated risk", () => {
+        const result = classifyRisk("bridge", 10, true, false, false);
+        expect(["high", "medium"]).toContain(result.level);
+        expect(result.reasoning).toContain("bridges");
+    });
+    it("classifies entity with mutations as higher risk", () => {
+        const result = classifyRisk("mutator", 5, false, true, false);
+        expect(result.score).toBeGreaterThan(classifyRisk("pure", 5, false, false, false).score);
+    });
+    it("reduces risk when entity is guarded", () => {
+        const unguarded = classifyRisk("fn", 30, false, false, false);
+        const guarded = classifyRisk("fn", 30, false, false, true);
+        expect(guarded.score).toBeLessThanOrEqual(unguarded.score);
+    });
+    it("classifies low-risk entity as low", () => {
+        const result = classifyRisk("simple", 2, false, false, false);
+        expect(result.level).toBe("low");
+        expect(result.score).toBeLessThan(25);
+    });
+    it("fan-in of 20+ triggers high classification", () => {
+        const result = classifyRisk("busy", 25, false, false, false);
+        expect(["high", "medium"]).toContain(result.level);
+        expect(result.reasoning).toContain("callers");
+    });
+    it("combines multiple factors", () => {
+        const result = classifyRisk("dangerous", 40, true, true, false);
+        expect(result.level).toBe("critical");
+        expect(result.factors.fanIn).toBeGreaterThan(0);
+        expect(result.factors.bridgeScore).toBeGreaterThan(0);
+        expect(result.factors.mutationScore).toBeGreaterThan(0);
+    });
+});
+describe("Bridge Detection (M.4)", () => {
+    it("detects entity bridging two communities", () => {
+        const edges = [
+            {
+                from_key: "bridge",
+                to_key: "a",
+                type: "calls",
+                file_path: "f.ts",
+                line: 1,
+            },
+            {
+                from_key: "bridge",
+                to_key: "b",
+                type: "calls",
+                file_path: "f.ts",
+                line: 2,
+            },
+        ];
+        const assignments = new Map([
+            ["bridge", 0],
+            ["a", 0],
+            ["b", 1],
+        ]);
+        expect(detectBridges("bridge", edges, assignments)).toBe(true);
+    });
+    it("non-bridge entity returns false", () => {
+        const edges = [
+            {
+                from_key: "local",
+                to_key: "neighbor",
+                type: "calls",
+                file_path: "f.ts",
+                line: 1,
+            },
+        ];
+        const assignments = new Map([
+            ["local", 0],
+            ["neighbor", 0],
+        ]);
+        expect(detectBridges("local", edges, assignments)).toBe(false);
+    });
+});
+describe("Batch Risk Classification", () => {
+    it("classifies all entities", () => {
+        const entities = [{ key: "a" }, { key: "b" }, { key: "c" }];
+        const fanInMap = new Map([
+            ["a", 50],
+            ["b", 5],
+            ["c", 0],
+        ]);
+        const edges = [];
+        const assignments = new Map();
+        const mutations = new Set(["b"]);
+        const guarded = new Set(["c"]);
+        const results = classifyAllRisks(entities, fanInMap, edges, assignments, mutations, guarded);
+        expect(results).toHaveLength(3);
+        expect(results[0]?.level).toBe("critical");
+        expect(results[1]?.factors.mutationScore).toBeGreaterThan(0);
+    });
+});

package/dist/__tests__/risk-signal-scope.test.js

@@ -0,0 +1,75 @@
+/**
+ * `ur|rsk` signal scope tests — verifies that array-shaped tool results
+ * (e.g. `get_references`) tag risk metadata with the max-risk neighbor's
+ * `entity_key`, and that `buildSignalPrefix` uses a composite dedup key
+ * so each new high-risk reference re-fires the signal instead of being
+ * suppressed by the queried entity's scope.
+ */
+import { beforeEach, describe, expect, it } from "vitest";
+import { buildSignalPrefix } from "../proxy/response-envelope.js";
+import { resetSignalDedupSingleton } from "../proxy/signal-dedup.js";
+describe("ur|rsk scope for reference-shaped results", () => {
+    beforeEach(() => {
+        resetSignalDedupSingleton();
+    });
+    it("emits ur|rsk when a high-risk caller is present (queried entity itself is low)", () => {
+        // Target is the queried entity (low risk). One of its callers is high risk.
+        // Without the envelope-aware extractor, this would emit no rsk at all.
+        const meta = {
+            entity_risk: {
+                fan_in: 24,
+                fan_out: 1,
+                risk_level: "high",
+                entity_key: "callerHigh",
+            },
+        };
+        const prefix = buildSignalPrefix(meta, undefined, "targetLow");
+        expect(prefix).toContain("ur|rsk");
+        expect(prefix).toContain("fan_in=24");
+    });
+    it("does not emit ur|rsk when no caller is high-risk", () => {
+        // No entity_risk on meta at all — extractor returned undefined for the
+        // all-normal-refs case.
+        const prefix = buildSignalPrefix({}, undefined, "targetLow");
+        expect(prefix).not.toContain("ur|rsk");
+    });
+    it("suppresses identical re-emission for the same target+ref pair (on_change dedup)", () => {
+        const meta = {
+            entity_risk: {
+                fan_in: 24,
+                fan_out: 1,
+                risk_level: "high",
+                entity_key: "callerHigh",
+            },
+        };
+        const first = buildSignalPrefix(meta, undefined, "targetLow");
+        const second = buildSignalPrefix(meta, undefined, "targetLow");
+        expect(first).toContain("ur|rsk");
+        expect(second).not.toContain("ur|rsk");
+    });
+    it("re-fires ur|rsk when the max-risk neighbor changes for the same queried entity", () => {
+        // First call: callerHigh1 is the worst offender.
+        const first = buildSignalPrefix({
+            entity_risk: {
+                fan_in: 24,
+                fan_out: 1,
+                risk_level: "high",
+                entity_key: "callerHigh1",
+            },
+        }, undefined, "targetLow");
+        // Second call (e.g. limit-paginated get_references): a different caller now
+        // tops the list. Composite key (target:ref:callerHigh2) is fresh, so emit.
+        const second = buildSignalPrefix({
+            entity_risk: {
+                fan_in: 30,
+                fan_out: 2,
+                risk_level: "high",
+                entity_key: "callerHigh2",
+            },
+        }, undefined, "targetLow");
+        expect(first).toContain("ur|rsk");
+        expect(first).toContain("fan_in=24");
+        expect(second).toContain("ur|rsk");
+        expect(second).toContain("fan_in=30");
+    });
+});