@retinue/agentkit 0.1.0

package/dist/adapters/memory/usage.js

@@ -0,0 +1,279 @@
+import { bucketStartFor, nextBucket } from "../../usage/quota.js";
+import { usageDedupeKey } from "../../usage/index.js";
+const ZERO_TOTALS = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cachedInputTokens: 0,
+    reasoningTokens: 0,
+    costMinorUnits: 0,
+    eventCount: 0,
+};
+// Imported from the port (#100) rather than defined here, so the Postgres adapter cannot drift.
+/**
+ * The ledger and its rollups over one set of rows (#139).
+ *
+ * One backend, because a rollup is *derived* from the ledger and nothing else — deriving it from a second copy
+ * of the events would make the two able to disagree, which is the one thing a spend figure must not do.
+ */
+export const createMemoryUsageBackend = (options = {}) => {
+    const clock = options.clock ?? (() => new Date().toISOString());
+    // tenantId → (dedupeKey → event). Partitioning by tenant makes cross-tenant reads impossible.
+    const byTenant = new Map();
+    const tenant = (t) => {
+        let m = byTenant.get(t);
+        if (!m)
+            byTenant.set(t, (m = new Map()));
+        return m;
+    };
+    /**
+     * When we learned about each event, keyed the same way as the event.
+     *
+     * Distinct from `occurredAt`: an event can be recorded late — a delayed provider report, a recovered run
+     * replaying its steps — with an `occurredAt` in the past. Staleness judged by `occurredAt` would see its
+     * bucket as already computed and never roll it up, which is a silent undercount.
+     *
+     * A monotonic counter rather than a clock, so two events recorded in the same millisecond still order — and
+     * so a test needs no injected clock to observe the property.
+     */
+    const recordedAt = new Map();
+    let recordSequence = 0;
+    const usage = {
+        async append({ tenantId, event }) {
+            const rows = tenant(tenantId);
+            const key = usageDedupeKey(event);
+            if (rows.has(key))
+                return; // idempotent: a re-recorded step is a no-op
+            rows.set(key, event);
+            recordedAt.set(`${tenantId} ${key}`, (recordSequence += 1));
+        },
+        async listByRun({ tenantId, runId, limit, cursor }) {
+            const all = [...tenant(tenantId).values()]
+                .filter((e) => e.runId === runId)
+                .sort((a, b) => (a.occurredAt < b.occurredAt ? -1 : a.occurredAt > b.occurredAt ? 1 : a.id < b.id ? -1 : 1));
+            const start = cursor ? all.findIndex((e) => e.id === cursor) + 1 : 0;
+            const items = all.slice(start, start + limit);
+            const nextCursor = start + limit < all.length ? items[items.length - 1]?.id : undefined;
+            const page = nextCursor === undefined ? { items } : { items, nextCursor };
+            return page;
+        },
+        async breakdown({ tenantId, from, to, by, limit }) {
+            const scoped = [...tenant(tenantId).values()].filter(
+            // Half-open, like every other range in this codebase, so adjacent periods tile without a boundary
+            // event appearing in both.
+            (e) => e.occurredAt >= from && e.occurredAt < to);
+            const groups = new Map();
+            for (const e of scoped) {
+                // A conversation is optional on a usage event — a background extraction has none — so those group under
+                // an explicit key rather than being silently dropped, which would make the breakdown not add up.
+                // #175: `principal` alongside the other two. The empty-string fallback is deliberate and matches the
+                // SQL adapter — an event with no principal groups under an explicit key rather than being silently
+                // dropped, which would make the breakdown not add up.
+                const key = by === "model" ? e.modelId : by === "principal" ? (e.principalId ?? "") : (e.conversationId ?? "");
+                const current = groups.get(key) ?? ZERO_TOTALS;
+                groups.set(key, {
+                    inputTokens: current.inputTokens + e.inputTokens,
+                    outputTokens: current.outputTokens + e.outputTokens,
+                    cachedInputTokens: current.cachedInputTokens + e.cachedInputTokens,
+                    reasoningTokens: current.reasoningTokens + (e.reasoningTokens ?? 0),
+                    costMinorUnits: current.costMinorUnits + e.costMinorUnits,
+                    eventCount: current.eventCount + 1,
+                });
+            }
+            return [...groups.entries()]
+                .map(([key, totals]) => ({ key, totals }))
+                // Largest cost first, so a `limit` drops what matters least; ties by key so the order is stable and a
+                // rendered breakdown does not reshuffle between refreshes.
+                .sort((a, b) => b.totals.costMinorUnits !== a.totals.costMinorUnits
+                ? b.totals.costMinorUnits - a.totals.costMinorUnits
+                : a.key.localeCompare(b.key))
+                .slice(0, limit);
+        },
+        async totalsBetween({ tenantId, from, to, principalId, modelId }) {
+            const scoped = [...tenant(tenantId).values()].filter((e) => 
+            // Half-open, like every other range here, so adjacent windows tile without a boundary event counting
+            // twice.
+            e.occurredAt >= from &&
+                e.occurredAt < to &&
+                // Absent means the whole tenant. Matching `principalId === undefined` against `e.principalId` would
+                // instead select only the records with *no* principal, which is the opposite of "everyone".
+                (principalId === undefined || e.principalId === principalId) &&
+                (modelId === undefined || e.modelId === modelId));
+            const totals = scoped.reduce((acc, e) => ({
+                inputTokens: acc.inputTokens + e.inputTokens,
+                outputTokens: acc.outputTokens + e.outputTokens,
+                cachedInputTokens: acc.cachedInputTokens + e.cachedInputTokens,
+                reasoningTokens: acc.reasoningTokens + (e.reasoningTokens ?? 0),
+                costMinorUnits: acc.costMinorUnits + e.costMinorUnits,
+                eventCount: acc.eventCount + 1,
+            }), ZERO_TOTALS);
+            // From the same filtered set as the totals, so the two cannot describe different sets of records.
+            const earliestAt = scoped.reduce((min, e) => (min === null || e.occurredAt < min ? e.occurredAt : min), null);
+            return { totals, earliestAt };
+        },
+        async totals({ tenantId, runId, conversationId }) {
+            const scoped = [...tenant(tenantId).values()].filter((e) => (runId === undefined || e.runId === runId) &&
+                (conversationId === undefined || e.conversationId === conversationId));
+            return scoped.reduce((acc, e) => ({
+                inputTokens: acc.inputTokens + e.inputTokens,
+                outputTokens: acc.outputTokens + e.outputTokens,
+                cachedInputTokens: acc.cachedInputTokens + e.cachedInputTokens,
+                reasoningTokens: acc.reasoningTokens + (e.reasoningTokens ?? 0),
+                costMinorUnits: acc.costMinorUnits + e.costMinorUnits,
+                eventCount: acc.eventCount + 1,
+            }), ZERO_TOTALS);
+        },
+    };
+    /** Buckets already computed, so `listStaleBuckets` can tell "never computed" from "computed and current". */
+    const computed = new Map();
+    /** The record sequence a bucket was last computed at, paired with its row. */
+    const computedAtSequence = new Map();
+    const rollupsFor = (t) => {
+        let m = computed.get(t);
+        if (!m)
+            computed.set(t, (m = new Map()));
+        return m;
+    };
+    /** Events in a bucket, by their `occurredAt`. The only input a rebuild has. */
+    const eventsIn = (tenantId, period, bucketStart) => {
+        const end = nextBucket(period, bucketStart);
+        return [...tenant(tenantId).values()].filter((e) => e.occurredAt >= bucketStart && e.occurredAt < end);
+    };
+    const sumOf = (events) => events.reduce((acc, e) => ({
+        inputTokens: acc.inputTokens + e.inputTokens,
+        outputTokens: acc.outputTokens + e.outputTokens,
+        cachedInputTokens: acc.cachedInputTokens + e.cachedInputTokens,
+        reasoningTokens: acc.reasoningTokens + (e.reasoningTokens ?? 0),
+        costMinorUnits: acc.costMinorUnits + e.costMinorUnits,
+        eventCount: acc.eventCount + 1,
+    }), ZERO_TOTALS);
+    /**
+     * The rollup map's key, which now carries the grain — #175.
+     *
+     * `principalId` absent is the **tenant** row; present is one person's. Written as a helper rather than
+     * interpolated at five call sites, because the tenant row and a principal's row differing by one segment of a
+     * string key is exactly the sort of thing that gets typed slightly differently in one place and reads back
+     * empty.
+     */
+    const rollupKey = (period, bucketStart, principalId) => `${period} ${bucketStart} ${principalId ?? ""}`;
+    const rollups = {
+        async rebuild({ tenantId, period, bucketStart, principalId }) {
+            const computedAt = clock();
+            // A **recomputation**, not an accumulation. Re-running writes the same numbers and two writers racing
+            // one bucket write the same value, which is what makes idempotency structural rather than bookkept.
+            // The whole bucket, or one person's slice of it. Same computation either way, which is what keeps the
+            // two grains from disagreeing.
+            const events = eventsIn(tenantId, period, bucketStart).filter((e) => principalId === undefined || e.principalId === principalId);
+            const totals = sumOf(events);
+            const row = {
+                ...totals,
+                period,
+                bucketStart,
+                // Carried on the row so `list` and `sum` can filter by grain. Without it a tenant chart would include
+                // every principal's row alongside the tenant's and double every figure.
+                ...(principalId === undefined ? {} : { principalId }),
+                // The currency of the events in the bucket. Empty when there are none — a bucket with no spend has no
+                // currency, and claiming one would be inventing a fact.
+                currency: events[0]?.currency ?? "",
+                computedAt,
+            };
+            rollupsFor(tenantId).set(rollupKey(period, bucketStart, principalId), row);
+            // The sequence at the moment of computation, so a *later* append marks the bucket stale again regardless
+            // of when the event claims to have occurred.
+            computedAtSequence.set(`${tenantId} ${rollupKey(period, bucketStart, principalId)}`, recordSequence);
+            return row;
+        },
+        async get({ tenantId, period, bucketStart, principalId }) {
+            // Absent from *this tenant's* map, so a foreign bucket is null without a comparison anyone could get
+            // wrong — and no aggregate can span tenants.
+            return rollupsFor(tenantId).get(rollupKey(period, bucketStart, principalId)) ?? null;
+        },
+        async list({ tenantId, period, from, to, limit, cursor, principalId }) {
+            const rows = [...rollupsFor(tenantId).values()]
+                .filter((r) => r.period === period &&
+                r.bucketStart >= from &&
+                r.bucketStart < to &&
+                // Exactly one grain. `undefined === undefined` selects the tenant rows.
+                r.principalId === principalId)
+                .sort((a, b) => a.bucketStart.localeCompare(b.bucketStart));
+            const start = cursor === undefined ? 0 : rows.findIndex((r) => r.bucketStart > cursor);
+            const at = start < 0 ? rows.length : start;
+            const items = rows.slice(at, at + limit);
+            const last = items[items.length - 1];
+            return at + limit < rows.length && last !== undefined
+                ? { items, nextCursor: last.bucketStart }
+                : { items };
+        },
+        async sum({ tenantId, period, from, to, principalId }) {
+            // Over the *rollups*, not the ledger: the whole point of AC-1 is that a read never scans raw records.
+            return [...rollupsFor(tenantId).values()]
+                .filter((r) => r.period === period &&
+                r.bucketStart >= from &&
+                r.bucketStart < to &&
+                r.principalId === principalId)
+                .reduce((acc, r) => ({
+                inputTokens: acc.inputTokens + r.inputTokens,
+                outputTokens: acc.outputTokens + r.outputTokens,
+                cachedInputTokens: acc.cachedInputTokens + r.cachedInputTokens,
+                reasoningTokens: acc.reasoningTokens + r.reasoningTokens,
+                costMinorUnits: acc.costMinorUnits + r.costMinorUnits,
+                eventCount: acc.eventCount + r.eventCount,
+            }), ZERO_TOTALS);
+        },
+        async listStaleBuckets({ tenantId, period, since, limit, cursor }) {
+            // Derived from the ledger: a bucket is stale when it holds an event newer than its last computation, or
+            // has never been computed. So an interrupted job resumes by asking again -- there is no cursor to lose.
+            const rows = rollupsFor(tenantId);
+            /**
+             * Both grains, in one pass — #175, matching the SQL adapter's GROUPING SETS.
+             *
+             * A per-principal rollup is only useful if something rebuilds it, and the job cannot know which principals
+             * were active in a bucket without reading the ledger. This walk is already reading it, so it reports both:
+             * one entry per bucket for the tenant, and one per (bucket, principal).
+             *
+             * Keyed on the newest *record* sequence, not the newest `occurredAt`, so an event recorded late with a
+             * backdated timestamp still marks its bucket stale.
+             */
+            const buckets = new Map();
+            for (const [key, event] of tenant(tenantId)) {
+                if (event.occurredAt < since)
+                    continue;
+                const bucketStart = bucketStartFor(period, event.occurredAt);
+                const seq = recordedAt.get(`${tenantId} ${key}`) ?? 0;
+                const grains = event.principalId === undefined ? [undefined] : [undefined, event.principalId];
+                for (const principalId of grains) {
+                    const mapKey = rollupKey(period, bucketStart, principalId);
+                    const seen = buckets.get(mapKey);
+                    if (seen === undefined || seq > seen.seq)
+                        buckets.set(mapKey, { bucketStart, ...(principalId === undefined ? {} : { principalId }), seq });
+                }
+            }
+            const stale = [...buckets.entries()]
+                .filter(([mapKey, entry]) => {
+                const existing = rows.get(mapKey);
+                if (existing === undefined)
+                    return true;
+                const computedSeq = computedAtSequence.get(`${tenantId} ${mapKey}`) ?? 0;
+                return entry.seq > computedSeq;
+            })
+                .map(([, entry]) => ({
+                period,
+                bucketStart: entry.bucketStart,
+                ...(entry.principalId === undefined ? {} : { principalId: entry.principalId }),
+            }))
+                // The tenant row first within a bucket, so a job that stops mid-bucket has at least the total.
+                .sort((a, b) => a.bucketStart.localeCompare(b.bucketStart) ||
+                (a.principalId ?? "").localeCompare(b.principalId ?? ""));
+            const start = cursor === undefined ? 0 : stale.findIndex((b) => b.bucketStart > cursor);
+            const at = start < 0 ? stale.length : start;
+            const items = stale.slice(at, at + limit);
+            const last = items[items.length - 1];
+            return at + limit < stale.length && last !== undefined
+                ? { items, nextCursor: last.bucketStart }
+                : { items };
+        },
+    };
+    return { usage, rollups };
+};
+export const createMemoryUsageStore = () => createMemoryUsageBackend().usage;
+export const createMemoryUsageRollupStore = () => createMemoryUsageBackend().rollups;
+//# sourceMappingURL=usage.js.map

package/dist/adapters/otel/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The OpenTelemetry adapter — AC-6: "instrumentation is vendor-neutral and can target a customer's own
+ * collector".
+ *
+ * The only file in `src/` that knows OpenTelemetry exists, and a boundary rule (R11) keeps it that way. That is
+ * what makes the claim true rather than aspirational: a single convenience import of `@opentelemetry/api` in a
+ * hot path is how a platform acquires a vendor, and it is invisible in review.
+ *
+ * **Structural types, no runtime import.** The OTel API surface this needs is declared below as interfaces, and
+ * a caller passes their own `TracerProvider` and `MeterProvider`. So `@retinue/agentkit` has no dependency on
+ * any OTel package — a customer already running the OTel SDK hands us the objects they have, and a customer
+ * running something else implements four small interfaces. `otel.test.ts` imports the *real*
+ * `@opentelemetry/api` and passes real providers through, which is the only way to know the structural types are
+ * right rather than plausible.
+ *
+ * That also means "target your own collector" needs nothing from us: exporters, samplers, resource attributes
+ * and endpoints are all configured on the provider the caller constructs. We never see a URL.
+ */
+import type { AttributeValue, SpanKind, Telemetry, TelemetryContext } from "../../telemetry/index.js";
+/** OTel's numeric SpanKind enum. Values are fixed by the spec, so the mapping below is stable. */
+export declare const OTEL_SPAN_KIND: Readonly<Record<SpanKind, number>>;
+export interface OtelSpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+export interface OtelSpan {
+    spanContext(): OtelSpanContext;
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: {
+        name?: string;
+        message?: string;
+    }): unknown;
+    end(): unknown;
+}
+export interface OtelTracer {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Record<string, AttributeValue>;
+    }, context?: unknown): OtelSpan;
+}
+export interface OtelTracerProvider {
+    getTracer(name: string, version?: string): OtelTracer;
+}
+export interface OtelCounter {
+    add(value: number, attributes?: Record<string, AttributeValue>): unknown;
+}
+export interface OtelHistogram {
+    record(value: number, attributes?: Record<string, AttributeValue>): unknown;
+}
+export interface OtelGauge {
+    record(value: number, attributes?: Record<string, AttributeValue>): unknown;
+}
+export interface OtelMeter {
+    createCounter(name: string, options?: {
+        unit?: string;
+        description?: string;
+    }): OtelCounter;
+    createHistogram(name: string, options?: {
+        unit?: string;
+        description?: string;
+    }): OtelHistogram;
+    createGauge(name: string, options?: {
+        unit?: string;
+        description?: string;
+    }): OtelGauge;
+}
+export interface OtelMeterProvider {
+    getMeter(name: string, version?: string): OtelMeter;
+}
+/**
+ * How a serialized parent becomes an OTel context.
+ *
+ * Injected, and this is the one seam that genuinely needs it. Building a `Context` containing a remote span
+ * requires `trace.setSpanContext(ROOT_CONTEXT, …)` from `@opentelemetry/api` — a *function* from the package we
+ * are refusing to import. So the caller supplies it in three lines at wiring time, which is a fair trade for the
+ * core staying dependency-free.
+ *
+ * Without it the adapter still works: spans are created without a remote parent, so a trace stops at the process
+ * boundary. Degrading rather than throwing, because a missing three lines of wiring should cost a trace link and
+ * not every request.
+ */
+export type RemoteContextFactory = (parent: {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: number;
+}) => unknown;
+export type OtelTelemetryOptions = {
+    readonly tracerProvider: OtelTracerProvider;
+    readonly meterProvider: OtelMeterProvider;
+    /** Instrumentation scope. Appears on every span and metric, so a collector can attribute them to us. */
+    readonly scopeName?: string;
+    readonly scopeVersion?: string;
+    readonly remoteContext?: RemoteContextFactory;
+    /**
+     * Where a log line goes.
+     *
+     * A sink taking a **string**, not a record — the string has already been through `formatLogLine`, which has
+     * already been through `redactFields`. A sink that received the record could format it itself and bypass the
+     * redaction, and it would be a reasonable-looking thing for someone to write.
+     */
+    readonly sink?: (line: string) => void;
+    readonly context?: TelemetryContext;
+    readonly now?: () => string;
+};
+export declare const createOtelTelemetry: (options: OtelTelemetryOptions) => Telemetry;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/otel/index.js

@@ -0,0 +1,133 @@
+/**
+ * The OpenTelemetry adapter — AC-6: "instrumentation is vendor-neutral and can target a customer's own
+ * collector".
+ *
+ * The only file in `src/` that knows OpenTelemetry exists, and a boundary rule (R11) keeps it that way. That is
+ * what makes the claim true rather than aspirational: a single convenience import of `@opentelemetry/api` in a
+ * hot path is how a platform acquires a vendor, and it is invisible in review.
+ *
+ * **Structural types, no runtime import.** The OTel API surface this needs is declared below as interfaces, and
+ * a caller passes their own `TracerProvider` and `MeterProvider`. So `@retinue/agentkit` has no dependency on
+ * any OTel package — a customer already running the OTel SDK hands us the objects they have, and a customer
+ * running something else implements four small interfaces. `otel.test.ts` imports the *real*
+ * `@opentelemetry/api` and passes real providers through, which is the only way to know the structural types are
+ * right rather than plausible.
+ *
+ * That also means "target your own collector" needs nothing from us: exporters, samplers, resource attributes
+ * and endpoints are all configured on the provider the caller constructs. We never see a URL.
+ */
+import { boundMetricAttributes } from "../../telemetry/metrics.js";
+import { formatLogLine, redactFields } from "../../telemetry/redaction.js";
+import { parseTraceparent, TRACE_FLAG_SAMPLED } from "../../telemetry/trace-context.js";
+/* ------------------------------------------------------------------------------------------------------------
+ * The OTel API surface, structurally.
+ *
+ * Narrowed to what is used. A wider declaration would be a copy of someone else's types that drifts, and every
+ * member here has to be satisfied by a real provider — which the adapter's test proves against the published
+ * package rather than against this file.
+ * ---------------------------------------------------------------------------------------------------------- */
+/** OTel's numeric SpanKind enum. Values are fixed by the spec, so the mapping below is stable. */
+export const OTEL_SPAN_KIND = {
+    internal: 0,
+    server: 1,
+    client: 2,
+    producer: 3,
+    consumer: 4,
+};
+/** OTel's numeric SpanStatusCode. */
+const OTEL_STATUS = { unset: 0, ok: 1, error: 2 };
+const toOtelSpan = (span) => ({
+    get context() {
+        const ctx = span.spanContext();
+        return { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags };
+    },
+    setAttributes(attributes) {
+        // One at a time: `setAttributes` is on OTel's Span but not on every implementation of it, and `setAttribute`
+        // is. Fewer members in the structural type means fewer things a customer's shim has to provide.
+        for (const [key, value] of Object.entries(attributes))
+            span.setAttribute(key, value);
+    },
+    recordError({ code, message }) {
+        // `name` carries the code. OTel's exception convention wants an Error-ish shape, and this is the honest one:
+        // a classified code and an optional message the caller took responsibility for -- never a thrown object,
+        // whose stack and cause routinely carry a token or the argument that caused the throw.
+        span.recordException({ name: code, ...(message !== undefined ? { message } : {}) });
+    },
+    setStatus(status) {
+        span.setStatus({ code: OTEL_STATUS[status] });
+    },
+    end() {
+        span.end();
+    },
+});
+export const createOtelTelemetry = (options) => {
+    const scope = options.scopeName ?? "@retinue/agentkit";
+    const otelTracer = options.tracerProvider.getTracer(scope, options.scopeVersion);
+    const otelMeter = options.meterProvider.getMeter(scope, options.scopeVersion);
+    const sink = options.sink ?? (() => { });
+    const now = options.now ?? (() => new Date().toISOString());
+    const tracer = {
+        startSpan(name, spanOptions = {}) {
+            const parent = parseTraceparent(spanOptions.parent);
+            const remote = parent !== null && options.remoteContext !== undefined
+                ? options.remoteContext({
+                    traceId: parent.traceId,
+                    spanId: parent.spanId,
+                    // Default to sampled when the parent's flags say nothing. The alternative -- defaulting to
+                    // unsampled -- silently drops the child of every span whose producer did not set the bit, which
+                    // reads as a propagation bug and is very hard to find.
+                    traceFlags: parent.traceFlags === 0 ? TRACE_FLAG_SAMPLED : parent.traceFlags,
+                })
+                : undefined;
+            return toOtelSpan(otelTracer.startSpan(name, {
+                kind: OTEL_SPAN_KIND[spanOptions.kind ?? "internal"],
+                ...(spanOptions.attributes !== undefined ? { attributes: { ...spanOptions.attributes } } : {}),
+            }, remote));
+        },
+    };
+    /**
+     * Metric attributes are bounded here, in the adapter.
+     *
+     * Not trusted to call sites: `runId` on a latency histogram is one line of code and one time series per run.
+     * It looks like helpful detail in review and is a cardinality incident in production, and the bill arrives a
+     * month later.
+     */
+    const bounded = (attributes) => ({
+        ...boundMetricAttributes(attributes),
+    });
+    const meter = {
+        counter(name, opts) {
+            const counter = otelMeter.createCounter(name, opts);
+            return { record: (value, attributes) => void counter.add(value, bounded(attributes)) };
+        },
+        histogram(name, opts) {
+            const histogram = otelMeter.createHistogram(name, opts);
+            return { record: (value, attributes) => void histogram.record(value, bounded(attributes)) };
+        },
+        gauge(name, opts) {
+            const gauge = otelMeter.createGauge(name, opts);
+            return { record: (value, attributes) => void gauge.record(value, bounded(attributes)) };
+        },
+    };
+    const makeLogger = (context) => ({
+        log(level, event, raw) {
+            const { fields, dropped } = redactFields(raw);
+            sink(formatLogLine({ level, event, at: now(), context: context, fields }));
+            if (dropped.length > 0)
+                sink(formatLogLine({
+                    level: "debug",
+                    event: "telemetry.fields-dropped",
+                    at: now(),
+                    context: context,
+                    // Names, never values, and capped -- a dropped field's *name* is safe, and eight of them is enough
+                    // to identify the call site without the notice itself becoming a long line.
+                    fields: { count: dropped.length, reason: dropped.slice(0, 8).join(",").slice(0, 120) },
+                }));
+        },
+        child(extra) {
+            return makeLogger({ ...context, ...extra });
+        },
+    });
+    return { tracer, meter, logger: makeLogger(options.context ?? { tenantId: "" }) };
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/postgres/artifact-exports.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Postgres `ArtifactExportStore` (#134).
+ *
+ * One property is in the SQL rather than above it: **`claim` is an insert that loses gracefully.**
+ * `ON CONFLICT DO NOTHING` against `UNIQUE (tenant_id, artifact_id, version, format)` means two concurrent
+ * requests for the same PDF cannot both claim it, whatever the application layer believes — and the loser
+ * reads the winner's row rather than erroring, because its next move is the same either way.
+ */
+import type { ArtifactExportStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresArtifactExportStore: (sql: SqlExecutor) => ArtifactExportStore;
+//# sourceMappingURL=artifact-exports.d.ts.map

package/dist/adapters/postgres/artifact-exports.js

@@ -0,0 +1,117 @@
+/**
+ * Postgres `ArtifactExportStore` (#134).
+ *
+ * One property is in the SQL rather than above it: **`claim` is an insert that loses gracefully.**
+ * `ON CONFLICT DO NOTHING` against `UNIQUE (tenant_id, artifact_id, version, format)` means two concurrent
+ * requests for the same PDF cannot both claim it, whatever the application layer believes — and the loser
+ * reads the winner's row rather than erroring, because its next move is the same either way.
+ */
+import { asId } from "../../core/ids.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : v);
+const toExport = (r) => ({
+    id: r.id,
+    artifactId: asId(r.artifact_id),
+    version: Number(r.version),
+    format: r.format,
+    state: r.state,
+    ...(r.file_id === null ? {} : { fileId: asId(r.file_id) }),
+    // `bigint` comes back as a string from node-postgres, correct past 2^53 and wrong for arithmetic. An
+    // export is well inside the safe range, so it is narrowed here rather than left for a caller.
+    ...(r.byte_size === null ? {} : { byteSize: Number(r.byte_size) }),
+    ...(r.checksum === null ? {} : { checksum: r.checksum }),
+    ...(r.failure_reason === null ? {} : { failureReason: r.failure_reason }),
+    ...(r.failure_message === null ? {} : { failureMessage: r.failure_message }),
+    requestedBy: asId(r.requested_by),
+    createdAt: iso(r.created_at),
+    ...(r.rendered_at === null ? {} : { renderedAt: iso(r.rendered_at) }),
+});
+const COLUMNS = `id, artifact_id, version, format, state, file_id, byte_size, checksum,
+                 failure_reason, failure_message, requested_by, created_at, rendered_at`;
+const encodeCursor = (createdAt, id) => Buffer.from(`${createdAt} ${id}`, "utf8").toString("base64url");
+const decodeCursor = (cursor) => {
+    const [createdAt, id] = Buffer.from(cursor, "base64url").toString("utf8").split(" ");
+    return createdAt === undefined || id === undefined ? null : { createdAt, id };
+};
+export const createPostgresArtifactExportStore = (sql) => ({
+    async claim({ tenantId, export: requested }) {
+        const inserted = await sql.query(`INSERT INTO artifact_exports (tenant_id, id, artifact_id, version, format, state,
+                                     requested_by, created_at)
+       VALUES ($1,$2,$3,$4,$5,'pending',$6,$7)
+       -- The claim. Against the unique constraint, so two concurrent requests for the same export cannot both
+       -- proceed to render -- and the loser gets zero rows rather than an error it would have to interpret.
+       ON CONFLICT (tenant_id, artifact_id, version, format) DO NOTHING
+       RETURNING ${COLUMNS}`, [
+            tenantId,
+            requested.id,
+            requested.artifactId,
+            requested.version,
+            requested.format,
+            requested.requestedBy,
+            requested.createdAt,
+        ]);
+        const created = inserted[0];
+        if (created !== undefined)
+            return { claimed: true, export: toExport(created) };
+        const existing = await sql.query(`SELECT ${COLUMNS} FROM artifact_exports
+        WHERE tenant_id = $1 AND artifact_id = $2 AND version = $3 AND format = $4`, [tenantId, requested.artifactId, requested.version, requested.format]);
+        const row = existing[0];
+        if (row === undefined)
+            // Deleted between the insert and this read. Treated as a fresh claim rather than thrown, because the
+            // caller has nothing better to do and rendering again is correct.
+            return { claimed: true, export: { ...requested, state: "pending" } };
+        return { claimed: false, export: toExport(row) };
+    },
+    async complete({ tenantId, id, state, fileId, byteSize, checksum, failureReason, failureMessage, at }) {
+        const rows = await sql.query(`UPDATE artifact_exports
+          SET state = $3,
+              file_id = $4,
+              byte_size = $5,
+              checksum = $6,
+              failure_reason = $7,
+              failure_message = $8,
+              rendered_at = $9::timestamptz
+        -- No compare on the previous state: a worker retrying after a crash does not know what it wrote, and
+        -- requiring it to would make recovery impossible.
+        WHERE tenant_id = $1 AND id = $2
+        RETURNING id`, [
+            tenantId,
+            id,
+            state,
+            fileId ?? null,
+            byteSize ?? null,
+            checksum ?? null,
+            failureReason ?? null,
+            failureMessage ?? null,
+            at,
+        ]);
+        return { recorded: rows.length > 0 };
+    },
+    async get({ tenantId, id }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM artifact_exports WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        // A foreign id yields no row, so it is null without a comparison anyone could get wrong.
+        return rows[0] === undefined ? null : toExport(rows[0]);
+    },
+    async find({ tenantId, artifactId, version, format }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM artifact_exports
+        WHERE tenant_id = $1 AND artifact_id = $2 AND version = $3 AND format = $4`, [tenantId, artifactId, version, format]);
+        return rows[0] === undefined ? null : toExport(rows[0]);
+    },
+    async listByArtifact({ tenantId, artifactId, limit, cursor }) {
+        // Keyset on `(created_at, id)`, matching the ORDER BY. An earlier version cursored on `id` alone while
+        // ordering by both, which is a cursor that does not describe the sequence it pages -- the page would skip
+        // or repeat rows whenever two exports shared a timestamp, which for two formats requested together is the
+        // normal case rather than a rare one.
+        const after = cursor === undefined ? null : decodeCursor(cursor);
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM artifact_exports
+        WHERE tenant_id = $1 AND artifact_id = $2
+          AND ($3::text IS NULL OR (created_at, id) > ($3::timestamptz, $4::text))
+        ORDER BY created_at, id
+        LIMIT $5`, [tenantId, artifactId, after?.createdAt ?? null, after?.id ?? null, limit + 1]);
+        const items = rows.slice(0, limit).map(toExport);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: encodeCursor(last.createdAt, last.id) }
+            : { items };
+    },
+});
+//# sourceMappingURL=artifact-exports.js.map