feat: structural parity guard on every write path (#119, #65)

[mmcky]

Closes #119. Closes #65. First item of the P0 corruption-class plan in #120.

What it does

Extracts the structural tokens — fenced-directive openings and (label)= target anchors — from a translation's source and output, and fails the file loudly on divergence. Wired into all three write paths: sync's markdown handler, sync's renamed-file handler, and forward's post-finalization output (so it checks exactly the bytes that would be written).

Every confirmed defect in this class shipped as a success and surfaced weeks later on a downstream strict build. Each one is now a named test:

Defect	Shape	Caught by
#119	{raw} jupyter → {raw}	structural args byte-equal
#65	(label)= anchors dropped	anchor sequence exact
#118	whole document wrapped in a fence	directive count/sequence collapse

The rules were calibrated empirically, not reasoned from the spec

A first draft required byte-equality everywhere. Dry-running it over all 211 source/target lecture pairs across five editions produced 362 false positives in exactly three classes, now admitted as presence-only ("flexible") arguments:

• {admonition}/{prf:*} titles and {contents}/{index} display text — legitimately translated (Contents → 目录 corpus-wide);
• {code-cell}'s kernel tag — editions legitimately pin different kernels (python3 upstream vs ipython3 across lecture-python.zh-cn), and target frontmatter is ground truth by design (forward --github: resync PRs omit state files and heading maps, and corrupt frontmatter-less files #105/fix(forward): complete + reviewable --github PRs, flag-based discovery, localisation as ground truth #108).

A dropped argument still fails even in the flexible classes. Deliberately byte-equal: solution (its arg is a cross-reference label), raw, include/figure/image paths. After calibration: 200 of 211 pairs pass; the remaining 11 are pending-drift artifacts of the current-vs-current dry-run — a comparison the guard never performs in situ, since it checks one run's input against that run's own output.

It found real production damage during calibration

sympy.fr had dropped its (sympy)= anchor — the only clean #65-class hit in the corpus, invisible to -W because nothing references the anchor yet. Restored in lecture-python-programming.fr#16. One guard, one dry-run, one live defect — on the class where the previous eight instances were all found weeks late, downstream.

Scope boundaries, stated

• Top-level tokens only. The scanner is a stateful fence walk: nested directives (inside {tab-set} etc.) and directive syntax quoted in documentation examples are invisible. Both sides use the same walker so blind spots cancel, and all three confirmed defect shapes are top-level. Nested coverage belongs to Work plan: suggested order for the post-review backlog #94 Phase 2's round-trip invariant, not this guard.
• Latent target damage surfaces on next sync. Section-based sync carries unchanged target sections forward; if a file's historical translation already dropped anchors, its next sync fails the guard until repaired. That is loud-by-design (forward resync stripped a MyST directive argument: {raw} jupyter -> {raw} (sir_model, v0.17.0) #119: "fail the file loudly"), and resync is the repair tool — but the first sync wave after this ships may fail files that were already broken, which is the guard doing its job on backlog.
• src/index.ts untouched — the guard lives in src/structural-parity.ts per the Stage-2 rule that guards go in modules Jest can load.

Validation

18 new tests (each defect shape by issue number + the legitimate-translation cases that must not trip), 50 suites / 1,171 passing, all five gates clean, corpus dry-run as above. A harness end-to-end can't easily manufacture a violating model response on demand; the corpus dry-run is the field validation for this one, and the first real sync/resync wave is the live test.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a structural-parity guard to prevent “success-shaped” silent corruption by asserting that key MyST structural tokens (top-level fenced-directive openings and (label)= target anchors) survive translation/resync unchanged, failing loudly when they diverge.

Changes:

• Introduces src/structural-parity.ts to extract/compare structural tokens and format actionable failure messages.
• Wires the guard into sync write paths (normal markdown + renamed-file handling) and the forward resync write path (post-finalization).
• Adds Jest coverage for confirmed defect shapes (#118/#119/#65) and updates dist-action/ output.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/sync-orchestrator.ts	Runs structural parity check after validateMyST() in both standard and renamed-file sync processing paths.
src/structural-parity.ts	Implements token extraction (stateful fence walk), parity comparison, and formatted violations for logs/errors.
src/cli/commands/forward.ts	Runs parity check after finalizeResyncContent() so it validates exact output bytes before writing/PR creation.
src/tests/structural-parity.test.ts	Adds targeted unit tests for known corruption shapes and allowed “flexible arg” cases.
dist-action/index.js	Bundled build output reflecting the new parity guard and call sites.