@aaac/observability 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 foo-log-inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @aaac/observability
+
+aaac-native, in-process observability recording for the AaaC toolchain.
+Records agent / process / promotion events into a local SQLite store and emits
+them to a generic OTEL backend. See `docs/observability-spec/` for the full design.
+
+## Install
+
+```bash
+npm install @aaac/observability
+```
+
+Requires Node.js >= 22.5 (uses the built-in `node:sqlite`).
+
+## What it does
+
+- **In-process recording**: `@aaac/runtime` emits agent-axis spans via
+  `observer.emit()`; external processes (git / Cursor hooks, CI) register events
+  via `registerExternalEvent()`.
+- **Pipeline**: EventCollector → Normalizer → Correlator (span lifecycle pairing,
+  duration, traceId) → Enricher (TypeScript correlation completion) → SqliteSink
+  + OtelEmitter.
+- **CanonicalEvent** internal model with cross-axis links; OTEL is the export
+  representation (Span / SpanLink).
+- **Generic OTEL aggregation**: `OtelEmitter` batches CanonicalEvents to an
+  OTLP-compatible backend (fail-open — local SQLite always records).
+- **Query (read path)**: `QueryAdapter` over the SQLite store — span / trace /
+  link traversal, independent of the write path.
+
+## Library usage
+
+```typescript
+import { createPipeline, EventCollector } from "@aaac/observability";
+```
+
+## CLI: `aaac-observ`
+
+A thin entrypoint for external event registration and querying (interface
+defined via cli-contracts).
+
+```bash
+aaac-observ record --event-type process.edit --lifecycle instant --attr edit.path=src/x.ts
+aaac-observ query trace --trace-id <id>
+```
+
+## Documentation
+
+- Event format and catalog: `docs/observability-spec/event-catalog.md`
+- Architecture: `docs/observability-spec/architecture.md`
+- 3-axis model: `docs/observability-spec/shift-left-guidline-v2.md`
+
+## License
+
+MIT