@unerr-ai/unerr 0.2.1 → 0.2.2

package/dist/tracking/native-watcher.js

@@ -1,131 +0,0 @@
-/**
- * Native file watcher — @parcel/watcher with debounced event emission.
- *
- * Uses OS-level file watching (FSEvents on macOS, inotify on Linux, ReadDirectoryChanges on Windows)
- * for millisecond-scale change detection. Events are debounced into batches (default 50ms window)
- * and deduplicated before emission.
- *
- * Respects .gitignore patterns and always excludes .unerr/, node_modules/, .git/.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("native-watcher");
-const ALWAYS_IGNORE_DIRS = [".unerr", "node_modules", ".git"];
-function loadGitignorePatterns(projectRoot) {
-    const gitignorePath = path.join(projectRoot, ".gitignore");
-    try {
-        if (!fs.existsSync(gitignorePath))
-            return [];
-        const content = fs.readFileSync(gitignorePath, "utf-8");
-        return content
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line && !line.startsWith("#"));
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Build ignore list for @parcel/watcher. Uses relative directory names
- * so the wrapper resolves them against the (real) watched directory,
- * avoiding symlink mismatches (e.g. /tmp → /private/tmp on macOS).
- */
-function buildIgnoreList(projectRoot, extra = []) {
-    const patterns = [...ALWAYS_IGNORE_DIRS];
-    for (const pattern of loadGitignorePatterns(projectRoot)) {
-        patterns.push(pattern.startsWith("/") ? pattern.slice(1) : pattern);
-    }
-    for (const pattern of extra) {
-        patterns.push(pattern);
-    }
-    return patterns;
-}
-export function createNativeWatcher(opts) {
-    const { projectRoot, debounceMs = 50, ignorePatterns = [], onEvents } = opts;
-    let subscription = null;
-    let running = false;
-    let debounceTimer = null;
-    let pendingEvents = [];
-    function flushEvents() {
-        if (pendingEvents.length === 0)
-            return;
-        const deduped = new Map();
-        for (const evt of pendingEvents) {
-            deduped.set(evt.path, evt);
-        }
-        const batch = Array.from(deduped.values());
-        pendingEvents = [];
-        try {
-            onEvents(batch);
-        }
-        catch (err) {
-            log.error("Error in onEvents callback:", err);
-        }
-    }
-    function scheduleFlush() {
-        if (debounceTimer !== null)
-            return;
-        debounceTimer = setTimeout(() => {
-            debounceTimer = null;
-            flushEvents();
-        }, debounceMs);
-        debounceTimer.unref();
-    }
-    async function start() {
-        if (running)
-            return;
-        let subscribeFn;
-        try {
-            const mod = await import("@parcel/watcher");
-            subscribeFn = mod.subscribe;
-        }
-        catch (err) {
-            log.warn("@parcel/watcher native bindings unavailable — file watching disabled.", err instanceof Error ? err.message : String(err));
-            return;
-        }
-        const resolvedRoot = fs.realpathSync(projectRoot);
-        const ignore = buildIgnoreList(resolvedRoot, ignorePatterns);
-        log.debug("Starting native watcher", { projectRoot: resolvedRoot, ignore });
-        subscription = await subscribeFn(resolvedRoot, (err, events) => {
-            if (err) {
-                log.error("Watcher error:", err);
-                return;
-            }
-            for (const evt of events) {
-                const rel = path.relative(resolvedRoot, evt.path);
-                const segs = rel.split(path.sep);
-                if (segs.some((s) => ALWAYS_IGNORE_DIRS.includes(s)))
-                    continue;
-                pendingEvents.push({
-                    type: evt.type,
-                    path: evt.path,
-                });
-            }
-            if (pendingEvents.length > 0)
-                scheduleFlush();
-        }, { ignore });
-        running = true;
-        log.debug("Native watcher started");
-    }
-    async function stop() {
-        if (!running)
-            return;
-        if (debounceTimer !== null) {
-            clearTimeout(debounceTimer);
-            debounceTimer = null;
-            flushEvents();
-        }
-        if (subscription) {
-            await subscription.unsubscribe();
-            subscription = null;
-        }
-        running = false;
-        log.debug("Native watcher stopped");
-    }
-    function isRunning() {
-        return running;
-    }
-    return { start, stop, isRunning };
-}

package/dist/tracking/offline-rewind.js

@@ -1,295 +0,0 @@
-/**
- * Offline Rewind — Zero-Network rewind using CozoDB + local git.
- * Phase 5.5 §1.3.4 (P5.5-CB-03)
- *
- * When the user is offline, this module performs a filesystem-level rewind
- * using the local CozoDB graph for blast radius computation and git for
- * file restoration.
- *
- * Integration Points:
- *   • P10 Bridge: Reads shadow ledger entries from .unerr/ledger/shadow.jsonl
- *   • P13 Bridge: Uses `git checkout {ref} -- {files}` for atomic file restore
- *   • P5.5 Bridge: On connectivity restore, flushes simulated rewind via sync-intent
- *
- * Invariant: Offline rewind produces identical file state as online rewind.
- * Difference: Anti-pattern rule synthesis deferred until connectivity (requires LLM).
- *
- * Blast radius resolution target: <200ms (CozoDB is in-process, no network).
- */
-import { randomBytes } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
-import { join } from "node:path";
-import { checkoutFile } from "../utils/git.js";
-import { createModuleLogger } from "../utils/logger.js";
-const log = createModuleLogger("offline-rewind");
-// ── Core Logic ─────────────────────────────────────────────────────────────
-/**
- * Perform an offline rewind using local resources only.
- *
- * Steps (per §1.3.4):
- *   1. Read local ledger entries from shadow.jsonl
- *   2. Identify the target entry and entries to revert
- *   3. Compute blast radius using CozoDB (entity lookup + 1-hop callers)
- *   4. If not dry run: apply file restores via `git checkout`
- *   5. Update local state: shadow.jsonl, branch_context.json, drift overlay
- */
-export async function offlineRewind(input) {
-    const startTime = Date.now();
-    const { targetEntryId, cwd, unerrDir, graph, ledger, dryRun } = input;
-    try {
-        // ── Step 1: Read local ledger entries ─────────────────────────────
-        const allEntries = ledger.readAllEntries();
-        const targetEntry = allEntries.find((e) => e.id === targetEntryId);
-        if (!targetEntry) {
-            return errorResult(`Target entry ${targetEntryId} not found in local ledger`);
-        }
-        // ── Step 2: Identify entries to revert ────────────────────────────
-        // All entries created AFTER the target, on the same branch, not already reverted
-        const entriesToRevert = allEntries.filter((e) => e.branch === targetEntry.branch &&
-            e.ts > targetEntry.ts &&
-            e.id !== targetEntryId &&
-            !e.result_summary?.rewind_status);
-        // Collect all files changed in entries to revert
-        const filesToRevert = new Set();
-        for (const entry of entriesToRevert) {
-            const files = extractFilesFromEntry(entry);
-            for (const f of files)
-                filesToRevert.add(f);
-        }
-        // Files in the target entry
-        const targetFiles = new Set(extractFilesFromEntry(targetEntry));
-        // ── Step 3: Compute blast radius using CozoDB (<200ms) ────────────
-        const blastRadius = await computeLocalBlastRadius(graph, Array.from(filesToRevert), targetFiles, startTime);
-        if (dryRun) {
-            return {
-                status: "dry_run",
-                rewindEntryId: null,
-                timelineBranch: readBranchCounter(unerrDir),
-                entriesReverted: entriesToRevert.length,
-                blastRadius,
-                filesRestored: [],
-            };
-        }
-        // ── Step 4: Apply file restores via git checkout ──────────────────
-        const filesRestored = [];
-        const safeToRestore = blastRadius.safeFiles;
-        if (safeToRestore.length > 0) {
-            // Find the HEAD SHA to restore from (target entry's head_sha)
-            const restoreRef = targetEntry.head_sha;
-            if (restoreRef) {
-                for (const filePath of safeToRestore) {
-                    try {
-                        await checkoutFile(cwd, restoreRef, filePath);
-                        filesRestored.push(filePath);
-                    }
-                    catch {
-                        log.warn(`Could not restore ${filePath}`);
-                    }
-                }
-            }
-        }
-        // ── Step 5: Update local state ────────────────────────────────────
-        // 5a. Increment timeline branch
-        const newBranch = incrementBranchCounter(unerrDir);
-        // 5b. Create rewind entry in shadow.jsonl
-        const rewindEntryId = generateId();
-        const rewindEntry = {
-            id: rewindEntryId,
-            ts: new Date().toISOString(),
-            tool: "revert_to_working_state",
-            args_summary: { target_entry_id: targetEntryId, offline: true },
-            result_summary: {
-                rewind_status: "simulated",
-                entries_reverted: entriesToRevert.length,
-                files_restored: filesRestored.length,
-                timeline_branch: newBranch,
-                rewind_target_id: targetEntryId,
-                blast_radius: {
-                    safeFiles: blastRadius.safeFiles,
-                    conflictedFiles: blastRadius.conflictedFiles.map((f) => f.filePath),
-                },
-            },
-            branch: targetEntry.branch,
-            head_sha: targetEntry.head_sha,
-            session_id: ledger.getSessionId(),
-            correlation_id: null,
-        };
-        // Append to shadow.jsonl
-        const ledgerPath = join(unerrDir, "ledger", "shadow.jsonl");
-        appendFileSync(ledgerPath, `${JSON.stringify(rewindEntry)}\n`, "utf-8");
-        // 5c. Mark intermediate entries as reverted locally
-        markEntriesReverted(unerrDir, entriesToRevert.map((e) => e.id));
-        // 5d. Clear drift overlay for reverted files (they're now at target state)
-        for (const _filePath of filesRestored) {
-            await graph.clearDriftOverlay();
-        }
-        return {
-            status: "simulated",
-            rewindEntryId,
-            timelineBranch: newBranch,
-            entriesReverted: entriesToRevert.length,
-            blastRadius,
-            filesRestored,
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return errorResult(message);
-    }
-}
-// ── Blast Radius Computation (CozoDB, <200ms) ─────────────────────────────
-async function computeLocalBlastRadius(graph, revertFiles, targetFiles, startTime) {
-    const safeFiles = [];
-    const conflictedFiles = [];
-    const affectedEntities = [];
-    const callerKeys = new Set();
-    for (const filePath of revertFiles) {
-        // Conflict: file exists in both target and reverted entries
-        if (targetFiles.has(filePath)) {
-            conflictedFiles.push({
-                filePath,
-                reason: "File modified in both target and reverted entries",
-            });
-        }
-        else {
-            safeFiles.push(filePath);
-        }
-        // Entity lookup via CozoDB file_index (in-process, <10ms)
-        const entities = await graph.getEntitiesByFile(filePath);
-        for (const entity of entities) {
-            affectedEntities.push({
-                key: entity.key,
-                name: entity.name,
-                filePath: entity.file_path,
-                riskLevel: entity.risk_level,
-            });
-            // 1-hop callers via CozoDB edges (pre-indexed, <50ms)
-            const callers = await graph.getCallersOf(entity.key);
-            for (const caller of callers) {
-                callerKeys.add(caller.key);
-            }
-        }
-    }
-    return {
-        safeFiles,
-        conflictedFiles,
-        affectedEntities,
-        affectedCallers: callerKeys.size,
-        resolvedInMs: Date.now() - startTime,
-    };
-}
-// ── Local State Helpers ────────────────────────────────────────────────────
-/**
- * Read the current timeline branch counter from branch_context.json.
- */
-function readBranchCounter(unerrDir) {
-    const contextPath = join(unerrDir, "ledger", "branch_context.json");
-    if (!existsSync(contextPath))
-        return 1;
-    try {
-        const data = JSON.parse(readFileSync(contextPath, "utf-8"));
-        return data.timeline_branch ?? 1;
-    }
-    catch {
-        return 1;
-    }
-}
-/**
- * Increment the timeline branch counter and return the new value.
- */
-function incrementBranchCounter(unerrDir) {
-    const contextPath = join(unerrDir, "ledger", "branch_context.json");
-    const ledgerDir = join(unerrDir, "ledger");
-    if (!existsSync(ledgerDir)) {
-        mkdirSync(ledgerDir, { recursive: true });
-    }
-    let data = {};
-    if (existsSync(contextPath)) {
-        try {
-            data = JSON.parse(readFileSync(contextPath, "utf-8"));
-        }
-        catch {
-            // Start fresh
-        }
-    }
-    const current = typeof data.timeline_branch === "number" ? data.timeline_branch : 1;
-    const next = current + 1;
-    data.timeline_branch = next;
-    data.last_rewind_at = new Date().toISOString();
-    writeFileSync(contextPath, JSON.stringify(data, null, 2), "utf-8");
-    return next;
-}
-/**
- * Mark entries as reverted in the pending_correlations.json file.
- * These entries are tracked locally as reverted.
- */
-function markEntriesReverted(unerrDir, entryIds) {
-    if (entryIds.length === 0)
-        return;
-    const revertedPath = join(unerrDir, "ledger", "reverted_entries.json");
-    const ledgerDir = join(unerrDir, "ledger");
-    if (!existsSync(ledgerDir)) {
-        mkdirSync(ledgerDir, { recursive: true });
-    }
-    let existing = [];
-    if (existsSync(revertedPath)) {
-        try {
-            existing = JSON.parse(readFileSync(revertedPath, "utf-8"));
-        }
-        catch {
-            // Start fresh
-        }
-    }
-    const merged = Array.from(new Set([...existing, ...entryIds]));
-    writeFileSync(revertedPath, JSON.stringify(merged, null, 2), "utf-8");
-}
-/**
- * Extract file paths from a shadow ledger entry's args_summary.
- */
-function extractFilesFromEntry(entry) {
-    const files = [];
-    // Check args_summary for file references
-    const args = entry.args_summary;
-    if (Array.isArray(args.files)) {
-        for (const f of args.files) {
-            if (typeof f === "string")
-                files.push(f);
-            else if (f &&
-                typeof f.file_path === "string") {
-                files.push(f.file_path);
-            }
-        }
-    }
-    if (typeof args.file_path === "string")
-        files.push(args.file_path);
-    // Check result_summary for affected files
-    const result = entry.result_summary;
-    if (Array.isArray(result.files_changed)) {
-        for (const f of result.files_changed) {
-            if (typeof f === "string")
-                files.push(f);
-        }
-    }
-    return files;
-}
-// ── Utilities ──────────────────────────────────────────────────────────────
-function generateId() {
-    return randomBytes(6).toString("hex");
-}
-function errorResult(message) {
-    return {
-        status: "error",
-        rewindEntryId: null,
-        timelineBranch: 0,
-        entriesReverted: 0,
-        blastRadius: {
-            safeFiles: [],
-            conflictedFiles: [],
-            affectedEntities: [],
-            affectedCallers: 0,
-            resolvedInMs: 0,
-        },
-        filesRestored: [],
-        errorMessage: message,
-    };
-}

package/dist/tracking/pending-violations.js

@@ -1,74 +0,0 @@
-/**
- * Sprint 7.3: Pending Violation Store — push-based rule enforcement safety net.
- *
- * Stores rule violations detected by file-watcher-triggered rule evaluation.
- * Violations attach to the internal `context` carrier on the next MCP response
- * and surface as `ur|wrn` prefix lines (then cleared).
- *
- * Flow:
- *   File change → DriftTracker → evaluateRules → store violations here
- *   Next MCP tool call → QueryRouter drains pending violations → `ur|wrn` prefix lines
- */
-export class PendingViolationStore {
-    violations = new Map();
-    /**
-     * Add violations from a file change. Replaces any existing violations for that file.
-     */
-    addViolations(filePath, violations) {
-        if (violations.length === 0) {
-            this.violations.delete(filePath);
-            return;
-        }
-        this.violations.set(filePath, violations.map((v) => ({
-            file: v.filePath,
-            rule: v.ruleName,
-            message: v.message,
-            line: v.line,
-        })));
-    }
-    /**
-     * Drain all pending violations — returns them and clears the store.
-     * Returns undefined if no violations pending.
-     */
-    drain() {
-        if (this.violations.size === 0)
-            return undefined;
-        const all = [];
-        for (const [, vs] of this.violations) {
-            all.push(...vs);
-        }
-        this.violations.clear();
-        return all;
-    }
-    /**
-     * Drain violations for specific files only.
-     * Returns undefined if no violations pending for those files.
-     */
-    drainForFiles(filePaths) {
-        const result = [];
-        for (const fp of filePaths) {
-            const vs = this.violations.get(fp);
-            if (vs) {
-                result.push(...vs);
-                this.violations.delete(fp);
-            }
-        }
-        return result.length > 0 ? result : undefined;
-    }
-    /** Check if any violations are pending. */
-    get hasPending() {
-        return this.violations.size > 0;
-    }
-    /** Total number of pending violations across all files. */
-    get count() {
-        let total = 0;
-        for (const [, vs] of this.violations) {
-            total += vs.length;
-        }
-        return total;
-    }
-    /** Clear all pending violations. */
-    clear() {
-        this.violations.clear();
-    }
-}

package/dist/tracking/persistence-effectiveness.js

@@ -1,167 +0,0 @@
-/**
- * Persistent Memory Effectiveness Tracker.
- *
- * Surfaces the "was this signal load-bearing?" question for the /reasoning
- * dashboard. Tracks fact/convention/resume/negative-warning injections as
- * open windows, then evaluates each window's verdict on turn close.
- *
- * Verdicts (emitted as TokenFlow events, mechanism: "persistent_memory"):
- *   reinforced  – same signal re-surfaced, no correction observed
- *   acted_on    – entity edited within window, no rollback / circuit-breaker
- *   ignored     – window closed without any observable downstream activity
- *   corrected   – circuit-breaker / drift / blast-radius fired for same entity
- *   caught      – (negative-fact only) anti-pattern warned, no recurrence
- *
- * Fired events also emit (with verdict:"fired") so the dashboard can count
- * raw surface volume separately from outcome.
- */
-export class PersistenceEffectivenessTracker {
-    tokenFlow;
-    windowTurns;
-    tokensPerSignal;
-    open = new Map();
-    constructor(tokenFlow, options = {}) {
-        this.tokenFlow = tokenFlow;
-        this.windowTurns = options.windowTurns ?? 5;
-        this.tokensPerSignal = options.tokensPerSignal ?? 60;
-    }
-    /**
-     * Record that a persistent-memory signal was injected/surfaced.
-     * Emits a "fired" verdict event immediately AND opens a window for later
-     * verdict resolution. Re-firing the same (kind, signal_id) within an open
-     * window counts as a reinforcement, not a new fired event.
-     */
-    recordSignalFired(p) {
-        const sessionId = p.session_id ?? this.tokenFlow.sessionId;
-        const key = `${p.kind}:${p.signal_id}`;
-        const existing = this.open.get(key);
-        if (existing) {
-            existing.reinforcements++;
-            return;
-        }
-        this.open.set(key, {
-            kind: p.kind,
-            signal_id: p.signal_id,
-            entity_key: p.entity_key ?? null,
-            session_id: sessionId,
-            fired_turn: p.turn,
-            fired_at_ms: Date.now(),
-            reinforcements: 0,
-            corrections: 0,
-            edits: 0,
-        });
-        this.emit({
-            verdict: "fired",
-            kind: p.kind,
-            signal_id: p.signal_id,
-            entity_key: p.entity_key ?? null,
-            session_id: sessionId,
-            turn: p.turn,
-            reinforcements: 0,
-            corrections: 0,
-            edits: 0,
-        });
-    }
-    /**
-     * Observed correction for an entity (circuit-breaker, drift, blast-radius
-     * warning, convention-violation auto-fire). Counts against any open signal
-     * scoped to the same entity_key.
-     */
-    recordCorrection(entityKey, type) {
-        if (!entityKey)
-            return;
-        for (const s of this.open.values()) {
-            if (s.entity_key === entityKey) {
-                s.corrections++;
-            }
-        }
-        // type captured for future detail enrichment
-        void type;
-    }
-    /**
-     * Observed Edit/Write on an entity. Counts toward "acted_on" verdict for
-     * any open signal scoped to the same entity_key.
-     */
-    recordEdit(entityKey) {
-        if (!entityKey)
-            return;
-        for (const s of this.open.values()) {
-            if (s.entity_key === entityKey) {
-                s.edits++;
-            }
-        }
-    }
-    /**
-     * Evaluate all open signals whose window has closed (current_turn - fired_turn >= windowTurns).
-     * Emits one verdict event per closed signal.
-     */
-    closeWindow(currentTurn) {
-        for (const [key, s] of this.open) {
-            if (currentTurn - s.fired_turn < this.windowTurns)
-                continue;
-            this.emitVerdict(s);
-            this.open.delete(key);
-        }
-    }
-    /**
-     * Close every open window — called at session end. Forces a verdict for
-     * everything still open regardless of turn distance.
-     */
-    closeAll(currentTurn) {
-        for (const [key, s] of this.open) {
-            this.emitVerdict(s, currentTurn);
-            this.open.delete(key);
-        }
-    }
-    /** Number of signals still open (for testing / introspection). */
-    openCount() {
-        return this.open.size;
-    }
-    emitVerdict(s, _currentTurn) {
-        const verdict = this.classify(s);
-        this.emit({
-            verdict,
-            kind: s.kind,
-            signal_id: s.signal_id,
-            entity_key: s.entity_key,
-            session_id: s.session_id,
-            turn: s.fired_turn,
-            reinforcements: s.reinforcements,
-            corrections: s.corrections,
-            edits: s.edits,
-        });
-    }
-    classify(s) {
-        if (s.corrections > 0)
-            return "corrected";
-        if (s.kind === "negative_warned") {
-            // For negative facts the "no recurrence" case is the win — caught.
-            return "caught";
-        }
-        if (s.edits > 0)
-            return "acted_on";
-        if (s.reinforcements > 0)
-            return "reinforced";
-        return "ignored";
-    }
-    emit(p) {
-        this.tokenFlow.record({
-            session_id: p.session_id,
-            turn: p.turn,
-            mechanism: "persistent_memory",
-            tool: null,
-            tokens_without: 0,
-            tokens_with: this.tokensPerSignal,
-            tokens_saved: 0,
-            detail: {
-                kind: p.kind,
-                verdict: p.verdict,
-                signal_id: p.signal_id,
-                entity_key: p.entity_key,
-                reinforcements: p.reinforcements,
-                corrections: p.corrections,
-                edits: p.edits,
-            },
-        });
-    }
-}