@nodii/telemetry 0.0.1 → 0.1.1

package/README.md

@@ -1,5 +1,227 @@
 # @nodii/telemetry
 
-Placeholder package at v0.0.1. Implementation lands at v0.1.0 per the locked feature_doc.
+Substrate observability library for the Nodii microservice stack. v0.1.0
+ships the SDK surface — bootstrap, log envelope, tracer, meter, audit
+signal, intent lifecycle, agent registry, context propagation — without
+the OTel-SDK wiring (deferred to a v0.1.x follow-up; see
+`.agent-todo.md` TS-12).
 
 **Spec**: `https://planning.dev.nucleus-cloud.in/api/v1/feature-docs?serviceId=nodii-libs&docKey=telemetry`
+
+## Install
+
+```sh
+bun add @nodii/telemetry
+```
+
+## Bootstrap (D152)
+
+```ts
+import { initTelemetry } from "@nodii/telemetry";
+
+initTelemetry({
+  serviceName: "nodii-billing-service",
+  env: process.env.APPLICATION_STATE!, // 'dev' | 'uat' | 'prod'
+  otlpEndpoint: process.env.OTLP_ENDPOINT,
+  vocabularyRegistry: {
+    billing_payments_total: {
+      family: "async_worker",
+      description: "Payments processed",
+      decision: "D23",
+    },
+  },
+  intentTypes: {
+    "billing.invoice.create": {
+      typeName: "billing.invoice.create",
+      server_mintable: true,
+      client_mintable: false,
+      timeout_seconds: 300,
+    },
+  },
+});
+```
+
+Subsequent `initTelemetry()` calls warn-log + no-op. Calling any public
+API before init throws `TelemetryNotInitialized`.
+
+## Logger (D13)
+
+```ts
+import { logger } from "@nodii/telemetry";
+
+logger.info("payment.charged", { invoice_id, amount_minor_units });
+logger.error("saga.compensation.failed", { saga_id, step, reason });
+```
+
+The 11-field envelope (`level, ts, msg, service, env, tenant_id,
+user_id, request_id, trace_id, span_id, intent_id`) is auto-attached
+from the active `NodiiContext` + the init config + the active OTel
+span. **Do not pass envelope fields yourself** — they get filled in.
+
+D15 redaction runs on every line (structured-field keys against the D2
+PII list + regex pass on the message string) and is **fail-closed**:
+if redaction throws, the line is DROPPED and
+`telemetry.sdk.redaction_failure_total{reason}` bumps.
+
+## Tracer (D26 / D27 / D28)
+
+```ts
+import { tracer, withSpanAttributes } from "@nodii/telemetry";
+
+await withSpanAttributes({ invoice_id }, async () => {
+  await tracer.span("billing.invoice.create", async (span) => {
+    span.setAttribute("payment.method", method);
+    // ... business logic; mandatory attrs auto-applied
+  });
+});
+```
+
+Mandatory attributes (`tenant_id, request_id, intent_id`) are stamped
+on span start. 4 KB per-value cap with `_truncated=true` marker. D27
+status mapping: `recordException` auto-pairs with `ERROR`; clean
+return defaults to `OK`.
+
+## Metrics (D18 / D19 / D20 / D24)
+
+```ts
+import { metrics } from "@nodii/telemetry";
+
+const paymentsCounter = metrics.counter("billing_payments_total", {
+  family: "async_worker",
+  description: "Payments processed",
+});
+paymentsCounter.inc({ tenant_id, pgw, status });
+```
+
+Names must exist in the vocabulary registry passed to
+`initTelemetry({ vocabularyRegistry })` — D24 ADR-gated. Mismatched
+family or off-vocab name → `MetricVocabularyError` + bumps
+`telemetry.sdk.cardinality_rejected_total{family, reason}`.
+
+D20 bare-label discipline: registration rejects `tenant.id` and
+`tenantId` variants.
+
+D19: exponential histograms, max 160 buckets.
+
+## Audit (D17 / D33)
+
+```ts
+import { audit } from "@nodii/telemetry";
+
+await audit.emit({
+  action: "payment.refund.issued",
+  target_kind: "payment",
+  target_id: payment.id,
+  payload: { amount_minor_units, reason },
+});
+```
+
+The library ships the adapter (write path); the emission policy
+(method-level interceptor, saga lifecycle events, agent-layer
+double-emission) and the `audit_log` schema live in the audit
+doctrine + each consuming service.
+
+## Intent lifecycle (D46 / D155)
+
+```ts
+import { intent } from "@nodii/telemetry";
+
+const id = await intent.begin("billing.invoice.create", { invoice_id });
+try {
+  // work
+  await intent.complete(id, { result: "ok" });
+} catch (err) {
+  await intent.abandon(id, "error");
+  throw err;
+}
+```
+
+`intent.begin` HARD-validates the type name against the registry
+(D155); unknown type → `IntentTypeNotRegistered`. Activates the intent
+on the active `NodiiContext` (sets `intent_id`). Nested begins stack
+by id match.
+
+`intent.progress` is a no-op stub at v0.1.0 per D155 § M02
+carry-forward.
+
+## @agentInvocable (D156)
+
+```ts
+import { agentInvocable } from "@nodii/telemetry";
+
+class PaymentService {
+  @agentInvocable({
+    mode: "composable",
+    authTier: "confirmation-required",
+    sideEffects: ["payment.refund"],
+    idempotency: "keyed-by-request-id",
+    description: "Refund a captured payment",
+  })
+  async refundPayment(req: RefundRequest): Promise<RefundResult> {
+    /* ... */
+  }
+}
+```
+
+Runtime is a no-op at v0.1.0 (D156). The decorator attaches the
+config to the method + the class prototype under a symbol-keyed
+property; the build-time codegen (separate tool, deferred) walks the
+tsc AST + falls back to the runtime registry to emit
+`agent-methods.generated.json`.
+
+## Context propagation (D40 / D41)
+
+```ts
+import {
+  type NodiiContext,
+  withContext,
+  getContext,
+  requireContext,
+} from "@nodii/telemetry";
+
+const ctx: NodiiContext = {
+  tenant_id: "...",
+  user_id: "...",
+  actor_type: "user",
+  on_behalf_of: null,
+  role: "owner",
+  request_id: "...",
+  intent_id: null,
+};
+await withContext(ctx, async () => {
+  /* every log / span / metric / audit emit picks up this context */
+});
+```
+
+Read with `getContext()` (returns null when no scope active) or
+`requireContext()` (throws). SDK middleware adapters (deferred to
+TS-9) are the ONLY writers of the parent-scope context per D41 lock;
+service code uses `withContext` for child scopes only.
+
+## SDK-internal counters
+
+The library increments these on its own behaviors (do not register
+them in your vocabulary):
+
+- `telemetry.sdk.redaction_failure_total{reason}` — D15 fail-closed
+  drop.
+- `telemetry.sdk.cardinality_rejected_total{family, reason}` — D18.
+- `telemetry.sdk.export_failures_total{signal, reason}` — D153.
+- `telemetry.sdk.trace_propagation_missing_total` — § 5.9 D25.
+
+## Deferred to v0.1.x
+
+See `.agent-todo.md` at the repo root:
+
+- **TS-9**: Subpath adapters (`/grpc`, `/bullmq`, `/outbox`,
+  `/system-process`, `/lambda`).
+- **TS-12**: Real OTel SDK wiring — replaces the no-op
+  `SpanEmitter` + the default JSON log sink with the OTLP
+  exporters.
+- **TS-13**: Smoke service per D157 at `ts/telemetry-smoke/`.
+- **TS-14**: Telemetry-tax-budget benchmark (D28 ≤ 200µs SDK-side
+  per typical RPC).
+
+## License
+
+MIT

package/dist/active-span.d.ts

@@ -0,0 +1,12 @@
+export interface ActiveSpanRef {
+    trace_id: string;
+    span_id: string;
+}
+export type ActiveSpanGetter = () => ActiveSpanRef | null;
+/** SDK-internal: the tracer module installs this on initialization. */
+export declare function _setActiveSpanGetter(g: ActiveSpanGetter): void;
+/** Read the active span ids. Returns null when no span is active. */
+export declare function getActiveSpan(): ActiveSpanRef | null;
+/** Test-only reset. */
+export declare function _resetActiveSpanForTests(): void;
+//# sourceMappingURL=active-span.d.ts.map

package/dist/active-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-span.d.ts","sourceRoot":"","sources":["../src/active-span.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,aAAa,GAAG,IAAI,CAAC;AAI1D,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAE9D;AAED,qEAAqE;AACrE,wBAAgB,aAAa,IAAI,aAAa,GAAG,IAAI,CAEpD;AAED,uBAAuB;AACvB,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/active-span.js

@@ -0,0 +1,20 @@
+// Active-span hooks. The tracer (§ 5.3) registers a getter that returns
+// the current `{ trace_id, span_id }` pair, or null if no span is
+// active. The logger reads this on every log line so envelope fields
+// `trace_id` and `span_id` (D13) are auto-stamped without the logger
+// importing the tracer (avoids a cycle and lets the OTel wiring land
+// in TS-12 as a strict module-internal swap).
+let getter = () => null;
+/** SDK-internal: the tracer module installs this on initialization. */
+export function _setActiveSpanGetter(g) {
+    getter = g;
+}
+/** Read the active span ids. Returns null when no span is active. */
+export function getActiveSpan() {
+    return getter();
+}
+/** Test-only reset. */
+export function _resetActiveSpanForTests() {
+    getter = () => null;
+}
+//# sourceMappingURL=active-span.js.map

package/dist/active-span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-span.js","sourceRoot":"","sources":["../src/active-span.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,kEAAkE;AAClE,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,8CAA8C;AAS9C,IAAI,MAAM,GAAqB,GAAG,EAAE,CAAC,IAAI,CAAC;AAE1C,uEAAuE;AACvE,MAAM,UAAU,oBAAoB,CAAC,CAAmB;IACtD,MAAM,GAAG,CAAC,CAAC;AACb,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,EAAE,CAAC;AAClB,CAAC;AAED,uBAAuB;AACvB,MAAM,UAAU,wBAAwB;IACtC,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC;AACtB,CAAC"}

package/dist/agent-invocable.d.ts

@@ -0,0 +1,24 @@
+import { type AgentInvocableConfig } from "./types";
+export declare const AGENT_INVOCABLE_METADATA: unique symbol;
+/**
+ * Method decorator. TS legacy decorators are still the only widely
+ * deployed form for class methods; we attach metadata under a
+ * symbol-keyed property on the method itself + on the class prototype.
+ *
+ * Usage:
+ *
+ *   class PaymentService {
+ *     @agentInvocable({ mode: 'composable', authTier: 'confirmation-required',
+ *                       sideEffects: ['payment.refund'], idempotency: 'keyed-by-request-id',
+ *                       description: 'Refund a captured payment' })
+ *     async refundPayment(req) { ... }
+ *   }
+ */
+export declare function agentInvocable(cfg: AgentInvocableConfig): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Read the registry from a class. Used by tests + the codegen fallback
+ * (when AST discovery doesn't find a decorator, e.g. when the file was
+ * transformed by a different toolchain).
+ */
+export declare function readAgentRegistry<T extends object>(ctor: T): Record<string | symbol, AgentInvocableConfig>;
+//# sourceMappingURL=agent-invocable.d.ts.map

package/dist/agent-invocable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-invocable.d.ts","sourceRoot":"","sources":["../src/agent-invocable.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AAEjB,eAAO,MAAM,wBAAwB,eAEpC,CAAC;AAoBF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,oBAAoB,IAGpD,QAAQ,MAAM,EACd,aAAa,MAAM,GAAG,MAAM,EAC5B,YAAY,kBAAkB,KAC7B,kBAAkB,CAuBtB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,IAAI,EAAE,CAAC,GACN,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,oBAAoB,CAAC,CAM/C"}

package/dist/agent-invocable.js

@@ -0,0 +1,64 @@
+// `@agentInvocable` decorator per D156. Runtime no-op at v0.1.0 — the
+// agent dispatcher consumes the build-time codegen registry
+// (`agent-methods.generated.json`), not the runtime metadata.
+//
+// At v0.1.0 we attach the supplied config to the method's prototype
+// under a well-known symbol so the codegen step (a separate tsc AST
+// walk in TS-8 wave 2) can also discover registrations via runtime
+// import if it falls back from the AST path.
+import { AGENT_INVOCABLE_SIDE_EFFECTS, } from "./types";
+export const AGENT_INVOCABLE_METADATA = Symbol.for("@nodii/telemetry/agentInvocable");
+function validate(cfg) {
+    if (cfg.mode === "strict-only" && !cfg.allowedPipelines?.length) {
+        throw new Error("@agentInvocable: `allowedPipelines` is required when `mode = 'strict-only'`");
+    }
+    for (const eff of cfg.sideEffects) {
+        if (!AGENT_INVOCABLE_SIDE_EFFECTS.includes(eff)) {
+            throw new Error(`@agentInvocable: sideEffect '${eff}' is not in the locked vocabulary (D156).`);
+        }
+    }
+    if (!cfg.description) {
+        throw new Error("@agentInvocable: `description` is required");
+    }
+}
+/**
+ * Method decorator. TS legacy decorators are still the only widely
+ * deployed form for class methods; we attach metadata under a
+ * symbol-keyed property on the method itself + on the class prototype.
+ *
+ * Usage:
+ *
+ *   class PaymentService {
+ *     @agentInvocable({ mode: 'composable', authTier: 'confirmation-required',
+ *                       sideEffects: ['payment.refund'], idempotency: 'keyed-by-request-id',
+ *                       description: 'Refund a captured payment' })
+ *     async refundPayment(req) { ... }
+ *   }
+ */
+export function agentInvocable(cfg) {
+    validate(cfg);
+    return function decorate(target, propertyKey, descriptor) {
+        const original = descriptor.value;
+        if (typeof original !== "function") {
+            throw new Error("@agentInvocable can only be applied to methods (PropertyDescriptor.value must be a function).");
+        }
+        // Attach metadata to the method function itself.
+        original[AGENT_INVOCABLE_METADATA] =
+            cfg;
+        // Mirror onto a class-level registry under the same symbol.
+        const ctor = target.constructor;
+        const existing = ctor[AGENT_INVOCABLE_METADATA] ?? {};
+        existing[propertyKey] = cfg;
+        ctor[AGENT_INVOCABLE_METADATA] = existing;
+        return descriptor;
+    };
+}
+/**
+ * Read the registry from a class. Used by tests + the codegen fallback
+ * (when AST discovery doesn't find a decorator, e.g. when the file was
+ * transformed by a different toolchain).
+ */
+export function readAgentRegistry(ctor) {
+    return (ctor[AGENT_INVOCABLE_METADATA] ?? {});
+}
+//# sourceMappingURL=agent-invocable.js.map

package/dist/agent-invocable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-invocable.js","sourceRoot":"","sources":["../src/agent-invocable.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,4DAA4D;AAC5D,8DAA8D;AAC9D,EAAE;AACF,oEAAoE;AACpE,oEAAoE;AACpE,mEAAmE;AACnE,6CAA6C;AAE7C,OAAO,EACL,4BAA4B,GAE7B,MAAM,SAAS,CAAC;AAEjB,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,GAAG,CAChD,iCAAiC,CAClC,CAAC;AAEF,SAAS,QAAQ,CAAC,GAAyB;IACzC,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QAClC,IAAI,CAAC,4BAA4B,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CACb,gCAAgC,GAAG,2CAA2C,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,GAAyB;IACtD,QAAQ,CAAC,GAAG,CAAC,CAAC;IACd,OAAO,SAAS,QAAQ,CACtB,MAAc,EACd,WAA4B,EAC5B,UAA8B;QAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAC;QACJ,CAAC;QACD,iDAAiD;QAChD,QAA+C,CAAC,wBAAwB,CAAC;YACxE,GAAG,CAAC;QACN,4DAA4D;QAC5D,MAAM,IAAI,GAAI,MAAkC,CAAC,WAGhD,CAAC;QACF,MAAM,QAAQ,GACX,IAAI,CAAC,wBAAwB,CAEhB,IAAI,EAAE,CAAC;QACvB,QAAQ,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;QAC5B,IAAI,CAAC,wBAAwB,CAAC,GAAG,QAAQ,CAAC;QAC1C,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAO;IAEP,OAAO,CACH,IAA2C,CAC3C,wBAAwB,CACyB,IAAI,EAAE,CAC1D,CAAC;AACJ,CAAC"}

package/dist/audit.d.ts

@@ -0,0 +1,47 @@
+export interface AuditEvent {
+    /** D33-locked vocabulary, e.g. `payment.refund.issued`. */
+    action: string;
+    /** D33: target_kind, e.g. `payment`, `service`, `feature_doc`. */
+    target_kind: string;
+    /** Stable id of the row being acted on. May be null for create-then-id. */
+    target_id: string | null;
+    /** Free-form payload; redaction happens in `audit.emit`. */
+    payload?: Record<string, unknown>;
+}
+/**
+ * The pluggable Postgres-write path. Services wire this on init by
+ * passing `auditWriter` to `initTelemetry({ ... })` (deferred) OR by
+ * calling `_setAuditWriter` from a `@nodii/db-rls` adapter. v0.1.0 ships
+ * a default no-op writer; consumers replace it.
+ */
+export type AuditWriter = (row: {
+    actor: string;
+    action: string;
+    target_kind: string;
+    target_id: string | null;
+    payload: Record<string, unknown> | null;
+    tenant_id: string | null;
+    request_id: string | null;
+    intent_id: string | null;
+    ts: string;
+}) => Promise<void> | void;
+/**
+ * SDK-internal: services or the `@nodii/db-rls` adapter sets the
+ * writer. Public callers MUST NOT call this; the override exists for
+ * the adapter layer.
+ */
+export declare function _setAuditWriter(w: AuditWriter): void;
+/** Test-only restore. */
+export declare function _resetAuditWriterForTests(): void;
+/**
+ * The `audit.emit` API. Awaits the writer so the caller can await one
+ * write before responding; failures propagate to the caller (audit is
+ * NOT best-effort the way logs are — D33 requires durable emission for
+ * mutations).
+ */
+declare function emit(event: AuditEvent): Promise<void>;
+export declare const audit: {
+    readonly emit: typeof emit;
+};
+export {};
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAQ3B;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAEpD;AAED,yBAAyB;AACzB,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;;;;GAKG;AACH,iBAAe,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAepD;AAwBD,eAAO,MAAM,KAAK;;CAER,CAAC"}

package/dist/audit.js

@@ -0,0 +1,78 @@
+// Audit signal class per D17 + D33 + D149. Separate from logs.
+//
+// "If a tenant could legitimately need to see this row, it's audit, not
+// log." — D17 cultural rule.
+//
+// The library ships the adapter (the write path); the audit emission
+// policy (D33 three paths: method-level interceptor, saga lifecycle,
+// agent-layer double-emission) and the audit_log SCHEMA live in the
+// audit doctrine, not here. `@nodii/telemetry`'s job is to provide
+// `audit.emit(...)` that lands the row in:
+//   - per-service Postgres audit_log table (via the configured writer)
+//   - ClickHouse mirror (via OTLP audit signal; deferred to TS-12)
+import { getContext } from "./context";
+import { requireTelemetry } from "./init";
+const noopWriter = () => {
+    /* no-op default; services wire a real writer */
+};
+let writer = noopWriter;
+/**
+ * SDK-internal: services or the `@nodii/db-rls` adapter sets the
+ * writer. Public callers MUST NOT call this; the override exists for
+ * the adapter layer.
+ */
+export function _setAuditWriter(w) {
+    writer = w;
+}
+/** Test-only restore. */
+export function _resetAuditWriterForTests() {
+    writer = noopWriter;
+}
+/**
+ * The `audit.emit` API. Awaits the writer so the caller can await one
+ * write before responding; failures propagate to the caller (audit is
+ * NOT best-effort the way logs are — D33 requires durable emission for
+ * mutations).
+ */
+async function emit(event) {
+    requireTelemetry(); // throws if SDK not init'd
+    const ctx = getContext();
+    const actor = formatActor(ctx);
+    await writer({
+        actor,
+        action: event.action,
+        target_kind: event.target_kind,
+        target_id: event.target_id,
+        payload: event.payload ?? null,
+        tenant_id: ctx?.tenant_id ?? null,
+        request_id: ctx?.request_id ?? null,
+        intent_id: ctx?.intent_id ?? null,
+        ts: new Date().toISOString(),
+    });
+}
+function formatActor(ctx) {
+    if (!ctx)
+        return "system";
+    switch (ctx.actor_type) {
+        case "user":
+            return ctx.user_id ? `user:${ctx.user_id}` : "user:unknown";
+        case "agent":
+            return ctx.on_behalf_of
+                ? `agent:on_behalf_of:${ctx.on_behalf_of}`
+                : "agent:unknown";
+        case "service":
+            return "service";
+        case "system":
+            return "system";
+        default: {
+            // Exhaustiveness check.
+            const _exhaustive = ctx.actor_type;
+            void _exhaustive;
+            return "unknown";
+        }
+    }
+}
+export const audit = {
+    emit,
+};
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,wEAAwE;AACxE,6BAA6B;AAC7B,EAAE;AACF,qEAAqE;AACrE,qEAAqE;AACrE,oEAAoE;AACpE,mEAAmE;AACnE,2CAA2C;AAC3C,uEAAuE;AACvE,mEAAmE;AAEnE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AA+B1C,MAAM,UAAU,GAAgB,GAAG,EAAE;IACnC,gDAAgD;AAClD,CAAC,CAAC;AAEF,IAAI,MAAM,GAAgB,UAAU,CAAC;AAErC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,CAAc;IAC5C,MAAM,GAAG,CAAC,CAAC;AACb,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,yBAAyB;IACvC,MAAM,GAAG,UAAU,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,IAAI,CAAC,KAAiB;IACnC,gBAAgB,EAAE,CAAC,CAAC,2BAA2B;IAC/C,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,MAAM,CAAC;QACX,KAAK;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,SAAS,EAAE,GAAG,EAAE,SAAS,IAAI,IAAI;QACjC,UAAU,EAAE,GAAG,EAAE,UAAU,IAAI,IAAI;QACnC,SAAS,EAAE,GAAG,EAAE,SAAS,IAAI,IAAI;QACjC,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAC7B,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAC,GAAkC;IACrD,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,QAAQ,GAAG,CAAC,UAAU,EAAE,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC;QAC9D,KAAK,OAAO;YACV,OAAO,GAAG,CAAC,YAAY;gBACrB,CAAC,CAAC,sBAAsB,GAAG,CAAC,YAAY,EAAE;gBAC1C,CAAC,CAAC,eAAe,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,OAAO,CAAC,CAAC,CAAC;YACR,wBAAwB;YACxB,MAAM,WAAW,GAAU,GAAG,CAAC,UAAU,CAAC;YAC1C,KAAK,WAAW,CAAC;YACjB,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,IAAI;CACI,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,40 @@
+import type { NodiiContext } from "./types";
+/**
+ * Returns the active `NodiiContext`, or null if no middleware adapter
+ * has set one for this async scope (cron-flow before the
+ * `system-process` adapter runs; raw scripts; tests without harness).
+ */
+export declare function getContext(): NodiiContext | null;
+/**
+ * Like `getContext()` but throws if no context is active. Use this in
+ * code that is allowed to assume an adapter ran — typically inside a
+ * request handler.
+ */
+export declare function requireContext(): NodiiContext;
+/**
+ * Run `fn` inside a child scope where `ctx` is the active context. Per
+ * D41: never mutates the parent scope — child finishes and the parent
+ * scope's context is unaffected.
+ */
+export declare function withContext<T>(ctx: NodiiContext, fn: () => T): T;
+/**
+ * SDK-internal use only. The middleware adapters (§ 5.9) call this on
+ * request entry to set the active context. Service code MUST NOT call
+ * this directly — use `withContext()` for child scopes only. Not part
+ * of the public barrel; subpath adapters import it via the package
+ * internal path.
+ */
+export declare function setContextForCurrentScope(ctx: NodiiContext): void;
+/**
+ * Update the active context's `intent_id` only. Used by the intent
+ * lifecycle (§ 5.6) when `intent.begin()` / `intent.complete()` /
+ * `intent.abandon()` activate or deactivate an intent. Returns the new
+ * context so callers can verify; throws if no context is active (intent
+ * lifecycle must run inside an established `NodiiContext`).
+ *
+ * This is the ONLY mutation API per D41. It exists because intent
+ * activation is a per-scope assignment that the intent lifecycle owns,
+ * not a service-code mutation.
+ */
+export declare function _setIntentIdInCurrentScope(intentId: string | null): NodiiContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,YAAY,GAAG,IAAI,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAQ7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,YAAY,CAUd"}

package/dist/context.js

@@ -0,0 +1,70 @@
+// Context propagation per D40 / D41.
+//
+// SDK middleware (§ 5.9 of the feature_doc) is the ONLY writer of
+// `NodiiContext`. Service code reads via `getContext()`; child scopes
+// only via `withContext({...}, fn)`. There is no public mutate-in-place
+// API — that's an invariant of D41.
+//
+// Implementation: Node's `AsyncLocalStorage`, which works under both
+// Node and Bun. The store holds a `NodiiContext` directly.
+import { AsyncLocalStorage } from "node:async_hooks";
+const als = new AsyncLocalStorage();
+/**
+ * Returns the active `NodiiContext`, or null if no middleware adapter
+ * has set one for this async scope (cron-flow before the
+ * `system-process` adapter runs; raw scripts; tests without harness).
+ */
+export function getContext() {
+    return als.getStore() ?? null;
+}
+/**
+ * Like `getContext()` but throws if no context is active. Use this in
+ * code that is allowed to assume an adapter ran — typically inside a
+ * request handler.
+ */
+export function requireContext() {
+    const ctx = als.getStore();
+    if (!ctx) {
+        throw new Error("No NodiiContext active. SDK middleware (or `withContext`) must run before this code path.");
+    }
+    return ctx;
+}
+/**
+ * Run `fn` inside a child scope where `ctx` is the active context. Per
+ * D41: never mutates the parent scope — child finishes and the parent
+ * scope's context is unaffected.
+ */
+export function withContext(ctx, fn) {
+    return als.run(ctx, fn);
+}
+/**
+ * SDK-internal use only. The middleware adapters (§ 5.9) call this on
+ * request entry to set the active context. Service code MUST NOT call
+ * this directly — use `withContext()` for child scopes only. Not part
+ * of the public barrel; subpath adapters import it via the package
+ * internal path.
+ */
+export function setContextForCurrentScope(ctx) {
+    als.enterWith(ctx);
+}
+/**
+ * Update the active context's `intent_id` only. Used by the intent
+ * lifecycle (§ 5.6) when `intent.begin()` / `intent.complete()` /
+ * `intent.abandon()` activate or deactivate an intent. Returns the new
+ * context so callers can verify; throws if no context is active (intent
+ * lifecycle must run inside an established `NodiiContext`).
+ *
+ * This is the ONLY mutation API per D41. It exists because intent
+ * activation is a per-scope assignment that the intent lifecycle owns,
+ * not a service-code mutation.
+ */
+export function _setIntentIdInCurrentScope(intentId) {
+    const cur = als.getStore();
+    if (!cur) {
+        throw new Error("Cannot set intent_id: no NodiiContext active. SDK middleware must run before `intent.begin()`.");
+    }
+    const next = { ...cur, intent_id: intentId };
+    als.enterWith(next);
+    return next;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,kEAAkE;AAClE,sEAAsE;AACtE,wEAAwE;AACxE,oCAAoC;AACpC,EAAE;AACF,qEAAqE;AACrE,2DAA2D;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,MAAM,GAAG,GAAG,IAAI,iBAAiB,EAAgB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAI,GAAiB,EAAE,EAAW;IAC3D,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAiB;IACzD,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAuB;IAEvB,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAiB,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IAC3D,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,19 @@
-export declare const LIB_NAME = "telemetry";
-export declare const VERSION = "0.0.1";
+export { initTelemetry } from "./init";
+export { forceFlush, getOtlpAdapterHandle, installOtlpAdapter, shutdownOtlpAdapter, } from "./otlp-adapter";
+export type { OtlpAdapterHandle, OtlpAdapterConfig } from "./otlp-adapter";
+export { logger } from "./logger";
+export { tracer, withSpanAttributes, getSagaTracer } from "./tracer";
+export type { Span, SpanKind, SpanRecord, SpanStatus } from "./tracer";
+export { metrics, MetricVocabularyError } from "./metrics";
+export type { CounterHandle, HistogramHandle, MetricRegistration, } from "./metrics";
+export { audit } from "./audit";
+export type { AuditEvent } from "./audit";
+export { intent, IntentTypeNotRegistered } from "./intent";
+export { agentInvocable, readAgentRegistry, AGENT_INVOCABLE_METADATA, } from "./agent-invocable";
+export { getContext, requireContext, withContext, } from "./context";
+export { isPiiFieldName, redactString, redactFields, PII_FIELD_NAMES, } from "./redaction";
+export { uuidv7, isUuidv7 } from "./uuid";
+export { TelemetryNotInitialized } from "./types";
+export type { ActorType, AgentInvocableAuthTier, AgentInvocableConfig, AgentInvocableIdempotency, AgentInvocableMode, AgentInvocableRateLimit, AgentInvocableSideEffect, AutoInstrumentationConfig, ErrorHandlingConfig, ExportFailureReason, InitTelemetryConfig, IntentTypeDefinition, IntentTypeRegistry, LogEnvelope, LogLevel, MetricFamily, MetricVocabularyEntry, MetricVocabularyRegistry, NodiiContext, ResourceAttributes, SamplingConfig, } from "./types";
+export { DEFAULT_SAMPLING_CONFIG, METRIC_FAMILIES, AGENT_INVOCABLE_SIDE_EFFECTS, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,QAAQ,cAAc,CAAC;AACpC,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,EACZ,kBAAkB,EAClB,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,GAC7B,MAAM,SAAS,CAAC"}