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

package/script/service/outbox_inbox.js

@@ -14,67 +14,137 @@ var _MemoryOutboxRepository_messages, _MemoryInboxRepository_seen, _OutboxDispat
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OutboxDispatcher = exports.NatsKvInboxRepository = exports.NatsKvOutboxRepository = exports.KvOutboxRecordSchema = exports.SqlInboxRepository = exports.SqlOutboxRepository = exports.MemoryInboxRepository = exports.MemoryOutboxRepository = exports.defaultSqlOutboxTables = void 0;
 exports.createSqlOutboxAdapter = createSqlOutboxAdapter;
+exports.getSqlOutboxMigrations = getSqlOutboxMigrations;
 exports.createSqliteOutboxSchema = createSqliteOutboxSchema;
 exports.createPostgresOutboxSchema = createPostgresOutboxSchema;
 exports.dispatchOutbox = dispatchOutbox;
-exports.outboxMessageToPrepared = outboxMessageToPrepared;
+exports.outboxMessageToPreparedEvent = outboxMessageToPreparedEvent;
+exports.preparedTrellisEventToOutboxRecord = preparedTrellisEventToOutboxRecord;
 const result_1 = require("@qlever-llc/result");
 const typebox_1 = require("typebox");
 const mod_js_1 = require("../telemetry/mod.js");
+/** Default Trellis helper-table names for SQL outbox and inbox storage. */
 exports.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.
  */
 function createSqlOutboxAdapter(executor, dialect, tables = exports.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.
+ */
+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. */
 function createSqliteOutboxSchema(tables = exports.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. */
 function createPostgresOutboxSchema(tables = exports.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 ?? exports.defaultSqlOutboxTables.outbox,
+        inbox: tables?.inbox ?? exports.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. */
 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,
@@ -98,7 +168,7 @@ 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;
@@ -108,6 +178,7 @@ class MemoryOutboxRepository {
             updatedAt: now.toISOString(),
             nextAttemptAt: undefined,
             lastError: undefined,
+            outcome: outcome ?? message.outcome,
         });
     }
     async markFailed(id, failure) {
@@ -165,17 +236,19 @@ 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,
@@ -185,9 +258,10 @@ 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,
@@ -197,15 +271,17 @@ 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)}`, [
@@ -237,8 +313,9 @@ class SqlInboxRepository {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: tables
+            value: void 0
         });
+        this.tables = validateSqlOutboxTables(tables);
     }
     async record(messageId, now = new Date()) {
         try {
@@ -266,7 +343,8 @@ const KvInboxRecordSchema = typebox_1.Type.Object({
 });
 exports.KvOutboxRecordSchema = typebox_1.Type.Object({
     id: typebox_1.Type.String(),
-    event: typebox_1.Type.String(),
+    kind: typebox_1.Type.String(),
+    name: typebox_1.Type.String(),
     subject: typebox_1.Type.String(),
     payload: typebox_1.Type.String(),
     headers: typebox_1.Type.Record(typebox_1.Type.String(), typebox_1.Type.String()),
@@ -281,6 +359,7 @@ exports.KvOutboxRecordSchema = typebox_1.Type.Object({
     updatedAt: typebox_1.Type.String(),
     nextAttemptAt: typebox_1.Type.Optional(typebox_1.Type.String()),
     lastError: typebox_1.Type.Optional(typebox_1.Type.String()),
+    outcome: typebox_1.Type.Optional(typebox_1.Type.String()),
 });
 /** Durable NATS KV outbox repository for services without SQL state. */
 class NatsKvOutboxRepository {
@@ -292,14 +371,15 @@ 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,
@@ -353,19 +433,23 @@ class NatsKvOutboxRepository {
         }
         return claimed;
     }
-    async markDispatched(id, now) {
+    async markDispatched(id, now, outcome) {
         const loaded = await this.kv.get(id).take();
         if ((0, result_1.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 ((0, result_1.isErr)(stored))
             throw stored.error;
@@ -565,7 +649,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. */
 async function dispatchOutbox(repository, runtime, options = {}) {
     const now = options.now ?? new Date();
     const retryDelayMs = options.retryDelayMs ?? 1000;
@@ -573,47 +657,115 @@ 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 ((0, result_1.isErr)(value)) {
-            (0, mod_js_1.recordTrellisError)(value.error, {
+        if (message.kind === "event.publish") {
+            const result = await runtime.publishPreparedEvent(outboxMessageToPreparedEvent(message));
+            const value = result.take();
+            if ((0, result_1.isErr)(value)) {
+                (0, mod_js_1.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 ((0, result_1.isErr)(value)) {
+                    (0, mod_js_1.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 {
+                (0, mod_js_1.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}`;
+            (0, mod_js_1.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. */
-function outboxMessageToPrepared(message) {
+/** Rehydrates a persisted outbox event row into a prepared event. */
+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. */
+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"]),
@@ -623,12 +775,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 },
@@ -638,6 +792,7 @@ function kvRecordToOutboxMessage(record) {
         updatedAt: record.updatedAt,
         nextAttemptAt: record.nextAttemptAt,
         lastError: record.lastError,
+        outcome: record.outcome,
     };
 }
 function placeholder(dialect, index) {
@@ -692,6 +847,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/script/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/script/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"}