ContractSpecContractSpec

Start with OSS

Back to changelog index

3.9.9

Aug 01, 2026 · 5 packages · 4 unique changes · 1 release entry

bundleslibs

This release affects the sharedLibs, solutions familyies.

Run contractspec connect adoption resolve --family sharedLibs to see how it impacts your project.

Release summaries

  • observability-tracing-evidence-spine

    Consolidate observability, tracing, logs, and cost/usage evidence onto one Instrumentation-facade spine; add the evidence-ledger read port, default-on agent telemetry, the managed-companyos ./observability subpath, and operator docs.

    maintainer

    lib.observability gains EvidenceLedgerReadPort + LedgerEvidenceEntry + EvidenceLedgerQuery (read seam mirroring EvidenceAppendPort). lib.ai-agent gains disableDefaultTelemetry? and instrumentation? config and installs createAgentObservabilityHooks by default. lib.surface-runtime replaces the rival surface-metrics counters with facade-backed recorders (recordResolutionDuration/recordSurfaceFallback/recordMissingRenderer) over defineSignal; OTel metric names move to canonical dotted ids. The api/worker withSpan/withSpanAsync span wrappers were removed in favour of Instrumentation.trace; getTracer remains. A Biome noRestrictedImports rule blocks reintroducing the retired span/metric APIs.

    integrator

    Emit all observability through createInstrumentation(...) — trace/meter/cost/usage/audit — keyed off defineSignal. Bind the evidence append + read ports at the app composition root inside the tenant transaction. In client/SSR-reachable modules import the facade from @lssm-tech/lib.observability/facade/instrumentation (NOT the root barrel, which pulls the Node OTel SDK). Consume PostHog names from @lssm-tech/bundle.managed-companyos/observability.

    customer

    Operators get a single, documented observability spine — traces, metrics, structured logs, and durable cost/usage evidence — with a new "Observability and cost evidence" docs page.

Upgrade steps

  • Emit observability through the Instrumentation facade

    assisted

    Replace ad-hoc span/metric helpers with one createInstrumentation(...) facade keyed off defineSignal. trace/meter route to OTel; cost/usage route to the durable evidence port.

    Packages: @lssm-tech/lib.observability, @lssm-tech/lib.ai-agent, @lssm-tech/lib.surface-runtime, @lssm-tech/bundle.managed-companyos, @lssm-tech/bundle.library

    1. Construct createInstrumentation({ meterName, serviceName, evidencePort }) once per service.
    2. Declare each signal with defineSignal({ id, kind, unit, dimensions }) and reference it by id.
    3. Use instrumentation.trace(signal, fn) for spans, instrumentation.meter(signal, value, attrs) for metrics, and instrumentation.cost/usage(record) for durable economic evidence.
    4. Remove any remaining withSpan/withSpanAsync call sites (the wrappers were deleted).

  • Keep agent telemetry default-on (or opt out)

    auto

    ContractSpecAgent installs observability hooks automatically. Pass instrumentation to back them with your own facade, or disableDefaultTelemetry to opt out.

    Packages: @lssm-tech/lib.observability, @lssm-tech/lib.ai-agent, @lssm-tech/lib.surface-runtime, @lssm-tech/bundle.managed-companyos, @lssm-tech/bundle.library

    1. Leave the defaults in place to get locale/system-prompt/retrieval/economics telemetry.

  • Import the facade from its subpath in client/SSR code

    manual

    The package root barrel pulls the Node OTel SDK; client/SSR-reachable modules must import the facade from @lssm-tech/lib.observability/facade/instrumentation.

    Packages: @lssm-tech/lib.observability, @lssm-tech/lib.ai-agent, @lssm-tech/lib.surface-runtime, @lssm-tech/bundle.managed-companyos, @lssm-tech/bundle.library

    1. Audit client/SSR-reachable modules that import createInstrumentation from the package root.
    2. Switch them to @lssm-tech/lib.observability/facade/instrumentation.

Unique release changes

  • - Consolidate observability, tracing, logs, and cost/usage evidence onto one Instrumentation-facade spine; add the evidence-ledger read port, default-on agent telemetry, the managed-companyos ./observability subpath, and operator docs.

    5 packages · 5 occurrences

  • - ContractSpecAgent installs observability hooks automatically. Pass instrumentation to back them with your own facade, or disableDefaultTelemetry to opt out.

    5 packages · 5 occurrences

  • - Replace ad-hoc span/metric helpers with one createInstrumentation(...) facade keyed off defineSignal. trace/meter route to OTel; cost/usage route to the durable evidence port.

    5 packages · 5 occurrences

  • - The package root barrel pulls the Node OTel SDK; client/SSR-reachable modules must import the facade from @lssm-tech/lib.observability/facade/instrumentation.

    5 packages · 5 occurrences

Impacted packages

  • @lssm-tech/bundle.library

    Layer: bundles · 4 changes

  • @lssm-tech/bundle.managed-companyos

    Layer: bundles · 4 changes

  • @lssm-tech/lib.ai-agent

    Layer: libs · 4 changes

  • @lssm-tech/lib.observability

    Layer: libs · 4 changes

  • @lssm-tech/lib.surface-runtime

    Layer: libs · 4 changes