lib.observability

@lssm-tech/lib.observability

./signals owns the canonical signal and evidence declaration family. Its signal-spec, evidence-record and database-signals leaves preserve the existing schemas, canonical identifiers, validation errors and DocBlocks. Historical ContractSpec signal imports forward to these same implementations. These entries validate supplied observations; they do not emit telemetry, persist evidence, evaluate current policy or authorize actions. Emission and tenant-scoped evidence ports remain in the existing instrumentation facade.

The local no-emit typecheck uses the repository common root to check the RuntimeCore compatibility fixture alongside this package's sources. Production declaration builds select tsconfig.build.json, retaining rootDir: src and excluding tests, specs and test-only directories from emitted declarations. The source typecheck still includes these fixtures through tsconfig.json; packed-consumer qualification retains its own package boundaries.

Website: https://contractspec.io

OpenTelemetry-based observability primitives.

What It Provides

• Layer: lib.
• Consumers: evolution, progressive-delivery, bundles.
• src/pipeline/ contains pipeline stages and orchestration helpers.
• ObservabilityPort and ErrorReportingPort expose vendor-neutral OTel signal contracts. Privacy filtering removes secret, raw payload, and personal fields by default, including separator, case, and camel-case aliases; bounded dispatchers isolate exporter outages from business work.
• W3C traceparent/tracestate carrier helpers preserve context across HTTP, queues, jobs, webhooks, MCP calls, and other synchronous or asynchronous boundaries. Incoming traceparent values are exact (surrounding whitespace is rejected), while tracestate members enforce W3C syntax, uniqueness, and member and total-size limits. Only ASCII space and tab are accepted as optional whitespace around member separators.
• Related ContractSpec packages include @lssm-tech/lib.contracts-integrations, @lssm-tech/lib.contracts-spec, @lssm-tech/lib.lifecycle, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
• src/pipeline/ contains pipeline stages and orchestration helpers.

Installation

npm install @lssm-tech/lib.observability

or

bun add @lssm-tech/lib.observability

Usage

Import the root entrypoint from @lssm-tech/lib.observability, or choose a documented subpath when you only need one part of the package surface.

Architecture

• src/anomaly is part of the package's public or composition surface.
• src/index.ts is the root public barrel and package entrypoint.
• src/intent is part of the package's public or composition surface.
• src/logging is part of the package's public or composition surface.
• src/metrics is part of the package's public or composition surface.
• src/pipeline/ contains pipeline stages and orchestration helpers.
• src/telemetry is part of the package's public or composition surface.
• OperationalImprovementAnalyticsReader projects an explicit PostHog/HogQL metadata allowlist into sanitized operational signals and plan-bound observation results. It never selects raw prompts, payloads, credentials, or personal fields.

Public Entry Points

• Export . resolves through ./src/index.ts.
• Export ./anomaly/alert-manager resolves through ./src/anomaly/alert-manager.ts.
• Export ./anomaly/anomaly-detector resolves through ./src/anomaly/anomaly-detector.ts.
• Export ./anomaly/baseline-calculator resolves through ./src/anomaly/baseline-calculator.ts.
• Export ./anomaly/root-cause-analyzer resolves through ./src/anomaly/root-cause-analyzer.ts.
• Export ./intent/aggregator resolves through ./src/intent/aggregator.ts.
• Export ./intent/detector resolves through ./src/intent/detector.ts.
• Export ./logging resolves through ./src/logging/index.ts. It exposes the OTel-correlated Logger and the host structured JSON logger (createStructuredLogger, hashTenantRef): ctx, msg calls, child bindings, injectable sink, and tenant_id emitted only as an opaque tenant_ref_ hash.
• Export ./metrics resolves through ./src/metrics/index.ts.
• Export ./pipeline/evolution-pipeline resolves through ./src/pipeline/evolution-pipeline.ts.
• Export ./telemetry/operational-improvement-reader resolves through ./src/telemetry/operational-improvement-reader.ts.
• The root entry point exports the platform ports, privacy sanitizer, resilient dispatcher, and W3C trace-context helpers.
• Keep the public subpath list aligned with package.json.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test --pass-with-no-tests
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Circular import issue.
• Normalize formatting across contracts-integrations, composio, and observability.
• Add AI provider ranking system with ranking-driven model selection.

Notes

• OTel span and metric naming conventions must stay consistent across the platform.
• Pipeline interfaces are adapter boundaries — do not leak vendor-specific details.
• Anomaly detection thresholds affect alerting; changes require validation.

Canonical source ownership: @lssm-tech/lib.contracts-runtime-kernel owns the existing framework-neutral implementation; module.forms/runtime owns the existing Forms service and FormsPlatformError; Observability/contracts-runtime owns the existing automatic backend event binding. Legacy five maps and default behavior are preserved. Clean artifact qualification and runtime authority remain separate requirements.

The contracts-runtime leaf owns the existing event binding. It retains the original root-selected singleton/backend initialization, logger-only override, active trace context, meter namespace, metric identities/names/tags, safe economic filtering and unsubscribe. No SDK/exporter starts. All prior public roots stay exact. Producer declarations/physical consumers/release/final-tree acceptance remain pending.

Canonical telemetry tracking, anomaly monitoring and registry implementations belong to Observability. Legacy telemetry leaves forward to the same constructors; privacy masking, sampling, defaults, provider dispatch and anomaly callback ordering are preserved. Clean declarations and physical consumers remain to be qualified.

Complete provider-neutral analytics request, reader and writer contracts are owned by Observability. Existing Integration provider leaves forward to the same full declarations. Concrete adapters and query execution remain with their existing implementations.

Portable signal schemas and evidence validation are owned by @lssm-tech/lib.observability-spec. Existing /signals/signal-spec and /signals/evidence-record leaves forward the same canonical objects. Database signal defaults remain here.

Canonical telemetry V2 schemas, validation, digests and delivery taxonomy preserve historical identities. The operations/audit leaves own portable audit queries, export/evidence commands and pipeline-health declarations with original retention, auth and signing requirements. Importing these leaves does not initialize telemetry or execute exports.

The shared/audit and shared/window leaves preserve original schema identities; operations/registry.audit retains the existing audit contract registration helper.