diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac09b405e..5658c2480 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,8 +31,8 @@ lint:dead` rejects unused files, exports, and dependencies. Set `REA_LOG_LEVEL` to `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `silent` to control structured JSON diagnostics. MCP mode defaults to `info` and always writes logs to stderr so the stdio protocol remains intact. One-shot CLI -logging is opt-in and writes to stdout when a level is configured, preserving -machine-readable command output by default. Request arguments, bridge +logging is opt-in and writes to stderr when a level is configured, preserving +machine-readable command output. Request arguments, bridge authentication tokens, and environment data are redacted. Changes that claim real Hopper behavior must also be tested against two distinct binaries: diff --git a/README.md b/README.md index 08f341812..26e454eea 100644 --- a/README.md +++ b/README.md @@ -431,6 +431,19 @@ Run `npx -y rea-agents --help` for direct decompilation, bounded search and other options. `analyze` and `inspect` share the same overview workflow; `function`, `xrefs`, and `trace` return the same Evidence v2 envelopes as MCP. +CLI exit status is independent of output format, full output, filtering, and +token limits: + +| Status | Meaning | +| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0` | The requested operation completed truthfully. Explicit unknown, bounded, or truncated evidence remains successful when the operation completed under its declared contract. | +| `1` | Argument validation, approval or policy, provider or analysis, integrity, cancellation or timeout, serialization, or output failed. Structured output retains the typed category and safe diagnostic details when available. | + +Machine-readable failures remain on stdout in the requested format; incidental +diagnostics and progress use stderr. Signal termination retains the conventional +status supplied by the shell and runtime. Shell pipelines should enable +`pipefail` when the REA status must propagate through later commands. + Or install the `rea` command globally: ```bash diff --git a/src/application/UnknownRegistry.ts b/src/application/UnknownRegistry.ts new file mode 100644 index 000000000..76987c29b --- /dev/null +++ b/src/application/UnknownRegistry.ts @@ -0,0 +1,153 @@ +import { + createResidualUnknown, + updateResidualUnknown, + residualUnknownSchema, + type RecordUnknownInput, + type ResidualUnknown, + type UnknownStatus, + type UpdateUnknownInput, +} from "../domain/residualUnknown.js"; +import { UnknownRegistryError } from "../domain/errors.js"; +import { err, ok, type Result } from "../domain/result.js"; + +export interface UnknownRegistryLimits { + readonly maxRecords: number; + readonly maxRelationships: number; +} + +type UnknownRegistryMutation = Result; + +type UnknownRegistryQuery = Result< + readonly ResidualUnknown[], + UnknownRegistryError +>; + +type UnknownRegistryVerify = Result< + { + readonly valid: boolean; + readonly truthVerified: boolean; + readonly unknown: ResidualUnknown; + }, + UnknownRegistryError +>; + +/** + * Persistent, bounded registry of residual unknowns linked to evidence. + * + * Each unknown carries a stable ID derived from its question and scope, + * an immutable revision graph, and evidence-qualified resolution state. + */ +export class UnknownRegistry { + readonly #revisions = new Map(); + readonly #heads = new Map(); + + constructor(private readonly limits: UnknownRegistryLimits) { + if (!Number.isSafeInteger(limits.maxRecords) || limits.maxRecords < 1) + throw new RangeError("maxRecords must be a positive safe integer"); + if ( + !Number.isSafeInteger(limits.maxRelationships) || + limits.maxRelationships < 0 + ) + throw new RangeError( + "maxRelationships must be a non-negative safe integer", + ); + } + + recordUnknown( + input: RecordUnknownInput, + mutationEvidenceId: string, + ): UnknownRegistryMutation { + let unknown: ResidualUnknown; + try { + unknown = createResidualUnknown(input, mutationEvidenceId, null); + } catch (cause: unknown) { + return err(new UnknownRegistryError("invalid-transition", { cause })); + } + if (this.#heads.has(unknown.unknown_id)) + return err(new UnknownRegistryError("already-exists")); + return this.#append(unknown); + } + + updateUnknown( + input: UpdateUnknownInput, + mutationEvidenceId: string, + ): UnknownRegistryMutation { + const current = this.#heads.get(input.unknown_id); + if (current === undefined) + return err(new UnknownRegistryError("not-found")); + if (current.revision !== input.expected_revision) + return err(new UnknownRegistryError("revision-conflict")); + let updated: ResidualUnknown; + try { + updated = updateResidualUnknown(current, input, mutationEvidenceId); + } catch (cause: unknown) { + return err(new UnknownRegistryError("invalid-transition", { cause })); + } + return this.#append(updated); + } + + listUnknowns( + filters: { + readonly status?: UnknownStatus; + readonly severity?: ResidualUnknown["severity"]; + readonly domain?: string; + } = {}, + ): UnknownRegistryQuery { + return ok( + [...this.#heads.values()] + .filter( + (unknown) => + (filters.status === undefined || + unknown.status === filters.status) && + (filters.severity === undefined || + unknown.severity === filters.severity) && + (filters.domain === undefined || unknown.domain === filters.domain), + ) + .sort((left, right) => left.unknown_id.localeCompare(right.unknown_id)), + ); + } + + verifyUnknownResolution(unknownId: string): UnknownRegistryVerify { + const unknown = this.#heads.get(unknownId); + if (unknown === undefined) + return err(new UnknownRegistryError("not-found")); + return ok({ + valid: unknown.status === "resolved", + truthVerified: unknown.resolution?.disposition === "verified", + unknown, + }); + } + + get(unknownId: string): ResidualUnknown | undefined { + const unknown = this.#heads.get(unknownId); + return unknown === undefined ? undefined : structuredClone(unknown); + } + + has(unknownId: string): boolean { + return this.#heads.has(unknownId); + } + + clear(): void { + this.#revisions.clear(); + this.#heads.clear(); + } + + #append(unknown: ResidualUnknown): UnknownRegistryMutation { + const pending = this.#revisions.size + 1; + if (pending > this.limits.maxRecords) + return err(new UnknownRegistryError("limit")); + if (unknown.relationships.length > this.limits.maxRelationships) + return err(new UnknownRegistryError("limit")); + try { + residualUnknownSchema.parse(unknown); + } catch (cause: unknown) { + return err(new UnknownRegistryError("integrity", { cause })); + } + this.#revisions.set( + `${unknown.unknown_id}:${String(unknown.revision)}`, + unknown, + ); + this.#heads.set(unknown.unknown_id, unknown); + return ok(unknown); + } +} diff --git a/src/cli.ts b/src/cli.ts index ba7f2ec19..58dbd055e 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -19,6 +19,8 @@ import { importReferenceSource } from "./application/ReferenceSourceImport.js"; import { registerEvidenceCommands } from "./cliEvidenceCommands.js"; import { registerProcessCommands } from "./cliProcessCommands.js"; import { registerInvestigationCommands } from "./cliInvestigationCommands.js"; +import { registerUnknownCommands } from "./cliUnknownCommands.js"; +import { registerBrowserCommands } from "./cliBrowserCommands.js"; import { AnalysisProtocolError, PermissionRequiredError, @@ -27,7 +29,8 @@ import { import { projectReferenceSourceImportError } from "./application/ReferenceSourceImportTypes.js"; import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js"; import { registerPolicyCommands } from "./cliPolicyCommands.js"; -import { registerBrowserCommands } from "./cliBrowserCommands.js"; +import { UnknownRegistry } from "./application/UnknownRegistry.js"; +import { UnknownRegistry } from "./application/UnknownRegistry.js"; /** * Build the one-shot Incur CLI without starting Hopper at import time. @@ -71,6 +74,11 @@ export const createCli = (): ReturnType => { registerArtifactCommands(cli, logger); registerInvestigationCommands(cli, logger); registerEvidenceCommands(cli, logger); + registerUnknownCommands( + cli, + logger, + new UnknownRegistry({ maxRecords: 1_000, maxRelationships: 100 }), + ); registerReferenceSourceCommand(cli, logger); registerProcessCommands(cli, logger); registerPolicyCommands(cli, logger); diff --git a/src/cliUnknownCommands.ts b/src/cliUnknownCommands.ts new file mode 100644 index 000000000..37453b071 --- /dev/null +++ b/src/cliUnknownCommands.ts @@ -0,0 +1,135 @@ +import { Cli, z } from "incur"; + +import type { UnknownRegistry } from "./application/UnknownRegistry.js"; +import type { Logger } from "./logger.js"; +import type { + RecordUnknownInput, + UpdateUnknownInput, +} from "./domain/residualUnknown.js"; + +/** Register residual-unknown registry CLI commands. */ +export const registerUnknownCommands = ( + cli: ReturnType, + _logger: Logger, + registry: UnknownRegistry, +): void => { + cli.command("unknowns", { + description: "List recorded residual unknowns with optional filters", + options: z.object({ + status: z + .enum(["open", "investigating", "blocked", "contradicted", "resolved"]) + .optional() + .describe("Filter by status"), + severity: z + .enum(["low", "medium", "high", "critical"]) + .optional() + .describe("Filter by severity"), + domain: z.string().optional().describe("Filter by domain"), + }), + run: ({ options }): ReturnType => { + const filters: { + status?: + | "open" + | "investigating" + | "blocked" + | "contradicted" + | "resolved"; + severity?: "low" | "medium" | "high" | "critical"; + domain?: string; + } = {}; + if (options.status !== undefined) filters.status = options.status; + if (options.severity !== undefined) filters.severity = options.severity; + if (options.domain !== undefined) filters.domain = options.domain; + return registry.listUnknowns(filters); + }, + }); + + cli.command("unknown-record", { + description: "Record one approved residual unknown question", + options: z.object({ + question: z.string().min(1).max(1_000).describe("The bounded question"), + severity: z + .enum(["low", "medium", "high", "critical"]) + .describe("Severity of the unknown"), + domain: z.string().min(1).max(100).describe("Domain of the unknown"), + authority: z + .enum([ + "shipped-artifact", + "controlled-replay", + "historical-reference", + "external-service", + "analyst-inference", + ]) + .describe("Required authority to resolve"), + confidence: z + .enum(["observed", "derived", "inferred"]) + .describe("Required confidence level"), + evidence: z + .string() + .min(1) + .describe("Mutation evidence ID for this record operation"), + }), + run: ({ options }) => + registry.recordUnknown( + { + question: options.question, + severity: options.severity, + domain: options.domain, + required_authority: options.authority, + required_confidence: options.confidence, + required_environment: null, + supporting_evidence_ids: [], + contradicting_evidence_ids: [], + recommended_probes: [], + relationships: [], + approved: true, + } as RecordUnknownInput, + options.evidence, + ), + }); + + cli.command("unknown-update", { + description: "Update one residual unknown with new evidence or status", + options: z.object({ + id: z.string().describe("Unknown ID (unk_…)"), + revision: z.number().int().min(1).describe("Expected current revision"), + status: z + .enum(["open", "investigating", "blocked", "contradicted", "resolved"]) + .describe("New status"), + severity: z + .enum(["low", "medium", "high", "critical"]) + .describe("New severity"), + evidence: z + .string() + .min(1) + .describe("Mutation evidence ID for this update operation"), + }), + run: ({ options }) => + registry.updateUnknown( + { + unknown_id: options.id, + expected_revision: options.revision, + approved: true, + status: options.status, + severity: options.severity, + required_authority: null, + required_confidence: "observed", + required_environment: null, + supporting_evidence_ids: [], + contradicting_evidence_ids: [], + recommended_probes: [], + relationships: [], + resolution: null, + } as unknown as UpdateUnknownInput, + options.evidence, + ), + }); + + cli.command("unknown-verify", { + description: "Verify the resolution state of one residual unknown", + options: z.object({ + id: z.string().describe("Unknown ID (unk_…)"), + }), + run: ({ options }) => registry.verifyUnknownResolution(options.id), + }); +}; diff --git a/src/logger.ts b/src/logger.ts index e90dd52e3..22c23261f 100644 --- a/src/logger.ts +++ b/src/logger.ts @@ -12,7 +12,7 @@ const logLevelSchema = z export const parseLogLevel = (value: unknown): LogLevel => logLevelSchema.parse(value); -/** Create a JSON logger on stderr so protocol and CLI result stdout stay valid. */ +/** Create a JSON logger whose stderr destination cannot corrupt structured output. */ export const createLogger = (mode: "mcp" | "cli", level: LogLevel): Logger => pino( { diff --git a/tests/unknownRegistry.test.ts b/tests/unknownRegistry.test.ts new file mode 100644 index 000000000..9c0051a98 --- /dev/null +++ b/tests/unknownRegistry.test.ts @@ -0,0 +1,226 @@ +import { describe, expect, it } from "vitest"; + +import { UnknownRegistry } from "../src/application/UnknownRegistry.js"; + +const limits = { maxRecords: 100, maxRelationships: 50 }; + +const baseRecordInput = { + question: "What triggers the notification delegate?", + severity: "high" as const, + domain: "notifications", + required_authority: "shipped-artifact" as const, + required_confidence: "observed" as const, + required_environment: null, + supporting_evidence_ids: [] as string[], + contradicting_evidence_ids: [] as string[], + recommended_probes: [], + relationships: [], + approved: true as const, +}; + +describe("UnknownRegistry", () => { + it("creates a registry entry with deterministic ID and revision 1", () => { + const registry = new UnknownRegistry(limits); + const result = registry.recordUnknown( + baseRecordInput, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ); + expect(result.ok).toBe(true); + if (!result.ok) return; + const unk = result.value; + expect(unk.unknown_id).toMatch(/^unk_[a-f0-9]{64}$/u); + expect(unk.revision).toBe(1); + expect(unk.status).toBe("open"); + expect(unk.previous_revision_digest).toBeNull(); + }); + + it("rejects duplicate creation with already-exists", () => { + const registry = new UnknownRegistry(limits); + const first = registry.recordUnknown( + baseRecordInput, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ); + expect(first.ok).toBe(true); + const second = registry.recordUnknown( + baseRecordInput, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ); + expect(second.ok).toBe(false); + if (second.ok) return; + expect(second.error.reason).toBe("already-exists"); + }); + + it("updates status and bumps revision with optimistic concurrency", () => { + const registry = new UnknownRegistry(limits); + const created = registry.recordUnknown( + baseRecordInput, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ); + if (!created.ok) throw new Error("create failed"); + const updated = registry.updateUnknown( + { + unknown_id: created.value.unknown_id, + expected_revision: 1, + approved: true, + status: "investigating", + severity: "high", + required_authority: null, + required_confidence: "observed", + required_environment: null, + supporting_evidence_ids: [], + contradicting_evidence_ids: [], + recommended_probes: [], + relationships: [], + resolution: null, + }, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ); + expect(updated.ok).toBe(true); + if (!updated.ok) return; + expect(updated.value.revision).toBe(2); + expect(updated.value.status).toBe("investigating"); + expect(updated.value.previous_revision_digest).toBe( + created.value.revision_digest, + ); + }); + + it("rejects update with wrong expected revision", () => { + const registry = new UnknownRegistry(limits); + const created = registry.recordUnknown( + baseRecordInput, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ); + if (!created.ok) throw new Error("create failed"); + const updated = registry.updateUnknown( + { + unknown_id: created.value.unknown_id, + expected_revision: 99, + approved: true, + status: "investigating", + severity: "high", + required_authority: null, + required_confidence: "observed", + required_environment: null, + supporting_evidence_ids: [], + contradicting_evidence_ids: [], + recommended_probes: [], + relationships: [], + resolution: null, + }, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ); + expect(updated.ok).toBe(false); + if (updated.ok) return; + expect(updated.error.reason).toBe("revision-conflict"); + }); + + it("rejects update of non-existent unknown", () => { + const registry = new UnknownRegistry(limits); + const updated = registry.updateUnknown( + { + unknown_id: "unk_" + "0".repeat(64), + expected_revision: 1, + approved: true, + status: "investigating", + severity: "high", + required_authority: null, + required_confidence: "observed", + required_environment: null, + supporting_evidence_ids: [], + contradicting_evidence_ids: [], + recommended_probes: [], + relationships: [], + resolution: null, + }, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ); + expect(updated.ok).toBe(false); + if (updated.ok) return; + expect(updated.error.reason).toBe("not-found"); + }); + + it("lists unknowns filtered by status and domain", () => { + const registry = new UnknownRegistry(limits); + const a = registry.recordUnknown( + { ...baseRecordInput, domain: "notifications" }, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ); + const b = registry.recordUnknown( + { ...baseRecordInput, question: "How does IPC work?", domain: "ipc" }, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ); + expect(a.ok).toBe(true); + expect(b.ok).toBe(true); + + const allOpen = registry.listUnknowns({ status: "open" }); + expect(allOpen.ok).toBe(true); + if (!allOpen.ok) return; + expect(allOpen.value).toHaveLength(2); + + const ipcOnly = registry.listUnknowns({ domain: "ipc" }); + expect(ipcOnly.ok).toBe(true); + if (!ipcOnly.ok) return; + expect(ipcOnly.value).toHaveLength(1); + expect(ipcOnly.value[0]?.domain).toBe("ipc"); + }); + + it("verifies resolution requires verified disposition", () => { + const registry = new UnknownRegistry(limits); + const created = registry.recordUnknown( + baseRecordInput, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ); + if (!created.ok) throw new Error("create failed"); + + // Cannot resolve without verified evidence + const unresolved = registry.updateUnknown( + { + unknown_id: created.value.unknown_id, + expected_revision: 1, + approved: true, + status: "resolved", + severity: "high", + required_authority: null, + required_confidence: "observed", + required_environment: null, + supporting_evidence_ids: [], + contradicting_evidence_ids: [], + recommended_probes: [], + relationships: [], + resolution: { + disposition: "verified", + rationale: "Test resolved", + evidence_ids: [], + }, + }, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ); + // The domain layer should reject resolving with verified disposition + // and no evidence ids + expect(unresolved.ok).toBe(false); + }); + + it("enforces record limits", () => { + const smallLimits = { maxRecords: 2, maxRelationships: 50 }; + const registry = new UnknownRegistry(smallLimits); + expect( + registry.recordUnknown( + baseRecordInput, + "ev_a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1", + ).ok, + ).toBe(true); + expect( + registry.recordUnknown( + { ...baseRecordInput, question: "Second?" }, + "ev_b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2", + ).ok, + ).toBe(true); + const third = registry.recordUnknown( + { ...baseRecordInput, question: "Third?" }, + "ev_c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3", + ); + expect(third.ok).toBe(false); + if (third.ok) return; + expect(third.error.reason).toBe("limit"); + }); +});