@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/esm/service/outbox_inbox.js

@@ -10,63 +10,131 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 var _MemoryOutboxRepository_messages, _MemoryInboxRepository_seen, _OutboxDispatcher_instances, _OutboxDispatcher_repository, _OutboxDispatcher_runtime, _OutboxDispatcher_options, _OutboxDispatcher_wakeTimer, _OutboxDispatcher_retryTimer, _OutboxDispatcher_idleTimer, _OutboxDispatcher_running, _OutboxDispatcher_pending, _OutboxDispatcher_retryDue, _OutboxDispatcher_stopped, _OutboxDispatcher_scheduleWakeup, _OutboxDispatcher_scheduleRetryWakeup, _OutboxDispatcher_scheduleIdleRetry, _OutboxDispatcher_run, _OutboxDispatcher_dispatchBatch, _OutboxDispatcher_retryDelayMs, _OutboxDispatcher_clearTimer;
-import { isErr } from "@qlever-llc/result";
+import { isErr, } from "@qlever-llc/result";
 import { Type } from "typebox";
 import { recordTrellisError } from "../telemetry/mod.js";
+/** Default Trellis helper-table names for SQL outbox and inbox storage. */
 export const defaultSqlOutboxTables = Object.freeze({
     outbox: "trellis_outbox",
     inbox: "trellis_inbox",
 });
+const sqlIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
- * Creates SQL outbox/inbox repositories plus DDL for caller-owned migrations.
+ * Creates SQL outbox/inbox repositories plus current helper-table DDL.
  *
- * Trellis does not import Drizzle here to avoid making every service depend on a
- * specific migration library. Services should include the returned DDL, or an
- * equivalent Drizzle table definition using these table and column names, in
- * their own Drizzle-managed migration flow.
+ * Use {@link getSqlOutboxMigrations} when services need versioned Trellis-owned
+ * migration artifacts for their normal database migration tooling.
  */
 export function createSqlOutboxAdapter(executor, dialect, tables = defaultSqlOutboxTables) {
+    const sqlTables = validateSqlOutboxTables(tables);
     return {
-        outbox: new SqlOutboxRepository(executor, dialect, tables),
-        inbox: new SqlInboxRepository(executor, dialect, tables),
+        outbox: new SqlOutboxRepository(executor, dialect, sqlTables),
+        inbox: new SqlInboxRepository(executor, dialect, sqlTables),
         ddl: dialect === "postgres"
-            ? createPostgresOutboxSchema(tables)
-            : createSqliteOutboxSchema(tables),
+            ? createPostgresOutboxSchema(sqlTables)
+            : createSqliteOutboxSchema(sqlTables),
     };
 }
+/**
+ * Returns Trellis-owned SQL outbox/inbox migration artifacts for a dialect.
+ *
+ * Trellis generates the helper-table SQL, but services remain responsible for
+ * running these artifacts through their normal database migration tooling.
+ */
+export function getSqlOutboxMigrations(options) {
+    const tables = resolveSqlOutboxTables(options.tables);
+    const up = options.dialect === "postgres"
+        ? createPostgresOutboxSchema(tables)
+        : createSqliteOutboxSchema(tables);
+    const down = createSqlOutboxDownSchema(tables);
+    return Object.freeze([
+        Object.freeze({
+            id: `trellis_sql_outbox_inbox_${options.dialect}_v1`,
+            version: 1,
+            dialect: options.dialect,
+            up,
+            down,
+            checksum: checksumMigrationSql(up, down),
+        }),
+    ]);
+}
 /** Returns SQLite DDL for Trellis outbox and inbox tables. */
 export function createSqliteOutboxSchema(tables = defaultSqlOutboxTables) {
+    const sqlTables = validateSqlOutboxTables(tables);
     return [
-        `CREATE TABLE IF NOT EXISTS ${tables.outbox} (id TEXT PRIMARY KEY, event TEXT NOT NULL, subject TEXT NOT NULL, payload TEXT NOT NULL, headers TEXT NOT NULL, state TEXT NOT NULL, attempts INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, next_attempt_at TEXT, last_error TEXT)`,
-        `CREATE INDEX IF NOT EXISTS ${tables.outbox}_due_idx ON ${tables.outbox} (state, next_attempt_at)`,
-        `CREATE TABLE IF NOT EXISTS ${tables.inbox} (message_id TEXT PRIMARY KEY, received_at TEXT NOT NULL)`,
+        `CREATE TABLE IF NOT EXISTS ${sqlTables.outbox} (id TEXT PRIMARY KEY, kind TEXT NOT NULL, name TEXT NOT NULL, subject TEXT NOT NULL, payload TEXT NOT NULL, headers TEXT NOT NULL, state TEXT NOT NULL, attempts INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, next_attempt_at TEXT, last_error TEXT, outcome TEXT)`,
+        `CREATE INDEX IF NOT EXISTS ${sqlTables.outbox}_due_idx ON ${sqlTables.outbox} (state, next_attempt_at)`,
+        `CREATE TABLE IF NOT EXISTS ${sqlTables.inbox} (message_id TEXT PRIMARY KEY, received_at TEXT NOT NULL)`,
     ];
 }
 /** Returns Postgres DDL for Trellis outbox and inbox tables. */
 export function createPostgresOutboxSchema(tables = defaultSqlOutboxTables) {
+    const sqlTables = validateSqlOutboxTables(tables);
     return [
-        `CREATE TABLE IF NOT EXISTS ${tables.outbox} (id text PRIMARY KEY, event text NOT NULL, subject text NOT NULL, payload text NOT NULL, headers jsonb NOT NULL, state text NOT NULL, attempts integer NOT NULL, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL, next_attempt_at timestamptz, last_error text)`,
-        `CREATE INDEX IF NOT EXISTS ${tables.outbox}_due_idx ON ${tables.outbox} (state, next_attempt_at)`,
-        `CREATE TABLE IF NOT EXISTS ${tables.inbox} (message_id text PRIMARY KEY, received_at timestamptz NOT NULL)`,
+        `CREATE TABLE IF NOT EXISTS ${sqlTables.outbox} (id text PRIMARY KEY, kind text NOT NULL, name text NOT NULL, subject text NOT NULL, payload text NOT NULL, headers jsonb NOT NULL, state text NOT NULL, attempts integer NOT NULL, created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL, next_attempt_at timestamptz, last_error text, outcome jsonb)`,
+        `CREATE INDEX IF NOT EXISTS ${sqlTables.outbox}_due_idx ON ${sqlTables.outbox} (state, next_attempt_at)`,
+        `CREATE TABLE IF NOT EXISTS ${sqlTables.inbox} (message_id text PRIMARY KEY, received_at timestamptz NOT NULL)`,
     ];
 }
+function createSqlOutboxDownSchema(tables) {
+    const sqlTables = validateSqlOutboxTables(tables);
+    return [
+        `DROP INDEX IF EXISTS ${sqlTables.outbox}_due_idx`,
+        `DROP TABLE IF EXISTS ${sqlTables.inbox}`,
+        `DROP TABLE IF EXISTS ${sqlTables.outbox}`,
+    ];
+}
+function resolveSqlOutboxTables(tables) {
+    return validateSqlOutboxTables({
+        outbox: tables?.outbox ?? defaultSqlOutboxTables.outbox,
+        inbox: tables?.inbox ?? defaultSqlOutboxTables.inbox,
+    });
+}
+function validateSqlOutboxTables(tables) {
+    validateSqlIdentifier("outbox", tables.outbox);
+    validateSqlIdentifier("inbox", tables.inbox);
+    return Object.freeze({ outbox: tables.outbox, inbox: tables.inbox });
+}
+function validateSqlIdentifier(kind, name) {
+    if (!sqlIdentifierPattern.test(name)) {
+        throw new Error(`Invalid SQL ${kind} table name "${name}". Use a simple identifier matching ${sqlIdentifierPattern.source}.`);
+    }
+}
+function checksumMigrationSql(up, down) {
+    return `fnv1a64:${fnv1a64Hex([
+        "-- up",
+        ...up,
+        "-- down",
+        ...down,
+    ].join("\n"))}`;
+}
+function fnv1a64Hex(input) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    for (const character of input) {
+        hash ^= BigInt(character.codePointAt(0) ?? 0);
+        hash = BigInt.asUintN(64, hash * prime);
+    }
+    return hash.toString(16).padStart(16, "0");
+}
 /** In-memory outbox repository intended for tests and local process adapters. */
 export class MemoryOutboxRepository {
     constructor() {
         _MemoryOutboxRepository_messages.set(this, new Map());
     }
-    async enqueue(event) {
+    async enqueue(record) {
         const now = new Date().toISOString();
-        const id = messageId(event);
+        const id = record.id;
         const existing = __classPrivateFieldGet(this, _MemoryOutboxRepository_messages, "f").get(id);
         if (existing)
             return existing;
         const message = {
             id,
-            event: event.event,
-            subject: event.subject,
-            payload: event.encodedPayload,
-            headers: { ...event.headers },
+            kind: record.kind,
+            name: record.name,
+            subject: record.subject,
+            payload: record.payload,
+            headers: { ...record.headers },
             state: "pending",
             attempts: 0,
             createdAt: now,
@@ -90,7 +158,7 @@ export class MemoryOutboxRepository {
         }
         return claimed;
     }
-    async markDispatched(id, now) {
+    async markDispatched(id, now, outcome) {
         const message = __classPrivateFieldGet(this, _MemoryOutboxRepository_messages, "f").get(id);
         if (!message)
             return;
@@ -100,6 +168,7 @@ export class MemoryOutboxRepository {
             updatedAt: now.toISOString(),
             nextAttemptAt: undefined,
             lastError: undefined,
+            outcome: outcome ?? message.outcome,
         });
     }
     async markFailed(id, failure) {
@@ -155,17 +224,19 @@ export class SqlOutboxRepository {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: tables
+            value: void 0
         });
+        this.tables = validateSqlOutboxTables(tables);
     }
-    async enqueue(event) {
+    async enqueue(record) {
         const now = new Date().toISOString();
         const message = {
-            id: messageId(event),
-            event: event.event,
-            subject: event.subject,
-            payload: event.encodedPayload,
-            headers: { ...event.headers },
+            id: record.id,
+            kind: record.kind,
+            name: record.name,
+            subject: record.subject,
+            payload: record.payload,
+            headers: { ...record.headers },
             state: "pending",
             attempts: 0,
             createdAt: now,
@@ -175,9 +246,10 @@ export class SqlOutboxRepository {
         const conflict = this.dialect === "postgres"
             ? "ON CONFLICT (id) DO NOTHING"
             : "ON CONFLICT(id) DO NOTHING";
-        await this.executor.execute(`INSERT INTO ${this.tables.outbox} (id, event, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error) VALUES (${placeholders(this.dialect, 11)}) ${conflict}`, [
+        await this.executor.execute(`INSERT INTO ${this.tables.outbox} (id, kind, name, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error, outcome) VALUES (${placeholders(this.dialect, 13)}) ${conflict}`, [
             message.id,
-            message.event,
+            message.kind,
+            message.name,
             message.subject,
             message.payload,
             headers,
@@ -187,15 +259,17 @@ export class SqlOutboxRepository {
             message.updatedAt,
             null,
             null,
+            null,
         ]);
         return message;
     }
     async claimDue(limit, now) {
-        const rows = await this.executor.query(`SELECT id, event, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error FROM ${this.tables.outbox} WHERE state != ${placeholder(this.dialect, 1)} AND (next_attempt_at IS NULL OR next_attempt_at <= ${placeholder(this.dialect, 2)}) ORDER BY created_at LIMIT ${placeholder(this.dialect, 3)}`, ["dispatched", now.toISOString(), limit]);
+        const rows = await this.executor.query(`SELECT id, kind, name, subject, payload, headers, state, attempts, created_at, updated_at, next_attempt_at, last_error, outcome FROM ${this.tables.outbox} WHERE state != ${placeholder(this.dialect, 1)} AND (next_attempt_at IS NULL OR next_attempt_at <= ${placeholder(this.dialect, 2)}) ORDER BY created_at LIMIT ${placeholder(this.dialect, 3)}`, ["dispatched", now.toISOString(), limit]);
         return rows.map(rowToOutboxMessage);
     }
-    async markDispatched(id, now) {
-        await this.executor.execute(`UPDATE ${this.tables.outbox} SET state = ${placeholder(this.dialect, 1)}, updated_at = ${placeholder(this.dialect, 2)}, next_attempt_at = NULL, last_error = NULL WHERE id = ${placeholder(this.dialect, 3)}`, ["dispatched", now.toISOString(), id]);
+    async markDispatched(id, now, outcome) {
+        const outcomeJson = outcome !== undefined ? JSON.stringify(outcome) : null;
+        await this.executor.execute(`UPDATE ${this.tables.outbox} SET state = ${placeholder(this.dialect, 1)}, updated_at = ${placeholder(this.dialect, 2)}, next_attempt_at = NULL, last_error = NULL, outcome = ${placeholder(this.dialect, 3)} WHERE id = ${placeholder(this.dialect, 4)}`, ["dispatched", now.toISOString(), outcomeJson, id]);
     }
     async markFailed(id, failure) {
         await this.executor.execute(`UPDATE ${this.tables.outbox} SET state = ${placeholder(this.dialect, 1)}, attempts = attempts + 1, updated_at = ${placeholder(this.dialect, 2)}, next_attempt_at = ${placeholder(this.dialect, 3)}, last_error = ${placeholder(this.dialect, 4)} WHERE id = ${placeholder(this.dialect, 5)}`, [
@@ -226,8 +300,9 @@ export class SqlInboxRepository {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: tables
+            value: void 0
         });
+        this.tables = validateSqlOutboxTables(tables);
     }
     async record(messageId, now = new Date()) {
         try {
@@ -254,7 +329,8 @@ const KvInboxRecordSchema = Type.Object({
 });
 export const KvOutboxRecordSchema = Type.Object({
     id: Type.String(),
-    event: Type.String(),
+    kind: Type.String(),
+    name: Type.String(),
     subject: Type.String(),
     payload: Type.String(),
     headers: Type.Record(Type.String(), Type.String()),
@@ -269,6 +345,7 @@ export const KvOutboxRecordSchema = Type.Object({
     updatedAt: Type.String(),
     nextAttemptAt: Type.Optional(Type.String()),
     lastError: Type.Optional(Type.String()),
+    outcome: Type.Optional(Type.String()),
 });
 /** Durable NATS KV outbox repository for services without SQL state. */
 export class NatsKvOutboxRepository {
@@ -280,14 +357,15 @@ export class NatsKvOutboxRepository {
             value: kv
         });
     }
-    async enqueue(event) {
+    async enqueue(rec) {
         const now = new Date().toISOString();
         const record = {
-            id: messageId(event),
-            event: event.event,
-            subject: event.subject,
-            payload: event.encodedPayload,
-            headers: { ...event.headers },
+            id: rec.id,
+            kind: rec.kind,
+            name: rec.name,
+            subject: rec.subject,
+            payload: rec.payload,
+            headers: { ...rec.headers },
             state: "pending",
             attempts: 0,
             createdAt: now,
@@ -341,19 +419,23 @@ export class NatsKvOutboxRepository {
         }
         return claimed;
     }
-    async markDispatched(id, now) {
+    async markDispatched(id, now, outcome) {
         const loaded = await this.kv.get(id).take();
         if (isErr(loaded)) {
             if (hasKvReason(loaded.error, "not found"))
                 return;
             throw loaded.error;
         }
+        const outcomeStr = outcome !== undefined
+            ? JSON.stringify(outcome)
+            : undefined;
         const stored = await loaded.put({
             ...loaded.value,
             state: "dispatched",
             updatedAt: now.toISOString(),
             nextAttemptAt: undefined,
             lastError: undefined,
+            outcome: outcomeStr ?? loaded.value.outcome,
         }, true).take();
         if (isErr(stored))
             throw stored.error;
@@ -550,7 +632,7 @@ _OutboxDispatcher_repository = new WeakMap(), _OutboxDispatcher_runtime = new We
         __classPrivateFieldSet(this, _OutboxDispatcher_idleTimer, undefined, "f");
     }
 };
-/** Dispatches due outbox messages through a Trellis runtime publisher. */
+/** Dispatches due outbox messages through a dispatch runtime. */
 export async function dispatchOutbox(repository, runtime, options = {}) {
     const now = options.now ?? new Date();
     const retryDelayMs = options.retryDelayMs ?? 1000;
@@ -558,47 +640,115 @@ export async function dispatchOutbox(repository, runtime, options = {}) {
     let dispatched = 0;
     let failed = 0;
     for (const message of messages) {
-        const result = await runtime.publishPrepared(outboxMessageToPrepared(message));
-        const value = result.take();
-        if (isErr(value)) {
-            recordTrellisError(value.error, {
+        if (message.kind === "event.publish") {
+            const result = await runtime.publishPreparedEvent(outboxMessageToPreparedEvent(message));
+            const value = result.take();
+            if (isErr(value)) {
+                recordTrellisError(value.error, {
+                    surface: "outbox",
+                    direction: "dispatcher",
+                    operation: message.name,
+                    phase: "publish",
+                    messagingSystem: "nats",
+                });
+                failed += 1;
+                await repository.markFailed(message.id, {
+                    error: value.error.message,
+                    nextAttemptAt: new Date(now.getTime() + retryDelayMs),
+                    now,
+                });
+                continue;
+            }
+            dispatched += 1;
+            await repository.markDispatched(message.id, now);
+        }
+        else if (message.kind === "job.create" || message.kind === "job.submit") {
+            if (runtime.dispatchJobSubmission) {
+                const result = await runtime.dispatchJobSubmission(message);
+                const value = result.take();
+                if (isErr(value)) {
+                    recordTrellisError(value.error, {
+                        surface: "outbox",
+                        direction: "dispatcher",
+                        operation: message.name,
+                        phase: "job.dispatch",
+                    });
+                    failed += 1;
+                    await repository.markFailed(message.id, {
+                        error: value.error.message,
+                        nextAttemptAt: new Date(now.getTime() + retryDelayMs),
+                        now,
+                    });
+                    continue;
+                }
+                dispatched += 1;
+                await repository.markDispatched(message.id, now);
+            }
+            else {
+                recordTrellisError(new Error(`job dispatch not supported`), {
+                    surface: "outbox",
+                    direction: "dispatcher",
+                    operation: message.name,
+                    phase: "dispatch",
+                });
+                await repository.markDispatched(message.id, now, {
+                    error: "job dispatch not supported",
+                });
+            }
+        }
+        else {
+            const error = `Unknown outbox record kind: ${message.kind}`;
+            recordTrellisError(new Error(error), {
                 surface: "outbox",
                 direction: "dispatcher",
-                operation: message.event,
-                phase: "publish",
-                messagingSystem: "nats",
+                operation: message.name,
+                phase: "dispatch",
             });
-            failed += 1;
-            await repository.markFailed(message.id, {
-                error: value.error.message,
-                nextAttemptAt: new Date(now.getTime() + retryDelayMs),
-                now,
-            });
-            continue;
+            await repository.markDispatched(message.id, now, { error });
         }
-        dispatched += 1;
-        await repository.markDispatched(message.id, now);
     }
     return { dispatched, failed };
 }
-/** Rehydrates a persisted outbox row into a prepared event. */
-export function outboxMessageToPrepared(message) {
+/** Rehydrates a persisted outbox event row into a prepared event. */
+export function outboxMessageToPreparedEvent(message) {
+    if (message.kind !== "event.publish") {
+        throw new Error(`Expected event.publish kind, got ${message.kind}`);
+    }
+    const payload = JSON.parse(message.payload);
+    const header = eventHeaderFromMessage(message.headers);
     return Object.freeze({
-        event: message.event,
+        event: message.name,
         subject: message.subject,
-        payload: Object.freeze(JSON.parse(message.payload)),
+        header: Object.freeze(header),
+        payload: Object.freeze(payload),
         encodedPayload: message.payload,
         headers: Object.freeze({ ...message.headers }),
     });
 }
-function messageId(event) {
-    return event.headers["Nats-Msg-Id"] ?? event.headers["nats-msg-id"] ??
-        event.payload.header.id;
+/** Adapts a prepared Trellis event into a generic outbox record. */
+export function preparedTrellisEventToOutboxRecord(event) {
+    return {
+        id: event.headers["Nats-Msg-Id"] ?? event.header.id,
+        kind: "event.publish",
+        name: event.event,
+        subject: event.subject,
+        payload: event.encodedPayload,
+        headers: event.headers,
+    };
+}
+function eventHeaderFromMessage(headers) {
+    const id = headers["Nats-Msg-Id"] ?? headers["nats-msg-id"];
+    const time = headers["Trellis-Event-Time"] ?? headers["trellis-event-time"];
+    return {
+        id: typeof id === "string" ? id : "",
+        time: typeof time === "string" ? time : new Date(0).toISOString(),
+    };
 }
 function rowToOutboxMessage(row) {
     return {
         id: stringField(row, "id"),
-        event: stringField(row, "event"),
+        kind: kindField(row, "kind"),
+        name: stringField(row, "name"),
         subject: stringField(row, "subject"),
         payload: stringField(row, "payload"),
         headers: parseHeaders(row["headers"]),
@@ -608,12 +758,14 @@ function rowToOutboxMessage(row) {
         updatedAt: stringField(row, "updated_at"),
         nextAttemptAt: optionalStringField(row, "next_attempt_at"),
         lastError: optionalStringField(row, "last_error"),
+        outcome: optionalStringField(row, "outcome"),
     };
 }
 function kvRecordToOutboxMessage(record) {
     return {
         id: record.id,
-        event: record.event,
+        kind: record.kind,
+        name: record.name,
         subject: record.subject,
         payload: record.payload,
         headers: { ...record.headers },
@@ -623,6 +775,7 @@ function kvRecordToOutboxMessage(record) {
         updatedAt: record.updatedAt,
         nextAttemptAt: record.nextAttemptAt,
         lastError: record.lastError,
+        outcome: record.outcome,
     };
 }
 function placeholder(dialect, index) {
@@ -677,6 +830,14 @@ function numberField(row, field) {
     }
     return value;
 }
+function kindField(row, field) {
+    const value = stringField(row, field);
+    if (value === "event.publish" || value === "job.create" ||
+        value === "job.submit") {
+        return value;
+    }
+    throw new Error(`Expected SQL field ${field} to be an outbox record kind`);
+}
 function stateField(row, field) {
     const value = stringField(row, field);
     if (value === "pending" || value === "dispatched" || value === "failed") {

package/esm/telemetry/metrics.d.ts

@@ -20,8 +20,63 @@ export type TrellisErrorMetricAttributes = {
     /** Static messaging operation name, when already known. */
     messagingOperation?: string;
 };
+/** Duration metric names accepted by {@link recordTrellisDuration}. */
+export type TrellisDurationMetricName = "trellis.connect.duration" | "trellis.auth.flow.duration" | "trellis.auth.approval_resolution.duration" | "trellis.auth.callout.duration" | "trellis.admin.workflow.duration" | "trellis.contract.analysis.duration";
+/** Low-cardinality attributes accepted by {@link recordTrellisDuration}. */
+export type TrellisDurationMetricAttributes = {
+    /** Stable Trellis surface name, such as `rpc`, `jobs`, or `operations`. */
+    surface?: string;
+    /** Stable operation kind or method name. Do not pass IDs, subjects, or URLs. */
+    operation?: string;
+    /** Stable lifecycle phase such as `bootstrap`, `encode`, or `total`. */
+    phase?: string;
+    /** Stable outcome label such as `ok` or `error`. */
+    outcome?: string;
+    /** Participant kind such as `admin`, `client`, `service`, or `device`. */
+    participantKind?: string;
+    /** Session kind such as `user`, `service`, or `device`. */
+    sessionKind?: string;
+    /** Auth flow such as `local`, `oauth`, `device`, or `bootstrap`. */
+    authFlow?: string;
+    /** Auth approval outcome such as `approved`, `denied`, `required`, or `none`. */
+    authApproval?: string;
+    /** Whether a deployment authority is present. */
+    authorityPresent?: boolean;
+    /** Plan classification such as `install`, `update`, `migration`, `noop`, or `unknown`. */
+    planClassification?: string;
+    /** Contract kind such as `app`, `service`, `device`, `builtin`, or `unknown`. */
+    contractKind?: string;
+    /** Static messaging system name, when already known. */
+    messagingSystem?: string;
+    /** Static messaging operation name, when already known. */
+    messagingOperation?: string;
+};
 /** Returns the shared Trellis OpenTelemetry meter. */
 export declare function getTrellisMeter(): Meter;
 /** Records one Trellis error with only stable, low-cardinality attributes. */
 export declare function recordTrellisError(error: unknown, attributes?: TrellisErrorMetricAttributes): void;
+/**
+ * Records one duration measurement on the given Trellis histogram.
+ *
+ * Converts `durationMs` to seconds. Negative, NaN, and infinite values are
+ * silently ignored.
+ *
+ * Histogram instruments are cached by metric name so `createHistogram` is
+ * called at most once per metric name.
+ *
+ * @param name - The duration metric name.
+ * @param durationMs - The measured duration in milliseconds.
+ * @param attributes - Optional low-cardinality attributes. Only values that
+ *   pass sanitization are included.
+ *
+ * @example
+ * ```ts
+ * recordTrellisDuration("trellis.connect.duration", 42.5, {
+ *   phase: "nats_connect",
+ *   outcome: "ok",
+ *   participantKind: "client",
+ * });
+ * ```
+ */
+export declare function recordTrellisDuration(name: TrellisDurationMetricName, durationMs: number, attributes?: TrellisDurationMetricAttributes): void;
 //# sourceMappingURL=metrics.d.ts.map

package/esm/telemetry/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAW,MAAM,oBAAoB,CAAC;AAiDzD,yEAAyE;AACzE,MAAM,MAAM,4BAA4B,GAAG;IACzC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AASF,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,KAAK,CAEvC;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,4BAAiC,GAC5C,IAAI,CAWN"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,KAAK,EAAW,MAAM,oBAAoB,CAAC;AAiDzE,yEAAyE;AACzE,MAAM,MAAM,4BAA4B,GAAG;IACzC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GACjC,0BAA0B,GAC1B,4BAA4B,GAC5B,2CAA2C,GAC3C,+BAA+B,GAC/B,iCAAiC,GACjC,oCAAoC,CAAC;AAEzC,4EAA4E;AAC5E,MAAM,MAAM,+BAA+B,GAAG;IAC5C,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0FAA0F;IAC1F,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAWF,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,KAAK,CAEvC;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,4BAAiC,GAC5C,IAAI,CAWN;AAsJD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,yBAAyB,EAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,+BAA+B,GAC3C,IAAI,CAaN"}

package/esm/telemetry/metrics.js

@@ -42,6 +42,7 @@ const AUTH_REASONS = new Set([
     "device_identity_key_mismatch",
     "invalid_device_qr_mac",
 ]);
+const DURATION_HISTOGRAM_CACHE = new Map();
 /** Returns the shared Trellis OpenTelemetry meter. */
 export function getTrellisMeter() {
     return metrics.getMeter(TRELLIS_METER_NAME);
@@ -79,6 +80,91 @@ export function buildTrellisErrorMetricAttributes(error, attributes = {}) {
     setLowCardinalityAttribute(metricAttributes, "messaging.operation", attributes.messagingOperation);
     return metricAttributes;
 }
+/**
+ * Builds sanitized, low-cardinality attributes for duration histograms.
+ *
+ * @internal Exported for focused tests; runtime callers should use
+ * {@link recordTrellisDuration}.
+ */
+export function buildTrellisDurationMetricAttributes(attributes = {}) {
+    const metricAttributes = {};
+    setLowCardinalityAttribute(metricAttributes, "trellis.surface", attributes.surface);
+    setLowCardinalityAttribute(metricAttributes, "trellis.operation", attributes.operation);
+    setLowCardinalityAttribute(metricAttributes, "trellis.phase", attributes.phase);
+    setLowCardinalityAttribute(metricAttributes, "trellis.outcome", attributes.outcome);
+    setLowCardinalityAttribute(metricAttributes, "trellis.participant.kind", attributes.participantKind);
+    setLowCardinalityAttribute(metricAttributes, "trellis.session.kind", attributes.sessionKind);
+    setLowCardinalityAttribute(metricAttributes, "trellis.auth.flow", attributes.authFlow);
+    setLowCardinalityAttribute(metricAttributes, "trellis.auth.approval", attributes.authApproval);
+    setLowCardinalityAttribute(metricAttributes, "trellis.plan.classification", attributes.planClassification);
+    setLowCardinalityAttribute(metricAttributes, "trellis.contract.kind", attributes.contractKind);
+    setLowCardinalityAttribute(metricAttributes, "messaging.system", attributes.messagingSystem);
+    setLowCardinalityAttribute(metricAttributes, "messaging.operation", attributes.messagingOperation);
+    if (attributes.authorityPresent !== undefined) {
+        setLowCardinalityAttribute(metricAttributes, "trellis.authority.present", String(attributes.authorityPresent));
+    }
+    return metricAttributes;
+}
+/**
+ * Records one duration measurement on the given Trellis histogram.
+ *
+ * Converts `durationMs` to seconds. Negative, NaN, and infinite values are
+ * silently ignored.
+ *
+ * Histogram instruments are cached by metric name so `createHistogram` is
+ * called at most once per metric name.
+ *
+ * @param name - The duration metric name.
+ * @param durationMs - The measured duration in milliseconds.
+ * @param attributes - Optional low-cardinality attributes. Only values that
+ *   pass sanitization are included.
+ *
+ * @example
+ * ```ts
+ * recordTrellisDuration("trellis.connect.duration", 42.5, {
+ *   phase: "nats_connect",
+ *   outcome: "ok",
+ *   participantKind: "client",
+ * });
+ * ```
+ */
+export function recordTrellisDuration(name, durationMs, attributes) {
+    if (typeof durationMs !== "number" ||
+        durationMs < 0 ||
+        !Number.isFinite(durationMs)) {
+        return;
+    }
+    const histogram = getDurationHistogram(name);
+    const metricAttributes = buildTrellisDurationMetricAttributes(attributes);
+    histogram.record(durationMs / 1000, metricAttributes);
+}
+function getDurationHistogram(name) {
+    let histogram = DURATION_HISTOGRAM_CACHE.get(name);
+    if (!histogram) {
+        histogram = getTrellisMeter().createHistogram(name, {
+            description: histogramDescription(name),
+            unit: "s",
+        });
+        DURATION_HISTOGRAM_CACHE.set(name, histogram);
+    }
+    return histogram;
+}
+function histogramDescription(name) {
+    switch (name) {
+        case "trellis.connect.duration":
+            return "Duration of connection lifecycle phases.";
+        case "trellis.auth.flow.duration":
+            return "Duration of auth flow phases.";
+        case "trellis.auth.approval_resolution.duration":
+            return "Duration of approval resolution phases.";
+        case "trellis.auth.callout.duration":
+            return "Duration of NATS auth callout phases.";
+        case "trellis.admin.workflow.duration":
+            return "Duration of admin workflow phases.";
+        case "trellis.contract.analysis.duration":
+            return "Duration of contract analysis phases.";
+    }
+}
 function trellisErrorType(error, serializable, override) {
     const overrideType = lowCardinalityValue(override);
     if (overrideType)