@tangle-network/agent-eval 0.196.0 → 0.198.0

package/dist/search/index.d.ts

@@ -0,0 +1,1162 @@
+import { A as SearchLedgerHash, C as SearchEdgeOperator, G as SearchSplit, H as SearchProposerKind, I as SearchNodeStatus, L as SearchOpenedEvent, T as SearchEstimateMethod, W as SearchSourceRef, i as SearchArtifactRef, j as SearchModelIdentity, l as SearchCandidateSurface, m as SearchClaim, t as NodeEstimate, y as SearchCloseReason } from "../search-ledger-types-p2xKfiDJ.js";
+import { $ as SearchNode, it as SearchStateView } from "../types-EBUav9Bu.js";
+import { $ as EXPANSION_OPERATORS, L as SearchPolicy, M as SearchUnitExtension, at as OperatorYieldRow, ct as LensResult, dt as rankingSplit, et as ExpansionOperator, ft as summarizeSamples, it as OperatorYieldOptions, lt as LensSignal, nt as OperatorOutcomeCounts, ot as OperatorYieldSignal, p as SearchRunResult, r as SearchArtifactCodec, rt as OperatorYieldData, s as SearchLane, st as operatorYield, t as RunSearchOptions, tt as MIN_OUTCOMES_FOR_WEIGHT, ut as SampleSummary, z as SearchPolicyView } from "../search-kernel-CuvbakC_.js";
+import { AgentProfileResourceRef } from "@tangle-network/agent-interface";
+//#region src/search/lenses/edit-credit.d.ts
+/** Signal name a policy reads. */
+declare const EDIT_CREDIT_SIGNAL = "reusableHunks";
+/** The estimator every gene credit names. */
+declare const EDIT_CREDIT_ESTIMATOR: SearchSourceRef;
+interface EditCreditOptions {
+  /**
+   * The parsed content a node's artifact reference names, or undefined when
+   * it is unavailable. The caller must verify the bytes against `ref.sha256`;
+   * the lens trusts what it is handed.
+   */
+  readArtifact(ref: SearchArtifactRef): unknown | undefined;
+  /** Split credit is measured on. Default: selection when the search declares
+   * one, else train. */
+  split?: SearchSplit;
+  /** Genes tested for pairwise interaction: those with the most measured
+   * units, one per linkage group. Default 24, so at most 276 pairs. */
+  interactionGenes?: number;
+}
+type EditGeneVerdict = 'reusable' | 'harmful' | 'unresolved' | 'insufficient';
+interface EditIntroduction {
+  nodeId: string;
+  edgeId: string;
+  operator: SearchEdgeOperator;
+  parents: string[];
+  /** The edge is a re-proposal into a node registered earlier. */
+  reproposal: boolean;
+}
+interface EditGene {
+  geneId: string;
+  kind: 'insert' | 'delete';
+  /** Where in the artifact: `prompt`, `component:<name>`, or a JSON path such
+   * as `/prompt/systemPrompt`. */
+  path: string;
+  /** Normalized lines: the gene's identity. */
+  lines: string[];
+  /** The lines as the first proposer wrote them. */
+  text: string;
+  /** Lineage edges whose child carries the gene while none of its parents
+   * did, in ledger order. More than one means a proposer made the same edit
+   * again. */
+  introduced: EditIntroduction[];
+  /** Lineage edges whose child lost the gene that a parent carried. */
+  dropped: number;
+  /** Genes introduced on the edge that first introduced this one: the edit
+   * it was born in, itself included, in artifact order. */
+  edit: string[];
+  /** Nodes with known content that carry it and are not invalid. */
+  carriers: number;
+  /** `invalid` carriers (judge integrity or admission failures), excluded from
+   * every contrast; an edit that makes nodes invalid shows here. */
+  invalidCarriers: number;
+  steps: {
+    /** Steps on which the gene flips. */
+    flips: number;
+    /** Of those, the steps its credit reads. */
+    clean: number;
+    /** Clean steps on which the child gained the gene. */
+    gained: number;
+    /** Clean steps on which the child lost it. */
+    lost: number;
+  };
+  /** Carrying side against lacking side on clean steps; `delta` is carrier
+   * minus non-carrier in the metric's units. */
+  credit: NodeEstimate;
+  verdict: EditGeneVerdict;
+  /** The first gene of this gene's linkage group: genes with the same clean
+   * steps, oriented the same way, have one credit and cannot be separated.
+   * Null when the gene has no partner. */
+  linkage: string | null;
+}
+interface EditInteraction {
+  genes: [string, string];
+  /** Clean steps of each gene, split by whether both ends carry the other. */
+  steps: {
+    firstWithSecond: number;
+    firstWithoutSecond: number;
+    secondWithFirst: number;
+    secondWithoutFirst: number;
+  };
+  /** Units with a contrast in at least one direction. */
+  units: number;
+  method: SearchEstimateMethod;
+  /** Mean per-unit difference of a gene's credit with the other present minus
+   * with it absent, both directions averaged, in the metric's units; null
+   * below 2 units. */
+  interaction: number | null;
+  /** Percentile bootstrap spread from 6 units; null below 6 or when every
+   * per-unit contrast is equal. */
+  interval: [number, number] | null;
+  indeterminate: boolean;
+  /** Exact two-sided sign test; null below 6 units. */
+  signP: number | null;
+  /** Holm-adjusted over every pair tested; null when this pair was not tested. */
+  adjustedP: number | null;
+  interacting: boolean;
+  /** The pair does better together than their separate credits add up to, in
+   * the objective's direction. Null without an interaction estimate. */
+  synergy: boolean | null;
+}
+interface EditSkillCandidate {
+  /** An inline skill resource: add it to `profile.resources.skills` (with
+   * `resources.failOnError: true`) and pass `improveOptions` to agent-runtime
+   * `improve()` with `method: officialSkillOpt(...)` to optimize it. */
+  resource: Extract<AgentProfileResourceRef, {
+    kind: 'inline';
+  }>;
+  improveOptions: {
+    surface: 'skills';
+    skills: {
+      resourceName: string;
+    };
+  };
+  /** The linked insert genes the skill holds, in artifact order. */
+  genes: string[];
+  path: string;
+  credit: NodeEstimate;
+}
+interface EditLineageRow {
+  nodeId: string;
+  ordinal: number;
+  depth: number | null;
+  primaryParentId: string | null;
+  parents: string[];
+  operator: SearchEdgeOperator | null;
+  status: SearchNode['status'];
+  /** Every gene this node carries. */
+  carries: string[];
+  contentKnown: boolean;
+}
+interface EditCreditData {
+  split: SearchSplit;
+  direction: 'maximize' | 'minimize';
+  edges: {
+    /** Edges with at least one parent registered before the child in this search. */
+    lineage: number;
+    /** Of those, edges whose child and every lineage parent had known content. */
+    read: number;
+    /** Why an edge's content was unknown, with counts. */
+    unknown: Record<string, number>;
+  };
+  /** Distinct parent-child pairs with known content; those with an invalid
+   * end are excluded from every contrast. */
+  steps: {
+    total: number;
+    invalidEnd: number;
+  };
+  nodes: {
+    total: number;
+    contentUnknown: number;
+    invalid: number;
+  };
+  /** Reusable, harmful, unresolved, then insufficient; within each, by credit. */
+  genes: EditGene[];
+  counts: Record<EditGeneVerdict, number>;
+  /** Independent edits per verdict: linkage groups, and for genes without a
+   * clean step the edit they were born in. */
+  editCounts: Record<EditGeneVerdict, number>;
+  interactions: {
+    genesConsidered: number;
+    /** Pairs with a with-and-without split in at least one direction. */
+    pairsWithContexts: number;
+    /** Pairs with 6 or more units and a non-degenerate contrast. */
+    pairsTested: number;
+    alpha: number;
+    correction: 'holm';
+    /** Flagged pairs first, then by adjusted p. */
+    pairs: EditInteraction[];
+  };
+  skillCandidates: EditSkillCandidate[];
+  /** What the reusable count would be with no true effect anywhere: credit is
+   * not adjusted for the number of edits, so read `reusable` against this. */
+  chance: {
+    /** Independent edits measured on 6 or more units. */
+    measuredEdits: number;
+    /** Sum over measured edits of the chance the verdict calls one reusable
+     * when it has no effect. */
+    expectedReusable: number;
+    method: string;
+  };
+  /** Rows in lineage order (depth-first along primary parents): the matrix a
+   * genealogy view draws, genes as columns. */
+  lineage: EditLineageRow[];
+  method: {
+    estimator: SearchSourceRef;
+    credit: string;
+    verdict: string;
+    interaction: string;
+    multiplicity: string;
+    /** The known bias of a lineage contrast in a search. */
+    selectionBias: string;
+  };
+}
+/** The signal: independent edits `pairedDeltaTest` finds improve the
+ * objective, null below 6 units on every gene. */
+interface EditCreditSignal extends LensSignal<number | null> {
+  /** How the value was computed, or why it is null. */
+  basis: string;
+  /** The first gene of each reusable edit, best first: the hunks a proposer
+   * reuses or a skill extraction starts from. */
+  top: string[];
+}
+type EditCreditResult = LensResult<EditCreditData, number | null> & {
+  signal: EditCreditSignal;
+};
+/**
+ * The edit-credit lens. Pure: the result depends only on `state` and what
+ * `readArtifact` returns for its references.
+ */
+declare function editCredit(state: SearchStateView, options: EditCreditOptions): EditCreditResult;
+/** The lens as compact text: what `agent-eval search show --edit-credit`
+ * prints and a proposer can read. */
+declare function editCreditText(result: EditCreditResult, options?: {
+  limit?: number;
+}): string;
+//#endregion
+//#region src/search/lenses/front.d.ts
+interface FrontExtraAxis {
+  name: string;
+  direction: 'maximize' | 'minimize';
+  /** Reads the axis value for one node from the same state the lens holds.
+   * Returning a non-finite number excludes the node from this axis's frontier
+   * pass the same way an unknown score or cost does. */
+  value(state: SearchStateView, nodeId: string): number;
+}
+interface FrontRow {
+  nodeId: string;
+  /** Mean per-unit score on the ranking split, in the objective's own units;
+   * null when the node has no scored cell there. */
+  score: number | null;
+  knownCostUsd: number;
+  /** False when any of the node's cells has unknown-cost attempts: its true
+   * cost may be higher than `knownCostUsd`, so it never competes on cost. */
+  costKnown: boolean;
+  /** True only for a node with a known score and a known cost that no other
+   * such node dominates on every declared axis. */
+  onFront: boolean;
+}
+interface FrontData {
+  split: 'train' | 'selection';
+  axes: string[];
+  rows: FrontRow[];
+  frontierSize: number;
+  /** Rows excluded from every frontier pass: unknown score, unknown cost, or
+   * a non-finite extra-axis read. */
+  excludedCount: number;
+}
+interface FrontOptions {
+  split?: 'train' | 'selection';
+  axes?: FrontExtraAxis[];
+}
+/** nodeId → 1 on the frontier, 0 off it. Every scored node appears; an
+ * excluded (unknown-score or unknown-cost) node reads 0, same as a dominated
+ * one, because "on the front" is the only claim this signal makes. */
+type FrontSignal = Record<string, number>;
+declare function front(state: SearchStateView, options?: FrontOptions): {
+  data: FrontData;
+  signal: {
+    name: string;
+    value: FrontSignal;
+  };
+};
+//#endregion
+//#region src/search/lenses/geometry.d.ts
+/** The one number a geometry lens exposes to policies: the shared
+ * `LensSignal`, with the noise model and sample it rests on. */
+interface GeometrySignal extends LensSignal<number | null> {
+  /** What the value is about when it names one thing, for example the unit
+   * `nextUnit` recommends; null otherwise. */
+  subject: string | null;
+  /** How the value is computed, including its noise model. */
+  method: string;
+  /** The sample the value rests on, in the unit `method` names. */
+  n: number;
+  /** Why `value` is null; null when it is not. */
+  insufficient: string | null;
+}
+interface GeometryLensResult<TData> extends LensResult<TData, number | null> {
+  /** The lens name, for example `landscape`. */
+  lens: string;
+  searchId: string;
+  /** The ledger position the lens read: the head's sequence, or -1 before any entry. */
+  sequence: number;
+  signal: GeometrySignal;
+}
+/**
+ * Nodes whose screen finished, in registration order, root first: the
+ * ledger's reading of the kernel's `screened` list. A node counts once it is
+ * not decided invalid, has an edge, and every cell it was allocated outside a
+ * rung or the claim can no longer run (scored, final, cancelled, or errored
+ * with no attempt left). Cells a rung opened later do not un-screen it.
+ */
+declare function screenedNodes(state: SearchStateView, options?: {
+  maxAttempts?: number;
+}): string[];
+//#endregion
+//#region src/search/lenses/plateau.d.ts
+/** What the plateau reads: a policy view, or the lens's own reading of one. */
+type SearchPlateauView = Pick<SearchPolicyView, 'direction' | 'rootNodeId' | 'screened' | 'complete' | 'unitScores'>;
+interface SearchPlateauOptions {
+  /** Accepted nodes the rise is measured across. Default 6. */
+  window?: number;
+}
+interface SearchPlateau {
+  /** `rise / noise`; null when insufficient. Below 1 the best improvement rose
+   * less than one standard error across the window: a plateau. */
+  value: number | null;
+  window: number;
+  /** Screened non-root nodes that dodged no unit and share at least 6 units
+   * with the root (the design's `descriptive` threshold), in registration
+   * order. Only these can hold the best. */
+  accepted: number;
+  /** The accepted nodes the window covers, oldest first. */
+  windowNodes: string[];
+  /** Best improvement over the root after the window minus before it; the
+   * root itself is the best before any node, at exactly 0. */
+  rise: number | null;
+  /** Standard error of the best node's improvement: sqrt(pooled variance / its
+   * shared units). */
+  noise: number | null;
+  best: {
+    nodeId: string;
+    gain: number;
+    pairs: number;
+  } | null;
+  /** Between-unit variance of per-unit improvements over the root, pooled over
+   * every screened complete node with 2 or more shared units. */
+  pooledVariance: number | null;
+  degreesOfFreedom: number;
+  method: string;
+  insufficient: string | null;
+}
+/**
+ * The plateau score of a search. Nodes are taken in the view's screened
+ * order, which is registration order. Insufficient with fewer than `window`
+ * accepted nodes, or without a pooled variance above zero.
+ */
+declare function searchPlateau(view: SearchPlateauView, options?: SearchPlateauOptions): SearchPlateau;
+interface DraftOnPlateauOptions {
+  /** Accepted nodes the plateau's rise is measured across, and expansions
+   * between two drafts. Default 6. */
+  window?: number;
+  /** Draft when the plateau score is below this many standard errors.
+   * Default 1: the best improvement rose less than one standard error. */
+  below?: number;
+}
+/**
+ * `base`, except that on a plateau it drafts: it proposes a fresh artifact
+ * (operator `draft`, anchored on the root) instead of refining one. The
+ * plateau is the `landscape` lens's signal (`searchPlateau` on this view):
+ * how many standard errors the best improvement over the root rose across the
+ * last `window` accepted nodes. A draft needs a measured plateau (at least
+ * `window` accepted nodes and a pooled variance) and an expansion count that
+ * is a multiple of `window`, so `base` expands at least `window − 1` times
+ * between drafts and each draft's lineage gets a chance to lift the plateau.
+ * Nodes still screening do not hold a draft back: the kernel expands while
+ * its screening backlog is below twice the lane capacity, so under a full
+ * pipeline some node is always screening, and the plateau reads only nodes
+ * whose screen finished. The leader and patience are `base`'s.
+ *
+ * This is AIDE's draft trigger driven by measured progress instead of a fixed
+ * count; `draftOnPlateau(aide(...))` adds it to `aide`'s own drafts. A draft
+ * pays off only when `base` then expands drafts that trail the leader:
+ * `incumbent` expands only its leader, so a draft that starts below it is
+ * never refined.
+ */
+declare function draftOnPlateau(base: SearchPolicy, options?: DraftOnPlateauOptions): SearchPolicy;
+//#endregion
+//#region src/search/lenses/landscape.d.ts
+/**
+ * How the lens measures the distance between two nodes' profiles.
+ *
+ * - `lineage`: edits along the lineage graph, one per recorded improve,
+ *   debug or merge edge between nodes of this search. A draft edge is not an
+ *   edit (the draft is written afresh), so a draft's lineage is unreachable
+ *   by this distance and unplaced, never guessed; `surfaceTextEdits` places it.
+ * - `distance`: any symmetric distance; null when it cannot be measured.
+ * - `vector`: a vector per node, for example a model embedding of the
+ *   profile; nodes are compared by Euclidean distance.
+ */
+type LandscapeEmbedding = {
+  kind: 'lineage';
+  name: string;
+  method: string;
+} | {
+  kind: 'distance';
+  name: string;
+  method: string;
+  distance(a: SearchNode, b: SearchNode): number | null;
+} | {
+  kind: 'vector';
+  name: string;
+  method: string;
+  vector(node: SearchNode): readonly number[] | null;
+};
+/** The default: edits recorded between two profiles along the lineage. */
+declare function lineageEdits(): LandscapeEmbedding;
+/** Surfaces whose content digests differ: the edit distance between two
+ * profiles at the granularity of their declared surfaces. */
+declare function surfaceDigestEdits(): LandscapeEmbedding;
+/**
+ * Line edits between the surfaces' texts: for each declared surface, the
+ * fewest line insertions and deletions that turn one text into the other
+ * (Myers, 1986), summed over surfaces. `read` returns a surface's content:
+ * a string, parsed JSON (flattened with `profileTextLines`), or null when it
+ * cannot be read, which leaves every distance of that node unknown. The lens
+ * stays pure; the caller owns the I/O and its verification.
+ */
+declare function surfaceTextEdits(read: (surface: SearchCandidateSurface) => unknown): LandscapeEmbedding;
+/** A caller's vector per node, for example a model embedding of its profile. */
+declare function vectorEmbedding(name: string, vector: (node: SearchNode) => readonly number[] | null): LandscapeEmbedding;
+/**
+ * JSON as lines a diff can count: one line per scalar leaf, `path=value`, and
+ * one line per line of a string, so an edit inside a long prompt counts the
+ * lines it changed rather than the whole prompt. Object keys are visited in
+ * code-unit order.
+ */
+declare function profileTextLines(value: unknown, path?: string): string[];
+/** Fewest line insertions plus deletions turning `a` into `b` (Myers' O(ND)
+ * greedy algorithm, which is fast when the texts are close). */
+declare function lineEditDistance(a: readonly string[], b: readonly string[]): number;
+interface LandscapeOptions {
+  /** The split scores come from. Default: the ranked split. */
+  split?: 'selection' | 'train';
+  /** Landmarks of the scaling. Default 32; a search with fewer nodes scales exactly. */
+  landmarks?: number;
+  /** Grid columns and rows. Default 24. */
+  grid?: number;
+  /** Scored nodes the surface is fitted on, evenly spaced in registration
+   * order with the root and the best node always in. Default 400. */
+  surfaceNodes?: number;
+  /** Screened nodes the plateau reads. Default 6. */
+  window?: number;
+  /** Attempts the kernel gives an errored cell. Default 3. */
+  maxAttempts?: number;
+}
+interface LandscapeNode {
+  nodeId: string;
+  ordinal: number;
+  depth: number | null;
+  status: SearchNodeStatus | null;
+  /** The operator of the node's first edge. */
+  operator: string | null;
+  /** Null when the node could not be placed; `unplaced` says why. */
+  x: number | null;
+  y: number | null;
+  unplaced: string | null;
+  /** Improvement over the root on shared units, larger is better; null
+   * without a shared unit. */
+  score: number | null;
+  /** Standard error of `score`: sqrt(pooled variance / pairs); 0 for the
+   * root, null when the pooled variance is unknown. */
+  standardError: number | null;
+  pairs: number;
+  method: SearchEstimateMethod;
+  /** Index into `basins.peaks`; null when unplaced, unscored, or when basins
+   * are insufficient. */
+  basin: number | null;
+}
+interface LandscapeGrid {
+  columns: number;
+  rows: number;
+  x: [number, number];
+  y: [number, number];
+  /** Posterior mean of the improvement over the root, `values[row][column]`;
+   * row 0 is the lowest y. Null where the nodes explain less than half the
+   * prior variance: the surface there is unknown, not flat. */
+  values: (number | null)[][];
+  /** Posterior standard deviation at each cell, supported or not. */
+  sd: number[][];
+  supportedCells: number;
+  /** The kriging model: a constant mean, a squared-exponential covariance of
+   * `priorVariance` and `lengthScale` (in coordinate units), and each node's
+   * own noise variance, pooled variance over its shared units. */
+  model: {
+    mean: number;
+    priorVariance: number;
+    lengthScale: number;
+    /** Log marginal likelihood of the chosen length scale. */
+    logLikelihood: number;
+    /** Log marginal likelihood of the same scores with no spatial
+     * correlation; the surface is drawn only when `logLikelihood` beats it
+     * by 1 or more. */
+    independentLogLikelihood: number;
+    /** Nodes the surface was fitted on (at most `surfaceNodes`). */
+    fitNodes: number;
+  };
+  method: string;
+}
+interface LandscapeBasin {
+  /** The basin's best node: the peak of its component. */
+  peak: {
+    nodeId: string;
+    x: number;
+    y: number;
+    score: number;
+    pairs: number;
+  };
+  /** How far the peak stands above the saddle node where its component first
+   * met a higher one; null for the highest peak and for a component that
+   * never met a higher one (a separate region of the graph). */
+  persistence: number | null;
+  /** The persistence this peak needed: `z` standard errors of the difference
+   * between the peak's and the saddle's scores. Null for the highest peak. */
+  threshold: number | null;
+  saddle: string | null;
+  nodes: number;
+}
+interface LandscapeData {
+  split: 'selection' | 'train';
+  direction: 'maximize' | 'minimize';
+  embedding: {
+    name: string;
+    method: string;
+    landmarks: number;
+    /** Median and largest distance between two landmarks, in the embedding's
+     * own unit (for example lines edited): how far apart the profiles are. */
+    landmarkDistance: {
+      median: number;
+      max: number;
+    } | null;
+    /** Of the scaled landmark matrix, largest first. */
+    eigenvalues: number[];
+    /** Share of the positive eigenvalue mass the two axes hold. */
+    explained: number | null;
+    /** Share of the absolute eigenvalue mass that is negative: how far the
+     * distance departs from a Euclidean one. */
+    negativeMass: number | null;
+    placed: number;
+    unplaced: number;
+  };
+  nodes: LandscapeNode[];
+  /** Parent-to-child segments of every node's lineage. */
+  lineage: Array<{
+    parent: string;
+    child: string;
+    operator: string;
+  }>;
+  grid: LandscapeGrid | null;
+  gridInsufficient: string | null;
+  basins: {
+    count: number | null;
+    /** Neighbours each node joins in the graph the basins are read on. */
+    neighbours: number;
+    /** Nodes with no higher neighbour: the peaks that could each survive. */
+    localMaxima: number;
+    /** Standard errors a peak must clear its saddle by: the Bonferroni
+     * normal quantile over `localMaxima − 1` tests at 5%. */
+    z: number | null;
+    /** Nodes the graph holds (at most 2000 plus the 100 best). */
+    graphNodes: number;
+    /** MDS axes the graph's distances use, and their share of the positive
+     * eigenvalue mass: the neighbours are near in this space. */
+    graphAxes: number;
+    graphExplained: number | null;
+    method: string;
+    insufficient: string | null;
+    peaks: LandscapeBasin[];
+  };
+  plateau: SearchPlateau;
+}
+/**
+ * The landscape of a search: every node placed by `embed`, the interpolated
+ * score over the placement, the basins of that surface, and the plateau
+ * signal. Pure: it reads the state and calls `embed`.
+ */
+declare function landscape(state: SearchStateView, embed?: LandscapeEmbedding, options?: LandscapeOptions): GeometryLensResult<LandscapeData>;
+/**
+ * The symmetric k-nearest-neighbour graph of points in any dimension: each
+ * point joins its k nearest (ties by index) and every edge is kept in both
+ * directions. Brute force, so callers keep n in the low thousands.
+ */
+declare function nearestNeighbours(points: readonly (readonly number[])[], k: number): number[][];
+/** The landscape as text for a terminal or a proposer's context: the same
+ * numbers the view draws, with a coarse shaded map. */
+declare function formatLandscape(lens: GeometryLensResult<LandscapeData>): string;
+//#endregion
+//#region src/search/lenses/meta-search.d.ts
+/** The configuration that ran a search, as its ledger records it. */
+interface SearchPolicyGenome {
+  /** `policy.expansion`: the policy's name with its parameters. A parameter
+   * equal to the search's own seed (`seed=<n>`) reads `seed=<search>`: the
+   * seed varies per search and is not a configuration choice. */
+  expansion: string;
+  /** `policy.allocation`: the allocator's name with its rung sizes. */
+  allocation: string;
+  budget: {
+    maxUsd: number | null;
+    maxCells: number | null;
+    maxNodes: number | null;
+    maxConcurrency: number | null;
+    reservedClaimUsd: number;
+  };
+  /** Every proposer a non-seed edge names, in canonical order. Unknown when
+   * the search recorded no proposal, so its proposer cannot be read. */
+  proposers: Array<{
+    kind: SearchProposerKind;
+    name: string;
+    source: SearchSourceRef;
+  }> | {
+    unknown: string;
+  };
+  /** What ran the candidate-generation operations (a proposer's model, or
+   * deterministic code), in canonical order; unknown with no such operation. */
+  proposerExecution: Array<{
+    kind: 'model';
+    model: SearchModelIdentity;
+  } | {
+    kind: 'deterministic';
+    source: SearchSourceRef;
+  }> | {
+    unknown: string;
+  };
+}
+/** Why a search has no lift to score. */
+type MetaSearchUnscoredReason = 'open' | 'no-claim' | 'claim-mismatch' | 'test-cannot-resolve' | 'no-valid-finalist' | 'insufficient';
+interface MetaSearchSpend {
+  knownUsd: number;
+  /** Proven lower bounds of unknown costs. */
+  floorUsd: number;
+  /** Cells and operations whose cost is unknown. */
+  unknownCost: number;
+}
+/** A search's lift per dollar: a value, a bound when some cost is only a
+ * floor, or unknown. */
+type MetaSearchLiftPerUsd = {
+  status: 'known';
+  value: number;
+  /** The lift's interval divided by the known spend, which is exact. */
+  interval: [number, number] | null;
+} | {
+  status: 'bound';
+  /** The lift divided by the committed spend, a lower bound on the true
+   * spend: the true value lies at or below it for a gain and at or above
+   * it for a loss. */
+  value: number;
+  bound: 'at-most' | 'at-least';
+  reason: string;
+} | {
+  status: 'unknown';
+  reason: string;
+};
+type MetaSearchScore = {
+  status: 'scored';
+  decision: 'ship' | 'hold';
+  /** The node whose held-out lift this is. */
+  nodeId: string;
+  /** The node against the root on the test split. */
+  estimate: NodeEstimate;
+  /** `estimate.delta` oriented so a gain is positive, in the metric's units. */
+  lift: number;
+  /** `estimate.interval`, oriented the same way; null below 6 units. */
+  liftInterval: [number, number] | null;
+  spend: MetaSearchSpend;
+  liftPerUsd: MetaSearchLiftPerUsd;
+} | {
+  status: 'unscored';
+  decision: SearchClaim['decision'] | null;
+  reason: MetaSearchUnscoredReason;
+  detail: string;
+  spend: MetaSearchSpend;
+};
+/** How a search relates to its parent in the forest. */
+type MetaSearchParent = {
+  relation: 'derived';
+  searchId: string;
+  /** The parent's node this search started from. */
+  nodeId: string;
+  /** The parent is among the searches the lens read. */
+  present: boolean;
+} | {
+  relation: 'contained';
+  searchId: string;
+  cellId: string;
+  attempt: number;
+  /** The outer node whose cell ran this search; null when the outer
+   * search was not read. */
+  nodeId: string | null;
+  present: boolean;
+};
+interface MetaSearchEntry {
+  searchId: string;
+  subject: string;
+  objective: {
+    metric: string;
+    direction: 'maximize' | 'minimize';
+  };
+  /** `subject · metric (direction)`: searches are compared only within one. */
+  objectiveKey: string;
+  status: 'open' | 'closed';
+  closeReason: SearchCloseReason | null;
+  genome: SearchPolicyGenome;
+  genomeDigest: SearchLedgerHash;
+  seed: number;
+  rootArtifactDigest: string | null;
+  nodes: number;
+  cells: {
+    settled: number;
+    test: number;
+  };
+  claim: {
+    decision: SearchClaim['decision'];
+    selected: string | null;
+    verification: 'verified' | 'mismatch' | 'unknown';
+    reason: string;
+  } | null;
+  score: MetaSearchScore;
+  parent: MetaSearchParent | null;
+  children: string[];
+  /** Edges from the forest's root; 0 for a root. */
+  depth: number;
+  /** The search's own tree, for a glyph: `[nodeId, primaryParentId, status]`
+   * in registration order, the first `glyphNodes`. */
+  glyph: {
+    nodes: Array<[string, string | null, string | null]>;
+    omitted: number;
+  };
+}
+/** A configuration's lift per known dollar across its scored searches. */
+interface MetaSearchConfigurationEstimate {
+  /** `searches`: the scored searches are the units. `test-units`: one scored
+   * search, so its own test units are. */
+  basis: 'searches' | 'test-units';
+  n: number;
+  value: number | null;
+  method: SearchEstimateMethod;
+  interval: [number, number] | null;
+  /** How the interval was computed; null without one. */
+  intervalMethod: 'percentile-bootstrap-of-mean' | 'paired-delta-test-over-usd' | null;
+}
+interface MetaSearchConfiguration {
+  genomeDigest: SearchLedgerHash;
+  objectiveKey: string;
+  genome: SearchPolicyGenome;
+  searches: string[];
+  decisions: {
+    ship: number;
+    hold: number;
+    'test-cannot-resolve': number;
+    none: number;
+  };
+  /** Searches with a known lift per dollar. */
+  scored: number;
+  /** Searches whose lift per dollar is a bound. */
+  bounded: number;
+  unscored: Partial<Record<MetaSearchUnscoredReason, number>>;
+  estimate: MetaSearchConfigurationEstimate;
+  /** Outer-search nodes whose cells ran this configuration's searches, with
+   * the outer node's parent configuration and its paired estimate against it
+   * on the outer search's ranking split. */
+  outerNodes: Array<{
+    searchId: string;
+    nodeId: string;
+    parentNodeId: string | null;
+    parentGenomeDigest: SearchLedgerHash | null;
+    againstParent: NodeEstimate | null;
+  }>;
+}
+interface MetaSearchData {
+  searches: MetaSearchEntry[];
+  roots: string[];
+  /** Best first: by estimate, then configurations without one. */
+  configurations: MetaSearchConfiguration[];
+  objectives: string[];
+  /** The objective the signal ranks within; null when none could be chosen. */
+  signalObjective: string | null;
+}
+/** The signal: the configuration with the largest estimated lift per known
+ * dollar within one objective, with its interval, its method and its n. */
+interface BestPolicyConfiguration {
+  /** Lift per known dollar of the best configuration; null when none has one. */
+  liftPerUsd: number | null;
+  objectiveKey: string | null;
+  genomeDigest: SearchLedgerHash | null;
+  genome: SearchPolicyGenome | null;
+  interval: [number, number] | null;
+  method: SearchEstimateMethod | null;
+  intervalMethod: MetaSearchConfigurationEstimate['intervalMethod'];
+  basis: MetaSearchConfigurationEstimate['basis'] | null;
+  n: number;
+  /** The configuration's searches, and how many of them have a known lift
+   * per dollar: the rest are unscored or bounded, never counted as 0. */
+  searches: number;
+  scored: number;
+  /** An outer-search node whose artifact runs this configuration, when an
+   * outer search ran it: the runnable configuration a caller derives the next
+   * search from. Null for a configuration only free-standing searches ran. */
+  outerNode: {
+    searchId: string;
+    nodeId: string;
+  } | null;
+  /** Why the value is what it is, including why it is null. */
+  reason: string;
+}
+interface MetaSearchOptions {
+  /** Nodes of each search's own tree carried for its glyph. Default 64. */
+  glyphNodes?: number;
+  /** The objective key the signal ranks within. Default: the one objective
+   * whose searches have a known lift per dollar; with several, the signal is
+   * null until one is named. */
+  objective?: string;
+}
+/** The signal's name, as a policy or a view reads it. */
+declare const META_SEARCH_SIGNAL = "metaSearch.bestPolicyConfiguration";
+/** The per-search score `metaSearchScore` computes. An outer search names it
+ * as its objective's judge. */
+declare const META_SEARCH_SCORE_SOURCE: SearchSourceRef;
+/**
+ * The genome of a search: the configuration its ledger records. Declared
+ * parts come from the header; the proposer comes from what the edges and
+ * candidate-generation operations name, because the header declares none.
+ */
+declare function searchPolicyGenome(state: SearchStateView): SearchPolicyGenome;
+/**
+ * A search's held-out lift per known dollar, from its claim and its test
+ * cells. Pure; it reads the test split, so a policy view (which holds no test
+ * cells) cannot call it; an outer search reads it from a closed inner search.
+ */
+declare function metaSearchScore(state: SearchStateView): MetaSearchScore;
+/** The lens: every search as a node of a search of searches. */
+declare function metaSearch(searches: readonly SearchStateView[], options?: MetaSearchOptions): LensResult<MetaSearchData, BestPolicyConfiguration>;
+/** `subject · metric (direction)`: the key searches are compared within. */
+declare function objectiveKey(header: NonNullable<SearchStateView['header']>): string;
+interface MetaSearchTextOptions {
+  /** Searches listed under each outer node or parent before the rest are
+   * counted. Default 5. */
+  searchesPerGroup?: number;
+}
+/**
+ * The lens as text, for an agent: the signal, every configuration best first
+ * with its coverage and interval, and the forest of searches with contained
+ * searches grouped under the outer node that ran them. `agent-eval search show
+ * --meta` prints it.
+ */
+declare function renderMetaSearchText(result: LensResult<MetaSearchData, BestPolicyConfiguration>, options?: MetaSearchTextOptions): string;
+//#endregion
+//#region src/search/lenses/skill-manifold.d.ts
+interface SkillManifoldOptions {
+  /** The split scores come from. Default: the ranked split. */
+  split?: 'selection' | 'train';
+  /** Largest rank the cross-validation tries. Default 4. */
+  maxRank?: number;
+  /** Cross-validation folds over observed cells. Default 5. */
+  folds?: number;
+  /** Leaders the signal separates. Default 3, the claim's finalist cap. */
+  leaders?: number;
+  /** Explicit leaders, for example an allocator's top of a rung. */
+  candidates?: readonly string[];
+  /** Read only cells settled at or before this ledger sequence, so a caller
+   * can re-derive what the lens said at an earlier point of the ledger. */
+  asOfSequence?: number;
+  /** Ridge penalty on standardized coordinates and loadings. Default 1: the
+   * maximum a posteriori fit under standard-normal priors on both, since
+   * standardized cells have unit variance. Weaker penalties overfit a search
+   * of a few nodes (on a real 9-node ledger, 0.1 made the rank-1 held-out
+   * error 3.5 times the rank-0 error). */
+  ridge?: number;
+  /** Rows the factor fits and the cross-validation read, evenly spaced in
+   * registration order; every row is then placed on the fitted loadings.
+   * Default 1000. */
+  sampleRows?: number;
+  /** Unit loadings from an earlier fit over the same units. When given, the
+   * lens fits no loadings: it places this search's nodes on them. */
+  calibration?: SkillCalibration;
+  /** `linear` factors standardized per-unit means; `logistic` fits the
+   * two-parameter item-response model to pass counts and needs every cell to
+   * score 0 or 1. Default `auto`: logistic when every cell scores 0 or 1. */
+  model?: 'auto' | 'linear' | 'logistic';
+  /** Also choose `count` units greedily from `among` (default: every
+   * modelled unit), updating the leaders' posteriors after each pick, so a
+   * batch does not repeat one direction. Returned as `data.batch`. */
+  batch?: {
+    count: number;
+    among?: readonly string[];
+  };
+}
+/** Unit loadings a later search can place its nodes on (`skillCalibration`). */
+interface SkillCalibration {
+  /** Where the loadings were fitted, for example `searchId@sequence`. */
+  source: string;
+  /** `identity`: the linear model on standardized means; `logit`: the
+   * item-response model on pass counts. */
+  link: SkillLink;
+  /** Standardization of the linear model: z = (score − center) / scale; 0
+   * and 1 under the logit link. */
+  center: number;
+  scale: number;
+  rank: number;
+  ridge: number;
+  /** Cross-validated squared error of one cell, on the standardized scale;
+   * null under the logit link, whose noise is the binomial's. */
+  noiseVariance: number | null;
+  /** Each unit's intercept on the model's scale and its loading. */
+  units: Array<{
+    unitId: string;
+    bias: number;
+    loading: number[];
+  }>;
+}
+type SkillLink = 'identity' | 'logit';
+interface SkillManifoldNode {
+  nodeId: string;
+  ordinal: number;
+  status: SearchNodeStatus | null;
+  /** Units the node scored among the modelled ones. */
+  observed: number;
+  /** Standardized coordinates along each axis; larger is better on axis
+   * orientation (see `SkillManifoldData.axes`). */
+  coordinates: number[];
+  /** The model's mean over every modelled unit, in the metric's units. */
+  predictedMean: number;
+  leader: boolean;
+}
+interface SkillManifoldUnit {
+  unitId: string;
+  /** Nodes that scored the unit (0 for a calibrated unit this search has not run). */
+  observedBy: number;
+  /** The unit's mean for a node at the origin, in the metric's units (a pass
+   * rate under the logit link). */
+  bias: number;
+  /** The same intercept on the model's own scale: standardized under the
+   * identity link, log-odds under the logit link. */
+  intercept: number;
+  /** The unit's direction in skill space (standardized, or log-odds per
+   * unit of coordinate under the logit link). */
+  loading: number[];
+  /** Length of `loading`: how strongly the unit separates nodes. */
+  strength: number;
+}
+interface SkillManifoldNextUnit {
+  unitId: string;
+  /** Expected share of the leaders' contrast variance one more cell on this
+   * unit, on every leader, removes; averaged over leader pairs. */
+  share: number;
+  /** Leaders that already scored the unit. */
+  measuredBy: number;
+}
+interface SkillManifoldData {
+  split: 'selection' | 'train';
+  direction: 'maximize' | 'minimize';
+  /** `fitted`: loadings fitted on this search; `calibrated`: taken from `source`. */
+  mode: 'fitted' | 'calibrated';
+  source: string;
+  matrix: {
+    rows: number;
+    units: number;
+    /** Observed cells of the modelled matrix (per-unit means). */
+    observed: number;
+    density: number | null;
+    /** Nodes left out: fewer than 2 modelled units (1 with a calibration). */
+    excludedNodes: number;
+    /** Units left out: scored by fewer than 2 nodes, or absent from the calibration. */
+    excludedUnits: number;
+    fitRows: number;
+  };
+  model: {
+    method: string;
+    link: SkillLink;
+    rank: number;
+    ridge: number;
+    center: number | null;
+    scale: number | null;
+    iterations: number;
+    converged: boolean;
+  } | null;
+  /** In-sample R² over rank-0 (unit means only), by rank. */
+  explained: {
+    byRank: Array<{
+      rank: number;
+      r2: number;
+    }>;
+    /** Share of the fitted structure each axis carries (its squared singular value). */
+    axisShare: number[];
+    method: string;
+  } | null;
+  intrinsicDimension: {
+    value: number | null;
+    method: string;
+    /** Held-out cells per rank. */
+    n: number;
+    folds: number;
+    curve: Array<{
+      rank: number;
+      error: number;
+      standardError: number;
+    }>;
+    insufficient: string | null;
+  };
+  /** Axis orientation: a positive coordinate is better on the objective. */
+  axes: string;
+  noiseVariance: number | null;
+  nodes: SkillManifoldNode[];
+  units: SkillManifoldUnit[];
+  leaders: Array<{
+    nodeId: string;
+    predictedMean: number;
+    observed: number;
+  }>;
+  nextUnits: SkillManifoldNextUnit[];
+  /** The greedy batch `options.batch` asked for; null when not asked or
+   * when no unit's information is known. */
+  batch: string[] | null;
+  insufficient: string | null;
+}
+/**
+ * The skill manifold of a search at rank `k` (`auto`: the cross-validated
+ * intrinsic dimension, at least 1, and 1 when too few nodes cross-validate).
+ * Pure: it reads the state, and `calibration` when given.
+ */
+declare function skillManifold(state: SearchStateView, k?: number | 'auto', options?: SkillManifoldOptions): GeometryLensResult<SkillManifoldData>;
+/** The loadings of a fitted manifold, for a later search over the same units
+ * to place its nodes on. Null unless cross-validation found at least one skill
+ * axis (intrinsic dimension 1 or more), and, for the linear model, measured
+ * the cell noise: loadings of an axis the held-out cells do not support would
+ * steer allocation by noise. */
+declare function skillCalibration(lens: GeometryLensResult<SkillManifoldData>): SkillCalibration | null;
+/**
+ * The `asha` extension that adds, at each rung, the units that best separate
+ * the leaders: the greedy `nextUnit` batch from `calibration`'s loadings,
+ * with this search's nodes placed on them from the cells the ledger held when
+ * the rung opened. The leaders are the lens's (the top 3 by predicted mean on
+ * every calibrated unit). Where the lens cannot rank (fewer than 2 leaders,
+ * or no measured noise), `asha` fills the rung from its seeded order.
+ */
+declare function nextUnitExtension(calibration: SkillCalibration, options?: {
+  leaders?: number;
+}): SearchUnitExtension;
+/** The manifold as text for a terminal or a proposer's context. */
+declare function formatSkillManifold(lens: GeometryLensResult<SkillManifoldData>): string;
+//#endregion
+//#region src/search/lenses/task-matrix.d.ts
+interface TaskMatrixCell {
+  nodeId: string;
+  unitId: string;
+  /** Mean of the node's scored cells on this unit; absent (not zero) when
+   * the node never scored the unit. */
+  mean: number | null;
+}
+interface TaskMatrixCluster {
+  /** Stable id: the lexicographically first member. */
+  id: string;
+  members: string[];
+}
+interface TaskMatrixSpecialistRow {
+  clusterId: string;
+  unitIds: string[];
+  /** Best node mean minus the mean of node means over the cluster's units,
+   * among nodes that scored at least one of them. Null with fewer than 2
+   * contributing nodes: no spread to measure, never reported as 0. */
+  gain: number | null;
+  nodesContributing: number;
+}
+interface TaskMatrixData {
+  split: 'train' | 'selection';
+  nodeIds: string[];
+  unitIds: string[];
+  nodeClusters: TaskMatrixCluster[];
+  unitClusters: TaskMatrixCluster[];
+  cells: TaskMatrixCell[];
+  specialistGain: TaskMatrixSpecialistRow[];
+}
+interface TaskMatrixOptions {
+  split?: 'train' | 'selection';
+}
+/** unitClusterId → specialist gain; null clusters (fewer than 2 contributing
+ * nodes) are omitted, not zeroed. */
+type TaskMatrixSignal = Record<string, number>;
+declare function taskMatrix(state: SearchStateView, options?: TaskMatrixOptions): {
+  data: TaskMatrixData;
+  signal: {
+    name: string;
+    value: TaskMatrixSignal;
+  };
+};
+//#endregion
+//#region src/search/lenses/tree.d.ts
+interface TreeNode {
+  nodeId: string;
+  status: SearchNodeStatus | null;
+  rung: number | null;
+  /** Edges from the root along primary parents; null when the node's
+   * parents are unknown (an `unknown`-attribution edge, or a derived root). */
+  depth: number | null;
+  cellCount: number;
+  knownCostUsd: number;
+  /** The operator of the edge that registered this node's primary parent;
+   * null for the root and for a node whose parents are unknown. */
+  operator: SearchEdgeOperator | null;
+  children: TreeNode[];
+}
+interface TreeData {
+  /** Normally one entry (the search's root). More than one only when a node
+   * has unknown parents (`primaryParentId === null` but it is not the
+   * root): such a node is shown as its own top-level entry rather than
+   * folded under the root it may or may not descend from. */
+  roots: TreeNode[];
+  nodeCount: number;
+  edgeCount: number;
+}
+declare function tree(state: SearchStateView): {
+  data: TreeData;
+  signal: {
+    name: string;
+    value: number;
+  };
+};
+//#endregion
+//#region src/search/nested-search.d.ts
+/** The outer cell attempt an inner search runs as. */
+type NestedSearchContainment = NonNullable<SearchOpenedEvent['containment']>;
+/** One inner search to run: a configuration on one outer task. */
+interface NestedSearchRunInput<TConfig> {
+  config: TConfig;
+  /** Record this as the inner search's `containment`. */
+  containment: NestedSearchContainment;
+  /** The inner search's id, a digest of `containment`: rerunning the same
+   * attempt opens the same ledger, so an inner search resumes rather than
+   * starting again. */
+  searchId: string;
+  task: {
+    taskId: string;
+    unitId: string;
+    split: SearchSplit;
+    rep: number;
+  };
+  signal: AbortSignal;
+}
+interface RunNestedSearchOptions<TConfig> extends Omit<RunSearchOptions<TConfig>, 'codec' | 'executor'> {
+  /** How configurations are stored as nodes. Default `searchConfigCodec()`,
+   * for plain JSON configurations. */
+  codec?: SearchArtifactCodec<TConfig>;
+  /** How many inner searches run at once, and what one is expected to cost:
+   * `cellUsd` is the admission rule's prior for one inner search. */
+  lane: SearchLane;
+  /** Run the inner search for one outer cell attempt to its close, recording
+   * `containment` in its header, and return its closed state. */
+  runInner(input: NestedSearchRunInput<TConfig>): Promise<SearchStateView>;
+  /** The closed inner search of an attempt an earlier outer process started,
+   * or null to run it through `runInner`. Default null. */
+  adoptInner?(input: NestedSearchRunInput<TConfig>): Promise<SearchStateView | null>;
+}
+/** The deterministic id of the inner search one outer cell attempt runs. */
+declare function nestedSearchId(containment: NestedSearchContainment): string;
+/**
+ * The codec for a plain JSON configuration: the node is the configuration's
+ * canonical JSON, and the diff names each top-level key whose value changed.
+ */
+declare function searchConfigCodec<TConfig>(): SearchArtifactCodec<TConfig>;
+/**
+ * Run an outer search over search configurations to its close, or continue
+ * one from its ledger. The outer search must maximize (its score is lift per
+ * dollar), its nodes must be `runtime-config` artifacts, and its judge must be
+ * `META_SEARCH_SCORE_SOURCE`.
+ */
+declare function runNestedSearch<TConfig>(options: RunNestedSearchOptions<TConfig>): Promise<SearchRunResult>;
+//#endregion
+export { type BestPolicyConfiguration, type DraftOnPlateauOptions, EDIT_CREDIT_ESTIMATOR, EDIT_CREDIT_SIGNAL, EXPANSION_OPERATORS, type EditCreditData, type EditCreditOptions, type EditCreditResult, type EditCreditSignal, type EditGene, type EditGeneVerdict, type EditInteraction, type EditIntroduction, type EditLineageRow, type EditSkillCandidate, type ExpansionOperator, type FrontData, type FrontExtraAxis, type FrontOptions, type FrontRow, type FrontSignal, type GeometryLensResult, type GeometrySignal, type LandscapeBasin, type LandscapeData, type LandscapeEmbedding, type LandscapeGrid, type LandscapeNode, type LandscapeOptions, type LensResult, type LensSignal, META_SEARCH_SCORE_SOURCE, META_SEARCH_SIGNAL, MIN_OUTCOMES_FOR_WEIGHT, type MetaSearchConfiguration, type MetaSearchConfigurationEstimate, type MetaSearchData, type MetaSearchEntry, type MetaSearchLiftPerUsd, type MetaSearchOptions, type MetaSearchParent, type MetaSearchScore, type MetaSearchSpend, type MetaSearchTextOptions, type MetaSearchUnscoredReason, type NestedSearchContainment, type NestedSearchRunInput, type OperatorOutcomeCounts, type OperatorYieldData, type OperatorYieldOptions, type OperatorYieldRow, type OperatorYieldSignal, type RunNestedSearchOptions, type SampleSummary, type SearchPlateau, type SearchPlateauOptions, type SearchPlateauView, type SearchPolicyGenome, type SkillCalibration, type SkillManifoldData, type SkillManifoldNextUnit, type SkillManifoldNode, type SkillManifoldOptions, type SkillManifoldUnit, type TaskMatrixCell, type TaskMatrixCluster, type TaskMatrixData, type TaskMatrixOptions, type TaskMatrixSignal, type TaskMatrixSpecialistRow, type TreeData, type TreeNode, draftOnPlateau, editCredit, editCreditText, formatLandscape, formatSkillManifold, front, landscape, lineEditDistance, lineageEdits, metaSearch, metaSearchScore, nearestNeighbours, nestedSearchId, nextUnitExtension, objectiveKey, operatorYield, profileTextLines, rankingSplit, renderMetaSearchText, runNestedSearch, screenedNodes, searchConfigCodec, searchPlateau, searchPolicyGenome, skillCalibration, skillManifold, summarizeSamples, surfaceDigestEdits, surfaceTextEdits, taskMatrix, tree, vectorEmbedding };
+//# sourceMappingURL=index.d.ts.map