@seanhogg/builderforce-memory 2026.7.12 → 2026.9.27

package/dist/telemetry/pricing.js

@@ -0,0 +1,98 @@
+/**
+ * telemetry/pricing.ts — cost-per-request, computed from real token counts.
+ *
+ * "Cost per request" is an LLM-native metric that cannot be derived from latency
+ * or call count: it depends on the model, the input/output split, AND how much of
+ * the input was a cache read (cheap) versus a cache write (dear). This module is
+ * the ONE place that arithmetic lives, so the bridges, the metrics registry, and
+ * the eval harness cannot disagree about what a run cost.
+ *
+ * Rates are DATA, not code: an enterprise on a negotiated rate card, a partner
+ * platform (Bedrock/Vertex bill separately from the first-party API), or a model
+ * released after this file was written is handled by passing a {@link PriceBook},
+ * never by editing a branch. Unknown models cost `undefined` — reported as an
+ * `unpricedCalls` count rather than silently billed at zero, because a silent
+ * zero is how cost dashboards lie.
+ */
+export const DEFAULT_CACHE_READ_MULTIPLIER = 0.1;
+export const DEFAULT_CACHE_WRITE_MULTIPLIER = 1.25;
+/**
+ * First-party Anthropic API rates (USD / 1M tokens), current as of 2026-08-20.
+ *
+ * Bedrock and Vertex are partner-operated and priced separately — supply those
+ * rates via a custom {@link PriceBook} rather than assuming these apply.
+ */
+export const ANTHROPIC_PRICE_BOOK = {
+    'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },
+    'claude-mythos-5': { inputPerMTok: 10, outputPerMTok: 50 },
+    'claude-opus-5': { inputPerMTok: 5, outputPerMTok: 25 },
+    'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },
+    'claude-opus-4-7': { inputPerMTok: 5, outputPerMTok: 25 },
+    'claude-opus-4-6': { inputPerMTok: 5, outputPerMTok: 25 },
+    'claude-sonnet-5': { inputPerMTok: 3, outputPerMTok: 15 },
+    'claude-sonnet-4-6': { inputPerMTok: 3, outputPerMTok: 15 },
+    'claude-haiku-4-5': { inputPerMTok: 1, outputPerMTok: 5 },
+};
+/**
+ * Evermind serves `evermind/<ref>` traffic on-device, so it has no per-token
+ * vendor bill. It is priced explicitly at zero rather than left unknown — the
+ * whole point of routing to Evermind is that the saving is *measurable*.
+ */
+export const EVERMIND_PRICE_BOOK = {
+    'evermind': { inputPerMTok: 0, outputPerMTok: 0 },
+    'ssm': { inputPerMTok: 0, outputPerMTok: 0 },
+};
+export const DEFAULT_PRICE_BOOK = { ...ANTHROPIC_PRICE_BOOK, ...EVERMIND_PRICE_BOOK };
+/**
+ * Resolves a model id to a rate: exact match first, then the longest key the
+ * model id starts with. Prefix matching is what makes dated snapshots
+ * (`claude-opus-4-5@20251101`) and platform-prefixed ids (`anthropic.claude-opus-5`)
+ * resolve without a per-variant entry.
+ */
+export function resolveRate(model, book = DEFAULT_PRICE_BOOK) {
+    const exact = book[model];
+    if (exact)
+        return exact;
+    let best;
+    let bestLen = 0;
+    for (const [key, rate] of Object.entries(book)) {
+        if (key.length > bestLen && (model.startsWith(key) || model.includes(`/${key}`))) {
+            best = rate;
+            bestLen = key.length;
+        }
+    }
+    return best;
+}
+/**
+ * Cost in USD for one call, or `undefined` when the model is not in the book.
+ *
+ * A locally-served call (`localCacheHit`) is free by construction — it never
+ * reached a provider — so it costs 0 even for an unpriced model.
+ */
+export function estimateCostUsd(usage, book = DEFAULT_PRICE_BOOK) {
+    if (usage.localCacheHit)
+        return 0;
+    const rate = resolveRate(usage.model, book);
+    if (!rate)
+        return undefined;
+    const cacheRead = rate.cacheReadMultiplier ?? DEFAULT_CACHE_READ_MULTIPLIER;
+    const cacheWrite = rate.cacheWriteMultiplier ?? DEFAULT_CACHE_WRITE_MULTIPLIER;
+    const perToken = (perMTok) => perMTok / 1_000_000;
+    return (usage.inputTokens * perToken(rate.inputPerMTok) +
+        usage.outputTokens * perToken(rate.outputPerMTok) +
+        (usage.cachedInputTokens ?? 0) * perToken(rate.inputPerMTok * cacheRead) +
+        (usage.cacheWriteTokens ?? 0) * perToken(rate.inputPerMTok * cacheWrite));
+}
+/**
+ * Character-based token estimate — the fallback when a provider reports no usage.
+ *
+ * ~4 characters per token is the standard English approximation. Estimates are
+ * flagged (`estimated: true`) all the way through to the metric snapshot so a
+ * cost figure never silently mixes measured and guessed numbers.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+//# sourceMappingURL=pricing.js.map

package/dist/telemetry/pricing.js.map

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

package/dist/telemetry/traceparent.d.ts

@@ -0,0 +1,50 @@
+/**
+ * telemetry/traceparent.ts — W3C Trace Context propagation.
+ *
+ * A {@link Tracer} on its own produces one span tree per PROCESS. A cloud run is not
+ * one process: portal → api → relay → runtime is four, and without propagation each
+ * hop opens its own root trace, so the operator gets four unrelated trees and has to
+ * correlate them by timestamp. Head-based propagation is what makes them one tree —
+ * the caller serialises `{ traceId, spanId, sampled }` into a `traceparent` header,
+ * the callee parses it and starts its root span as a CHILD of the remote span.
+ *
+ * The sampling flag travels with it on purpose: a sampling decision taken per-hop
+ * would record hop 1 and drop hop 3, which is a tree with holes in it — the same
+ * failure the in-process `_sampled` map exists to prevent, one network hop out.
+ *
+ * Pure string work, zero dependencies, no OpenTelemetry SDK — the wire format is a
+ * 55-character ASCII string and re-implementing it costs less than the dependency.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+/** A trace position received from (or sent to) another process. */
+export interface TraceContext {
+    /** 32 lowercase hex chars, never all-zero. */
+    traceId: string;
+    /** 16 lowercase hex chars, never all-zero — the REMOTE span, parent of ours. */
+    spanId: string;
+    /** The `sampled` flag (bit 0x01). False means the caller decided to drop the trace. */
+    sampled: boolean;
+}
+/**
+ * Parse a `traceparent` header, or `null` when it is absent or unusable.
+ *
+ * Rejecting rather than repairing is deliberate: a malformed header means the caller
+ * is not actually in the trace we would be joining, and inventing a link to it
+ * produces a tree that misattributes latency. `null` makes the callee start a fresh
+ * root, which is at least true.
+ *
+ * Unknown future versions are accepted by reading the first four fields — that is
+ * what the spec requires, so a later spec revision does not silently break every
+ * hop. Version `ff` is invalid by definition and is rejected.
+ */
+export declare function parseTraceparent(header: string | null | undefined): TraceContext | null;
+/**
+ * Serialise a trace position as a version-`00` `traceparent` header.
+ *
+ * Ids are normalised to the wire widths — left-padded when short, right-trimmed when
+ * long — so a tracer configured with a non-standard id factory still emits a legal
+ * header rather than one every downstream collector drops.
+ */
+export declare function formatTraceparent(ctx: TraceContext): string;
+//# sourceMappingURL=traceparent.d.ts.map

package/dist/telemetry/traceparent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.d.ts","sourceRoot":"","sources":["../../src/telemetry/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mEAAmE;AACnE,MAAM,WAAW,YAAY;IACzB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;CACpB;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CAavF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAK3D"}

package/dist/telemetry/traceparent.js

@@ -0,0 +1,77 @@
+/**
+ * telemetry/traceparent.ts — W3C Trace Context propagation.
+ *
+ * A {@link Tracer} on its own produces one span tree per PROCESS. A cloud run is not
+ * one process: portal → api → relay → runtime is four, and without propagation each
+ * hop opens its own root trace, so the operator gets four unrelated trees and has to
+ * correlate them by timestamp. Head-based propagation is what makes them one tree —
+ * the caller serialises `{ traceId, spanId, sampled }` into a `traceparent` header,
+ * the callee parses it and starts its root span as a CHILD of the remote span.
+ *
+ * The sampling flag travels with it on purpose: a sampling decision taken per-hop
+ * would record hop 1 and drop hop 3, which is a tree with holes in it — the same
+ * failure the in-process `_sampled` map exists to prevent, one network hop out.
+ *
+ * Pure string work, zero dependencies, no OpenTelemetry SDK — the wire format is a
+ * 55-character ASCII string and re-implementing it costs less than the dependency.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+/** The only trace-flag bit W3C defines today. */
+const FLAG_SAMPLED = 0x01;
+const TRACE_ID_LENGTH = 32;
+const SPAN_ID_LENGTH = 16;
+const HEX = /^[0-9a-f]+$/;
+/** True when `value` is `length` lowercase hex chars and not entirely zeros. */
+function isUsableId(value, length) {
+    return value.length === length && HEX.test(value) && /[1-9a-f]/.test(value);
+}
+/**
+ * Parse a `traceparent` header, or `null` when it is absent or unusable.
+ *
+ * Rejecting rather than repairing is deliberate: a malformed header means the caller
+ * is not actually in the trace we would be joining, and inventing a link to it
+ * produces a tree that misattributes latency. `null` makes the callee start a fresh
+ * root, which is at least true.
+ *
+ * Unknown future versions are accepted by reading the first four fields — that is
+ * what the spec requires, so a later spec revision does not silently break every
+ * hop. Version `ff` is invalid by definition and is rejected.
+ */
+export function parseTraceparent(header) {
+    if (typeof header !== 'string')
+        return null;
+    const parts = header.trim().toLowerCase().split('-');
+    if (parts.length < 4)
+        return null;
+    const [version, traceId, spanId, flags] = parts;
+    if (version.length !== 2 || !HEX.test(version) || version === 'ff')
+        return null;
+    // Version 00 is exactly four fields; a longer header at version 00 is malformed.
+    if (version === '00' && parts.length !== 4)
+        return null;
+    if (!isUsableId(traceId, TRACE_ID_LENGTH) || !isUsableId(spanId, SPAN_ID_LENGTH))
+        return null;
+    if (flags.length !== 2 || !HEX.test(flags))
+        return null;
+    return { traceId, spanId, sampled: (parseInt(flags, 16) & FLAG_SAMPLED) !== 0 };
+}
+/**
+ * Serialise a trace position as a version-`00` `traceparent` header.
+ *
+ * Ids are normalised to the wire widths — left-padded when short, right-trimmed when
+ * long — so a tracer configured with a non-standard id factory still emits a legal
+ * header rather than one every downstream collector drops.
+ */
+export function formatTraceparent(ctx) {
+    const traceId = normaliseId(ctx.traceId, TRACE_ID_LENGTH);
+    const spanId = normaliseId(ctx.spanId, SPAN_ID_LENGTH);
+    const flags = (ctx.sampled ? FLAG_SAMPLED : 0).toString(16).padStart(2, '0');
+    return `00-${traceId}-${spanId}-${flags}`;
+}
+/** Pad/trim an id to the wire width, dropping any non-hex byte to `0`. */
+function normaliseId(value, length) {
+    const hex = (value ?? '').toLowerCase().replace(/[^0-9a-f]/g, '');
+    return hex.length >= length ? hex.slice(0, length) : hex.padStart(length, '0');
+}
+//# sourceMappingURL=traceparent.js.map

package/dist/telemetry/traceparent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceparent.js","sourceRoot":"","sources":["../../src/telemetry/traceparent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,iDAAiD;AACjD,MAAM,YAAY,GAAG,IAAI,CAAC;AAE1B,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,MAAM,GAAG,GAAG,aAAa,CAAC;AAE1B,gFAAgF;AAChF,SAAS,UAAU,CAAC,KAAa,EAAE,MAAc;IAC7C,OAAO,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiC;IAC9D,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,KAAyC,CAAC;IACpF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChF,iFAAiF;IACjF,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,cAAc,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9F,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAExD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IAC/C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7E,OAAO,MAAM,OAAO,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;AAC9C,CAAC;AAED,0EAA0E;AAC1E,SAAS,WAAW,CAAC,KAAa,EAAE,MAAc;IAC9C,MAAM,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAClE,OAAO,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACnF,CAAC"}

package/dist/telemetry/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * telemetry/types.ts — the observability vocabulary shared by every enterprise
+ * subsystem (ingest, retrieval, orchestration, eval, bridges).
+ *
+ * Enterprise buyers do not ask "is it fast", they ask "show me the span tree for
+ * this request, the token count per model, and what it cost". That needs one
+ * canonical record, not per-subsystem logging. A {@link SpanData} is that record:
+ * a tracing span that ALSO carries LLM-native usage and cost, so a single
+ * exporter pipeline feeds both a trace viewer and the metric aggregates.
+ *
+ * The shape is deliberately OTLP-compatible (trace/span ids, parent linkage,
+ * attributes, events, status) so `toOtlpSpan()` is a pure rename rather than a
+ * re-model — but nothing here depends on the OpenTelemetry SDK, which keeps the
+ * package zero-dependency and browser-safe.
+ */
+/** Attribute values are kept primitive so a span serializes to JSON losslessly. */
+export type AttributeValue = string | number | boolean;
+export type SpanKind = 'llm' | 'embedding' | 'retrieval' | 'ingest' | 'agent' | 'tool' | 'graph' | 'internal';
+export type SpanStatus = 'unset' | 'ok' | 'error';
+export interface SpanEvent {
+    name: string;
+    /** Epoch millis. */
+    at: number;
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Token accounting for one model call.
+ *
+ * `cachedInputTokens` and `cacheWriteTokens` are split out because they are
+ * billed at different multipliers than plain input (see {@link PriceBook}); a
+ * cost model that folds them into `inputTokens` overstates spend by ~10x on a
+ * cache-heavy workload, which is exactly the workload enterprises run.
+ */
+export interface LlmUsage {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** Input tokens served from the provider's prompt cache (billed at a discount). */
+    cachedInputTokens?: number;
+    /** Input tokens written INTO the provider's prompt cache (billed at a premium). */
+    cacheWriteTokens?: number;
+    /** True when the whole call was served locally (exact/semantic cache) — cost 0. */
+    localCacheHit?: boolean;
+    /** True when token counts are inferred rather than reported by the provider. */
+    estimated?: boolean;
+}
+/** A completed (or in-flight) span, ready to export. */
+export interface SpanData {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    /** Epoch millis. */
+    startedAt: number;
+    /** Epoch millis; absent while the span is still open. */
+    endedAt?: number;
+    durationMs?: number;
+    attributes: Record<string, AttributeValue>;
+    events: SpanEvent[];
+    status: SpanStatus;
+    error?: string;
+    /** Present on `llm` spans. */
+    usage?: LlmUsage;
+    /** Derived from `usage` + the tracer's price book, in USD. */
+    costUsd?: number;
+    /** Millis from request start to the first streamed token, when streaming. */
+    timeToFirstTokenMs?: number;
+}
+/** Sink for finished spans. Implementations must not throw into the caller. */
+export interface SpanExporter {
+    export(spans: readonly SpanData[]): void | Promise<void>;
+    /** Optional flush hook for buffered/remote exporters. */
+    shutdown?(): void | Promise<void>;
+}
+/**
+ * A bridge that reports what its last call actually consumed.
+ *
+ * Optional on {@link TransformerBridge} so third-party bridges stay valid; when
+ * present, {@link InstrumentedBridge} prefers these provider-reported numbers
+ * over its own character-based estimate.
+ */
+export interface BridgeCallInfo {
+    usage?: LlmUsage;
+    /** True when the call never reached the provider (exact or semantic cache hit). */
+    cacheHit?: boolean;
+    /** Which cache tier served it, when `cacheHit`. */
+    cacheTier?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/telemetry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvD,MAAM,MAAM,QAAQ,GACd,KAAK,GACL,WAAW,GACX,WAAW,GACX,QAAQ,GACR,OAAO,GACP,MAAM,GACN,OAAO,GACP,UAAU,CAAC;AAEjB,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IACzB,MAAM,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,yDAAyD;IACzD,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/telemetry/types.js

@@ -0,0 +1,17 @@
+/**
+ * telemetry/types.ts — the observability vocabulary shared by every enterprise
+ * subsystem (ingest, retrieval, orchestration, eval, bridges).
+ *
+ * Enterprise buyers do not ask "is it fast", they ask "show me the span tree for
+ * this request, the token count per model, and what it cost". That needs one
+ * canonical record, not per-subsystem logging. A {@link SpanData} is that record:
+ * a tracing span that ALSO carries LLM-native usage and cost, so a single
+ * exporter pipeline feeds both a trace viewer and the metric aggregates.
+ *
+ * The shape is deliberately OTLP-compatible (trace/span ids, parent linkage,
+ * attributes, events, status) so `toOtlpSpan()` is a pure rename rather than a
+ * re-model — but nothing here depends on the OpenTelemetry SDK, which keeps the
+ * package zero-dependency and browser-safe.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/telemetry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/vectorstore/MemoryVectorStore.d.ts

@@ -0,0 +1,72 @@
+/**
+ * vectorstore/MemoryVectorStore.ts — the in-process reference adapter.
+ *
+ * It is the default store, the test double for every layer above it, and the
+ * conformance benchmark a remote adapter is checked against. It is also the
+ * honest answer for edge deployments (a Worker, a browser tab, an on-prem box)
+ * where standing up a vector database is not on the table.
+ *
+ * Performance notes, because "in-memory" is not an excuse for O(N) per query:
+ *   • The HNSW graph is built ONCE and extended incrementally on upsert. The
+ *     shared `denseSearch` helper rebuilds its index per call, which is right for
+ *     a one-shot rerank over a candidate set and wrong for a store that is queried
+ *     repeatedly — so this adapter owns a persistent index instead.
+ *   • Deletes tombstone rather than rebuild; the graph is rebuilt only once
+ *     tombstones pass a share of the index, amortising the cost.
+ *   • Filtered queries over-fetch from the graph and post-filter, falling back to
+ *     an exact scan only when the filter is selective enough that the graph could
+ *     not fill `topK`. Correct in both regimes, fast in the common one.
+ */
+import { type HnswOptions } from '../retrieval/hnsw.js';
+import type { AccessScope, MetadataFilter, UpsertResult, VectorMatch, VectorQuery, VectorRecord, VectorStore } from './types.js';
+export interface MemoryVectorStoreOptions {
+    /** Adapter name for telemetry. Default `'memory'`. */
+    name?: string;
+    /**
+     * Record count at/above which dense search uses the HNSW graph instead of an
+     * exact cosine scan. Below it, a scan is both simpler and faster. Default 256.
+     */
+    annThreshold?: number;
+    /** HNSW construction parameters. */
+    hnsw?: HnswOptions;
+    /**
+     * Over-fetch multiplier for filtered ANN queries — how many graph candidates
+     * to pull per requested result before post-filtering. Default 4.
+     */
+    filterOverfetch?: number;
+    /**
+     * Rebuild the graph once tombstoned nodes exceed this share of it. Default 0.2.
+     */
+    rebuildTombstoneRatio?: number;
+}
+export declare class MemoryVectorStore implements VectorStore {
+    readonly name: string;
+    private readonly _records;
+    private readonly _annThreshold;
+    private readonly _hnswOpts;
+    private readonly _overfetch;
+    private readonly _rebuildRatio;
+    private _index;
+    /** Ids present in the graph but deleted from the store. */
+    private readonly _tombstones;
+    constructor(opts?: MemoryVectorStoreOptions);
+    get size(): number;
+    upsert(records: readonly VectorRecord[]): Promise<UpsertResult>;
+    fetch(ids: readonly string[]): Promise<VectorRecord[]>;
+    delete(ids: readonly string[]): Promise<number>;
+    deleteByFilter(filter: MetadataFilter, scope?: AccessScope): Promise<number>;
+    count(filter?: MetadataFilter, scope?: AccessScope): Promise<number>;
+    query(query: VectorQuery): Promise<VectorMatch[]>;
+    /**
+     * BM25 over the visible corpus. Present because lexical recall catches the
+     * exact identifiers (error codes, SKUs, function names) that embeddings blur —
+     * the failure mode enterprise RAG evaluations reliably surface.
+     */
+    keywordSearch(query: VectorQuery): Promise<VectorMatch[]>;
+    private _denseScore;
+    private _visible;
+    private _toMatch;
+    private _ensureIndex;
+    private _maybeRebuild;
+}
+//# sourceMappingURL=MemoryVectorStore.d.ts.map

package/dist/vectorstore/MemoryVectorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryVectorStore.d.ts","sourceRoot":"","sources":["../../src/vectorstore/MemoryVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,KAAK,EACR,WAAW,EACX,cAAc,EACd,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,wBAAwB;IACrC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,qBAAa,iBAAkB,YAAW,WAAW;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,OAAO,CAAC,MAAM,CAAwB;IACtC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,IAAI,GAAE,wBAA6B;IAQ/C,IAAI,IAAI,IAAI,MAAM,CAA+B;IAE3C,MAAM,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAuB/D,KAAK,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAStD,MAAM,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAW/C,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ5E,KAAK,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAUpE,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAoBvD;;;;OAIG;IACG,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAoB/D,OAAO,CAAC,WAAW;IAkCnB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,aAAa;CAOxB"}

package/dist/vectorstore/MemoryVectorStore.js

@@ -0,0 +1,205 @@
+/**
+ * vectorstore/MemoryVectorStore.ts — the in-process reference adapter.
+ *
+ * It is the default store, the test double for every layer above it, and the
+ * conformance benchmark a remote adapter is checked against. It is also the
+ * honest answer for edge deployments (a Worker, a browser tab, an on-prem box)
+ * where standing up a vector database is not on the table.
+ *
+ * Performance notes, because "in-memory" is not an excuse for O(N) per query:
+ *   • The HNSW graph is built ONCE and extended incrementally on upsert. The
+ *     shared `denseSearch` helper rebuilds its index per call, which is right for
+ *     a one-shot rerank over a candidate set and wrong for a store that is queried
+ *     repeatedly — so this adapter owns a persistent index instead.
+ *   • Deletes tombstone rather than rebuild; the graph is rebuilt only once
+ *     tombstones pass a share of the index, amortising the cost.
+ *   • Filtered queries over-fetch from the graph and post-filter, falling back to
+ *     an exact scan only when the filter is selective enough that the graph could
+ *     not fill `topK`. Correct in both regimes, fast in the common one.
+ */
+import { bm25Search } from '../retrieval/bm25.js';
+import { HnswIndex } from '../retrieval/hnsw.js';
+import { cosineSimilarity } from '../similarity/index.js';
+import { combineFilters, matchesFilter } from './filter.js';
+export class MemoryVectorStore {
+    name;
+    _records = new Map();
+    _annThreshold;
+    _hnswOpts;
+    _overfetch;
+    _rebuildRatio;
+    _index;
+    /** Ids present in the graph but deleted from the store. */
+    _tombstones = new Set();
+    constructor(opts = {}) {
+        this.name = opts.name ?? 'memory';
+        this._annThreshold = Math.max(1, opts.annThreshold ?? 256);
+        this._hnswOpts = opts.hnsw ?? {};
+        this._overfetch = Math.max(1, opts.filterOverfetch ?? 4);
+        this._rebuildRatio = opts.rebuildTombstoneRatio ?? 0.2;
+    }
+    get size() { return this._records.size; }
+    async upsert(records) {
+        let upserted = 0;
+        for (const record of records) {
+            const previous = this._records.get(record.id);
+            this._records.set(record.id, record);
+            upserted += 1;
+            if (!record.vector)
+                continue;
+            // A changed vector under an existing id invalidates its graph node;
+            // tombstone the old one so search cannot return the stale neighbour.
+            if (previous?.vector && this._index?.has(record.id)) {
+                this._tombstones.add(record.id);
+                this._maybeRebuild();
+                continue;
+            }
+            if (this._index && !this._index.has(record.id)) {
+                this._index.add(record.id, record.vector);
+                this._tombstones.delete(record.id);
+            }
+        }
+        return { upserted, skipped: 0 };
+    }
+    async fetch(ids) {
+        const out = [];
+        for (const id of ids) {
+            const record = this._records.get(id);
+            if (record)
+                out.push(record);
+        }
+        return out;
+    }
+    async delete(ids) {
+        let removed = 0;
+        for (const id of ids) {
+            if (!this._records.delete(id))
+                continue;
+            removed += 1;
+            if (this._index?.has(id))
+                this._tombstones.add(id);
+        }
+        this._maybeRebuild();
+        return removed;
+    }
+    async deleteByFilter(filter, scope) {
+        const effective = combineFilters(filter, scope);
+        const doomed = [...this._records.values()]
+            .filter((r) => matchesFilter(r.metadata, effective))
+            .map((r) => r.id);
+        return this.delete(doomed);
+    }
+    async count(filter, scope) {
+        const effective = combineFilters(filter, scope);
+        if (!effective)
+            return this._records.size;
+        let n = 0;
+        for (const record of this._records.values()) {
+            if (matchesFilter(record.metadata, effective))
+                n += 1;
+        }
+        return n;
+    }
+    async query(query) {
+        const topK = Math.max(1, query.topK ?? 10);
+        const minScore = query.minScore ?? 0;
+        const filter = combineFilters(query.filter, query.scope);
+        if (!query.vector) {
+            // No embedding: degrade to a filter-only listing rather than returning
+            // nothing, so metadata-only lookups do not need a second code path.
+            return this._visible(filter)
+                .slice(0, topK)
+                .map((r) => this._toMatch(r, 1, query.includeVectors));
+        }
+        const scored = this._denseScore(query.vector, topK, filter);
+        return scored
+            .filter((hit) => hit.score >= minScore)
+            .slice(0, topK)
+            .map(({ record, score }) => this._toMatch(record, score, query.includeVectors));
+    }
+    /**
+     * BM25 over the visible corpus. Present because lexical recall catches the
+     * exact identifiers (error codes, SKUs, function names) that embeddings blur —
+     * the failure mode enterprise RAG evaluations reliably surface.
+     */
+    async keywordSearch(query) {
+        const text = query.text?.trim();
+        if (!text)
+            return [];
+        const topK = Math.max(1, query.topK ?? 10);
+        const filter = combineFilters(query.filter, query.scope);
+        const visible = this._visible(filter);
+        if (visible.length === 0)
+            return [];
+        const hits = bm25Search(text, visible.map((r) => ({ id: r.id, text: r.text })));
+        const best = hits[0]?.score ?? 0;
+        return hits.slice(0, topK).map((hit) => {
+            const record = this._records.get(hit.id);
+            // BM25 scores are unbounded; normalising against the top hit puts them
+            // on the same [0,1] footing as cosine so fusion weights mean something.
+            return this._toMatch(record, best > 0 ? hit.score / best : 0, query.includeVectors);
+        });
+    }
+    _denseScore(vector, topK, filter) {
+        const embedded = [...this._records.values()].filter((r) => r.vector);
+        const exactScan = () => embedded
+            .filter((r) => matchesFilter(r.metadata, filter))
+            .map((r) => ({ record: r, score: cosineSimilarity(vector, r.vector) }))
+            .sort((a, b) => b.score - a.score);
+        if (embedded.length < this._annThreshold)
+            return exactScan();
+        this._ensureIndex(embedded);
+        const index = this._index;
+        const wanted = filter ? topK * this._overfetch : topK;
+        const hits = index.search(vector, wanted + this._tombstones.size);
+        const matched = [];
+        for (const hit of hits) {
+            if (this._tombstones.has(hit.id))
+                continue;
+            const record = this._records.get(hit.id);
+            if (!record || !matchesFilter(record.metadata, filter))
+                continue;
+            matched.push({ record, score: hit.score });
+        }
+        // The graph could not fill the page under this filter — the filter is more
+        // selective than the over-fetch anticipated, so pay for an exact scan
+        // rather than return a short, silently-truncated result set.
+        if (matched.length < topK && filter)
+            return exactScan();
+        return matched;
+    }
+    _visible(filter) {
+        const all = [...this._records.values()];
+        return filter ? all.filter((r) => matchesFilter(r.metadata, filter)) : all;
+    }
+    _toMatch(record, score, includeVectors) {
+        const match = {
+            id: record.id,
+            text: record.text,
+            score,
+            metadata: record.metadata,
+        };
+        if (includeVectors && record.vector)
+            match.vector = record.vector;
+        return match;
+    }
+    _ensureIndex(embedded) {
+        if (this._index)
+            return;
+        const index = new HnswIndex(this._hnswOpts);
+        for (const record of embedded)
+            index.add(record.id, record.vector);
+        this._index = index;
+        this._tombstones.clear();
+    }
+    _maybeRebuild() {
+        const index = this._index;
+        if (!index || index.size === 0)
+            return;
+        if (this._tombstones.size / index.size < this._rebuildRatio)
+            return;
+        this._index = undefined;
+        this._tombstones.clear();
+    }
+}
+//# sourceMappingURL=MemoryVectorStore.js.map