feat: ship multi-stage guardrails — ingest-router + read-router + adaptive memory-router + composition

Ships three new agentos primitives + a self-calibrating extension to
memory-router. Together with the existing memory-router and query-router,
they form the agentos multi-stage guardrails pattern: every pipeline
boundary has an LLM-as-judge orchestrator that classifies its input and
picks a strategy.

@framers/agentos/ingest-router (NEW):
- Input-stage orchestrator. Classifies content (short/long-conversation,
  long-article, code, structured-data, multimodal) and picks a storage
  strategy (raw-chunks, summarized, observational, fact-graph, hybrid,
  skip).
- Four shipping presets: raw-chunks (default), summarized, observational,
  hybrid.
- Provider-agnostic LLMIngestClassifier with base + few-shot prompts.
- FunctionIngestDispatcher with registry-of-executors pattern.
- Budget-aware dispatch with three modes (hard / soft / cheapest-fallback).
- 38 contract tests across routing tables, pure selectIngestStrategy,
  classifier parsing, dispatcher routing, top-level decide+decideAndDispatch.

@framers/agentos/read-router (NEW):
- Read-stage orchestrator. Classifies query+evidence into one of five
  intents (precise-fact, multi-source-synthesis, time-interval,
  preference-recommendation, abstention-candidate) and picks a reader
  strategy (single-call, two-call-extract-answer, commit-vs-abstain,
  verbatim-citation, scratchpad-then-answer).
- Three shipping presets: precise-fact (default), synthesis, temporal.
- Provider-agnostic LLMReadIntentClassifier.
- FunctionReadDispatcher.
- Budget-aware dispatch.
- 26 contract tests.

@framers/agentos/memory-router/adaptive (NEW, extends existing):
- AdaptiveMemoryRouter: self-calibrating router that derives routing
  tables from a workload-specific calibration dataset. Consumers run
  Phase A on their workload and get a tailored router instead of using
  LongMemEval-S Phase B presets.
- aggregateCalibration: rolls (category, backend) samples into mean
  cost + mean accuracy + n cells.
- selectByPreset: picks a backend per category given aggregated
  calibration + a preset rule (minimize-cost / balanced / maximize-
  accuracy).
- buildAdaptiveRoutingTable: builds a complete frozen RoutingTable
  with calibrated picks where data is available; preset fallback
  elsewhere.
- 13 contract tests.

@framers/agentos/multi-stage-guardrails (NEW):
- MultiStageGuardrails class composes IngestStage + RecallStage +
  ReadStage into one pipeline.
- IngestStage / RecallStage / ReadStage are minimal pluggable
  interfaces — agentos routers satisfy them via thin adapters
  (ingestRouterAsStage / memoryRouterAsStage / readRouterAsStage),
  custom implementations slot in too.
- ingest / recall / read methods for independent stages;
  recallAndRead for end-to-end.
- 10 contract tests.

Total: 87 new tests (163 total across all four memory-router family
modules). All four modules build clean and load at runtime via their
respective package.json subpaths (./ingest-router, ./read-router,
./memory-router, ./multi-stage-guardrails).

Each module ships a README documenting public types, usage patterns
(decide-only, decide+dispatch, manual override, budget-aware, custom
implementations), and the relationship to sibling primitives.

Same single-OpenAI-key reproducibility as memory-router: classifiers
talk to provider-agnostic LLM adapter interfaces; no SDK imports
inside any module.

Author: jddunn

package.json

@@ -263,6 +263,21 @@
       "default": "./dist/memory-router/index.js",
       "types": "./dist/memory-router/index.d.ts"
     },
+    "./ingest-router": {
+      "import": "./dist/ingest-router/index.js",
+      "default": "./dist/ingest-router/index.js",
+      "types": "./dist/ingest-router/index.d.ts"
+    },
+    "./read-router": {
+      "import": "./dist/read-router/index.js",
+      "default": "./dist/read-router/index.js",
+      "types": "./dist/read-router/index.d.ts"
+    },
+    "./multi-stage-guardrails": {
+      "import": "./dist/multi-stage-guardrails/index.js",
+      "default": "./dist/multi-stage-guardrails/index.js",
+      "types": "./dist/multi-stage-guardrails/index.d.ts"
+    },
     "./memory/index": {
       "import": "./dist/memory/index.js",
       "default": "./dist/memory/index.js",

src/ingest-router/IngestRouter.ts

@@ -0,0 +1,191 @@
+/**
+ * @file IngestRouter.ts
+ * @description Top-level input-stage orchestrator that composes the
+ * ingest classifier and the pure {@link selectIngestStrategy} into a
+ * single per-content routing call.
+ *
+ * Same shape as MemoryRouter (recall-stage) so the multi-stage guardrails
+ * orchestrator can compose them uniformly. Decide-only and decide+dispatch
+ * flows are both supported.
+ *
+ * @module @framers/agentos/ingest-router/IngestRouter
+ */
+
+import type {
+  IIngestClassifier,
+  IngestClassifierResult,
+} from './classifier.js';
+import {
+  DEFAULT_INGEST_COSTS,
+  type IngestStrategyCostPoint,
+} from './costs.js';
+import {
+  PRESET_INGEST_TABLES,
+  type IngestContentKind,
+  type IngestRouterPreset,
+  type IngestRoutingTable,
+  type IngestStrategyId,
+} from './routing-tables.js';
+import {
+  selectIngestStrategy,
+  type IngestBudgetMode,
+  type IngestRoutingDecision,
+} from './select-strategy.js';
+import type {
+  IIngestDispatcher,
+  IngestDispatchResult,
+} from './dispatcher.js';
+
+export interface IngestBudgetPolicy {
+  readonly perIngestUsd?: number;
+  readonly mode?: IngestBudgetMode;
+}
+
+export interface IngestRouterOptions {
+  readonly classifier: IIngestClassifier;
+  readonly preset?: IngestRouterPreset;
+  readonly routingTable?: IngestRoutingTable;
+  readonly mapping?: Partial<Record<IngestContentKind, IngestStrategyId>>;
+  readonly budget?: IngestBudgetPolicy;
+  readonly strategyCosts?: Readonly<
+    Record<IngestStrategyId, IngestStrategyCostPoint>
+  >;
+  readonly useFewShotPrompt?: boolean;
+  readonly dispatcher?: IIngestDispatcher<unknown, unknown>;
+}
+
+export interface IngestRouterDecideOptions {
+  /**
+   * Optional manual override of the classifier. When set, the classifier
+   * is NOT invoked and the routing table is consulted with this kind
+   * directly. Useful when the caller already knows the content kind
+   * (e.g., file extension determines code vs structured-data).
+   */
+  readonly manualKind?: IngestContentKind;
+  readonly groundTruthKind?: IngestContentKind | null;
+  readonly useFewShotPrompt?: boolean;
+}
+
+export interface IngestRouterDecision {
+  readonly classifier: IngestClassifierResult;
+  readonly routing: IngestRoutingDecision;
+}
+
+export interface IngestRouterDispatchedResult<TOutcome> {
+  readonly decision: IngestRouterDecision;
+  readonly outcome: TOutcome;
+  readonly strategy: IngestStrategyId;
+}
+
+export class IngestRouterDispatcherMissingError extends Error {
+  constructor() {
+    super(
+      'IngestRouter.decideAndDispatch requires a dispatcher. ' +
+        'Either pass a dispatcher in options or call `decide` and dispatch yourself.',
+    );
+    this.name = 'IngestRouterDispatcherMissingError';
+  }
+}
+
+/**
+ * Public input-stage orchestrator. One instance per ingest endpoint;
+ * reuse across content events.
+ */
+export class IngestRouter {
+  private readonly classifier: IIngestClassifier;
+  private readonly preset: IngestRouterPreset;
+  private readonly routingTable: IngestRoutingTable;
+  private readonly budgetPerIngestUsd: number | null;
+  private readonly budgetMode: IngestBudgetMode;
+  private readonly strategyCosts: Readonly<
+    Record<IngestStrategyId, IngestStrategyCostPoint>
+  >;
+  private readonly defaultUseFewShotPrompt: boolean;
+  private readonly dispatcher: IIngestDispatcher<unknown, unknown> | null;
+
+  constructor(options: IngestRouterOptions) {
+    this.classifier = options.classifier;
+    this.preset = options.preset ?? 'raw-chunks';
+    this.dispatcher = options.dispatcher ?? null;
+
+    const baseTable = options.routingTable ?? PRESET_INGEST_TABLES[this.preset];
+    if (options.mapping) {
+      const patched: Record<IngestContentKind, IngestStrategyId> = {
+        ...baseTable.defaultMapping,
+      };
+      for (const key of Object.keys(options.mapping) as IngestContentKind[]) {
+        const ov = options.mapping[key];
+        if (ov) patched[key] = ov;
+      }
+      this.routingTable = Object.freeze({
+        preset: baseTable.preset,
+        defaultMapping: Object.freeze(patched),
+      });
+    } else {
+      this.routingTable = baseTable;
+    }
+
+    this.budgetPerIngestUsd = options.budget?.perIngestUsd ?? null;
+    this.budgetMode = options.budget?.mode ?? 'cheapest-fallback';
+    this.strategyCosts = options.strategyCosts ?? DEFAULT_INGEST_COSTS;
+    this.defaultUseFewShotPrompt = options.useFewShotPrompt ?? false;
+  }
+
+  async decide(
+    content: string,
+    options?: IngestRouterDecideOptions,
+  ): Promise<IngestRouterDecision> {
+    let classifier: IngestClassifierResult;
+    if (options?.manualKind) {
+      classifier = {
+        kind: options.manualKind,
+        tokensIn: 0,
+        tokensOut: 0,
+        model: 'manual',
+      };
+    } else {
+      const useFewShot =
+        options?.useFewShotPrompt ?? this.defaultUseFewShotPrompt;
+      classifier = await this.classifier.classify(
+        content,
+        useFewShot ? { useFewShotPrompt: true } : undefined,
+      );
+    }
+
+    const routing = selectIngestStrategy({
+      predictedKind: classifier.kind,
+      groundTruthKind: options?.groundTruthKind ?? null,
+      config: {
+        table: this.routingTable,
+        budgetPerIngestUsd: this.budgetPerIngestUsd,
+        budgetMode: this.budgetMode,
+        strategyCosts: this.strategyCosts,
+      },
+    });
+
+    return { classifier, routing };
+  }
+
+  async decideAndDispatch<TOutcome, TPayload = undefined>(
+    content: string,
+    dispatchPayload?: TPayload,
+    options?: IngestRouterDecideOptions,
+  ): Promise<IngestRouterDispatchedResult<TOutcome>> {
+    if (!this.dispatcher) {
+      throw new IngestRouterDispatcherMissingError();
+    }
+
+    const decision = await this.decide(content, options);
+    const dispatched = (await this.dispatcher.dispatch({
+      strategy: decision.routing.chosenStrategy,
+      content,
+      payload: dispatchPayload as unknown,
+    })) as IngestDispatchResult<TOutcome>;
+
+    return {
+      decision,
+      outcome: dispatched.outcome,
+      strategy: dispatched.strategy,
+    };
+  }
+}

src/ingest-router/README.md

@@ -0,0 +1,129 @@
+# @framers/agentos/ingest-router
+
+Input-stage LLM-as-judge orchestrator. Classifies incoming content and picks an ingest strategy: `raw-chunks`, `summarized`, `observational`, `fact-graph`, `hybrid`, or `skip`. Sibling of `@framers/agentos/memory-router` (recall-stage) and `@framers/agentos/read-router` (read-stage).
+
+## Why route at ingest
+
+Different content benefits from different storage. A 3-turn chat snippet doesn't justify the LLM cost of observation extraction; a 50-turn customer-support thread does. A long-form article benefits from session-summarized contextual retrieval; structured CSV data doesn't. The router takes the content (plus an optional manual override), classifies it, and picks the storage strategy that the downstream MemoryRouter can recall against effectively.
+
+## Six content kinds
+
+| Kind | Examples |
+|---|---|
+| `short-conversation` | 1-3 turn chats, brief Q&A |
+| `long-conversation` | extended chat sessions, support threads |
+| `long-article` | blog posts, paper sections, long emails |
+| `code` | source files, configs, schemas |
+| `structured-data` | CSV, JSON record lists, table dumps |
+| `multimodal` | content with images, video frames, audio |
+
+## Six ingest strategies
+
+| Strategy | What it writes | Cost |
+|---|---|---|
+| `raw-chunks` | turn/chunk traces with embeddings | $0.0001/ingest |
+| `summarized` | session/document summary prefixed to every chunk | $0.005/ingest |
+| `observational` | structured observation log replacing raw turns | $0.020/ingest |
+| `fact-graph` | extracted fact triples + entity-relation graph | $0.015/ingest |
+| `hybrid` | parallel raw + summarized + observational | $0.030/ingest |
+| `skip` | content discarded; nothing written | $0 |
+
+## Four shipping presets
+
+| Preset | Strategy | When to use |
+|---|---|---|
+| `raw-chunks` (default) | every kind → raw-chunks | high-volume / cost-sensitive workloads where retrieval does the work |
+| `summarized` | long-* and code → summarized; short stays raw | documents/conversations with global context that aids recall |
+| `observational` | long-conversation → observational; long-article → summarized | conversational workloads with multi-session synthesis questions |
+| `hybrid` | long-* → hybrid; short stays raw | cost-tolerant workloads with heterogeneous retrieval needs |
+
+## Installation
+
+Already part of `@framers/agentos`. Import from the subpath:
+
+```ts
+import {
+  LLMIngestClassifier,
+  IngestRouter,
+  FunctionIngestDispatcher,
+} from '@framers/agentos/ingest-router';
+```
+
+## Usage
+
+### Decide-only
+
+```ts
+const router = new IngestRouter({
+  classifier: new LLMIngestClassifier({ llm: openaiAdapter }),
+  preset: 'summarized',
+});
+
+const { classifier, routing } = await router.decide(content);
+console.log(classifier.kind);            // 'long-conversation'
+console.log(routing.chosenStrategy);     // 'observational'
+console.log(routing.estimatedCostUsd);   // 0.020
+```
+
+### Decide + dispatch
+
+```ts
+type Outcome = { writtenTraces: number };
+
+const router = new IngestRouter({
+  classifier: new LLMIngestClassifier({ llm: openaiAdapter }),
+  preset: 'observational',
+  dispatcher: new FunctionIngestDispatcher<Outcome>({
+    'raw-chunks': async (content) => ({ writtenTraces: await rawIngest(content) }),
+    summarized: async (content) => ({ writtenTraces: await summarizedIngest(content) }),
+    observational: async (content) => ({ writtenTraces: await omIngest(content) }),
+  }),
+});
+
+const { decision, outcome } = await router.decideAndDispatch(content);
+```
+
+### Manual kind override
+
+When the caller already knows the content kind (e.g., file extension determines code), skip the LLM classifier:
+
+```ts
+const decision = await router.decide(content, {
+  manualKind: 'code',
+});
+// classifier is not invoked; routing table consulted with 'code' directly.
+```
+
+### Budget-aware
+
+```ts
+const router = new IngestRouter({
+  classifier,
+  preset: 'observational',
+  budget: {
+    perIngestUsd: 0.005,           // tight per-ingest ceiling
+    mode: 'cheapest-fallback',     // silently downgrade to a fitting strategy
+  },
+});
+```
+
+## API surface
+
+- `IngestContentKind`, `IngestStrategyId`, `IngestRouterPreset`, `IngestRoutingTable`
+- `INGEST_CONTENT_KINDS` — the six-kind tuple
+- `RAW_CHUNKS_TABLE`, `SUMMARIZED_TABLE`, `OBSERVATIONAL_TABLE`, `HYBRID_TABLE`, `PRESET_INGEST_TABLES`
+- `IngestStrategyCostPoint`, `DEFAULT_INGEST_COSTS`
+- `selectIngestStrategy` (pure function)
+- `IngestRoutingDecision`, `IngestRouterConfig`, `IngestBudgetMode`
+- `IIngestClassifier`, `IIngestClassifierLLM`, `LLMIngestClassifier`
+- `INGEST_CLASSIFIER_SYSTEM_PROMPT`, `INGEST_CLASSIFIER_SYSTEM_PROMPT_FEWSHOT`
+- `IIngestDispatcher`, `FunctionIngestDispatcher`
+- `IngestRouter`, `IngestRouterOptions`, `IngestRouterDecideOptions`, `IngestRouterDispatchedResult`
+- Errors: `IngestRouterUnknownKindError`, `IngestRouterBudgetExceededError`, `UnsupportedIngestStrategyError`, `IngestRouterDispatcherMissingError`
+
+## Related
+
+- `@framers/agentos/memory-router` — recall-stage sibling
+- `@framers/agentos/read-router` — read-stage sibling
+- `@framers/agentos/multi-stage-guardrails` — composition primitive that wires the three stages together
+- `@framers/agentos/core/guardrails` + `agentos-ext-grounding-guard` — output-stage validation