@feltdb/core 0.6.9 → 0.6.11

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

@@ -0,0 +1,100 @@
+/**
+ * Runtime investigation supervisor.
+ *
+ * Reads durable runtime observations out of the Development Workspace, opens
+ * investigations for the ones that represent actionable defects, builds the
+ * evidence and the finding, produces the agent-executable remediation
+ * contract, tracks the repository change, and verifies the outcome against a
+ * later runtime observation.
+ *
+ * The architectural boundary is enforced here: this supervisor observes,
+ * investigates, contracts, verifies, and remembers. It never edits source and
+ * it never decides that a defect is fixed on any basis other than a runtime
+ * observation.
+ */
+import type { RemediationContract, RepositoryIdentity, RuntimeInvestigation, RuntimeRequestObservation, VerificationCriterion } from './workspace-types.js';
+import { InvestigationLifecycleManager } from './investigation-lifecycle-manager.js';
+export interface SupervisorOptions {
+    /** Directory containing `.feltdb/`. */
+    projectDir: string;
+    /** Workspace authority endpoint. */
+    endpoint: string;
+    workspaceId: string;
+    /** Directory the coding agent will modify. Defaults to the application directory. */
+    repositoryDir?: string;
+}
+/** The artifact handed to the coding agent. */
+export interface AgentHandoffArtifact {
+    investigationId: string;
+    /** Machine-readable contract. */
+    contract: RemediationContract;
+    /** Human-readable briefing. */
+    markdown: string;
+    /** Where the artifact was written for the agent to pick up. */
+    jsonPath: string;
+    markdownPath: string;
+}
+export declare class RuntimeInvestigationSupervisor {
+    readonly investigations: InvestigationLifecycleManager;
+    private readonly options;
+    private connection;
+    private readonly seenObservations;
+    constructor(options: SupervisorOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private require;
+    /** Every runtime observation the workspace has persisted. */
+    observations(): Promise<RuntimeRequestObservation[]>;
+    /**
+     * Wait for a runtime observation matching a verification criterion.
+     *
+     * Returns undefined on timeout, which is what produces an INCONCLUSIVE
+     * verification rather than a false VERIFIED.
+     */
+    awaitObservation(criterion: VerificationCriterion, options?: {
+        after: number;
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<RuntimeRequestObservation | undefined>;
+    /**
+     * Open investigations for actionable defects that do not have one yet.
+     *
+     * Successful requests are persisted as observations but never open an
+     * investigation.
+     */
+    ingestObservations(): Promise<RuntimeInvestigation[]>;
+    /**
+     * Drive a single observation through investigation and analysis.
+     *
+     * Ends in PROPOSED with evidence, a finding, and a remediation contract, and
+     * with the repository baseline recorded so the change can be attributed.
+     */
+    openInvestigation(observation: RuntimeRequestObservation): RuntimeInvestigation;
+    /** Repository state, used as the remediation baseline. */
+    repositoryIdentity(): RepositoryIdentity;
+    /** Source files that exist on disk and could implement the observed route. */
+    private relevantSource;
+    /**
+     * Write the agent handoff artifact.
+     *
+     * FeltDB stops here: it produces a complete, machine-readable engineering
+     * contract and hands it over. Inspecting the repository and editing source
+     * is the coding agent's job, not FeltDB's.
+     */
+    writeAgentHandoff(investigationId: string): AgentHandoffArtifact;
+    /** Whether the repository moved since the investigation baseline. */
+    detectRepositoryChange(investigationId: string): RuntimeInvestigation;
+    /**
+     * Verify the contract against the runtime.
+     *
+     * Waits for a matching runtime observation produced after the code change
+     * and evaluates it. No observation means INCONCLUSIVE.
+     */
+    verify(investigationId: string, options?: {
+        after: number;
+        timeoutMs?: number;
+    }): Promise<RuntimeInvestigation>;
+    /** One-line description of why an investigation exists. */
+    describe(investigation: RuntimeInvestigation): string;
+}
+//# sourceMappingURL=investigation-supervisor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"investigation-supervisor.d.ts","sourceRoot":"","sources":["../../src/workspace/investigation-supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAW9B,OAAO,EAAE,6BAA6B,EAAE,MAAM,sCAAsC,CAAC;AAKrF,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,8BAA8B;IACzC,QAAQ,CAAC,cAAc,EAAE,6BAA6B,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAE1C,OAAO,EAAE,iBAAiB;IAYhC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IASxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,OAAO,CAAC,OAAO;IAKf,6DAA6D;IACvD,YAAY,IAAI,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAK1D;;;;;OAKG;IACG,gBAAgB,CACpB,SAAS,EAAE,qBAAqB,EAChC,OAAO,GAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAiB,GACjF,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC;IAcjD;;;;;OAKG;IACG,kBAAkB,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAW3D;;;;;OAKG;IACH,iBAAiB,CAAC,WAAW,EAAE,yBAAyB,GAAG,oBAAoB;IAmB/E,0DAA0D;IAC1D,kBAAkB,IAAI,kBAAkB;IAIxC,8EAA8E;IAC9E,OAAO,CAAC,cAAc;IAMtB;;;;;;OAMG;IACH,iBAAiB,CAAC,eAAe,EAAE,MAAM,GAAG,oBAAoB;IA8DhE,qEAAqE;IACrE,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,oBAAoB;IAWrE;;;;;OAKG;IACG,MAAM,CACV,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAiB,GAC5D,OAAO,CAAC,oBAAoB,CAAC;IAUhC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,oBAAoB,GAAG,MAAM;CAGtD"}

package/dist/workspace/investigation-supervisor.js

@@ -0,0 +1,238 @@
+/**
+ * Runtime investigation supervisor.
+ *
+ * Reads durable runtime observations out of the Development Workspace, opens
+ * investigations for the ones that represent actionable defects, builds the
+ * evidence and the finding, produces the agent-executable remediation
+ * contract, tracks the repository change, and verifies the outcome against a
+ * later runtime observation.
+ *
+ * The architectural boundary is enforced here: this supervisor observes,
+ * investigates, contracts, verifies, and remembers. It never edits source and
+ * it never decides that a defect is fixed on any basis other than a runtime
+ * observation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { RUNTIME_OBSERVATION_COLLECTION, isActionableRuntimeDefect } from './runtime-observation.js';
+import { collectEvidence, candidateSourcePaths, deriveFinding, recommendChanges, resolveRelevantSource, summarizeDefect, verificationContractFor, } from './investigation-analysis.js';
+import { InvestigationLifecycleManager } from './investigation-lifecycle-manager.js';
+import { captureRepositoryIdentity } from './git-identity.js';
+import { agentRemediationHandoff } from './runtime-investigation.js';
+import { connectDevelopmentWorkspace } from './workspace-connection.js';
+export class RuntimeInvestigationSupervisor {
+    constructor(options) {
+        this.connection = null;
+        this.seenObservations = new Set();
+        this.options = options;
+        this.investigations = new InvestigationLifecycleManager(options.projectDir);
+        // Observations already turned into investigations must not re-open on a
+        // restart, so the seen set is rebuilt from durable state.
+        for (const investigation of this.investigations.listInvestigations()) {
+            for (const observationId of investigation.observationIds || [investigation.observationId]) {
+                this.seenObservations.add(observationId);
+            }
+        }
+    }
+    async connect() {
+        if (this.connection)
+            return;
+        this.connection = await connectDevelopmentWorkspace({
+            workspaceId: this.options.workspaceId,
+            endpoint: this.options.endpoint,
+            clientType: 'agent',
+        });
+    }
+    async disconnect() {
+        await this.connection?.disconnect();
+        this.connection = null;
+    }
+    require() {
+        if (!this.connection)
+            throw new Error('Supervisor is not connected to the workspace');
+        return this.connection;
+    }
+    /** Every runtime observation the workspace has persisted. */
+    async observations() {
+        const records = await this.require().query(RUNTIME_OBSERVATION_COLLECTION);
+        return records.sort((left, right) => left.timestamp - right.timestamp);
+    }
+    /**
+     * Wait for a runtime observation matching a verification criterion.
+     *
+     * Returns undefined on timeout, which is what produces an INCONCLUSIVE
+     * verification rather than a false VERIFIED.
+     */
+    async awaitObservation(criterion, options = { after: 0 }) {
+        const deadline = Date.now() + (options.timeoutMs ?? 10000);
+        const interval = options.intervalMs ?? 100;
+        while (Date.now() < deadline) {
+            const match = (await this.observations()).find(observation => observation.timestamp > options.after
+                && observation.method.toUpperCase() === criterion.method.toUpperCase()
+                && samePath(observation.url, criterion.url));
+            if (match)
+                return match;
+            await delay(interval);
+        }
+        return undefined;
+    }
+    /**
+     * Open investigations for actionable defects that do not have one yet.
+     *
+     * Successful requests are persisted as observations but never open an
+     * investigation.
+     */
+    async ingestObservations() {
+        const opened = [];
+        for (const observation of await this.observations()) {
+            if (this.seenObservations.has(observation.observationId))
+                continue;
+            this.seenObservations.add(observation.observationId);
+            if (!isActionableRuntimeDefect(observation))
+                continue;
+            opened.push(this.openInvestigation(observation));
+        }
+        return opened;
+    }
+    /**
+     * Drive a single observation through investigation and analysis.
+     *
+     * Ends in PROPOSED with evidence, a finding, and a remediation contract, and
+     * with the repository baseline recorded so the change can be attributed.
+     */
+    openInvestigation(observation) {
+        const created = this.investigations.createInvestigation(observation, this.options.workspaceId);
+        const evidence = collectEvidence(created.id, observation);
+        this.investigations.transitionToInvestigating(created.id, evidence);
+        const finding = deriveFinding(created.id, observation, evidence);
+        this.investigations.transitionToFinding(created.id, finding);
+        const contract = {
+            investigationId: created.id,
+            originalObservation: observation,
+            finding: finding.statement,
+            evidence: evidence.map(item => item.statement),
+            relevantSource: this.relevantSource(observation.url),
+            recommendedChanges: recommendChanges(observation),
+            verificationCriteria: verificationContractFor(observation),
+        };
+        return this.investigations.sendToAgent(created.id, contract, this.repositoryIdentity());
+    }
+    /** Repository state, used as the remediation baseline. */
+    repositoryIdentity() {
+        return captureRepositoryIdentity(this.options.repositoryDir || this.options.projectDir);
+    }
+    /** Source files that exist on disk and could implement the observed route. */
+    relevantSource(url) {
+        const root = this.options.repositoryDir || this.options.projectDir;
+        const existing = candidateSourcePaths(url).filter(candidate => fs.existsSync(path.join(root, candidate)));
+        return resolveRelevantSource(url, existing);
+    }
+    /**
+     * Write the agent handoff artifact.
+     *
+     * FeltDB stops here: it produces a complete, machine-readable engineering
+     * contract and hands it over. Inspecting the repository and editing source
+     * is the coding agent's job, not FeltDB's.
+     */
+    writeAgentHandoff(investigationId) {
+        const investigation = this.investigations.loadInvestigation(investigationId);
+        if (!investigation?.remediationContract) {
+            throw new Error(`Investigation ${investigationId} has no remediation contract`);
+        }
+        const contract = investigation.remediationContract;
+        // Handoff artifacts live beside the investigation store, never inside it:
+        // a `<id>.agent.json` in the store would be read back as an investigation.
+        const directory = path.join(this.options.projectDir, '.feltdb', 'handoff');
+        fs.mkdirSync(directory, { recursive: true });
+        const jsonPath = path.join(directory, `${investigationId}.agent.json`);
+        const markdownPath = path.join(directory, `${investigationId}.agent.md`);
+        const markdown = [
+            `# FeltDB Investigation ${investigationId}`,
+            '',
+            '## Observation',
+            `${contract.originalObservation.method} ${contract.originalObservation.url} -> HTTP ${contract.originalObservation.status}`,
+            `Observed by: ${contract.originalObservation.browser || 'unknown'} (${contract.originalObservation.runtime || 'unknown'})`,
+            '',
+            '## Evidence (observed by the runtime)',
+            ...(investigation.evidence || []).map(item => `- [${item.kind}] ${item.statement}`),
+            '',
+            '## Finding (FeltDB analysis, not an observation)',
+            contract.finding,
+            `Confidence: ${investigation.finding?.confidence || 'unknown'}`,
+            '',
+            '## Relevant source',
+            ...(contract.relevantSource.length > 0
+                ? contract.relevantSource.map(item => `- ${item.file}${item.line ? `:${item.line}` : ''}`)
+                : ['- (no route file matched; locate the handler for this path)']),
+            '',
+            '## Recommended change',
+            ...contract.recommendedChanges.map(item => `- ${item}`),
+            '',
+            '## Verification contract',
+            ...contract.verificationCriteria.map(item => `- ${item.kind}: ${item.method} ${item.url} must return one of [${(item.expectedStatuses || []).join(', ')}]`),
+            '',
+            'FeltDB verifies this contract against a real runtime observation after you change the code.',
+            'A passing build, a passing test, or a commit does not satisfy it.',
+        ].join('\n');
+        fs.writeFileSync(jsonPath, JSON.stringify({
+            investigationId,
+            workspaceId: investigation.workspaceId,
+            // The agent needs to know which repository the source paths are relative
+            // to; without it the contract would not be independently actionable.
+            repositoryDir: path.resolve(this.options.repositoryDir || this.options.projectDir),
+            observation: contract.originalObservation,
+            evidence: investigation.evidence || [],
+            finding: investigation.finding,
+            relevantSource: contract.relevantSource,
+            recommendedChanges: contract.recommendedChanges,
+            verificationContract: contract.verificationCriteria,
+            instructions: agentRemediationHandoff(contract),
+        }, null, 2), 'utf8');
+        fs.writeFileSync(markdownPath, `${markdown}\n`, 'utf8');
+        return { investigationId, contract, markdown, jsonPath, markdownPath };
+    }
+    /** Whether the repository moved since the investigation baseline. */
+    detectRepositoryChange(investigationId) {
+        const repositoryDir = this.options.repositoryDir || this.options.projectDir;
+        const investigation = this.investigations.loadInvestigation(investigationId);
+        if (!investigation)
+            throw new Error(`Investigation ${investigationId} not found`);
+        const started = investigation.remediationState === 'SENT_TO_AGENT'
+            ? this.investigations.markImplementing(investigationId)
+            : investigation;
+        void started;
+        return this.investigations.detectRepositoryChange(investigationId, repositoryDir);
+    }
+    /**
+     * Verify the contract against the runtime.
+     *
+     * Waits for a matching runtime observation produced after the code change
+     * and evaluates it. No observation means INCONCLUSIVE.
+     */
+    async verify(investigationId, options = { after: 0 }) {
+        const investigation = this.investigations.loadInvestigation(investigationId);
+        if (!investigation?.remediationContract) {
+            throw new Error(`Investigation ${investigationId} has no remediation contract`);
+        }
+        const criterion = investigation.remediationContract.verificationCriteria.find(item => item.kind === 'primary');
+        const observation = await this.awaitObservation(criterion, options);
+        return this.investigations.recordVerification(investigationId, investigation.remediationContract, observation);
+    }
+    /** One-line description of why an investigation exists. */
+    describe(investigation) {
+        return investigation.originalObservation ? summarizeDefect(investigation.originalObservation) : investigation.id;
+    }
+}
+function samePath(actual, expected) {
+    try {
+        const left = new URL(actual, 'http://localhost');
+        const right = new URL(expected, 'http://localhost');
+        return left.origin === right.origin && left.pathname === right.pathname && left.search === right.search;
+    }
+    catch {
+        return actual === expected;
+    }
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

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

@@ -1,11 +1,15 @@
 import type { InvestigationState, RemediationContract, RemediationState, RuntimeInvestigation, RuntimeRequestObservation, VerificationAttempt, VerificationState, WorkspaceActivity } from './workspace-types.js';
+/** Canonical FeltDB investigation collection. */
+export declare const RUNTIME_INVESTIGATION_COLLECTION = "runtime_investigation";
+/** External/legacy DevTools collection retained without migration. */
+export declare const LEGACY_RUNTIME_INVESTIGATION_COLLECTION = "runtime_investigations";
 export declare function transitionInvestigation(investigation: RuntimeInvestigation, next: InvestigationState): RuntimeInvestigation;
 export declare function transitionRemediation(investigation: RuntimeInvestigation, next: RemediationState): RuntimeInvestigation;
 export declare function transitionVerification(investigation: RuntimeInvestigation, next: VerificationState): RuntimeInvestigation;
 export declare function createRemediationContract(input: Omit<RemediationContract, 'id' | 'observationId' | 'createdAt' | 'updatedAt'>): RemediationContract;
 export declare function classifyWorkspaceActivity(investigationId: string, paths: string[]): WorkspaceActivity;
 export declare function evaluateVerification(contract: RemediationContract, observation?: RuntimeRequestObservation, verificationId?: string): VerificationAttempt;
-export declare const RUNTIME_INVESTIGATION_INSTRUCTIONS = "Your job:\nInvestigate this runtime observation only.\nDetermine whether it represents an actual defect, identify the most likely root cause, inspect the relevant source, reproduce the behavior when possible, and propose a fix.\nInvestigation is read-only.\nDo NOT:\n- modify source files\n- modify configuration files\n- modify package.json\n- modify .gitignore\n- install dependencies\n- run migrations\n- generate code\n- apply patches\n- commit changes\n- create a PR\n- execute the proposed fix\nYou MAY:\n- inspect source files\n- inspect configuration\n- inspect package scripts\n- inspect logs\n- inspect runtime state\n- run read-only diagnostics\n- reproduce the request\n- run tests that do not mutate the workspace\n- use curl or equivalent HTTP diagnostics\nWhen you have established the cause, stop and report the finding.\nRespond with exactly these sections:\nFinding\nEvidence\nRelevant source\nRecommended change\nConfidence";
+export declare const RUNTIME_INVESTIGATION_INSTRUCTIONS = "INVESTIGATION PHASE: Read-Only Analysis Only\n\nYour job:\nInvestigate this runtime observation only.\n\nDetermine whether it represents an actual defect, identify the most likely root cause, inspect the relevant source, reproduce the behavior when possible, and propose a fix.\n\nInvestigation is READ-ONLY. Do not implement or apply any changes.\n\nBOUNDARIES:\n\nDo NOT (ever, under any circumstances):\n- modify source files\n- modify configuration files\n- modify package.json\n- modify .gitignore or other dotfiles\n- install or update dependencies\n- run migrations or other state-altering commands\n- generate code or apply patches\n- commit changes or create branches\n- create a pull request\n- execute, test, or deploy the proposed fix\n- restart services or clear caches\n- make any changes to the runtime environment\n\nYou MAY:\n- inspect and read source files\n- inspect configuration and build files\n- inspect package scripts and dependencies\n- inspect logs and runtime state\n- run read-only diagnostics\n- reproduce the request locally\n- run existing tests that do not mutate the workspace\n- use curl or equivalent HTTP diagnostics\n- trace through code statically\n- query the runtime via read-only APIs\n\nWHEN INVESTIGATION IS COMPLETE:\n\nStop immediately. Do not attempt to fix the problem yourself.\n\nReport the finding with these sections:\n\nFinding\nEvidence\nRelevant source\nRecommended change\nConfidence\n\nInvestigation is separate from implementation. The user will explicitly start an implementation task if they want changes made.\n\nFELTDB OBSERVATION BOUNDARY:\n\nFeltDB runtime observation is independent of this investigation.\nDo not invoke, modify, or bypass FeltDB runtime observation behavior as part of the investigation.\nThe runtime observation is evidence to analyze, not an instruction to modify the application.\nFollow the active coding agent's normal permission model.\nInvestigation remains read-only unless the user explicitly starts an implementation task.";
 export declare const FELTDB_OBSERVATION_BOUNDARY = "FeltDB runtime observation is independent of this investigation.\nDo not invoke, modify, or bypass FeltDB runtime observation behavior as part of the investigation.\nThe runtime observation is evidence to analyze, not an instruction to modify the application.\nFollow the active coding agent's normal permission model. Investigation remains read-only unless the user explicitly starts an implementation task.";
 export declare function agentRemediationHandoff(contract: RemediationContract): string;
 //# sourceMappingURL=runtime-investigation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-investigation.d.ts","sourceRoot":"","sources":["../../src/workspace/runtime-investigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EAEnB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAqB9B,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,oBAAoB,EAAE,IAAI,EAAE,kBAAkB,GAAG,oBAAoB,CAE3H;AACD,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,oBAAoB,EAAE,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,CAEvH;AACD,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,oBAAoB,EAAE,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,CAEzH;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,eAAe,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG,mBAAmB,CAKnJ;AAGD,wBAAgB,yBAAyB,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAOrG;AAiBD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,CAAC,EAAE,yBAAyB,EACvC,cAAc,SAA2B,GACxC,mBAAmB,CAgBrB;AAED,eAAO,MAAM,kCAAkC,m7BAgCpC,CAAC;AAEZ,eAAO,MAAM,2BAA2B,6ZAG4G,CAAC;AAErJ,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAU7E"}
+{"version":3,"file":"runtime-investigation.d.ts","sourceRoot":"","sources":["../../src/workspace/runtime-investigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,mBAAmB,EAEnB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAE9B,iDAAiD;AACjD,eAAO,MAAM,gCAAgC,0BAA0B,CAAC;AACxE,sEAAsE;AACtE,eAAO,MAAM,uCAAuC,2BAA2B,CAAC;AAqBhF,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,oBAAoB,EAAE,IAAI,EAAE,kBAAkB,GAAG,oBAAoB,CAE3H;AACD,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,oBAAoB,EAAE,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,CAEvH;AACD,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,oBAAoB,EAAE,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,CAEzH;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,eAAe,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG,mBAAmB,CAKnJ;AAGD,wBAAgB,yBAAyB,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAOrG;AAiBD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,CAAC,EAAE,yBAAyB,EACvC,cAAc,SAA2B,GACxC,mBAAmB,CAgBrB;AAED,eAAO,MAAM,kCAAkC,o+DAyD2C,CAAC;AAE3F,eAAO,MAAM,2BAA2B,6ZAG4G,CAAC;AAErJ,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAU7E"}

package/dist/workspace/runtime-investigation.js

@@ -1,3 +1,7 @@
+/** Canonical FeltDB investigation collection. */
+export const RUNTIME_INVESTIGATION_COLLECTION = 'runtime_investigation';
+/** External/legacy DevTools collection retained without migration. */
+export const LEGACY_RUNTIME_INVESTIGATION_COLLECTION = 'runtime_investigations';
 const INVESTIGATION_TRANSITIONS = {
     OBSERVED: ['INVESTIGATING'], INVESTIGATING: ['FINDING'], FINDING: ['PROPOSED'], PROPOSED: [],
 };
@@ -78,39 +82,64 @@ export function evaluateVerification(contract, observation, verificationId = uni
         summary: fixed ? 'The primary verification contract succeeded.' : 'The original defect remains reproducible.',
     };
 }
-export const RUNTIME_INVESTIGATION_INSTRUCTIONS = `Your job:
+export const RUNTIME_INVESTIGATION_INSTRUCTIONS = `INVESTIGATION PHASE: Read-Only Analysis Only
+
+Your job:
 Investigate this runtime observation only.
+
 Determine whether it represents an actual defect, identify the most likely root cause, inspect the relevant source, reproduce the behavior when possible, and propose a fix.
-Investigation is read-only.
-Do NOT:
+
+Investigation is READ-ONLY. Do not implement or apply any changes.
+
+BOUNDARIES:
+
+Do NOT (ever, under any circumstances):
 - modify source files
 - modify configuration files
 - modify package.json
-- modify .gitignore
-- install dependencies
-- run migrations
-- generate code
-- apply patches
-- commit changes
-- create a PR
-- execute the proposed fix
+- modify .gitignore or other dotfiles
+- install or update dependencies
+- run migrations or other state-altering commands
+- generate code or apply patches
+- commit changes or create branches
+- create a pull request
+- execute, test, or deploy the proposed fix
+- restart services or clear caches
+- make any changes to the runtime environment
+
 You MAY:
-- inspect source files
-- inspect configuration
-- inspect package scripts
-- inspect logs
-- inspect runtime state
+- inspect and read source files
+- inspect configuration and build files
+- inspect package scripts and dependencies
+- inspect logs and runtime state
 - run read-only diagnostics
-- reproduce the request
-- run tests that do not mutate the workspace
+- reproduce the request locally
+- run existing tests that do not mutate the workspace
 - use curl or equivalent HTTP diagnostics
-When you have established the cause, stop and report the finding.
-Respond with exactly these sections:
+- trace through code statically
+- query the runtime via read-only APIs
+
+WHEN INVESTIGATION IS COMPLETE:
+
+Stop immediately. Do not attempt to fix the problem yourself.
+
+Report the finding with these sections:
+
 Finding
 Evidence
 Relevant source
 Recommended change
-Confidence`;
+Confidence
+
+Investigation is separate from implementation. The user will explicitly start an implementation task if they want changes made.
+
+FELTDB OBSERVATION BOUNDARY:
+
+FeltDB runtime observation is independent of this investigation.
+Do not invoke, modify, or bypass FeltDB runtime observation behavior as part of the investigation.
+The runtime observation is evidence to analyze, not an instruction to modify the application.
+Follow the active coding agent's normal permission model.
+Investigation remains read-only unless the user explicitly starts an implementation task.`;
 export const FELTDB_OBSERVATION_BOUNDARY = `FeltDB runtime observation is independent of this investigation.
 Do not invoke, modify, or bypass FeltDB runtime observation behavior as part of the investigation.
 The runtime observation is evidence to analyze, not an instruction to modify the application.

package/dist/workspace/runtime-observation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * FeltDB Runtime Observation Contract
+ *
+ * The single observation model shared by every runtime that reports into a
+ * FeltDB Development Workspace. The browser runtime in `@feltdb/core` produces
+ * these records, the workspace persists them durably, investigations are
+ * created from them, and verification is evaluated against them.
+ *
+ * This module is browser-safe: it must not import Node built-ins.
+ */
+import type { CorrelatedRuntimeEvent, RuntimeObservationCorrelation, RuntimeRequestObservation } from './workspace-types.js';
+/** Workspace collection holding durable runtime observations. */
+export declare const RUNTIME_OBSERVATION_COLLECTION = "runtime_observation";
+/**
+ * Query parameter names whose values are replaced before an observation is
+ * persisted. Matching is case-insensitive and substring-based so that
+ * `access_token`, `apiKey`, and `X-Session` are all covered.
+ */
+export declare const REDACTED_PARAMETER_PATTERNS: string[];
+/** Placeholder substituted for a redacted value. */
+export declare const REDACTION_PLACEHOLDER = "[redacted]";
+/**
+ * Redact sensitive values from a URL while preserving the parts verification
+ * depends on: origin, pathname, and the set of query parameter names.
+ *
+ * FeltDB never captures request or response bodies, and never captures
+ * `Authorization` or `Cookie` headers, so URL redaction is the only place
+ * where credential material can reach a persisted observation.
+ */
+export declare function redactUrl(url: string): string;
+/** Redact a free-text runtime message that may embed a URL or credential. */
+export declare function redactMessage(message: string): string;
+/** Browser family and engine derived from a user agent string. */
+export declare function describeBrowser(userAgent: string): {
+    browser: string;
+    engine: string;
+};
+/**
+ * Whether an observation represents an actionable runtime defect.
+ *
+ * FeltDB does not open an investigation for every request. Only these
+ * qualify:
+ *   - a server-error response (HTTP >= 500)
+ *   - a request that produced no response at all (network failure)
+ *   - a client-error response correlated with a runtime or console error
+ *
+ * Successful requests, redirects, and bare 4xx responses (which are usually
+ * intentional application behavior) do not open investigations.
+ */
+export declare function isActionableRuntimeDefect(observation: RuntimeRequestObservation): boolean;
+/** Human-readable reason an observation was treated as actionable. */
+export declare function describeDefect(observation: RuntimeRequestObservation): string;
+/** Generate a workspace-unique observation identifier. */
+export declare function createObservationId(): string;
+/** Generate a correlation identifier for a single in-flight request. */
+export declare function createCorrelationId(): string;
+export interface RuntimeObservationInput {
+    method: string;
+    url: string;
+    status: number;
+    startedAt: number;
+    completedAt: number;
+    workspaceId?: string;
+    sessionId?: string;
+    runtimeInstanceId?: string;
+    correlation?: RuntimeObservationCorrelation;
+    page?: string;
+    userAgent?: string;
+    correlationId?: string;
+    correlatedEvents?: CorrelatedRuntimeEvent[];
+    networkFailure?: boolean;
+    requestCharacteristics?: Record<string, unknown>;
+    responseCharacteristics?: Record<string, unknown>;
+}
+/**
+ * Build a redacted runtime observation.
+ *
+ * All redaction is applied here so that no caller can persist an unredacted
+ * observation by accident.
+ */
+export declare function createRuntimeObservation(input: RuntimeObservationInput): RuntimeRequestObservation;
+//# sourceMappingURL=runtime-observation.d.ts.map

package/dist/workspace/runtime-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-observation.d.ts","sourceRoot":"","sources":["../../src/workspace/runtime-observation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,6BAA6B,EAC7B,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAE9B,iEAAiE;AACjE,eAAO,MAAM,8BAA8B,wBAAwB,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,UAGvC,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAOlD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgB7C;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAatF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,yBAAyB,GAAG,OAAO,CAQzF;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,WAAW,EAAE,yBAAyB,GAAG,MAAM,CAI7E;AAID,0DAA0D;AAC1D,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,6BAA6B,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC5C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnD;AAcD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,GAAG,yBAAyB,CAiClG"}