Skip to content
ContractSpec
Start here

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-kernel

Start with the framework-neutral engine, canonical registries and caller-supplied runtime ports.

Read package manual →

Suggested entry point

@lssm-tech/lib.contracts-runtime-server-rest

Inspect the REST adapter matching your framework and its request/context handling.

Read package manual →

Suggested entry point

@lssm-tech/lib.contracts-runtime-server-mcp

Use the existing contract-to-MCP adapter when exposing a selected operation registry to tools.

Read package manual →

Suggested entry point

@lssm-tech/lib.contracts-runtime-client-react

Locate the React consumer integration for the shared query/cache runtime.

Read package manual →

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