@unerr-ai/unerr 0.2.1 → 0.2.3

package/dist/tracking/causal-bridge.js

@@ -1,317 +0,0 @@
-/**
- * Causal Bridge — assembles causal chains linking AI interactions to code survival.
- *
- * Given an entity key, traces all AI interactions (from shadow ledger) through
- * commit associations to survival outcomes. Produces a CausalChain with per-interaction
- * survival classification and aggregate durability.
- *
- * Survival window: 24 hours. If an entity survives 24h without being reverted
- * or modified, the interaction is classified as "survived".
- *
- * Outcome classification:
- *   - survived: entity unchanged after 24h
- *   - reverted: entity reverted via git revert/checkout within 24h
- *   - human_modified: entity changed by human commit within 24h
- *   - ai_modified: entity changed by another AI interaction within 24h
- */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { gitQuery } from "../utils/exec.js";
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("causal-bridge");
-const SURVIVAL_WINDOW_MS = 24 * 60 * 60 * 1000;
-const AI_COMMIT_PATTERNS = [
-    /\bgenerated\b/i,
-    /\bauto[-\s]?generated\b/i,
-    /\bai[-\s]?assisted\b/i,
-    /\bcopilot\b/i,
-    /\bcursor\b/i,
-    /\bclaude\b/i,
-    /\bgpt\b/i,
-    /\bunerr\b/i,
-];
-export class CausalBridge {
-    unerrDir;
-    cwd;
-    commitCache = new Map();
-    constructor(unerrDir, cwd) {
-        this.unerrDir = unerrDir;
-        this.cwd = cwd;
-    }
-    async buildCausalChain(entityKey) {
-        const entityName = extractEntityName(entityKey);
-        const ledgerEntries = this.loadEntityLedgerEntries(entityKey);
-        if (ledgerEntries.length === 0) {
-            return {
-                entityKey,
-                entityName,
-                interactions: [],
-                durability: 1.0,
-                failureModes: [],
-            };
-        }
-        const commits = await this.loadEntityCommitHistory(entityKey);
-        const interactions = [];
-        const failureModeSet = new Set();
-        for (const entry of ledgerEntries) {
-            const interaction = await this.classifyInteraction(entry, commits, entityKey);
-            interactions.push(interaction);
-            if (!interaction.survived) {
-                failureModeSet.add(interaction.outcome);
-            }
-        }
-        const durability = computeAggregateDurability(interactions);
-        return {
-            entityKey,
-            entityName,
-            interactions,
-            durability,
-            failureModes: Array.from(failureModeSet),
-        };
-    }
-    async buildCausalChains(entityKeys) {
-        const chains = [];
-        for (const key of entityKeys) {
-            const chain = await this.buildCausalChain(key);
-            chains.push(chain);
-        }
-        return chains;
-    }
-    loadEntityLedgerEntries(entityKey) {
-        const ledgerPath = join(this.unerrDir, "ledger", "shadow.jsonl");
-        if (!existsSync(ledgerPath))
-            return [];
-        const content = readFileSync(ledgerPath, "utf-8");
-        const lines = content.split("\n").filter((l) => l.trim().length > 0);
-        const entries = [];
-        for (const line of lines) {
-            try {
-                const entry = JSON.parse(line);
-                if (entryReferencesEntity(entry, entityKey)) {
-                    entries.push(entry);
-                }
-            }
-            catch { }
-        }
-        return entries.sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
-    }
-    async loadEntityCommitHistory(entityKey) {
-        const filePath = entityKeyToFilePath(entityKey);
-        if (!filePath)
-            return [];
-        const raw = await gitQuery([
-            "log",
-            "--format=%H|%at|%s|%an",
-            "--follow",
-            "--diff-filter=ACDMR",
-            "--",
-            filePath,
-        ], this.cwd);
-        if (!raw)
-            return [];
-        const commits = [];
-        for (const line of raw.split("\n")) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            const parts = trimmed.split("|");
-            if (parts.length < 4)
-                continue;
-            const sha = parts[0];
-            const timestamp = Number.parseInt(parts[1], 10) * 1000;
-            const message = parts[2];
-            const author = parts.slice(3).join("|");
-            if (this.commitCache.has(sha)) {
-                commits.push(this.commitCache.get(sha));
-                continue;
-            }
-            const filesRaw = await gitQuery(["diff-tree", "--no-commit-id", "--name-only", "-r", sha], this.cwd);
-            const files = filesRaw
-                ? filesRaw
-                    .split("\n")
-                    .map((f) => f.trim())
-                    .filter(Boolean)
-                : [];
-            const info = { sha, timestamp, message, author, files };
-            this.commitCache.set(sha, info);
-            commits.push(info);
-        }
-        return commits.sort((a, b) => a.timestamp - b.timestamp);
-    }
-    async classifyInteraction(entry, commits, entityKey) {
-        const entryTs = new Date(entry.ts).getTime();
-        const prompt = extractPrompt(entry);
-        const commitSha = entry.commit_sha ?? "";
-        const sessionId = entry.session_id;
-        const subsequentCommits = commits.filter((c) => c.timestamp > entryTs && c.timestamp <= entryTs + SURVIVAL_WINDOW_MS);
-        if (subsequentCommits.length === 0) {
-            const timeSinceEntry = Date.now() - entryTs;
-            const survived = timeSinceEntry >= SURVIVAL_WINDOW_MS;
-            return {
-                prompt,
-                commitSha,
-                sessionId,
-                timestamp: entry.ts,
-                survived,
-                outcome: survived ? "survived" : "survived",
-                survivalMs: timeSinceEntry,
-            };
-        }
-        const filePath = entityKeyToFilePath(entityKey);
-        for (const commit of subsequentCommits) {
-            if (!filePath || !commit.files.includes(filePath))
-                continue;
-            const survivalMs = commit.timestamp - entryTs;
-            if (isRevertCommit(commit.message)) {
-                return {
-                    prompt,
-                    commitSha,
-                    sessionId,
-                    timestamp: entry.ts,
-                    survived: false,
-                    outcome: "reverted",
-                    survivalMs,
-                };
-            }
-            if (isAiCommit(commit.message)) {
-                return {
-                    prompt,
-                    commitSha,
-                    sessionId,
-                    timestamp: entry.ts,
-                    survived: false,
-                    outcome: "ai_modified",
-                    survivalMs,
-                };
-            }
-            return {
-                prompt,
-                commitSha,
-                sessionId,
-                timestamp: entry.ts,
-                survived: false,
-                outcome: "human_modified",
-                survivalMs,
-            };
-        }
-        return {
-            prompt,
-            commitSha,
-            sessionId,
-            timestamp: entry.ts,
-            survived: true,
-            outcome: "survived",
-            survivalMs: Date.now() - entryTs,
-        };
-    }
-}
-function computeAggregateDurability(interactions) {
-    if (interactions.length === 0)
-        return 1.0;
-    const survivedCount = interactions.filter((i) => i.survived).length;
-    return survivedCount / interactions.length;
-}
-function extractEntityName(entityKey) {
-    const parts = entityKey.split("::");
-    return parts[parts.length - 1] ?? entityKey;
-}
-function entityKeyToFilePath(entityKey) {
-    const fileMatch = entityKey.match(/^([^:]+)/);
-    if (!fileMatch)
-        return null;
-    return fileMatch[1];
-}
-function entryReferencesEntity(entry, entityKey) {
-    const argsStr = JSON.stringify(entry.args_summary);
-    if (argsStr.includes(entityKey))
-        return true;
-    const resultStr = JSON.stringify(entry.result_summary);
-    if (resultStr.includes(entityKey))
-        return true;
-    const filePath = entityKeyToFilePath(entityKey);
-    if (filePath && argsStr.includes(filePath))
-        return true;
-    return false;
-}
-function extractPrompt(entry) {
-    if (entry.plan_summary)
-        return entry.plan_summary;
-    const args = entry.args_summary;
-    if (typeof args.prompt === "string")
-        return args.prompt;
-    if (typeof args.message === "string")
-        return args.message;
-    if (typeof args.query === "string")
-        return args.query;
-    return `${entry.tool} call`;
-}
-function isRevertCommit(message) {
-    const lower = message.toLowerCase();
-    return (lower.startsWith("revert ") ||
-        lower.includes("revert:") ||
-        lower.includes("undo ") ||
-        lower.includes("rollback "));
-}
-function isAiCommit(message) {
-    return AI_COMMIT_PATTERNS.some((p) => p.test(message));
-}
-/**
- * Standalone causal chain assembly from pre-loaded ledger entries.
- * Does not require git — classifies based on entry data alone.
- */
-export function assembleCausalChain(entityKey, entries) {
-    const entityName = extractEntityName(entityKey);
-    const relevant = entries.filter((e) => entryReferencesEntity(e, entityKey));
-    const interactions = [];
-    const failureModeSet = new Set();
-    for (let i = 0; i < relevant.length; i++) {
-        const entry = relevant[i];
-        const entryTs = new Date(entry.ts).getTime();
-        const prompt = extractPrompt(entry);
-        const commitSha = entry.commit_sha ??
-            (typeof entry.result_summary.commit_sha === "string"
-                ? entry.result_summary.commit_sha
-                : "");
-        let survived = true;
-        let outcome = "survived";
-        let survivalMs = Date.now() - entryTs;
-        if (i + 1 < relevant.length) {
-            const nextEntry = relevant[i + 1];
-            const nextTs = new Date(nextEntry.ts).getTime();
-            survivalMs = nextTs - entryTs;
-            if (survivalMs < SURVIVAL_WINDOW_MS) {
-                survived = false;
-                outcome = "ai_modified";
-            }
-        }
-        interactions.push({
-            prompt,
-            commitSha,
-            sessionId: entry.session_id,
-            timestamp: entry.ts,
-            survived,
-            outcome,
-            survivalMs,
-        });
-        if (!survived) {
-            failureModeSet.add(outcome);
-        }
-    }
-    return {
-        entityKey,
-        entityName,
-        interactions,
-        durability: computeDurability(interactions),
-        failureModes: Array.from(failureModeSet),
-    };
-}
-/**
- * Computes aggregate durability from a set of interactions.
- * Durability = fraction of interactions that survived.
- */
-export function computeDurability(interactions) {
-    if (interactions.length === 0)
-        return 1.0;
-    const survivedCount = interactions.filter((i) => i.survived).length;
-    return survivedCount / interactions.length;
-}

package/dist/tracking/circuit-breaker.js

@@ -1,147 +0,0 @@
-/**
- * Sprint 10.6: Ledger Circuit Breaker — hallucination loop detection.
- *
- * Detects when the AI enters a fix-break-fix-break cycle:
- * >4 consecutive broken entries on the same entity within 10 minutes.
- * Attaches a circuit_breaker payload to the internal `meta` carrier, which
- * `buildSignalPrefix()` drains into a `ur|hlt` prefix line on the response.
- *
- * Design authority: Phase 5.5 §1.2.8b (Ledger Circuit Breaker)
- */
-/** stderr logger */
-const _log = {
-    info: (msg) => process.stderr.write(`[unerr:circuit-breaker] ${msg}\n`),
-    warn: (msg) => process.stderr.write(`[unerr:circuit-breaker] WARN: ${msg}\n`),
-};
-/** Threshold: consecutive failed modifications to trigger halt. */
-const CONSECUTIVE_THRESHOLD = 4;
-/** Window: 10 minutes in milliseconds. */
-const WINDOW_MS = 10 * 60 * 1000;
-export class LedgerCircuitBreaker {
-    /**
-     * Per-entity tracking of recent modification attempts.
-     * Key: entity name or entity key.
-     */
-    entityAttempts = new Map();
-    /**
-     * Entities currently halted. Cleared when entity changes or user resets.
-     */
-    haltedEntities = new Set();
-    /**
-     * Record a sync_local_diff that touched an entity.
-     * Call this after rule evaluation on sync.
-     */
-    recordAttempt(entity, hadViolations) {
-        const attempts = this.entityAttempts.get(entity) ?? [];
-        attempts.push({ timestamp: Date.now(), hadViolations });
-        this.entityAttempts.set(entity, attempts);
-        // Prune old attempts outside the window
-        this.pruneOldAttempts(entity);
-    }
-    /**
-     * Check if any entity has tripped the circuit breaker.
-     * Returns metadata to inject into _meta, or null if no trip.
-     */
-    check(entities) {
-        for (const entity of entities) {
-            if (this.haltedEntities.has(entity)) {
-                const attempts = this.entityAttempts.get(entity) ?? [];
-                return {
-                    triggered: true,
-                    entity,
-                    attempts: attempts.length,
-                    message: formatHaltMessage(entity, attempts.length),
-                };
-            }
-            const attempts = this.entityAttempts.get(entity) ?? [];
-            if (attempts.length < CONSECUTIVE_THRESHOLD)
-                continue;
-            // Check if last N attempts all had violations within the window
-            const now = Date.now();
-            const recentAttempts = attempts.filter((a) => now - a.timestamp < WINDOW_MS);
-            if (recentAttempts.length < CONSECUTIVE_THRESHOLD)
-                continue;
-            // Check if the last CONSECUTIVE_THRESHOLD attempts all had violations
-            const lastN = recentAttempts.slice(-CONSECUTIVE_THRESHOLD);
-            const allHadViolations = lastN.every((a) => a.hadViolations);
-            if (allHadViolations) {
-                this.haltedEntities.add(entity);
-                _log.warn(`Circuit breaker tripped for entity: ${entity} (${lastN.length} consecutive failures)`);
-                return {
-                    triggered: true,
-                    entity,
-                    attempts: lastN.length,
-                    message: formatHaltMessage(entity, lastN.length),
-                };
-            }
-        }
-        return null;
-    }
-    /**
-     * Reset the circuit breaker for a specific entity.
-     * Called when the entity changes externally or user provides new instruction.
-     */
-    reset(entity) {
-        this.haltedEntities.delete(entity);
-        this.entityAttempts.delete(entity);
-        _log.info(`Circuit breaker reset for: ${entity}`);
-    }
-    /**
-     * Reset all circuit breakers.
-     */
-    resetAll() {
-        this.haltedEntities.clear();
-        this.entityAttempts.clear();
-        _log.info("All circuit breakers reset");
-    }
-    /**
-     * Get list of currently halted entities.
-     */
-    getHaltedEntities() {
-        return [...this.haltedEntities];
-    }
-    /**
-     * Check if a specific entity is halted.
-     */
-    isHalted(entity) {
-        return this.haltedEntities.has(entity);
-    }
-    /**
-     * Generate _context injection for the response envelope.
-     * Returns null if no circuit breaker is triggered for the given entities.
-     */
-    toContextInjection(entities) {
-        const meta = this.check(entities);
-        if (!meta)
-            return null;
-        return {
-            "dev.unerr/circuit_breaker": {
-                triggered: meta.triggered,
-                entity: meta.entity,
-                attempts: meta.attempts,
-                message: meta.message,
-                action: "Review previous attempts before retrying. Consider a different approach.",
-            },
-        };
-    }
-    pruneOldAttempts(entity) {
-        const attempts = this.entityAttempts.get(entity);
-        if (!attempts)
-            return;
-        const cutoff = Date.now() - WINDOW_MS;
-        const pruned = attempts.filter((a) => a.timestamp > cutoff);
-        if (pruned.length === 0) {
-            this.entityAttempts.delete(entity);
-            this.haltedEntities.delete(entity);
-        }
-        else {
-            this.entityAttempts.set(entity, pruned);
-        }
-    }
-}
-/**
- * S9.4: Format halt message — clear, actionable, includes attempt count.
- */
-export function formatHaltMessage(entity, attempts) {
-    return `Stop. You've tried modifying ${entity} ${attempts} times with violations each time. Each attempt produced rule violations within the last 10 minutes. Consider a fundamentally different approach or ask the user for guidance.`;
-}

package/dist/tracking/commit-watcher.js

@@ -1,114 +0,0 @@
-/**
- * Commit Watcher — detects git commits by polling HEAD SHA.
- *
- * Polls `git rev-parse HEAD` every 5s (same cadence as branch poller).
- * When HEAD SHA changes:
- *   1. Extracts changed files via `git diff --name-only {old}..{new}`
- *   2. Calls IntentCorrelator.associateCommit(commitSha, files)
- *   3. Optionally triggers a flush callback
- *
- * All logging to stderr. Timer is unref'd so it doesn't keep the process alive.
- */
-import { getChangedFiles, getHeadSha } from "../utils/git.js";
-import { createModuleLogger } from "../utils/logger.js";
-import { encodeIntentAsNote } from "./intent-encoder.js";
-const log = createModuleLogger("commit");
-const DEFAULT_POLL_MS = 5_000;
-export class CommitWatcher {
-    cwd;
-    pollIntervalMs;
-    correlator;
-    onCommit;
-    timer = null;
-    lastHeadSha = null;
-    running = false;
-    sessionId;
-    branchContext = null;
-    driftSummaryFn = null;
-    constructor(correlator, opts = {}) {
-        this.cwd = opts.cwd ?? process.cwd();
-        this.pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_MS;
-        this.correlator = correlator;
-        this.onCommit = opts.onCommit;
-        this.sessionId = opts.sessionId ?? "";
-    }
-    /**
-     * Set branch context for git note encoding.
-     */
-    setBranchContext(ctx) {
-        this.branchContext = ctx;
-    }
-    /**
-     * Set drift summary provider for git note encoding.
-     */
-    setDriftSummaryFn(fn) {
-        this.driftSummaryFn = fn;
-    }
-    /**
-     * Start polling for commits. Captures initial HEAD SHA on first call.
-     */
-    async start() {
-        if (this.running)
-            return;
-        this.running = true;
-        this.lastHeadSha = await getHeadSha(this.cwd);
-        this.timer = setInterval(() => {
-            this.poll();
-        }, this.pollIntervalMs);
-        // Don't keep process alive just for commit watching
-        this.timer.unref();
-    }
-    /**
-     * Stop polling.
-     */
-    stop() {
-        this.running = false;
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-    }
-    /**
-     * Get the last known HEAD SHA (for testing/status).
-     */
-    getLastHeadSha() {
-        return this.lastHeadSha;
-    }
-    /**
-     * Force a poll cycle (useful for testing).
-     */
-    async poll() {
-        try {
-            const currentHead = await getHeadSha(this.cwd);
-            if (!currentHead)
-                return;
-            if (this.lastHeadSha && currentHead !== this.lastHeadSha) {
-                const files = await getChangedFiles(this.cwd, this.lastHeadSha, currentHead);
-                const associated = this.correlator.associateCommit(currentHead, files);
-                if (associated > 0) {
-                    log.info(`Commit ${currentHead.slice(0, 8)}: associated ${associated} pending correlation(s)`);
-                    const committed = this.correlator
-                        .getCommittedUnflushed()
-                        .filter((c) => c.commitSha === currentHead);
-                    if (committed.length > 0 && this.sessionId) {
-                        const drift = this.driftSummaryFn
-                            ? await this.driftSummaryFn()
-                            : {
-                                added: 0,
-                                modified: 0,
-                                deleted: 0,
-                            };
-                        encodeIntentAsNote(currentHead, committed, this.sessionId, this.branchContext, drift, this.cwd).catch(() => {
-                            /* fire-and-forget */
-                        });
-                    }
-                }
-                this.onCommit?.(currentHead, files, associated);
-            }
-            this.lastHeadSha = currentHead;
-        }
-        catch {
-            // Git errors are non-fatal — skip this cycle
-        }
-    }
-}

package/dist/tracking/context-ledger.js

@@ -1,119 +0,0 @@
-/**
- * Cross-Session Context Dedup Ledger — persists delivered _context keys
- * across sessions so repeated information isn't re-delivered.
- *
- * Stored in .unerr/state/context-ledger.json.
- * On session start, loads previous deliveries into the in-session dedup (C.4).
- *
- * Temporal intelligence note: this implements the warm tier of the
- * three-tier memory architecture (Section 13.8). Keys older than
- * TTL_DAYS are evicted to prevent unbounded growth.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-const TTL_DAYS = 7;
-const MAX_ENTRIES = 50_000;
-export function createContextLedger(unerrDir) {
-    const stateDir = join(unerrDir, "state");
-    const filePath = join(stateDir, "context-ledger.json");
-    let records = [];
-    let index = new Map();
-    function ensureDir() {
-        if (!existsSync(stateDir)) {
-            mkdirSync(stateDir, { recursive: true });
-        }
-    }
-    function compoundKey(entityKey, contextKey) {
-        return `${entityKey}::${contextKey}`;
-    }
-    function load() {
-        ensureDir();
-        if (!existsSync(filePath)) {
-            records = [];
-            index = new Map();
-            return new Map();
-        }
-        try {
-            const raw = readFileSync(filePath, "utf-8");
-            const parsed = JSON.parse(raw);
-            records = Array.isArray(parsed) ? parsed : [];
-        }
-        catch {
-            records = [];
-        }
-        index = new Map();
-        for (const r of records) {
-            let set = index.get(r.entityKey);
-            if (!set) {
-                set = new Set();
-                index.set(r.entityKey, set);
-            }
-            set.add(r.contextKey);
-        }
-        return new Map([...index.entries()].map(([k, v]) => [k, new Set(v)]));
-    }
-    function save(delivered) {
-        ensureDir();
-        const newRecords = [];
-        const now = new Date().toISOString();
-        for (const [entityKey, contextKeys] of delivered) {
-            for (const contextKey of contextKeys) {
-                const existing = records.find((r) => r.entityKey === entityKey && r.contextKey === contextKey);
-                newRecords.push({
-                    entityKey,
-                    contextKey,
-                    deliveredAt: existing?.deliveredAt ?? now,
-                });
-            }
-        }
-        records = newRecords;
-        index = delivered;
-        try {
-            writeFileSync(filePath, JSON.stringify(records, null, 2), "utf-8");
-        }
-        catch {
-            /* best effort */
-        }
-    }
-    function hasDelivered(entityKey, contextKey) {
-        const set = index.get(entityKey);
-        return set?.has(contextKey) ?? false;
-    }
-    function markDelivered(entityKey, contextKeys) {
-        let set = index.get(entityKey);
-        if (!set) {
-            set = new Set();
-            index.set(entityKey, set);
-        }
-        const now = new Date().toISOString();
-        for (const ck of contextKeys) {
-            if (!set.has(ck)) {
-                set.add(ck);
-                records.push({ entityKey, contextKey: ck, deliveredAt: now });
-            }
-        }
-    }
-    function getDeliveredCount() {
-        return records.length;
-    }
-    function prune() {
-        const cutoff = new Date(Date.now() - TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();
-        const before = records.length;
-        records = records.filter((r) => r.deliveredAt >= cutoff);
-        if (records.length > MAX_ENTRIES) {
-            records = records.slice(-MAX_ENTRIES);
-        }
-        index = new Map();
-        for (const r of records) {
-            let set = index.get(r.entityKey);
-            if (!set) {
-                set = new Set();
-                index.set(r.entityKey, set);
-            }
-            set.add(r.contextKey);
-        }
-        return before - records.length;
-    }
-    load();
-    return { load, save, hasDelivered, markDelivered, getDeliveredCount, prune };
-}