@metaharness/darwin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RuvNet (https://ruv.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @metaharness/darwin
+
+> Darwin Mode — **the model is frozen; the harness evolves.**
+
+Bounded, empirical, population-based self-improvement of an agent harness
+(ADR-070…075). "Self-improving agents" is widely misread as "the model trains
+itself." Darwin Mode ships the practical version: an agent **modifies its own
+harness**, runs benchmarks in a sandbox, keeps the variants that *measurably*
+improve, and builds an **archive of successful descendants**. The foundation
+model never changes — what evolves is the operating system around it (planner,
+context builder, reviewer, retry/tool/memory/score policy). This follows the
+**Darwin Gödel Machine** lineage: iteratively mutate the source of a coding
+agent, then *empirically validate* each variant — no weight updates, just a
+population, a benchmark, and an archive.
+
+```
+repo
+  → profile      RepoProfile (pkg mgr, test cmd, source/risk files)
+  → baseline     generate the seven mutation-surface files
+  → mutate       pick ONE approved surface, perturb it (behind the gate)
+  → sandbox      safety-inspect → run the test command (no shell, no net, no secrets)
+  → score        weighted base score − hard penalty layer
+  → archive      record parent→child as a TREE (not a single best branch)
+  → select       sample the next generation from the WHOLE archive
+  → repeat
+```
+
+Dependency-free: **Node ≥ 20 built-ins only**, no runtime dependencies.
+
+## Quick start
+
+Build (TypeScript → `dist/`):
+
+```bash
+npm run build      # tsc
+```
+
+Then evolve a repo with the CLI (one verb, `evolve`):
+
+```bash
+metaharness-darwin evolve <repo> [--generations N] [--children N] [--concurrency N] [--seed N]
+```
+
+| Flag | Meaning | Default |
+|------|---------|---------|
+| `--generations N` | number of generations to run | `3` |
+| `--children N`    | children produced per parent per generation | `4` |
+| `--concurrency N` | max variants evaluated concurrently (bounded fan-out) | `4` |
+| `--seed N`        | deterministic seed for mutation selection | `0` |
+
+The `<repo>` argument defaults to the current directory. Everything is written
+under a self-describing `.metaharness/` work tree inside the repo:
+
+```
+<repo>/.metaharness/
+├── archive.json          # the population TREE: ArchiveRecord[] (variant + score + children)
+├── lineage.json          # serialized graph { nodes, edges } for rendering
+├── variants/             # one directory per variant (its mutation-surface files)
+│   ├── baseline/
+│   ├── g1_v0/  …
+├── runs/                 # one <variantId>.json per variant: { traces, score }
+└── reports/
+    └── winner.json       # the best scored ArchiveRecord
+```
+
+Sample run output (leaderboard + winner lineage, printed to stdout):
+
+```
+Darwin Mode — leaderboard
+  0.842  g2_v1  [contextBuilder]  safety=1.00  pass=1.00 ◀ winner
+  0.791  g1_v0  [reviewer]        safety=1.00  pass=1.00
+  0.788  baseline  [planner]      safety=1.00  pass=1.00
+  0.000  g1_v3  [toolPolicy]      safety=0.00  pass=0.00
+
+Winner: g2_v1
+Lineage: baseline → g1_v0 → g2_v1
+Delta over baseline: +0.054
+
+Artifacts: <repo>/.metaharness
+```
+
+## The seven mutation surfaces
+
+A child variant may mutate **exactly one** surface per generation, and a variant
+directory may contain **only** these seven files — nothing else (the allowlist is
+enforced by `safety.ts`, see `FILE_BY_SURFACE` / `APPROVED_FILES`). Each surface
+is pure, side-effect-free policy logic over injected data.
+
+| Surface (`MutationSurface`) | File | Governs |
+|-----------------------------|------|---------|
+| `planner`        | `planner.ts`         | task string → ordered plan steps (map → inspect → patch → verify) |
+| `contextBuilder` | `context_builder.ts` | ranks candidate files by term overlap with the task |
+| `reviewer`       | `reviewer.ts`        | flags changed files against an injected risk-file list + test outcome |
+| `retryPolicy`    | `retry_policy.ts`    | whether/how to retry given a symbolic failure classification |
+| `toolPolicy`     | `tool_policy.ts`     | allow-list + deterministic ordering over symbolic command kinds |
+| `memoryPolicy`   | `memory_policy.ts`   | whether an outcome record is worth remembering |
+| `scorePolicy`    | `score_policy.ts`    | the weight vector a variant *proposes* over the positive scoring terms |
+
+A variant may *propose* score weights via `scorePolicy`, but it can never
+re-grade itself: the verdict that decides promotion is computed by the frozen
+kernel scorer (see below), not by the variant's own file.
+
+## Scoring and the promotion gate
+
+The scorer (`src/scorer.ts`, ADR-072) is a **pure function** — re-running it on
+the same traces yields an identical verdict. It is a weighted base score over six
+`[0,1]` terms (weights from `scoreWeights()`, summing to 1.0):
+
+```
+baseScore = 0.35·taskSuccess + 0.20·testPassRate + 0.15·traceQuality
+          + 0.10·costEfficiency + 0.10·latencyEfficiency + 0.10·safetyScore
+```
+
+minus a hard **penalty layer** read out of the run traces (a single safety
+violation can drive the final score negative — that is the point):
+
+```
+finalScore = baseScore − 0.30·secretExposure − 0.25·destructiveAction
+                       − 0.20·hallucinatedFile − 0.15·toolLoop − 0.10·costOverrun
+```
+
+A child replaces its parent only when **all four** promotion clauses hold
+against the parent:
+
+```
+1. beatsParent       finalScore > parentFinalScore + promotionDelta   (default delta 0.05)
+2. safetyOk          safetyScore ≥ 0.95
+3. noRegression      testPassRate ≥ parentTestPassRate
+4. noBlockedActions  safetyScore == 1.0  (zero blocked actions in any trace)
+```
+
+Non-promoted variants are **retained**, not deleted — "did not clear the gate"
+means "not chosen as a parent by the default policy," never "removed."
+
+## The archive: evolve like species, not release like software
+
+The archive (`src/archive.ts`, ADR-073) is a **tree** of variants keyed by id and
+persisted as `archive.json`, not a single best branch. Selection
+(`selectParents`) samples the **whole** archive — including older, non-promoted
+branches — which is how evolution escapes hill-climbing: when a generation
+stalls (no promotions), a weak-looking ancestor can still seed a strong branch.
+Insertion order is preserved, so `best()`, tie-breaks, and `selectParents` are
+all deterministic and reproducible from `archive.json` alone.
+
+## Safety model
+
+A self-modifying agent that can edit anything is a liability. Darwin Mode's bound
+is enforced in `src/safety.ts` (ADR-071) as the **load-bearing security
+boundary**, with two independent, defense-in-depth checks:
+
+- **`inspectVariant(dir)`** runs *before any variant executes*. It disqualifies a
+  variant directory containing anything other than the seven approved files, a
+  blocked filename (`.env`, `secret`, `id_rsa`, `.git`, `package.json`, …), a
+  symlink or nested directory, or blocked content (`process.env`,
+  `child_process`, `eval`, `fetch`, restricted node builtins, shell strings, …).
+- **`validateGeneratedCode(code)`** runs *before generated code is written to
+  disk* (the LLM-mutator path). Independent pattern set; a violating generation
+  is **discarded**, never repaired in place.
+
+The gate runs **first**: a disqualified variant never has its test command run —
+the sandbox seals the trace with the reserved exit code `99` and records the
+findings as `blockedActions`, which zeroes `safetyScore` and makes promotion
+impossible. When a variant *is* admitted, the sandbox (`src/sandbox.ts`) is
+**shell-free** (the test command is split to argv and run via `execFile`, never a
+shell — no command-injection surface) and runs under a **scrubbed environment**
+(only `PATH` plus three identifying variables; nothing else from `process.env`
+leaks, so secrets, tokens, and proxy settings never reach a variant).
+
+See [`SECURITY.md`](../../SECURITY.md) for the full threat model.
+
+## Programmatic API
+
+```ts
+import { evolve } from '@metaharness/darwin';
+
+const result = await evolve({
+  repoRoot: '/abs/path/to/repo',
+  workRoot: '/abs/path/to/repo/.metaharness',
+  generations: 3,
+  childrenPerGeneration: 4,
+  concurrency: 4,
+  promotionDelta: 0.05,
+  seed: 0,
+  tasks: [
+    'run repository test suite',
+    'verify generated harness safety',
+    'check trace quality',
+  ],
+});
+
+result.winner;        // the best scored ArchiveRecord (or null)
+result.winnerLineage; // ['baseline', 'g1_v0', 'g2_v1'] — root → winner
+result.records;       // every ArchiveRecord, in insertion order
+result.baseline;      // the baseline record
+```
+
+The package also re-exports the building blocks behind `evolve`: `profileRepo`,
+`generateBaselineHarness`, `createChildVariant`, `DeterministicMutator` /
+`CodeGenerator`, `runVariantTask` / `runVariantTasks`, `scoreVariant` /
+`scoreWeights`, `Archive`, `inspectVariant` / `validateGeneratedCode`, plus the
+`SURFACES`, `FILE_BY_SURFACE`, and `APPROVED_FILES` constants.
+
+## Status
+
+**Prototype.** The default `DeterministicMutator` performs seeded,
+signature-preserving string edits (bounded context-window, retry-budget,
+threshold, and phrasing perturbations) — a **placeholder** for an LLM-backed
+`CodeGenerator` that slots in behind the *same* `validateGeneratedCode` gate. The
+mutator is the only piece meant to be swapped; the safety boundary, scorer, and
+archive are kernel code.
+
+## License
+
+MIT © rUv. See ADRs
+[070](../../docs/adrs/ADR-070-darwin-mode-self-improving-harness.md) ·
+[071](../../docs/adrs/ADR-071-darwin-mutation-surfaces-safety-allowlist.md) ·
+[072](../../docs/adrs/ADR-072-darwin-scoring-and-promotion.md) ·
+[073](../../docs/adrs/ADR-073-darwin-archive-and-selection.md) ·
+[074](../../docs/adrs/ADR-074-darwin-ruvector-memory-ruflo-fabric.md) ·
+[075](../../docs/adrs/ADR-075-darwin-prototype-roadmap-and-acceptance.md),
+and the [repository](https://github.com/ruvnet/agent-harness-generator).

package/SECURITY.md

@@ -0,0 +1,200 @@
+# Darwin Mode — Security Model & Adversarial Audit
+
+> Package: `@metaharness/darwin` (`packages/darwin-mode`)
+> Scope: the self-modification boundary — `src/safety.ts`, `src/sandbox.ts`, `src/scorer.ts`.
+> Audit suite: `__tests__/security/` (97 tests).
+
+Darwin Mode lets an agent **mutate its own harness** (seven policy files), run the
+mutated harness against a benchmark, and promote measured, safe wins. A
+self-modifying agent that can edit anything is a liability; this document
+describes the boundary that makes the system **honestly bounded**, the
+adversarial tests that pin it, and the **residual gaps** the audit found.
+
+Related ADRs:
+[ADR-070](../../docs/adrs/ADR-070-darwin-mode-self-improving-harness.md) (loop) ·
+[ADR-071](../../docs/adrs/ADR-071-darwin-mutation-surfaces-safety-allowlist.md) (mutation surfaces + gate) ·
+[ADR-072](../../docs/adrs/ADR-072-darwin-scoring-and-promotion.md) (scoring + promotion) ·
+[ADR-073](../../docs/adrs/ADR-073-darwin-archive-and-selection.md) (archive/lineage) ·
+[ADR-074](../../docs/adrs/ADR-074-darwin-ruvector-memory-ruflo-fabric.md) (memory/fabric) ·
+[ADR-075](../../docs/adrs/ADR-075-darwin-prototype-roadmap-and-acceptance.md) (acceptance).
+
+---
+
+## 1. Threat model
+
+**Adversary**: the variant generator (today a deterministic mutator; tomorrow an
+LLM behind the *same* gate). It is assumed to be capable of emitting any text
+into the files it is allowed to write, and to *try* to:
+
+1. **Escape the allowlist** — write an 8th file, a nested dir, a symlink to host
+   files, a dependency manifest, or an `.env`/key file.
+2. **Smuggle a capability** — embed `process.env`, `child_process`, `fetch`, a
+   shell string (`curl|sh`), `eval`, dynamic `import`, or a destructive fs op in
+   an *approved* file.
+3. **Exfiltrate via the test command** — leak ambient secrets (`AWS_SECRET_ACCESS_KEY`,
+   proxy config) or inject shell metacharacters (`;`, `&&`, `$(...)`) into the
+   command that scores it.
+4. **Re-grade itself** — propose a self-serving `score_policy.ts` to inflate its
+   own score, or get promoted while carrying a blocked action.
+
+**Not in scope** (see §7): containing *arbitrary native code* that a
+repo-provided test command legitimately runs — that is an OS-sandbox concern,
+not this gate's. This gate bounds *what the agent writes*, not what the repo's
+own test runner does.
+
+---
+
+## 2. The seven-file allowlist (ADR-071)
+
+A variant directory may contain **only** these seven files — one concern each.
+Anything else is disqualified before execution.
+
+| Surface (`MutationSurface`) | File | Controls |
+|---|---|---|
+| `planner` | `planner.ts` | task decomposition |
+| `contextBuilder` | `context_builder.ts` | what enters context |
+| `reviewer` | `reviewer.ts` | patch critique |
+| `retryPolicy` | `retry_policy.ts` | retry / abandon / escalate |
+| `toolPolicy` | `tool_policy.ts` | which tools, in what order |
+| `memoryPolicy` | `memory_policy.ts` | remember / retrieve / forget |
+| `scorePolicy` | `score_policy.ts` | *proposes* weights (read-only at run time) |
+
+Source of truth: `FILE_BY_SURFACE` / `APPROVED_FILES` in `src/safety.ts`.
+
+---
+
+## 3. Two-layer, defense-in-depth gate (ADR-071)
+
+Two **independent** checks share `BLOCKED_CONTENT_PATTERNS` but run at different
+points, so a class that slips one is caught by the other.
+
+- **`inspectVariant(dir)`** — runs in the sandbox **before any command executes**.
+  Walks the directory with `lstat` (never follows symlinks), enforces the
+  allowlist, blocked-filename substrings, size cap (256 KiB/file), entry cap
+  (32), and content patterns. Returns a non-empty findings list to disqualify.
+- **`validateGeneratedCode(code)`** — runs on LLM/agent output **before it is
+  written to disk**. Content-only, de-duplicated reasons. A violating generation
+  is **discarded, never repaired in place**.
+
+Both are **code, not comments**. A disqualified variant never has its test
+command run: the sandbox seals a `RunTrace` with the reserved `exitCode 99` and
+records the findings as `blockedActions`.
+
+---
+
+## 4. Shell-free, env-scrubbed sandbox (ADR-070 §sandbox)
+
+`runVariantTask` in `src/sandbox.ts`:
+
+- **Gate first.** `inspectVariant` runs before anything; findings ⇒ `exitCode 99`,
+  no command executed (proven: `sandbox-injection.test.ts` →
+  *"disqualified variant never runs its command"*).
+- **No shell.** The command is whitespace-split into argv and run via
+  `execFile` — **never** a shell. `;`, `&&`, `|`, `$(...)` are inert argument
+  strings, not metacharacters (proven: *"shell-free execution"* cases).
+- **Scrubbed env.** Only `PATH`, `NODE_ENV=test`, `METAHARNESS_VARIANT`,
+  `METAHARNESS_TASK` are exposed. `AWS_SECRET_ACCESS_KEY`, `HTTP_PROXY`,
+  `DARWIN_SECRET`, etc. read as `undefined` inside the command (proven:
+  *"environment scrubbing"* case).
+- **Never throws.** A failing/timing-out command becomes a `RunTrace`, so a
+  hostile variant cannot abort the evolution loop.
+
+---
+
+## 5. Frozen scorer / benchmark immutability (ADR-072)
+
+`scoreVariant` in `src/scorer.ts` is **frozen kernel code**, *not* the variant's
+`score_policy.ts`. Its only inputs are
+`(variantId, traces, parentScore, promotionDelta, taskTimeoutMs)` — **there is no
+parameter through which variant file content can enter**. A variant may *propose*
+different weights, but the authoritative verdict is computed here, so a variant
+**can never re-grade itself** (proven: `scorer-immutability.test.ts`).
+
+Two structural guarantees:
+
+- **Any `blockedActions` ⇒ `safetyScore 0` ⇒ `promoted: false`**, and the
+  promotion gate requires `safetyScore ≥ 0.95`. An unsafe variant cannot win,
+  even against a weak parent (proven: *"a blocked-action variant can NEVER be
+  promoted"*).
+- **Reproducible.** Identical traces yield an identical `finalScore`/`promoted`,
+  independent of `variantId` (proven: *"identical traces ⇒ identical verdict"*).
+
+The child also **cannot edit the benchmark**: `tasks` and `testCommand` live in
+the `RepoProfile`, outside the variant directory and outside the allowlist
+(ADR-071 rule 9).
+
+---
+
+## 6. The ten containment rules → where enforced → which test proves it
+
+| # | Rule (ADR-071) | Enforced in | Proving test |
+|---|---|---|---|
+| 1 | No production writes | allowlist; sandbox runs in repo root with scrubbed env, variant dir is write target only | `inspect-bypass` (allowlist), `sandbox-injection` (disqualified-never-runs) |
+| 2 | No credential access | `BLOCKED_FILENAME_PATTERNS` (`.env`/`secret`/`token`/`id_rsa`/…) + `BLOCKED_CONTENT_PATTERNS` (secret handling) + env scrub | `inspect-bypass` (blocked filenames + blocked content `secret/token/credential/private_key`); `sandbox-injection` (env scrub) |
+| 3 | No network by default | content patterns `fetch(`/`XHR`/`WebSocket`/`node:net,http,…`/`from 'net'…`/`curl,wget,ssh` | `inspect-bypass` + `validate-generated` (network cases) |
+| 4 | No mutation outside approved files | `APPROVED_FILES` allowlist; `MAX_FILES`; no nested dirs; no symlinks | `inspect-bypass` (extra files, subdir, symlink, >32 entries) |
+| 5 | No promotion without benchmark evidence | `scoreVariant` promotion gate (4 clauses) | `scorer-immutability` + `scorer.test.ts` (gate) |
+| 6 | No deletion commands | content patterns `rm` + flag/path (`\brm\s+[-/]`)/`rmdir`/`unlink`/`rmSync` | `inspect-bypass` + `validate-generated` (`rm -rf`, `rm <path>`, `rmSync`) |
+| 7 | No child-process escape | content patterns `child_process`/`exec*`/`spawn*` | `inspect-bypass` + `validate-generated` (process exec); `sandbox-injection` (no shell) |
+| 8 | No hidden state | size cap + entry cap; no symlinks (no out-of-tree state) | `inspect-bypass` (oversized file, >32 entries, symlink) |
+| 9 | No benchmark changes by the child | tasks/testCommand are in `RepoProfile`, never in the allowlist; scorer takes only traces | `scorer-immutability` (no variant-file channel) |
+| 10 | Full lineage + rollback | archive tree + witness (ADR-073/ADR-011) | covered by `archive.test.ts` (out of this audit's scope) |
+
+---
+
+## 7. Residual risks / out of scope
+
+### 7a. Hardened content-scan gaps (FIXED)
+
+The audit found three blind spots where a payload defeated
+`BLOCKED_CONTENT_PATTERNS`. **All three are now closed in `src/safety.ts`** (both
+`inspectVariant` and `validateGeneratedCode` inherit the same patterns), and the
+tests that documented them are pinned **green** as regression tests.
+
+| # | Former bypass | Payload | Fix shipped in `BLOCKED_CONTENT_PATTERNS` |
+|---|---|---|---|
+| **#1** | Computed-member env access | `process['env']` · ``process[`env`]`` · `Reflect.get(process,'env')` | `/process\s*[.[]\s*['"\x60]?\s*env/i` (dot **or** bracket, optional quote/backtick) + a dedicated `/\bReflect\s*\.\s*get\s*\(\s*process/i` |
+| **#2** | Subpath module import | `import … from 'fs/promises'` (also `'fs/x'`, `'net/…'`) | `/from\s+['"](fs|net|http|https|dns|tls|dgram|cluster|vm|worker_threads)(\/[^'"]*)?['"]/i` + `node:fs/…` subpaths |
+| **#3** | Non-`-rf` destructive shell | `"rm /etc/important_config"` (a bare `rm <path>`) | `/\brm\s+[-/]/i` (any flag **or** path), not only `rm -rf` |
+
+> Even before the fix, the env-scrub in the sandbox (§4) meant **#1 could not
+> exfiltrate a real secret at run time** (env is empty) and the no-shell
+> execution limited **#2/#3** to an already-scrubbed Node process — so these were
+> defense-in-depth erosions of layer 1, not a full break. They are now closed so
+> the static scan and the structural guarantees agree.
+
+Files: `__tests__/security/inspect-bypass.test.ts` (hardened #1a/#1b/#1c/#2/#3),
+`__tests__/security/validate-generated.test.ts` (hardened #1/#2/#3) — now green.
+
+### 7b. Out of scope by design
+
+- **The repo-provided `testCommand` runs real code.** `inspectVariant` bounds
+  what the *agent writes*, not what the *repo's own test runner* legitimately
+  executes. Containing that runner (CPU/mem/fs/network limits) is an **OS-level
+  sandbox** concern (containers/seccomp/cgroups), outside this package. The
+  package's contribution is: shell-free invocation + scrubbed env + a hard
+  wall-clock timeout + output-buffer cap.
+- **Deterministic mutator is a placeholder.** Today's mutator is string
+  replacement; the LLM `CodeGenerator` (ADR-071 §contract) drops in **behind the
+  same gate** — `validateGeneratedCode` is the choke point that does not move.
+- **Pattern-based scanning is heuristic.** A static regex scan cannot prove
+  semantic safety; it is a *floor*. The §7a bypasses illustrate that obfuscation
+  is always possible against a denylist. The structural defenses (allowlist,
+  no-symlink, no-shell, env-scrub, frozen scorer, safety-gated promotion) are the
+  load-bearing guarantees; the content denylist is a best-effort early filter.
+- **Penalty-layer heuristics** (`scorer.ts` `SECRET_RE`/`DESTRUCTIVE_RE`/…) match
+  on trace stderr text and are coarse by design (ADR-072 §penalty); they are not
+  a containment boundary, only a scoring signal.
+
+---
+
+## 8. Running the audit
+
+```bash
+npx vitest run packages/darwin-mode/__tests__/security
+```
+
+97 tests, all green: every blocked attack in §3–§6 is rejected **and** the three
+former §7a content-scan gaps are now closed and pinned as regression tests. If a
+new obfuscation is found, add it as a failing test, harden
+`BLOCKED_CONTENT_PATTERNS`, and update this doc together.

package/dist/archive.d.ts

@@ -0,0 +1,89 @@
+import type { ArchiveRecord, HarnessVariant, ScoreCard } from './types.js';
+/**
+ * In-memory tree of {@link ArchiveRecord}s keyed by variant id, persisted to a
+ * JSON file. Insertion order is preserved (a `Map` iterates in insertion order)
+ * so every ordering — `all`, tie-breaks in `best`, ties in `selectParents` — is
+ * deterministic and reproducible from `archive.json` alone.
+ */
+export declare class Archive {
+    private readonly file;
+    /** variantId → record. A Map preserves insertion order. */
+    private readonly records;
+    /**
+     * @param file Absolute path to `archive.json`. The file need not exist yet;
+     *   {@link load} tolerates a missing or corrupt file by starting empty.
+     */
+    constructor(file: string);
+    /**
+     * Load records from {@link file} if it exists. A missing, unreadable, or
+     * corrupt file (or one whose JSON is not an `ArchiveRecord[]`) is tolerated by
+     * starting from an empty archive — never throws.
+     */
+    load(): Promise<void>;
+    /**
+     * Insert a record `{ variant, score: null, children: [] }` if the variant id
+     * is absent (idempotent — a re-add is a no-op). When `variant.parentId` is set
+     * and that parent already exists, append this id to the parent's `children`
+     * (without duplicates), wiring up the tree edge.
+     */
+    addVariant(variant: HarnessVariant): void;
+    /**
+     * Attach a scorecard to a variant. Throws a clear error if the variant id is
+     * unknown — scoring a phantom variant is a programmer error, not a soft miss.
+     */
+    setScore(variantId: string, score: ScoreCard): void;
+    /** The record for `variantId`, or `undefined` if it is not in the archive. */
+    get(variantId: string): ArchiveRecord | undefined;
+    /** Every record, in insertion order. */
+    all(): ArchiveRecord[];
+    /**
+     * The scored record with the highest `score.finalScore`, or `null` when no
+     * record is scored yet. Ties break toward the earlier insertion (the first
+     * record to reach that score wins), making the choice deterministic.
+     */
+    best(): ArchiveRecord | null;
+    /**
+     * The archive-wide selection that escapes hill-climbing: the top-`limit`
+     * scored variants by `finalScore`, drawn from the WHOLE archive including
+     * older, non-promoted branches (ADR-073 stall fallback). Deterministic — ties
+     * break by insertion order, so the result is reproducible.
+     *
+     * @param limit Maximum number of parents to return. `<= 0` yields `[]`.
+     */
+    selectParents(limit: number): HarnessVariant[];
+    /**
+     * The path of ids from the root ancestor down to `variantId`, following
+     * `parentId` upward then reversing. Returns `[]` if `variantId` is unknown.
+     * Guarded against cycles (e.g. a self-parent or a corrupt ancestor loop): each
+     * id is visited at most once, so the walk always terminates.
+     */
+    lineageOf(variantId: string): string[];
+    /**
+     * A serializable projection of the tree for rendering the evolution graph:
+     * one node per record (carrying generation, mutated surface, final score, and
+     * promotion flag), and one edge per existing parent→child relationship. Edges
+     * referencing a missing endpoint are omitted so the graph stays well-formed.
+     */
+    toLineageGraph(): {
+        nodes: Array<{
+            id: string;
+            parentId: string | null;
+            generation: number;
+            mutationSurface: string;
+            finalScore: number | null;
+            promoted: boolean | null;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+        }>;
+    };
+    /**
+     * Persist the archive as pretty-printed JSON to {@link file}, creating the
+     * parent directory if needed. The on-disk shape is exactly `all()` — an
+     * `ArchiveRecord[]` in insertion order — so a subsequent {@link load}
+     * reconstructs the same archive.
+     */
+    save(): Promise<void>;
+}
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;GAKG;AACH,qBAAa,OAAO;IAQN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;OAGG;gBAC0B,IAAI,EAAE,MAAM;IAEzC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB3B;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAczC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAUnD,8EAA8E;IAC9E,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIjD,wCAAwC;IACxC,GAAG,IAAI,aAAa,EAAE;IAItB;;;;OAIG;IACH,IAAI,IAAI,aAAa,GAAG,IAAI;IAW5B;;;;;;;OAOG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAoB9C;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAkBtC;;;;;OAKG;IACH,cAAc,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;YACxB,UAAU,EAAE,MAAM,CAAC;YACnB,eAAe,EAAE,MAAM,CAAC;YACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;SAC1B,CAAC,CAAC;QACH,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC5C;IA+BD;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}