@seanhogg/builderforce-memory 2026.7.14 → 2026.9.28

package/dist/vectorstore/filter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * vectorstore/filter.ts — the ONE evaluator and the ONE scope compiler.
+ *
+ * Two rules this file exists to enforce:
+ *
+ *   • A filter means the same thing everywhere. The in-process store, the
+ *     post-filter a remote adapter applies when its dialect cannot express a
+ *     clause, the ingest de-duplicator and the eval harness all call
+ *     {@link matchesFilter}. A second implementation would eventually disagree
+ *     about `null` or about a missing field, and a filter that disagrees with
+ *     itself across two code paths is a cross-tenant leak waiting for traffic.
+ *
+ *   • Access scope is compiled, never hand-written. {@link accessFilter} is the
+ *     single definition of "what may this caller see", so a new adapter or a new
+ *     query path inherits the rule instead of re-deriving it.
+ */
+import { type AccessScope, type MetadataFilter, type MetadataRecord } from './types.js';
+/**
+ * Compiles an access scope into a filter.
+ *
+ * The ACL clause is `anyOf(acl, [...principals, '*'])`. Records are required to
+ * carry a non-empty `acl` (ingestion defaults it to `['*']`), which is what makes
+ * the rule fail CLOSED: a record written without an ACL matches nothing rather
+ * than matching everyone.
+ */
+export declare function accessFilter(scope: AccessScope): MetadataFilter;
+/**
+ * ANDs a caller filter with a scope, dropping either when absent.
+ * Returns `undefined` only when neither is present — an unscoped query, which is
+ * legitimate for single-tenant use but never happens by accident, because the
+ * caller had to omit the scope explicitly.
+ */
+export declare function combineFilters(filter?: MetadataFilter, scope?: AccessScope): MetadataFilter | undefined;
+/** Evaluates a filter against one record's metadata. */
+export declare function matchesFilter(metadata: MetadataRecord, filter?: MetadataFilter): boolean;
+/**
+ * Walks a filter tree, reporting every field it touches. Adapters use this to
+ * decide up front whether a dialect can push the whole filter down, or whether a
+ * post-filter pass is needed.
+ */
+export declare function filterFields(filter: MetadataFilter, out?: Set<string>): Set<string>;
+//# sourceMappingURL=filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/vectorstore/filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAKH,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EAEtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,CAW/D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC1B,MAAM,CAAC,EAAE,cAAc,EACvB,KAAK,CAAC,EAAE,WAAW,GACpB,cAAc,GAAG,SAAS,CAI5B;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CA8BxF;AAkCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,cAAoB,GAAG,GAAG,CAAC,MAAM,CAAC,CAazF"}

package/dist/vectorstore/filter.js

@@ -0,0 +1,132 @@
+/**
+ * vectorstore/filter.ts — the ONE evaluator and the ONE scope compiler.
+ *
+ * Two rules this file exists to enforce:
+ *
+ *   • A filter means the same thing everywhere. The in-process store, the
+ *     post-filter a remote adapter applies when its dialect cannot express a
+ *     clause, the ingest de-duplicator and the eval harness all call
+ *     {@link matchesFilter}. A second implementation would eventually disagree
+ *     about `null` or about a missing field, and a filter that disagrees with
+ *     itself across two code paths is a cross-tenant leak waiting for traffic.
+ *
+ *   • Access scope is compiled, never hand-written. {@link accessFilter} is the
+ *     single definition of "what may this caller see", so a new adapter or a new
+ *     query path inherits the rule instead of re-deriving it.
+ */
+import { ACL_FIELD, ACL_PUBLIC, SENSITIVITY_FIELD, TENANT_FIELD, } from './types.js';
+/**
+ * Compiles an access scope into a filter.
+ *
+ * The ACL clause is `anyOf(acl, [...principals, '*'])`. Records are required to
+ * carry a non-empty `acl` (ingestion defaults it to `['*']`), which is what makes
+ * the rule fail CLOSED: a record written without an ACL matches nothing rather
+ * than matching everyone.
+ */
+export function accessFilter(scope) {
+    const clauses = [
+        { op: 'eq', field: TENANT_FIELD, value: scope.tenantId },
+        { op: 'anyOf', field: ACL_FIELD, values: [...(scope.principals ?? []), ACL_PUBLIC] },
+    ];
+    if (scope.maxSensitivity !== undefined) {
+        clauses.push({ op: 'lte', field: SENSITIVITY_FIELD, value: scope.maxSensitivity });
+    }
+    return { op: 'and', filters: clauses };
+}
+/**
+ * ANDs a caller filter with a scope, dropping either when absent.
+ * Returns `undefined` only when neither is present — an unscoped query, which is
+ * legitimate for single-tenant use but never happens by accident, because the
+ * caller had to omit the scope explicitly.
+ */
+export function combineFilters(filter, scope) {
+    const scoped = scope ? accessFilter(scope) : undefined;
+    if (filter && scoped)
+        return { op: 'and', filters: [scoped, filter] };
+    return filter ?? scoped;
+}
+/** Evaluates a filter against one record's metadata. */
+export function matchesFilter(metadata, filter) {
+    if (!filter)
+        return true;
+    switch (filter.op) {
+        case 'and':
+            return filter.filters.every((f) => matchesFilter(metadata, f));
+        case 'or':
+            return filter.filters.some((f) => matchesFilter(metadata, f));
+        case 'not':
+            return !matchesFilter(metadata, filter.filter);
+        case 'exists':
+            return metadata[filter.field] !== undefined && metadata[filter.field] !== null;
+        case 'in':
+            return filter.values.some((v) => scalarEquals(metadata[filter.field], v));
+        case 'nin':
+            return !filter.values.some((v) => scalarEquals(metadata[filter.field], v));
+        case 'anyOf': {
+            const actual = metadata[filter.field];
+            if (actual === undefined || actual === null)
+                return false;
+            const held = Array.isArray(actual) ? actual : [actual];
+            return held.some((h) => filter.values.some((v) => scalarEquals(h, v)));
+        }
+        case 'contains': {
+            const actual = metadata[filter.field];
+            if (typeof actual !== 'string')
+                return false;
+            return actual.toLowerCase().includes(filter.value.toLowerCase());
+        }
+        default:
+            return compare(metadata[filter.field], filter.op, filter.value);
+    }
+}
+function scalarEquals(a, b) {
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return Array.isArray(a) && Array.isArray(b)
+            && a.length === b.length
+            && a.every((v, i) => v === b[i]);
+    }
+    return a === b;
+}
+function compare(actual, op, expected) {
+    if (op === 'eq')
+        return scalarEquals(actual, expected);
+    if (op === 'ne')
+        return !scalarEquals(actual, expected);
+    // Ordering comparisons on a missing or non-scalar field are false rather than
+    // throwing: a record without the field simply does not satisfy `sensitivity <= n`.
+    if (actual === undefined || actual === null)
+        return false;
+    if (Array.isArray(actual) || Array.isArray(expected) || expected === null)
+        return false;
+    if (typeof actual !== typeof expected)
+        return false;
+    if (typeof actual === 'boolean' || typeof expected === 'boolean')
+        return false;
+    switch (op) {
+        case 'gt': return actual > expected;
+        case 'gte': return actual >= expected;
+        case 'lt': return actual < expected;
+        default: return actual <= expected;
+    }
+}
+/**
+ * Walks a filter tree, reporting every field it touches. Adapters use this to
+ * decide up front whether a dialect can push the whole filter down, or whether a
+ * post-filter pass is needed.
+ */
+export function filterFields(filter, out = new Set()) {
+    switch (filter.op) {
+        case 'and':
+        case 'or':
+            for (const f of filter.filters)
+                filterFields(f, out);
+            break;
+        case 'not':
+            filterFields(filter.filter, out);
+            break;
+        default:
+            out.add(filter.field);
+    }
+    return out;
+}
+//# sourceMappingURL=filter.js.map

package/dist/vectorstore/filter.js.map

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

package/dist/vectorstore/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * vectorstore — the VectorStore port, its declarative filter algebra, and the
+ * adapters. Tenant/ACL scope is compiled into every read, so multi-tenant RAG
+ * fails closed rather than depending on each caller remembering to scope.
+ */
+export { MemoryVectorStore } from './MemoryVectorStore.js';
+export type { MemoryVectorStoreOptions } from './MemoryVectorStore.js';
+export { RestVectorStore } from './RestVectorStore.js';
+export type { RestVectorStoreOptions } from './RestVectorStore.js';
+export { getDialect, listDialects, registerDialect, evermindDialect, qdrantDialect, pineconeDialect, vertexAiDialect, } from './dialects.js';
+export type { VectorDialect, DialectContext, HttpRequest, TranslatedFilter, } from './dialects.js';
+export { accessFilter, combineFilters, matchesFilter, filterFields, } from './filter.js';
+export { TENANT_FIELD, ACL_FIELD, SENSITIVITY_FIELD, ACL_PUBLIC, } from './types.js';
+export type { AccessScope, ComparisonOp, MetadataFilter, MetadataRecord, MetadataValue, UpsertResult, VectorMatch, VectorQuery, VectorRecord, VectorStore, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vectorstore/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EACH,UAAU,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,aAAa,EACb,eAAe,EACf,eAAe,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACR,aAAa,EACb,cAAc,EACd,WAAW,EACX,gBAAgB,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACH,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACH,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,UAAU,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EACR,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,GACd,MAAM,YAAY,CAAC"}

package/dist/vectorstore/index.js

@@ -0,0 +1,11 @@
+/**
+ * vectorstore — the VectorStore port, its declarative filter algebra, and the
+ * adapters. Tenant/ACL scope is compiled into every read, so multi-tenant RAG
+ * fails closed rather than depending on each caller remembering to scope.
+ */
+export { MemoryVectorStore } from './MemoryVectorStore.js';
+export { RestVectorStore } from './RestVectorStore.js';
+export { getDialect, listDialects, registerDialect, evermindDialect, qdrantDialect, pineconeDialect, vertexAiDialect, } from './dialects.js';
+export { accessFilter, combineFilters, matchesFilter, filterFields, } from './filter.js';
+export { TENANT_FIELD, ACL_FIELD, SENSITIVITY_FIELD, ACL_PUBLIC, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/vectorstore/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vectorstore/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EACH,UAAU,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,aAAa,EACb,eAAe,EACf,eAAe,GAClB,MAAM,eAAe,CAAC;AAQvB,OAAO,EACH,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACH,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,UAAU,GACb,MAAM,YAAY,CAAC"}

package/dist/vectorstore/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * vectorstore/types.ts — the VectorStore port.
+ *
+ * Enterprise deployments do not get to choose the vector database; the customer
+ * already has one (pgvector in their Cloud SQL, Vertex AI Vector Search because
+ * they are a GCP shop, Qdrant because platform standardised on it). So the store
+ * is a PORT, and every adapter is infrastructure behind it. Retrieval, ingestion
+ * and evaluation depend on this interface and never on a vendor.
+ *
+ * Two things make it enterprise-grade rather than a toy vector index:
+ *
+ *   1. **Filters are DATA, not predicates.** A `(record) => boolean` cannot be
+ *      pushed down to a remote database — it forces fetch-everything-then-filter,
+ *      which is both slow and a data-leak: rows the caller may not see are read
+ *      into the process before being dropped. {@link MetadataFilter} is a small
+ *      declarative algebra each adapter translates into its own query language.
+ *
+ *   2. **Access scope is first-class.** Multi-tenant RAG fails closed only if the
+ *      tenant predicate is part of the query the database runs. {@link AccessScope}
+ *      compiles to a filter that is AND-ed into every read, so "forgot to scope the
+ *      query" is not a reachable state.
+ */
+export type MetadataValue = string | number | boolean | null | string[];
+export type MetadataRecord = Record<string, MetadataValue>;
+/** A stored unit of retrievable knowledge. */
+export interface VectorRecord {
+    id: string;
+    /** The chunk text — returned with matches so a retriever can rerank on it. */
+    text: string;
+    /** Embedding. Optional so a store can embed server-side. */
+    vector?: Float32Array;
+    metadata: MetadataRecord;
+}
+export interface VectorMatch {
+    id: string;
+    text: string;
+    /** Similarity in [0,1] — cosine for every adapter here. */
+    score: number;
+    metadata: MetadataRecord;
+    vector?: Float32Array;
+}
+export type ComparisonOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+export type MetadataFilter = {
+    op: ComparisonOp;
+    field: string;
+    value: MetadataValue;
+}
+/** Field equals any of `values` (scalar field). */
+ | {
+    op: 'in' | 'nin';
+    field: string;
+    values: MetadataValue[];
+}
+/**
+ * Field (an array, or a scalar treated as a one-element array) intersects
+ * `values`. This is the ACL primitive — every mainstream vector database can
+ * express "array field matches any of", which is why ACLs are modelled as an
+ * array rather than as a bitmask or a nested object.
+ */
+ | {
+    op: 'anyOf';
+    field: string;
+    values: MetadataValue[];
+}
+/** Case-insensitive substring match on a string field. */
+ | {
+    op: 'contains';
+    field: string;
+    value: string;
+} | {
+    op: 'exists';
+    field: string;
+} | {
+    op: 'and';
+    filters: MetadataFilter[];
+} | {
+    op: 'or';
+    filters: MetadataFilter[];
+} | {
+    op: 'not';
+    filter: MetadataFilter;
+};
+/**
+ * The non-composite half of the algebra — every variant that names a `field`.
+ * Dialect translation works leaf-by-leaf, so having the type say so removes a
+ * cast from every adapter.
+ */
+export type LeafFilter = Extract<MetadataFilter, {
+    field: string;
+}>;
+/** Metadata keys the access model reserves. Ingestion always populates them. */
+export declare const TENANT_FIELD = "tenantId";
+export declare const ACL_FIELD = "acl";
+export declare const SENSITIVITY_FIELD = "sensitivity";
+/** ACL entry meaning "any principal within the tenant". */
+export declare const ACL_PUBLIC = "*";
+export interface AccessScope {
+    /** Hard tenant boundary. Every read is AND-ed with an equality on this. */
+    tenantId: string;
+    /**
+     * Group / role / user ids the caller holds. A record is visible when its `acl`
+     * array intersects these, or contains {@link ACL_PUBLIC}. Omit for
+     * tenant-wide access to public records only.
+     */
+    principals?: string[];
+    /**
+     * Highest classification level the caller may read (records carry a numeric
+     * `sensitivity`). Omit for no ceiling.
+     */
+    maxSensitivity?: number;
+}
+export interface VectorQuery {
+    /** Dense query embedding. Required unless the adapter embeds server-side. */
+    vector?: Float32Array;
+    /** Raw query text — used by `keywordSearch`, and by server-side embedders. */
+    text?: string;
+    /** Results to return. Default 10. */
+    topK?: number;
+    /** Declarative metadata predicate, pushed down to the store. */
+    filter?: MetadataFilter;
+    /** Tenant/ACL scope, AND-ed with `filter`. */
+    scope?: AccessScope;
+    /** Drop matches scoring below this. Default 0. */
+    minScore?: number;
+    /** Return stored vectors on matches (costs bandwidth). Default false. */
+    includeVectors?: boolean;
+}
+export interface UpsertResult {
+    upserted: number;
+    /** Ids the store considered unchanged and skipped, when it can tell. */
+    skipped: number;
+}
+/**
+ * The port. `keywordSearch` is optional because not every vector database has a
+ * lexical index; retrievers degrade to dense-only and SAY SO on the span rather
+ * than silently returning worse results.
+ */
+export interface VectorStore {
+    /** Adapter name, stamped on telemetry spans. */
+    readonly name: string;
+    upsert(records: readonly VectorRecord[]): Promise<UpsertResult>;
+    query(query: VectorQuery): Promise<VectorMatch[]>;
+    delete(ids: readonly string[]): Promise<number>;
+    /** Bulk delete by predicate — how an incremental sync removes a stale source. */
+    deleteByFilter(filter: MetadataFilter, scope?: AccessScope): Promise<number>;
+    fetch(ids: readonly string[]): Promise<VectorRecord[]>;
+    count(filter?: MetadataFilter, scope?: AccessScope): Promise<number>;
+    /** Lexical/BM25 search, when the adapter supports one. */
+    keywordSearch?(query: VectorQuery): Promise<VectorMatch[]>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/vectorstore/types.js

@@ -0,0 +1,30 @@
+/**
+ * vectorstore/types.ts — the VectorStore port.
+ *
+ * Enterprise deployments do not get to choose the vector database; the customer
+ * already has one (pgvector in their Cloud SQL, Vertex AI Vector Search because
+ * they are a GCP shop, Qdrant because platform standardised on it). So the store
+ * is a PORT, and every adapter is infrastructure behind it. Retrieval, ingestion
+ * and evaluation depend on this interface and never on a vendor.
+ *
+ * Two things make it enterprise-grade rather than a toy vector index:
+ *
+ *   1. **Filters are DATA, not predicates.** A `(record) => boolean` cannot be
+ *      pushed down to a remote database — it forces fetch-everything-then-filter,
+ *      which is both slow and a data-leak: rows the caller may not see are read
+ *      into the process before being dropped. {@link MetadataFilter} is a small
+ *      declarative algebra each adapter translates into its own query language.
+ *
+ *   2. **Access scope is first-class.** Multi-tenant RAG fails closed only if the
+ *      tenant predicate is part of the query the database runs. {@link AccessScope}
+ *      compiles to a filter that is AND-ed into every read, so "forgot to scope the
+ *      query" is not a reachable state.
+ */
+// ── Access scope ──────────────────────────────────────────────────────────────
+/** Metadata keys the access model reserves. Ingestion always populates them. */
+export const TENANT_FIELD = 'tenantId';
+export const ACL_FIELD = 'acl';
+export const SENSITIVITY_FIELD = 'sensitivity';
+/** ACL entry meaning "any principal within the tenant". */
+export const ACL_PUBLIC = '*';
+//# sourceMappingURL=types.js.map

package/dist/vectorstore/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/vectorstore/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA0DH,iFAAiF;AAEjF,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AACvC,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC;AAC/B,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAC/C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.7.14",
-  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, hybrid RAG retrieval, and persistent agent memory for BuilderForce.ai agents.",
+  "version": "2026.9.28",
+  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,34 @@
     "./retrieval": {
       "types": "./dist/retrieval/index.d.ts",
       "import": "./dist/retrieval/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "import": "./dist/telemetry/index.js"
+    },
+    "./vectorstore": {
+      "types": "./dist/vectorstore/index.d.ts",
+      "import": "./dist/vectorstore/index.js"
+    },
+    "./ingest": {
+      "types": "./dist/ingest/index.d.ts",
+      "import": "./dist/ingest/index.js"
+    },
+    "./rag": {
+      "types": "./dist/rag/index.d.ts",
+      "import": "./dist/rag/index.js"
+    },
+    "./orchestration": {
+      "types": "./dist/orchestration/index.d.ts",
+      "import": "./dist/orchestration/index.js"
+    },
+    "./eval": {
+      "types": "./dist/eval/index.d.ts",
+      "import": "./dist/eval/index.js"
+    },
+    "./evermind": {
+      "types": "./dist/evermind/index.d.ts",
+      "import": "./dist/evermind/index.js"
     }
   },
   "type": "module",
@@ -35,7 +63,13 @@
     "browser-ai",
     "agent-memory",
     "builderforce",
-    "typescript"
+    "typescript",
+    "rag",
+    "vector-database",
+    "multi-agent",
+    "observability",
+    "enterprise-ai",
+    "langgraph-alternative"
   ],
   "author": {
     "name": "Sean Hogg",
@@ -53,7 +87,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.7.14"
+    "@seanhogg/builderforce-memory-engine": "^2026.9.28"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -67,7 +101,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.7.14"
+    "@seanhogg/builderforce-memory-engine": "2026.9.28"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/bridges/AnthropicBridge.ts

@@ -6,7 +6,8 @@
  */
 
 import { SSMError } from '../errors/SSMError.js';
-import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import type { LlmUsage } from '../telemetry/types.js';
+import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
 
 export interface AnthropicBridgeOptions {
     /** Anthropic API key. */
@@ -46,6 +47,8 @@ export class AnthropicBridge implements TransformerBridge {
     private readonly _maxTokens   : number;
     private readonly _cacheSystem : boolean;
 
+    private _lastCall: BridgeCallInfo | undefined;
+
     constructor(opts: AnthropicBridgeOptions) {
         this._apiKey       = opts.apiKey;
         this._model        = opts.model      ?? 'claude-haiku-4-5';
@@ -55,6 +58,16 @@ export class AnthropicBridge implements TransformerBridge {
         this._cacheSystem  = opts.cacheSystem  ?? true;
     }
 
+    /**
+     * Provider-reported usage for the last call. Anthropic splits input tokens
+     * three ways — fresh, cache read, and cache write — and each is billed at a
+     * different rate, so a cost model that only reads `input_tokens` is wrong on
+     * exactly the cache-heavy traffic this bridge is tuned to produce.
+     */
+    get lastCall(): BridgeCallInfo | undefined {
+        return this._lastCall;
+    }
+
     async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
         const body = this._buildBody(prompt, opts, false);
         const res  = await this._fetch(body);
@@ -72,6 +85,12 @@ export class AnthropicBridge implements TransformerBridge {
         if (typeof content !== 'string') {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected Anthropic response shape.');
         }
+        this._lastCall = {
+            usage: readAnthropicUsage(
+                (json as any).usage,
+                (json as any).model ?? opts.model ?? this._model,
+            ),
+        };
         return content;
     }
 
@@ -91,7 +110,32 @@ export class AnthropicBridge implements TransformerBridge {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Anthropic streaming response has no body.');
         }
 
-        yield* parseAnthropicStream(res.body);
+        const model = opts.model ?? this._model;
+        let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, reportedModel = model;
+
+        yield* parseAnthropicStream(res.body, (event) => {
+            // `message_start` carries the input split; `message_delta` the running
+            // output count. Both are folded so the final usage is provider-measured.
+            const start = (event as any).message?.usage;
+            const delta = (event as any).usage;
+            const usage = start ?? delta;
+            if (!usage) return;
+            if (typeof (event as any).message?.model === 'string') reportedModel = (event as any).message.model;
+            input      = Math.max(input,      Number(usage.input_tokens) || 0);
+            output     = Math.max(output,     Number(usage.output_tokens) || 0);
+            cacheRead  = Math.max(cacheRead,  Number(usage.cache_read_input_tokens) || 0);
+            cacheWrite = Math.max(cacheWrite, Number(usage.cache_creation_input_tokens) || 0);
+        });
+
+        this._lastCall = {
+            usage: {
+                model: reportedModel,
+                inputTokens: input,
+                outputTokens: output,
+                cachedInputTokens: cacheRead,
+                cacheWriteTokens: cacheWrite,
+            },
+        };
     }
 
     private _buildBody(prompt: string, opts: BridgeGenerateOptions, stream: boolean): string {
@@ -129,7 +173,10 @@ export class AnthropicBridge implements TransformerBridge {
 
 // ── SSE parser (Anthropic event format) ──────────────────────────────────────
 
-async function* parseAnthropicStream(body: ReadableStream<Uint8Array>): AsyncIterable<string> {
+async function* parseAnthropicStream(
+    body: ReadableStream<Uint8Array>,
+    onEvent?: (event: Record<string, unknown>) => void,
+): AsyncIterable<string> {
     const reader  = body.getReader();
     const decoder = new TextDecoder();
     let buffer    = '';
@@ -150,6 +197,7 @@ async function* parseAnthropicStream(body: ReadableStream<Uint8Array>): AsyncIte
                 const data = trimmed.slice(6);
                 try {
                     const event = JSON.parse(data) as Record<string, unknown>;
+                    onEvent?.(event);
                     // content_block_delta events carry the streamed text
                     if (event['type'] === 'content_block_delta') {
                         const text = (event as any).delta?.text;
@@ -164,3 +212,20 @@ async function* parseAnthropicStream(body: ReadableStream<Uint8Array>): AsyncIte
         reader.releaseLock();
     }
 }
+
+/**
+ * Maps an Anthropic `usage` object onto the canonical {@link LlmUsage} shape.
+ * Absent when the response omits usage (an older gateway shim), in which case
+ * `InstrumentedBridge` falls back to an estimate and flags it as such.
+ */
+function readAnthropicUsage(usage: unknown, model: string): LlmUsage | undefined {
+    if (!usage || typeof usage !== 'object') return undefined;
+    const u = usage as Record<string, unknown>;
+    return {
+        model,
+        inputTokens: Number(u['input_tokens']) || 0,
+        outputTokens: Number(u['output_tokens']) || 0,
+        cachedInputTokens: Number(u['cache_read_input_tokens']) || 0,
+        cacheWriteTokens: Number(u['cache_creation_input_tokens']) || 0,
+    };
+}