@retinue/agentkit 0.1.0

package/dist/telemetry/instrument.js

@@ -0,0 +1,232 @@
+/**
+ * Wiring telemetry to the boundaries — AC-1, AC-2, AC-3.
+ *
+ * The port is inert on its own. These are the wrappers that put it on the path a run actually takes, and they
+ * are **decorators over the existing seams** rather than edits inside them: `instrumentDispatcher` wraps a
+ * `JobDispatcher`, `instrumentConsumer` wraps a `JobConsumer`. Two reasons, and the second is the real one.
+ *
+ * The first is that a deployment without telemetry runs the undecorated object, so telemetry cannot be the
+ * reason a run fails.
+ *
+ * The second is that instrumentation *inside* the dispatcher would put a span around the enqueue and nothing
+ * around the wait between enqueue and claim — which is the number a user actually experiences. Wrapping both
+ * sides is what makes claim latency measurable at all.
+ */
+import { BOUNDARY_SPANS } from "./spans.js";
+import { createRunMetrics } from "./metrics.js";
+import { formatTraceparent, parseTraceparent } from "./trace-context.js";
+import {} from "./index.js";
+import { errorCodeOf, withSpan } from "./index.js";
+/**
+ * Wrap a dispatcher so the enqueue is a span and the job carries the trace forward.
+ *
+ * The traceparent goes down through `enqueueRun`, which #143 widened to accept it. The first version of this
+ * remembered the span it had just opened and let the adapter read it back — which is wrong the moment two
+ * enqueues overlap, and overlapping enqueues are the normal case, not the edge one. A racy trace link is worse
+ * than none: it attributes one tenant's run to another tenant's request.
+ */
+export const instrumentDispatcher = (inner, deps) => {
+    const clock = deps.now ?? (() => Date.now());
+    return {
+        async enqueueRun(input) {
+            await withSpan(deps.telemetry.tracer, BOUNDARY_SPANS.enqueue, {
+                // `producer`, so a collector renders the queue hop as a queue hop rather than as a nested call. The
+                // distinction matters in a trace view: a producer span is expected to end long before its consumer.
+                kind: "producer",
+                // The *caller's* traceparent is this span's parent — the request that is enqueueing. Missing in the
+                // first version, and the end-to-end test caught it immediately: the enqueue span opened its own trace,
+                // so the worker faithfully continued a trace containing nothing but the queue hop. Every span existed,
+                // every parent link was present, and the trace was still useless.
+                ...(input.traceparent !== undefined ? { parent: input.traceparent } : {}),
+                attributes: { tenantId: input.tenantId, runId: input.runId },
+            }, async (span) => {
+                try {
+                    await inner.enqueueRun({
+                        ...input,
+                        // The *enqueue span's* context, not the request's: the consumer's span is a child of this hop, and
+                        // parenting it to the request instead would flatten the queue out of the trace entirely.
+                        traceparent: formatTraceparent(span.context),
+                        enqueuedAt: input.enqueuedAt ?? new Date(clock()).toISOString(),
+                    });
+                }
+                catch (error) {
+                    deps.telemetry.logger.log("error", "run.enqueue-failed", {
+                        tenantId: input.tenantId,
+                        runId: input.runId,
+                        errorCode: errorCodeOf(error),
+                    });
+                    throw error;
+                }
+                deps.telemetry.logger.log("info", "run.enqueued", { tenantId: input.tenantId, runId: input.runId });
+            });
+        },
+    };
+};
+/**
+ * Wrap a consumer so each job continues its producer's trace and claim latency is recorded.
+ *
+ * The handler runs *inside* the claim span, so everything the run does — model calls, tool calls, an approval
+ * wait — is a descendant of it and of the original request. That is AC-1: one user request, one trace, across
+ * three processes.
+ */
+export const instrumentConsumer = (inner, deps) => {
+    const metrics = deps.metrics ?? createRunMetrics(deps.telemetry.meter);
+    const now = deps.now ?? (() => Date.now());
+    const workerId = deps.workerId;
+    return {
+        start(handler) {
+            return inner.start(async (job) => {
+                const parent = parseTraceparent(job.traceparent);
+                const claimedAt = now();
+                // Claim latency, from the producer's stamp. Recorded before the handler runs, so it is reported even if
+                // the run then fails -- a queue backing up and a run failing are different incidents and a metric that
+                // only appeared on success would hide the first behind the second.
+                if (job.enqueuedAt !== undefined) {
+                    const enqueued = Date.parse(job.enqueuedAt);
+                    // Skew between two hosts can make this negative. Dropped rather than clamped to zero: a zero is
+                    // indistinguishable from a genuinely instant claim, and a p99 built from fabricated zeros reads
+                    // healthy. The absence is the honest answer.
+                    if (Number.isFinite(enqueued) && claimedAt >= enqueued)
+                        metrics.claimLatencyMs.record(claimedAt - enqueued, { tenantId: job.tenantId });
+                }
+                await withSpan(deps.telemetry.tracer, BOUNDARY_SPANS.claim, {
+                    // `consumer`, the other half of the producer span. A collector uses the pair to draw the queue hop.
+                    kind: "consumer",
+                    ...(parent !== null ? { parent: job.traceparent } : {}),
+                    attributes: {
+                        tenantId: job.tenantId,
+                        runId: job.runId,
+                        // Whether the trace was actually continued. Without this, a propagation bug looks identical to a
+                        // job that was enqueued before propagation existed, and both look like a working trace.
+                        "queue.trace_continued": parent !== null,
+                        ...(workerId !== undefined ? { workerId } : {}),
+                    },
+                }, async () => {
+                    const logger = deps.telemetry.logger.child({ tenantId: job.tenantId, runId: job.runId });
+                    logger.log("info", "run.claimed", { ...(workerId !== undefined ? { workerId } : {}) });
+                    const startedAt = now();
+                    try {
+                        await handler(job);
+                        metrics.runDurationMs.record(now() - startedAt, { tenantId: job.tenantId, outcome: "completed" });
+                        metrics.runsTotal.record(1, { tenantId: job.tenantId, outcome: "completed" });
+                    }
+                    catch (error) {
+                        const errorCode = errorCodeOf(error);
+                        // Duration on the failure path too. A dashboard built only on successes shows latency improving
+                        // as things break, because the slow runs are the ones that time out.
+                        metrics.runDurationMs.record(now() - startedAt, { tenantId: job.tenantId, outcome: "failed" });
+                        metrics.runsTotal.record(1, { tenantId: job.tenantId, outcome: "failed", errorCode });
+                        logger.log("error", "run.failed", { errorCode });
+                        throw error;
+                    }
+                });
+            });
+        },
+        stop: (graceMs) => inner.stop(graceMs),
+    };
+};
+/**
+ * Time a model call — latency, outcome and the model, with no prompt anywhere near it.
+ *
+ * The attributes are the model id and the outcome. Not the prompt, not the response, not the token *contents* —
+ * the counts are on the usage ledger, which is the place designed to hold them and which is tenant-scoped.
+ */
+export const instrumentModelCall = async (deps, input, call) => {
+    const now = deps.now ?? (() => Date.now());
+    const startedAt = now();
+    return withSpan(deps.telemetry.tracer, BOUNDARY_SPANS.model, {
+        kind: "client",
+        attributes: {
+            tenantId: input.tenantId,
+            modelId: input.modelId,
+            ...(input.runId !== undefined ? { runId: input.runId } : {}),
+            ...(input.providerId !== undefined ? { providerId: input.providerId } : {}),
+        },
+    }, async () => {
+        const attrs = { tenantId: input.tenantId, modelId: input.modelId };
+        try {
+            const result = await call();
+            deps.metrics.modelLatencyMs.record(now() - startedAt, attrs);
+            deps.metrics.modelCallsTotal.record(1, { ...attrs, outcome: "ok" });
+            return result;
+        }
+        catch (error) {
+            deps.metrics.modelLatencyMs.record(now() - startedAt, attrs);
+            deps.metrics.modelCallsTotal.record(1, { ...attrs, outcome: "error", errorCode: errorCodeOf(error) });
+            deps.telemetry.logger.log("warn", "model.failed", {
+                tenantId: input.tenantId,
+                modelId: input.modelId,
+                errorCode: errorCodeOf(error),
+            });
+            throw error;
+        }
+    });
+};
+/** Time a tool call. Same shape, and the same deliberate absence of arguments and results. */
+export const instrumentToolCall = async (deps, input, call) => {
+    const now = deps.now ?? (() => Date.now());
+    const startedAt = now();
+    return withSpan(deps.telemetry.tracer, BOUNDARY_SPANS.tool, {
+        kind: "internal",
+        attributes: {
+            tenantId: input.tenantId,
+            toolName: input.toolName,
+            ...(input.runId !== undefined ? { runId: input.runId } : {}),
+        },
+    }, async () => {
+        const attrs = { tenantId: input.tenantId, toolName: input.toolName };
+        try {
+            const result = await call();
+            deps.metrics.toolLatencyMs.record(now() - startedAt, attrs);
+            deps.metrics.toolCallsTotal.record(1, { ...attrs, outcome: "ok" });
+            return result;
+        }
+        catch (error) {
+            deps.metrics.toolLatencyMs.record(now() - startedAt, attrs);
+            deps.metrics.toolCallsTotal.record(1, { ...attrs, outcome: "error", errorCode: errorCodeOf(error) });
+            deps.telemetry.logger.log("warn", "tool.failed", {
+                tenantId: input.tenantId,
+                toolName: input.toolName,
+                errorCode: errorCodeOf(error),
+            });
+            throw error;
+        }
+    });
+};
+/**
+ * Record how long a run waited for a human.
+ *
+ * Not a wrapper, because the wait is not a function call: the run is *suspended*, the process may have exited,
+ * and the decision arrives in a different request entirely. So this is called when the decision lands, with both
+ * timestamps — the only shape that can measure a wait spanning a deploy.
+ *
+ * Often the longest span in a trace, and the one that most needs to be visibly *not* the platform's latency.
+ */
+export const recordApprovalWait = (deps, input) => {
+    const requested = Date.parse(input.requestedAt);
+    const decided = Date.parse(input.decidedAt);
+    if (Number.isFinite(requested) && Number.isFinite(decided) && decided >= requested)
+        deps.metrics.approvalWaitMs.record(decided - requested, { tenantId: input.tenantId });
+    const span = deps.telemetry.tracer.startSpan(BOUNDARY_SPANS.approvalWait, {
+        kind: "internal",
+        ...(input.traceparent !== undefined ? { parent: input.traceparent } : {}),
+        attributes: {
+            tenantId: input.tenantId,
+            runId: input.runId,
+            interactionId: input.interactionId,
+            decision: input.decision,
+        },
+    });
+    span.setStatus("ok");
+    span.end();
+    deps.telemetry.logger.log("info", "approval.decided", {
+        tenantId: input.tenantId,
+        runId: input.runId,
+        interactionId: input.interactionId,
+        decision: input.decision,
+        ...(Number.isFinite(requested) && Number.isFinite(decided) && decided >= requested
+            ? { waitMs: decided - requested }
+            : {}),
+    });
+};
+//# sourceMappingURL=instrument.js.map

package/dist/telemetry/log-events.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Every log line's name — the structural half of AC-5.
+ *
+ * A logger whose message is a `string` can be handed a prompt. Not by anyone careless: by someone debugging an
+ * incident at midnight who needs to see what the model was asked, ships it, and never removes it. A redaction
+ * denylist does not help, because the content is in the *message*, which a denylist cannot inspect without
+ * pattern-matching prose.
+ *
+ * So the message is a closed union of literals. A caller **cannot** put content in it — there is no string
+ * parameter to put it in. Adding a log line means adding a name here, which is a reviewed act in a file whose
+ * whole purpose is visible from its first line. That is the difference between a rule and a mechanism.
+ *
+ * Named after what happened, in past tense, so a log is readable as a sequence of facts.
+ */
+export declare const LOG_EVENTS: readonly ["request.received", "request.completed", "request.rejected", "run.admitted", "run.refused-quota", "run.refused-authorization", "run.enqueued", "run.enqueue-failed", "run.claimed", "run.claim-contended", "run.lease-expired", "run.reaped", "run.reap-failed", "run.started", "run.checkpointed", "run.completed", "run.failed", "run.cancelled", "run.retry-scheduled", "run.handler-threw", "model.called", "model.failed", "tool.called", "tool.failed", "tool.denied", "approval.requested", "approval.decided", "question.requested", "question.answered", "worker.started", "worker.draining", "worker.stopped", "telemetry.fields-dropped"];
+export type LogEvent = (typeof LOG_EVENTS)[number];
+//# sourceMappingURL=log-events.d.ts.map

package/dist/telemetry/log-events.js

@@ -0,0 +1,58 @@
+/**
+ * Every log line's name — the structural half of AC-5.
+ *
+ * A logger whose message is a `string` can be handed a prompt. Not by anyone careless: by someone debugging an
+ * incident at midnight who needs to see what the model was asked, ships it, and never removes it. A redaction
+ * denylist does not help, because the content is in the *message*, which a denylist cannot inspect without
+ * pattern-matching prose.
+ *
+ * So the message is a closed union of literals. A caller **cannot** put content in it — there is no string
+ * parameter to put it in. Adding a log line means adding a name here, which is a reviewed act in a file whose
+ * whole purpose is visible from its first line. That is the difference between a rule and a mechanism.
+ *
+ * Named after what happened, in past tense, so a log is readable as a sequence of facts.
+ */
+export const LOG_EVENTS = [
+    // Request and admission
+    "request.received",
+    "request.completed",
+    "request.rejected",
+    "run.admitted",
+    "run.refused-quota",
+    "run.refused-authorization",
+    // Queue
+    "run.enqueued",
+    "run.enqueue-failed",
+    "run.claimed",
+    "run.claim-contended",
+    "run.lease-expired",
+    "run.reaped",
+    "run.reap-failed",
+    // Execution
+    "run.started",
+    "run.checkpointed",
+    "run.completed",
+    "run.failed",
+    "run.cancelled",
+    "run.retry-scheduled",
+    "run.handler-threw",
+    // Model and tools
+    "model.called",
+    "model.failed",
+    "tool.called",
+    "tool.failed",
+    "tool.denied",
+    // Human in the loop
+    "approval.requested",
+    "approval.decided",
+    "question.requested",
+    "question.answered",
+    // Process lifecycle
+    "worker.started",
+    "worker.draining",
+    "worker.stopped",
+    // Telemetry's own faults. A dropped field must be visible, or redaction becomes a silent data loss that
+    // nobody notices until an incident needs the field that was being dropped.
+    "telemetry.fields-dropped",
+];
+//# sourceMappingURL=log-events.js.map

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The metric set — AC-3: "metrics answer queue health, latency and error rate without reading logs".
+ *
+ * That criterion is a test of *completeness*, so the instruments are declared as data and `createRunMetrics`
+ * builds a typed recorder for each. A metric name at a call site is a string nothing checks, and the failure is
+ * a dashboard panel that is empty because a name was misspelled once.
+ *
+ * Units are in the names (`_ms`, `_total`) as well as in the metadata, because a graph legend shows the name
+ * and not the unit, and "is 4000 seconds or milliseconds" is the wrong question to be asking during an incident.
+ */
+import type { Attributes, Meter, MetricRecorder } from "./index.js";
+export type InstrumentKind = "counter" | "histogram" | "gauge";
+export type InstrumentSpec = {
+    readonly name: string;
+    readonly kind: InstrumentKind;
+    readonly unit: string;
+    readonly description: string;
+    /**
+     * The operational question this exists to answer.
+     *
+     * Recorded per instrument because "enough to answer 'is it healthy'" is the acceptance criterion, and a metric
+     * with no question behind it is one nobody looks at — while a question with no metric is the gap this field
+     * makes visible.
+     */
+    readonly answers: string;
+};
+export declare const RUN_INSTRUMENTS: {
+    readonly queueDepth: {
+        readonly name: "agentkit_queue_depth";
+        readonly kind: "gauge";
+        readonly unit: "{job}";
+        readonly description: "Jobs waiting on the run queue.";
+        readonly answers: "Is work arriving faster than it is being processed?";
+    };
+    readonly claimLatencyMs: {
+        readonly name: "agentkit_claim_latency_ms";
+        readonly kind: "histogram";
+        readonly unit: "ms";
+        readonly description: "Time from enqueue to a worker claiming the run.";
+        readonly answers: "How long does a user wait before anything starts happening?";
+    };
+    readonly runDurationMs: {
+        readonly name: "agentkit_run_duration_ms";
+        readonly kind: "histogram";
+        readonly unit: "ms";
+        readonly description: "Wall-clock time from claim to a terminal run state.";
+        readonly answers: "Are runs getting slower?";
+    };
+    readonly runsTotal: {
+        readonly name: "agentkit_runs_total";
+        readonly kind: "counter";
+        readonly unit: "{run}";
+        readonly description: "Runs reaching a terminal state, by outcome.";
+        readonly answers: "What fraction of runs fail, and is that changing?";
+    };
+    readonly modelLatencyMs: {
+        readonly name: "agentkit_model_latency_ms";
+        readonly kind: "histogram";
+        readonly unit: "ms";
+        readonly description: "Duration of one model call.";
+        readonly answers: "Is a slow run the provider's fault or ours?";
+    };
+    readonly modelCallsTotal: {
+        readonly name: "agentkit_model_calls_total";
+        readonly kind: "counter";
+        readonly unit: "{call}";
+        readonly description: "Model calls, by outcome and model.";
+        readonly answers: "What is the model error rate, per model?";
+    };
+    readonly toolCallsTotal: {
+        readonly name: "agentkit_tool_calls_total";
+        readonly kind: "counter";
+        readonly unit: "{call}";
+        readonly description: "Tool calls, by outcome and tool.";
+        readonly answers: "Which tool is failing, and how often?";
+    };
+    readonly toolLatencyMs: {
+        readonly name: "agentkit_tool_latency_ms";
+        readonly kind: "histogram";
+        readonly unit: "ms";
+        readonly description: "Duration of one tool call.";
+        readonly answers: "Is a tool the reason runs are slow?";
+    };
+    readonly approvalWaitMs: {
+        readonly name: "agentkit_approval_wait_ms";
+        readonly kind: "histogram";
+        readonly unit: "ms";
+        readonly description: "Time a run spent waiting for a human decision.";
+        readonly answers: "Are approvals the bottleneck rather than the platform?";
+    };
+    readonly retriesTotal: {
+        readonly name: "agentkit_retries_total";
+        readonly kind: "counter";
+        readonly unit: "{retry}";
+        readonly description: "Retry attempts, by reason.";
+        readonly answers: "Is a provider degrading before it starts failing outright?";
+    };
+};
+export type RunInstrumentKey = keyof typeof RUN_INSTRUMENTS;
+export type RunMetrics = Readonly<Record<RunInstrumentKey, MetricRecorder>>;
+/**
+ * Build every instrument once.
+ *
+ * Once, at wiring time, rather than per call: an OTel meter deduplicates by name, but a port implementation need
+ * not, and creating an instrument inside a hot path is how a metrics backend acquires a million series.
+ */
+export declare const createRunMetrics: (meter: Meter) => RunMetrics;
+/**
+ * The attribute set a metric may carry.
+ *
+ * Bounded on purpose, and this is the important part: every metric attribute multiplies the series count, and
+ * an unbounded one — a run id, a conversation id, a user id — is how a metrics bill becomes the largest line in
+ * an infrastructure budget. Ids belong on **spans and logs**, which are sampled and indexed, never on metrics.
+ */
+export declare const METRIC_ATTRIBUTE_ALLOWLIST: readonly string[];
+/**
+ * Drop unbounded attributes before recording.
+ *
+ * Applied by the adapter, not trusted to call sites. `runId` on a latency histogram is one line of code and one
+ * series per run — it looks like helpful detail in review and is a cardinality incident in production.
+ */
+export declare const boundMetricAttributes: (attributes: Attributes | undefined) => Attributes;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/telemetry/metrics.js

@@ -0,0 +1,135 @@
+/**
+ * The metric set — AC-3: "metrics answer queue health, latency and error rate without reading logs".
+ *
+ * That criterion is a test of *completeness*, so the instruments are declared as data and `createRunMetrics`
+ * builds a typed recorder for each. A metric name at a call site is a string nothing checks, and the failure is
+ * a dashboard panel that is empty because a name was misspelled once.
+ *
+ * Units are in the names (`_ms`, `_total`) as well as in the metadata, because a graph legend shows the name
+ * and not the unit, and "is 4000 seconds or milliseconds" is the wrong question to be asking during an incident.
+ */
+export const RUN_INSTRUMENTS = {
+    queueDepth: {
+        name: "agentkit_queue_depth",
+        kind: "gauge",
+        unit: "{job}",
+        description: "Jobs waiting on the run queue.",
+        answers: "Is work arriving faster than it is being processed?",
+    },
+    claimLatencyMs: {
+        name: "agentkit_claim_latency_ms",
+        kind: "histogram",
+        unit: "ms",
+        description: "Time from enqueue to a worker claiming the run.",
+        answers: "How long does a user wait before anything starts happening?",
+    },
+    runDurationMs: {
+        name: "agentkit_run_duration_ms",
+        kind: "histogram",
+        unit: "ms",
+        description: "Wall-clock time from claim to a terminal run state.",
+        answers: "Are runs getting slower?",
+    },
+    runsTotal: {
+        name: "agentkit_runs_total",
+        kind: "counter",
+        unit: "{run}",
+        description: "Runs reaching a terminal state, by outcome.",
+        answers: "What fraction of runs fail, and is that changing?",
+    },
+    modelLatencyMs: {
+        name: "agentkit_model_latency_ms",
+        kind: "histogram",
+        unit: "ms",
+        description: "Duration of one model call.",
+        answers: "Is a slow run the provider's fault or ours?",
+    },
+    modelCallsTotal: {
+        name: "agentkit_model_calls_total",
+        kind: "counter",
+        unit: "{call}",
+        description: "Model calls, by outcome and model.",
+        answers: "What is the model error rate, per model?",
+    },
+    toolCallsTotal: {
+        name: "agentkit_tool_calls_total",
+        kind: "counter",
+        unit: "{call}",
+        description: "Tool calls, by outcome and tool.",
+        answers: "Which tool is failing, and how often?",
+    },
+    toolLatencyMs: {
+        name: "agentkit_tool_latency_ms",
+        kind: "histogram",
+        unit: "ms",
+        description: "Duration of one tool call.",
+        answers: "Is a tool the reason runs are slow?",
+    },
+    approvalWaitMs: {
+        name: "agentkit_approval_wait_ms",
+        kind: "histogram",
+        unit: "ms",
+        description: "Time a run spent waiting for a human decision.",
+        answers: "Are approvals the bottleneck rather than the platform?",
+    },
+    retriesTotal: {
+        name: "agentkit_retries_total",
+        kind: "counter",
+        unit: "{retry}",
+        description: "Retry attempts, by reason.",
+        answers: "Is a provider degrading before it starts failing outright?",
+    },
+};
+/**
+ * Build every instrument once.
+ *
+ * Once, at wiring time, rather than per call: an OTel meter deduplicates by name, but a port implementation need
+ * not, and creating an instrument inside a hot path is how a metrics backend acquires a million series.
+ */
+export const createRunMetrics = (meter) => {
+    const build = (spec) => {
+        const options = { unit: spec.unit, description: spec.description };
+        if (spec.kind === "counter")
+            return meter.counter(spec.name, options);
+        if (spec.kind === "histogram")
+            return meter.histogram(spec.name, options);
+        return meter.gauge(spec.name, options);
+    };
+    const out = {};
+    for (const [key, spec] of Object.entries(RUN_INSTRUMENTS))
+        out[key] = build(spec);
+    return out;
+};
+/**
+ * The attribute set a metric may carry.
+ *
+ * Bounded on purpose, and this is the important part: every metric attribute multiplies the series count, and
+ * an unbounded one — a run id, a conversation id, a user id — is how a metrics bill becomes the largest line in
+ * an infrastructure budget. Ids belong on **spans and logs**, which are sampled and indexed, never on metrics.
+ */
+export const METRIC_ATTRIBUTE_ALLOWLIST = [
+    "tenantId",
+    "outcome",
+    "errorCode",
+    "toolName",
+    "modelId",
+    "providerId",
+    "reason",
+];
+const METRIC_ALLOWED = new Set(METRIC_ATTRIBUTE_ALLOWLIST);
+/**
+ * Drop unbounded attributes before recording.
+ *
+ * Applied by the adapter, not trusted to call sites. `runId` on a latency histogram is one line of code and one
+ * series per run — it looks like helpful detail in review and is a cardinality incident in production.
+ */
+export const boundMetricAttributes = (attributes) => {
+    if (attributes === undefined)
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(attributes))
+        if (METRIC_ALLOWED.has(key))
+            out[key] = value;
+    return out;
+};
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/noop.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Telemetry that does nothing, and the in-memory telemetry the tests assert on.
+ *
+ * `NOOP_TELEMETRY` is why no call site has an `if (telemetry)`. Optional-and-checked would be checked in
+ * nineteen places and forgotten in the twentieth, and the forgotten one is a crash rather than a missing span.
+ *
+ * `createRecordingTelemetry` is the same port over arrays. It is what makes AC-1, AC-2 and AC-5 assertable
+ * without a collector: the redaction test needs to see the *actual bytes* a sink would write, and a mock that
+ * captured the call arguments would prove the caller's intent rather than the output.
+ */
+import type { Attributes, LogRecord, Span, SpanStatus, Telemetry, TelemetryContext } from "./index.js";
+export declare const NOOP_TELEMETRY: Telemetry;
+export type RecordedSpan = {
+    readonly name: string;
+    readonly kind: string;
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | null;
+    attributes: Record<string, string | number | boolean>;
+    status: SpanStatus;
+    errorCode: string | null;
+    ended: boolean;
+};
+export type RecordedMetric = {
+    readonly instrument: string;
+    readonly value: number;
+    readonly attributes: Attributes;
+};
+export type RecordingTelemetry = Telemetry & {
+    readonly spans: readonly RecordedSpan[];
+    readonly metrics: readonly RecordedMetric[];
+    readonly logs: readonly LogRecord[];
+    /** The bytes a sink would write. The redaction test asserts on these, not on the records. */
+    readonly lines: readonly string[];
+};
+export declare const createRecordingTelemetry: (base?: TelemetryContext, now?: () => string) => RecordingTelemetry;
+/** The traceparent for a span, for putting into a job payload or an outbound header. */
+export declare const traceparentOf: (span: Span) => string;
+//# sourceMappingURL=noop.d.ts.map