@feltdb/core 0.6.9 → 0.6.11

package/dist/workspace/investigation-analysis.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Investigation analysis.
+ *
+ * This module draws the line the rest of the system depends on:
+ *
+ *   Evidence  — facts the runtime observed. Never generated by FeltDB.
+ *   Finding   — FeltDB's engineering interpretation of that evidence.
+ *
+ * The two are separate types with separate provenance markers
+ * (`source: "runtime_observation"` vs `origin: "feltdb_analysis"`) so that a
+ * generated diagnosis can never be presented, stored, or handed to an agent as
+ * though it were raw runtime evidence.
+ *
+ * This module is pure: it performs no I/O and imports no Node built-ins.
+ */
+import type { InvestigationEvidence, InvestigationFinding, RuntimeRequestObservation, SourceLocation, VerificationCriterion } from './workspace-types.js';
+/**
+ * Turn a runtime observation into evidence records.
+ *
+ * Every statement here restates something the runtime actually saw. Nothing in
+ * this function may infer a cause.
+ */
+export declare function collectEvidence(investigationId: string, observation: RuntimeRequestObservation): InvestigationEvidence[];
+/**
+ * Interpret the evidence.
+ *
+ * This is FeltDB's analysis, explicitly marked as such. It states what the
+ * evidence means for the engineer without claiming to be an observation.
+ */
+export declare function deriveFinding(investigationId: string, observation: RuntimeRequestObservation, evidence: InvestigationEvidence[]): InvestigationFinding;
+/** Candidate source paths that could implement the observed endpoint. */
+export declare function candidateSourcePaths(url: string): string[];
+/** The recommended change FeltDB proposes, stated as a request, not a patch. */
+export declare function recommendChanges(observation: RuntimeRequestObservation): string[];
+/**
+ * The verification contract.
+ *
+ * This is what FeltDB will hold the runtime to after the agent has worked. It
+ * must be expressed as an observable runtime outcome, never as a build,
+ * test, or commit result.
+ */
+export declare function verificationContractFor(observation: RuntimeRequestObservation): VerificationCriterion[];
+/** A one-line summary of why the investigation was opened. */
+export declare function summarizeDefect(observation: RuntimeRequestObservation): string;
+/** Source locations restricted to files the caller confirmed exist. */
+export declare function resolveRelevantSource(url: string, existingFiles: string[]): SourceLocation[];
+//# sourceMappingURL=investigation-analysis.d.ts.map

package/dist/workspace/investigation-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"investigation-analysis.d.ts","sourceRoot":"","sources":["../../src/workspace/investigation-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAK9B;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,yBAAyB,GACrC,qBAAqB,EAAE,CAsEzB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,yBAAyB,EACtC,QAAQ,EAAE,qBAAqB,EAAE,GAChC,oBAAoB,CAoBtB;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAe1D;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,yBAAyB,GAAG,MAAM,EAAE,CAYjF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,yBAAyB,GAAG,qBAAqB,EAAE,CAUvG;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,WAAW,EAAE,yBAAyB,GAAG,MAAM,CAE9E;AAUD,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAG5F"}

package/dist/workspace/investigation-analysis.js

@@ -0,0 +1,181 @@
+/**
+ * Investigation analysis.
+ *
+ * This module draws the line the rest of the system depends on:
+ *
+ *   Evidence  — facts the runtime observed. Never generated by FeltDB.
+ *   Finding   — FeltDB's engineering interpretation of that evidence.
+ *
+ * The two are separate types with separate provenance markers
+ * (`source: "runtime_observation"` vs `origin: "feltdb_analysis"`) so that a
+ * generated diagnosis can never be presented, stored, or handed to an agent as
+ * though it were raw runtime evidence.
+ *
+ * This module is pure: it performs no I/O and imports no Node built-ins.
+ */
+import { describeDefect } from './runtime-observation.js';
+const uniqueId = (prefix) => `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+/**
+ * Turn a runtime observation into evidence records.
+ *
+ * Every statement here restates something the runtime actually saw. Nothing in
+ * this function may infer a cause.
+ */
+export function collectEvidence(investigationId, observation) {
+    const base = {
+        investigationId,
+        observationId: observation.observationId,
+        source: 'runtime_observation',
+        observedAt: observation.timestamp,
+    };
+    const evidence = [];
+    if (observation.networkFailure) {
+        evidence.push({
+            ...base,
+            id: uniqueId('evidence'),
+            kind: 'network_failure',
+            statement: `${observation.method} ${observation.url} produced no HTTP response.`,
+            detail: { method: observation.method, url: observation.url, ...observation.responseCharacteristics },
+        });
+    }
+    else {
+        evidence.push({
+            ...base,
+            id: uniqueId('evidence'),
+            kind: 'http_response',
+            statement: `${observation.method} ${observation.url} responded with HTTP ${observation.status}.`,
+            detail: {
+                method: observation.method,
+                url: observation.url,
+                status: observation.status,
+                ...observation.responseCharacteristics,
+            },
+        });
+    }
+    if (typeof observation.durationMs === 'number') {
+        evidence.push({
+            ...base,
+            id: uniqueId('evidence'),
+            kind: 'timing',
+            statement: `The request completed in ${observation.durationMs}ms.`,
+            detail: { durationMs: observation.durationMs },
+        });
+    }
+    if (observation.browser || observation.page) {
+        evidence.push({
+            ...base,
+            id: uniqueId('evidence'),
+            kind: 'browser_context',
+            statement: `Observed by the ${observation.browser || 'unknown'} runtime on page ${observation.page || 'unknown'}.`,
+            detail: {
+                browser: observation.browser,
+                engine: observation.engine,
+                page: observation.page,
+                runtime: observation.runtime,
+                correlationId: observation.correlationId,
+            },
+        });
+    }
+    for (const event of observation.correlatedEvents || []) {
+        evidence.push({
+            ...base,
+            id: uniqueId('evidence'),
+            kind: event.kind === 'console_error' || event.kind === 'console_warn' ? 'console_error' : 'runtime_error',
+            statement: `Correlated ${event.kind.replace(/_/g, ' ')}: ${event.message}`,
+            observedAt: event.timestamp,
+            detail: { stack: event.stack, source: event.source, correlationId: observation.correlationId },
+        });
+    }
+    return evidence;
+}
+/**
+ * Interpret the evidence.
+ *
+ * This is FeltDB's analysis, explicitly marked as such. It states what the
+ * evidence means for the engineer without claiming to be an observation.
+ */
+export function deriveFinding(investigationId, observation, evidence) {
+    const path = safePath(observation.url);
+    const correlated = evidence.filter(item => item.kind === 'console_error' || item.kind === 'runtime_error');
+    const statement = observation.networkFailure
+        ? `${path} is unreachable from the browser runtime. The request never produced an HTTP response, so the endpoint is the source of the observed runtime failure.`
+        : `${path} is returning HTTP ${observation.status}. The endpoint is the source of the observed runtime failure${correlated.length > 0 ? ', and it is accompanied by a correlated runtime error' : ''}.`;
+    return {
+        id: uniqueId('finding'),
+        investigationId,
+        statement,
+        origin: 'feltdb_analysis',
+        // Confidence is higher when the runtime corroborated the response with an
+        // error of its own.
+        confidence: correlated.length > 0 ? 'high' : observation.status >= 500 ? 'high' : 'medium',
+        derivedFromEvidence: evidence.map(item => item.id),
+        createdAt: Date.now(),
+    };
+}
+/** Candidate source paths that could implement the observed endpoint. */
+export function candidateSourcePaths(url) {
+    const path = safePath(url).replace(/^\//, '').replace(/\/$/, '');
+    if (!path)
+        return [];
+    const extensions = ['ts', 'tsx', 'js', 'jsx', 'mjs'];
+    const candidates = [];
+    for (const extension of extensions) {
+        candidates.push(`app/${path}/route.${extension}`);
+        candidates.push(`src/app/${path}/route.${extension}`);
+        candidates.push(`pages/${path}.${extension}`);
+        candidates.push(`src/pages/${path}.${extension}`);
+        candidates.push(`${path}.${extension}`);
+        candidates.push(`src/${path}.${extension}`);
+        candidates.push(`server/${path}.${extension}`);
+    }
+    return candidates;
+}
+/** The recommended change FeltDB proposes, stated as a request, not a patch. */
+export function recommendChanges(observation) {
+    const path = safePath(observation.url);
+    if (observation.networkFailure) {
+        return [
+            `Make ${observation.method} ${path} reachable so the browser receives an HTTP response.`,
+            'Investigate the handler registration and the server startup path for this route.',
+        ];
+    }
+    return [
+        `Change ${observation.method} ${path} so it returns a successful response instead of HTTP ${observation.status}.`,
+        'Correct the failure inside the request handler rather than suppressing the error at the call site.',
+    ];
+}
+/**
+ * The verification contract.
+ *
+ * This is what FeltDB will hold the runtime to after the agent has worked. It
+ * must be expressed as an observable runtime outcome, never as a build,
+ * test, or commit result.
+ */
+export function verificationContractFor(observation) {
+    return [{
+            id: uniqueId('criterion'),
+            kind: 'primary',
+            method: observation.method,
+            url: observation.url,
+            originalStatus: observation.status,
+            expectedStatuses: [200, 201, 202, 204],
+            description: `${observation.method} ${safePath(observation.url)} must return a successful HTTP status when observed by the browser runtime.`,
+        }];
+}
+/** A one-line summary of why the investigation was opened. */
+export function summarizeDefect(observation) {
+    return `${observation.method} ${safePath(observation.url)}: ${describeDefect(observation)}`;
+}
+function safePath(url) {
+    try {
+        return new URL(url, 'http://localhost').pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** Source locations restricted to files the caller confirmed exist. */
+export function resolveRelevantSource(url, existingFiles) {
+    const candidates = new Set(candidateSourcePaths(url));
+    return existingFiles.filter(file => candidates.has(file)).map(file => ({ file }));
+}

package/dist/workspace/investigation-lifecycle-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Durable investigation lifecycle.
+ *
+ * Investigations live in `.feltdb/investigations/<id>.json` inside the
+ * workspace. That location is what makes the development loop durable rather
+ * than browser-session memory: a refresh, a process exit, or a full workspace
+ * restart all leave the investigation, its evidence, its finding, its Git
+ * association, and its verification result intact and queryable.
+ *
+ * Every state change goes through the lifecycle state machines in
+ * `runtime-investigation.ts`, so an invalid transition throws instead of
+ * silently producing an impossible record.
+ */
+import type { InvestigationEvidence, InvestigationFinding, RemediationContract, RepositoryIdentity, RuntimeInvestigation, RuntimeRequestObservation } from './workspace-types.js';
+/** Aggregate facts about the durable investigation store. */
+export interface InvestigationStoreMetrics {
+    investigations: number;
+    observations: number;
+    evidenceRecords: number;
+    verifiedInvestigations: number;
+    serializedBytes: number;
+    loadMilliseconds: number;
+}
+export declare class InvestigationLifecycleManager {
+    private readonly workspaceDir;
+    private readonly investigationsDir;
+    constructor(workspaceDir: string);
+    private ensureDirectories;
+    /** Open an investigation for a runtime observation. */
+    createInvestigation(observation: RuntimeRequestObservation, workspaceId?: string): RuntimeInvestigation;
+    persistInvestigation(investigation: RuntimeInvestigation): void;
+    loadInvestigation(id: string): RuntimeInvestigation | null;
+    listInvestigations(): RuntimeInvestigation[];
+    /** Find the investigation opened for a given observation, if any. */
+    findByObservationId(observationId: string): RuntimeInvestigation | null;
+    /** Add an observation reference without changing the factual observation. */
+    linkRuntimeObservationToInvestigation(observationId: string, investigationId: string): RuntimeInvestigation;
+    private require;
+    /** OBSERVED -> INVESTIGATING, attaching the runtime evidence. */
+    transitionToInvestigating(id: string, evidence?: InvestigationEvidence[]): RuntimeInvestigation;
+    /**
+     * INVESTIGATING -> FINDING.
+     *
+     * Accepts a structured {@link InvestigationFinding}. A bare string is still
+     * accepted so existing callers keep working; it is stored as an analysis
+     * finding with no evidence attribution.
+     */
+    transitionToFinding(id: string, finding: InvestigationFinding | string): RuntimeInvestigation;
+    /**
+     * FINDING -> PROPOSED and NOT_STARTED -> SENT_TO_AGENT.
+     *
+     * Records the repository state at handoff so a later comparison can prove
+     * what the agent changed.
+     */
+    sendToAgent(id: string, contract: Omit<RemediationContract, 'id' | 'observationId' | 'createdAt' | 'updatedAt'>, gitBefore?: RepositoryIdentity): RuntimeInvestigation;
+    /** SENT_TO_AGENT -> IMPLEMENTING. The agent has started work. */
+    markImplementing(id: string): RuntimeInvestigation;
+    /**
+     * IMPLEMENTING -> CHANGES_DETECTED, using observable repository state.
+     *
+     * Returns the investigation unchanged when the repository has not moved:
+     * FeltDB will not advance the lifecycle on an agent's say-so.
+     */
+    detectRepositoryChange(id: string, projectDir: string): RuntimeInvestigation;
+    /**
+     * CHANGES_DETECTED -> IMPLEMENTATION_COMPLETE, and the verification state
+     * machine becomes ready to watch the runtime.
+     *
+     * A detected repository change means remediation happened. It does not mean
+     * the defect is fixed, so this only opens verification — it never concludes it.
+     */
+    completeImplementation(id: string): RuntimeInvestigation;
+    /**
+     * Evaluate the verification contract against a runtime observation.
+     *
+     * The outcome is decided by the observation alone. A missing or
+     * non-matching observation yields INCONCLUSIVE; it never yields VERIFIED.
+     */
+    recordVerification(id: string, contract: RemediationContract, observation?: RuntimeRequestObservation): RuntimeInvestigation;
+    /**
+     * Measure the durable development-plane store.
+     *
+     * This is an empirical baseline for durability, queryability, and restart
+     * cost. It is not a scale claim.
+     */
+    metrics(): InvestigationStoreMetrics;
+}
+//# sourceMappingURL=investigation-lifecycle-manager.d.ts.map

package/dist/workspace/investigation-lifecycle-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"investigation-lifecycle-manager.d.ts","sourceRoot":"","sources":["../../src/workspace/investigation-lifecycle-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EAEnB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EAE1B,MAAM,sBAAsB,CAAC;AAU9B,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,6BAA6B;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,YAAY,EAAE,MAAM;IAKhC,OAAO,CAAC,iBAAiB;IAMzB,uDAAuD;IACvD,mBAAmB,CAAC,WAAW,EAAE,yBAAyB,EAAE,WAAW,SAAK,GAAG,oBAAoB;IAwBnG,oBAAoB,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI;IAS/D,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAM1D,kBAAkB,IAAI,oBAAoB,EAAE;IAe5C,qEAAqE;IACrE,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAKvE,6EAA6E;IAC7E,qCAAqC,CAAC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,oBAAoB;IAgB3G,OAAO,CAAC,OAAO;IAQf,iEAAiE;IACjE,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,GAAE,qBAAqB,EAAO,GAAG,oBAAoB;IAOnG;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,oBAAoB;IAmB7F;;;;;OAKG;IACH,WAAW,CACT,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,eAAe,GAAG,WAAW,GAAG,WAAW,CAAC,EACvF,SAAS,CAAC,EAAE,kBAAkB,GAC7B,oBAAoB;IAiBvB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB;IAMlD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,oBAAoB;IAgB5E;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB;IASxD;;;;;OAKG;IACH,kBAAkB,CAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,CAAC,EAAE,yBAAyB,GACtC,oBAAoB;IAuBvB;;;;;OAKG;IACH,OAAO,IAAI,yBAAyB;CA0BrC"}

package/dist/workspace/investigation-lifecycle-manager.js

@@ -0,0 +1,259 @@
+/**
+ * Durable investigation lifecycle.
+ *
+ * Investigations live in `.feltdb/investigations/<id>.json` inside the
+ * workspace. That location is what makes the development loop durable rather
+ * than browser-session memory: a refresh, a process exit, or a full workspace
+ * restart all leave the investigation, its evidence, its finding, its Git
+ * association, and its verification result intact and queryable.
+ *
+ * Every state change goes through the lifecycle state machines in
+ * `runtime-investigation.ts`, so an invalid transition throws instead of
+ * silently producing an impossible record.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRemediationContract, evaluateVerification, transitionInvestigation, transitionRemediation, transitionVerification, } from './runtime-investigation.js';
+import { trackRemediation } from './git-identity.js';
+export class InvestigationLifecycleManager {
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+        this.investigationsDir = path.join(workspaceDir, '.feltdb', 'investigations');
+    }
+    ensureDirectories() {
+        if (!fs.existsSync(this.investigationsDir)) {
+            fs.mkdirSync(this.investigationsDir, { recursive: true });
+        }
+    }
+    /** Open an investigation for a runtime observation. */
+    createInvestigation(observation, workspaceId = '') {
+        this.ensureDirectories();
+        const id = `inv_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        const now = Date.now();
+        const investigation = {
+            id,
+            workspaceId: observation.workspaceId || workspaceId,
+            observationId: observation.observationId || `obs_${now}`,
+            observationIds: [observation.observationId || `obs_${now}`],
+            runtimeInstanceId: observation.runtimeInstanceId,
+            sessionId: observation.sessionId,
+            remediationContractId: '',
+            investigationState: 'OBSERVED',
+            remediationState: 'NOT_STARTED',
+            verificationState: 'NOT_READY',
+            originalObservation: observation,
+            evidence: [],
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.persistInvestigation(investigation);
+        return investigation;
+    }
+    persistInvestigation(investigation) {
+        this.ensureDirectories();
+        const filePath = path.join(this.investigationsDir, `${investigation.id}.json`);
+        // Write-then-rename so a crash mid-write cannot leave a truncated record.
+        const temporary = `${filePath}.tmp`;
+        fs.writeFileSync(temporary, JSON.stringify(investigation, null, 2), 'utf8');
+        fs.renameSync(temporary, filePath);
+    }
+    loadInvestigation(id) {
+        const filePath = path.join(this.investigationsDir, `${id}.json`);
+        if (!fs.existsSync(filePath))
+            return null;
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    listInvestigations() {
+        if (!fs.existsSync(this.investigationsDir))
+            return [];
+        return fs.readdirSync(this.investigationsDir)
+            .filter(file => file.endsWith('.json'))
+            .map(file => this.loadInvestigation(file.replace(/\.json$/, '')))
+            // Only records that are actually investigations count. Anything else
+            // that lands in the directory must not be reported as one.
+            .filter((investigation) => investigation !== null
+            && typeof investigation.id === 'string'
+            && typeof investigation.investigationState === 'string'
+            && typeof investigation.verificationState === 'string')
+            .sort((left, right) => left.createdAt - right.createdAt);
+    }
+    /** Find the investigation opened for a given observation, if any. */
+    findByObservationId(observationId) {
+        return this.listInvestigations().find(item => item.observationId === observationId || item.observationIds?.includes(observationId)) || null;
+    }
+    /** Add an observation reference without changing the factual observation. */
+    linkRuntimeObservationToInvestigation(observationId, investigationId) {
+        const investigation = this.require(investigationId);
+        const existing = this.findByObservationId(observationId);
+        if (existing && existing.id !== investigationId) {
+            throw new Error(`Runtime observation ${observationId} is already linked to ${existing.id}`);
+        }
+        investigation.observationIds = [...new Set([
+                investigation.observationId,
+                ...(investigation.observationIds || []),
+                observationId,
+            ])];
+        investigation.updatedAt = Date.now();
+        this.persistInvestigation(investigation);
+        return investigation;
+    }
+    require(id) {
+        const investigation = this.loadInvestigation(id);
+        if (!investigation)
+            throw new Error(`Investigation ${id} not found`);
+        return investigation;
+    }
+    // --- investigation phase ------------------------------------------------
+    /** OBSERVED -> INVESTIGATING, attaching the runtime evidence. */
+    transitionToInvestigating(id, evidence = []) {
+        const updated = transitionInvestigation(this.require(id), 'INVESTIGATING');
+        updated.evidence = [...(updated.evidence || []), ...evidence];
+        this.persistInvestigation(updated);
+        return updated;
+    }
+    /**
+     * INVESTIGATING -> FINDING.
+     *
+     * Accepts a structured {@link InvestigationFinding}. A bare string is still
+     * accepted so existing callers keep working; it is stored as an analysis
+     * finding with no evidence attribution.
+     */
+    transitionToFinding(id, finding) {
+        const updated = transitionInvestigation(this.require(id), 'FINDING');
+        updated.finding = typeof finding === 'string'
+            ? {
+                id: `finding_${Date.now()}`,
+                investigationId: id,
+                statement: finding,
+                origin: 'feltdb_analysis',
+                confidence: 'medium',
+                derivedFromEvidence: (updated.evidence || []).map(item => item.id),
+                createdAt: Date.now(),
+            }
+            : finding;
+        this.persistInvestigation(updated);
+        return updated;
+    }
+    // --- remediation phase --------------------------------------------------
+    /**
+     * FINDING -> PROPOSED and NOT_STARTED -> SENT_TO_AGENT.
+     *
+     * Records the repository state at handoff so a later comparison can prove
+     * what the agent changed.
+     */
+    sendToAgent(id, contract, gitBefore) {
+        const investigation = this.require(id);
+        const proposed = transitionInvestigation(investigation, 'PROPOSED');
+        const remediation = createRemediationContract({
+            ...contract,
+            originalObservation: contract.originalObservation || investigation.originalObservation,
+        });
+        proposed.remediationContract = remediation;
+        proposed.remediationContractId = remediation.id;
+        const sent = transitionRemediation(proposed, 'SENT_TO_AGENT');
+        if (gitBefore) {
+            sent.remediation = { investigationId: id, gitBefore, changedPaths: [] };
+        }
+        this.persistInvestigation(sent);
+        return sent;
+    }
+    /** SENT_TO_AGENT -> IMPLEMENTING. The agent has started work. */
+    markImplementing(id) {
+        const updated = transitionRemediation(this.require(id), 'IMPLEMENTING');
+        this.persistInvestigation(updated);
+        return updated;
+    }
+    /**
+     * IMPLEMENTING -> CHANGES_DETECTED, using observable repository state.
+     *
+     * Returns the investigation unchanged when the repository has not moved:
+     * FeltDB will not advance the lifecycle on an agent's say-so.
+     */
+    detectRepositoryChange(id, projectDir) {
+        const investigation = this.require(id);
+        const before = investigation.remediation?.gitBefore;
+        if (!before)
+            throw new Error(`Investigation ${id} has no repository baseline; call sendToAgent with gitBefore`);
+        const tracking = trackRemediation(id, before, projectDir);
+        if (!tracking.changeIdentity) {
+            investigation.remediation = tracking;
+            this.persistInvestigation(investigation);
+            return investigation;
+        }
+        const updated = transitionRemediation(investigation, 'CHANGES_DETECTED');
+        updated.remediation = tracking;
+        this.persistInvestigation(updated);
+        return updated;
+    }
+    /**
+     * CHANGES_DETECTED -> IMPLEMENTATION_COMPLETE, and the verification state
+     * machine becomes ready to watch the runtime.
+     *
+     * A detected repository change means remediation happened. It does not mean
+     * the defect is fixed, so this only opens verification — it never concludes it.
+     */
+    completeImplementation(id) {
+        const complete = transitionRemediation(this.require(id), 'IMPLEMENTATION_COMPLETE');
+        const waiting = transitionVerification(complete, 'WAITING_FOR_RUNTIME');
+        this.persistInvestigation(waiting);
+        return waiting;
+    }
+    // --- verification phase -------------------------------------------------
+    /**
+     * Evaluate the verification contract against a runtime observation.
+     *
+     * The outcome is decided by the observation alone. A missing or
+     * non-matching observation yields INCONCLUSIVE; it never yields VERIFIED.
+     */
+    recordVerification(id, contract, observation) {
+        let current = this.require(id);
+        if (current.verificationState === 'NOT_READY')
+            current = transitionVerification(current, 'WAITING_FOR_RUNTIME');
+        if (current.verificationState === 'WAITING_FOR_RUNTIME')
+            current = transitionVerification(current, 'VERIFYING');
+        const attempt = evaluateVerification(contract, observation);
+        const settled = transitionVerification(current, attempt.result);
+        settled.verificationId = attempt.verificationId;
+        settled.verificationAttempt = attempt;
+        if (observation) {
+            settled.verificationObservation = observation;
+            settled.observationIds = [...new Set([
+                    settled.observationId,
+                    ...(settled.observationIds || []),
+                    observation.observationId,
+                ])];
+        }
+        this.persistInvestigation(settled);
+        return settled;
+    }
+    // --- store facts --------------------------------------------------------
+    /**
+     * Measure the durable development-plane store.
+     *
+     * This is an empirical baseline for durability, queryability, and restart
+     * cost. It is not a scale claim.
+     */
+    metrics() {
+        const startedAt = Date.now();
+        const investigations = this.listInvestigations();
+        const loadMilliseconds = Date.now() - startedAt;
+        let serializedBytes = 0;
+        if (fs.existsSync(this.investigationsDir)) {
+            for (const file of fs.readdirSync(this.investigationsDir).filter(name => name.endsWith('.json'))) {
+                serializedBytes += fs.statSync(path.join(this.investigationsDir, file)).size;
+            }
+        }
+        return {
+            investigations: investigations.length,
+            observations: investigations.reduce((total, item) => total + new Set([
+                item.observationId,
+                ...(item.observationIds || []),
+                item.verificationObservation?.observationId,
+            ].filter(Boolean)).size, 0),
+            evidenceRecords: investigations.reduce((total, item) => total + (item.evidence?.length || 0), 0),
+            verifiedInvestigations: investigations.filter(item => item.verificationState === 'VERIFIED').length,
+            serializedBytes,
+            loadMilliseconds,
+        };
+    }
+}