@feltdb/core 0.6.8 → 0.6.10

package/dist/workspace/investigation-supervisor.js

@@ -0,0 +1,236 @@
+/**
+ * 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()) {
+            this.seenObservations.add(investigation.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

@@ -5,7 +5,7 @@ export declare function transitionVerification(investigation: RuntimeInvestigati
 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;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,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

@@ -78,39 +78,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,79 @@
+/**
+ * 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, 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;
+    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,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAE9F,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,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;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,GAAG,yBAAyB,CAwBlG"}

package/dist/workspace/runtime-observation.js

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+/** Workspace collection holding durable runtime observations. */
+export 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 const REDACTED_PARAMETER_PATTERNS = [
+    'token', 'key', 'secret', 'password', 'passwd', 'auth', 'session',
+    'credential', 'signature', 'sig', 'code', 'assertion', 'bearer',
+];
+/** Placeholder substituted for a redacted value. */
+export const REDACTION_PLACEHOLDER = '[redacted]';
+function isRedactedParameter(name) {
+    const lowered = name.toLowerCase();
+    return REDACTED_PARAMETER_PATTERNS.some(pattern => lowered.includes(pattern));
+}
+/**
+ * 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 function redactUrl(url) {
+    try {
+        const parsed = new URL(url, typeof location !== 'undefined' ? location.href : 'http://localhost');
+        if (parsed.username || parsed.password) {
+            parsed.username = '';
+            parsed.password = '';
+        }
+        for (const name of [...parsed.searchParams.keys()]) {
+            if (isRedactedParameter(name))
+                parsed.searchParams.set(name, REDACTION_PLACEHOLDER);
+        }
+        if (parsed.hash)
+            parsed.hash = '';
+        return parsed.toString();
+    }
+    catch {
+        // A URL we cannot parse is a URL we cannot safely redact.
+        return REDACTION_PLACEHOLDER;
+    }
+}
+/** Redact a free-text runtime message that may embed a URL or credential. */
+export function redactMessage(message) {
+    return message.replace(/https?:\/\/[^\s"'`)]+/g, match => redactUrl(match));
+}
+/** Browser family and engine derived from a user agent string. */
+export function describeBrowser(userAgent) {
+    const ua = userAgent || '';
+    // Order matters: Brave/Edge/Opera all also claim "Chrome".
+    if (/\bBrave\//i.test(ua))
+        return { browser: 'Brave', engine: 'Blink' };
+    if (/\bEdg\//.test(ua))
+        return { browser: 'Edge', engine: 'Blink' };
+    if (/\bOPR\//.test(ua))
+        return { browser: 'Opera', engine: 'Blink' };
+    if (/\bFirefox\//.test(ua))
+        return { browser: 'Firefox', engine: 'Gecko' };
+    // `HeadlessChrome/` has no word boundary before "Chrome", so match the token
+    // directly. Headless Chrome is still Chrome, and still Blink.
+    if (/(?:Headless)?Chrome\//.test(ua))
+        return { browser: 'Chrome', engine: 'Blink' };
+    // Safari identifies itself last because Chromium also carries "Safari".
+    if (/\bSafari\//.test(ua) && /\bVersion\//.test(ua))
+        return { browser: 'Safari', engine: 'WebKit' };
+    return { browser: 'Unknown', engine: 'Unknown' };
+}
+/**
+ * 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 function isActionableRuntimeDefect(observation) {
+    if (observation.networkFailure)
+        return true;
+    if (observation.status >= 500)
+        return true;
+    if (observation.status >= 400) {
+        return (observation.correlatedEvents || [])
+            .some(event => event.kind === 'runtime_error' || event.kind === 'unhandled_rejection');
+    }
+    return false;
+}
+/** Human-readable reason an observation was treated as actionable. */
+export function describeDefect(observation) {
+    if (observation.networkFailure)
+        return 'the request produced no HTTP response';
+    if (observation.status >= 500)
+        return `the endpoint responded with HTTP ${observation.status}`;
+    return `the endpoint responded with HTTP ${observation.status} alongside a runtime error`;
+}
+let observationCounter = 0;
+/** Generate a workspace-unique observation identifier. */
+export function createObservationId() {
+    observationCounter += 1;
+    return `obs_${Date.now()}_${observationCounter}_${Math.random().toString(36).slice(2, 9)}`;
+}
+/** Generate a correlation identifier for a single in-flight request. */
+export function createCorrelationId() {
+    return `corr_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+ * Build a redacted runtime observation.
+ *
+ * All redaction is applied here so that no caller can persist an unredacted
+ * observation by accident.
+ */
+export function createRuntimeObservation(input) {
+    const { browser, engine } = describeBrowser(input.userAgent || '');
+    return {
+        observationId: createObservationId(),
+        workspaceId: input.workspaceId,
+        method: input.method.toUpperCase(),
+        url: redactUrl(input.url),
+        status: input.status,
+        timestamp: input.completedAt,
+        durationMs: Math.max(0, input.completedAt - input.startedAt),
+        runtime: 'browser',
+        browser,
+        engine,
+        page: input.page ? redactUrl(input.page) : undefined,
+        correlationId: input.correlationId,
+        correlatedEvents: (input.correlatedEvents || []).map(event => ({
+            ...event,
+            message: redactMessage(event.message),
+            stack: event.stack ? redactMessage(event.stack) : undefined,
+        })),
+        networkFailure: input.networkFailure || undefined,
+        requestCharacteristics: input.requestCharacteristics,
+        responseCharacteristics: input.responseCharacteristics,
+    };
+}

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

@@ -0,0 +1,51 @@
+/**
+ * FeltDB Browser Runtime Observation
+ *
+ * The runtime that ships inside `@feltdb/core` and runs in the developer's
+ * browser. It instruments the page's HTTP and error surfaces, correlates
+ * console/runtime errors to the request that was in flight, and publishes
+ * redacted observations into the FeltDB Development Workspace, where they are
+ * persisted durably.
+ *
+ * Browser → @feltdb/core → observation → FeltDB workspace → durable persistence
+ *
+ * This module is browser-safe: it must not import Node built-ins. It uses only
+ * `fetch`, `XMLHttpRequest`, `console`, and `window` event handlers, so the
+ * same contract is produced by Chromium, Gecko, and WebKit browsers even
+ * though their internal implementations differ.
+ */
+import type { RuntimeRequestObservation } from './workspace-types.js';
+export interface RuntimeObservationOptions {
+    /** Pairing code (FELT-XXXXXX) printed by `feltdb dev`. */
+    pairingCode?: string;
+    /** Pairing discovery endpoint, when it differs from the authority. */
+    discoveryEndpoint?: string;
+    /** Authority endpoint, when the workspace is already known. */
+    endpoint?: string;
+    /** Workspace id, when the workspace is already known. */
+    workspaceId?: string;
+    /**
+     * How long a failing request is held so that console and runtime errors
+     * emitted immediately afterwards can be correlated to it.
+     */
+    correlationWindowMs?: number;
+    /** Expose the handle as `globalThis.__feltdbRuntime`. Defaults to true. */
+    exposeGlobal?: boolean;
+}
+export interface RuntimeObservationHandle {
+    workspaceId: string;
+    /** Observations produced by this page, in order. */
+    observations(): RuntimeRequestObservation[];
+    /** Resolve once every pending observation has been persisted. */
+    flush(): Promise<void>;
+    /** Restore the original browser APIs and disconnect from the workspace. */
+    stop(): Promise<void>;
+}
+/**
+ * Start observing the current page and reporting into the workspace.
+ *
+ * Returns once the workspace connection is established, so a caller can await
+ * it before exercising the application.
+ */
+export declare function startRuntimeObservation(options: RuntimeObservationOptions): Promise<RuntimeObservationHandle>;
+//# sourceMappingURL=runtime-observer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-observer.d.ts","sourceRoot":"","sources":["../../src/workspace/runtime-observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA0B,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAS9F,MAAM,WAAW,yBAAyB;IACxC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,YAAY,IAAI,yBAAyB,EAAE,CAAC;IAC5C,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,2EAA2E;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAID;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA0PnC"}