dual-brain 0.2.30 → 0.3.1

package/dist/src/integrity.js

@@ -0,0 +1,206 @@
+/**
+ * integrity.ts — State integrity primitives for dual-brain
+ *
+ * Provides:
+ *   - atomicWriteJson / readJsonSafe   — safe JSON file I/O with schema versioning
+ *   - acquireLock / releaseLock / withLock — advisory file locks
+ *   - lockedUpdate                      — locked atomic read-modify-write
+ *   - atomicAppend                      — append-only ledger with lock
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Write JSON to filePath atomically via a temp file + rename.
+ * Adds _schemaVersion and _writtenAt to plain objects.
+ */
+export function atomicWriteJson(filePath, data, opts = {}) {
+    const { schemaVersion = 1, backup = false } = opts;
+    // Stamp schema version onto plain objects
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        data._schemaVersion = schemaVersion;
+        data._writtenAt = new Date().toISOString();
+    }
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+    const json = JSON.stringify(data, null, 2) + '\n';
+    // Write to temp file
+    writeFileSync(tmpPath, json);
+    // Validate the temp file is parseable before committing
+    try {
+        JSON.parse(readFileSync(tmpPath, 'utf8'));
+    }
+    catch (err) {
+        unlinkSync(tmpPath);
+        throw new Error(`atomicWrite: validation failed for ${filePath}: ${err.message}`);
+    }
+    // Optionally back up the existing file
+    if (backup && existsSync(filePath)) {
+        const backupPath = filePath + '.bak';
+        try {
+            renameSync(filePath, backupPath);
+        }
+        catch { }
+    }
+    // Atomic rename — either fully succeeds or the original is untouched
+    renameSync(tmpPath, filePath);
+}
+/**
+ * Read and parse a JSON file safely, with optional schema migration.
+ * Falls back to a .bak copy on parse failure.
+ * Returns null when the file is absent or unrecoverable.
+ */
+export function readJsonSafe(filePath, opts = {}) {
+    const { expectedVersion, migrate } = opts;
+    if (!existsSync(filePath))
+        return null;
+    let data;
+    try {
+        data = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        // Primary file corrupt — try backup
+        const bakPath = filePath + '.bak';
+        if (existsSync(bakPath)) {
+            try {
+                data = JSON.parse(readFileSync(bakPath, 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        }
+        else {
+            return null;
+        }
+    }
+    // Schema version check with optional migration
+    if (expectedVersion !== undefined && data?._schemaVersion !== expectedVersion) {
+        if (migrate && typeof migrate === 'function') {
+            data = migrate(data, data?._schemaVersion, expectedVersion);
+        }
+        // Tolerant read: return data even without a migrator
+    }
+    return data;
+}
+// ---------------------------------------------------------------------------
+// 2. Advisory file locks
+// ---------------------------------------------------------------------------
+const LOCK_TIMEOUT_MS = 10_000; // stale lock threshold
+const LOCK_RETRY_MS = 50; // busy-wait interval
+const LOCK_MAX_RETRIES = 100; // max retries (~5 s)
+/**
+ * Acquire an advisory lock for filePath by creating filePath.lock.
+ * Stale locks (> LOCK_TIMEOUT_MS old) are cleared automatically.
+ */
+export function acquireLock(filePath) {
+    const lockPath = filePath + '.lock';
+    // Clear stale or corrupt lock
+    if (existsSync(lockPath)) {
+        try {
+            const lockData = JSON.parse(readFileSync(lockPath, 'utf8'));
+            const age = Date.now() - (lockData.createdAt || 0);
+            if (age > LOCK_TIMEOUT_MS) {
+                unlinkSync(lockPath);
+            }
+        }
+        catch {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { }
+        }
+    }
+    // Spin-try to create the lock exclusively
+    let retries = 0;
+    while (retries < LOCK_MAX_RETRIES) {
+        try {
+            writeFileSync(lockPath, JSON.stringify({
+                pid: process.pid,
+                createdAt: Date.now(),
+                holder: process.argv[1] || 'unknown',
+            }), { flag: 'wx' }); // 'wx' = exclusive create, EEXIST if present
+            return { acquired: true, lockPath };
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                retries++;
+                // Synchronous busy-wait — intentional; only triggered under contention
+                const start = Date.now();
+                while (Date.now() - start < LOCK_RETRY_MS) { }
+                continue;
+            }
+            throw err; // Unexpected error — propagate
+        }
+    }
+    return { acquired: false, lockPath, reason: 'timeout' };
+}
+/**
+ * Release a previously acquired lock.
+ */
+export function releaseLock(lockResult) {
+    if (lockResult?.lockPath) {
+        try {
+            unlinkSync(lockResult.lockPath);
+        }
+        catch { }
+    }
+}
+/**
+ * Run fn while holding an advisory lock on filePath.
+ * Throws if the lock cannot be acquired within the retry window.
+ */
+export function withLock(filePath, fn) {
+    const lock = acquireLock(filePath);
+    if (!lock.acquired) {
+        throw new Error(`Could not acquire lock for ${filePath}: ${lock.reason}`);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
+/**
+ * Locked atomic read-modify-write.
+ * Reads the current JSON, passes it to updateFn, then writes the result.
+ * If updateFn returns undefined the file is left unchanged.
+ */
+export function lockedUpdate(filePath, updateFn, opts = {}) {
+    return withLock(filePath, () => {
+        const current = readJsonSafe(filePath, opts);
+        const updated = updateFn(current);
+        if (updated !== undefined) {
+            atomicWriteJson(filePath, updated, opts);
+        }
+        return updated;
+    });
+}
+// ---------------------------------------------------------------------------
+// 3. Append-only ledger with lock
+// ---------------------------------------------------------------------------
+/**
+ * Append a NDJSON record to filePath under an advisory lock.
+ * On lock failure the write is attempted without a lock (best-effort).
+ */
+export async function atomicAppend(filePath, record) {
+    const line = JSON.stringify(record) + '\n';
+    const lock = acquireLock(filePath);
+    if (!lock.acquired) {
+        // Non-fatal: best-effort append without lock
+        try {
+            mkdirSync(dirname(filePath), { recursive: true });
+            appendFileSync(filePath, line);
+        }
+        catch { }
+        return;
+    }
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        appendFileSync(filePath, line);
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
+//# sourceMappingURL=integrity.js.map

package/dist/src/integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.js","sourceRoot":"","sources":["../../src/integrity.ts"],"names":[],"mappings":"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"}

package/dist/src/intelligence.d.ts

@@ -0,0 +1,104 @@
+/**
+ * intelligence.ts — Situational awareness for every pipeline run.
+ * Reads project reality fresh, derives task context, and detects contradictions
+ * between what an agent plans to do and what is actually true.
+ */
+interface ParsedFailure {
+    prompt: string;
+    error: string;
+    approach: string;
+    timestamp: number;
+}
+interface ParsedOutcome {
+    task: string;
+    success: boolean;
+    timestamp: number;
+}
+export interface ProjectBrief {
+    packageName: string;
+    version: string;
+    versionMajor: number;
+    description: string;
+    branch: string;
+    dirty: boolean;
+    dirtyFiles: string[];
+    recentCommits: string[];
+    aheadOfRemote: number;
+    brandName: string;
+    cliCommand: string;
+    moduleType: string;
+    entryPoint: string;
+    testCommand: string | null;
+    protectedPaths: string[];
+    recentFailures: ParsedFailure[];
+    recentOutcomes: ParsedOutcome[];
+    derivedAt: number;
+}
+/**
+ * Read project reality fresh. No cache. Returns a ProjectBrief.
+ */
+export declare function deriveProjectState(cwd?: string): ProjectBrief;
+interface PriorAttempt {
+    approach?: string;
+    tier?: string;
+    failed: boolean;
+    reason?: string;
+    files?: string[];
+    filesChanged?: string[];
+    status?: string;
+    error?: string;
+    type?: string;
+}
+export interface TaskBrief {
+    task: string;
+    priorAttempts: Array<{
+        approach: string;
+        failed: boolean;
+        reason: string;
+    }>;
+    activeConstraints: string[];
+    filesInScope: string[];
+    filesOutOfScope: string[];
+    escalationLevel: 'normal' | 'elevated' | 'critical';
+}
+/**
+ * Derive task-scoped context from the current prompt and optional session events.
+ */
+export declare function deriveTaskContext(task?: string, recentEvents?: Array<PriorAttempt | null>): TaskBrief;
+interface Plan {
+    description?: string;
+    assumptions?: Record<string, string> | string;
+    targetFiles?: string[];
+}
+interface Contradiction {
+    type: string;
+    severity: 'block' | 'warn';
+    message: string;
+    evidence: {
+        expected: string;
+        actual: string;
+    };
+}
+/**
+ * Detect contradictions between project reality, task context, and a proposed plan.
+ * Returns an array of contradiction objects.
+ */
+export declare function detectContradictions(projectBrief: ProjectBrief, taskBrief: TaskBrief | null, plan?: Plan): Contradiction[];
+interface SessionContext {
+    relatedSessions?: unknown[];
+    riskSignals?: unknown;
+    priorAttempts?: Array<{
+        failed?: boolean;
+        status?: string;
+        daysAgo?: number;
+        when?: string;
+        error?: string;
+        reason?: string;
+    }>;
+    relevantFiles?: string[];
+}
+/**
+ * Format a compact situational awareness summary (max 15 lines) for agent prompts.
+ */
+export declare function formatBrief(projectBrief: ProjectBrief, taskBrief: TaskBrief | null, sessionContext?: SessionContext | null): string;
+export {};