[PR #920] [MERGED] perf(cli): defer unused catalog work during command startup #2346

New issue

Closed

opened 2026-10-16 21:17:37 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:17:37 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/920
Author: @morluto
Created: 10/7/2026
Status: ✅ Merged
Merged: 10/7/2026
Merged by: @morluto

Base: main ← Head: codex/cli-catalog-startup

📝 Commits (3)

e9bfd0d perf(cli): defer catalog digests and use canonical cache scope
7b271ec Merge remote-tracking branch 'origin/main' into codex/cli-catalog-startup
df2cf0e Merge remote-tracking branch 'origin/main' into codex/cli-catalog-startup

📊 Changes

4 files changed (+120 additions, -43 deletions)

View changed files

📝 src/application/binary/AnalysisSnapshotCache.test.ts (+55 -1)
📝 src/application/binary/AnalysisSnapshotCache.ts (+7 -9)
📝 src/catalogIdentity.ts (+47 -33)
📝 tests/boundary/mcp/serverIdentity.test.ts (+11 -0)

📄 Description

Summary

Reduce CLI startup work for commands that do not request catalog schema digests. This is a profiling finding from the whole-codebase audit; no separate issue is linked.

Problem and expected behavior

rea --version and rea --help eagerly converted 131 tool input/output schemas to JSON Schema and computed catalog hashes during module import. The binary snapshot cache also loaded the 7.3 MB compiled generated catalog solely to identify official tool names. These commands should retain their complete output without performing unused schema projection and hashing.

Change and scope

Compute catalog digests synchronously on first access and memoize successful computation. The enumerable digests getter preserves the public identity fields through JSON serialization and detached clones. Counts and tool metadata still come from canonical contracts. Derive snapshot document requirements directly from OFFICIAL_TOOL_CONTRACTS, retaining the existing document-state exclusions and cursor rules.

Contract and boundary impact

Semantic owner and earliest changed stage: catalog identity initialization and binary snapshot operation classification.
CLI and MCP/tool-catalog contract: identical command output, catalog fields, schemas, ordering, counts, and hashes.
Provider, bridge, target-format, or platform compatibility: no provider protocol changes.
Evidence, artifact, provenance, or reconstruction contract: unchanged.
Process execution, authorization, cleanup, or containment impact: unchanged.
Generated metadata, package, or installation impact: generated documents and catalog remain unchanged; snapshot cache no longer imports generated catalog at runtime.

Evidence and regression coverage

Executed on macOS arm64, Node 24.18.0, against main f0a68dce. Five alternating baseline/candidate fresh Node processes per command, after one warmup per executable with filesystem cache warm. Timing includes child startup and captured output; output hashing is outside the timed interval.

Command	Baseline median	Candidate median
`--version`	528.1 ms	405.8 ms
`--help`	509.8 ms	398.5 ms

Every sample produced identical stdout/stderr hashes. Full compiled catalog identity serializes byte-for-byte like the baseline, and its detached clone matches. CPU profiling identified eager JSON Schema conversion, identity hashing, generated-catalog evaluation, and associated GC on the original version-command path.

Regression coverage checks identity serialization/cloning and explicit document/cursor cache requirements. Existing production stdio MCP, doctor, server identity, CLI output, dispatch, inventory, and snapshot boundary tests pass. This measures metadata-command startup on this host, not provider analysis throughput. First digest access still performs the required complete schema work.

Validation performed

npm run build:cached — passed.
npm run check:fast — passed.
npm run docs:check — passed.
npm run test:focused -- src/application/binary/AnalysisSnapshotCache.test.ts tests/boundary/filesystem/analysisSnapshot.test.ts tests/boundary/mcp/serverIdentity.test.ts tests/boundary/mcp/mcpDoctor.test.ts tests/boundary/cli/dispatcher.test.ts tests/boundary/cli/cliToolCoverage.test.ts tests/boundary/cli/cliOutput.test.ts tests/acceptance/applications/runtime.test.ts — eight suites, 29 passed, one platform-specific skip.
Independent Standards and Spec reviews — no findings.

Compatibility, safety, and release

Breaking changes or migrations: none.
Real Hopper/Ghidra/browser coverage: no new provider claim; provider verification was not repeated for this initialization-only change.
Package or release metadata impact: none.
Security, privacy, process, or containment changes: none.

Review checklist

One focused outcome with a Conventional Commit title.
Reason for no separate issue stated above.
Observable output and meaningful snapshot boundary rules verified.
Generated documents checked; unchanged contracts need no regeneration.
CLI output compared exactly and production MCP identity checked.
Final diff checked for unrelated changes 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/920 **Author:** [@morluto](https://github.com/morluto) **Created:** 10/7/2026 **Status:** ✅ Merged **Merged:** 10/7/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/cli-catalog-startup` --- ### 📝 Commits (3) - [`e9bfd0d`](https://github.com/morluto/rea/commit/e9bfd0dc1bd0108408f9ed59092ffa17d54bc217) perf(cli): defer catalog digests and use canonical cache scope - [`7b271ec`](https://github.com/morluto/rea/commit/7b271eca30e8804b11d56addff3a5868c7289f39) Merge remote-tracking branch 'origin/main' into codex/cli-catalog-startup - [`df2cf0e`](https://github.com/morluto/rea/commit/df2cf0ef3658756dba57fd493c54827ce6d66f1a) Merge remote-tracking branch 'origin/main' into codex/cli-catalog-startup ### 📊 Changes **4 files changed** (+120 additions, -43 deletions) <details> <summary>View changed files</summary> 📝 `src/application/binary/AnalysisSnapshotCache.test.ts` (+55 -1) 📝 `src/application/binary/AnalysisSnapshotCache.ts` (+7 -9) 📝 `src/catalogIdentity.ts` (+47 -33) 📝 `tests/boundary/mcp/serverIdentity.test.ts` (+11 -0) </details> ### 📄 Description ## Summary Reduce CLI startup work for commands that do not request catalog schema digests. This is a profiling finding from the whole-codebase audit; no separate issue is linked. ## Problem and expected behavior `rea --version` and `rea --help` eagerly converted 131 tool input/output schemas to JSON Schema and computed catalog hashes during module import. The binary snapshot cache also loaded the 7.3 MB compiled generated catalog solely to identify official tool names. These commands should retain their complete output without performing unused schema projection and hashing. ## Change and scope Compute catalog digests synchronously on first access and memoize successful computation. The enumerable `digests` getter preserves the public identity fields through JSON serialization and detached clones. Counts and tool metadata still come from canonical contracts. Derive snapshot document requirements directly from `OFFICIAL_TOOL_CONTRACTS`, retaining the existing document-state exclusions and cursor rules. ## Contract and boundary impact - Semantic owner and earliest changed stage: catalog identity initialization and binary snapshot operation classification. - CLI and MCP/tool-catalog contract: identical command output, catalog fields, schemas, ordering, counts, and hashes. - Provider, bridge, target-format, or platform compatibility: no provider protocol changes. - Evidence, artifact, provenance, or reconstruction contract: unchanged. - Process execution, authorization, cleanup, or containment impact: unchanged. - Generated metadata, package, or installation impact: generated documents and catalog remain unchanged; snapshot cache no longer imports generated catalog at runtime. ## Evidence and regression coverage Executed on macOS arm64, Node 24.18.0, against main `f0a68dce`. Five alternating baseline/candidate fresh Node processes per command, after one warmup per executable with filesystem cache warm. Timing includes child startup and captured output; output hashing is outside the timed interval. | Command | Baseline median | Candidate median | | --- | ---: | ---: | | `--version` | 528.1 ms | 405.8 ms | | `--help` | 509.8 ms | 398.5 ms | Every sample produced identical stdout/stderr hashes. Full compiled catalog identity serializes byte-for-byte like the baseline, and its detached clone matches. CPU profiling identified eager JSON Schema conversion, identity hashing, generated-catalog evaluation, and associated GC on the original version-command path. Regression coverage checks identity serialization/cloning and explicit document/cursor cache requirements. Existing production stdio MCP, doctor, server identity, CLI output, dispatch, inventory, and snapshot boundary tests pass. This measures metadata-command startup on this host, not provider analysis throughput. First digest access still performs the required complete schema work. ## Validation performed - `npm run build:cached` — passed. - `npm run check:fast` — passed. - `npm run docs:check` — passed. - `npm run test:focused -- src/application/binary/AnalysisSnapshotCache.test.ts tests/boundary/filesystem/analysisSnapshot.test.ts tests/boundary/mcp/serverIdentity.test.ts tests/boundary/mcp/mcpDoctor.test.ts tests/boundary/cli/dispatcher.test.ts tests/boundary/cli/cliToolCoverage.test.ts tests/boundary/cli/cliOutput.test.ts tests/acceptance/applications/runtime.test.ts` — eight suites, 29 passed, one platform-specific skip. - Independent Standards and Spec reviews — no findings. ## Compatibility, safety, and release - Breaking changes or migrations: none. - Real Hopper/Ghidra/browser coverage: no new provider claim; provider verification was not repeated for this initialization-only change. - Package or release metadata impact: none. - Security, privacy, process, or containment changes: none. ## Review checklist - [x] One focused outcome with a Conventional Commit title. - [x] Reason for no separate issue stated above. - [x] Observable output and meaningful snapshot boundary rules verified. - [x] Generated documents checked; unchanged contracts need no regeneration. - [x] CLI output compared exactly and production MCP identity checked. - [x] Final diff checked for unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:17:37 +00:00