@noego/telemetry 0.0.1

package/README.md

@@ -0,0 +1,130 @@
+# `@noego/telemetry`
+
+Bounded structured telemetry for Node, browsers, and Electron. The core package owns envelope normalization, batching, transport contracts, routing, and collector semantics. SQLite is an explicit Node-only storage terminal.
+
+```ts
+import {
+  DEFAULT_METADATA_SNAPSHOT_LIMITS,
+  DEFAULT_TELEMETRY_ADMISSION_POLICY,
+  NodeTelemetryProducerHost,
+} from '@noego/telemetry/node/producer';
+
+const host = new NodeTelemetryProducerHost({
+  source: 'api',
+  processKind: 'server',
+  transport, // Any TelemetryBatchTransport implementation.
+  admission: DEFAULT_TELEMETRY_ADMISSION_POLICY,
+  metadata: DEFAULT_METADATA_SNAPSHOT_LIMITS,
+  producerId: null,
+});
+
+host.client.info('tool.set.resolve.started', {
+  conversationId: 169,
+  toolCount: 8,
+});
+```
+
+Producer calls only take a bounded metadata snapshot and enqueue it. Encoding, checksums, transport work, metric extraction, persistence, and maintenance run asynchronously downstream.
+
+Producer-only Node applications should import `@noego/telemetry/node/producer`.
+That entry contains no SQLite, Proper, SQLStack, filesystem, or native-addon
+dependency. The existing `@noego/telemetry/node` entry remains the compatible
+collector/combined composition surface and therefore includes SQLite support.
+
+Node supports producer, collector, and combined roles. Browser code injects a
+browser-safe transport through `@noego/telemetry/browser`; Electron renderers
+use the browser client while the main or utility process composes the Node
+collector. Custom batch transports and custom storage terminals implement the
+public core contracts, so pipes and durable targets can be chained or fanned
+out without changing event producers.
+
+## Rust N-API collector
+
+Electron applications should use `NativeTelemetryHost.combined(...)` from
+`@noego/telemetry/node` when collector work must not run on Electron's event
+loop. The N-API boundary validates its constructor configuration, starts one
+named `noego-telemetry-collector` Rust thread, and sends it commands through a
+bounded channel. Batch validation, metric extraction, SQLite transactions,
+rollups, retention, lease heartbeats, checkpoints, incremental reclaim, and
+shutdown execute on that thread. JavaScript receives promises backed by N-API
+tasks; no SQLite statement executes in the calling JavaScript thread.
+
+Build the native addon with `npm run build:native`, or use `npm run build` to
+build the addon and TypeScript package together. The build requires a Rust
+toolchain with Cargo. The resulting N-API 9 addon is loaded by package-relative
+path and works under both supported Node and Electron runtimes. There is no
+fallback from `NativeTelemetryHost` to synchronous JavaScript SQLite.
+
+Collector and combined Node hosts can create same-process producers with
+`host.createLocalProducer({ source, processKind, admission, metadata,
+producerId })`. Each producer receives its own in-memory durable pipe and
+sequence identity; the host owns and drains all of them before collector
+shutdown.
+
+SQLite owns its schema and runs bundled Proper migrations through its sole
+writer connection. Table names are predefined; a validated prefix or logical
+table override map is available as an initialization escape hatch. Metric
+definitions write generic versioned rows and never create application tables.
+
+SQLite idempotency is deliberately time-bounded. Exact duplicate
+acknowledgements are retained for `raw + lateArrival`; after that window, the
+durable per-producer watermark rejects reused or overlapping sequence ranges.
+The ingestion horizon is the longest configured raw/sample/rollup retention
+window. Batches containing events older than that horizon are rejected, which
+allows inactive producer watermarks to be removed after their acknowledgements,
+raw rows, samples, and extraction failures have expired without letting an old
+retry resurrect a retained aggregate. Retention catches up in 500-row
+transactions until its work deadline, and also bounds completed maintenance
+runs, released/expired reader leases, extraction failures, and unreferenced
+inactive metric definitions. Committed producer drop counters are accumulated
+transactionally in a fixed target/reason/priority table and exposed in the
+SQLite target status; duplicate batches never increment them twice.
+
+Node collector hosts run maintenance once at startup and once, within the same
+absolute shutdown deadline, after producers drain. Regular scheduling remains
+collector-owned. A cardinality `reject` marks only that metric/version/
+resolution/bucket as durably rejected: it is not query coverage and cannot
+authorize raw/sample deletion, but it also cannot block other rollups or later
+retention stages. Unchanged rejections are not recomputed; a late sample
+invalidates the marker and retries the bucket. Retention keyset-scans beyond
+protected rows, and due-bucket selection filters current markers before its
+page limit, so old or rejected buckets cannot starve newer work.
+
+Metric query ranges are half-open and return only buckets fully contained in
+the requested interval. An unaligned leading or trailing bucket is represented
+as a `partial-bucket` coverage gap instead of returning data from outside the
+range. Historical definition versions are never merged implicitly: overlapping
+versions are returned as parallel, version-labelled segments, and graph output
+uses separate version/resolution series.
+
+The Node CLI uses the same bounded query contracts:
+
+```bash
+telemetry timeline query --config telemetry.config.yml \
+  --storage-base /path/to/app-data \
+  --label tool.set.resolve.started \
+  --from 2026-07-10T10:00:00Z \
+  --to 2026-07-10T12:00:00Z
+
+telemetry metrics graph --config telemetry.config.yml \
+  --storage-base /path/to/app-data \
+  --metric tool_set_resolve_by_conversation \
+  --where conversationId=169 \
+  --measurement count \
+  --resolution 15m \
+  --from 2026-07-10T10:00:00Z \
+  --to 2026-07-10T12:00:00Z \
+  --type line --format svg --output tool-resolves.svg
+```
+
+`--where` values use JSON primitive typing: `169`, `true`, `false`, and `null`
+remain typed values, while ordinary text remains text. Quote a numeric-looking
+string as JSON (for example `--where 'conversationId="169"'`). Repeating a
+dimension or passing a non-empty JSON array creates a bounded `in` filter.
+
+Read-only timeline, metric, graph, and guarded SQL commands can query a live
+SQLite collector through a concurrent WAL reader. Migration and maintenance
+commands acquire the exclusive telemetry lease and refuse a live collector.
+See the `@noego/telemetry/core`, `/node/producer`, `/node`,
+`/browser`, `/electron`, `/sqlite`, `/trace-adapter`, `/cli`, and `/testing`
+exports for composition.