[PR #4589] feat(evidence): cluster artifacts from retained Evidence references and summaries #6325

Open
opened 2026-10-31 01:13:35 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4589
Author: @nikhilsaxena04
Created: 10/16/2026
Status: 🔄 Open

Base: main ← Head: feat/4135-cluster-artifacts-retained-evidence


📝 Commits (9)

  • c124e52 feat(evidence): cluster inspected artifacts into families by root digest
  • 31260ff fix(evidence): keep cluster member identity and byte claims exact
  • 8422c26 fix(evidence): count scope exclusions on the scope axis only
  • 5eb4183 fix(evidence): bound the cluster member index and make its rows exact
  • 1b1a5d6 fix(server): measure the clustering response before delivering it
  • 9f96472 fix(evidence): keep clustering coverage, identity, and provenance exact
  • aaf1317 fix(evidence): count clustering omissions and withhold the index without reparsing
  • d681e24 fix(evidence): remove the unused clustering input type alias
  • ba21bd3 feat(evidence): cluster artifacts from retained Evidence references and summaries

📊 Changes

22 files changed (+3216 additions, -4 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/references/evidence-workflows.md (+9 -0)
📝 docs/cli.md (+13 -0)
📝 docs/mcp-contracts.md (+58 -0)
➕ src/application/artifacts/ArtifactFamilyClusteringCommand.ts (+66 -0)
➕ src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts (+212 -0)
➕ src/application/artifacts/ArtifactFamilyClusteringEvidence.ts (+102 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/cliEvidenceCommands.ts (+46 -0)
📝 src/contracts/sessionToolContracts.ts (+6 -0)
📝 src/contracts/toolContractExamples.ts (+8 -0)
📝 src/contracts/toolEffects.ts (+1 -0)
📝 src/contracts/toolOutputSchemaGroups.ts (+2 -0)
➕ src/domain/artifactFamilyClustering.test.ts (+753 -0)
➕ src/domain/artifactFamilyClustering.ts (+584 -0)
➕ src/domain/artifactFamilyClusteringIndex.test.ts (+137 -0)
➕ src/domain/artifactFamilyClusteringIndex.ts (+196 -0)
📝 src/domain/artifactInventoryEvidence.test.ts (+14 -1)
📝 src/domain/artifactInventoryEvidence.ts (+12 -3)
➕ src/server/registerArtifactFamilyClusteringTool.ts (+183 -0)
📝 src/server/registerSessionTools.ts (+7 -0)

...and 2 more files

📄 Description

Summary

Allow cluster_artifacts to accept members by retained Evidence ID or inspect_analysis_view summary, resolving the complete parent inventory retained in the session before clustering. Fixes #4135. Depends on #4133.

Problem and expected behavior

cluster_artifacts and rea cluster-artifacts previously accepted members only as complete inline inspect_artifact inventory Evidence. For callers or AI agents with 5–10 large archives, resending entire inventories over the MCP transport was heavy, redundant, and risked transport buffer exhaustion. Furthermore, an agent holding only an inspect_analysis_view summary view (to conserve context window) could not cluster at all, despite the complete parent inventory remaining retained in the session ledger.

compare_artifacts already addresses this by accepting either nested inventory Evidence or its summary, resolving the exact retained parent before comparing. This PR aligns cluster_artifacts with that established pattern.

Change and scope

  • Updated artifactFamilyMemberSchema in src/domain/artifactFamilyClustering.ts to accept:
    • { label: string, evidence: Evidence | string }
    • { label: string, evidence_id: string }
  • Added resolveArtifactFamilyClusteringEvidence in src/application/artifacts/ArtifactFamilyClusteringEvidence.ts to resolve retained Evidence references via resolveEvidenceInput and validate that summary views reproject deterministically from their retained parent via inspectAnalysisViewValidated.
  • Enforced operation validation: only artifact inventory Evidence (inspect_artifact or inventory_artifact) is accepted; non-artifact Evidence returns typed AnalysisInputError.
  • Missing or identity-mismatched references return typed EvidenceReferenceError, and forged or tampered summary facts return typed EvidenceIntegrityError.
  • Updated registerArtifactFamilyClusteringTool.ts to resolve member references before clustering.
  • Updated session tool contracts in src/contracts/sessionToolContracts.ts and docs/mcp-contracts.md.
  • Added unit tests in src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts (9 tests) and boundary tests in tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts.

Follow the contribution scope.

Contract and boundary impact

  • Semantic owner and earliest changed stage: cluster_artifacts input admission and resolution in ArtifactFamilyClusteringEvidence.ts and registerArtifactFamilyClusteringTool.ts.
  • Contribution scope fit and linked maintainer decision: Resolves #4135; extends clustering input flexibility within existing session Evidence patterns.
  • CLI and MCP/tool-catalog contract: cluster_artifacts input schema now accepts evidence_id and string evidence IDs in addition to full inline Evidence. Standalone CLI usage continues to accept inline Evidence without breaking changes.
  • Provider, bridge, target-format, or platform compatibility: Platform-independent; session-only capability for retained Evidence.
  • Evidence, artifact, provenance, or reconstruction contract: Retains resolved parent Evidence roster in tool parameters. Provenance and integrity of inventories are verified.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): Not applicable; operates entirely on retained session Evidence.
  • Generated metadata, package, or installation impact: None.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated:
    • src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts (9 unit tests)
    • tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts (added mixed roster boundary test)
  • Base reproduction or other evidence: Verified against real MCP session with retained Evidence and summary view projection.
  • User-visible CLI/MCP output: Retained Evidence IDs and summary views cluster identically to inline inventories, returning partition families and shared member indices.
  • Remaining proof gaps: None.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npx vitest run src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts — 9/9 passed.
  • npx vitest run tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts — 5/5 passed.
  • npm run check:fast — 2/2 tasks passed (typecheck and lint clean).
  • npx oxfmt --check src/application/artifacts/ArtifactFamilyClusteringEvidence.ts src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts src/domain/artifactFamilyClustering.ts src/server/registerArtifactFamilyClusteringTool.ts src/contracts/sessionToolContracts.ts docs/mcp-contracts.md tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts — All matched files use the correct format.

Compatibility, safety, and release

  • Breaking changes or migration steps: None. Fully backwards-compatible with existing inline Evidence members.
  • Real Hopper/Ghidra, browser, or OS coverage: Cross-platform.
  • Package or release metadata impact: None.
  • Security, privacy, process, or containment review: Strict reprojection integrity check prevents summary forgery attacks.

Author readiness

Human owner: @nikhilsaxena04

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4589 **Author:** [@nikhilsaxena04](https://github.com/nikhilsaxena04) **Created:** 10/16/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/4135-cluster-artifacts-retained-evidence` --- ### 📝 Commits (9) - [`c124e52`](https://github.com/morluto/rea/commit/c124e52e20ab5842f4c3141911f6eaa75ccb0202) feat(evidence): cluster inspected artifacts into families by root digest - [`31260ff`](https://github.com/morluto/rea/commit/31260ffa88a165fd9d56a92e4be90b232047c11d) fix(evidence): keep cluster member identity and byte claims exact - [`8422c26`](https://github.com/morluto/rea/commit/8422c2660c94459371f79c030540ceb752560365) fix(evidence): count scope exclusions on the scope axis only - [`5eb4183`](https://github.com/morluto/rea/commit/5eb4183dd12600d68f017e197f0e3c6ec63bb81c) fix(evidence): bound the cluster member index and make its rows exact - [`1b1a5d6`](https://github.com/morluto/rea/commit/1b1a5d64064dad0962436eaa314c4a72b9b275d5) fix(server): measure the clustering response before delivering it - [`9f96472`](https://github.com/morluto/rea/commit/9f96472d9c3d0aacc32e09c48ec346747dc1b1d8) fix(evidence): keep clustering coverage, identity, and provenance exact - [`aaf1317`](https://github.com/morluto/rea/commit/aaf13170ab311c3cfbd1de80154d4099ec5c8229) fix(evidence): count clustering omissions and withhold the index without reparsing - [`d681e24`](https://github.com/morluto/rea/commit/d681e2459e9bc5d5168c418814eb88f7647939fa) fix(evidence): remove the unused clustering input type alias - [`ba21bd3`](https://github.com/morluto/rea/commit/ba21bd3ac12eb0870f85acd88972c0afb3e40dd4) feat(evidence): cluster artifacts from retained Evidence references and summaries ### 📊 Changes **22 files changed** (+3216 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/references/evidence-workflows.md` (+9 -0) 📝 `docs/cli.md` (+13 -0) 📝 `docs/mcp-contracts.md` (+58 -0) ➕ `src/application/artifacts/ArtifactFamilyClusteringCommand.ts` (+66 -0) ➕ `src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts` (+212 -0) ➕ `src/application/artifacts/ArtifactFamilyClusteringEvidence.ts` (+102 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/cliEvidenceCommands.ts` (+46 -0) 📝 `src/contracts/sessionToolContracts.ts` (+6 -0) 📝 `src/contracts/toolContractExamples.ts` (+8 -0) 📝 `src/contracts/toolEffects.ts` (+1 -0) 📝 `src/contracts/toolOutputSchemaGroups.ts` (+2 -0) ➕ `src/domain/artifactFamilyClustering.test.ts` (+753 -0) ➕ `src/domain/artifactFamilyClustering.ts` (+584 -0) ➕ `src/domain/artifactFamilyClusteringIndex.test.ts` (+137 -0) ➕ `src/domain/artifactFamilyClusteringIndex.ts` (+196 -0) 📝 `src/domain/artifactInventoryEvidence.test.ts` (+14 -1) 📝 `src/domain/artifactInventoryEvidence.ts` (+12 -3) ➕ `src/server/registerArtifactFamilyClusteringTool.ts` (+183 -0) 📝 `src/server/registerSessionTools.ts` (+7 -0) _...and 2 more files_ </details> ### 📄 Description ## Summary Allow `cluster_artifacts` to accept members by retained Evidence ID or `inspect_analysis_view` summary, resolving the complete parent inventory retained in the session before clustering. Fixes #4135. Depends on #4133. ## Problem and expected behavior `cluster_artifacts` and `rea cluster-artifacts` previously accepted members only as complete inline `inspect_artifact` inventory Evidence. For callers or AI agents with 5–10 large archives, resending entire inventories over the MCP transport was heavy, redundant, and risked transport buffer exhaustion. Furthermore, an agent holding only an `inspect_analysis_view` summary view (to conserve context window) could not cluster at all, despite the complete parent inventory remaining retained in the session ledger. `compare_artifacts` already addresses this by accepting either nested inventory Evidence or its summary, resolving the exact retained parent before comparing. This PR aligns `cluster_artifacts` with that established pattern. ## Change and scope - Updated `artifactFamilyMemberSchema` in `src/domain/artifactFamilyClustering.ts` to accept: - `{ label: string, evidence: Evidence | string }` - `{ label: string, evidence_id: string }` - Added `resolveArtifactFamilyClusteringEvidence` in `src/application/artifacts/ArtifactFamilyClusteringEvidence.ts` to resolve retained Evidence references via `resolveEvidenceInput` and validate that summary views reproject deterministically from their retained parent via `inspectAnalysisViewValidated`. - Enforced operation validation: only artifact inventory Evidence (`inspect_artifact` or `inventory_artifact`) is accepted; non-artifact Evidence returns typed `AnalysisInputError`. - Missing or identity-mismatched references return typed `EvidenceReferenceError`, and forged or tampered summary facts return typed `EvidenceIntegrityError`. - Updated `registerArtifactFamilyClusteringTool.ts` to resolve member references before clustering. - Updated session tool contracts in `src/contracts/sessionToolContracts.ts` and `docs/mcp-contracts.md`. - Added unit tests in `src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts` (9 tests) and boundary tests in `tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts`. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). ## Contract and boundary impact - Semantic owner and earliest changed stage: `cluster_artifacts` input admission and resolution in `ArtifactFamilyClusteringEvidence.ts` and `registerArtifactFamilyClusteringTool.ts`. - Contribution scope fit and linked maintainer decision: Resolves #4135; extends clustering input flexibility within existing session Evidence patterns. - CLI and MCP/tool-catalog contract: `cluster_artifacts` input schema now accepts `evidence_id` and string `evidence` IDs in addition to full inline Evidence. Standalone CLI usage continues to accept inline Evidence without breaking changes. - Provider, bridge, target-format, or platform compatibility: Platform-independent; session-only capability for retained Evidence. - Evidence, artifact, provenance, or reconstruction contract: Retains resolved parent Evidence roster in tool parameters. Provenance and integrity of inventories are verified. - Target selection, authority, upstream behavior, and cleanup details (if applicable): Not applicable; operates entirely on retained session Evidence. - Generated metadata, package, or installation impact: None. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: - `src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts` (9 unit tests) - `tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts` (added mixed roster boundary test) - Base reproduction or other evidence: Verified against real MCP session with retained Evidence and summary view projection. - User-visible CLI/MCP output: Retained Evidence IDs and summary views cluster identically to inline inventories, returning partition families and shared member indices. - Remaining proof gaps: None. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npx vitest run src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts` — 9/9 passed. - `npx vitest run tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts` — 5/5 passed. - `npm run check:fast` — 2/2 tasks passed (typecheck and lint clean). - `npx oxfmt --check src/application/artifacts/ArtifactFamilyClusteringEvidence.ts src/application/artifacts/ArtifactFamilyClusteringEvidence.test.ts src/domain/artifactFamilyClustering.ts src/server/registerArtifactFamilyClusteringTool.ts src/contracts/sessionToolContracts.ts docs/mcp-contracts.md tests/boundary/mcp/artifactFamilyClusteringMcp.test.ts` — All matched files use the correct format. ## Compatibility, safety, and release - Breaking changes or migration steps: None. Fully backwards-compatible with existing inline Evidence members. - Real Hopper/Ghidra, browser, or OS coverage: Cross-platform. - Package or release metadata impact: None. - Security, privacy, process, or containment review: Strict reprojection integrity check prevents summary forgery attacks. ## Author readiness Human owner: @nikhilsaxena04 - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6325
No description provided.