Story
As an XMD component or operation author, I want types to expose the contextual interfaces my operation needs, so I can understand and compose its dependencies without tracing every possible provider installation.
A contextual interface describes operations supplied by the surrounding Effection scope. The required shape can be known even when the provider that supplies it is selected at runtime.
Example
A review component sends Agent prompts and reads files. Its type makes those requirements visible. An enclosing operation that calls the review component exposes the requirements it has not supplied itself. A host can choose production or test providers while preserving the same required shapes.
This example describes the intended information, not a proposed TypeScript signature. The type representation and checking mechanism remain open design questions.
Current gap
XMD's contextual APIs already type arguments, results, and middleware through Api<A>. The installed Effection Operation<T> describes the result and iteration protocol; it does not expose a set of required contextual interfaces. Readers therefore discover those requirements by following calls and registrations.
Typed API members and typed context requirements solve different problems. A handler can have the correct signature while its surrounding assembly still lacks behavior a consumer requires.
Accepted direction
- Required contextual shapes are visible independently of the selected provider implementation.
- The design examines how requirements propagate through nested calls and how supplying behavior affects the remaining requirements.
- The design distinguishes required services, optional contextual values, usable defaults, and default handlers that refuse because no provider is installed.
- Contextual selection, lexical middleware composition, and scope-owned lifetimes remain supported.
- Type information describes composition requirements. Execution identity, permissions, durable settlement, and exclusive ownership retain their existing owners.
Open design questions
- Does the representation belong in Effection,
@effectionx/context-api, XMD, or a combination? Prefer an upstream solution where the requirement is general.
- Can requirements be inferred through ordinary
yield* composition, or must some boundaries declare them? What is the annotation cost?
- How are partial middleware, delegation, conditional use, and defaults represented?
- Which missing requirements can TypeScript reject at an assembly boundary, and which remain runtime checks for dynamic plugins and components?
- How are stable, namespaced API identities represented across separately loaded package copies?
Evidence and completion
Use one real XMD consumer and its production/test assemblies as the reference case, beginning with Agent.prompt and a file-reading operation. Show a nested call whose requirements are visible, an assembly that supplies them, and one that omits a required interface. Explain whether the omission is statically rejected or only reported as a declared requirement; do not present documentation-only typing as an availability guarantee.
The first design deliverable includes the proposed signatures, propagation examples, unsupported cases, and a recommendation backed by a small type-checking experiment. If the representation cannot reliably enforce availability, record that limitation and the value it still provides. Product interface and architecture review settle the design before an implementation handoff is finalized.
References and relationships
packages/core/src/agent/agent-api.ts: a representative typed contextual API.packages/runtime/apis.ts: file, process, environment, and fetch operations.architecture.md sections State ownership and State across loaded copies; .agents/architecture-rules.md.@effectionx/context-api 0.6.0 and the installed Effection declarations are the investigation starting point, not required future versions.
This is an independent follow-up Story with open design choices. Its companions are #893 (source relationships) and #894 (live Effection inspection). None is a prerequisite for the others; integrating 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
Choosing concrete providers statically, replacing contextual APIs with explicit parameter threading, implementing the source index or inspector, and changing XMD execution or persistence semantics.
Story
As an XMD component or operation author, I want types to expose the contextual interfaces my operation needs, so I can understand and compose its dependencies without tracing every possible provider installation.
A contextual interface describes operations supplied by the surrounding Effection scope. The required shape can be known even when the provider that supplies it is selected at runtime.
Example
A review component sends Agent prompts and reads files. Its type makes those requirements visible. An enclosing operation that calls the review component exposes the requirements it has not supplied itself. A host can choose production or test providers while preserving the same required shapes.
This example describes the intended information, not a proposed TypeScript signature. The type representation and checking mechanism remain open design questions.
Current gap
XMD's contextual APIs already type arguments, results, and middleware through
Api<A>. The installed EffectionOperation<T>describes the result and iteration protocol; it does not expose a set of required contextual interfaces. Readers therefore discover those requirements by following calls and registrations.Typed API members and typed context requirements solve different problems. A handler can have the correct signature while its surrounding assembly still lacks behavior a consumer requires.
Accepted direction
Open design questions
@effectionx/context-api, XMD, or a combination? Prefer an upstream solution where the requirement is general.yield*composition, or must some boundaries declare them? What is the annotation cost?Evidence and completion
Use one real XMD consumer and its production/test assemblies as the reference case, beginning with
Agent.promptand a file-reading operation. Show a nested call whose requirements are visible, an assembly that supplies them, and one that omits a required interface. Explain whether the omission is statically rejected or only reported as a declared requirement; do not present documentation-only typing as an availability guarantee.The first design deliverable includes the proposed signatures, propagation examples, unsupported cases, and a recommendation backed by a small type-checking experiment. If the representation cannot reliably enforce availability, record that limitation and the value it still provides. Product interface and architecture review settle the design before an implementation handoff is finalized.
References and relationships
packages/core/src/agent/agent-api.ts: a representative typed contextual API.packages/runtime/apis.ts: file, process, environment, and fetch operations.architecture.mdsections State ownership and State across loaded copies;.agents/architecture-rules.md.@effectionx/context-api0.6.0 and the installed Effection declarations are the investigation starting point, not required future versions.This is an independent follow-up Story with open design choices. Its companions are #893 (source relationships) and #894 (live Effection inspection). None is a prerequisite for the others; integrating 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
Choosing concrete providers statically, replacing contextual APIs with explicit parameter threading, implementing the source index or inspector, and changing XMD execution or persistence semantics.