kairo-mcp 1.3.0

package/dist/storage/faultAdapter.d.ts

@@ -0,0 +1,64 @@
+import type { StorageAdapter } from './storageAdapter.js';
+import type { AuditEntry, KairoEvent } from '../types/events.js';
+import type { Checkpoint, SessionState } from '../types/domain.js';
+import type { RepoIntelligence } from '../core/repo/types.js';
+import type { VectorIndex } from '../core/vector/types.js';
+import type { TelemetryEvent } from '../core/telemetry/types.js';
+/**
+ * Deterministic in-process fault injection for storage operations
+ * (ADR-0013). Tests configure rules; the adapter applies them.
+ *
+ * Honest scope: faults are *simulations*, not real disk failures. They
+ * prove the handler code is correct (e.g. the caller releases a lease on
+ * appendEvent error), not that the OS layer is correct. By convention this
+ * adapter is test-only — the constructor warns when NODE_ENV is not "test".
+ */
+export type StorageMethod = 'init' | 'appendEvent' | 'readEvents' | 'saveSessionSnapshot' | 'loadSessionSnapshot' | 'saveCheckpoint' | 'loadCheckpoint' | 'loadLatestCheckpoint' | 'saveContinuation' | 'loadContinuation' | 'loadLatestContinuation' | 'saveIntelligence' | 'loadLatestIntelligence' | 'loadIntelligenceByFingerprint' | 'saveGraph' | 'saveVectorIndex' | 'loadVectorIndex' | 'audit' | 'readAudit' | 'appendTelemetry' | 'readTelemetry' | 'saveReport';
+export interface FailRule {
+    /** Trigger on the Nth call (1-indexed). Default 1. */
+    afterN?: number;
+    /** Trigger on every call once `afterN` is reached. Default false. */
+    repeating?: boolean;
+    /** Error to throw. Defaults to a generic Error. */
+    error?: Error;
+}
+export declare class FaultInjector {
+    private readonly rules;
+    failOn(method: StorageMethod, rule?: FailRule): this;
+    reset(): void;
+    /**
+     * Test whether the next call to `method` should throw. Increments the
+     * internal counter for that method on every call (whether or not it
+     * fires).
+     */
+    shouldFail(method: StorageMethod): Error | undefined;
+}
+export declare class FaultInjectingAdapter implements StorageAdapter {
+    private readonly inner;
+    private readonly fi;
+    constructor(inner: StorageAdapter, fi: FaultInjector);
+    private maybeThrow;
+    init(): Promise<void>;
+    appendEvent(e: KairoEvent): Promise<void>;
+    readEvents(): Promise<KairoEvent[]>;
+    saveSessionSnapshot(s: SessionState): Promise<void>;
+    loadSessionSnapshot(id: string): Promise<SessionState | undefined>;
+    saveCheckpoint(c: Checkpoint): Promise<void>;
+    loadCheckpoint(id: string): Promise<Checkpoint | undefined>;
+    loadLatestCheckpoint(): Promise<Checkpoint | undefined>;
+    saveContinuation(name: string, md: string): Promise<string>;
+    loadContinuation(name: string): Promise<string | undefined>;
+    loadLatestContinuation(): Promise<string | undefined>;
+    saveIntelligence(i: RepoIntelligence): Promise<void>;
+    loadLatestIntelligence(): Promise<RepoIntelligence | undefined>;
+    loadIntelligenceByFingerprint(fp: string): Promise<RepoIntelligence | undefined>;
+    saveGraph(kind: string, md: string): Promise<void>;
+    saveVectorIndex(i: VectorIndex): Promise<void>;
+    loadVectorIndex(): Promise<VectorIndex | undefined>;
+    audit(e: AuditEntry): Promise<void>;
+    readAudit(): Promise<AuditEntry[]>;
+    appendTelemetry(e: TelemetryEvent): Promise<void>;
+    readTelemetry(): Promise<TelemetryEvent[]>;
+    saveReport(name: string, md: string): Promise<void>;
+}
+//# sourceMappingURL=faultAdapter.d.ts.map

package/dist/storage/faultAdapter.d.ts.map

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

package/dist/storage/faultAdapter.js

@@ -0,0 +1,134 @@
+import { logger } from '../utils/logger.js';
+export class FaultInjector {
+    rules = new Map();
+    failOn(method, rule = {}) {
+        this.rules.set(method, { rule, calls: 0, fired: false });
+        return this;
+    }
+    reset() {
+        this.rules.clear();
+    }
+    /**
+     * Test whether the next call to `method` should throw. Increments the
+     * internal counter for that method on every call (whether or not it
+     * fires).
+     */
+    shouldFail(method) {
+        const state = this.rules.get(method);
+        if (!state)
+            return undefined;
+        state.calls += 1;
+        const trigger = state.rule.afterN ?? 1;
+        if (state.calls < trigger)
+            return undefined;
+        if (state.fired && !state.rule.repeating)
+            return undefined;
+        state.fired = true;
+        return state.rule.error ?? new Error(`FaultInjector: simulated failure in ${method}`);
+    }
+}
+export class FaultInjectingAdapter {
+    inner;
+    fi;
+    constructor(inner, fi) {
+        this.inner = inner;
+        this.fi = fi;
+        if (process.env.NODE_ENV !== 'test' && process.env.VITEST !== 'true') {
+            logger.warn('FaultInjectingAdapter is test-only and should never wrap a production adapter.');
+        }
+    }
+    maybeThrow(m) {
+        const err = this.fi.shouldFail(m);
+        if (err)
+            throw err;
+    }
+    async init() {
+        this.maybeThrow('init');
+        return this.inner.init();
+    }
+    async appendEvent(e) {
+        this.maybeThrow('appendEvent');
+        return this.inner.appendEvent(e);
+    }
+    async readEvents() {
+        this.maybeThrow('readEvents');
+        return this.inner.readEvents();
+    }
+    async saveSessionSnapshot(s) {
+        this.maybeThrow('saveSessionSnapshot');
+        return this.inner.saveSessionSnapshot(s);
+    }
+    async loadSessionSnapshot(id) {
+        this.maybeThrow('loadSessionSnapshot');
+        return this.inner.loadSessionSnapshot(id);
+    }
+    async saveCheckpoint(c) {
+        this.maybeThrow('saveCheckpoint');
+        return this.inner.saveCheckpoint(c);
+    }
+    async loadCheckpoint(id) {
+        this.maybeThrow('loadCheckpoint');
+        return this.inner.loadCheckpoint(id);
+    }
+    async loadLatestCheckpoint() {
+        this.maybeThrow('loadLatestCheckpoint');
+        return this.inner.loadLatestCheckpoint();
+    }
+    async saveContinuation(name, md) {
+        this.maybeThrow('saveContinuation');
+        return this.inner.saveContinuation(name, md);
+    }
+    async loadContinuation(name) {
+        this.maybeThrow('loadContinuation');
+        return this.inner.loadContinuation(name);
+    }
+    async loadLatestContinuation() {
+        this.maybeThrow('loadLatestContinuation');
+        return this.inner.loadLatestContinuation();
+    }
+    async saveIntelligence(i) {
+        this.maybeThrow('saveIntelligence');
+        return this.inner.saveIntelligence(i);
+    }
+    async loadLatestIntelligence() {
+        this.maybeThrow('loadLatestIntelligence');
+        return this.inner.loadLatestIntelligence();
+    }
+    async loadIntelligenceByFingerprint(fp) {
+        this.maybeThrow('loadIntelligenceByFingerprint');
+        return this.inner.loadIntelligenceByFingerprint(fp);
+    }
+    async saveGraph(kind, md) {
+        this.maybeThrow('saveGraph');
+        return this.inner.saveGraph(kind, md);
+    }
+    async saveVectorIndex(i) {
+        this.maybeThrow('saveVectorIndex');
+        return this.inner.saveVectorIndex(i);
+    }
+    async loadVectorIndex() {
+        this.maybeThrow('loadVectorIndex');
+        return this.inner.loadVectorIndex();
+    }
+    async audit(e) {
+        this.maybeThrow('audit');
+        return this.inner.audit(e);
+    }
+    async readAudit() {
+        this.maybeThrow('readAudit');
+        return this.inner.readAudit();
+    }
+    async appendTelemetry(e) {
+        this.maybeThrow('appendTelemetry');
+        return this.inner.appendTelemetry(e);
+    }
+    async readTelemetry() {
+        this.maybeThrow('readTelemetry');
+        return this.inner.readTelemetry();
+    }
+    async saveReport(name, md) {
+        this.maybeThrow('saveReport');
+        return this.inner.saveReport(name, md);
+    }
+}
+//# sourceMappingURL=faultAdapter.js.map

package/dist/storage/faultAdapter.js.map

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

package/dist/storage/fileStorageAdapter.d.ts

@@ -0,0 +1,55 @@
+import type { StorageAdapter } from './storageAdapter.js';
+import type { AuditEntry, KairoEvent } from '../types/events.js';
+import type { TelemetryEvent } from '../core/telemetry/types.js';
+import type { Checkpoint, SessionState } from '../types/domain.js';
+import type { RepoIntelligence } from '../core/repo/types.js';
+import type { VectorIndex } from '../core/vector/types.js';
+import { type QuarantineSink } from './quarantine.js';
+/**
+ * Local-first, event-sourced file backend.
+ *
+ * - `events.jsonl` is append-only and authoritative.
+ * - Snapshots/checkpoints are written temp-then-rename so a crash never leaves a
+ *   half-written JSON document.
+ * - `readEvents` tolerates a torn trailing line (e.g. crash mid-append) by discarding
+ *   only that line, preserving all prior history.
+ */
+export declare class FileStorageAdapter implements StorageAdapter {
+    private readonly paths;
+    private readonly quarantine;
+    constructor(projectRoot?: string, quarantine?: QuarantineSink);
+    init(): Promise<void>;
+    appendEvent(event: KairoEvent): Promise<void>;
+    readEvents(): Promise<KairoEvent[]>;
+    saveSessionSnapshot(state: SessionState): Promise<void>;
+    loadSessionSnapshot(id: string): Promise<SessionState | undefined>;
+    saveCheckpoint(checkpoint: Checkpoint): Promise<void>;
+    loadCheckpoint(id: string): Promise<Checkpoint | undefined>;
+    loadLatestCheckpoint(): Promise<Checkpoint | undefined>;
+    saveContinuation(name: string, markdown: string): Promise<string>;
+    loadContinuation(name: string): Promise<string | undefined>;
+    loadLatestContinuation(): Promise<string | undefined>;
+    saveIntelligence(intel: RepoIntelligence): Promise<void>;
+    loadLatestIntelligence(): Promise<RepoIntelligence | undefined>;
+    loadIntelligenceByFingerprint(fp: string): Promise<RepoIntelligence | undefined>;
+    saveGraph(kind: string, markdown: string): Promise<void>;
+    saveVectorIndex(index: VectorIndex): Promise<void>;
+    loadVectorIndex(): Promise<VectorIndex | undefined>;
+    audit(entry: AuditEntry): Promise<void>;
+    readAudit(): Promise<AuditEntry[]>;
+    appendTelemetry(event: TelemetryEvent): Promise<void>;
+    readTelemetry(): Promise<TelemetryEvent[]>;
+    saveReport(name: string, markdown: string): Promise<void>;
+    private writeAtomic;
+    private readFileOrEmpty;
+    /**
+     * Tolerant + validating JSONL reader (ADR-0012). Corrupt or invalid lines
+     * are quarantined to `.kairo/quarantine/{source}.jsonl` and the rest of
+     * the file is still read. A torn trailing line — the v0.1 crash-safety
+     * contract — remains silent.
+     */
+    private readValidatedJsonl;
+    private readJson;
+    private latestFile;
+}
+//# sourceMappingURL=fileStorageAdapter.d.ts.map

package/dist/storage/fileStorageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileStorageAdapter.d.ts","sourceRoot":"","sources":["../../src/storage/fileStorageAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgB1E;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;gBAEhC,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,cAAc;IAKvD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBrB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAInC,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAWlE,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAK3D,oBAAoB,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAOvD,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKjE,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQ3D,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAMrD,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD,sBAAsB,IAAI,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAI/D,6BAA6B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAIhF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,eAAe,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAInD,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAIlC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAI1C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAMjD,WAAW;YAMX,eAAe;IAQ7B;;;;;OAKG;YACW,kBAAkB;YAqDlB,QAAQ;YAQR,UAAU;CAQzB"}

package/dist/storage/fileStorageAdapter.js

@@ -0,0 +1,219 @@
+import { mkdir, appendFile, writeFile, readFile, readdir, rename } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { kairoPaths } from './paths.js';
+import { logger } from '../utils/logger.js';
+import { FileQuarantineSink } from './quarantine.js';
+import { AuditEntryZ, KairoEventZ, SessionStateZ, TelemetryEventZ, } from '../contracts/zodSchemas.js';
+import { migrateAudit, migrateCheckpoint, migrateEvent, migrateSession, migrateTelemetry, } from '../contracts/migrations.js';
+/**
+ * Local-first, event-sourced file backend.
+ *
+ * - `events.jsonl` is append-only and authoritative.
+ * - Snapshots/checkpoints are written temp-then-rename so a crash never leaves a
+ *   half-written JSON document.
+ * - `readEvents` tolerates a torn trailing line (e.g. crash mid-append) by discarding
+ *   only that line, preserving all prior history.
+ */
+export class FileStorageAdapter {
+    paths;
+    quarantine;
+    constructor(projectRoot, quarantine) {
+        this.paths = kairoPaths(projectRoot);
+        this.quarantine = quarantine ?? new FileQuarantineSink(this.paths.quarantineDir);
+    }
+    async init() {
+        for (const dir of [
+            this.paths.base,
+            this.paths.sessionsDir,
+            this.paths.checkpointsDir,
+            this.paths.continuationsDir,
+            this.paths.reportsDir,
+            this.paths.intelligenceDir,
+            this.paths.graphsDir,
+            this.paths.vectorDir,
+            this.paths.quarantineDir,
+        ]) {
+            await mkdir(dir, { recursive: true });
+        }
+    }
+    async appendEvent(event) {
+        await appendFile(this.paths.events, `${JSON.stringify(event)}\n`, 'utf8');
+    }
+    async readEvents() {
+        return this.readValidatedJsonl(this.paths.events, KairoEventZ, migrateEvent);
+    }
+    async saveSessionSnapshot(state) {
+        const tagged = state.schema ? state : { ...state, schema: 1 };
+        await this.writeAtomic(this.paths.sessionFile(state.id), JSON.stringify(tagged, null, 2));
+    }
+    async loadSessionSnapshot(id) {
+        const raw = await this.readJson(this.paths.sessionFile(id));
+        if (raw === undefined)
+            return undefined;
+        const parsed = SessionStateZ.safeParse(raw);
+        if (!parsed.success) {
+            logger.warn(`Session snapshot ${id} failed schema validation; using as-is`);
+            return migrateSession(raw);
+        }
+        return migrateSession(parsed.data);
+    }
+    async saveCheckpoint(checkpoint) {
+        const tagged = checkpoint.schema ? checkpoint : { ...checkpoint, schema: 1 };
+        await this.writeAtomic(this.paths.checkpointFile(checkpoint.id), JSON.stringify(tagged, null, 2));
+    }
+    async loadCheckpoint(id) {
+        const raw = await this.readJson(this.paths.checkpointFile(id));
+        return raw === undefined ? undefined : migrateCheckpoint(raw);
+    }
+    async loadLatestCheckpoint() {
+        const latest = await this.latestFile(this.paths.checkpointsDir, '.json');
+        if (!latest)
+            return undefined;
+        const raw = await this.readJson(join(this.paths.checkpointsDir, latest));
+        return raw === undefined ? undefined : migrateCheckpoint(raw);
+    }
+    async saveContinuation(name, markdown) {
+        await this.writeAtomic(this.paths.continuationFile(name), markdown);
+        return name;
+    }
+    async loadContinuation(name) {
+        try {
+            return await readFile(this.paths.continuationFile(name), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async loadLatestContinuation() {
+        const latest = await this.latestFile(this.paths.continuationsDir, '.md');
+        if (!latest)
+            return undefined;
+        return readFile(join(this.paths.continuationsDir, latest), 'utf8');
+    }
+    async saveIntelligence(intel) {
+        const body = JSON.stringify(intel, null, 2);
+        await this.writeAtomic(this.paths.intelligenceFile(intel.fingerprint), body);
+        await this.writeAtomic(this.paths.latestIntelligenceFile, body);
+    }
+    async loadLatestIntelligence() {
+        return this.readJson(this.paths.latestIntelligenceFile);
+    }
+    async loadIntelligenceByFingerprint(fp) {
+        return this.readJson(this.paths.intelligenceFile(fp));
+    }
+    async saveGraph(kind, markdown) {
+        await this.writeAtomic(this.paths.graphFile(kind), markdown);
+    }
+    async saveVectorIndex(index) {
+        await this.writeAtomic(this.paths.vectorIndexFile, JSON.stringify(index));
+    }
+    async loadVectorIndex() {
+        return this.readJson(this.paths.vectorIndexFile);
+    }
+    async audit(entry) {
+        const tagged = entry.schema ? entry : { ...entry, schema: 1 };
+        await appendFile(this.paths.audit, `${JSON.stringify(tagged)}\n`, 'utf8');
+    }
+    async readAudit() {
+        return this.readValidatedJsonl(this.paths.audit, AuditEntryZ, migrateAudit);
+    }
+    async appendTelemetry(event) {
+        await appendFile(this.paths.telemetry, `${JSON.stringify(event)}\n`, 'utf8');
+    }
+    async readTelemetry() {
+        return this.readValidatedJsonl(this.paths.telemetry, TelemetryEventZ, migrateTelemetry);
+    }
+    async saveReport(name, markdown) {
+        await this.writeAtomic(this.paths.reportFile(name), markdown);
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    async writeAtomic(path, content) {
+        const tmp = `${path}.${process.pid}.tmp`;
+        await writeFile(tmp, content, 'utf8');
+        await rename(tmp, path);
+    }
+    async readFileOrEmpty(path) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Tolerant + validating JSONL reader (ADR-0012). Corrupt or invalid lines
+     * are quarantined to `.kairo/quarantine/{source}.jsonl` and the rest of
+     * the file is still read. A torn trailing line — the v0.1 crash-safety
+     * contract — remains silent.
+     */
+    async readValidatedJsonl(path, schema, migrate) {
+        const raw = await this.readFileOrEmpty(path);
+        if (raw.length === 0)
+            return [];
+        // Don't filter empty lines yet — we need 1-based line numbers that
+        // match the on-disk position for the quarantine record.
+        const allLines = raw.split('\n');
+        const source = basename(path);
+        const out = [];
+        for (let i = 0; i < allLines.length; i++) {
+            const line = allLines[i] ?? '';
+            if (line.trim().length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                const isTorn = i === allLines.length - 1 && !raw.endsWith('\n');
+                if (isTorn) {
+                    logger.warn(`Discarding torn trailing line in ${source} (crash recovery)`);
+                }
+                else {
+                    await this.quarantine.write({
+                        detectedAt: new Date().toISOString(),
+                        source,
+                        line: i + 1,
+                        reason: 'parse',
+                        raw: line,
+                    });
+                }
+                continue;
+            }
+            const result = schema.safeParse(parsed);
+            if (!result.success) {
+                await this.quarantine.write({
+                    detectedAt: new Date().toISOString(),
+                    source,
+                    line: i + 1,
+                    reason: 'validation',
+                    detail: result.error.issues
+                        .slice(0, 3)
+                        .map((iss) => `${iss.path.join('.')}: ${iss.message}`)
+                        .join('; '),
+                    raw: line,
+                });
+                continue;
+            }
+            out.push(migrate(result.data));
+        }
+        return out;
+    }
+    async readJson(path) {
+        try {
+            return JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async latestFile(dir, ext) {
+        try {
+            const entries = (await readdir(dir)).filter((f) => f.endsWith(ext)).sort();
+            return entries.at(-1);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=fileStorageAdapter.js.map

package/dist/storage/fileStorageAdapter.js.map

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

package/dist/storage/paths.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolves the per-project `.kairo/` layout. The project root is, in order of
+ * precedence: explicit argument → `KAIRO_PROJECT_ROOT` → current working directory.
+ */
+export interface KairoPaths {
+    root: string;
+    base: string;
+    events: string;
+    audit: string;
+    telemetry: string;
+    sessionsDir: string;
+    checkpointsDir: string;
+    continuationsDir: string;
+    reportsDir: string;
+    intelligenceDir: string;
+    graphsDir: string;
+    vectorDir: string;
+    vectorIndexFile: string;
+    quarantineDir: string;
+    sessionFile: (id: string) => string;
+    checkpointFile: (id: string) => string;
+    continuationFile: (name: string) => string;
+    intelligenceFile: (fingerprint: string) => string;
+    latestIntelligenceFile: string;
+    graphFile: (kind: string) => string;
+    reportFile: (name: string) => string;
+}
+export declare function resolveProjectRoot(explicit?: string): string;
+export declare function kairoPaths(explicitRoot?: string): KairoPaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/storage/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/storage/paths.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,UAAU,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,UAAU,CA0B5D"}

package/dist/storage/paths.js

@@ -0,0 +1,32 @@
+import { resolve, join } from 'node:path';
+export function resolveProjectRoot(explicit) {
+    return resolve(explicit ?? process.env.KAIRO_PROJECT_ROOT ?? process.cwd());
+}
+export function kairoPaths(explicitRoot) {
+    const root = resolveProjectRoot(explicitRoot);
+    const base = join(root, '.kairo');
+    return {
+        root,
+        base,
+        events: join(base, 'events.jsonl'),
+        audit: join(base, 'audit.jsonl'),
+        telemetry: join(base, 'telemetry.jsonl'),
+        sessionsDir: join(base, 'sessions'),
+        checkpointsDir: join(base, 'checkpoints'),
+        continuationsDir: join(base, 'continuations'),
+        reportsDir: join(base, 'reports'),
+        intelligenceDir: join(base, 'intelligence'),
+        graphsDir: join(base, 'graphs'),
+        vectorDir: join(base, 'vector'),
+        vectorIndexFile: join(base, 'vector', 'index.json'),
+        quarantineDir: join(base, 'quarantine'),
+        sessionFile: (id) => join(base, 'sessions', `${id}.json`),
+        checkpointFile: (id) => join(base, 'checkpoints', `${id}.json`),
+        continuationFile: (name) => join(base, 'continuations', name),
+        intelligenceFile: (fp) => join(base, 'intelligence', `${fp}.json`),
+        latestIntelligenceFile: join(base, 'intelligence', 'latest.json'),
+        graphFile: (kind) => join(base, 'graphs', `${kind}.md`),
+        reportFile: (name) => join(base, 'reports', name),
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/storage/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/storage/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA8B1C,MAAM,UAAU,kBAAkB,CAAC,QAAiB;IAClD,OAAO,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,YAAqB;IAC9C,MAAM,IAAI,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC;QAClC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QAChC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,iBAAiB,CAAC;QACxC,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;QACnC,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QACzC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC;QAC7C,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;QACjC,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC;QAC3C,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC;QAC/B,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC;QAC/B,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,CAAC;QACnD,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC;QACvC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC;QACzD,cAAc,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,CAAC;QAC/D,gBAAgB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,CAAC;QAC7D,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,CAAC;QAClE,sBAAsB,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,CAAC;QACjE,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,KAAK,CAAC;QACvD,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC;KAClD,CAAC;AACJ,CAAC"}

package/dist/storage/quarantine.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Last-resort corruption recovery for append-only logs (ADR-0012).
+ *
+ * When a record fails to parse or validate, the raw line is written to
+ * `.kairo/quarantine/{file}.jsonl` along with metadata (line number, reason,
+ * timestamp). The reader continues with the rest of the file. Quarantined
+ * records are never reaped automatically.
+ */
+export interface QuarantinedRecord {
+    /** ISO timestamp at which the corruption was detected. */
+    detectedAt: string;
+    /** Source filename, e.g. `events.jsonl`. */
+    source: string;
+    /** 1-based line number in the source file. */
+    line: number;
+    /** Human reason: 'parse' (JSON.parse failed) or 'validation' (zod failed). */
+    reason: 'parse' | 'validation';
+    /** Best-effort description of the validation failure. */
+    detail?: string;
+    /** The raw line contents, verbatim. */
+    raw: string;
+}
+export interface QuarantineSink {
+    write(record: QuarantinedRecord): Promise<void>;
+}
+export declare class FileQuarantineSink implements QuarantineSink {
+    private readonly base;
+    private ensured;
+    constructor(quarantineDir: string);
+    write(record: QuarantinedRecord): Promise<void>;
+}
+/** Used in tests / contexts where corruption should be a hard error. */
+export declare class NoopQuarantineSink implements QuarantineSink {
+    write(_record: QuarantinedRecord): Promise<void>;
+}
+//# sourceMappingURL=quarantine.d.ts.map

package/dist/storage/quarantine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quarantine.d.ts","sourceRoot":"","sources":["../../src/storage/quarantine.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,MAAM,EAAE,OAAO,GAAG,YAAY,CAAC;IAC/B,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAS;gBACZ,aAAa,EAAE,MAAM;IAG3B,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAStD;AAED,wEAAwE;AACxE,qBAAa,kBAAmB,YAAW,cAAc;IACjD,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGvD"}

package/dist/storage/quarantine.js

@@ -0,0 +1,26 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+export class FileQuarantineSink {
+    base;
+    ensured = false;
+    constructor(quarantineDir) {
+        this.base = quarantineDir;
+    }
+    async write(record) {
+        if (!this.ensured) {
+            await mkdir(this.base, { recursive: true });
+            this.ensured = true;
+        }
+        const file = join(this.base, `${record.source}`);
+        await appendFile(file, `${JSON.stringify(record)}\n`, 'utf8');
+        logger.warn(`Quarantined ${record.source} line ${record.line} (${record.reason}); see ${file}`);
+    }
+}
+/** Used in tests / contexts where corruption should be a hard error. */
+export class NoopQuarantineSink {
+    async write(_record) {
+        // Intentionally silent.
+    }
+}
+//# sourceMappingURL=quarantine.js.map