@nodii/telemetry 0.1.1 → 0.3.1

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

@@ -1,47 +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;
-    /** D33: target_kind, e.g. `payment`, `service`, `feature_doc`. */
+    /** Maps to `resource_type` per doctrine § 3. */
     target_kind: string;
-    /** Stable id of the row being acted on. May be null for create-then-id. */
+    /** Maps to `resource_id` per doctrine § 3. */
     target_id: string | null;
-    /** Free-form payload; redaction happens in `audit.emit`. */
+    /** Maps to `metadata` per doctrine § 3. */
     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.
+ * 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: {
-    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;
+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;
+    }>;
+}
 /**
- * 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.
+ * 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 restore. */
+/** Test-only reset. Clears the wired writer; the next `audit.emit` will throw. */
 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).
+ * 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;
 };
-export {};
 //# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

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

package/dist/audit.js

@@ -1,77 +1,264 @@
-// Audit signal class per D17 + D33 + D149. Separate from logs.
+// 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.
+// 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 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)
+// 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";
-const noopWriter = () => {
-    /* no-op default; services wire a real writer */
-};
-let writer = noopWriter;
+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.
+ * 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. */
+/** Test-only reset. Clears the wired writer; the next `audit.emit` will throw. */
 export function _resetAuditWriterForTests() {
-    writer = noopWriter;
+    writer = null;
 }
 /**
- * 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).
+ * SDK-internal: `configureTelemetry({audit: {chain}})` calls this to wire
+ * the opt-in chain adapter. Setting `null` removes it.
  */
-async function emit(event) {
-    requireTelemetry(); // throws if SDK not init'd
-    const ctx = getContext();
-    const actor = formatActor(ctx);
-    await writer({
-        actor,
+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) {
+    // Back-compat — v0.1.x callers conventionally put `tenant_id` inside
+    // the `payload` object. v0.3.0's resolveRow requires it at the top
+    // level (or via NodiiContext). Pull it out here so existing callers
+    // keep working without forcing a 3-lang migration.
+    const payload = event.payload ?? {};
+    const tenantIdRaw = payload.tenant_id;
+    const tenantId = typeof tenantIdRaw === "string" && tenantIdRaw.length > 0
+        ? tenantIdRaw
+        : undefined;
+    return {
         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(),
-    });
+        resourceType: event.target_kind,
+        resourceId: event.target_id,
+        tenantId,
+        metadata: payload,
+    };
 }
-function formatActor(ctx) {
+/**
+ * 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 "system";
+        return "unknown";
     switch (ctx.actor_type) {
         case "user":
-            return ctx.user_id ? `user:${ctx.user_id}` : "user:unknown";
+            return "tenant_user";
         case "agent":
-            return ctx.on_behalf_of
-                ? `agent:on_behalf_of:${ctx.on_behalf_of}`
-                : "agent:unknown";
+            return "agent";
         case "service":
             return "service";
         case "system":
             return "system";
         default: {
-            // Exhaustiveness check.
+            // 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,
 };