D. Compatibility Report

What must keep working, what may change, and what the change costs.

D.1 Corpus compatibility — can existing ROS research be used unchanged?

Answer: yes, and it must be.

OBSERVED: every construct in the corpus is machine-readable today; the current engine simply declines to read most of it. Nothing in the corpus is malformed in a way that requires editing:

• 117 authored docs: 116 have YAML front matter, 1 does not (archived duplicate)
• 49/49 authored IDs unique; 520/520 frontier IDs unique; zero collisions
• 878 canonical relationship instances resolve
• 9 dangling references — legitimate research states, to be warned not fixed

The required change is entirely in the parser, per §1.2. Specifically vNext must read, without any file edits:

Target: zero manual migrations. Any valid existing artifact that vNext cannot represent is a design defect (§1.2).

D.2 URL compatibility

OBSERVED current scheme:

/research/<slug>/                ~700 pages
/collections/<facet>/<value>/    175 pages

The uncomfortable finding

slug = slugify(id ? ${id}-${title} : title).

For the 68 of 117 authored documents with no id, the URL is a function of the title. These URLs are already unstable: any retitling silently breaks them, and has presumably done so historically.

INFERENCE: "preserve existing URLs" is therefore a weaker obligation than it first appears. There is no guarantee that today's URLs match yesterday's for the majority of documents.

Proposed compatibility posture

Emit a redirects.json (and GitHub Pages-compatible HTML redirect stubs) mapping every currently published URL to its vNext canonical URL. Build should fail if a previously published URL disappears without a redirect entry (see L, regression tests).

D.3 Machine-readable contract compatibility

OBSERVED current published contracts:

INFERENCE: no external consumer is demonstrable from the repositories inspected. The architecture document (Hypothesis 6) asserts the catalog is "a first-class artifact and should remain versioned", which is a stated intent rather than an observed dependency.

PROPOSAL: keep emitting research-catalog.json at schemaVersion: 1.1 with its current record shape for one release as a compatibility shim, while publishing the new bounded contracts (see K) alongside. Retire it only after a release in which nothing reports breakage.

Note the defect to not carry forward: the current catalog inlines 4.0 MB of rendered HTML into a 6.3 MB metadata file. The vNext contract must separate metadata from content.

D.4 ROS contract compatibility

DOCUMENTED ROS RULE: ROS owns ros.json, registries/, .ros/, schemas/, and the work protocol. The publisher must not write into any of them.

OBSERVED: the current publisher does not read ROS at all — no registry, no ros.json, no .ros/. vNext should read ros.json (for canonicalRoots and project identity) and the registries (as an authoritative artifact list), but must remain read-only with respect to ROS state.

OBSERVED constraint: the VE research corpus lives under content/projects/**, which is outside the canonical roots ROS declares in research-publisher's own ros.json (research/journals, research/packages, research/theories, research/evidence). vNext cannot assume ROS canonical roots locate the corpus; discovery must stay configuration-driven.

D.5 Build and deployment compatibility

OBSERVED: GitHub Actions → GitHub Pages; dist/ committed to the repository (1,776 tracked files).

Constraints vNext inherits:

• Static hosting only; no server-side request handling.
• GitHub Pages serves /path/ → /path/index.html; no rewrite rules, so client-side routing needs a 404 fallback (one already exists: dist/404.html).
• A committed dist/ means build output diffs land in review. vNext should keep output deterministic so diffs are meaningful — the current build stamps generatedOn, which the vNext contract should move out of content-addressed files.

D.6 What must remain stable — summary