Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(reconstruction)!: summarize obligation ledgers by cited Evidence authority (#5875)

Kaoru082225e1a24a3ed3
diff --git a/docs/reconstruction-obligation-ledgers.md b/docs/reconstruction-obligation-ledgers.md
index 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 a
runtime or process claim. Marking a claim `blocked` or `out-of-scope` records the
disposition 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 and
dependency graphs, Evidence links, and limitations.
diff --git a/src/application/ReconstructionObligationLedger.fixture.ts b/src/application/ReconstructionObligationLedger.fixture.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 = z
required_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.ts
index 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.ts
index 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)),