@framers/agentos 0.2.6 → 0.2.8

package/dist/memory-router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory-router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAYH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAoC9D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,kCAAkC,GACnC,MAAM,mBAAmB,CAAC;AAgB3B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/memory-router/routing-tables.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link MemoryRouter}.
+ *
+ * The MemoryRouter dispatches each query to one of the available
+ * {@link MemoryBackendId} backends based on the classifier-predicted
+ * {@link MemoryQueryCategory}. The mapping from category to backend is a
+ * "routing table" — a frozen object that callers can pass through unchanged
+ * for the shipping defaults, or override per-category for custom workloads.
+ *
+ * Three preset tables ship out of the box, each calibrated from Phase B
+ * N=500 LongMemEval-S measurements:
+ *
+ * - {@link MINIMIZE_COST_TABLE}: cheapest Pareto-dominant backend per
+ *   category. Pays the OM premium only on multi-session and
+ *   single-session-preference (the categories where the architectural lift
+ *   exceeds the cost premium).
+ * - {@link BALANCED_TABLE}: trades modest cost for large latency wins on
+ *   knowledge-update and temporal-reasoning.
+ * - {@link MAXIMIZE_ACCURACY_TABLE}: highest-accuracy backend per category;
+ *   ties broken by cost. v2 (post-Phase-B-2026-04-24) routes
+ *   temporal-reasoning back to canonical-hybrid after Phase B revealed the
+ *   v1 routing's accuracy gain was within CI noise but paid OM ingest cost.
+ *
+ * @module @framers/agentos/memory-router/routing-tables
+ */
+/**
+ * The six question categories the LLM-as-judge classifier produces.
+ * Calibrated from LongMemEval-S categories; mappings to other benchmark
+ * taxonomies (e.g. LOCOMO single-hop / multi-hop / temporal /
+ * open-domain / adversarial) are handled at adapter boundaries.
+ */
+export declare const MEMORY_QUERY_CATEGORIES: readonly ["single-session-user", "single-session-assistant", "single-session-preference", "knowledge-update", "multi-session", "temporal-reasoning"];
+/**
+ * The six question categories the LLM-as-judge classifier produces.
+ */
+export type MemoryQueryCategory = (typeof MEMORY_QUERY_CATEGORIES)[number];
+/**
+ * The retrieval architecture identifiers the router can dispatch to.
+ *
+ * - `canonical-hybrid`: BM25 + dense + RRF fusion + Cohere rerank-v3.5
+ *   over the raw memory traces. The default cheapest-and-fastest path.
+ * - `observational-memory-v10`: synthesized observation log fed to the
+ *   reader, with classifier-driven routing inside the OM pipeline. No
+ *   verbatim citation rule.
+ * - `observational-memory-v11`: same as v10 but with conditional
+ *   verbatim citation appended for knowledge-update and
+ *   single-session-user categories. Wins on multi-session and
+ *   single-session-preference.
+ *
+ * Backend execution itself lives in {@link MemoryDispatcher}; this type
+ * is the contract between the routing decision and the dispatcher.
+ */
+export type MemoryBackendId = 'canonical-hybrid' | 'observational-memory-v10' | 'observational-memory-v11';
+/**
+ * The three shipping presets. Each preset corresponds to a distinct point
+ * on the Phase B-measured cost-accuracy Pareto frontier.
+ */
+export type MemoryRouterPreset = 'minimize-cost' | 'balanced' | 'maximize-accuracy';
+/**
+ * A routing table maps every {@link MemoryQueryCategory} to its preferred
+ * {@link MemoryBackendId} for the given preset. Tables ship frozen so
+ * consumers cannot mutate the routing surface from outside the module.
+ */
+export interface RoutingTable {
+    readonly preset: MemoryRouterPreset;
+    readonly defaultMapping: Readonly<Record<MemoryQueryCategory, MemoryBackendId>>;
+}
+/**
+ * Preset: minimize-cost.
+ *
+ * Pareto-dominant cheapest backend per category. Pays the OM premium only
+ * on the two categories where the architectural lift earns it
+ * (multi-session +6.8pp, single-session-preference +3.3pp). Every other
+ * category routes to canonical-hybrid where Phase B measurements show the
+ * cheaper backend either dominates or matches within CI noise.
+ *
+ * Phase B simulation: 73.9% accuracy at $0.092/correct; oracle ceiling
+ * 76.0% at $0.157/correct. **Pareto-dominates the all-Tier-2b flat
+ * baseline by 4.77x cost reduction at +0.5pp accuracy** on the
+ * LongMemEval-S Phase B distribution.
+ *
+ * Recommended default for cost-sensitive workloads.
+ */
+export declare const MINIMIZE_COST_TABLE: RoutingTable;
+/**
+ * Preset: balanced.
+ *
+ * Trades 1.6x cost for >10x latency reductions on knowledge-update and
+ * temporal-reasoning. Phase B measurements show Tier 2a v10 ties Tier 1
+ * canonical on accuracy for these two categories at much lower latency
+ * (4-19s vs 80-100s) — the latency win comes from skipping per-turn
+ * cognitive replay in favor of synthesized observations.
+ *
+ * Phase B simulation: 74.5% accuracy at $0.205/correct; 2.12x cheaper
+ * than Tier 2b flat with comparable accuracy.
+ *
+ * Recommended for interactive workloads where latency matters and the
+ * cost premium over minimize-cost is acceptable.
+ */
+export declare const BALANCED_TABLE: RoutingTable;
+/**
+ * Preset: maximize-accuracy (v2).
+ *
+ * Highest-accuracy backend per category, ties broken by cost. v2
+ * (2026-04-24, post-Phase-B) routes temporal-reasoning back to
+ * canonical-hybrid after Phase B revealed:
+ *   - v1 routing (TR -> Tier 2a) paid OM ingest cost for a within-CI
+ *     accuracy gain (71.0% Tier 2a vs 70.2% Tier 1) on a hold-out slice;
+ *   - combined with classifier misroutes the aggregate fell below the
+ *     74% acceptance floor at 73.8%.
+ * v2 keeps TR on canonical-hybrid where it's cheapest and
+ * accuracy-equivalent.
+ *
+ * Phase B measured: 75.6% [71.8, 79.2] at $0.2434/correct, 65.6s avg
+ * latency.
+ */
+export declare const MAXIMIZE_ACCURACY_TABLE: RoutingTable;
+/**
+ * Convenience registry of all three preset tables, keyed by preset name.
+ * Useful when surfacing presets through a CLI flag or config field where
+ * the preset name is a string and the consumer needs the table object.
+ */
+export declare const PRESET_TABLES: Readonly<Record<MemoryRouterPreset, RoutingTable>>;
+//# sourceMappingURL=routing-tables.d.ts.map

package/dist/memory-router/routing-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.d.ts","sourceRoot":"","sources":["../../src/memory-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,sJAO1B,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,UAAU,GACV,mBAAmB,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC,CAAC;CACjF;AAMD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAUhB,CAAC;AAEnB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,YAUX,CAAC;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,EAAE,YAUpB,CAAC;AAEnB;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAKzE,CAAC"}

package/dist/memory-router/routing-tables.js

@@ -0,0 +1,137 @@
+/**
+ * @file routing-tables.ts
+ * @description Preset routing tables for {@link MemoryRouter}.
+ *
+ * The MemoryRouter dispatches each query to one of the available
+ * {@link MemoryBackendId} backends based on the classifier-predicted
+ * {@link MemoryQueryCategory}. The mapping from category to backend is a
+ * "routing table" — a frozen object that callers can pass through unchanged
+ * for the shipping defaults, or override per-category for custom workloads.
+ *
+ * Three preset tables ship out of the box, each calibrated from Phase B
+ * N=500 LongMemEval-S measurements:
+ *
+ * - {@link MINIMIZE_COST_TABLE}: cheapest Pareto-dominant backend per
+ *   category. Pays the OM premium only on multi-session and
+ *   single-session-preference (the categories where the architectural lift
+ *   exceeds the cost premium).
+ * - {@link BALANCED_TABLE}: trades modest cost for large latency wins on
+ *   knowledge-update and temporal-reasoning.
+ * - {@link MAXIMIZE_ACCURACY_TABLE}: highest-accuracy backend per category;
+ *   ties broken by cost. v2 (post-Phase-B-2026-04-24) routes
+ *   temporal-reasoning back to canonical-hybrid after Phase B revealed the
+ *   v1 routing's accuracy gain was within CI noise but paid OM ingest cost.
+ *
+ * @module @framers/agentos/memory-router/routing-tables
+ */
+// ============================================================================
+// Public types
+// ============================================================================
+/**
+ * The six question categories the LLM-as-judge classifier produces.
+ * Calibrated from LongMemEval-S categories; mappings to other benchmark
+ * taxonomies (e.g. LOCOMO single-hop / multi-hop / temporal /
+ * open-domain / adversarial) are handled at adapter boundaries.
+ */
+export const MEMORY_QUERY_CATEGORIES = [
+    'single-session-user',
+    'single-session-assistant',
+    'single-session-preference',
+    'knowledge-update',
+    'multi-session',
+    'temporal-reasoning',
+];
+// ============================================================================
+// Preset tables
+// ============================================================================
+/**
+ * Preset: minimize-cost.
+ *
+ * Pareto-dominant cheapest backend per category. Pays the OM premium only
+ * on the two categories where the architectural lift earns it
+ * (multi-session +6.8pp, single-session-preference +3.3pp). Every other
+ * category routes to canonical-hybrid where Phase B measurements show the
+ * cheaper backend either dominates or matches within CI noise.
+ *
+ * Phase B simulation: 73.9% accuracy at $0.092/correct; oracle ceiling
+ * 76.0% at $0.157/correct. **Pareto-dominates the all-Tier-2b flat
+ * baseline by 4.77x cost reduction at +0.5pp accuracy** on the
+ * LongMemEval-S Phase B distribution.
+ *
+ * Recommended default for cost-sensitive workloads.
+ */
+export const MINIMIZE_COST_TABLE = Object.freeze({
+    preset: 'minimize-cost',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': 'canonical-hybrid',
+        'single-session-user': 'canonical-hybrid',
+        'temporal-reasoning': 'canonical-hybrid',
+        'knowledge-update': 'canonical-hybrid',
+        'multi-session': 'observational-memory-v11',
+        'single-session-preference': 'observational-memory-v11',
+    }),
+});
+/**
+ * Preset: balanced.
+ *
+ * Trades 1.6x cost for >10x latency reductions on knowledge-update and
+ * temporal-reasoning. Phase B measurements show Tier 2a v10 ties Tier 1
+ * canonical on accuracy for these two categories at much lower latency
+ * (4-19s vs 80-100s) — the latency win comes from skipping per-turn
+ * cognitive replay in favor of synthesized observations.
+ *
+ * Phase B simulation: 74.5% accuracy at $0.205/correct; 2.12x cheaper
+ * than Tier 2b flat with comparable accuracy.
+ *
+ * Recommended for interactive workloads where latency matters and the
+ * cost premium over minimize-cost is acceptable.
+ */
+export const BALANCED_TABLE = Object.freeze({
+    preset: 'balanced',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': 'canonical-hybrid',
+        'single-session-user': 'canonical-hybrid',
+        'temporal-reasoning': 'observational-memory-v10',
+        'knowledge-update': 'observational-memory-v10',
+        'multi-session': 'observational-memory-v11',
+        'single-session-preference': 'observational-memory-v11',
+    }),
+});
+/**
+ * Preset: maximize-accuracy (v2).
+ *
+ * Highest-accuracy backend per category, ties broken by cost. v2
+ * (2026-04-24, post-Phase-B) routes temporal-reasoning back to
+ * canonical-hybrid after Phase B revealed:
+ *   - v1 routing (TR -> Tier 2a) paid OM ingest cost for a within-CI
+ *     accuracy gain (71.0% Tier 2a vs 70.2% Tier 1) on a hold-out slice;
+ *   - combined with classifier misroutes the aggregate fell below the
+ *     74% acceptance floor at 73.8%.
+ * v2 keeps TR on canonical-hybrid where it's cheapest and
+ * accuracy-equivalent.
+ *
+ * Phase B measured: 75.6% [71.8, 79.2] at $0.2434/correct, 65.6s avg
+ * latency.
+ */
+export const MAXIMIZE_ACCURACY_TABLE = Object.freeze({
+    preset: 'maximize-accuracy',
+    defaultMapping: Object.freeze({
+        'single-session-assistant': 'canonical-hybrid',
+        'single-session-user': 'observational-memory-v11',
+        'temporal-reasoning': 'canonical-hybrid',
+        'knowledge-update': 'observational-memory-v11',
+        'multi-session': 'observational-memory-v11',
+        'single-session-preference': 'observational-memory-v11',
+    }),
+});
+/**
+ * Convenience registry of all three preset tables, keyed by preset name.
+ * Useful when surfacing presets through a CLI flag or config field where
+ * the preset name is a string and the consumer needs the table object.
+ */
+export const PRESET_TABLES = Object.freeze({
+    'minimize-cost': MINIMIZE_COST_TABLE,
+    'balanced': BALANCED_TABLE,
+    'maximize-accuracy': MAXIMIZE_ACCURACY_TABLE,
+});
+//# sourceMappingURL=routing-tables.js.map

package/dist/memory-router/routing-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tables.js","sourceRoot":"","sources":["../../src/memory-router/routing-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,qBAAqB;IACrB,0BAA0B;IAC1B,2BAA2B;IAC3B,kBAAkB;IAClB,eAAe;IACf,oBAAoB;CACZ,CAAC;AA+CX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAiB,MAAM,CAAC,MAAM,CAAC;IAC7D,MAAM,EAAE,eAAwB;IAChC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,kBAAkB;QACzC,oBAAoB,EAAE,kBAAkB;QACxC,kBAAkB,EAAE,kBAAkB;QACtC,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiB,MAAM,CAAC,MAAM,CAAC;IACxD,MAAM,EAAE,UAAmB;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,kBAAkB;QACzC,oBAAoB,EAAE,0BAA0B;QAChD,kBAAkB,EAAE,0BAA0B;QAC9C,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAiB,MAAM,CAAC,MAAM,CAAC;IACjE,MAAM,EAAE,mBAA4B;IACpC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;QAC5B,0BAA0B,EAAE,kBAAkB;QAC9C,qBAAqB,EAAE,0BAA0B;QACjD,oBAAoB,EAAE,kBAAkB;QACxC,kBAAkB,EAAE,0BAA0B;QAC9C,eAAe,EAAE,0BAA0B;QAC3C,2BAA2B,EAAE,0BAA0B;KACxD,CAAC;CACH,CAAiB,CAAC;AAEnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,MAAM,CAAC,MAAM,CAAC;IACZ,eAAe,EAAE,mBAAmB;IACpC,UAAU,EAAE,cAAc;IAC1B,mBAAmB,EAAE,uBAAuB;CAC7C,CAAC,CAAC"}

package/dist/memory-router/select-backend.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @file select-backend.ts
+ * @description Pure function that turns a classifier-predicted category
+ * + a {@link MemoryRouterConfig} into a {@link MemoryRoutingDecision}.
+ *
+ * Stateless. Deterministic. No I/O. Suitable for use inside hot dispatch
+ * loops and inside cache-key construction (the function's output is a
+ * pure function of its inputs).
+ *
+ * The decision carries:
+ *   - the chosen {@link MemoryBackendId},
+ *   - the predicted category (and optional ground-truth for telemetry),
+ *   - the estimated USD cost of the routing pick,
+ *   - the budget ceiling (if any) and whether the pick exceeded it,
+ *   - a human-readable reason explaining the routing path taken.
+ *
+ * @module @framers/agentos/memory-router/select-backend
+ */
+import type { MemoryBackendCostPoint } from './backend-costs.js';
+import type { MemoryBackendId, MemoryQueryCategory, MemoryRouterPreset, RoutingTable } from './routing-tables.js';
+/**
+ * Budget enforcement modes:
+ *   - `hard`: throw {@link MemoryRouterBudgetExceededError} if the
+ *     routing-table pick exceeds the per-query USD budget. Lets callers
+ *     escalate at the application layer (e.g. fall back to a reduced
+ *     pipeline or surface a 402-style error).
+ *   - `soft`: exceed the budget only when the picked backend has a
+ *     better USD-per-correct ratio than the cheapest backend that fits.
+ *     Prefers accuracy-economical overflows.
+ *   - `cheapest-fallback`: silently downgrade to the cheapest backend
+ *     that fits the budget. Suitable for cost-strict workloads where
+ *     correctness gracefully degrades.
+ */
+export type MemoryBudgetMode = 'hard' | 'soft' | 'cheapest-fallback';
+/**
+ * Configuration object for {@link selectBackend}. Bundles the routing
+ * table, cost data, and budget policy into a single value the function
+ * can reason about deterministically.
+ */
+export interface MemoryRouterConfig {
+    readonly table: RoutingTable;
+    readonly budgetPerQuery: number | null;
+    readonly budgetMode: MemoryBudgetMode;
+    readonly backendCosts: Readonly<Record<MemoryBackendId, MemoryBackendCostPoint>>;
+}
+/**
+ * Output of {@link selectBackend}. The chosen backend plus full telemetry
+ * about how the routing decision was made.
+ */
+export interface MemoryRoutingDecision {
+    readonly predictedCategory: MemoryQueryCategory;
+    /**
+     * Optional ground-truth category, for telemetry only. When the caller
+     * has access to gold labels (e.g. during benchmarking), passing them
+     * through here lets downstream analysis distinguish classifier
+     * misroutes from architectural misses without needing a second pass.
+     */
+    readonly groundTruthCategory: MemoryQueryCategory | null;
+    readonly chosenBackend: MemoryBackendId;
+    readonly chosenBackendReason: string;
+    readonly estimatedCostUsd: number;
+    readonly budgetCeiling: number | null;
+    readonly budgetExceeded: boolean;
+    readonly preset: MemoryRouterPreset;
+}
+/**
+ * Thrown when the predicted category is not in the routing table. Should
+ * never fire with the three shipping presets (each covers all six
+ * categories) but guards custom-table misuse.
+ */
+export declare class MemoryRouterUnknownCategoryError extends Error {
+    readonly category: string;
+    constructor(category: string);
+}
+/**
+ * Thrown by `hard` budget mode when the routing-table pick exceeds the
+ * per-query USD ceiling. Carries the picked backend + cost + budget so
+ * application-layer fallbacks can decide what to do (fall back to a
+ * different memory architecture, return a typed 402 to the user, etc).
+ */
+export declare class MemoryRouterBudgetExceededError extends Error {
+    readonly backend: MemoryBackendId;
+    readonly cost: number;
+    readonly budget: number;
+    constructor(backend: MemoryBackendId, cost: number, budget: number);
+}
+/**
+ * Pure routing decision: maps a predicted category to a backend choice
+ * given a routing table + budget policy + cost-points data.
+ *
+ * Algorithm:
+ *   1. Look up the table's preferred backend for the predicted category.
+ *      Throw if missing (custom-table misuse).
+ *   2. If no budget is set, return the table's pick.
+ *   3. If the pick fits the budget, return it.
+ *   4. If the pick exceeds:
+ *      - `hard`: throw {@link MemoryRouterBudgetExceededError}.
+ *      - `cheapest-fallback`: pick the cheapest backend that fits;
+ *        if none fits, pick the absolute cheapest and flag exceeded.
+ *      - `soft`: keep the pick if its $/correct beats the cheapest fits;
+ *        otherwise downgrade to the cheapest fits. Globally-no-fit case
+ *        falls through to absolute-cheapest with budgetExceeded=true.
+ *
+ * @param args
+ * @param args.predictedCategory - Category predicted by the LLM-as-judge classifier.
+ * @param args.groundTruthCategory - Gold-label category for telemetry, or null in production.
+ * @param args.config - Routing table + budget policy + cost-points map.
+ *
+ * @returns A {@link MemoryRoutingDecision} describing the chosen backend.
+ *
+ * @throws {@link MemoryRouterUnknownCategoryError} when the table does not
+ *   cover `predictedCategory`.
+ * @throws {@link MemoryRouterBudgetExceededError} when `budgetMode === 'hard'`
+ *   and the routing-table pick exceeds the budget.
+ *
+ * @example
+ * ```ts
+ * const decision = selectBackend({
+ *   predictedCategory: 'multi-session',
+ *   groundTruthCategory: null,
+ *   config: {
+ *     table: MINIMIZE_COST_TABLE,
+ *     budgetPerQuery: 0.05,
+ *     budgetMode: 'cheapest-fallback',
+ *     backendCosts: DEFAULT_MEMORY_BACKEND_COSTS,
+ *   },
+ * });
+ * console.log(decision.chosenBackend); // 'observational-memory-v11' (fits)
+ * ```
+ */
+export declare function selectBackend(args: {
+    predictedCategory: MemoryQueryCategory;
+    groundTruthCategory: MemoryQueryCategory | null;
+    config: MemoryRouterConfig;
+}): MemoryRoutingDecision;
+//# sourceMappingURL=select-backend.d.ts.map

package/dist/memory-router/select-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-backend.d.ts","sourceRoot":"","sources":["../../src/memory-router/select-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACb,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAClF;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,iBAAiB,EAAE,mBAAmB,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED;;;;GAIG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;aAC7B,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAI7C;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;aAEtC,OAAO,EAAE,eAAe;aACxB,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAFd,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAQjC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,mBAAmB,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAChD,MAAM,EAAE,kBAAkB,CAAC;CAC5B,GAAG,qBAAqB,CA6IxB"}

package/dist/memory-router/select-backend.js

@@ -0,0 +1,210 @@
+/**
+ * @file select-backend.ts
+ * @description Pure function that turns a classifier-predicted category
+ * + a {@link MemoryRouterConfig} into a {@link MemoryRoutingDecision}.
+ *
+ * Stateless. Deterministic. No I/O. Suitable for use inside hot dispatch
+ * loops and inside cache-key construction (the function's output is a
+ * pure function of its inputs).
+ *
+ * The decision carries:
+ *   - the chosen {@link MemoryBackendId},
+ *   - the predicted category (and optional ground-truth for telemetry),
+ *   - the estimated USD cost of the routing pick,
+ *   - the budget ceiling (if any) and whether the pick exceeded it,
+ *   - a human-readable reason explaining the routing path taken.
+ *
+ * @module @framers/agentos/memory-router/select-backend
+ */
+/**
+ * Thrown when the predicted category is not in the routing table. Should
+ * never fire with the three shipping presets (each covers all six
+ * categories) but guards custom-table misuse.
+ */
+export class MemoryRouterUnknownCategoryError extends Error {
+    constructor(category) {
+        super(`MemoryRouter: category '${category}' not in routing table`);
+        this.category = category;
+        this.name = 'MemoryRouterUnknownCategoryError';
+    }
+}
+/**
+ * Thrown by `hard` budget mode when the routing-table pick exceeds the
+ * per-query USD ceiling. Carries the picked backend + cost + budget so
+ * application-layer fallbacks can decide what to do (fall back to a
+ * different memory architecture, return a typed 402 to the user, etc).
+ */
+export class MemoryRouterBudgetExceededError extends Error {
+    constructor(backend, cost, budget) {
+        super(`MemoryRouter: backend '${backend}' cost $${cost.toFixed(4)} ` +
+            `exceeds hard budget $${budget.toFixed(4)}`);
+        this.backend = backend;
+        this.cost = cost;
+        this.budget = budget;
+        this.name = 'MemoryRouterBudgetExceededError';
+    }
+}
+/**
+ * Pure routing decision: maps a predicted category to a backend choice
+ * given a routing table + budget policy + cost-points data.
+ *
+ * Algorithm:
+ *   1. Look up the table's preferred backend for the predicted category.
+ *      Throw if missing (custom-table misuse).
+ *   2. If no budget is set, return the table's pick.
+ *   3. If the pick fits the budget, return it.
+ *   4. If the pick exceeds:
+ *      - `hard`: throw {@link MemoryRouterBudgetExceededError}.
+ *      - `cheapest-fallback`: pick the cheapest backend that fits;
+ *        if none fits, pick the absolute cheapest and flag exceeded.
+ *      - `soft`: keep the pick if its $/correct beats the cheapest fits;
+ *        otherwise downgrade to the cheapest fits. Globally-no-fit case
+ *        falls through to absolute-cheapest with budgetExceeded=true.
+ *
+ * @param args
+ * @param args.predictedCategory - Category predicted by the LLM-as-judge classifier.
+ * @param args.groundTruthCategory - Gold-label category for telemetry, or null in production.
+ * @param args.config - Routing table + budget policy + cost-points map.
+ *
+ * @returns A {@link MemoryRoutingDecision} describing the chosen backend.
+ *
+ * @throws {@link MemoryRouterUnknownCategoryError} when the table does not
+ *   cover `predictedCategory`.
+ * @throws {@link MemoryRouterBudgetExceededError} when `budgetMode === 'hard'`
+ *   and the routing-table pick exceeds the budget.
+ *
+ * @example
+ * ```ts
+ * const decision = selectBackend({
+ *   predictedCategory: 'multi-session',
+ *   groundTruthCategory: null,
+ *   config: {
+ *     table: MINIMIZE_COST_TABLE,
+ *     budgetPerQuery: 0.05,
+ *     budgetMode: 'cheapest-fallback',
+ *     backendCosts: DEFAULT_MEMORY_BACKEND_COSTS,
+ *   },
+ * });
+ * console.log(decision.chosenBackend); // 'observational-memory-v11' (fits)
+ * ```
+ */
+export function selectBackend(args) {
+    const { predictedCategory, groundTruthCategory, config } = args;
+    const { table, budgetPerQuery, budgetMode, backendCosts } = config;
+    // 1. Validate: category must be in routing table.
+    const picked = table.defaultMapping[predictedCategory];
+    if (!picked) {
+        throw new MemoryRouterUnknownCategoryError(predictedCategory);
+    }
+    // 2. Compute per-query cost for the picked backend on this category.
+    const pickedCost = backendCosts[picked].perCategoryCostPerQuery[predictedCategory];
+    // 3. Budget pass-through: no budget OR pick fits.
+    if (budgetPerQuery === null || pickedCost <= budgetPerQuery) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: picked,
+            chosenBackendReason: budgetPerQuery === null
+                ? 'routing-table pick, no budget'
+                : 'routing-table pick fits budget',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // 4. Budget exceeded. Hard mode bails immediately.
+    if (budgetMode === 'hard') {
+        throw new MemoryRouterBudgetExceededError(picked, pickedCost, budgetPerQuery);
+    }
+    // Find the cheapest backend that fits the budget on this category.
+    const candidates = Object.values(backendCosts).map((c) => ({
+        backend: c.backend,
+        cost: c.perCategoryCostPerQuery[predictedCategory],
+    }));
+    const fits = candidates.filter((c) => c.cost <= budgetPerQuery);
+    const cheapestFits = fits.length > 0
+        ? fits.reduce((a, b) => (a.cost <= b.cost ? a : b))
+        : null;
+    // No backend fits at all -> globally cheapest with budgetExceeded=true.
+    if (!cheapestFits) {
+        const globallyCheapest = candidates.reduce((a, b) => a.cost <= b.cost ? a : b);
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: globallyCheapest.backend,
+            chosenBackendReason: 'no backend fits budget; picking absolute cheapest',
+            estimatedCostUsd: globallyCheapest.cost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    // cheapest-fallback: silently downgrade.
+    if (budgetMode === 'cheapest-fallback') {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: cheapestFits.backend,
+            chosenBackendReason: 'budget downgrade (cheapest-fallback mode)',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // soft: keep the pick only if it's better $/correct than cheapest-fits.
+    const pickedAcc = backendCosts[picked].perCategoryAccuracy[predictedCategory];
+    const cheapestAcc = backendCosts[cheapestFits.backend].perCategoryAccuracy[predictedCategory];
+    // Edge case: picked has zero accuracy -> always downgrade.
+    if (pickedAcc === 0) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: cheapestFits.backend,
+            chosenBackendReason: 'soft budget downgrade: picked has 0 acc on category',
+            estimatedCostUsd: cheapestFits.cost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: false,
+            preset: table.preset,
+        };
+    }
+    // Edge case: cheapest has zero accuracy -> stay with picked even though exceeded.
+    if (cheapestAcc === 0) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: picked,
+            chosenBackendReason: 'soft exceed: cheapest has 0 acc',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    const pickedCPC = pickedCost / pickedAcc;
+    const cheapestCPC = cheapestFits.cost / cheapestAcc;
+    if (pickedCPC <= cheapestCPC) {
+        return {
+            predictedCategory,
+            groundTruthCategory,
+            chosenBackend: picked,
+            chosenBackendReason: 'soft exceed: better $/correct',
+            estimatedCostUsd: pickedCost,
+            budgetCeiling: budgetPerQuery,
+            budgetExceeded: true,
+            preset: table.preset,
+        };
+    }
+    return {
+        predictedCategory,
+        groundTruthCategory,
+        chosenBackend: cheapestFits.backend,
+        chosenBackendReason: 'soft budget downgrade: cheaper $/correct',
+        estimatedCostUsd: cheapestFits.cost,
+        budgetCeiling: budgetPerQuery,
+        budgetExceeded: false,
+        preset: table.preset,
+    };
+}
+//# sourceMappingURL=select-backend.js.map

package/dist/memory-router/select-backend.js.map

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