@tangle-network/agent-eval 0.44.1 → 0.46.0

package/dist/contract/index.d.ts

@@ -1,5 +1,7 @@
-export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCellResult, c as CampaignCostMeter, d as CampaignResult, e as CampaignTraceWriter, f as CodeSurface, D as Dispatch, g as DispatchContext, G as Gate, h as GateContext, i as GateDecision, j as GateResult, k as GenerationCandidate, l as GenerationRecord, I as ImprovementDriver, J as JudgeConfig, m as JudgeDimension, n as JudgeScore, M as MutableSurface, o as Mutator, O as OptimizerConfig, S as Scenario, p as SessionScript } from '../types-DToGONFA.js';
-export { C as CampaignStorage, D as DefaultProductionGateOptions, E as EvolutionaryDriverOptions, G as GepaDriverOptions, H as HeldOutGateOptions, R as RunCampaignOptions, a as RunEvalOptions, b as RunImprovementLoopOptions, c as RunImprovementLoopResult, d as composeGate, e as defaultProductionGate, f as evolutionaryDriver, g as fsCampaignStorage, h as gepaDriver, i as heldOutGate, j as inMemoryCampaignStorage, r as runCampaign, k as runEval, l as runImprovementLoop } from '../run-improvement-loop-CbilHQAb.js';
+import { S as Scenario, M as MutableSurface, D as DispatchContext, J as JudgeConfig, I as ImprovementDriver, G as Gate } from '../types-8u72Gc76.js';
+export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCellResult, c as CampaignCostMeter, d as CampaignResult, e as CampaignTraceWriter, f as CodeSurface, g as Dispatch, h as GateContext, i as GateDecision, j as GateResult, k as GenerationCandidate, l as GenerationRecord, m as JudgeDimension, n as JudgeScore, o as Mutator, O as OptimizerConfig, p as SessionScript } from '../types-8u72Gc76.js';
+import { C as CampaignStorage, R as RunImprovementLoopResult } from '../run-improvement-loop-Bfam3MT1.js';
+export { D as DefaultProductionGateOptions, E as EvolutionaryDriverOptions, G as GepaDriverOptions, H as HeldOutGateOptions, a as RunCampaignOptions, b as RunEvalOptions, c as RunImprovementLoopOptions, d as composeGate, e as defaultProductionGate, f as evolutionaryDriver, g as fsCampaignStorage, h as gepaDriver, i as heldOutGate, j as inMemoryCampaignStorage, r as runCampaign, k as runEval, l as runImprovementLoop } from '../run-improvement-loop-Bfam3MT1.js';
 export { D as DeploymentOutcome, F as FileSystemOutcomeStore, a as FileSystemOutcomeStoreOptions, I as InMemoryOutcomeStore, O as OutcomeStore } from '../outcome-store-BxJ3DQKJ.js';
 import '../llm-client-BXVRUZyX.js';
 import '../errors-mje_cKOs.js';
@@ -8,3 +10,198 @@ import '@tangle-network/agent-runtime';
 import '../red-team-30II1T4o.js';
 import '../dataset-BlwAtYYf.js';
 import '../store-Db2Bv8Cf.js';
+
+/**
+ * # `selfImprove()` — the LAND-tier one-shot.
+ *
+ * The cheapest possible call site to run a real closed-loop self-
+ * improvement over your agent. Wraps `runImprovementLoop` with smart
+ * defaults and a budget-shaped options API; every escape hatch the
+ * substrate exposes is reachable from here without losing the
+ * one-function feel.
+ *
+ * Defaults picked to match the LAND-tier story:
+ *   - In-memory storage (no filesystem touch).
+ *   - `gepaDriver` reflective mutation with copywriting-flavored primitives
+ *     (override `driver` or `mutationPrimitives` for any domain).
+ *   - `defaultProductionGate` with `deltaThreshold: 0.05`.
+ *   - Held-out split = 25% of scenarios, deterministic by id hash.
+ *   - 3 generations × population 2 (raise via `budget` for more search).
+ *   - `autoOnPromote: 'none'` (we don't open PRs unless you ask).
+ *
+ * Want one-click? Provide `agent` + `scenarios` + `judge`. Done.
+ * Want distributed? Pass `cellPlacement` + an `httpDispatch`-backed
+ * agent. Want a code-tier surface? Pass a `MutableSurface` + your own
+ * `driver`. Same function.
+ */
+
+interface SelfImproveBudget {
+    /** Hard $ ceiling across all cells in baseline + every generation. Cells
+     *  beyond the ceiling are skipped (cost-aware, not aborted). */
+    dollars?: number;
+    /** How many improvement generations to explore. Default 3. Set 0 to
+     *  skip improvement entirely (selfImprove becomes a baseline-only run). */
+    generations?: number;
+    /** Candidates the driver proposes per generation. Default 2. */
+    populationSize?: number;
+    /** Max concurrent cells across the loop. Default 2. */
+    maxConcurrency?: number;
+    /** Fraction of `scenarios` held out from training, used for the gate.
+     *  Default 0.25. Ignored when `holdoutScenarios` is set explicitly. */
+    holdoutFraction?: number;
+    /** Explicit held-out scenarios; overrides `holdoutFraction`. */
+    holdoutScenarios?: Scenario[];
+}
+interface SelfImproveLlm {
+    /** Endpoint base URL. Default Tangle Router. */
+    baseUrl?: string;
+    /** Bearer token. Default `process.env.OPENAI_API_KEY`. */
+    apiKey?: string;
+    /** Model id used by `gepaDriver` reflection. Default
+     *  `anthropic/claude-sonnet-4.6`. */
+    model?: string;
+}
+type SelfImproveProgressEvent = {
+    kind: 'baseline.started';
+    scenarios: number;
+} | {
+    kind: 'baseline.completed';
+    compositeMean: number;
+    durationMs: number;
+} | {
+    kind: 'generation.started';
+    index: number;
+    populationSize: number;
+} | {
+    kind: 'generation.completed';
+    index: number;
+    bestComposite: number;
+    durationMs: number;
+} | {
+    kind: 'gate.decided';
+    decision: string;
+    lift: number;
+};
+interface SelfImproveOptions<TScenario extends Scenario, TArtifact> {
+    /**
+     * Your agent — a function that takes the current `MutableSurface`
+     * (typically a system prompt the loop is optimizing) plus the
+     * scenario + cell ctx, and returns the artifact your judge scores.
+     *
+     * Same shape as `RunOptimizationOptions.dispatchWithSurface`. Wrap a
+     * plain `Dispatch` if you don't have a surface seam:
+     *
+     *   agent: (_surface, scenario, ctx) => yourPlainDispatch(scenario, ctx)
+     *
+     * That mode evaluates without mutating any surface — useful as a
+     * baseline-only run (set `budget.generations = 0`).
+     */
+    agent: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+    /** Scenarios to evaluate against. Train/holdout split is computed from
+     *  these unless `budget.holdoutScenarios` is set explicitly. */
+    scenarios: TScenario[];
+    /** Judge that scores artifacts. Bring your own; use `langchainJudge`
+     *  from `/adapters/langchain` for a Runnable-shaped one. */
+    judge: JudgeConfig<TArtifact, TScenario>;
+    /** Starting surface — system prompt, JSON config, anything `MutableSurface`
+     *  accepts. The driver mutates this each generation. */
+    baselineSurface: MutableSurface;
+    /** Budget + loop shape. All fields optional; defaults pick the LAND-tier
+     *  story. */
+    budget?: SelfImproveBudget;
+    /** Custom driver. Default is `gepaDriver` configured from `llm` +
+     *  `mutationPrimitives`. */
+    driver?: ImprovementDriver;
+    /** Default-driver overrides — used when `driver` is unset. */
+    mutationPrimitives?: string[];
+    driverTarget?: string;
+    /** Custom gate. Default is `defaultProductionGate` with
+     *  `deltaThreshold: 0.05` on the held-out split. */
+    gate?: Gate<TArtifact, TScenario>;
+    /** LLM config consumed by the default `gepaDriver`. Ignored if you pass
+     *  your own `driver`. */
+    llm?: SelfImproveLlm;
+    /** Storage backend. Default `inMemoryCampaignStorage()` — nothing
+     *  persists past the call. Pass `fsCampaignStorage()` to write to disk. */
+    storage?: CampaignStorage;
+    /** Run directory (logical for in-memory storage, real path for fs).
+     *  Default `mem://selfImprove-<timestamp>`. */
+    runDir?: string;
+    /** Distributed-driver seam — same as `RunCampaignOptions.cellPlacement`.
+     *  Returns an opaque placement key the substrate forwards to your agent
+     *  as `ctx.placement`. Combined with `httpDispatch` from
+     *  `/adapters/http`, fans cells across regions. */
+    cellPlacement?: (input: {
+        scenario: TScenario;
+        rep: number;
+        generation?: number;
+    }) => string | undefined;
+    /** Streaming hook — fires on baseline + each generation + gate decision.
+     *  Consumer routes events wherever (UI, dashboard, logs). */
+    onProgress?: (event: SelfImproveProgressEvent) => void;
+    /** Auto-promotion behavior on a ship decision. Default `'none'` — we
+     *  return the winner; you ship it however you ship. `'pr'` opens a
+     *  GitHub PR via `openAutoPr`; requires `ghOwner` + `ghRepo`. */
+    autoOnPromote?: 'pr' | 'none';
+    ghOwner?: string;
+    ghRepo?: string;
+}
+interface SelfImproveResult<TScenario extends Scenario, TArtifact> {
+    /** Composite mean across all scenarios, baseline run. */
+    baseline: {
+        compositeMean: number;
+        perScenario: Record<string, number>;
+    };
+    /** Composite mean on the held-out set, winner run. */
+    winner: {
+        compositeMean: number;
+        perScenario: Record<string, number>;
+        surface: MutableSurface;
+    };
+    /** `winner.compositeMean - baselineOnHoldout.compositeMean`. Positive
+     *  means the gate observed improvement. */
+    lift: number;
+    /** `defaultProductionGate.decide()` result. */
+    gateDecision: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
+    /** Number of generations actually explored (may be less than the
+     *  budget if the driver gave up early). */
+    generationsExplored: number;
+    /** Wall-clock total. */
+    durationMs: number;
+    /** Total cost across baseline + every generation. */
+    totalCostUsd: number;
+    /**
+     * Raw substrate result for advanced inspection — full per-generation
+     * candidates, full campaign artifacts, all judge scores. Useful for
+     * debugging or reporting beyond the summary.
+     */
+    raw: RunImprovementLoopResult<TArtifact, TScenario>;
+}
+/**
+ * One-shot self-improvement loop. See module docstring for defaults +
+ * extension points.
+ *
+ * @example Minimum (LAND tier):
+ *
+ *   const result = await selfImprove({
+ *     agent: (surface, scenario, ctx) => myAgent(surface, scenario, ctx.signal),
+ *     scenarios,
+ *     judge,
+ *     baselineSurface: DEFAULT_PROMPT,
+ *   })
+ *   console.log(`lift: ${result.lift.toFixed(3)} (${result.gateDecision})`)
+ *
+ * @example Distributed (workers in three regions):
+ *
+ *   await selfImprove({
+ *     agent: httpDispatch({ resolveUrl: ({ placement }) => REGION_URLS[placement!] }),
+ *     scenarios,
+ *     judge,
+ *     baselineSurface: DEFAULT_PROMPT,
+ *     cellPlacement: ({ scenario }) => scenario.region,
+ *     budget: { maxConcurrency: 12 },
+ *   })
+ */
+declare function selfImprove<TScenario extends Scenario, TArtifact>(opts: SelfImproveOptions<TScenario, TArtifact>): Promise<SelfImproveResult<TScenario, TArtifact>>;
+
+export { CampaignStorage, DispatchContext, Gate, ImprovementDriver, JudgeConfig, MutableSurface, RunImprovementLoopResult, Scenario, type SelfImproveBudget, type SelfImproveLlm, type SelfImproveOptions, type SelfImproveProgressEvent, type SelfImproveResult, selfImprove };

package/dist/contract/index.js

@@ -6,12 +6,12 @@ import {
   heldOutGate,
   runEval,
   runImprovementLoop
-} from "../chunk-H5BGRSN4.js";
+} from "../chunk-HRKOCLQA.js";
 import {
   fsCampaignStorage,
   inMemoryCampaignStorage,
   runCampaign
-} from "../chunk-RXK7FXLV.js";
+} from "../chunk-J3EIOI3O.js";
 import "../chunk-N4SBKEPJ.js";
 import "../chunk-YV7J7X5N.js";
 import {
@@ -24,6 +24,130 @@ import "../chunk-VXNVVBZO.js";
 import "../chunk-PC4UYEBM.js";
 import "../chunk-QYJT52YW.js";
 import "../chunk-NSBPE2FW.js";
+
+// src/contract/self-improve.ts
+function splitTrainHoldout(scenarios, fraction) {
+  function hash(s) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < s.length; i++) {
+      h ^= s.charCodeAt(i);
+      h = Math.imul(h, 16777619) >>> 0;
+    }
+    return h;
+  }
+  const sorted = [...scenarios].sort((a, b) => hash(a.id) - hash(b.id));
+  const nHoldout = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)));
+  return {
+    holdout: sorted.slice(0, nHoldout),
+    train: sorted.slice(nHoldout)
+  };
+}
+function meanComposite(byScenario) {
+  const perScenario = {};
+  const values = [];
+  for (const [id, agg] of Object.entries(byScenario)) {
+    perScenario[id] = agg.meanComposite;
+    values.push(agg.meanComposite);
+  }
+  return {
+    compositeMean: values.length === 0 ? 0 : values.reduce((s, v) => s + v, 0) / values.length,
+    perScenario
+  };
+}
+var DEFAULT_MUTATION_PRIMITIVES = [
+  "Tighten the hook: lead with the specific user outcome.",
+  "Replace generic adjectives with specific verbs or proof numbers.",
+  "Anchor every claim in something the scenario's brief literally supports.",
+  "Honor the surface-shape constraint (length, register, audience vocabulary)."
+];
+async function selfImprove(opts) {
+  const startedAt = Date.now();
+  const budget = opts.budget ?? {};
+  const generations = budget.generations ?? 3;
+  const populationSize = budget.populationSize ?? 2;
+  const maxConcurrency = budget.maxConcurrency ?? 2;
+  const holdoutFraction = budget.holdoutFraction ?? 0.25;
+  const costCeiling = budget.dollars;
+  const explicitHoldout = budget.holdoutScenarios;
+  const { train, holdout } = explicitHoldout ? {
+    train: opts.scenarios.filter((s) => !explicitHoldout.some((h) => h.id === s.id)),
+    holdout: explicitHoldout
+  } : splitTrainHoldout(opts.scenarios, holdoutFraction);
+  if (train.length === 0) {
+    throw new Error("selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios.");
+  }
+  if (holdout.length === 0) {
+    throw new Error("selfImprove: holdout split is empty. Pass more scenarios.");
+  }
+  const driver = opts.driver ?? gepaDriver({
+    llm: {
+      baseUrl: opts.llm?.baseUrl ?? "https://router.tangle.tools/v1",
+      apiKey: opts.llm?.apiKey ?? process.env.OPENAI_API_KEY ?? ""
+    },
+    model: opts.llm?.model ?? "anthropic/claude-sonnet-4.6",
+    target: opts.driverTarget ?? "agent surface (system prompt or config) being optimized by selfImprove",
+    mutationPrimitives: opts.mutationPrimitives ?? DEFAULT_MUTATION_PRIMITIVES
+  });
+  const gate = opts.gate ?? defaultProductionGate({
+    holdoutScenarios: holdout,
+    deltaThreshold: 0.05
+  });
+  const storage = opts.storage ?? inMemoryCampaignStorage();
+  const runDir = opts.runDir ?? `mem://selfImprove-${startedAt}`;
+  if (opts.onProgress) {
+    opts.onProgress({ kind: "baseline.started", scenarios: opts.scenarios.length });
+  }
+  const result = await runImprovementLoop({
+    scenarios: train,
+    baselineSurface: opts.baselineSurface,
+    dispatchWithSurface: opts.agent,
+    driver,
+    judges: [opts.judge],
+    populationSize,
+    maxGenerations: generations,
+    holdoutScenarios: holdout,
+    gate,
+    autoOnPromote: opts.autoOnPromote ?? "none",
+    ghOwner: opts.ghOwner,
+    ghRepo: opts.ghRepo,
+    storage,
+    runDir,
+    maxConcurrency,
+    cellPlacement: opts.cellPlacement,
+    costCeiling
+  });
+  const baseline = meanComposite(result.baselineOnHoldout.aggregates.byScenario);
+  const winnerStats = meanComposite(result.winnerOnHoldout.aggregates.byScenario);
+  if (opts.onProgress) {
+    opts.onProgress({
+      kind: "baseline.completed",
+      compositeMean: baseline.compositeMean,
+      durationMs: Date.now() - startedAt
+    });
+    opts.onProgress({
+      kind: "gate.decided",
+      decision: result.gateResult.decision,
+      lift: winnerStats.compositeMean - baseline.compositeMean
+    });
+  }
+  const totalCost = result.baselineCampaign.aggregates.totalCostUsd + result.generations.reduce(
+    (sum, gen) => sum + gen.surfaces.reduce((s, sf) => s + sf.campaign.aggregates.totalCostUsd, 0),
+    0
+  );
+  return {
+    baseline,
+    winner: {
+      ...winnerStats,
+      surface: result.winnerSurface
+    },
+    lift: winnerStats.compositeMean - baseline.compositeMean,
+    gateDecision: result.gateResult.decision,
+    generationsExplored: result.generations.length,
+    durationMs: Date.now() - startedAt,
+    totalCostUsd: totalCost,
+    raw: result
+  };
+}
 export {
   FileSystemOutcomeStore,
   InMemoryOutcomeStore,
@@ -36,6 +160,7 @@ export {
   inMemoryCampaignStorage,
   runCampaign,
   runEval,
-  runImprovementLoop
+  runImprovementLoop,
+  selfImprove
 };
 //# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../../src/contract/self-improve.ts"],"sourcesContent":["/**\n * # `selfImprove()` — the LAND-tier one-shot.\n *\n * The cheapest possible call site to run a real closed-loop self-\n * improvement over your agent. Wraps `runImprovementLoop` with smart\n * defaults and a budget-shaped options API; every escape hatch the\n * substrate exposes is reachable from here without losing the\n * one-function feel.\n *\n * Defaults picked to match the LAND-tier story:\n *   - In-memory storage (no filesystem touch).\n *   - `gepaDriver` reflective mutation with copywriting-flavored primitives\n *     (override `driver` or `mutationPrimitives` for any domain).\n *   - `defaultProductionGate` with `deltaThreshold: 0.05`.\n *   - Held-out split = 25% of scenarios, deterministic by id hash.\n *   - 3 generations × population 2 (raise via `budget` for more search).\n *   - `autoOnPromote: 'none'` (we don't open PRs unless you ask).\n *\n * Want one-click? Provide `agent` + `scenarios` + `judge`. Done.\n * Want distributed? Pass `cellPlacement` + an `httpDispatch`-backed\n * agent. Want a code-tier surface? Pass a `MutableSurface` + your own\n * `driver`. Same function.\n */\n\nimport { runImprovementLoop, type RunImprovementLoopResult } from '../campaign/presets/run-improvement-loop'\nimport { gepaDriver } from '../campaign/drivers/gepa'\nimport { defaultProductionGate } from '../campaign/gates/default-production-gate'\nimport { type CampaignStorage, inMemoryCampaignStorage } from '../campaign/storage'\nimport type {\n  DispatchContext,\n  Gate,\n  ImprovementDriver,\n  JudgeConfig,\n  MutableSurface,\n  Scenario,\n} from '../campaign/types'\n\nexport interface SelfImproveBudget {\n  /** Hard $ ceiling across all cells in baseline + every generation. Cells\n   *  beyond the ceiling are skipped (cost-aware, not aborted). */\n  dollars?: number\n  /** How many improvement generations to explore. Default 3. Set 0 to\n   *  skip improvement entirely (selfImprove becomes a baseline-only run). */\n  generations?: number\n  /** Candidates the driver proposes per generation. Default 2. */\n  populationSize?: number\n  /** Max concurrent cells across the loop. Default 2. */\n  maxConcurrency?: number\n  /** Fraction of `scenarios` held out from training, used for the gate.\n   *  Default 0.25. Ignored when `holdoutScenarios` is set explicitly. */\n  holdoutFraction?: number\n  /** Explicit held-out scenarios; overrides `holdoutFraction`. */\n  holdoutScenarios?: Scenario[]\n}\n\nexport interface SelfImproveLlm {\n  /** Endpoint base URL. Default Tangle Router. */\n  baseUrl?: string\n  /** Bearer token. Default `process.env.OPENAI_API_KEY`. */\n  apiKey?: string\n  /** Model id used by `gepaDriver` reflection. Default\n   *  `anthropic/claude-sonnet-4.6`. */\n  model?: string\n}\n\nexport type SelfImproveProgressEvent =\n  | { kind: 'baseline.started'; scenarios: number }\n  | { kind: 'baseline.completed'; compositeMean: number; durationMs: number }\n  | { kind: 'generation.started'; index: number; populationSize: number }\n  | { kind: 'generation.completed'; index: number; bestComposite: number; durationMs: number }\n  | { kind: 'gate.decided'; decision: string; lift: number }\n\nexport interface SelfImproveOptions<TScenario extends Scenario, TArtifact> {\n  /**\n   * Your agent — a function that takes the current `MutableSurface`\n   * (typically a system prompt the loop is optimizing) plus the\n   * scenario + cell ctx, and returns the artifact your judge scores.\n   *\n   * Same shape as `RunOptimizationOptions.dispatchWithSurface`. Wrap a\n   * plain `Dispatch` if you don't have a surface seam:\n   *\n   *   agent: (_surface, scenario, ctx) => yourPlainDispatch(scenario, ctx)\n   *\n   * That mode evaluates without mutating any surface — useful as a\n   * baseline-only run (set `budget.generations = 0`).\n   */\n  agent: (\n    surface: MutableSurface,\n    scenario: TScenario,\n    ctx: DispatchContext,\n  ) => Promise<TArtifact>\n\n  /** Scenarios to evaluate against. Train/holdout split is computed from\n   *  these unless `budget.holdoutScenarios` is set explicitly. */\n  scenarios: TScenario[]\n\n  /** Judge that scores artifacts. Bring your own; use `langchainJudge`\n   *  from `/adapters/langchain` for a Runnable-shaped one. */\n  judge: JudgeConfig<TArtifact, TScenario>\n\n  /** Starting surface — system prompt, JSON config, anything `MutableSurface`\n   *  accepts. The driver mutates this each generation. */\n  baselineSurface: MutableSurface\n\n  /** Budget + loop shape. All fields optional; defaults pick the LAND-tier\n   *  story. */\n  budget?: SelfImproveBudget\n\n  /** Custom driver. Default is `gepaDriver` configured from `llm` +\n   *  `mutationPrimitives`. */\n  driver?: ImprovementDriver\n\n  /** Default-driver overrides — used when `driver` is unset. */\n  mutationPrimitives?: string[]\n  driverTarget?: string\n\n  /** Custom gate. Default is `defaultProductionGate` with\n   *  `deltaThreshold: 0.05` on the held-out split. */\n  gate?: Gate<TArtifact, TScenario>\n\n  /** LLM config consumed by the default `gepaDriver`. Ignored if you pass\n   *  your own `driver`. */\n  llm?: SelfImproveLlm\n\n  /** Storage backend. Default `inMemoryCampaignStorage()` — nothing\n   *  persists past the call. Pass `fsCampaignStorage()` to write to disk. */\n  storage?: CampaignStorage\n\n  /** Run directory (logical for in-memory storage, real path for fs).\n   *  Default `mem://selfImprove-<timestamp>`. */\n  runDir?: string\n\n  /** Distributed-driver seam — same as `RunCampaignOptions.cellPlacement`.\n   *  Returns an opaque placement key the substrate forwards to your agent\n   *  as `ctx.placement`. Combined with `httpDispatch` from\n   *  `/adapters/http`, fans cells across regions. */\n  cellPlacement?: (input: {\n    scenario: TScenario\n    rep: number\n    generation?: number\n  }) => string | undefined\n\n  /** Streaming hook — fires on baseline + each generation + gate decision.\n   *  Consumer routes events wherever (UI, dashboard, logs). */\n  onProgress?: (event: SelfImproveProgressEvent) => void\n\n  /** Auto-promotion behavior on a ship decision. Default `'none'` — we\n   *  return the winner; you ship it however you ship. `'pr'` opens a\n   *  GitHub PR via `openAutoPr`; requires `ghOwner` + `ghRepo`. */\n  autoOnPromote?: 'pr' | 'none'\n  ghOwner?: string\n  ghRepo?: string\n}\n\nexport interface SelfImproveResult<TScenario extends Scenario, TArtifact> {\n  /** Composite mean across all scenarios, baseline run. */\n  baseline: {\n    compositeMean: number\n    perScenario: Record<string, number>\n  }\n  /** Composite mean on the held-out set, winner run. */\n  winner: {\n    compositeMean: number\n    perScenario: Record<string, number>\n    surface: MutableSurface\n  }\n  /** `winner.compositeMean - baselineOnHoldout.compositeMean`. Positive\n   *  means the gate observed improvement. */\n  lift: number\n  /** `defaultProductionGate.decide()` result. */\n  gateDecision: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling'\n  /** Number of generations actually explored (may be less than the\n   *  budget if the driver gave up early). */\n  generationsExplored: number\n  /** Wall-clock total. */\n  durationMs: number\n  /** Total cost across baseline + every generation. */\n  totalCostUsd: number\n  /**\n   * Raw substrate result for advanced inspection — full per-generation\n   * candidates, full campaign artifacts, all judge scores. Useful for\n   * debugging or reporting beyond the summary.\n   */\n  raw: RunImprovementLoopResult<TArtifact, TScenario>\n}\n\n/**\n * Deterministic train/holdout split by a stable hash of `scenario.id`,\n * so the same scenario set always splits the same way across runs.\n */\nfunction splitTrainHoldout<TScenario extends Scenario>(\n  scenarios: TScenario[],\n  fraction: number,\n): { train: TScenario[]; holdout: TScenario[] } {\n  // Stable fnv-1a-ish hash of the id for ordering.\n  function hash(s: string): number {\n    let h = 2166136261 >>> 0\n    for (let i = 0; i < s.length; i++) {\n      h ^= s.charCodeAt(i)\n      h = Math.imul(h, 16777619) >>> 0\n    }\n    return h\n  }\n  const sorted = [...scenarios].sort((a, b) => hash(a.id) - hash(b.id))\n  const nHoldout = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)))\n  return {\n    holdout: sorted.slice(0, nHoldout),\n    train: sorted.slice(nHoldout),\n  }\n}\n\nfunction meanComposite(\n  byScenario: Record<string, { meanComposite: number }>,\n): { compositeMean: number; perScenario: Record<string, number> } {\n  const perScenario: Record<string, number> = {}\n  const values: number[] = []\n  for (const [id, agg] of Object.entries(byScenario)) {\n    perScenario[id] = agg.meanComposite\n    values.push(agg.meanComposite)\n  }\n  return {\n    compositeMean: values.length === 0 ? 0 : values.reduce((s, v) => s + v, 0) / values.length,\n    perScenario,\n  }\n}\n\nconst DEFAULT_MUTATION_PRIMITIVES = [\n  'Tighten the hook: lead with the specific user outcome.',\n  'Replace generic adjectives with specific verbs or proof numbers.',\n  'Anchor every claim in something the scenario\\'s brief literally supports.',\n  'Honor the surface-shape constraint (length, register, audience vocabulary).',\n]\n\n/**\n * One-shot self-improvement loop. See module docstring for defaults +\n * extension points.\n *\n * @example Minimum (LAND tier):\n *\n *   const result = await selfImprove({\n *     agent: (surface, scenario, ctx) => myAgent(surface, scenario, ctx.signal),\n *     scenarios,\n *     judge,\n *     baselineSurface: DEFAULT_PROMPT,\n *   })\n *   console.log(`lift: ${result.lift.toFixed(3)} (${result.gateDecision})`)\n *\n * @example Distributed (workers in three regions):\n *\n *   await selfImprove({\n *     agent: httpDispatch({ resolveUrl: ({ placement }) => REGION_URLS[placement!] }),\n *     scenarios,\n *     judge,\n *     baselineSurface: DEFAULT_PROMPT,\n *     cellPlacement: ({ scenario }) => scenario.region,\n *     budget: { maxConcurrency: 12 },\n *   })\n */\nexport async function selfImprove<TScenario extends Scenario, TArtifact>(\n  opts: SelfImproveOptions<TScenario, TArtifact>,\n): Promise<SelfImproveResult<TScenario, TArtifact>> {\n  const startedAt = Date.now()\n\n  const budget = opts.budget ?? {}\n  const generations = budget.generations ?? 3\n  const populationSize = budget.populationSize ?? 2\n  const maxConcurrency = budget.maxConcurrency ?? 2\n  const holdoutFraction = budget.holdoutFraction ?? 0.25\n  const costCeiling = budget.dollars\n\n  const explicitHoldout = budget.holdoutScenarios\n  const { train, holdout } = explicitHoldout\n    ? {\n        train: opts.scenarios.filter((s) => !explicitHoldout.some((h) => h.id === s.id)),\n        holdout: explicitHoldout as TScenario[],\n      }\n    : splitTrainHoldout(opts.scenarios, holdoutFraction)\n\n  if (train.length === 0) {\n    throw new Error('selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios.')\n  }\n  if (holdout.length === 0) {\n    throw new Error('selfImprove: holdout split is empty. Pass more scenarios.')\n  }\n\n  const driver: ImprovementDriver =\n    opts.driver ??\n    gepaDriver({\n      llm: {\n        baseUrl: opts.llm?.baseUrl ?? 'https://router.tangle.tools/v1',\n        apiKey: opts.llm?.apiKey ?? process.env.OPENAI_API_KEY ?? '',\n      },\n      model: opts.llm?.model ?? 'anthropic/claude-sonnet-4.6',\n      target: opts.driverTarget ?? 'agent surface (system prompt or config) being optimized by selfImprove',\n      mutationPrimitives: opts.mutationPrimitives ?? DEFAULT_MUTATION_PRIMITIVES,\n    })\n\n  const gate: Gate<TArtifact, TScenario> =\n    opts.gate ??\n    defaultProductionGate<TArtifact, TScenario>({\n      holdoutScenarios: holdout,\n      deltaThreshold: 0.05,\n    })\n\n  const storage = opts.storage ?? inMemoryCampaignStorage()\n  const runDir = opts.runDir ?? `mem://selfImprove-${startedAt}`\n\n  if (opts.onProgress) {\n    opts.onProgress({ kind: 'baseline.started', scenarios: opts.scenarios.length })\n  }\n\n  const result = await runImprovementLoop<TScenario, TArtifact>({\n    scenarios: train,\n    baselineSurface: opts.baselineSurface,\n    dispatchWithSurface: opts.agent,\n    driver,\n    judges: [opts.judge],\n    populationSize,\n    maxGenerations: generations,\n    holdoutScenarios: holdout,\n    gate,\n    autoOnPromote: opts.autoOnPromote ?? 'none',\n    ghOwner: opts.ghOwner,\n    ghRepo: opts.ghRepo,\n    storage,\n    runDir,\n    maxConcurrency,\n    cellPlacement: opts.cellPlacement,\n    costCeiling,\n  })\n\n  const baseline = meanComposite(result.baselineOnHoldout.aggregates.byScenario)\n  const winnerStats = meanComposite(result.winnerOnHoldout.aggregates.byScenario)\n\n  if (opts.onProgress) {\n    opts.onProgress({\n      kind: 'baseline.completed',\n      compositeMean: baseline.compositeMean,\n      durationMs: Date.now() - startedAt,\n    })\n    opts.onProgress({\n      kind: 'gate.decided',\n      decision: result.gateResult.decision,\n      lift: winnerStats.compositeMean - baseline.compositeMean,\n    })\n  }\n\n  const totalCost =\n    result.baselineCampaign.aggregates.totalCostUsd +\n    result.generations.reduce(\n      (sum, gen) => sum + gen.surfaces.reduce((s, sf) => s + sf.campaign.aggregates.totalCostUsd, 0),\n      0,\n    )\n\n  return {\n    baseline,\n    winner: {\n      ...winnerStats,\n      surface: result.winnerSurface,\n    },\n    lift: winnerStats.compositeMean - baseline.compositeMean,\n    gateDecision: result.gateResult.decision,\n    generationsExplored: result.generations.length,\n    durationMs: Date.now() - startedAt,\n    totalCostUsd: totalCost,\n    raw: result,\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "@tangle-network/agent-eval — wire protocol",
-    "version": "0.44.0",
+    "version": "0.45.0",
     "description": "HTTP and stdio RPC interface to agent-eval. The TypeScript runtime is the source of truth; this spec is the contract that cross-language clients (Python, Rust, Go) generate from.\n\nWire-protocol version: 1.0.0. Bumps on breaking changes to request/response schemas.",
     "contact": {
       "name": "Tangle Network",

package/dist/rl.d.ts

@@ -1,5 +1,5 @@
 import { R as RunRecord, a as RunSplitTag } from './run-record-BGY6bHRh.js';
-import { d as CampaignResult } from './types-DToGONFA.js';
+import { d as CampaignResult } from './types-8u72Gc76.js';
 import { V as VerificationReport, R as Researcher, F as FailureMode, S as SteeringChange, E as ExperimentPlan, a as ExperimentResult, b as EvalCampaignResult, c as EvalCampaignOptions } from './researcher-CoJMs2Iz.js';
 export { r as runEvalCampaign } from './researcher-CoJMs2Iz.js';
 import { S as Span, T as TraceStore } from './store-Db2Bv8Cf.js';

package/dist/{run-campaign-GNDO66B4.js → run-campaign-6UEVBPP3.js}

@@ -1,10 +1,10 @@
 import {
   runCampaign
-} from "./chunk-RXK7FXLV.js";
+} from "./chunk-J3EIOI3O.js";
 import "./chunk-WP7SY7AI.js";
 import "./chunk-QYJT52YW.js";
 import "./chunk-NSBPE2FW.js";
 export {
   runCampaign
 };
-//# sourceMappingURL=run-campaign-GNDO66B4.js.map
+//# sourceMappingURL=run-campaign-6UEVBPP3.js.map

package/dist/{run-improvement-loop-CbilHQAb.d.ts → run-improvement-loop-Bfam3MT1.d.ts}

@@ -1,4 +1,4 @@
-import { S as Scenario, d as CampaignResult, j as GateResult, o as Mutator, I as ImprovementDriver, G as Gate, D as DispatchFn, J as JudgeConfig, L as LabeledScenarioStore, e as CampaignTraceWriter, M as MutableSurface, l as GenerationRecord } from './types-DToGONFA.js';
+import { S as Scenario, d as CampaignResult, j as GateResult, o as Mutator, I as ImprovementDriver, G as Gate, g as DispatchFn, J as JudgeConfig, L as LabeledScenarioStore, e as CampaignTraceWriter, M as MutableSurface, l as GenerationRecord } from './types-8u72Gc76.js';
 import { L as LlmClientOptions } from './llm-client-BXVRUZyX.js';
 import { RunRecord } from '@tangle-network/agent-runtime';
 import { R as RedTeamCase } from './red-team-30II1T4o.js';
@@ -267,6 +267,22 @@ interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
      *  (Cloudflare Workers, Deno, edge) — the `CampaignResult` is still
      *  produced; artifacts/traces just aren't persisted to disk. */
     storage?: CampaignStorage;
+    /**
+     * Optional per-cell placement strategy. Returns an opaque string the
+     * substrate forwards as `ctx.placement` to the Dispatch — placement-aware
+     * Dispatches (e.g. `httpDispatch` from `/adapters/http`) use it to route
+     * each cell to the right worker, region, or sandbox. When unset, every
+     * cell receives `ctx.placement = undefined` and behaves identically to
+     * the in-process case.
+     *
+     * @example
+     *   cellPlacement: ({ scenario }) => scenario.tags?.includes('eu') ? 'eu-west' : 'us-east'
+     */
+    cellPlacement?: (input: {
+        scenario: TScenario;
+        rep: number;
+        generation?: number;
+    }) => string | undefined;
 }
 declare function runCampaign<TScenario extends Scenario, TArtifact>(opts: RunCampaignOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
 
@@ -398,4 +414,4 @@ interface RunImprovementLoopResult<TArtifact, TScenario extends Scenario> extend
 }
 declare function runImprovementLoop<TScenario extends Scenario, TArtifact>(opts: RunImprovementLoopOptions<TScenario, TArtifact>): Promise<RunImprovementLoopResult<TArtifact, TScenario>>;
 
-export { type CampaignStorage as C, type DefaultProductionGateOptions as D, type EvolutionaryDriverOptions as E, type GepaDriverOptions as G, type HeldOutGateOptions as H, type OpenAutoPrOptions as O, type RunCampaignOptions as R, type RunEvalOptions as a, type RunImprovementLoopOptions as b, type RunImprovementLoopResult as c, composeGate as d, defaultProductionGate as e, evolutionaryDriver as f, fsCampaignStorage as g, gepaDriver as h, heldOutGate as i, inMemoryCampaignStorage as j, runEval as k, runImprovementLoop as l, type OpenAutoPrResult as m, type RunOptimizationOptions as n, type RunOptimizationResult as o, openAutoPr as p, runOptimization as q, runCampaign as r, surfaceHash as s };
+export { type CampaignStorage as C, type DefaultProductionGateOptions as D, type EvolutionaryDriverOptions as E, type GepaDriverOptions as G, type HeldOutGateOptions as H, type OpenAutoPrOptions as O, type RunImprovementLoopResult as R, type RunCampaignOptions as a, type RunEvalOptions as b, type RunImprovementLoopOptions as c, composeGate as d, defaultProductionGate as e, evolutionaryDriver as f, fsCampaignStorage as g, gepaDriver as h, heldOutGate as i, inMemoryCampaignStorage as j, runEval as k, runImprovementLoop as l, type OpenAutoPrResult as m, type RunOptimizationOptions as n, type RunOptimizationResult as o, openAutoPr as p, runOptimization as q, runCampaign as r, surfaceHash as s };

package/dist/{types-DToGONFA.d.ts → types-8u72Gc76.d.ts}

@@ -40,6 +40,14 @@ interface DispatchContext {
     cycleId?: string;
     /** Populated when the substrate resumed from a prior cache hit. */
     resumedFrom?: string;
+    /**
+     * Opaque placement key supplied by `RunCampaignOptions.cellPlacement`.
+     * The substrate forwards it through unchanged; placement-aware Dispatch
+     * implementations (e.g. `httpDispatch` from `/adapters/http`) read it to
+     * route the cell to the right worker / region / sandbox. `undefined`
+     * when no placement strategy is configured.
+     */
+    placement?: string;
 }
 /** @experimental One function: scenario + ctx → artifact. Dispatcher chooses
  *  whether to call `runMultishot`, `runLoop`, raw `streamPrompt`, anything. */
@@ -364,4 +372,4 @@ interface CampaignResult<TArtifact = unknown, TScenario extends Scenario = Scena
     scenarios: Array<Pick<TScenario, 'id' | 'kind'>>;
 }
 
-export type { CampaignAggregates as C, DispatchFn as D, Gate as G, ImprovementDriver as I, JudgeConfig as J, LabeledScenarioStore as L, MutableSurface as M, OptimizerConfig as O, ProposeContext as P, RedactionStatus as R, Scenario as S, TraceSpan as T, CampaignArtifactWriter as a, CampaignCellResult as b, CampaignCostMeter as c, CampaignResult as d, CampaignTraceWriter as e, CodeSurface as f, DispatchContext as g, GateContext as h, GateDecision as i, GateResult as j, GenerationCandidate as k, GenerationRecord as l, JudgeDimension as m, JudgeScore as n, Mutator as o, SessionScript as p, LabeledScenarioWrite as q, LabeledScenarioSampleArgs as r, LabeledScenarioRecord as s, JudgeAggregate as t, LabeledScenarioSource as u, ScenarioAggregate as v };
+export type { CampaignAggregates as C, DispatchContext as D, Gate as G, ImprovementDriver as I, JudgeConfig as J, LabeledScenarioStore as L, MutableSurface as M, OptimizerConfig as O, ProposeContext as P, RedactionStatus as R, Scenario as S, TraceSpan as T, CampaignArtifactWriter as a, CampaignCellResult as b, CampaignCostMeter as c, CampaignResult as d, CampaignTraceWriter as e, CodeSurface as f, DispatchFn as g, GateContext as h, GateDecision as i, GateResult as j, GenerationCandidate as k, GenerationRecord as l, JudgeDimension as m, JudgeScore as n, Mutator as o, SessionScript as p, LabeledScenarioWrite as q, LabeledScenarioSampleArgs as r, LabeledScenarioRecord as s, JudgeAggregate as t, LabeledScenarioSource as u, ScenarioAggregate as v };

package/docs/adapters-observability.md

@@ -0,0 +1,121 @@
+# Composing agent-eval with your observability stack
+
+`@tangle-network/agent-eval` ships its own OpenTelemetry pipeline
+(`@tangle-network/agent-eval/telemetry`) that emits spans for every
+cell, judge invocation, mutator proposal, and gate decision. **It's
+just OTel** — same protocol as Langfuse SDK, OpenLLMetry, Arize
+Phoenix, TraceAI, and the OpenTelemetry GenAI semantic conventions.
+
+That means: if you already instrument your agent with any OTel-native
+observability tool, the two compose **for free at the protocol layer**.
+This doc shows the composition pattern; no agent-eval-specific adapter
+code required.
+
+## TL;DR — one OTel context, two emitters
+
+1. Set up a shared OTel tracer provider in your process (or service mesh).
+2. Configure your observability tool (TraceAI / Langfuse / OpenLLMetry /
+   Phoenix) to register its instrumentations against that provider.
+3. Configure agent-eval's `/telemetry` exporter against the same provider.
+4. Run a campaign. Both sets of spans land at your OTel collector.
+5. Filter / route / fan-out at the collector layer — Jaeger, Tempo,
+   Phoenix, Langfuse cloud, your private collector, whatever.
+
+The Tangle substrate doesn't compete with the observability tool;
+they're orthogonal. The tool tells you *what your agent did*; the
+substrate tells you *what the campaign / judge / mutator decided about
+it*. Unified at the trace level, you see both as one timeline per cell.
+
+## Per-tool notes
+
+### TraceAI (Future-AGI)
+
+- TS SDK auto-instruments OpenAI/Anthropic SDKs + LangChain.
+- Compatible with the OpenTelemetry GenAI semantic conventions.
+- Compose: register TraceAI's instrumentations on the global tracer
+  provider, then either point both at your OTLP collector or at
+  TraceAI's hosted backend if you want their UI.
+
+### Langfuse SDK
+
+- Larger installed base; has its own hosted product + OSS self-host.
+- Their OpenTelemetry-compatible mode ships LLM call spans with
+  Langfuse-specific attributes preserved.
+- Compose: register Langfuse as an OTel processor; agent-eval's
+  campaign/judge/mutator spans appear alongside the LLM calls in their
+  UI.
+
+### OpenLLMetry (Traceloop)
+
+- OSS auto-instrumentation library; OTel-native by design.
+- Wide framework coverage (LangChain, LlamaIndex, Haystack, OpenAI,
+  Anthropic).
+- Compose: set up Traceloop's exporter; agent-eval's exporter shares
+  the same trace context per cell.
+
+### Arize Phoenix
+
+- OSS observability backend; strong in the eval-tooling community.
+- OTel-native ingest; renders trace + span attributes per the GenAI
+  semantic conventions.
+- Compose: point both exporters at your local Phoenix instance. Phoenix
+  becomes the unified UI for both LLM-call traces and campaign spans.
+
+## Wiring pattern (reference)
+
+```ts
+import { trace } from '@opentelemetry/api'
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
+
+// 1. One shared tracer provider for the process.
+const provider = new NodeTracerProvider()
+provider.addSpanProcessor(new SimpleSpanProcessor(
+  new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+))
+provider.register()
+
+// 2. Your observability tool registers against the global provider.
+//    Example for TraceAI / OpenLLMetry / Langfuse — call their init.
+//    (See each tool's docs.)
+
+// 3. agent-eval is already OTel-native; it picks up the same global
+//    provider. Just ensure `@tangle-network/agent-eval/telemetry` is
+//    initialized for the campaign:
+import { setOtelExporter } from '@tangle-network/agent-eval/telemetry'
+setOtelExporter({ kind: 'otel-global' })  // use the global provider
+
+// 4. Run your campaign — both sets of spans land at the collector.
+import { runEval } from '@tangle-network/agent-eval/contract'
+await runEval({ /* ... */ })
+```
+
+That's it. No new adapter shipping required — the libs are already
+designed to live in the same OTel ecosystem.
+
+## When you'd want a deeper, code-level adapter
+
+The two cases where a thin adapter would add value beyond the
+OTel-protocol composition:
+
+1. **Cost-aware judging.** Your observability tool's auto-instrumented
+   spans carry token counts + cost. A custom `JudgeConfig` can read
+   them via the OTel context and refuse to score artifacts that
+   exceeded a per-call budget. Easy to write yourself; we'll ship a
+   reference helper (`costAwareJudgeFromOtel`) when a partner pulls on
+   this.
+2. **Tool-aware judging.** Your instrumentation captures the tool-call
+   sequence (`langchain.tool.invoked`, `openai.function.called`, etc.).
+   A judge that scores "did the agent use the right tool" reads those
+   spans directly. Also straightforward; helper ships when needed.
+
+Both of these are L1-tier ergonomic helpers; the underlying composition
+works today without them.
+
+## What this does NOT install
+
+No new dependencies. No new peer deps. No `@traceai/*`, no
+`@langfuse/*`, no `@opentelemetry/*` in our manifest. You bring the
+observability stack you want; agent-eval just emits OTel and respects
+whatever provider is registered.

package/docs/design/external-agent-wedge.md

@@ -32,11 +32,11 @@ So adoption is *graduated*, and the builder picks the depth: (1) **trace-analysi
 
 | Tier | What they do | What they get | Billing |
 |---|---|---|---|
-| **LAND** (exists today) | `npm i @tangle-network/agent-eval`, wrap their agent behind one `dispatch` seam, bring a judge | Full self-improvement loop + **local** trace/eval artifacts. Any infra, no sandbox. | Free (lib) |
+| **LAND** (exists today) | `npm i @tangle-network/agent-eval`, wrap their agent behind one `dispatch` seam, bring a judge | Full self-improvement loop + **local** trace/eval artifacts. Any infra, no sandbox. | Free (lib) — **with optional Tangle Router as a $0-friction inference upsell.** When a builder points `OPENAI_BASE_URL` at `router.tangle.tools/v1`, every campaign call (agent + judge + reflective mutation) routes through us; we earn the routing margin. Same code, opt-in monetization vector that ships today. |
 | **EXPAND** (the build) | Route trace/eval/labeled-scenario data to our orchestrator | Hosted dashboards, cross-run intelligence, the capture flywheel as a service | **Metered** — composes with existing sandbox Stripe + cost-ledger |
 | **PLATFORM** (the carrot) | Move execution into our sandbox (agent-dev-container) | Substrate + orchestrator data/intelligence pre-wired, batteries included | Sandbox usage |
 
-The free lib casts the widest possible net at near-zero cost (it's already published). Value capture is EXPAND: hosting their data/intelligence = a billable surface on the dimensions we already meter (ingested/retained volume, eval-campaign compute, loop runs, seats). "We don't host observability unless they route to us" is the *business model*, not a gap.
+The free lib casts the widest possible net at near-zero cost (it's already published). LAND is **not actually zero-revenue** — pointing the loop at Tangle Router is a one-line config change with no other code differences, so we monetize inference for any LAND-tier adopter who opts in. The wedge ladder is therefore four steps: no-revenue install → router routing margin (LAND with router) → metered data hosting (EXPAND) → sandbox usage (PLATFORM). Each step a one-line config change, never a rewrite. Value capture concentrates at EXPAND (hosting their data/intelligence is the biggest billable surface), but LAND-with-router is the immediate upsell available from day one.
 
 ## Plan & gates — land-first, validate, then build