cli-jaw 2.2.25 → 2.3.0

package/dist/src/messaging/effect-once.js

@@ -0,0 +1,204 @@
+// ─── Effect-once claims ──────────────────────────────────
+// At-least-once ingress means a protected effect can be reached twice. This table is
+// how the second arrival learns the first one already happened.
+//
+// A lease that has run out does NOT mean the effect failed. The owning process may
+// have died a millisecond before or a millisecond after the external write. Expiry
+// therefore permits a new CLAIM and nothing else; deciding what actually happened is
+// a per-effect reconciler's job, and until it decides, `manual` is the honest state.
+//
+// The connection is injected for the same reason the journal injects it: reaching for
+// the db singleton makes the table exist as a side effect of whoever imported first.
+import { randomUUID } from 'node:crypto';
+import { registerChildRetentionPredicate } from './durable-ingress.js';
+export const EFFECT_CLAIMS_TABLE = 'effect_claims';
+/** Local DB writes: a process that holds one this long is not coming back. */
+export const LOCAL_EFFECT_LEASE_MS = 30_000;
+/** Process spawn and remote tool calls legitimately take longer. */
+export const REMOTE_EFFECT_LEASE_MS = 120_000;
+export const CREATE_EFFECT_CLAIMS_SQL = `
+CREATE TABLE IF NOT EXISTS effect_claims (
+    channel          TEXT NOT NULL CHECK(channel IN ('telegram', 'slack', 'discord')),
+    account_id       TEXT NOT NULL,
+    event_id         TEXT NOT NULL,
+    effect_name      TEXT NOT NULL,
+    claim_token      TEXT NOT NULL UNIQUE,
+    state            TEXT NOT NULL DEFAULT 'claimed'
+                     CHECK(state IN ('claimed', 'completed', 'failed', 'manual')),
+    owner_id         TEXT,
+    lease_expires_at INTEGER,
+    result_digest    TEXT,
+    claimed_at       INTEGER NOT NULL,
+    completed_at     INTEGER,
+    last_error       TEXT,
+    PRIMARY KEY (channel, account_id, event_id, effect_name),
+    FOREIGN KEY (channel, account_id, event_id)
+        REFERENCES ingress_events(channel, account_id, event_id)
+);
+CREATE INDEX IF NOT EXISTS idx_effect_claims_state
+    ON effect_claims (state, claimed_at);
+`;
+const STATES = new Set(['claimed', 'completed', 'failed', 'manual']);
+function rowToRecord(row) {
+    const state = String(row['state']);
+    if (!STATES.has(state)) {
+        // Refused on read rather than guessed at: an unknown state here would otherwise
+        // be treated as "not terminal" and re-claimed.
+        throw new Error(`effect claims: unrecognised state ${JSON.stringify(state)}`);
+    }
+    return {
+        channel: String(row['channel']),
+        accountId: String(row['account_id']),
+        eventId: String(row['event_id']),
+        effectName: String(row['effect_name']),
+        claimToken: String(row['claim_token']),
+        state: state,
+        ownerId: row['owner_id'] ?? null,
+        leaseExpiresAt: row['lease_expires_at'] ?? null,
+        resultDigest: row['result_digest'] ?? null,
+        claimedAt: Number(row['claimed_at']),
+        completedAt: row['completed_at'] ?? null,
+        lastError: row['last_error'] ?? null,
+    };
+}
+export class EffectClaimStore {
+    database;
+    now;
+    ownerId;
+    constructor(database, options = {}) {
+        this.database = database;
+        this.now = options.now ?? (() => Date.now());
+        this.ownerId = options.ownerId ?? `${randomUUID()}:${randomUUID()}`;
+        this.database.exec(CREATE_EFFECT_CLAIMS_SQL);
+        registerChildRetentionPredicate({
+            table: EFFECT_CLAIMS_TABLE,
+            // A claim that has not reached a terminal state still describes work whose
+            // outcome nobody knows. Sweeping its parent would erase the only record.
+            blockingExistsSql: "SELECT 1 FROM effect_claims c WHERE c.channel = e.channel "
+                + "AND c.account_id = e.account_id AND c.event_id = e.event_id "
+                + "AND c.state NOT IN ('completed', 'failed')",
+            deleteTerminalSql: "DELETE FROM effect_claims WHERE channel = ? AND account_id = ? "
+                + "AND event_id = ? AND state IN ('completed', 'failed')",
+        });
+    }
+    get owner() { return this.ownerId; }
+    find(key) {
+        const row = this.database.prepare(`
+            SELECT * FROM effect_claims
+            WHERE channel = ? AND account_id = ? AND event_id = ? AND effect_name = ?
+        `).get(key.channel, key.accountId, key.eventId, key.effectName);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * Take ownership of one effect, or report why not.
+     *
+     * BEGIN IMMEDIATE plus an observed-token CAS is what makes two live workers safe:
+     * both can read the same expired row, only one can write it, and the loser sees
+     * `lease_held` rather than running the effect body a second time.
+     */
+    claim(key, leaseMs = LOCAL_EFFECT_LEASE_MS) {
+        const run = this.database.transaction(() => {
+            const now = this.now();
+            const existing = this.find(key);
+            if (!existing) {
+                const claimToken = randomUUID();
+                this.database.prepare(`
+                    INSERT INTO effect_claims (
+                        channel, account_id, event_id, effect_name, claim_token,
+                        state, owner_id, lease_expires_at, claimed_at
+                    ) VALUES (?, ?, ?, ?, ?, 'claimed', ?, ?, ?)
+                `).run(key.channel, key.accountId, key.eventId, key.effectName, claimToken, this.ownerId, now + leaseMs, now);
+                const record = this.find(key);
+                if (!record)
+                    throw new Error('effect claims: claim did not persist');
+                return { acquired: true, claimToken, record };
+            }
+            if (existing.state !== 'claimed') {
+                // completed/failed/manual are all answers. Only an operator or a replay
+                // may reopen one, and neither goes through this path.
+                return { acquired: false, reason: 'terminal', record: existing };
+            }
+            if (existing.leaseExpiresAt !== null && existing.leaseExpiresAt > now) {
+                return { acquired: false, reason: 'lease_held', record: existing };
+            }
+            const claimToken = randomUUID();
+            const changes = this.database.prepare(`
+                UPDATE effect_claims
+                SET owner_id = ?, claim_token = ?, claimed_at = ?, lease_expires_at = ?, last_error = NULL
+                WHERE channel = ? AND account_id = ? AND event_id = ? AND effect_name = ?
+                  AND state = 'claimed' AND claim_token = ?
+            `).run(this.ownerId, claimToken, now, now + leaseMs, key.channel, key.accountId, key.eventId, key.effectName, existing.claimToken).changes;
+            if (changes !== 1) {
+                const latest = this.find(key);
+                return { acquired: false, reason: 'lease_held', record: latest ?? existing };
+            }
+            const record = this.find(key);
+            if (!record)
+                throw new Error('effect claims: re-claim did not persist');
+            return { acquired: true, claimToken, record };
+        });
+        return run.immediate();
+    }
+    /** Extend a lease this worker still owns. Long effects heartbeat rather than
+     *  taking a lease long enough to hide a dead process. */
+    heartbeat(key, claimToken, leaseMs = LOCAL_EFFECT_LEASE_MS) {
+        return this.database.prepare(`
+            UPDATE effect_claims SET lease_expires_at = ?
+            WHERE channel = ? AND account_id = ? AND event_id = ? AND effect_name = ?
+              AND state = 'claimed' AND owner_id = ? AND claim_token = ?
+        `).run(this.now() + leaseMs, key.channel, key.accountId, key.eventId, key.effectName, this.ownerId, claimToken).changes === 1;
+    }
+    settle(key, claimToken, state, extra = {}) {
+        const run = this.database.transaction(() => this.database.prepare(`
+            UPDATE effect_claims
+            SET state = ?, completed_at = ?, lease_expires_at = NULL,
+                result_digest = COALESCE(?, result_digest),
+                last_error = ?
+            WHERE channel = ? AND account_id = ? AND event_id = ? AND effect_name = ?
+              AND state = 'claimed' AND owner_id = ? AND claim_token = ?
+        `).run(state, this.now(), extra.resultDigest ?? null, extra.lastError ?? null, key.channel, key.accountId, key.eventId, key.effectName, this.ownerId, claimToken).changes === 1);
+        return run.immediate();
+    }
+    /** The external effect is known to have happened. */
+    complete(key, claimToken, resultDigest) {
+        return this.settle(key, claimToken, 'completed', resultDigest === undefined ? {} : { resultDigest });
+    }
+    /** Known NOT to have happened, so a later replay may legitimately retry it. */
+    fail(key, claimToken, lastError) {
+        return this.settle(key, claimToken, 'failed', { lastError });
+    }
+    /** Cannot be decided automatically. Terminal until an operator says otherwise;
+     *  guessing here is how a payment sends twice or a reset silently does not. */
+    holdForManual(key, claimToken, lastError) {
+        return this.settle(key, claimToken, 'manual', { lastError });
+    }
+    list(filter = {}) {
+        const where = filter.state ? 'WHERE state = ?' : '';
+        const params = filter.state ? [filter.state] : [];
+        params.push(filter.limit ?? 50);
+        const rows = this.database.prepare(`SELECT * FROM effect_claims ${where} ORDER BY claimed_at DESC LIMIT ?`).all(...params);
+        return rows.map(rowToRecord);
+    }
+    /** Rows whose lease has run out. Candidates for a reconciler, not for a re-run. */
+    listExpired(now = this.now(), limit = 50) {
+        const rows = this.database.prepare(`
+            SELECT * FROM effect_claims
+            WHERE state = 'claimed' AND lease_expires_at IS NOT NULL AND lease_expires_at <= ?
+            ORDER BY lease_expires_at, claimed_at LIMIT ?
+        `).all(now, limit);
+        return rows.map(rowToRecord);
+    }
+}
+let store = null;
+export function initEffectClaimStore(database, options = {}) {
+    store = new EffectClaimStore(database, options);
+    return store;
+}
+export function getEffectClaimStore() {
+    return store;
+}
+/** Test seam: the module-level handle outlives a single test otherwise. */
+export function __resetEffectClaimStoreForTests() {
+    store = null;
+}
+//# sourceMappingURL=effect-once.js.map

package/dist/src/messaging/effect-once.js.map

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

package/dist/src/messaging/inbound-envelope.js

@@ -0,0 +1,168 @@
+// ─── Inbound Envelope Normalizers ────────────────────
+// One pure function per vendor, turning a vendor inbound event into an
+// `InboundEnvelope`. Nothing here reaches a network, a clock it was not handed,
+// or a vendor SDK: the transport handler collects the fields it already has and
+// calls in.
+//
+// Deliberately NOT importing `src/telegram/bot.ts`, `src/slack/bot.ts` or
+// `src/discord/bot.ts`. Those modules run at import time (bot singletons, dedupe
+// stores, prepared SQLite statements) and drag in the vendor SDKs — discord.js
+// alone costs ~48MB RSS. A normalizer that cannot be imported without starting a
+// transport is not testable, so the inputs are narrow structural types declared
+// locally instead.
+//
+// Every function returns `null` when a required field cannot be determined. The
+// caller treats null as "do not admit this event". Fabricating a placeholder
+// (`'unknown'`, `0`, `''`) would be worse than dropping: `accountId` namespaces
+// the ingress journal, so a fake one silently merges two workspaces' event keys.
+/** Build the opaque correlation handle for logs and traces.
+ *
+ *  It exists to join a core-side log line back to a vendor delivery when
+ *  debugging, and that is ALL it may carry. Never put a token, a message body, a
+ *  file name or an attachment URL in here: this string is written to logs and
+ *  traces that are not redacted downstream and are routinely pasted into issues.
+ *  Vendor ids are safe because they are meaningless without the credential. */
+const rawRef = (kind, id) => `${kind}:${id}`;
+/**
+ * Telegram: `receivedAt` comes from the adapter clock, not the update.
+ *
+ * A Telegram update does carry `message.date`, but this tree never extracts it —
+ * no handler reads it and no existing field is derived from it. It is also a SEND
+ * time in whole seconds, not a receive time, and it is absent on several update
+ * kinds this path admits. Deriving `receivedAt` from it would silently change
+ * meaning per update type, so the honest value is the moment this process
+ * observed the update. The clock is injectable purely so tests are deterministic.
+ */
+export function telegramInboundEnvelope(input) {
+    const accountId = idString(input.botUserId);
+    const eventId = idString(input.updateId);
+    const chatId = idString(input.chatId);
+    const actorId = idString(input.fromId);
+    if (!accountId || !eventId || !chatId || !actorId)
+        return null;
+    if (input.target.channel !== 'telegram')
+        return null;
+    const threadKey = telegramThreadKey(input);
+    return {
+        channel: 'telegram',
+        accountId,
+        eventId,
+        conversationKey: `telegram:${chatId}`,
+        ...(threadKey ? { threadKey } : {}),
+        actorId,
+        receivedAt: (input.now ?? Date.now)(),
+        // Telegram's polling offset only advances once the reply is delivered, so a
+        // crash mid-run redelivers the update. A transport property, not a setting.
+        ackPolicy: 'after-final-delivery',
+        rawEnvelopeRef: rawRef('telegram:update', eventId),
+        target: input.target,
+    };
+}
+/** Topic id 1 is the forum's General topic, which is the chat itself rather than a
+ *  distinct thread. `buildTelegramTarget` excludes it from `threadId`; excluding it
+ *  here too keeps `threadKey` and `target.threadId` from disagreeing. */
+function telegramThreadKey(input) {
+    if (!input.isTopicMessage)
+        return undefined;
+    const raw = input.messageThreadId;
+    if (raw == null)
+        return undefined;
+    const numeric = Number(raw);
+    if (!Number.isFinite(numeric) || numeric <= 1)
+        return undefined;
+    return String(raw);
+}
+/**
+ * Slack: `receivedAt` is derived from `event.ts`, which unlike the other two
+ * vendors IS a canonical event time (epoch seconds with microsecond fraction).
+ * An unparseable ts drops the event rather than falling back to the local clock —
+ * `ts` is also the event identity, so a ts we cannot read means we cannot dedupe.
+ */
+export function slackInboundEnvelope(input) {
+    const accountId = (input.teamId ?? '').trim();
+    const channelId = (input.channelId ?? '').trim();
+    const ts = (input.ts ?? '').trim();
+    const actorId = (input.userId ?? '').trim() || (input.botId ?? '').trim();
+    if (!accountId || !channelId || !ts || !actorId)
+        return null;
+    if (input.target.channel !== 'slack')
+        return null;
+    const receivedAt = Number(ts) * 1000;
+    if (!Number.isFinite(receivedAt))
+        return null;
+    // Same shape as `slackEventKey` in src/slack/ingress.ts, the source of truth for
+    // the ingress dedupe key. Reimplemented rather than imported because that module
+    // opens the SQLite dedupe store at import time. Its `'unknown'` team fallback is
+    // unreachable from here: an empty team already returned null.
+    const eventId = `${accountId}:${channelId}:${ts}`;
+    const threadTs = (input.threadTs ?? '').trim();
+    // The PARENT ts identifies the thread. A top-level message has none, so its own
+    // ts becomes the parent of the thread a reply would open (see
+    // `resolveSlackThreadTs`). With replyInThread off no thread is opened at all.
+    const threadKey = threadTs || (input.replyInThread !== false ? ts : '');
+    const envelopeId = (input.envelopeId ?? '').trim();
+    return {
+        channel: 'slack',
+        accountId,
+        eventId,
+        conversationKey: `slack:${accountId}:${channelId}`,
+        ...(threadKey ? { threadKey } : {}),
+        actorId,
+        receivedAt,
+        // Socket Mode still requires an ack within 3s, but the ack is now held
+        // until this event is durably recorded. Acking first would let a crash
+        // between ack and journal lose a message Slack considers delivered.
+        ackPolicy: 'after-durable-append',
+        ...(envelopeId ? { rawEnvelopeRef: rawRef('slack:envelope', envelopeId) } : {}),
+        target: input.target,
+    };
+}
+/**
+ * Discord: `receivedAt` comes from the adapter clock for the same reason as
+ * Telegram. discord.js exposes `msg.createdTimestamp`, but this tree extracts it
+ * nowhere, and it is derived from the snowflake's CREATION time — for an edited or
+ * gateway-replayed message that can sit far from when we received it. Rather than
+ * guess which one the ingress journal means, record when we observed it.
+ */
+export function discordInboundEnvelope(input) {
+    const accountId = (input.botUserId ?? '').trim();
+    const eventId = (input.messageId ?? '').trim();
+    const channelId = (input.channelId ?? '').trim();
+    const actorId = (input.authorId ?? '').trim();
+    if (!accountId || !eventId || !channelId || !actorId)
+        return null;
+    if (input.target.channel !== 'discord')
+        return null;
+    // A DM has no guild. 'dm' occupies the guild slot so a DM conversation key can
+    // never collide with a guild id, and stays readable in a log line.
+    const guildId = (input.guildId ?? '').trim() || 'dm';
+    // In a thread the channel id IS the thread id, so the parent channel identifies
+    // the conversation (mirrors `buildDiscordTarget`).
+    const parentId = (input.parentId ?? '').trim();
+    const conversationId = input.isThread ? (parentId || channelId) : channelId;
+    return {
+        channel: 'discord',
+        accountId,
+        eventId,
+        conversationKey: `discord:${guildId}:${conversationId}`,
+        ...(input.isThread ? { threadKey: channelId } : {}),
+        actorId,
+        receivedAt: (input.now ?? Date.now)(),
+        // The gateway acks on its own schedule, outside this process's control.
+        ackPolicy: 'transport-managed',
+        rawEnvelopeRef: rawRef('discord:message', eventId),
+        target: input.target,
+    };
+}
+/** Telegram ids arrive as numbers on the wire and as strings everywhere in this
+ *  tree. Rejects the empty string and non-finite numbers so a bad id drops the
+ *  event instead of producing `'NaN'` or `'undefined'` as a key fragment. */
+function idString(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+//# sourceMappingURL=inbound-envelope.js.map

package/dist/src/messaging/inbound-envelope.js.map

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

package/dist/src/messaging/ingress-audit.js

@@ -0,0 +1,41 @@
+// ─── Ingress replay audit trail ──────────────────────
+// A replay re-runs somebody's message. Who asked, why, and what state it was in
+// beforehand are the facts you want when the same message turns up twice and nobody
+// remembers touching it — so they are written before anyone can be asked.
+//
+// Append-only JSONL rather than a table: this is evidence, and a file that is only
+// ever appended to is harder to quietly revise than a row that can be updated.
+import fs from 'node:fs';
+import path from 'node:path';
+import { JAW_HOME } from '../core/config.js';
+export function ingressAuditPath() {
+    return path.join(JAW_HOME, 'messaging-ingress-audit.jsonl');
+}
+export function appendIngressAudit(entry) {
+    const file = ingressAuditPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+}
+/** Most recent first. A malformed line is skipped rather than failing the read: a
+ *  partially written tail must not hide the history before it. */
+export function readIngressAudit(limit = 20) {
+    const file = ingressAuditPath();
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch { /* skip a torn line, keep the rest */ }
+    }
+    return entries.reverse().slice(0, limit);
+}
+//# sourceMappingURL=ingress-audit.js.map

package/dist/src/messaging/ingress-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingress-audit.js","sourceRoot":"","sources":["../../../src/messaging/ingress-audit.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,gFAAgF;AAChF,oFAAoF;AACpF,0EAA0E;AAC1E,EAAE;AACF,mFAAmF;AACnF,+EAA+E;AAE/E,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAc7C,MAAM,UAAU,gBAAgB;IAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,+BAA+B,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IACvD,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAC;IAChC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;kEACkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,KAAK,GAAG,EAAE;IACvC,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAC;IAChC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QAAC,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAAC,CAAC;IAC5C,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;IACpB,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,CAAC;YAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAsB,CAAC,CAAC;QAAC,CAAC;QAC5D,MAAM,CAAC,CAAC,qCAAqC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC"}

package/dist/src/messaging/ingress-generation.js

@@ -0,0 +1,22 @@
+// Current chat_sessions.generation for an inbound envelope.
+//
+// Envelope.conversationKey is a routing key (`telegram:123`), not
+// remote_session_bindings.remote_key (`jaw:telegram:...`). Look up through
+// buildRemoteBindingKey(target). Missing binding or an uninitialized
+// session-generation store is generation 0 — same as a brand-new session.
+import { buildRemoteBindingKey } from './session-key.js';
+import { getRemoteBoundSessionId } from '../core/chat-sessions.js';
+import { readSessionGeneration } from '../core/session-generation.js';
+export function currentGenerationForEnvelope(envelope) {
+    try {
+        const remoteKey = buildRemoteBindingKey(envelope.target);
+        const sessionId = getRemoteBoundSessionId(remoteKey);
+        if (!sessionId)
+            return 0;
+        return readSessionGeneration({ chatSessionId: sessionId, conversationKey: remoteKey });
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=ingress-generation.js.map

package/dist/src/messaging/ingress-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingress-generation.js","sourceRoot":"","sources":["../../../src/messaging/ingress-generation.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,kEAAkE;AAClE,2EAA2E;AAC3E,qEAAqE;AACrE,0EAA0E;AAE1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,MAAM,UAAU,4BAA4B,CAAC,QAAyB;IAClE,IAAI,CAAC;QACD,MAAM,SAAS,GAAG,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,CAAC;QACzB,OAAO,qBAAqB,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,CAAC,CAAC;IACb,CAAC;AACL,CAAC"}

package/dist/src/messaging/metrics.js

@@ -0,0 +1,69 @@
+// In-process messaging metrics.
+//
+// Labels are a closed set. Actor, event, conversation, and session ids are
+// high-cardinality and belong on the trace, not here. There is no exporter
+// in this cycle — snapshot() is what health/doctor read.
+export const METRIC_LABEL_KEYS = ['channel', 'state', 'result'];
+const ALLOWED = new Set(METRIC_LABEL_KEYS);
+const counters = new Map();
+const histograms = new Map();
+function sanitizeLabels(labels) {
+    const out = {};
+    if (!labels)
+        return out;
+    for (const key of METRIC_LABEL_KEYS) {
+        const value = labels[key];
+        if (typeof value === 'string' && value.length > 0)
+            out[key] = value;
+    }
+    return out;
+}
+function seriesKey(name, labels) {
+    const parts = [name];
+    for (const key of METRIC_LABEL_KEYS) {
+        if (labels[key])
+            parts.push(`${key}=${labels[key]}`);
+    }
+    return parts.join('|');
+}
+export function inc(name, labels = {}, by = 1) {
+    if (!Number.isFinite(by) || by === 0)
+        return;
+    const safe = sanitizeLabels(labels);
+    const key = seriesKey(name, safe);
+    const existing = counters.get(key);
+    if (existing) {
+        existing.value += by;
+        return;
+    }
+    counters.set(key, { name, labels: safe, value: by });
+}
+export function observe(name, value, labels = {}) {
+    if (!Number.isFinite(value))
+        return;
+    const safe = sanitizeLabels(labels);
+    const key = seriesKey(name, safe);
+    const existing = histograms.get(key);
+    if (existing) {
+        existing.count += 1;
+        existing.sum += value;
+        existing.min = Math.min(existing.min, value);
+        existing.max = Math.max(existing.max, value);
+        return;
+    }
+    histograms.set(key, { name, labels: safe, count: 1, sum: value, min: value, max: value });
+}
+export function snapshotMetrics() {
+    return {
+        counters: [...counters.values()].map((row) => ({ ...row, labels: { ...row.labels } })),
+        histograms: [...histograms.values()].map((row) => ({ ...row, labels: { ...row.labels } })),
+    };
+}
+/** Test seam: the registry is process-global. */
+export function __resetMessagingMetricsForTests() {
+    counters.clear();
+    histograms.clear();
+}
+// Keep the unused set referenced so a future label cannot be added silently.
+void ALLOWED;
+//# sourceMappingURL=metrics.js.map

package/dist/src/messaging/metrics.js.map

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