Skip to content

research(architecture): establish demand and compatibility gates for external domain modules #3137

Open

Description

@N0zoM1z0

Follow-up to #2016, whose original three-stage implementation and scoped verification are complete. This issue owns only the bounded continuation below. #740 owns the broader modularization roadmap; this issue owns only the demand/compatibility gate for the previously deferred external SDK.

Analyst question and outcome

Is there a concrete domain/provider integration that the current static descriptors and one REA distribution cannot reasonably support, sufficient to justify an external module SDK?

Existing evidence and decision boundary

Status: demand research and compatibility design only; a generic plugin ecosystem is deferred.

#2122/#2261 establish small static WASM/EVM bindings using named contracts, existing factories/CLI names, legacy injection and cleanup ownership. #2427 verifies incompatible static contract bindings through compiler assignability and duplicate SDK registration before provider use. This is not third-party dynamic ABI/version admission. Descriptor wiring alone established no token or latency reduction.

Bounded work

  1. Collect at most two concrete extension use cases from actual maintainer/contributor workflows. For each, document the current static integration steps, repeated maintenance/discovery cost and exact limitation; do not infer demand from the availability of a plugin mechanism.
  2. Compare keeping static composition, a documented internal extension recipe, and an optional external module boundary. Preserve one usable default distribution and existing capabilities/catalog; users must not install packs to regain shipped tools. Engine adapters, domain semantics and composed workflows remain distinct.
  3. If external loading is justified, specify a small contract/identity/lifetime boundary and pre-use compatibility tests: exact named operations/types, post-SDK advertised schema dialect, version/ABI admission, duplicate registration, capability/effect declarations, partial/unavailable failure isolation and retained cleanup/retry ownership. No catalog position selects a handler/schema.
  4. Document packaging/configuration migration and discovery costs. Automatic discovery, hot reload, plugin distribution, a mandatory Code Mode bridge, generic engine protocols and persistent database caches are not implemented by this issue. Add these only through independently justified proposals. A no-SDK decision closes this research task successfully.

Acceptance

  • At most two concrete extension needs and observed costs demonstrate whether static composition is insufficient.
  • Compare the smallest existing/static alternative with an external boundary, including migration and measured discovery/maintenance costs.
  • Document a no-SDK decision or a narrow opt-in contract and meaningful pre-use/lifecycle/old-client verification plan.
  • SDK/runtime loader/hot reload/distribution work remains deferred and separately scoped; existing user defaults and shipped capabilities remain usable.

Compatibility, measurement and host constraints

Token consumption and time to a correct answer are the primary outcomes. Record total/cached/uncached input, output, discovery, RPCs, retries and failed attempts separately from JSON bytes. Preserve negative results; a smaller response alone is not a speed or token win. Separate observed producer/transport/client work and unknown stages, and compare equivalent completed questions.

Keep current complete defaults, caller-selected inputs/providers, source bytes, Evidence identity/links, omission/null/type distinctions, partial coverage, and lifecycle/export/import behavior. Inspect the current advertised contracts and reuse existing selectors/views before adding code. Any implementation needs measured benefit and relevant compatibility verification; a documented no-change decision is a successful research outcome. Run checks for affected boundaries rather than repeating unrelated suites after each small correction.

Run heavy work serially under one CPU, 3 GiB early stop / 4 GiB hard memory, no swap, owned scopes and host-availability checks. Distinguish verified payload-phase observations from unavailable terminal whole-scope counters; missing counters stay unknown. For performance experiments, use real public CLI/MCP workflows and actual Codex CLI tasks when assessing agent token/time outcomes, with a private temporary profile pointing at the tested REA MCP; pin the requested model/reasoning and runtime within each cohort. Planning or demand-only work does not require an unrelated model/provider matrix. Simulated providers do not establish real-provider behavior. Keep raw captures/binaries/replies/transcripts/configuration private, commit source and curated reproducible findings, and record unrelated product bugs in the existing /tmp team handoff. No release is part of this task.

Activity

  1. self-assigned this
    on Oct 14, 2026
  2. added
    enhancementNew feature or request
    P1: highHigh priority issue for current or next iteration
    area: domainDomain logic, errors, and pure functions
    roadmapMulti-issue implementation roadmap
    performancePerformance regressions, scaling limits, and bounded-resource work
    designArchitecture, provider, or contract decisions needed before implementation
    on Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P1: highHigh priority issue for current or next iterationarea: domainDomain logic, errors, and pure functionsarea:domaindesignArchitecture, provider, or contract decisions needed before implementationenhancementNew feature or requestperformancePerformance regressions, scaling limits, and bounded-resource workroadmapMulti-issue implementation roadmaptriageAwaiting triage and prioritization

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions