@untangle-code/observability 0.0.0-stage → 0.1.1

package/NOTICE

@@ -0,0 +1,90 @@
+# NOTICE
+
+Copyright (C) 2026 Luke Bölling and contributors.
+
+This attribution covers original Untangle work. Contributors retain copyright in
+their contributions. Third-party packages, grammars and other materials retain
+their own copyright holders, licenses and notices; this line does not replace them.
+
+## License — binding decision
+
+Untangle is licensed under the **GNU Affero General Public License, Version 3
+(AGPL-3.0-only)**. See [`LICENSE`](./LICENSE).
+
+This decision is **final, not provisional**, and was explicitly instructed by
+the project owner. No contributor, agent or tool may change it without a new
+explicit instruction.
+
+The repository-wide license covers Untangle's first-party source code, scripts,
+tests, fixtures, configuration, documentation, website and brand artwork, including
+the logo and 3D yarn illustrations. Every workspace `package.json` declares
+`"license": "AGPL-3.0-only"`. There is no separately licensed enterprise component
+or separate permissive license for documentation or brand assets.
+
+Third-party code, embedded grammars, dependency assets and their notices retain
+their original licenses. Their inclusion does not relicense those works. The
+repository license does not grant trademark rights or change the license of a
+repository analyzed with Untangle. See the repository's `docs/LICENSING.md` for
+scope and verification details.
+
+This resolves the license question left open in `vision.md` §14 and completes
+`product.md` §16, item 2.
+
+## Rationale
+
+- **Network copyleft fits the intended product model.** AGPL §13 sets source
+  availability requirements for modified versions used through a computer network.
+  The current local CLI/stdio-MCP entry and future shared-server modes share the
+  same license.
+- **Local-first analysis has a clear boundary.** Running Untangle against a codebase
+  does not replace that codebase's own license with Untangle's license.
+- **First-party components share one license.** Implemented components and future
+  official plugins use this repository's licensing policy. Planned integrations do
+  not establish implemented or published products.
+
+## Deliberately accepted consequence
+
+The project deliberately chooses AGPL rather than a permissive embedding license.
+Redistribution, modifications and combined works must be assessed against the
+actual terms in `LICENSE`, including applicable Corresponding Source requirements.
+No permissive exception, commercial dual license or special contract-only package
+license is granted or promised by this notice.
+
+## Dependencies
+
+Third-party runtime dependencies are checked against the allowlist in
+`scripts/check-licenses.mjs`. Their licenses and copyright notices remain unchanged
+and traceable through package `THIRD_PARTY_LICENSES.md` files, grammar provenance,
+the lockfile and release SBOM. The allowlist includes MIT / Apache-2.0 / BSD / ISC
+and other explicitly listed licenses; it is not a license grant for dependencies.
+
+The allowlist in `scripts/check-licenses.mjs` applies to **dependencies**, not
+workspace packages. Untangle's own packages carry AGPL-3.0-only and are excluded
+from that check.
+
+## Clean room
+
+Untangle is an independent implementation with its own data models, APIs, tool
+names, tests and sources. Feature ideas may be derived from publicly observable
+behavior and generally known techniques. Third-party source code is not copied,
+including from AGPL projects even where the license would permit it.
+
+## Contribution terms
+
+Pull requests are welcome under the repository's existing AGPL-3.0-only license.
+No separate CLA, copyright assignment or DCO sign-off is required. Contributors
+must have the right to submit their work under those terms. See CONTRIBUTING.md.
+
+## Release decisions
+
+- [x] Copyright attribution: Luke Bölling, with contributors retaining their rights.
+- [x] Contributions use AGPL-3.0-only without an additional CLA or DCO gate.
+
+## Open legal items before public beta
+
+- [ ] Trademark search for the product name `Untangle`.
+- [ ] Registration and legal review of the npm scope `@untangle-code`.
+- [ ] Verify source availability and notices for each released network daemon/server
+  mode (WP-59). The current stdio MCP `untangle_about` already reports the license,
+  source repository and build commit when supplied; metadata alone does not prove
+  that a concrete deployed version's source is available.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @untangle-code/observability
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An internal private package, not published to npm. It builds error, logging, redaction,
+correlation, metric and profiling components on `@untangle-code/domain`. Its only direct I/O is
+`process.stderr` for logging and `process.memoryUsage()` for profiling; no network or filesystem.
+
+Normative sources: [`spec.md`](../../spec.md) §23 (health/observability), §24 (security/privacy),
+§25.1 (error classes), taking precedence in conflicts; [`architecture.md`](../../architecture.md)
+§22 (error architecture) and §24 (observability).
+
+Every exported domain type (`UntangleError`, `ErrorCode`, `ERROR_CODES`, `LoggerPort`, `LogEvent`,
+`LogLevel`, `Clock`, `Random`, `ToolResponseEnvelopeV1`, …) is imported from
+`@untangle-code/domain`, never redefined locally.
+
+<a id="modulübersicht-alles-re-exportiert-aus-srcindexts"></a>
+
+## Modules (all re-exported from `src/index.ts`)
+
+| Module | Contents | Normative source |
+|---|---|---|
+| `errors.ts` | `ERROR_FACTORIES` (one factory per `ErrorCode`, generated from `ERROR_CODES`) and 28 named convenience exports (`configInvalidError`, `lockHeldError`, …); `toErrorEnvelope(error)` maps **any** thrown value to `ToolResponseEnvelopeV1.error`; domain re-exports `UntangleError`, `ErrorCode`, `ERROR_CODES`, `isUntangleError`, `isErrorCode` | spec §25.1, §21.2; portfolio §15; arch §22.1 |
+| `redact.ts` | Pure `redact(value, options?)`, recursive over objects/arrays; masks known secret keys and secret-like values, suppresses source fields by default (opt in through `includeSourceText`) | spec §24, §23.2 |
+| `correlation.ts` | `createRequestContext({ clock, random })`, IDs exclusively through injected `Clock`/`Random` ports | arch §24.1 |
+| `logger.ts` | `createLogger(options): Logger`, implementing `LoggerPort`: stderr JSON lines, level filtering, `child()` with inherited context, automatic redaction before writing | arch §24.2 |
+| `metrics.ts` | `MetricsRegistry`, exactly the 11 counters from spec §23.3 (8 counters, 1 histogram, 2 ratio gauges); pure-object `snapshot()` | spec §23.3 |
+| `profiling.ts` | `ProfileCollector`: stage timing through injected `Clock`, file counts, cache-hit rates, embedding/Qdrant latency and bytes, parser/language breakdown, memory high-water mark through `process.memoryUsage()` | arch §24.3 |
+
+<a id="verwendung-durch-andere-packages"></a>
+
+## Use by other packages
+
+- **core-engine** throws `UntangleError` using `*Error` factories at adapter boundaries and builds
+  `ToolResponseEnvelopeV1.error` through `toErrorEnvelope()`.
+- **cli/mcp-server** create a `RequestContext` (`createRequestContext`) and child logger
+  (`logger.child({ requestId, workspaceId, … })`) per tool invocation for the operation's lifetime.
+- **index-pipeline** increments `MetricsRegistry` counters during scanning/chunking and populates
+  a `ProfileCollector` with `--profile`.
+
+<a id="entscheidungen"></a>
+
+## Decisions
+
+Choices left open by spec.md/architecture.md; additive extensions are welcome, local redefinitions are not:
+
+1. **`toErrorEnvelope()` for non-`UntangleError` values.** spec.md §21.2 defines the error shape,
+   not behavior for raw `Error`, string or object throws. Such values receive
+   `code: "UNKNOWN_ERROR"` (exported as `UNKNOWN_ERROR_CODE`) and `retryable: false`, never one of
+   the 28 known `ErrorCode` values. Spec §25.2 forbids equating absence and infrastructure failure,
+   and a raw `Error` cannot be safely assigned to either. Envelope `error.code` is specified as
+   `string`, not `ErrorCode`, so this conforms to the spec.
+2. **Generated factory map rather than 28 handwritten classes.** `ERROR_FACTORIES` derives from
+   domain's `ERROR_CODES`, so factories cannot diverge from the code list. The 28 named exports
+   (`configInvalidError`, …) alias map entries rather than provide another source of truth.
+3. **Correlation IDs beyond `requestId`/`jobId` belong in `context`.** Domain's fixed `LogEvent`
+   (architecture.md §24.2) has only these two top-level fields. `generationId`, `workspaceId`,
+   `repoId`, `refId` from §24.1 have no dedicated slots and enter `context` under those names through
+   `logger.child({...})`; the nearer `child()` wins collisions. This does not break or extend the
+   domain-pinned `LogEvent` shape.
+4. **`createRequestContext()` creates only `requestId`.** `jobId`/`generationId` belong to the
+   subsystem actually starting a job/generation (job engine/index pipeline), not blind advance
+   generation without an existing job. Those subsystems should use the same injected `Random`
+   (`random.uuid()`) once built. `workspaceId`/`repoId`/`refId` are content-addressed domain
+   identities (`buildWorkspaceId` etc.), not random IDs; callers attach them to request context.
+5. **Three metric kinds, not two.** Spec §23.3 calls all eleven names counters, but
+   `search_latency_ms` is a distribution (histogram), and
+   `resolved_import_ratio`/`resolved_call_ratio` are snapshot ratios, not monotonic counts. A true
+   counter would misrepresent them. The remaining eight are cumulative counters. The name set
+   stays exactly the eleven from spec §23.3 and cannot be extended with new names.
+6. **Redaction-key and source-field lists are local choices, not normatively prescribed.**
+   Spec §24 lists apiKey, token, password, authorization, cookie as examples and generally requires
+   no unsolicited logging of secrets or complete source. `SECRET_KEY_PATTERN` and
+   `SOURCE_TEXT_KEYS` (mirroring `CodeChunkPayloadV1`/`CodeChunkDraft`) are additive WP-04 choices.
+   Later packages with more secret/source fields should extend these lists rather than implement
+   another redactor.
+7. **`Logger` is a superset of domain's `LoggerPort`.** `Logger extends LoggerPort` adds
+   `error()/warn()/info()/debug()/trace()` convenience methods that obtain timestamps from injected
+   `Clock`. Domain's `log(event: LogEvent)` remains the low-level interface, used internally by
+   convenience methods; every `createLogger()` instance stays fully `LoggerPort`-conformant.
+8. **Redaction runs inside the logger, not at call sites.** `createLogger()` automatically applies
+   `redact()` to every `context` before writing, so callers need not remember it.
+   `debugIncludeSourceText` defaults to `false` and provides spec §24's explicit opt-in exception
+   for source fields; secret keys remain masked regardless.
+
+<a id="offene-punkte"></a>
+
+## Open issues
+
+- `docs/BUILD_PLAN.md` had not been created in this working directory when this package was built
+  (only spec.md, architecture.md, product.md, vision.md, portfolio.md existed). The package
+  therefore follows the requested spec.md §23/§25.1 and architecture.md §22/§24 only. A later
+  `docs/BUILD_PLAN.md` contract register should be checked against these decisions, not silently
+  overwrite them.
+- Root `tsconfig.json` reference orchestration is outside this package's ownership. The root owner
+  must add `{ "path": "packages/observability" }` to `references` for `tsc -b tsconfig.json` to
+  include it. Its own scripts (`pnpm --filter @untangle-code/observability run typecheck/test`)
+  are independent and pass.
+- No external metric exporter such as Prometheus: optional under spec §23.3 and deliberately
+  unbuilt. `snapshot()` returns a pure object callers can export themselves.
+
+<a id="lizenz"></a>
+
+## License
+
+
+**AGPL-3.0-only.** This package includes the complete license in [`LICENSE`](./LICENSE), the
+license-choice rationale in [`NOTICE`](./NOTICE), and licenses for all third-party production
+dependencies in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md). All three ship in the npm
+tarball: AGPL-3.0-only §4 and §5 require recipients to receive the license; a README alone is not
+a copy of the license.
+
+Local use alone does not trigger an obligation. Copyleft obligations apply to redistribution and
+providing a network service (AGPL §13).
+
+Corresponding TypeScript source ships under `src/` in the same tarball; the complete repository
+is available at <https://github.com/lboel/untangle>.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,24 @@
+# Third-party licenses — @untangle-code/observability
+
+Generated by `pnpm third-party-licenses` from this package's installed
+production dependency tree: transitive `dependencies`, across
+workspace edges, with no `devDependencies` included. The generator reads
+each resolved package's `package.json` in `node_modules`; nothing is maintained by hand
+or estimated.
+
+Do not edit manually: `pnpm third-party-licenses --check` fails on drift,
+and `pnpm check-publishable` rejects packages without a current file.
+
+This file exists because `docs/BUILD_PLAN.md`, risk R6, makes
+per-package `THIRD_PARTY_LICENSES.md` a release gate for npm publication.
+
+Untangle itself is **AGPL-3.0-only** (see `LICENSE` and `NOTICE` in
+this package). The packages below are third-party works; their own
+licenses and copyright notices continue to apply unchanged. Workspace
+packages (`@untangle-code/*`) are not listed here; they belong to the same
+work and use the same AGPL-3.0-only license.
+
+## Result: no third-party dependencies
+
+This package has no production dependencies outside the workspace.
+The list is empty because none exist, not because they were not checked.

package/dist/correlation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Correlation ids (architecture.md §24.1).
+ *
+ * Ids are drawn exclusively from the injected `Clock`/`Random` ports so that
+ * request contexts are reproducible in tests — never `Date.now()` or
+ * `Math.random()` (BUILD_PLAN global determinism rule).
+ *
+ * `request_id` is the only id created here. `job_id` and `generation_id`
+ * are owned by the subsystems that create the underlying job/generation
+ * (job-engine, index pipeline) — they mint them the same way, via
+ * `Random.uuid()`, once those packages exist; minting them here would just
+ * move the decision of *when* a job/generation begins out of its owner.
+ * `workspace_id`/`repo_id`/`ref_id` are never random — they are the
+ * content-derived identities `@untangle-code/domain` already builds
+ * (`buildWorkspaceId` et al.) and are attached to a request context by the
+ * caller, not generated by observability.
+ */
+import type { Clock, Random } from "@untangle-code/domain";
+export interface RequestContextDeps {
+    clock: Clock;
+    random: Random;
+}
+export interface RequestContext {
+    /** Random per-operation id (architecture.md §24.1: `request_id`). */
+    requestId: string;
+    /** Epoch-ms creation time, via `Clock` — never `Date.now()`. */
+    createdAtEpochMs: number;
+    /** ISO-8601 creation time, via `Clock`. */
+    createdAtIso: string;
+}
+/**
+ * Creates a fresh request context. Deterministic given a deterministic
+ * `Clock`/`Random` (e.g. in tests): same fakes in, same ids out.
+ */
+export declare function createRequestContext(deps: RequestContextDeps): RequestContext;
+//# sourceMappingURL=correlation.d.ts.map

package/dist/correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,CAM7E"}

package/dist/correlation.js

@@ -0,0 +1,12 @@
+/**
+ * Creates a fresh request context. Deterministic given a deterministic
+ * `Clock`/`Random` (e.g. in tests): same fakes in, same ids out.
+ */
+export function createRequestContext(deps) {
+    return {
+        requestId: deps.random.uuid(),
+        createdAtEpochMs: deps.clock.nowEpochMs(),
+        createdAtIso: deps.clock.nowIso(),
+    };
+}
+//# sourceMappingURL=correlation.js.map

package/dist/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAiCA;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAC7B,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE;QACzC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;KAClC,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Typed error helpers on top of `@untangle-code/domain`'s `UntangleError`
+ * (architecture.md §22.1, spec.md §25.1, portfolio.md §15).
+ *
+ * `UntangleError`, `ErrorCode`, `ERROR_CODES` and `isUntangleError` are
+ * already fully defined in domain (BUILD_PLAN §3 contract register) — this
+ * module does not redefine them, only adds:
+ *
+ * - one factory function per error class (`ERROR_FACTORIES`, plus a named
+ *   export per code for ergonomic call sites), and
+ * - `toErrorEnvelope()`, which turns *any* thrown value into the `error`
+ *   field shape of `ToolResponseEnvelopeV1` (spec.md §21.2), including
+ *   values that are not `UntangleError` at all (adapter throws, programmer
+ *   errors) so that MCP/CLI response building never has to branch on the
+ *   error's runtime type itself.
+ */
+import { UntangleError, type ErrorCode, type ToolResponseEnvelopeV1, type UntangleErrorOptions } from "@untangle-code/domain";
+export { ERROR_CODES, CORE_ERROR_CODES, PORTFOLIO_ERROR_CODES, STORAGE_ERROR_CODES, isErrorCode, isUntangleError, UntangleError, } from "@untangle-code/domain";
+export type { ErrorCode, UntangleErrorOptions } from "@untangle-code/domain";
+/** Envelope `error` field shape (spec.md §21.2), derived from domain's envelope type. */
+export type EnvelopeErrorV1 = NonNullable<ToolResponseEnvelopeV1<unknown>["error"]>;
+/** Code used for `toErrorEnvelope()` when the input is not an `UntangleError`. */
+export declare const UNKNOWN_ERROR_CODE = "UNKNOWN_ERROR";
+export type ErrorFactory = (message: string, options?: UntangleErrorOptions) => UntangleError;
+/**
+ * One factory per {@link ErrorCode} (spec.md §25.1 ∪ portfolio.md §15).
+ *
+ * Built from `ERROR_CODES` itself so this map can never drift out of sync
+ * with domain's code list — see `errors.test.ts` for the completeness check.
+ */
+export declare const ERROR_FACTORIES: Readonly<Record<ErrorCode, ErrorFactory>>;
+export declare const configInvalidError: ErrorFactory;
+export declare const workspaceNotFoundError: ErrorFactory;
+export declare const pathOutsideWorkspaceError: ErrorFactory;
+export declare const parserUnavailableError: ErrorFactory;
+export declare const embeddingUnavailableError: ErrorFactory;
+export declare const embeddingDimensionMismatchError: ErrorFactory;
+export declare const qdrantUnavailableError: ErrorFactory;
+export declare const qdrantSchemaIncompatibleError: ErrorFactory;
+export declare const lanceDbUnavailableError: ErrorFactory;
+export declare const lanceDbSchemaIncompatibleError: ErrorFactory;
+export declare const indexIncompleteError: ErrorFactory;
+export declare const indexProfileMismatchError: ErrorFactory;
+export declare const lockHeldError: ErrorFactory;
+export declare const jobCancelledError: ErrorFactory;
+export declare const graphIncompleteError: ErrorFactory;
+export declare const analysisIncompleteError: ErrorFactory;
+export declare const pointTooLargeError: ErrorFactory;
+export declare const pluginEngineIncompatibleError: ErrorFactory;
+export declare const portfolioIncompleteError: ErrorFactory;
+export declare const portfolioGenerationMissingError: ErrorFactory;
+export declare const portfolioStaleError: ErrorFactory;
+export declare const manifestParseFailedError: ErrorFactory;
+export declare const technologyUnknownError: ErrorFactory;
+export declare const blueprintKindUnknownError: ErrorFactory;
+export declare const blueprintEvidenceInsufficientError: ErrorFactory;
+export declare const blueprintTargetNotEmptyError: ErrorFactory;
+export declare const blueprintTargetOutsideAllowedError: ErrorFactory;
+export declare const blueprintWriteFailedError: ErrorFactory;
+export declare const enrichmentDisabledError: ErrorFactory;
+export declare const enrichmentUnavailableError: ErrorFactory;
+/**
+ * Turns any thrown value into the `error` field of `ToolResponseEnvelopeV1`
+ * (spec.md §21.2).
+ *
+ * - An `UntangleError` round-trips through its own `toEnvelopeError()`.
+ * - A plain `Error` (adapter throw, programmer error) is mapped to
+ *   {@link UNKNOWN_ERROR_CODE} with `retryable: false` — never silently
+ *   promoted to a known {@link ErrorCode}, since "not found" and
+ *   "infrastructure failure" must never be conflated (spec.md §25.2).
+ * - Any other thrown value is stringified the same way.
+ */
+export declare function toErrorEnvelope(error: unknown): EnvelopeErrorV1;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAEL,aAAa,EAEb,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7E,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEpF,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,aAAa,CAAC;AAO9F;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAKrE,CAAC;AAGF,eAAO,MAAM,kBAAkB,cAAiC,CAAC;AACjE,eAAO,MAAM,sBAAsB,cAAsC,CAAC;AAC1E,eAAO,MAAM,yBAAyB,cAAyC,CAAC;AAChF,eAAO,MAAM,sBAAsB,cAAqC,CAAC;AACzE,eAAO,MAAM,yBAAyB,cAAwC,CAAC;AAC/E,eAAO,MAAM,+BAA+B,cAA+C,CAAC;AAC5F,eAAO,MAAM,sBAAsB,cAAqC,CAAC;AACzE,eAAO,MAAM,6BAA6B,cAA6C,CAAC;AACxF,eAAO,MAAM,uBAAuB,cAAsC,CAAC;AAC3E,eAAO,MAAM,8BAA8B,cAA8C,CAAC;AAC1F,eAAO,MAAM,oBAAoB,cAAmC,CAAC;AACrE,eAAO,MAAM,yBAAyB,cAAyC,CAAC;AAChF,eAAO,MAAM,aAAa,cAA4B,CAAC;AACvD,eAAO,MAAM,iBAAiB,cAAgC,CAAC;AAC/D,eAAO,MAAM,oBAAoB,cAAmC,CAAC;AACrE,eAAO,MAAM,uBAAuB,cAAsC,CAAC;AAC3E,eAAO,MAAM,kBAAkB,cAAkC,CAAC;AAClE,eAAO,MAAM,6BAA6B,cAA6C,CAAC;AAGxF,eAAO,MAAM,wBAAwB,cAAuC,CAAC;AAC7E,eAAO,MAAM,+BAA+B,cAA+C,CAAC;AAC5F,eAAO,MAAM,mBAAmB,cAAkC,CAAC;AACnE,eAAO,MAAM,wBAAwB,cAAwC,CAAC;AAC9E,eAAO,MAAM,sBAAsB,cAAqC,CAAC;AACzE,eAAO,MAAM,yBAAyB,cAAyC,CAAC;AAChF,eAAO,MAAM,kCAAkC,cAAkD,CAAC;AAClG,eAAO,MAAM,4BAA4B,cAA6C,CAAC;AACvF,eAAO,MAAM,kCAAkC,cAAmD,CAAC;AACnG,eAAO,MAAM,yBAAyB,cAAyC,CAAC;AAChF,eAAO,MAAM,uBAAuB,cAAsC,CAAC;AAC3E,eAAO,MAAM,0BAA0B,cAAyC,CAAC;AAEjF;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAiB/D"}

package/dist/errors.js

@@ -0,0 +1,100 @@
+/**
+ * Typed error helpers on top of `@untangle-code/domain`'s `UntangleError`
+ * (architecture.md §22.1, spec.md §25.1, portfolio.md §15).
+ *
+ * `UntangleError`, `ErrorCode`, `ERROR_CODES` and `isUntangleError` are
+ * already fully defined in domain (BUILD_PLAN §3 contract register) — this
+ * module does not redefine them, only adds:
+ *
+ * - one factory function per error class (`ERROR_FACTORIES`, plus a named
+ *   export per code for ergonomic call sites), and
+ * - `toErrorEnvelope()`, which turns *any* thrown value into the `error`
+ *   field shape of `ToolResponseEnvelopeV1` (spec.md §21.2), including
+ *   values that are not `UntangleError` at all (adapter throws, programmer
+ *   errors) so that MCP/CLI response building never has to branch on the
+ *   error's runtime type itself.
+ */
+import { ERROR_CODES, UntangleError, isUntangleError, } from "@untangle-code/domain";
+export { ERROR_CODES, CORE_ERROR_CODES, PORTFOLIO_ERROR_CODES, STORAGE_ERROR_CODES, isErrorCode, isUntangleError, UntangleError, } from "@untangle-code/domain";
+/** Code used for `toErrorEnvelope()` when the input is not an `UntangleError`. */
+export const UNKNOWN_ERROR_CODE = "UNKNOWN_ERROR";
+function factory(code) {
+    return (message, options) => new UntangleError(code, message, options);
+}
+/**
+ * One factory per {@link ErrorCode} (spec.md §25.1 ∪ portfolio.md §15).
+ *
+ * Built from `ERROR_CODES` itself so this map can never drift out of sync
+ * with domain's code list — see `errors.test.ts` for the completeness check.
+ */
+export const ERROR_FACTORIES = Object.freeze(Object.fromEntries(ERROR_CODES.map((code) => [code, factory(code)])));
+// Named convenience exports — one per error class (spec.md §25.1).
+export const configInvalidError = ERROR_FACTORIES.CONFIG_INVALID;
+export const workspaceNotFoundError = ERROR_FACTORIES.WORKSPACE_NOT_FOUND;
+export const pathOutsideWorkspaceError = ERROR_FACTORIES.PATH_OUTSIDE_WORKSPACE;
+export const parserUnavailableError = ERROR_FACTORIES.PARSER_UNAVAILABLE;
+export const embeddingUnavailableError = ERROR_FACTORIES.EMBEDDING_UNAVAILABLE;
+export const embeddingDimensionMismatchError = ERROR_FACTORIES.EMBEDDING_DIMENSION_MISMATCH;
+export const qdrantUnavailableError = ERROR_FACTORIES.QDRANT_UNAVAILABLE;
+export const qdrantSchemaIncompatibleError = ERROR_FACTORIES.QDRANT_SCHEMA_INCOMPATIBLE;
+export const lanceDbUnavailableError = ERROR_FACTORIES.LANCEDB_UNAVAILABLE;
+export const lanceDbSchemaIncompatibleError = ERROR_FACTORIES.LANCEDB_SCHEMA_INCOMPATIBLE;
+export const indexIncompleteError = ERROR_FACTORIES.INDEX_INCOMPLETE;
+export const indexProfileMismatchError = ERROR_FACTORIES.INDEX_PROFILE_MISMATCH;
+export const lockHeldError = ERROR_FACTORIES.LOCK_HELD;
+export const jobCancelledError = ERROR_FACTORIES.JOB_CANCELLED;
+export const graphIncompleteError = ERROR_FACTORIES.GRAPH_INCOMPLETE;
+export const analysisIncompleteError = ERROR_FACTORIES.ANALYSIS_INCOMPLETE;
+export const pointTooLargeError = ERROR_FACTORIES.POINT_TOO_LARGE;
+export const pluginEngineIncompatibleError = ERROR_FACTORIES.PLUGIN_ENGINE_INCOMPATIBLE;
+// Named convenience exports — one per error class (portfolio.md §15).
+export const portfolioIncompleteError = ERROR_FACTORIES.PORTFOLIO_INCOMPLETE;
+export const portfolioGenerationMissingError = ERROR_FACTORIES.PORTFOLIO_GENERATION_MISSING;
+export const portfolioStaleError = ERROR_FACTORIES.PORTFOLIO_STALE;
+export const manifestParseFailedError = ERROR_FACTORIES.MANIFEST_PARSE_FAILED;
+export const technologyUnknownError = ERROR_FACTORIES.TECHNOLOGY_UNKNOWN;
+export const blueprintKindUnknownError = ERROR_FACTORIES.BLUEPRINT_KIND_UNKNOWN;
+export const blueprintEvidenceInsufficientError = ERROR_FACTORIES.BLUEPRINT_EVIDENCE_INSUFFICIENT;
+export const blueprintTargetNotEmptyError = ERROR_FACTORIES.BLUEPRINT_TARGET_NOT_EMPTY;
+export const blueprintTargetOutsideAllowedError = ERROR_FACTORIES.BLUEPRINT_TARGET_OUTSIDE_ALLOWED;
+export const blueprintWriteFailedError = ERROR_FACTORIES.BLUEPRINT_WRITE_FAILED;
+export const enrichmentDisabledError = ERROR_FACTORIES.ENRICHMENT_DISABLED;
+export const enrichmentUnavailableError = ERROR_FACTORIES.ENRICHMENT_UNAVAILABLE;
+/**
+ * Turns any thrown value into the `error` field of `ToolResponseEnvelopeV1`
+ * (spec.md §21.2).
+ *
+ * - An `UntangleError` round-trips through its own `toEnvelopeError()`.
+ * - A plain `Error` (adapter throw, programmer error) is mapped to
+ *   {@link UNKNOWN_ERROR_CODE} with `retryable: false` — never silently
+ *   promoted to a known {@link ErrorCode}, since "not found" and
+ *   "infrastructure failure" must never be conflated (spec.md §25.2).
+ * - Any other thrown value is stringified the same way.
+ */
+export function toErrorEnvelope(error) {
+    if (isUntangleError(error)) {
+        return error.toEnvelopeError();
+    }
+    if (error instanceof Error) {
+        return {
+            code: UNKNOWN_ERROR_CODE,
+            message: error.message,
+            retryable: false,
+            details: { name: error.name },
+        };
+    }
+    return {
+        code: UNKNOWN_ERROR_CODE,
+        message: typeof error === "string" ? error : safeStringify(error),
+        retryable: false,
+    };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @untangle-code/observability — the only public export of this package.
+ *
+ * Errors (architecture.md §22.1), structured logging (§24.2), redaction
+ * (spec.md §24), correlation ids (§24.1), metrics (spec.md §23.3) and
+ * `--profile` collection (architecture.md §24.3). No I/O beyond
+ * `process.stderr`/`process.memoryUsage`; no network, no filesystem.
+ */
+export * from "./errors.js";
+export * from "./redact.js";
+export * from "./correlation.js";
+export * from "./logger.js";
+export * from "./metrics.js";
+export * from "./profiling.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,aAAa,CAAC;AAG5B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,aAAa,CAAC;AAG5B,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @untangle-code/observability — the only public export of this package.
+ *
+ * Errors (architecture.md §22.1), structured logging (§24.2), redaction
+ * (spec.md §24), correlation ids (§24.1), metrics (spec.md §23.3) and
+ * `--profile` collection (architecture.md §24.3). No I/O beyond
+ * `process.stderr`/`process.memoryUsage`; no network, no filesystem.
+ */
+// Errors — factories on top of domain's UntangleError, plus envelope mapping.
+export * from "./errors.js";
+// Redaction.
+export * from "./redact.js";
+// Correlation ids.
+export * from "./correlation.js";
+// Structured logger (LoggerPort implementation).
+export * from "./logger.js";
+// Metrics registry (spec.md §23.3).
+export * from "./metrics.js";
+// Profiling collector (architecture.md §24.3).
+export * from "./profiling.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,cAAc,aAAa,CAAC;AAE5B,aAAa;AACb,cAAc,aAAa,CAAC;AAE5B,mBAAmB;AACnB,cAAc,kBAAkB,CAAC;AAEjC,iDAAiD;AACjD,cAAc,aAAa,CAAC;AAE5B,oCAAoC;AACpC,cAAc,cAAc,CAAC;AAE7B,+CAA+C;AAC/C,cAAc,gBAAgB,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Structured logger (architecture.md §24.2) implementing domain's
+ * `LoggerPort`: JSON lines on stderr, level filtering, and a child logger
+ * with bound context.
+ *
+ * `LogEvent` (architecture.md §24.2, fixed in domain) only carries
+ * `requestId`/`jobId` as first-class correlation fields; `generationId`,
+ * `workspaceId`, `repoId` and `refId` (architecture.md §24.1's full
+ * correlation set) have no first-class slot in that shape. This module's
+ * decision (README "Entscheidungen"): those four travel inside `context`
+ * under their own keys, merged in the same way `context` itself is —
+ * closest (call-site) binding wins over an ancestor `child()`'s binding.
+ */
+import type { Clock, LoggerPort, LogLevel } from "@untangle-code/domain";
+/** Bindings a child logger merges into every event it emits. */
+export interface LoggerBindings {
+    component?: string;
+    requestId?: string;
+    jobId?: string;
+    generationId?: string;
+    workspaceId?: string;
+    repoId?: string;
+    refId?: string;
+    context?: Record<string, unknown>;
+}
+/** `LoggerPort` plus per-level convenience methods that fill in `timestamp` via `Clock`. */
+export interface Logger extends LoggerPort {
+    error(event: string, context?: Record<string, unknown>): void;
+    warn(event: string, context?: Record<string, unknown>): void;
+    info(event: string, context?: Record<string, unknown>): void;
+    debug(event: string, context?: Record<string, unknown>): void;
+    trace(event: string, context?: Record<string, unknown>): void;
+    child(bindings: LoggerBindings): Logger;
+}
+export interface CreateLoggerOptions {
+    /** Time source for auto-timestamped convenience methods (`info()`, …). Never `Date.now()`. */
+    clock: Clock;
+    /** Minimum level emitted; events below it are dropped without touching `sink`. Default `"info"`. */
+    level?: LogLevel;
+    /** Where a finished JSON line is written. Default: one `process.stderr.write` call per event. */
+    sink?: (line: string) => void;
+    /**
+     * Opt-in escape hatch (spec.md §24): when `false` (default), source-text
+     * fields in `context` are suppressed rather than logged verbatim.
+     */
+    debugIncludeSourceText?: boolean;
+    /** Initial bound context, equivalent to calling `.child(bindings)` once up front. */
+    bindings?: LoggerBindings;
+}
+/** Creates a structured, JSON-lines-on-stderr {@link Logger} (architecture.md §24.2). */
+export declare function createLogger(options: CreateLoggerOptions): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAY,UAAU,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAYnF,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,4FAA4F;AAC5F,MAAM,WAAW,MAAO,SAAQ,UAAU;IACxC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,8FAA8F;IAC9F,KAAK,EAAE,KAAK,CAAC;IACb,oGAAoG;IACpG,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,iGAAiG;IACjG,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAyHD,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAQjE"}