@nodii/telemetry 0.0.2 → 0.3.0

package/dist/audit.js

@@ -0,0 +1,255 @@
+// Audit signal class — the canonical adapter per `02-audit-doctrine.md`
+// § 3 (row shape) + § 6.0 (Patterns A/B/C tx-bound) + § 13 (opt-in chain).
+//
+// "If a tenant could legitimately need to see this row, it's audit, not
+// log." — D17 cultural rule, doctrine § 1.
+//
+// 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 `<service>_audit_event` schema
+// live in `02-audit-doctrine.md`, not here. The Drizzle schema fragment
+// for the table ships from `@nodii/telemetry/drizzle`.
+//
+// Three emission patterns per § 6.0:
+//   - Pattern A — explicit tx pass: `audit.emit(tx, args)`
+//   - Pattern B — Hono `c.set("txn", tx)` middleware: also `audit.emit(tx, args)`
+//   - Pattern C — out-of-band: `audit.emit(args)` (writer owns its tx)
+import { AUDIT_ACTOR_KINDS, AUDIT_OUTCOMES, } from "./audit-types";
+import { getContext } from "./context";
+import { requireTelemetry } from "./init";
+import { uuidv7 } from "./uuid";
+export { AUDIT_ACTOR_KINDS, AUDIT_OUTCOMES };
+/**
+ * Thrown by `audit.emit` when no `AuditWriter` has been wired. v0.1.2
+ * replaces the v0.1.0–v0.1.1 silent-Noop failure mode (R1 violation,
+ * drift `4cc80f62`). Services MUST wire a writer via `_setAuditWriter(...)`
+ * before the first `audit.emit` fires.
+ */
+export class TelemetryAuditWriterMissing extends Error {
+    constructor() {
+        super("@nodii/telemetry: audit.emit called before an AuditWriter was wired. " +
+            "Drift 4cc80f62 (R1, breaking) removed the v0.1.0–v0.1.1 Noop default " +
+            "because it silently dropped audit rows. Wire a real writer via " +
+            "`_setAuditWriter(...)` (typically from `@nodii/db-rls`'s adapter " +
+            "writing to <serviceName>_audit_event per 02-audit-doctrine.md § 6.0).");
+        this.name = "TelemetryAuditWriterMissing";
+    }
+}
+let writer = null;
+let chain = null;
+/**
+ * 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 reset. Clears the wired writer; the next `audit.emit` will throw. */
+export function _resetAuditWriterForTests() {
+    writer = null;
+}
+/**
+ * SDK-internal: `configureTelemetry({audit: {chain}})` calls this to wire
+ * the opt-in chain adapter. Setting `null` removes it.
+ */
+export function _setAuditChain(adapter) {
+    chain = adapter;
+}
+/** Test-only reset. Removes the wired chain adapter. */
+export function _resetAuditChainForTests() {
+    chain = null;
+}
+/** SDK-internal accessor for tests + chain-layer integration probes. */
+export function _getAuditChain() {
+    return chain;
+}
+/**
+ * Type guard distinguishing the legacy `AuditEvent` from the rich `AuditArgs`.
+ * The discriminator is `target_kind`: present on the legacy shape, absent on
+ * the rich shape (which uses `resourceType`). Both shapes carry `action`.
+ */
+function isLegacyEvent(arg) {
+    return ("target_kind" in arg &&
+        typeof arg.target_kind === "string" &&
+        !("resourceType" in arg));
+}
+/**
+ * Map the legacy shape onto the rich `AuditArgs` so the rest of the
+ * pipeline only handles one input form. Mapping per doctrine § 3:
+ *   target_kind → resource_type
+ *   target_id   → resource_id
+ *   payload     → metadata
+ * Other rich fields are left undefined for `resolveRow` to fill from ctx.
+ */
+function legacyToRich(event) {
+    return {
+        action: event.action,
+        resourceType: event.target_kind,
+        resourceId: event.target_id,
+        metadata: event.payload ?? {},
+    };
+}
+/**
+ * Derive the canonical `actor_kind` from a `NodiiContext`. Falls back to
+ * `'unknown'` per doctrine § 4.2 — the SDK MUST emit `unknown` when no
+ * actor stamp can be derived; this is a security-event marker, not a
+ * silent default.
+ *
+ * Mapping rules per § 4 + auth-sdk § 5.6:
+ *   ctx.actor_type='user'    → 'tenant_user'  (callers override to 'employee_user' when platform-admin)
+ *   ctx.actor_type='agent'   → 'agent'
+ *   ctx.actor_type='service' → 'service'
+ *   ctx.actor_type='system'  → 'system'
+ *   ctx absent               → 'unknown'      (security marker)
+ */
+function deriveActorKind(ctx) {
+    if (!ctx)
+        return "unknown";
+    switch (ctx.actor_type) {
+        case "user":
+            return "tenant_user";
+        case "agent":
+            return "agent";
+        case "service":
+            return "service";
+        case "system":
+            return "system";
+        default: {
+            // Exhaustiveness check + future-proofing if ActorType grows.
+            const _exhaustive = ctx.actor_type;
+            void _exhaustive;
+            return "unknown";
+        }
+    }
+}
+/**
+ * Derive the canonical `actor_id` from `NodiiContext`. For `actor_type='user'`
+ * use `user_id`; for `actor_type='agent'` use `on_behalf_of` (the human who
+ * authorised the dispatch — per doctrine § 4.1 agent extension); for service
+ * + system contexts no `actor_id` is derivable and the caller must supply
+ * one if needed.
+ */
+function deriveActorId(ctx) {
+    if (!ctx)
+        return null;
+    switch (ctx.actor_type) {
+        case "user":
+            return ctx.user_id;
+        case "agent":
+            return ctx.on_behalf_of;
+        case "service":
+        case "system":
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Build the canonical `AuditEventRow` from `AuditArgs` + the active
+ * `NodiiContext`. Resolution rules (in order):
+ *   1. `tenant_id`: args.tenantId → ctx.tenant_id → throw
+ *   2. `actor_kind`: args.actorKind → derive from ctx → 'unknown'
+ *   3. `actor_id`: args.actorId → derive from ctx → null
+ *   4. `request_id`, `intent_id`: args → ctx → null
+ *   5. Other fields: pass through args (null when undefined)
+ *
+ * Throws `Error` when neither args nor ctx carry a `tenant_id` — the
+ * audit row cannot be RLS-bound without one, so silently dropping it
+ * would be a doctrine § 3 + R1 violation.
+ */
+function resolveRow(args) {
+    const ctx = getContext();
+    const tenantId = args.tenantId ?? ctx?.tenant_id ?? null;
+    if (!tenantId) {
+        throw new Error("audit.emit: tenant_id is required — pass `tenantId` in args or " +
+            "invoke inside a `withContext({tenant_id: ...})` scope. The audit " +
+            "row cannot be RLS-bound without it (02-audit-doctrine.md § 3).");
+    }
+    const actorKind = args.actorKind ?? deriveActorKind(ctx);
+    const actorId = args.actorId ?? deriveActorId(ctx);
+    return {
+        id: uuidv7(),
+        tenant_id: tenantId,
+        at: new Date(),
+        actor_kind: actorKind,
+        actor_id: actorId,
+        actor_external_id: args.actorExternalId ?? null,
+        actor_display: args.actorDisplay ?? null,
+        actor_ip: args.actorIp ?? null,
+        actor_user_agent: args.actorUserAgent ?? null,
+        actor: args.actor ?? null,
+        action: args.action,
+        resource_type: args.resourceType,
+        resource_id: args.resourceId ?? null,
+        resource_label: args.resourceLabel ?? null,
+        secondary_resource_type: args.secondaryResourceType ?? null,
+        secondary_resource_id: args.secondaryResourceId ?? null,
+        outcome: args.outcome ?? "success",
+        http_status: args.httpStatus ?? null,
+        grpc_code: args.grpcCode ?? null,
+        error_code: args.errorCode ?? null,
+        error_message: args.errorMessage ?? null,
+        error_details: args.errorDetails ?? null,
+        before: args.before ?? null,
+        after: args.after ?? null,
+        patch: args.patch ?? null,
+        changed_fields: args.changedFields ?? null,
+        reason_code: args.reasonCode ?? null,
+        reason_text: args.reasonText ?? null,
+        request_id: args.requestId ?? ctx?.request_id ?? null,
+        correlation_id: args.correlationId ?? null,
+        trace_id: args.traceId ?? null,
+        span_id: args.spanId ?? null,
+        intent_id: args.intentId ?? ctx?.intent_id ?? null,
+        saga_id: args.sagaId ?? null,
+        step_id: args.stepId ?? null,
+        idempotency_key: args.idempotencyKey ?? null,
+        queue_name: args.queueName ?? null,
+        job_id: args.jobId ?? null,
+        parent_audit_event_id: args.parentAuditEventId ?? null,
+        read_count: args.readCount ?? null,
+        first_read_at: args.firstReadAt ?? null,
+        last_read_at: args.lastReadAt ?? null,
+        // Chain columns left null unless an adapter is wired (see emitImpl).
+        prev_hash: null,
+        row_hash: null,
+        tenant_audit_seq: null,
+        metadata: args.metadata ?? {},
+    };
+}
+/**
+ * Shared write path. Resolves the row, optionally runs the chain adapter,
+ * and hands the row + tx to the writer. Throws `TelemetryAuditWriterMissing`
+ * when no writer is wired (drift `4cc80f62` enforcement).
+ */
+async function emitImpl(args, tx) {
+    requireTelemetry();
+    if (writer === null) {
+        throw new TelemetryAuditWriterMissing();
+    }
+    const row = resolveRow(args);
+    if (chain !== null) {
+        const augmented = await chain.augment(row, tx);
+        row.prev_hash = augmented.prev_hash;
+        row.row_hash = augmented.row_hash;
+        row.tenant_audit_seq = augmented.tenant_audit_seq;
+    }
+    await writer(row, tx);
+}
+async function emit(a, b) {
+    if (b !== undefined) {
+        // emit(tx, args) — Pattern A / B.
+        return emitImpl(b, a);
+    }
+    const arg = a;
+    if (isLegacyEvent(arg)) {
+        return emitImpl(legacyToRich(arg));
+    }
+    // emit(args) — Pattern C.
+    return emitImpl(arg);
+}
+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":"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"}

package/dist/configure.d.ts

@@ -0,0 +1,34 @@
+import { type AuditChainAdapter } from "./audit";
+/**
+ * Arguments to `configureTelemetry`. Currently only `audit.chain` is
+ * supported; the shape exists so additional knobs (e.g. log redaction
+ * overrides, custom exporters) can be added without an API break.
+ */
+export interface ConfigureTelemetryOptions {
+    audit?: {
+        /**
+         * Opt-in tamper-evident chain layer per `02-audit-doctrine.md § 13` +
+         * § 15.3. When wired, every `audit.emit` row receives `prev_hash`,
+         * `row_hash`, and `tenant_audit_seq` from the adapter before the row
+         * lands in the writer.
+         *
+         * Pass `null` to remove a previously-wired adapter (useful for tests
+         * + services that toggle chain coverage via feature flag).
+         *
+         * The library does NOT inspect the adapter beyond calling `augment`.
+         * Implementations (typically `@nodii/audit-chain`) own the hashing,
+         * the per-tenant monotonic sequence (via
+         * `pg_advisory_xact_lock(hash(tenant_id || 'audit'))`), and any
+         * verifier-worker reconciliation.
+         */
+        chain?: AuditChainAdapter | null;
+    };
+}
+/**
+ * Wire optional telemetry adapters. Currently the only knob is
+ * `audit.chain`. Idempotent: calling repeatedly with `audit.chain` set
+ * replaces the previously-wired adapter; calling with `audit` undefined
+ * leaves the existing wiring intact.
+ */
+export declare function configureTelemetry(opts: ConfigureTelemetryOptions): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/configure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE;QACN;;;;;;;;;;;;;;WAcG;QACH,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;KAClC,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAIxE"}

package/dist/configure.js

@@ -0,0 +1,23 @@
+// Top-level telemetry configuration knobs that aren't part of
+// `initTelemetry()`'s argument shape — typically opt-in adapter layers
+// (audit chain, future: tracing exporters, metric reducers).
+//
+// `configureTelemetry(...)` is idempotent and order-independent w.r.t.
+// `initTelemetry()`: a service can call it before `initTelemetry()` (set
+// up the chain adapter at module load) or after (wire it during boot
+// once secrets/clients are resolved). The library reads the wired
+// adapter inside `audit.emit` at write time — there is no init-time
+// snapshot.
+import { _setAuditChain } from "./audit";
+/**
+ * Wire optional telemetry adapters. Currently the only knob is
+ * `audit.chain`. Idempotent: calling repeatedly with `audit.chain` set
+ * replaces the previously-wired adapter; calling with `audit` undefined
+ * leaves the existing wiring intact.
+ */
+export function configureTelemetry(opts) {
+    if (opts.audit !== undefined && "chain" in opts.audit) {
+        _setAuditChain(opts.audit.chain ?? null);
+    }
+}
+//# sourceMappingURL=configure.js.map

package/dist/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,uEAAuE;AACvE,6DAA6D;AAC7D,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,qEAAqE;AACrE,kEAAkE;AAClE,oEAAoE;AACpE,YAAY;AAEZ,OAAO,EAAE,cAAc,EAA0B,MAAM,SAAS,CAAC;AA4BjE;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACtD,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IAC3C,CAAC;AACH,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"}