@nodii/telemetry 0.0.2 → 0.3.0

package/dist/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * D41 lock: the per-request context written ONCE on request entry by an
+ * SDK middleware adapter (§ 5.9), never mutated within a request. Read
+ * via `getContext()`; child scopes created via `withContext({...}, fn)`.
+ */
+export interface NodiiContext {
+    /** UUID. Bare label `tenant_id` per D20 — same key across signals. */
+    tenant_id: string;
+    /** null when `actor_type !== 'user'`. */
+    user_id: string | null;
+    actor_type: ActorType;
+    /** Set when `actor_type === 'agent'`. */
+    on_behalf_of: string | null;
+    role: string;
+    request_id: string;
+    /** Set when an intent is active (D46/D155). */
+    intent_id: string | null;
+}
+/** D41 + D45/D46 (E5 reframe). Locked enum. */
+export type ActorType = "user" | "agent" | "system" | "service";
+/**
+ * D18 lock: six metric families. SDK rejects metric registrations whose
+ * declared family is outside this enum.
+ */
+export type MetricFamily = "request_handler" | "saga" | "async_worker" | "outbox" | "pool" | "intent";
+export declare const METRIC_FAMILIES: readonly MetricFamily[];
+/**
+ * D156 lock (operator-confirmed: 7 fields despite prose saying "8"):
+ * `@agentInvocable` runtime metadata. Build-time codegen emits these to
+ * `agent-methods.generated.json` per service; runtime is a no-op at
+ * v0.1.0.
+ */
+export interface AgentInvocableConfig {
+    mode: AgentInvocableMode;
+    authTier: AgentInvocableAuthTier;
+    sideEffects: readonly AgentInvocableSideEffect[];
+    /** Required when `mode === 'strict-only'`. */
+    allowedPipelines?: readonly string[];
+    idempotency: AgentInvocableIdempotency;
+    rateLimit?: AgentInvocableRateLimit;
+    description: string;
+}
+export type AgentInvocableMode = "composable" | "strict-only" | "human-only";
+export type AgentInvocableAuthTier = "autonomous" | "confirmation-required" | "never";
+/** D156 bounded vocab. SDK validates against this list at registration. */
+export type AgentInvocableSideEffect = "db.write" | "db.delete" | "email.send" | "sms.send" | "slack.post" | "payment.charge" | "payment.refund" | "external-api" | "file.write" | "notification.send";
+export declare const AGENT_INVOCABLE_SIDE_EFFECTS: readonly AgentInvocableSideEffect[];
+export type AgentInvocableIdempotency = "keyed-by-request-id" | "natural-key" | "none";
+export interface AgentInvocableRateLimit {
+    perMinute?: number;
+    perHour?: number;
+    perDay?: number;
+}
+/**
+ * D155 lock: intent_types registry shared with E5 gateway classifier
+ * via `intent-rules.json`. Loaded by `initTelemetry()` at start; SDK
+ * validates `intent.begin(typeName)` against this on every call (HARD
+ * from v0.1.0).
+ */
+export interface IntentTypeDefinition {
+    typeName: string;
+    server_mintable: boolean;
+    client_mintable: boolean;
+    /** D155: per-type timeout. */
+    timeout_seconds: number;
+}
+export type IntentTypeRegistry = Record<string, IntentTypeDefinition>;
+/**
+ * D16/D63/D64/D65/D66 lock — full shape ships at v0.1.0 with defaults
+ * matching OFF-at-launch. Flipping sampling on is a config change, NOT
+ * an API change. SDK reads `samplingConfig` from `initTelemetry()` but
+ * applies it only when D78 trigger fires.
+ */
+export interface SamplingConfig {
+    /** D16: default false (off at launch). */
+    enabled: boolean;
+    keepRules: {
+        /** D65 default 1.0 (100%). */
+        errors: number;
+        /** D65 default 1.0. */
+        sagas: number;
+        /** D65 default 1.0. */
+        agentAttributed: number;
+        /** D65 default 1.0. */
+        intent: number;
+        /** D64: latency keep-rule family-tiered. */
+        slowPerFamily: Record<MetricFamily, number>;
+        /** D65: per-family baseline probabilistic. */
+        baseline: Record<MetricFamily, number>;
+    };
+    cascade: {
+        /** D66: default true. */
+        keptTraceForcesKeptSpans: boolean;
+        /** D66: default true. */
+        keptTraceForcesKeptLogs: boolean;
+    };
+}
+/** Defaults exposed for callers who want to override only a slice. */
+export declare const DEFAULT_SAMPLING_CONFIG: SamplingConfig;
+/** D154 lock. */
+export interface AutoInstrumentationConfig {
+    httpServer?: boolean;
+    httpClient?: boolean;
+    grpcServer?: boolean;
+    grpcClient?: boolean;
+    /** TS only per D149. */
+    bullmqProducer?: boolean;
+    /** TS only per D149. */
+    bullmqConsumer?: boolean;
+    /** D67 default on; runtime override per-service. */
+    pgQuerySpans?: boolean;
+    hostMetrics?: boolean;
+    logAutoStamping?: boolean;
+    resourceAttributes?: boolean;
+    /** D15: SDK-side canonical, fail-closed. */
+    piiRedaction?: boolean;
+    redisSpans?: boolean;
+    dnsLookups?: boolean;
+    fileSystem?: boolean;
+    pgDetailedStatement?: boolean;
+}
+/**
+ * D153 lock: backpressure + drop policy. SDK queue → memory_limiter →
+ * exporter queue. No persistent buffer at v1. Drop is the policy; the
+ * counter is the observability.
+ */
+export interface ErrorHandlingConfig {
+    /** D153 default: 5000. */
+    otlpSendingQueueSize: number;
+    /** Drop on queue full; counter increments. Always true at v0.1.0. */
+    dropOnFull: true;
+}
+/** Reasons recorded by `telemetry.sdk.export_failures_total`. */
+export type ExportFailureReason = "queue_full" | "network_error" | "server_5xx" | "timeout";
+/**
+ * D60 resource attributes. `serviceName` + `env` are required;
+ * everything else is optional and surfaces as OTel Resource attributes.
+ */
+export interface ResourceAttributes {
+    serviceName: string;
+    /** 'dev' | 'uat' | 'prod' typical; locked at service deploy time. */
+    env: string;
+    serviceVersion?: string;
+    deploymentRegion?: string;
+    /** Free-form additional attributes. */
+    extra?: Record<string, string | number | boolean>;
+}
+/** The full `initTelemetry()` argument shape. */
+export interface InitTelemetryConfig {
+    /** D60 resource attributes. `serviceName` + `env` required. */
+    serviceName: string;
+    env: string;
+    serviceVersion?: string;
+    deploymentRegion?: string;
+    /** OTLP gRPC endpoint, e.g. `https://otel.dev.nucleus-cloud.in`. */
+    otlpEndpoint?: string;
+    /** D24 metric vocabulary registry. Loaded from disk via `vocabularyRegistry` arg. */
+    vocabularyRegistry?: MetricVocabularyRegistry;
+    /** D155 intent_types registry. */
+    intentTypes?: IntentTypeRegistry;
+    /** D154 toggles; missing = use D154 defaults. */
+    autoInstrumentation?: AutoInstrumentationConfig;
+    /** D16 sampling stub; defaults to OFF. */
+    samplingConfig?: SamplingConfig;
+    /** D153 backpressure + drop. */
+    errorHandling?: Partial<ErrorHandlingConfig>;
+    /** Free-form extra resource attributes (D60). */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /**
+     * When true, the real OTLP gRPC exporters are NOT installed at init —
+     * tracer/logger/metrics keep their no-op backends. Used by unit tests
+     * that want to assert SDK semantics without a live collector.
+     * Default: false (real OTLP exporters wired when `otlpEndpoint` is set).
+     */
+    disableOtlp?: boolean;
+}
+/**
+ * D24 lock: every metric name must be in this registry, with a family
+ * + description + the D-number that ADR-gates its inclusion. Registry
+ * file shipped as JSON at `vocabulary.json` (D24 § 5.4), loaded into
+ * this shape by `initTelemetry()`.
+ */
+export interface MetricVocabularyEntry {
+    family: MetricFamily;
+    description: string;
+    /** D-number reference, e.g. `D23`. */
+    decision: string;
+}
+export type MetricVocabularyRegistry = Record<string, MetricVocabularyEntry>;
+/**
+ * Locked log envelope per D13. All 11 fields are SDK-injected from
+ * `NodiiContext` + the initTelemetry config + active OTel context.
+ * Callers pass only `msg` + custom fields.
+ */
+export interface LogEnvelope {
+    level: LogLevel;
+    /** ISO-8601 timestamp. */
+    ts: string;
+    msg: string;
+    /** From `initTelemetry({ serviceName })`. */
+    service: string;
+    /** From `initTelemetry({ env })`. */
+    env: string;
+    /** From `NodiiContext.tenant_id`. */
+    tenant_id: string;
+    /** From `NodiiContext.user_id`. May be null. */
+    user_id: string | null;
+    /** Set when `actor_type === 'agent'`; mirrors `NodiiContext.on_behalf_of`. */
+    on_behalf_of?: string | null;
+    /** D41 actor_type. */
+    actor_type?: ActorType;
+    /** From `NodiiContext.request_id`. */
+    request_id: string;
+    /** From active OTel context. Null when no span is active. */
+    trace_id: string | null;
+    /** From active OTel context. Null when no span is active. */
+    span_id: string | null;
+    /** From `NodiiContext.intent_id`. */
+    intent_id: string | null;
+}
+/** D14 levels. `info` default in prod; `debug` runtime-toggleable per-tenant. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * SDK error thrown when any public API is called before
+ * `initTelemetry()` has run. Caller catches → fix init order.
+ */
+export declare class TelemetryNotInitialized extends Error {
+    constructor();
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,66 @@
+// Core type surface for @nodii/telemetry v0.1.0.
+//
+// Locked by feature_doc `nodii-libs/telemetry` v3 (D13, D18, D20–D22,
+// D26, D40–D43, D60, D151–D156). Every other module in this package
+// imports from here.
+export const METRIC_FAMILIES = [
+    "request_handler",
+    "saga",
+    "async_worker",
+    "outbox",
+    "pool",
+    "intent",
+];
+export const AGENT_INVOCABLE_SIDE_EFFECTS = [
+    "db.write",
+    "db.delete",
+    "email.send",
+    "sms.send",
+    "slack.post",
+    "payment.charge",
+    "payment.refund",
+    "external-api",
+    "file.write",
+    "notification.send",
+];
+/** Defaults exposed for callers who want to override only a slice. */
+export const DEFAULT_SAMPLING_CONFIG = {
+    enabled: false,
+    keepRules: {
+        errors: 1.0,
+        sagas: 1.0,
+        agentAttributed: 1.0,
+        intent: 1.0,
+        slowPerFamily: {
+            request_handler: 1.0,
+            saga: 1.0,
+            async_worker: 1.0,
+            outbox: 1.0,
+            pool: 1.0,
+            intent: 1.0,
+        },
+        baseline: {
+            request_handler: 0.1,
+            saga: 0.1,
+            async_worker: 0.1,
+            outbox: 0.1,
+            pool: 0.1,
+            intent: 0.1,
+        },
+    },
+    cascade: {
+        keptTraceForcesKeptSpans: true,
+        keptTraceForcesKeptLogs: true,
+    },
+};
+/**
+ * SDK error thrown when any public API is called before
+ * `initTelemetry()` has run. Caller catches → fix init order.
+ */
+export class TelemetryNotInitialized extends Error {
+    constructor() {
+        super("`@nodii/telemetry` was not initialized before use. Call `initTelemetry(...)` once at process start.");
+        this.name = "TelemetryNotInitialized";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,qBAAqB;AAoCrB,MAAM,CAAC,MAAM,eAAe,GAA4B;IACtD,iBAAiB;IACjB,MAAM;IACN,cAAc;IACd,QAAQ;IACR,MAAM;IACN,QAAQ;CACA,CAAC;AAsCX,MAAM,CAAC,MAAM,4BAA4B,GACvC;IACE,UAAU;IACV,WAAW;IACX,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,YAAY;IACZ,mBAAmB;CACX,CAAC;AA4Db,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,OAAO,EAAE,KAAK;IACd,SAAS,EAAE;QACT,MAAM,EAAE,GAAG;QACX,KAAK,EAAE,GAAG;QACV,eAAe,EAAE,GAAG;QACpB,MAAM,EAAE,GAAG;QACX,aAAa,EAAE;YACb,eAAe,EAAE,GAAG;YACpB,IAAI,EAAE,GAAG;YACT,YAAY,EAAE,GAAG;YACjB,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,GAAG;SACZ;QACD,QAAQ,EAAE;YACR,eAAe,EAAE,GAAG;YACpB,IAAI,EAAE,GAAG;YACT,YAAY,EAAE,GAAG;YACjB,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,GAAG;YACT,MAAM,EAAE,GAAG;SACZ;KACF;IACD,OAAO,EAAE;QACP,wBAAwB,EAAE,IAAI;QAC9B,uBAAuB,EAAE,IAAI;KAC9B;CACF,CAAC;AA4IF;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CACH,qGAAqG,CACtG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/uuid.d.ts

@@ -0,0 +1,5 @@
+/** Generate a UUIDv7. Time-ordered, k-sortable. */
+export declare function uuidv7(): string;
+/** Validate UUIDv7 surface shape (8-4-4-4-12 hex, version nibble = 7). */
+export declare function isUuidv7(s: string): boolean;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAUA,mDAAmD;AACnD,wBAAgB,MAAM,IAAI,MAAM,CAyB/B;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAI3C"}

package/dist/uuid.js

@@ -0,0 +1,34 @@
+// UUIDv7 mint. Used by:
+//   - `intent.begin()` to generate the intent_id sync (D155).
+//   - Middleware adapters minting `request_id` when the inbound request
+//     lacks one (§ 5.9 — fallback only).
+//
+// UUIDv7 layout (RFC 9562 §5.7):
+//   48-bit Unix ts ms | 4-bit version (=7) | 12-bit rand | 2-bit variant (=10) | 62-bit rand
+import { randomBytes } from "node:crypto";
+/** Generate a UUIDv7. Time-ordered, k-sortable. */
+export function uuidv7() {
+    const ts = BigInt(Date.now());
+    const rand = randomBytes(10); // 80 bits of randomness; we use 74 (12 + 62)
+    // 6 bytes of timestamp.
+    const tsHex = ts.toString(16).padStart(12, "0");
+    // 2 bytes for: 4-bit version (=7) + 12-bit random
+    const r12 = ((rand[0] ?? 0) << 4) | ((rand[1] ?? 0) >> 4); // 12 bits
+    const verAndRand = (0x7000 | (r12 & 0x0fff)).toString(16).padStart(4, "0");
+    // 2 bytes for: 2-bit variant (=10) + 14-bit random
+    const r14 = (((rand[1] ?? 0) & 0x0f) << 10) |
+        ((rand[2] ?? 0) << 2) |
+        ((rand[3] ?? 0) >> 6); // 14 bits
+    const variantAndRand = (0x8000 | (r14 & 0x3fff))
+        .toString(16)
+        .padStart(4, "0");
+    // 6 bytes (48 bits) of remaining random.
+    const tailBytes = rand.subarray(3, 9);
+    const tailHex = Buffer.from(tailBytes).toString("hex");
+    return `${tsHex.slice(0, 8)}-${tsHex.slice(8, 12)}-${verAndRand}-${variantAndRand}-${tailHex}`;
+}
+/** Validate UUIDv7 surface shape (8-4-4-4-12 hex, version nibble = 7). */
+export function isUuidv7(s) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(s);
+}
+//# sourceMappingURL=uuid.js.map

package/dist/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,8DAA8D;AAC9D,wEAAwE;AACxE,yCAAyC;AACzC,EAAE;AACF,iCAAiC;AACjC,6FAA6F;AAE7F,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,mDAAmD;AACnD,MAAM,UAAU,MAAM;IACpB,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,6CAA6C;IAE3E,wBAAwB;IACxB,MAAM,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAEhD,kDAAkD;IAClD,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU;IACrE,MAAM,UAAU,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAE3E,mDAAmD;IACnD,MAAM,GAAG,GACP,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU;IACnC,MAAM,cAAc,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC;SAC7C,QAAQ,CAAC,EAAE,CAAC;SACZ,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEpB,yCAAyC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEvD,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,UAAU,IAAI,cAAc,IAAI,OAAO,EAAE,CAAC;AACjG,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,OAAO,wEAAwE,CAAC,IAAI,CAClF,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nodii/telemetry",
-  "version": "0.0.2",
-  "description": "Placeholder for @nodii/telemetry — implementation lands at v0.1.0",
+  "version": "0.3.0",
+  "description": "Substrate observability library for the Nodii microservice stack — OTel wrapper, log envelope, intent lifecycle, audit signal, agent registry, context propagation. Spec: planning hub docKey=telemetry.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,24 +10,61 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./drizzle": {
+      "types": "./dist/drizzle/index.d.ts",
+      "default": "./dist/drizzle/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "echo 'no tests yet; placeholder package'"
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.12.2",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.2",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.57.2",
+    "@opentelemetry/exporter-metrics-otlp-grpc": "^0.57.2",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.57.2",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-logs": "^0.57.2",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
+    "@opentelemetry/sdk-node": "^0.57.2",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/sdk-trace-node": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.28.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.2",
+    "drizzle-orm": "^0.36.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/api-logs": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "drizzle-orm": "^0.36.0",
     "typescript": "^5.9.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/cognion-nucleus/nodii-libs.git",
+    "url": "git+https://github.com/cognion-nucleus/nodii-libs.git",
     "directory": "ts/telemetry"
   }
 }