@nodii/telemetry 0.0.2 → 0.3.0

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-types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Doctrine `02-audit-doctrine.md § 4` — the canonical `actor_kind` enum.
+ * 10 values, in this exact order; tests assert the order, so don't
+ * reorder without a drift entry. The SQL enum type is `audit_actor_kind`
+ * (one Postgres type shared across every service DB).
+ *
+ * `unknown` is the security marker per § 4.2 — emitted when no actor
+ * stamp can be derived; surfaces as a security alert via obs M17.
+ */
+export declare const AUDIT_ACTOR_KINDS: readonly ["employee_user", "tenant_user", "tenant_customer", "service", "worker", "webhook_provider", "external_system", "agent", "system", "unknown"];
+export type ActorKind = (typeof AUDIT_ACTOR_KINDS)[number];
+/** Doctrine § 7 — 7-value `outcome` enum. Order matches the doctrine. */
+export declare const AUDIT_OUTCOMES: readonly ["success", "failure", "partial", "queued", "dry_run", "denied_by_authz", "denied_by_mfa"];
+export type AuditOutcome = (typeof AUDIT_OUTCOMES)[number];
+//# sourceMappingURL=audit-types.d.ts.map

package/dist/audit-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-types.d.ts","sourceRoot":"","sources":["../src/audit-types.ts"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,wJAWpB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,yEAAyE;AACzE,eAAO,MAAM,cAAc,qGAQjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/audit-types.js

@@ -0,0 +1,39 @@
+// Type + enum constants for the audit signal. Kept separate from
+// `audit.ts` so the top-level `@nodii/telemetry` barrel does not
+// transitively pull `drizzle-orm` (which lives under `./drizzle/`).
+//
+// Consumers who don't run Drizzle still get `ActorKind`, `AuditOutcome`,
+// and the value arrays via the main barrel — and the Drizzle schema
+// fragment that uses these is reachable via `@nodii/telemetry/drizzle`.
+/**
+ * Doctrine `02-audit-doctrine.md § 4` — the canonical `actor_kind` enum.
+ * 10 values, in this exact order; tests assert the order, so don't
+ * reorder without a drift entry. The SQL enum type is `audit_actor_kind`
+ * (one Postgres type shared across every service DB).
+ *
+ * `unknown` is the security marker per § 4.2 — emitted when no actor
+ * stamp can be derived; surfaces as a security alert via obs M17.
+ */
+export const AUDIT_ACTOR_KINDS = [
+    "employee_user",
+    "tenant_user",
+    "tenant_customer",
+    "service",
+    "worker",
+    "webhook_provider",
+    "external_system",
+    "agent",
+    "system",
+    "unknown",
+];
+/** Doctrine § 7 — 7-value `outcome` enum. Order matches the doctrine. */
+export const AUDIT_OUTCOMES = [
+    "success",
+    "failure",
+    "partial",
+    "queued",
+    "dry_run",
+    "denied_by_authz",
+    "denied_by_mfa",
+];
+//# sourceMappingURL=audit-types.js.map

package/dist/audit-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-types.js","sourceRoot":"","sources":["../src/audit-types.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,iEAAiE;AACjE,oEAAoE;AACpE,EAAE;AACF,yEAAyE;AACzE,oEAAoE;AACpE,wEAAwE;AAExE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,eAAe;IACf,aAAa;IACb,iBAAiB;IACjB,SAAS;IACT,QAAQ;IACR,kBAAkB;IAClB,iBAAiB;IACjB,OAAO;IACP,QAAQ;IACR,SAAS;CACD,CAAC;AAIX,yEAAyE;AACzE,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS;IACT,SAAS;IACT,SAAS;IACT,QAAQ;IACR,SAAS;IACT,iBAAiB;IACjB,eAAe;CACP,CAAC"}

package/dist/audit.d.ts

@@ -0,0 +1,226 @@
+import { AUDIT_ACTOR_KINDS, AUDIT_OUTCOMES, type ActorKind, type AuditOutcome } from "./audit-types";
+export { AUDIT_ACTOR_KINDS, AUDIT_OUTCOMES };
+export type { ActorKind, AuditOutcome };
+/**
+ * Structured `actor` jsonb extension per doctrine § 4.1. Open-ended map;
+ * each `actor_kind` defines its own well-known fields (employee/user:
+ * `capacity`/`mfa`/`mfa_at`/`jti`; service: `instance_id`/`scopes`;
+ * worker: `queue_name`/`job_id`; webhook_provider: `transaction_id`/
+ * `signature_verified`; agent: `on_behalf_of`/`intent_id`/`tool`). NOT
+ * type-checked here — services that need stricter typing can layer their
+ * own discriminated union on top.
+ */
+export type ActorStamp = Record<string, unknown>;
+/**
+ * The rich audit-emit input shape per doctrine § 3 + § 6.0. Every field
+ * except `action` and `resourceType` is optional; the SDK resolves missing
+ * fields from `NodiiContext` + the active OTel span before handing the row
+ * to the writer.
+ *
+ * Field name convention: camelCase on the input; the SDK normalises to
+ * snake_case for the persisted row (`AuditEventRow`) matching the
+ * `<service>_audit_event` column names. This mirrors how Drizzle / pgx /
+ * SQLAlchemy schemas are typically declared in service code.
+ */
+export interface AuditArgs {
+    tenantId?: string | null;
+    action: string;
+    resourceType: string;
+    resourceId?: string | null;
+    resourceLabel?: string | null;
+    secondaryResourceType?: string | null;
+    secondaryResourceId?: string | null;
+    actorKind?: ActorKind | null;
+    actorId?: string | null;
+    actorExternalId?: string | null;
+    actorDisplay?: string | null;
+    actorIp?: string | null;
+    actorUserAgent?: string | null;
+    actor?: ActorStamp | null;
+    outcome?: AuditOutcome;
+    httpStatus?: number | null;
+    grpcCode?: string | null;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    errorDetails?: Record<string, unknown> | null;
+    before?: Record<string, unknown> | null;
+    after?: Record<string, unknown> | null;
+    patch?: Record<string, unknown> | null;
+    changedFields?: string[] | null;
+    reasonCode?: string | null;
+    reasonText?: string | null;
+    requestId?: string | null;
+    correlationId?: string | null;
+    traceId?: string | null;
+    spanId?: string | null;
+    intentId?: string | null;
+    sagaId?: string | null;
+    stepId?: string | null;
+    idempotencyKey?: string | null;
+    queueName?: string | null;
+    jobId?: string | null;
+    parentAuditEventId?: string | null;
+    readCount?: number | null;
+    firstReadAt?: Date | null;
+    lastReadAt?: Date | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The fully-resolved row handed to the writer (and, if wired, to the chain
+ * adapter). Snake_case names match the `<service>_audit_event` columns 1:1
+ * per doctrine § 3 — the writer can copy fields into the SQL INSERT without
+ * a translation layer.
+ */
+export interface AuditEventRow {
+    id: string;
+    tenant_id: string;
+    at: Date;
+    actor_kind: ActorKind;
+    actor_id: string | null;
+    actor_external_id: string | null;
+    actor_display: string | null;
+    actor_ip: string | null;
+    actor_user_agent: string | null;
+    actor: ActorStamp | null;
+    action: string;
+    resource_type: string;
+    resource_id: string | null;
+    resource_label: string | null;
+    secondary_resource_type: string | null;
+    secondary_resource_id: string | null;
+    outcome: AuditOutcome;
+    http_status: number | null;
+    grpc_code: string | null;
+    error_code: string | null;
+    error_message: string | null;
+    error_details: Record<string, unknown> | null;
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+    patch: Record<string, unknown> | null;
+    changed_fields: string[] | null;
+    reason_code: string | null;
+    reason_text: string | null;
+    request_id: string | null;
+    correlation_id: string | null;
+    trace_id: string | null;
+    span_id: string | null;
+    intent_id: string | null;
+    saga_id: string | null;
+    step_id: string | null;
+    idempotency_key: string | null;
+    queue_name: string | null;
+    job_id: string | null;
+    parent_audit_event_id: string | null;
+    read_count: number | null;
+    first_read_at: Date | null;
+    last_read_at: Date | null;
+    prev_hash: Uint8Array | null;
+    row_hash: Uint8Array | null;
+    tenant_audit_seq: bigint | null;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Legacy minimal shape from v0.1.0–v0.2.0. Still accepted by `audit.emit`
+ * so call sites in `@nodii/pii`, `@nodii/saga`, `@nodii/grpc-interceptors`
+ * continue to work unchanged. New callers should use `AuditArgs`.
+ *
+ * @deprecated Use `AuditArgs`. Mapping: `target_kind` → `resource_type`,
+ *   `target_id` → `resource_id`, `payload` → `metadata`.
+ */
+export interface AuditEvent {
+    /** D33-locked vocabulary, e.g. `payment.refund.issued`. */
+    action: string;
+    /** Maps to `resource_type` per doctrine § 3. */
+    target_kind: string;
+    /** Maps to `resource_id` per doctrine § 3. */
+    target_id: string | null;
+    /** Maps to `metadata` per doctrine § 3. */
+    payload?: Record<string, unknown>;
+}
+/**
+ * The pluggable Postgres-write path per doctrine § 15.1 + § 15.4.
+ *
+ * Services wire this at boot by calling `_setAuditWriter(...)` from a
+ * `@nodii/db-rls` adapter (or any service-supplied writer that implements
+ * this signature). The writer receives the canonical `AuditEventRow`
+ * matching `<service>_audit_event` columns 1:1.
+ *
+ * `tx` argument carries the in-flight transaction handle when `audit.emit`
+ * is called via Pattern A or B (in-tx); `undefined` for Pattern C
+ * (out-of-band — writer is responsible for opening its own short-lived tx
+ * scoped to `row.tenant_id`).
+ *
+ * v0.1.2 (drift `4cc80f62`) — the Noop default is GONE. If a service calls
+ * `audit.emit(...)` before wiring a real writer, the SDK throws
+ * `TelemetryAuditWriterMissing`. This closes the R1 violation in which
+ * audit rows were silently dropped because the lib defaulted to a no-op
+ * writer in production paths.
+ */
+export type AuditWriter = (row: AuditEventRow, tx?: unknown) => Promise<void> | void;
+/**
+ * Opt-in tamper-evident chain layer per doctrine § 13 + § 15.3. Wired via
+ * `configureTelemetry({audit: {chain}})` — typically from
+ * `@nodii/audit-chain`'s boot adapter.
+ *
+ * `augment` receives the canonical row (with `prev_hash` / `row_hash` /
+ * `tenant_audit_seq` all `null`) plus the in-flight tx (or `undefined`)
+ * and returns the computed chain triple. The implementation MUST acquire
+ * `pg_advisory_xact_lock(hash(tenant_id || 'audit'))` inside the tx so
+ * sequence allocation is per-tenant monotonic.
+ *
+ * Services that don't run the chain leave the three columns NULL; the
+ * library writes them as `null` to Postgres.
+ */
+export interface AuditChainAdapter {
+    augment(row: AuditEventRow, tx?: unknown): Promise<{
+        prev_hash: Uint8Array | null;
+        row_hash: Uint8Array;
+        tenant_audit_seq: bigint;
+    }>;
+}
+/**
+ * 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 declare class TelemetryAuditWriterMissing extends Error {
+    constructor();
+}
+/**
+ * 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 reset. Clears the wired writer; the next `audit.emit` will throw. */
+export declare function _resetAuditWriterForTests(): void;
+/**
+ * SDK-internal: `configureTelemetry({audit: {chain}})` calls this to wire
+ * the opt-in chain adapter. Setting `null` removes it.
+ */
+export declare function _setAuditChain(adapter: AuditChainAdapter | null): void;
+/** Test-only reset. Removes the wired chain adapter. */
+export declare function _resetAuditChainForTests(): void;
+/** SDK-internal accessor for tests + chain-layer integration probes. */
+export declare function _getAuditChain(): AuditChainAdapter | null;
+/**
+ * Pattern A / B (in-tx) — atomic with the mutation. Writer receives the
+ * caller's transaction handle and writes the audit row inside it.
+ */
+declare function emit(tx: unknown, args: AuditArgs): Promise<void>;
+/** Pattern C (out-of-band) — writer opens its own tenant-scoped tx. */
+declare function emit(args: AuditArgs): Promise<void>;
+/**
+ * Backward-compatible overload for the legacy minimal shape. Maps onto
+ * `AuditArgs` per doctrine § 3 before entering the shared write path.
+ *
+ * @deprecated Use the rich `AuditArgs` form. This overload exists so the
+ *   v0.2.x call sites in `@nodii/pii`, `@nodii/saga`, `@nodii/grpc-
+ *   interceptors` keep working unchanged while their authors migrate.
+ */
+declare function emit(event: AuditEvent): Promise<void>;
+export declare const audit: {
+    readonly emit: typeof emit;
+};
+//# 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":"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"}