feat(v3): D4 Milestone 1 — cross-doc primitives + node-based helpers (v0.14)

[mbreiser]

What this is

Milestone 1 of D4 (cross-library import) for the v3 Experiment Designer — the
substrate for copying conditions (plus the anchors and plugin declarations they
depend on) from a second parsed YAML.Document into the one you're editing.
M1 is pure logic + Node tests; no UI (UI is Milestone 3).

Per docs/development/v3-d4-implementation-handoff.md §5. Stops at M1 — does not
start M2.

Two commits

1. docs(v3): D4 design rev 3 — applies the rev-2 → rev-3 fix list, then folds
   in the findings from a fresh codex-plan-review (gpt-5.5) pass on rev 3.
2. feat(v3): D4 Milestone 1 — the code + tests + footer bump.

Design: rev 2 → rev 3

Applied the 11-item fix list (v3-d4-design-reviews.md): plugin merge-by-default
when same runtime resource (anchors still namespace); one shared aliasRewriteMap;
visited-set closure; topological anchor insert; commit rewrites the cloned name:;
alias-bound plugin_name block; cross-buffer collision check; fixed sortedJson;
broken-alias hard-block; lock via UI handlers.

Then ran codex-plan-review on rev 3 and addressed the findings (reconciliation +
raw outputs under .codex-review/, gitignored). M1-actionable ones are in this
PR's code; M2/M3 ones are recorded in the design:

• In code now: cloneNodeAcrossDocs rewrites inline anchor definitions (not
  just alias refs); docInsert*Node derive the JS mirror internally; and (my
  finding Codex missed) ensureTopLevelSection splices a created section before
  conditions: — appending after it would put an imported *alias before its
  &anchor and, with verifyAliasOrder: true (the stringify default), toString()
  would throw.
• Recorded for M2/M3: broaden plugin merge identity + rig guard; built-in
  plugin_name: log special-case; walk imported plugin config aliases;
  planned-name collision blocking (incl. empty prefix); commit atomicity
  (snapshot/restore); expanded import-mode locking; no setDirty on enter;
  self-referential-anchor handling in topo sort.

Open questions surfaced (not blocking M1): keep plugin merge-by-default with a
broadened identity vs explicit per-plugin mapping; confirm the "snippet importer"
product contract; import provenance. Proceeding on the handoff's pre-answered
defaults.

Code

New js/v3-import.js (dual-export: ES module + CommonJS + window global):
collectAliasReferences, resolveAlias (via alias.resolve(doc) — last-wins, not
name lookup), cloneNodeAcrossDocs (one shared rewrite map; rewrites alias refs +
inline anchor defs; preserves comments), yamlNodeStructuralEquals, sortedJson
(recursive key sort).

New helpers in js/protocol-yaml-v3.js (exported from ProtocolV3 object +
named export): ensureTopLevelSection, docInsertConditionNode,
docInsertVariableNode, docInsertPluginNode — node-based (preserve comments/
anchors, unlike the JS-object-building docInsertCondition), mirror derived
internally via extractCondition/extractPlugin.

Tests — Milestone 1 gate

Suites N1–N6 (+43 checks) in tests/test-protocol-roundtrip-v3.js + a reusable
tests/fixtures/v3_sibling_source.yaml (scalar + transitive anchors, plugins, an
aliasing condition). Cover: cross-doc clone+rewrite, inline-anchor rewrite, last-wins
resolution, transitive walks, insert into existing and absent variables: (with
a re-parse assertion proving the placement fix), internal mirror derivation, plugin
insert, round-trip stable.

npm test → arena 10/10 · v2 137/137 · v3 510/510  (was 467)

Footer bumped v0.13 → v0.14.

Not in scope (later milestones)

M2 staging buffer + commit pipeline; M3 three-pane UI + locking; M4 polish/docs.

🤖 Generated with Claude Code