Story
As an XMD maintainer, I want to navigate the source relationships between components and contextual APIs, so I can find what a component calls, what can handle those calls, and where hosts install that behavior.
Example
Starting from Agent.prompt, a reader can find components that invoke it, providers that implement it, middleware that wraps it, and host assemblies that install those providers. Starting from <Prompt>, the reader can follow its implementation to that operation and the relevant source locations.
The index describes relationships found in source. It identifies uncertainty where actual component resolution or handler selection depends on runtime context.
Current gap
Imports reveal module dependencies, but contextual behavior also depends on operation calls, middleware registration, host installation, and component composition. Discovering these relationships currently requires following source across files.
XMD already has non-executing source inspection and a component documentation index. Those answer where elements are written and how registered components are documented; they do not provide this relationship graph.
Accepted direction
- Generate an index from source and existing declarations wherever possible, so source changes do not require maintaining a second architectural description by hand.
- Distinguish operation calls, provider implementations, middleware wrapping, host installation, and component composition. A module import alone does not establish those relationships.
- Preserve source locations and component origins. Two same-named components from different origins remain distinct.
- Show dynamic or unresolved relationships honestly. Candidate providers in source are not evidence of which provider handled a live call.
- Building or reading the index does not execute authored documents, start providers, or create execution history.
Open design questions
- Which source forms belong in the first useful index: TypeScript operations, function components, authored Markdown components, plugin declarations, and host assemblies?
- Which relationships can the TypeScript compiler and existing XMD scanner derive, and which need small explicit declarations?
- How should users query and navigate the index: editor integration, a CLI, a generated artifact, or another surface?
- How are aliases, re-exports, dynamic component resolution, and separately loaded packages represented?
- What freshness and regeneration behavior makes an index dependable while respecting repository verification ownership rules?
Evidence and completion
Use the existing <Prompt> → Agent.prompt → ACP provider → CLI/REPL assembly path as a reference journey. The proposed index shows callers, implementations, wrappers, installations, and source locations with each relationship identified by kind.
Include controls that distinguish a semantic index from an import graph: a caller reached through an alias, two providers for the same API, two same-named components from different origins, and a dynamic relationship the index cannot settle. A source rename or relationship change appears after regeneration without a manual graph edit.
The first design deliverable includes a representative generated index, the navigation/query proposal, supported and unresolved relationship classes, and a recommendation for the smallest useful implementation. Product interface and architecture review settle the design before an implementation handoff is finalized.
References and relationships
packages/core/src/agent/function-components.ts and packages/core/src/agent/agent-api.ts.packages/acp/src/provider.ts, packages/cli/src/agent-stack.ts, and packages/cli/src/repl-profile.ts.packages/core/src/source-inspection.ts, packages/core/src/inspect.ts, and packages/core/src/documentation-index.ts: existing inspection/catalog boundaries to evaluate for reuse.architecture.md sections State across loaded copies, The Plugin boundary, and The three contextual APIs a Plugin composes through.
This is an independent follow-up Story with open design choices. Its companions are #892 (typed context requirements) and #894 (live Effection inspection). Existing types and source are sufficient to begin; neither companion is a prerequisite. Connecting their results is a later decision.
The shared distinction is: types describe required behavior, a source index describes code relationships, runtime inspection describes actual activity, and the journal describes durable execution history.
Out of scope
Claiming the statically selected runtime middleware chain, changing component resolution, implementing typed context requirements or the runtime inspector, and a manually maintained architecture graph.
Story
As an XMD maintainer, I want to navigate the source relationships between components and contextual APIs, so I can find what a component calls, what can handle those calls, and where hosts install that behavior.
Example
Starting from
Agent.prompt, a reader can find components that invoke it, providers that implement it, middleware that wraps it, and host assemblies that install those providers. Starting from<Prompt>, the reader can follow its implementation to that operation and the relevant source locations.The index describes relationships found in source. It identifies uncertainty where actual component resolution or handler selection depends on runtime context.
Current gap
Imports reveal module dependencies, but contextual behavior also depends on operation calls, middleware registration, host installation, and component composition. Discovering these relationships currently requires following source across files.
XMD already has non-executing source inspection and a component documentation index. Those answer where elements are written and how registered components are documented; they do not provide this relationship graph.
Accepted direction
Open design questions
Evidence and completion
Use the existing
<Prompt>→Agent.prompt→ ACP provider → CLI/REPL assembly path as a reference journey. The proposed index shows callers, implementations, wrappers, installations, and source locations with each relationship identified by kind.Include controls that distinguish a semantic index from an import graph: a caller reached through an alias, two providers for the same API, two same-named components from different origins, and a dynamic relationship the index cannot settle. A source rename or relationship change appears after regeneration without a manual graph edit.
The first design deliverable includes a representative generated index, the navigation/query proposal, supported and unresolved relationship classes, and a recommendation for the smallest useful implementation. Product interface and architecture review settle the design before an implementation handoff is finalized.
References and relationships
packages/core/src/agent/function-components.tsandpackages/core/src/agent/agent-api.ts.packages/acp/src/provider.ts,packages/cli/src/agent-stack.ts, andpackages/cli/src/repl-profile.ts.packages/core/src/source-inspection.ts,packages/core/src/inspect.ts, andpackages/core/src/documentation-index.ts: existing inspection/catalog boundaries to evaluate for reuse.architecture.mdsections State across loaded copies, The Plugin boundary, and The three contextual APIs a Plugin composes through.This is an independent follow-up Story with open design choices. Its companions are #892 (typed context requirements) and #894 (live Effection inspection). Existing types and source are sufficient to begin; neither companion is a prerequisite. Connecting their results is a later decision.
The shared distinction is: types describe required behavior, a source index describes code relationships, runtime inspection describes actual activity, and the journal describes durable execution history.
Out of scope
Claiming the statically selected runtime middleware chain, changing component resolution, implementing typed context requirements or the runtime inspector, and a manually maintained architecture graph.