Skip to content
ContractSpec
Start here

Area guide · 7 packages · Instrument one request path

Observability, testing and qualification

Follow behavior across boundaries and distinguish declared support from evidence that a selected composition works.

What are you trying to do?

  • Where do signal declarations differ from telemetry emission?
  • How does trace context cross asynchronous boundaries?
  • Which test proves the behavior I am claiming?

Why start with these packages

Suggested entry point

@lssm-tech/lib.observability

Use vendor-neutral instrumentation, signals and evidence-facing surfaces.

Read package manual →

Suggested entry point

@lssm-tech/lib.observability-spec

Inspect declarative observability contracts before binding a backend.

Read package manual →

Suggested entry point

@lssm-tech/lib.testing

Locate contract-aware testing utilities, generators, recorders and adapters.

Read package manual →

Suggested entry point

@lssm-tech/lib.agent-evals

Inspect the agent evaluation package for the selected agent task and environment.

Read package manual →

Practical steps

Step 01

Trace a successful and denied request

Follow correlation from the caller through the adapter, handler and any queued/provider work. Compare a valid request with a policy or validation denial and inspect which safe identifiers remain available for diagnosis.

Step 02

Choose one concrete regression

Use the owning package’s existing fixture or test surface for the failure you are addressing: replay, wrong scope, schema mismatch, provider timeout or translation/context drift. Avoid a check that merely restates the implementation.

Step 03

Record what the result establishes

Attach the source revision, package/environment context, command or test identity and observed outcome. Keep unexecuted source examples and source-present APIs labeled accordingly, so a later release or product page can make a defensible availability claim.

Choose the boundary to observe

The observability package provides OpenTelemetry-oriented primitives with vendor-neutral signal and error-reporting ports. Its canonical signal/evidence declarations validate supplied observations; emission, persistence and backend selection belong to the instrumentation facade and host. Start with one operation and the question you need to answer: latency, failure cause, denied authority, queue delay or provider outcome. Emit identifiers and safe evidence references that let an operator correlate those events without copying the full business payload.

Preserve context and privacy

The source documents W3C trace carrier helpers across HTTP, queues, jobs, webhooks and MCP. It also describes default privacy filtering and bounded dispatch that isolates exporter outages from business work. Inspect the exact carrier boundary and its validation rather than manually concatenating trace headers. Keep operational trace state distinct from durable domain evidence: a missing telemetry event should not be interpreted as proof that a business effect did or did not happen.

Match the test to the claim

Testing utilities include contract-aware runners, recording and generation surfaces; conformance and agent-evaluation packages provide other targeted checks. Select a check that can falsify the behavior being documented. Static source inspection can show a declared operation; a handler fixture can demonstrate a local result; a transport test can qualify encoding and context; a clean package consumer can reveal distribution problems. Provider-backed and deployed evidence require their own environment and should not be inferred from those earlier checks.

Follow a practical path.

Trace a successful and denied request

Follow correlation from the caller through the adapter, handler and any queued/provider work. Compare a valid request with a policy or validation denial and inspect which safe identifiers remain available for diagnosis.

Choose one concrete regression

Use the owning package’s existing fixture or test surface for the failure you are addressing: replay, wrong scope, schema mismatch, provider timeout or translation/context drift. Avoid a check that merely restates the implementation.

Record what the result establishes

Attach the source revision, package/environment context, command or test identity and observed outcome. Keep unexecuted source examples and source-present APIs labeled accordingly, so a later release or product page can make a defensible availability claim.

Packages in this area (7)

7 of 7 shown

  • lib.agent-evalsSuggested entry pointplatformnode

    Agent evaluation runners, adapters, graders, and recommendation evidence.

    Inspect the agent evaluation package for the selected agent task and environment.

    Open manual →
  • Cross-runtime lifecycle conformance suite for ContractSpec agent runtime adapters

    Open manual →
  • lib.loggerplatformnodebrowser

    Comprehensive logging library optimized for Bun with ElysiaJS integration

    Open manual →
  • lib.observabilitySuggested entry pointplatformnode

    OpenTelemetry-based observability primitives

    Use vendor-neutral instrumentation, signals and evidence-facing surfaces.

    Open manual →
  • lib.observability-specSuggested entry pointplatformnodebunbrowser

    Pure signal declarations, cost evidence models and deterministic validation shared by observability and billing.

    Inspect declarative observability contracts before binding a backend.

    Open manual →
  • lib.testingSuggested entry pointplatformnode

    Contract-aware testing utilities and runners

    Locate contract-aware testing utilities, generators, recorders and adapters.

    Open manual →
  • Shared test infrastructure helpers for Phase 1 / Phase 3 cockpit-kit extraction

    Open manual →

Curated but no longer in the workspace: tool.test-redaction-rules