Typed ProblemSpecs (Plan 2) + learning-loops run ledger L1 (Plan 3)

[aarontrowbridge]

Two slices of the typed-ProblemSpecs initiative, in one branch because Plan 3 builds directly on Plan 2's hashing.

Green: @amicode/schema 92/92 · @amicode/amico-run 376/376 · extension 769 passed / 6 pre-existing skips. Verified across 4 consecutive full pnpm -r sweeps.

Plan 2 — typed specs reach the TypeScript side

• problemspec schema vendored from the Julia registries, in two variants: the OSS one emitted from Piccolo (c3884122) and the FULL one from private Piccolissimo (9098f6f). Emitting the full variant from Piccolissimo rather than Piccolo is deliberate — a public Piccolo emission would leak private capability names.
• hashing.ts is byte-identical to Julia's Piccolo.Specs.structure_hash/problem_hash, pinned against Julia-emitted sidecar fixtures. This works because JS's Number::toString is the ECMAScript algorithm hashes.jl was hand-built to match — please don't substitute another float formatter on either side.
• solvespec v4: adds problem_spec (oneOf [string, object]), xor with script_path, integer schema_version enum.
• amico-run routes solvespec.problem_spec → Piccolo.Specs.solve_spec.
• ajv ↔ JSONSchema.jl dual-validation on shared fixtures, plus a cross-repo vendoring-drift gate.

Schema-registration gotcha, documented in code: problemspec and ledger-record register in SCHEMAS only, never SUPPORTED_VERSIONS_BY_KIND — both are top-level oneOf shapes with no properties.schema_version, and registering them there crashes the module at load.

Plan 3 — the run ledger (learning loops L1)

Append-only JSONL at ~/.amico/ledger/runs.jsonl. Six record types: solve, verdict, attempt_error, fallback, override, burn. Atomic via PIPE_BUF + O_APPEND, schema-validated on every append.

• amico-run is the single writer. Every extension-side stanza shells amico ledger append; the extension never writes the JSONL. A failed ledger write never fails a run.
• L-A retrieval: medians + IQR over source:"user" solves (excluding both replay and simulated), with "verified" := an agree verdict joined on problem_hash, visible provenance, and a mechanical (n, IQR) → confidence rubric.
• Interim cap: ledger-sourced confidence never reaches high, applied twice. Veloce auto-accepts only high, so without the cap a tight-IQR verified prior would auto-apply the moment L-A shipped, with no per-structure trust gate in place. L-H earns that back.
• E2E acceptance: two runs of one structure with distinct problem_hash and one agree verdict → "n=2 runs, 1 verified" with confidence capped at medium.

One real defect found and fixed here (e164855)

structure_hash covers a problem's type skeleton, not its task — it never includes goal.gate, so a CZ and an X gate on the same system/template/solver hash identically. That's correct for warm-pool routing (the gate doesn't change the Julia type) but wrong for priors: neither the primary nor the fallback retrieval key discriminated the goal, while summary.goal was recorded and even required. A hard CZ's median Q/max_iter were being recommended for a trivially easier X gate.

Fixed in the retrieval key, not the hash — the hash's coarseness is load-bearing for routing and precompilation. Omitting the goal stays legal but the provenance then reads goal not keyed rather than implying a tighter key than was used.

Divergences from the plan, all forced by reality

• @amicode/schema's structureHash is unreachable from amicode_tools.ts — its Bun plugin runtime resolves only relative sibling imports, not bare package specifiers. So structure_hash is read back from the prior run's result.toml (the value settle() already stamped) instead of recomputed. Arguably better: one writer of that hash, no chance of two implementations drifting.
• action:"query" needs ≥1 completed run in a workspace — there's no propose-time spec-assembly pipeline yet. Matches L-A's intent (priors are for a repeat formulation) but worth a human's confirmation.
• attempt_error/fallback had no in-process hook — both happen inside a bash-invoked amico run. Rather than invent one, this adds two bookkeeping tools, amicode_report_attempt_error and amicode_report_fallback, following amicode_recommend's record-what-happened-elsewhere pattern. verdict had a real call site and is wired into amicode_verify. This is new tool surface — a design call, flagged rather than buried.
• platform doesn't exist in problemspec.schema.json, so settle() derives it from system.template (MultiTransmonSystem → multi_transmon). Informational only, but the fallback retrieval key keys on it, so the heuristic is load-bearing there.

Known caveats

• The vendoring-drift HARD gate soft-skips until the Piccolo/Piccolissimo emission commits are pushed, because the sidecar shas are local-only. It auto-hardens once they land (Piccolo side is Piccolo.Specs Phase 1 — declarative ProblemSpec wire format + interpreter (call-surface neutral) Piccolo.jl#258).
• Pre-split hazard: packages/schema registers the FULL problemspec.schema.json as the shipped problemspec kind, with the OSS variant vendored alongside "for package-access staging." Only a comment says which to ship. An OSS extraction that keeps this package as-is would expose six private-only enum values (altissimo backend, continuation/staged strategies, hermite_bending_energy/hermite_c2 objectives, robust wrapper). Harmless today since this repo is private — but it wants a build-time gate before the open-core split ships.
• Piccolo.jl#259 (Phase 1b) changes the OSS schema additively (allOf 4→7). Hash sidecars are unaffected (they hash spec data, not the schema), but both vendored schema variants will need re-staging after it merges.
• amico-run's bundle-and-spawn tests are load-sensitive under pnpm -r: two flakes were observed and then failed to reproduce across 4 consecutive green sweeps (a different test each time, neither touching changed code paths). Pre-existing fragility; will eventually bite CI.

🤖 Generated with Claude Code