Area guide · 9 packages · Trace an operation from request to handler
Handlers, runtimes and transports
Connect declared operations to supplied handlers, client state and the transport your application actually runs.
What are you trying to do?
- What belongs in the portable runtime kernel?
- Which adapter matches my REST, GraphQL or MCP host?
- Where are approvals and authenticated context enforced?
Why start with these packages
Suggested entry point
@lssm-tech/lib.contracts-runtime-kernelStart with the framework-neutral engine, canonical registries and caller-supplied runtime ports.
Suggested entry point
@lssm-tech/lib.contracts-runtime-server-restInspect the REST adapter matching your framework and its request/context handling.
Suggested entry point
@lssm-tech/lib.contracts-runtime-server-mcpUse the existing contract-to-MCP adapter when exposing a selected operation registry to tools.
Suggested entry point
@lssm-tech/lib.contracts-runtime-client-reactLocate the React consumer integration for the shared query/cache runtime.
Practical steps
Step 01
Choose one vertical slice
Select a query and a command already declared in source. Identify their registry bindings, handler context, adapter entry and consumer call. Start with the smallest actual host composition that exercises these pieces together.
Step 02
Inspect the negative path
Trace invalid input, missing trusted identity, required-but-missing approval and an unavailable handler/provider. The relevant question is whether execution stops at the correct boundary and returns a result the caller can handle.
Step 03
Qualify the selected environment
Use the host’s existing test and build setup for the exact runtime and package versions. Record separately whether you checked source, local handler execution, the transport boundary or a deployed endpoint; those observations answer different questions.
Separate reusable runtime from host composition
The runtime kernel owns the shared engine and registry identities while accepting storage, transport, approval, policy and audit responsibilities through supplied ports. Host/environment wiring and concrete providers live above that foundation. Select the server adapter by the application framework and transport, then inspect the client adapter that consumes it. REST, GraphQL and MCP are related projections of selected contracts; registering a contract does not by itself establish an authenticated endpoint or a configured handler.
Follow the request context
The REST README documents createFetchHandler with an asynchronous-capable context factory and an approvalReceipt adapter. Approval evidence is kept outside operation input and is passed to the common handler context. Required approvals are checked before handler invocation by the shared registry. Parameterized REST routes decode path values and make them authoritative over conflicting query/body fields. These details matter when replacing a handwritten endpoint: preserving the public input shape also requires preserving trusted context and precedence rules.
Keep query behavior consistent
REST requests rebuild the canonical QueryEnvelope, including supported search, filter, sort, pagination and consistency metadata. That metadata is separate from flat business input. The documented client deliberately avoids sending client cache policy by default because cache key material may contain tenant or user identifiers that would enter URL logs. Inspect caching, invalidation and offline behavior at the kernel/client boundary instead of hiding those concerns inside each handler. A transport success must still produce the expected canonical result.
Follow a practical path.
Choose one vertical slice
Select a query and a command already declared in source. Identify their registry bindings, handler context, adapter entry and consumer call. Start with the smallest actual host composition that exercises these pieces together.
Inspect the negative path
Trace invalid input, missing trusted identity, required-but-missing approval and an unavailable handler/provider. The relevant question is whether execution stops at the correct boundary and returns a result the caller can handle.
Qualify the selected environment
Use the host’s existing test and build setup for the exact runtime and package versions. Record separately whether you checked source, local handler execution, the transport boundary or a deployed endpoint; those observations answer different questions.
Packages in this area (9)
9 of 9 shown
- Open manual →
React runtime adapters for ContractSpec contracts
Locate the React consumer integration for the shared query/cache runtime.
- Open manual →
Framework-neutral in-house query/cache/offline engine and Transport port for ContractSpec data fetching
- Open manual →
Canonical framework-neutral ContractSpec engine, ports and storage; no Forms or backend authority
Start with the framework-neutral engine, canonical registries and caller-supplied runtime ports.
- Open manual →
GraphQL server runtime adapters for ContractSpec contracts
- Open manual →
MCP server runtime adapters for ContractSpec contracts
Use the existing contract-to-MCP adapter when exposing a selected operation registry to tools.
- Open manual →
REST server runtime adapters for ContractSpec contracts
Inspect the REST adapter matching your framework and its request/context handling.
- Open manual →
Shared GraphQL core: Pothos builder factory, scalars, tracing & complexity
- Open manual →
Pothos federation helpers and subgraph schema export utilities
- Open manual →
Pothos + Prisma builder factory with injectable client/DMMF
What connects to this area
Core contracts
The operation definition fixes the input, outcome and policy the runtime must preserve.
Schemas and results
Validation and serialization must match at both sides of the request.
Identity and access
The host constructs trusted request authority.
Governance and approvals
Required approval evidence belongs in the execution context.