Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(reconstruction)!: summarize obligation ledgers by cited Evidence authority (#5875)
Kaoru082225e1a24a3ed3
diff --git a/docs/reconstruction-obligation-ledgers.md b/docs/reconstruction-obligation-ledgers.mdindex e3e4b6f0d..6b930c534 100644--- a/docs/reconstruction-obligation-ledgers.md+++ b/docs/reconstruction-obligation-ledgers.md@@ -320,6 +320,13 @@ close a `packaged-process` obligation. A static-only source cannot close aruntime or process claim. Marking a claim `blocked` or `out-of-scope` records thedisposition but does not silently count it as verified.+The `summary` counts obligations. `by_status`, `by_application_layer`, and+`by_source_state` place each obligation in exactly one bucket.+`by_evidence_authority` groups obligations by the Evidence `authority` of their+`authority_references`: an obligation counts once under each distinct authority+it cites, so those counts can exceed `total`. A reference's own `state` and the+obligation's `source_state` do not affect its authority bucket.+The tool returns every obligation inline. Its `ledger_id` and `closure_digest`identify the complete result, including summaries, reports, ownership anddependency graphs, Evidence links, and limitations.diff --git a/src/application/ReconstructionObligationLedger.fixture.ts b/src/application/ReconstructionObligationLedger.fixture.tsindex ba1578281..ae535025f 100644--- a/src/application/ReconstructionObligationLedger.fixture.ts+++ b/src/application/ReconstructionObligationLedger.fixture.ts@@ -149,3 +149,63 @@ export const reviewedObligation = (disposition: "active",review_evidence_ids: [evidenceId],});++const authorityEvidence = (+ label: string,+ authority: "shipped-artifact" | "controlled-replay",+) =>+ createEvidence(+ undefined,+ { id: "fixture", name: "Fixture", version: "1" },+ {+ operation: "observe",+ parameters: { label },+ result: { present: true },+ confidence: "observed",+ authority,+ },+ );++/**+ * Request with one single-reference shipped-artifact obligation and one+ * obligation citing two shipped-artifact records and one controlled-replay+ * record. Shipped-artifact review references have candidate state while both+ * reviewed obligations have reviewed source state.+ */+export const mixedAuthorityRequest =+ (): ReconstructionObligationLedgerInput => {+ const shipped = authorityEvidence("shipped", "shipped-artifact");+ const otherShipped = authorityEvidence("other-shipped", "shipped-artifact");+ const replay = authorityEvidence("replay", "controlled-replay");+ return request([shipped, otherShipped, replay], {+ reviewed_obligations: [+ reviewedObligation("review.shipped", shipped.evidence_id),+ {+ ...reviewedObligation("review.mixed", shipped.evidence_id),+ review_evidence_ids: [+ shipped.evidence_id,+ replay.evidence_id,+ otherShipped.evidence_id,+ ],+ },+ ],+ });+ };++/** Summary buckets expected for {@link mixedAuthorityRequest}. */+export const MIXED_AUTHORITY_SUMMARY = {+ total: 2,+ by_evidence_authority: [+ { key: "shipped-artifact", count: 2 },+ { key: "controlled-replay", count: 1 },+ { key: "historical-reference", count: 0 },+ { key: "external-service", count: 0 },+ { key: "analyst-inference", count: 0 },+ ],+ by_source_state: [+ { key: "candidate", count: 0 },+ { key: "observed", count: 0 },+ { key: "reviewed", count: 2 },+ { key: "unknown", count: 0 },+ ],+} as const;diff --git a/src/contracts/reconstructionReadinessExample.ts b/src/contracts/reconstructionReadinessExample.tsindex 124ce2a05..35e286007 100644--- a/src/contracts/reconstructionReadinessExample.ts+++ b/src/contracts/reconstructionReadinessExample.ts@@ -4,7 +4,10 @@ import {READINESS_REQUIRED_CHECKS,READINESS_STAGE_IDS,} from "../domain/reconstructionReadinessJourneyFindings.js";-import { reconstructionObligationLedgerClosureDigest } from "../domain/reconstructionObligationLedgerIntegrity.js";+import {+ reconstructionObligationLedgerClosureDigest,+ summarizeReconstructionObligations,+} from "../domain/reconstructionObligationLedgerIntegrity.js";import type { ReconstructionObligationLedger } from "../domain/reconstructionObligationLedgerSchemas.js";import type { ReconstructionReadinessInput } from "../domain/reconstructionReadinessSchemas.js";@@ -43,60 +46,17 @@ const FIXTURES = ["incomplete-reconstruction","broken-runtime",] as const;-const STATUSES = [- "unowned",- "characterized",- "implemented",- "verified",- "contradicted",- "blocked",- "out-of-scope",- "unknown",-] as const;-const LAYERS = [- "cli",- "protocol",- "electron",- "persistence",- "process",- "runtime",- "packaging",- "native-abi",- "application",- "other",-] as const;-const EVIDENCE_STATES = [- "candidate",- "observed",- "reviewed",- "unknown",-] as const;const READINESS_OBLIGATION_LEDGER = (() => {- const ledger: Omit<ReconstructionObligationLedger, "closure_digest"> = {+ const facts: Omit<+ ReconstructionObligationLedger,+ "closure_digest" | "summary"+ > = {schema: "ReconstructionObligationLedger",ledger_id: `rol_${HASH}`,status: "ready",coverage: {status: "complete",},- summary: {- total: 1,- required: 1,- verified: 1,- required_open: 0,- by_status: STATUSES.map((key) => ({- key,- count: key === "verified" ? 1 : 0,- })),- by_application_layer: LAYERS.map((key) => ({- key,- count: key === "process" ? 1 : 0,- })),- by_evidence_authority: EVIDENCE_STATES.map((key) => ({- key,- count: key === "observed" ? 1 : 0,- })),- },reports: {missing_owner_obligation_ids: [],missing_verifier_obligation_ids: [],@@ -189,6 +149,10 @@ const READINESS_OBLIGATION_LEDGER = (() => {evidence_links: [EVIDENCE_ID],limitations: [],};+ const ledger = {+ ...facts,+ summary: summarizeReconstructionObligations(facts.obligations),+ };return {...ledger,closure_digest: reconstructionObligationLedgerClosureDigest(ledger),diff --git a/src/domain/evidence.ts b/src/domain/evidence.tsindex cf32dee6c..ad78f74f6 100644--- a/src/domain/evidence.ts+++ b/src/domain/evidence.ts@@ -112,7 +112,8 @@ export const evidenceLocationSchema = z.discriminatedUnion("kind", [}),]);-const evidenceAuthoritySchema = z.enum([+/** Source authority vocabulary owned by Evidence and reused by its consumers. */+export const evidenceAuthoritySchema = z.enum(["shipped-artifact","controlled-replay","historical-reference",diff --git a/src/domain/reconstructionObligationLedgerIntegrity.ts b/src/domain/reconstructionObligationLedgerIntegrity.tsindex c0f9dd099..0ca3d8843 100644--- a/src/domain/reconstructionObligationLedgerIntegrity.ts+++ b/src/domain/reconstructionObligationLedgerIntegrity.ts@@ -1,5 +1,6 @@import { digestCanonicalValue } from "./canonicalDigest.js";import { canonicalJson } from "./comparisonSemantics.js";+import { evidenceAuthoritySchema } from "./evidence.js";import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";import type {@@ -48,6 +49,12 @@ export const summarizeReconstructionObligations = (({ application_layer }) => application_layer,),by_evidence_authority: countBy(+ obligations,+ evidenceAuthoritySchema.options,+ ({ authority_references: references }) =>+ references.map(({ authority }) => authority),+ ),+ by_source_state: countBy(obligations,["candidate", "observed", "reviewed", "unknown"],({ source_state }) => source_state,@@ -201,12 +208,19 @@ export const reconstructionObligationLedgerClosureDigest = (ledger: {"Reconstruction obligation ledger",);+/** Count items per key; an item counts once under each distinct key it has. */const countBy = <Value extends string, Item>(items: readonly Item[],values: readonly Value[],- valueFor: (item: Item) => Value,-): { key: Value; count: number }[] =>- values.map((value) => ({- key: value,- count: items.filter((item) => valueFor(item) === value).length,- }));+ valuesFor: (item: Item) => Value | readonly Value[],+): { key: Value; count: number }[] => {+ const counts = new Map<Value, number>();+ for (const item of items) {+ const itemValues = valuesFor(item);+ for (const value of new Set(+ typeof itemValues === "string" ? [itemValues] : itemValues,+ ))+ counts.set(value, (counts.get(value) ?? 0) + 1);+ }+ return values.map((value) => ({ key: value, count: counts.get(value) ?? 0 }));+};diff --git a/src/domain/reconstructionObligationLedgerSchemas.ts b/src/domain/reconstructionObligationLedgerSchemas.tsindex 6d3403c8d..60ae22646 100644--- a/src/domain/reconstructionObligationLedgerSchemas.ts+++ b/src/domain/reconstructionObligationLedgerSchemas.ts@@ -2,6 +2,7 @@ import { z } from "zod";import { STABLE_IDENTIFIER_PATTERN } from "./stringPatterns.js";+import { evidenceAuthoritySchema } from "./evidence.js";import { evidenceBundleSchema } from "./evidenceBundle.js";import { digestSchema } from "./../domain/digests.js";import { prefixedDigestSchema } from "./../domain/digests.js";@@ -91,6 +92,13 @@ export const obligationOriginalAuthoritySchema = z.enum(["external",]);+const obligationEvidenceStateSchema = z.enum([+ "candidate",+ "observed",+ "reviewed",+ "unknown",+]);+const obligationTargetSchema = z.strictObject({artifact_sha256: digestSchema.nullable(),application_node_id: z@@ -106,14 +114,8 @@ const obligationTargetSchema = z.strictObject({const authorityReferenceSchema = z.strictObject({evidence_id: evidenceIdSchema,- authority: z.enum([- "shipped-artifact",- "controlled-replay",- "historical-reference",- "external-service",- "analyst-inference",- ]),- state: z.enum(["candidate", "observed", "reviewed", "unknown"]),+ authority: evidenceAuthoritySchema,+ state: obligationEvidenceStateSchema,location: textSchema,});@@ -235,7 +237,7 @@ export const reconstructionObligationSchema = z.strictObject({family: textSchema,target: obligationTargetSchema,authority_references: z.array(authorityReferenceSchema).min(1),- source_state: z.enum(["candidate", "observed", "reviewed", "unknown"]),+ source_state: obligationEvidenceStateSchema,observed_cases: z.array(observedCaseSchema),required: z.boolean(),required_case_kinds: z.array(obligationCaseKindSchema).min(1),@@ -295,7 +297,8 @@ const obligationSummariesMatch = (countEntriesMatch(actual.by_evidence_authority,expected.by_evidence_authority,- );+ ) &&+ countEntriesMatch(actual.by_source_state, expected.by_source_state);export const reconstructionObligationLedgerSchema = z.strictObject({@@ -313,8 +316,11 @@ export const reconstructionObligationLedgerSchema = zrequired_open: z.number().int().min(0),by_status: countBySchema(obligationStatusSchema),by_application_layer: countBySchema(obligationLayerSchema),- by_evidence_authority: countBySchema(- z.enum(["candidate", "observed", "reviewed", "unknown"]),+ by_evidence_authority: countBySchema(evidenceAuthoritySchema).describe(+ "Obligations per Evidence authority. An obligation counts once under each distinct authority among its authority_references, so counts can sum above total.",+ ),+ by_source_state: countBySchema(obligationEvidenceStateSchema).describe(+ "Obligations per source_state; each obligation counts once.",),}),reports: z.strictObject({diff --git a/tests/boundary/cli/reconstructionObligationLedgerCli.test.ts b/tests/boundary/cli/reconstructionObligationLedgerCli.test.tsindex 91b101364..532707c59 100644--- a/tests/boundary/cli/reconstructionObligationLedgerCli.test.ts+++ b/tests/boundary/cli/reconstructionObligationLedgerCli.test.ts@@ -5,6 +5,10 @@ import { describe, expect, it } from "vitest";import { createEvidence } from "../../../src/domain/evidence.js";import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";+import {+ MIXED_AUTHORITY_SUMMARY,+ mixedAuthorityRequest,+} from "../../../src/application/ReconstructionObligationLedger.fixture.js";const execute = promisify(execFile);@@ -116,4 +120,44 @@ describe("reconstruction obligation ledger CLI parity", () => {},});}, 20_000);++ it("summarizes obligations by their cited Evidence authorities", async () => {+ const { stdout } = await execute(+ process.execPath,+ [+ "scripts/rea.mjs",+ "build-reconstruction-obligation-ledger",+ JSON.stringify(mixedAuthorityRequest()),+ "--json",+ ],+ { cwd: process.cwd(), env: process.env, maxBuffer: 16 * 1_024 * 1_024 },+ );+ const ledger = JSON.parse(stdout).normalized_result;+ expect(ledger.summary).toMatchObject(MIXED_AUTHORITY_SUMMARY);+ expect(+ ledger.obligations.map(+ (obligation: {+ readonly obligation_id: string;+ readonly authority_references: readonly {+ readonly authority: string;+ readonly state: string;+ }[];+ }) => [+ obligation.obligation_id,+ obligation.authority_references.map(+ ({ authority, state }) => `${authority}/${state}`,+ ),+ ],+ ),+ ).toEqual([+ [+ "review.mixed",+ expect.arrayContaining([+ "shipped-artifact/candidate",+ "controlled-replay/reviewed",+ ]),+ ],+ ["review.shipped", ["shipped-artifact/candidate"]],+ ]);+ }, 20_000);});diff --git a/tests/boundary/mcp/reconstructionObligationLedgerMcp.test.ts b/tests/boundary/mcp/reconstructionObligationLedgerMcp.test.tsindex c027654ce..dc9795f6e 100644--- a/tests/boundary/mcp/reconstructionObligationLedgerMcp.test.ts+++ b/tests/boundary/mcp/reconstructionObligationLedgerMcp.test.ts@@ -7,7 +7,11 @@ import { parseMcpToolError } from "../../fixtures/mcpToolError.js";import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";import { createEvidence } from "../../../src/domain/evidence.js";import { createServer } from "../../../src/server/createServer.js";-import { reviewedObligation } from "../../../src/application/ReconstructionObligationLedger.fixture.js";+import {+ MIXED_AUTHORITY_SUMMARY,+ mixedAuthorityRequest,+ reviewedObligation,+} from "../../../src/application/ReconstructionObligationLedger.fixture.js";import { observed } from "../../fixtures/analysisExecution.js";type LedgerRequest = (@@ -155,6 +159,20 @@ describe("reconstruction obligation ledger MCP parity", () => {});});+ it("summarizes obligations by their cited Evidence authorities", async () => {+ const input = mixedAuthorityRequest();+ await withLedgerClient(async (request) => {+ const result = await request(+ input.evidence_bundle,+ input.reviewed_obligations,+ );+ expect(result.isError).not.toBe(true);+ expect(result.structuredContent).toMatchObject({+ normalized_result: { summary: MIXED_AUTHORITY_SUMMARY },+ });+ });+ });+it("returns the complete Evidence-backed ledger inline", async () => {const session = createTestBinarySession(() => ({execute: () => Promise.resolve(observed(null)),