design_db: a verification-gated library of subcircuit implementations

[plex1]

What this adds

spire.design_db — a content-addressed store of correct implementations of a subcircuit.
Each slot is keyed by its golden specification; implementations enter only through a
verification gate and are selected deterministically at build time. Generation and selection
are fully decoupled: filling a slot once lets every later build pick from it. Generation itself
lives outside spire (RTLScout calls in through the public insert/annotate API; spire never
imports rtlscout).

New folder src/spire/design_db/ plus a spire console script ([project.scripts]) — purely
additive, no existing spire module is touched (19 files, +3485 lines, 0 deletions).

The pieces

• Store — content-addressed slots design_db/v1/<spec_key>/ (spec, golden, verification,
  starting point, admitted designs). Zero-config root resolution: explicit --db →
  $SPIREHDL_DB_PATH → nearest design_db/ upward from cwd → auto-create.
• Insert gate — verify against the slot's frozen verification → structural dedup (AAG) →
  metric-stamp (aig + transistors) → atomic admit (dir rename). A failing candidate
  leaves no trace; a structural duplicate returns deduped=True. Spire designs are first-class
  inserts: the .py source is stored alongside, Verilog stays the interchange form.
• Verification tiers — Tier 0: CEC vs golden (combinational, yosys-abc). Tier 1: auto sim
  harness (corners + seeded random, golden-simulated outputs, frozen tb.sv + vectors).
  Tier 2: authored stimulus (a Python generate(ports, n_vectors, seed) generator; outputs
  always golden-simulated). set-verification (configure + one-shot freeze) is split from
  verify (advisory check) and insert (the gate); frozen verifications are immutable.
• Selection — deterministic and instant, pure functions over the stamped metric vectors:
  objective = area|delay|adp|edap or combinators (constrained, weighted,
  lexicographic), pareto_front, and pin= as a reproducibility lock. Metric systems are
  self-describing (each design's metrics.json maps objective axes per measurement system);
  annotate attaches externally measured systems — e.g. real asap7 PPA — enabling
  metric="asap7" selection. The resolved (selected_id, objective, metric) is recorded in the
  manifest for auditability.
• @from_design_db decorator — trace → auto-register the slot (golden + spec + default
  verification + captured starting point) → select → splice. Miss ⇒ the original logic
  (AAG-identical to the undecorated function, test-asserted), never an error, never spends
  budget. Opt-in fill= hook: called once on a miss as
  fill(spec_key, db_root=…, objective=…, metric=…), with a re-select in the same compile.
  Slot names are permanent (function qualname by default; renames raise).
• Concurrency — the per-slot index is derived from the atomically-admitted design dirs
  (index.json is only a self-healing cache) and manifest writes are fcntl-locked, so
  concurrent inserts — same slot or different slots, threads or processes — can never lose
  designs. Parallel fills of one DB are supported.
• CLI — spire db init|ls|show|insert|seed|verify|set-verification|annotate (also
  python -m spire.design_db).

Trust model, in one line

Producers propose; the gate disposes — nothing enters without passing the slot's frozen
verification, metrics are tooling-stamped, and technology PPA enters only through annotate.

Testing

51 tests in testing/design_db/, all passing; full spire suite green:

• store / gate / dedup fundamentals, CLI round-trips
• selection engine, decorator (incl. miss-path AAG identity and fill-hook fires-once),
  starting-point capture
• sim tiers + freeze semantics (frozen tb reuse, authored-stimulus path)
• python-first inserts (source stored and re-runnable)
• annotate / self-describing metric systems (incl. sibling-consistency guard)
• index derivation: self-healing cache, struct-hash stamping + legacy fallback, and
  three concurrent subprocess inserts into one slot all landing

Downstream, RTLScout's full suite runs against this branch as a submodule (99 passed), including
a composed test where a decorator miss fires a real RTLScout campaign and the same compile
splices the result.

Docs

docs/README_design_db.md — concepts, decorator + filling quick starts, the fill= contract,
selection & metric systems, verification tiers, CLI table, layout on disk.