morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #1143] [MERGED] perf(mcp): share repeated output schema definitions #2678

New issue

Closed

opened 2026-10-17 21:08:57 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:08:57 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: perf/mcp-output-schema-references

📝 Commits (1)

4b7ac7d perf(mcp): share repeated output schema definitions

📊 Changes

6 files changed (+413 additions, -5 deletions)

View changed files

📝 docs/mcp-contracts.md (+4 -0)
➕ src/contracts/toolOutputReferences.test.ts (+177 -0)
📝 src/contracts/toolSchemaMetadata.test.ts (+50 -2)
📝 src/contracts/toolSchemaMetadata.ts (+10 -2)
📝 tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts (+2 -1)
➕ tests/fixtures/localJsonSchemaReferences.ts (+170 -0)

📄 Description

Summary

The complete MCP catalog repeats large output-schema subtrees, increasing tools/list transfer and the pinned client's first successful call cost. Share repeated output definitions through local JSON Schema references while retaining complete tool descriptions and result validation. Progress on #1065.

Problem and expected behavior

REA should advertise its complete output contracts without repeatedly inlining the same definitions. On the same source baseline, the complete 138-tool catalog occupied 1,996,829 bytes and controlled first successful calls took 3.635 and 3.251 seconds. Both input compatibility and complete Evidence results must remain intact.

Change and scope

Default output projection uses Zod's reused: "ref" option. Existing projection memoization and explicit caller options remain supported. Input projection and canonical validation keep their existing behavior. A schema-aware test fixture expands finite local references for comparisons, intersects emitted numeric bounds, removes provably redundant regex constraints, rejects conflicting reference siblings, and preserves object/tuple evaluation scopes.

Two sequential paired measurements used the same source baseline (d1c904ba), pinned SDK, two-CPU affinity and a captured valid session response. The final branch is integrated with frozen main 283c82f6; the paired figures isolate this change on their stated measurement baseline. Controlled handlers isolate catalog and client-validator costs; real target workflows were verified separately.

Measurement	Before	After
Complete `tools/list` catalog	1,996,829 bytes	1,746,799 bytes (-12.5%)
First successful call, pair 1	3.635 s	2.160 s
First successful call, pair 2	3.251 s	2.128 s
Process maximum RSS, pair 1	557,334,528 bytes	467,910,656 bytes
Process maximum RSS, pair 2	580,558,848 bytes	466,853,888 bytes

Every input schema is identical after actual SDK conversion. The catalog with only output schemas removed remains 549,243 bytes and 133,214 cl100k_base tokens. These token counts are a fixed tokenizer proxy; actual model context depends on the client. Input-facing context reduction and the remaining cancellation/deadline work stay open under #1065. The complete-result transport redesign remains a separate task.

Contract and boundary impact

Semantic owner and earliest changed stage: contracts' advertised output JSON Schema projection.
CLI and MCP/tool-catalog contract: all 138 tools retained; object roots, complete fields and canonical output validation preserved. CLI analysis results are unchanged. Output schemas now contain finite local references.
Provider, bridge, target-format, or platform compatibility: no provider implementation changes; native Windows Notion and Obsidian packaged workflows verified.
Evidence, artifact, provenance, or reconstruction contract: complete Evidence and selected traces retain identical identifiers and contents.
Process execution, authorization, cleanup, or containment impact: no production lifecycle or authority changes.
Generated metadata, package, or installation impact: generated fixtures/catalogs remain ignored. Same-source tarballs differ only in dist/contracts/toolSchemaMetadata.js, with no added or removed package files; compressed size increases by 27 bytes.

Selected fragments of the actual analyze_javascript_application output schema advertised through tools/list (other complete fields and definitions omitted here):

{
  "name": "analyze_javascript_application",
  "outputSchema": {
    "type": "object",
    "properties": {
      "evidence_id": { "$ref": "#/$defs/__schema66" }
    },
    "$defs": {
      "__schema66": {
        "type": "string",
        "pattern": "^ev_[a-f0-9]{64}$"
      }
    }
  }
}

Evidence and regression coverage

Tests added or updated: all-contract output equivalence across draft 2020-12 and draft-07; AJV versus canonical numeric/strict-object validation; local-pointer escaping, literal reference-shaped data, unresolved/cyclic references, conflicting constraints, strict-object evaluation scope, and layered native-selector patterns; existing semantic assertions now inspect expanded schemas while validating the original referenced schemas.
Base reproduction or other evidence: actual SDK conversions preserve all input schemas and all expanded output meanings across all 138 tools. Direct repository fixtures preserve schemas and named handler meaning in original and reversed presentation order.
User-visible CLI/MCP output: full native Windows Notion/Obsidian analysis completes and retains Evidence. Under the default 10 MiB transport budget, large inline analysis/bundle results return typed resource constraints; selected feature traces validate through the client, ping remains responsive, close clears retained Evidence, and stale references fail meaningfully. This preserves the existing complete-result contract.
Remaining proof gaps: Final integrated package verification, both complete native Windows application reruns, and all 22 CI checks passed on head 4b7ac7de. Real Hopper/Ghidra/browser and Muse/opencode workflows are outside this schema-only validation claim. Input-facing context, external-client deadlines and the remaining cancellation phases stay open under #1065.

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

npm run build:cached — passed after integration with main; local memory/concurrency controls are forwarded using the installed Turbo's documented environment mode.
npm run check -- --concurrency=1 — all six static tasks passed on the integrated source.
npm run test:focused -- src/contracts/toolSchemaMetadata.test.ts src/contracts/toolOutputReferences.test.ts tests/boundary/mcp/toolSchemaValidity.test.ts tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts tests/boundary/mcp/wireInputSchemaLimits.test.ts — 24 tests passed.
npm run test:focused -- tests/boundary/providers/auxiliaryDeclarations.test.ts — four tests passed.
npm run test:focused -- tests/acceptance/contractPresentation.test.ts — both original/reversed presentation tests passed.
npm run docs:check — passed on the integrated source.
Full installed-package verifier — final integrated run passed in 184.224 seconds, with a 1,464,537,088-byte family RSS peak and at least 9,034,551,296 bytes host available. Actual CLI/MCP, complete catalog, Evidence, lifecycle, setup and update checks passed.
Native Windows final installed-package full Notion/Obsidian workflows — passed under two-CPU affinity, BelowNormal priority, a 1.5 GiB Node heap and guarded memory/disk budgets. Same complete selected traces and Evidence IDs as the corresponding pre-integration runs. Full analysis took 72.078 s / 175.663 s with an explicitly extended request deadline; whole process-family working-set peaks were 1,400,930,304 / 1,656,119,296 bytes. The default 10 MiB budget returned typed transport constraints for complete inline results, and direct feature retrieval, ping and session cleanup succeeded. These are acceptance observations, not paired performance measurements.
CI — all 22 checks passed on the final head, including all test shards, coverage, Linux/macOS x64 and arm64 package baselines, native Windows package/capability checks, and real Apple artifact CLI/MCP verification.
git diff --check — passed.

Compatibility, safety, and release

Breaking changes or migration steps: complete input/output data shapes are unchanged; advertised output representation uses standard local references. Explicit inline projection remains supported.
Real Hopper/Ghidra, browser, or OS coverage: no real Hopper/Ghidra/browser verification for this schema-only change. Real native Windows ASAR workflows were verified. Muse/opencode compatibility is limited to local schema and SDK checks.
Package or release metadata impact: no version bump or published-fix claim; the candidate retains the existing development package version.
Security, privacy, process, or containment review: results remain complete, with no new permissions, truncation or target execution. Public examples contain no host paths or credentials. Resource budgets and cleanup were checked in actual workflows.

Review checklist

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/1143 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/9/2026 **Status:** ✅ Merged **Merged:** 10/9/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `perf/mcp-output-schema-references` --- ### 📝 Commits (1) - [`4b7ac7d`](https://github.com/morluto/rea/commit/4b7ac7de7503c4753c6c94fd213ad46ba1b341ea) perf(mcp): share repeated output schema definitions ### 📊 Changes **6 files changed** (+413 additions, -5 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-contracts.md` (+4 -0) ➕ `src/contracts/toolOutputReferences.test.ts` (+177 -0) 📝 `src/contracts/toolSchemaMetadata.test.ts` (+50 -2) 📝 `src/contracts/toolSchemaMetadata.ts` (+10 -2) 📝 `tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts` (+2 -1) ➕ `tests/fixtures/localJsonSchemaReferences.ts` (+170 -0) </details> ### 📄 Description ## Summary The complete MCP catalog repeats large output-schema subtrees, increasing `tools/list` transfer and the pinned client's first successful call cost. Share repeated output definitions through local JSON Schema references while retaining complete tool descriptions and result validation. Progress on #1065. ## Problem and expected behavior REA should advertise its complete output contracts without repeatedly inlining the same definitions. On the same source baseline, the complete 138-tool catalog occupied 1,996,829 bytes and controlled first successful calls took 3.635 and 3.251 seconds. Both input compatibility and complete Evidence results must remain intact. ## Change and scope Default output projection uses Zod's `reused: "ref"` option. Existing projection memoization and explicit caller options remain supported. Input projection and canonical validation keep their existing behavior. A schema-aware test fixture expands finite local references for comparisons, intersects emitted numeric bounds, removes provably redundant regex constraints, rejects conflicting reference siblings, and preserves object/tuple evaluation scopes. Two sequential paired measurements used the same source baseline (`d1c904ba`), pinned SDK, two-CPU affinity and a captured valid session response. The final branch is integrated with frozen main `283c82f6`; the paired figures isolate this change on their stated measurement baseline. Controlled handlers isolate catalog and client-validator costs; real target workflows were verified separately. | Measurement | Before | After | | --- | --- | --- | | Complete `tools/list` catalog | 1,996,829 bytes | 1,746,799 bytes (-12.5%) | | First successful call, pair 1 | 3.635 s | 2.160 s | | First successful call, pair 2 | 3.251 s | 2.128 s | | Process maximum RSS, pair 1 | 557,334,528 bytes | 467,910,656 bytes | | Process maximum RSS, pair 2 | 580,558,848 bytes | 466,853,888 bytes | Every input schema is identical after actual SDK conversion. The catalog with only output schemas removed remains 549,243 bytes and 133,214 `cl100k_base` tokens. These token counts are a fixed tokenizer proxy; actual model context depends on the client. Input-facing context reduction and the remaining cancellation/deadline work stay open under #1065. The complete-result transport redesign remains a separate task. ## Contract and boundary impact - Semantic owner and earliest changed stage: contracts' advertised output JSON Schema projection. - CLI and MCP/tool-catalog contract: all 138 tools retained; object roots, complete fields and canonical output validation preserved. CLI analysis results are unchanged. Output schemas now contain finite local references. - Provider, bridge, target-format, or platform compatibility: no provider implementation changes; native Windows Notion and Obsidian packaged workflows verified. - Evidence, artifact, provenance, or reconstruction contract: complete Evidence and selected traces retain identical identifiers and contents. - Process execution, authorization, cleanup, or containment impact: no production lifecycle or authority changes. - Generated metadata, package, or installation impact: generated fixtures/catalogs remain ignored. Same-source tarballs differ only in `dist/contracts/toolSchemaMetadata.js`, with no added or removed package files; compressed size increases by 27 bytes. Selected fragments of the actual `analyze_javascript_application` output schema advertised through `tools/list` (other complete fields and definitions omitted here): ```json { "name": "analyze_javascript_application", "outputSchema": { "type": "object", "properties": { "evidence_id": { "$ref": "#/$defs/__schema66" } }, "$defs": { "__schema66": { "type": "string", "pattern": "^ev_[a-f0-9]{64}$" } } } } ``` ## Evidence and regression coverage - Tests added or updated: all-contract output equivalence across draft 2020-12 and draft-07; AJV versus canonical numeric/strict-object validation; local-pointer escaping, literal reference-shaped data, unresolved/cyclic references, conflicting constraints, strict-object evaluation scope, and layered native-selector patterns; existing semantic assertions now inspect expanded schemas while validating the original referenced schemas. - Base reproduction or other evidence: actual SDK conversions preserve all input schemas and all expanded output meanings across all 138 tools. Direct repository fixtures preserve schemas and named handler meaning in original and reversed presentation order. - User-visible CLI/MCP output: full native Windows Notion/Obsidian analysis completes and retains Evidence. Under the default 10 MiB transport budget, large inline analysis/bundle results return typed resource constraints; selected feature traces validate through the client, ping remains responsive, close clears retained Evidence, and stale references fail meaningfully. This preserves the existing complete-result contract. - Remaining proof gaps: Final integrated package verification, both complete native Windows application reruns, and all 22 CI checks passed on head `4b7ac7de`. Real Hopper/Ghidra/browser and Muse/opencode workflows are outside this schema-only validation claim. Input-facing context, external-client deadlines and the remaining cancellation phases stay open under #1065. 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 - `npm run build:cached` — passed after integration with main; local memory/concurrency controls are forwarded using the installed Turbo's documented environment mode. - `npm run check -- --concurrency=1` — all six static tasks passed on the integrated source. - `npm run test:focused -- src/contracts/toolSchemaMetadata.test.ts src/contracts/toolOutputReferences.test.ts tests/boundary/mcp/toolSchemaValidity.test.ts tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts tests/boundary/mcp/wireInputSchemaLimits.test.ts` — 24 tests passed. - `npm run test:focused -- tests/boundary/providers/auxiliaryDeclarations.test.ts` — four tests passed. - `npm run test:focused -- tests/acceptance/contractPresentation.test.ts` — both original/reversed presentation tests passed. - `npm run docs:check` — passed on the integrated source. - Full installed-package verifier — final integrated run passed in 184.224 seconds, with a 1,464,537,088-byte family RSS peak and at least 9,034,551,296 bytes host available. Actual CLI/MCP, complete catalog, Evidence, lifecycle, setup and update checks passed. - Native Windows final installed-package full Notion/Obsidian workflows — passed under two-CPU affinity, BelowNormal priority, a 1.5 GiB Node heap and guarded memory/disk budgets. Same complete selected traces and Evidence IDs as the corresponding pre-integration runs. Full analysis took 72.078 s / 175.663 s with an explicitly extended request deadline; whole process-family working-set peaks were 1,400,930,304 / 1,656,119,296 bytes. The default 10 MiB budget returned typed transport constraints for complete inline results, and direct feature retrieval, ping and session cleanup succeeded. These are acceptance observations, not paired performance measurements. - CI — all 22 checks passed on the final head, including all test shards, coverage, Linux/macOS x64 and arm64 package baselines, native Windows package/capability checks, and real Apple artifact CLI/MCP verification. - `git diff --check` — passed. ## Compatibility, safety, and release - Breaking changes or migration steps: complete input/output data shapes are unchanged; advertised output representation uses standard local references. Explicit inline projection remains supported. - Real Hopper/Ghidra, browser, or OS coverage: no real Hopper/Ghidra/browser verification for this schema-only change. Real native Windows ASAR workflows were verified. Muse/opencode compatibility is limited to local schema and SDK checks. - Package or release metadata impact: no version bump or published-fix claim; the candidate retains the existing development package version. - Security, privacy, process, or containment review: results remain complete, with no new permissions, truncation or target execution. Public examples contain no host paths or credentials. Resource budgets and cleanup were checked in actual workflows. ## Review checklist - [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>

bsakaguchi

2026-10-17 21:08:57 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-10-31 01:05:50 +00:00

[PR #2714] [CLOSED] fix(javascript): ignore Electron callee names that only share a suffix #5336

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#2678

No description provided.

Rows
Columns