A document's format and version are read, not just written (#1520) #1575

Closed
jaylouisw wants to merge 1 commit from fix/1116-0054 into main
Owner

Fixes #1520

format and version were written by both the saver and serialize() and compared by nothing: {"format":"bogus"} and {"version":99} both loaded as empty boards, and a saved file stamped version: 99 loaded as if the number meant nothing.

What changed

  • DOCUMENT_FORMAT / DOCUMENT_VERSION and one rule, stampProblem(), live in engine/topology.js; serialize() writes the stamp from those constants.
  • Topology.fromJSON() enforces the rule at the one door every loader goes through: another format is refused, a version above this build's is refused rather than half-read, a version that is not a positive whole number is refused. An unstamped document still loads - every board saved before the rule is one.
  • The server's three copies of the format string (savedDocProblem, documentShapeProblem, saveTopologyNow) now call the same rule, the file header is written from the same constants, and a header that disagrees with the board it wraps is refused with both values named.
  • docs/ARCHITECTURE.md records the rule.

Tests

  • New test/document-version-stamp.test.js (13 assertions), written failing first: 8 of its 13 failed before the change.
  • Full npm test: 258 suites, 9402 assertions, 1 failure - test/spec-vs-description.test.js ("4 device(s) promise ports they do not have"), which fails identically on origin/main with this change stashed, so it is pre-existing and unrelated.
  • node scripts/syntax-check.js: 328 files, all OK.

No new features: this hardens an existing guard and removes three copies of a string.

Fixes #1520 `format` and `version` were written by both the saver and `serialize()` and compared by nothing: `{"format":"bogus"}` and `{"version":99}` both loaded as empty boards, and a saved file stamped `version: 99` loaded as if the number meant nothing. **What changed** - `DOCUMENT_FORMAT` / `DOCUMENT_VERSION` and one rule, `stampProblem()`, live in `engine/topology.js`; `serialize()` writes the stamp from those constants. - `Topology.fromJSON()` enforces the rule at the one door every loader goes through: another `format` is refused, a `version` above this build's is refused rather than half-read, a `version` that is not a positive whole number is refused. An unstamped document still loads - every board saved before the rule is one. - The server's three copies of the format string (`savedDocProblem`, `documentShapeProblem`, `saveTopologyNow`) now call the same rule, the file header is written from the same constants, and a header that disagrees with the board it wraps is refused with both values named. - `docs/ARCHITECTURE.md` records the rule. **Tests** - New `test/document-version-stamp.test.js` (13 assertions), written failing first: 8 of its 13 failed before the change. - Full `npm test`: 258 suites, 9402 assertions, 1 failure - `test/spec-vs-description.test.js` ("4 device(s) promise ports they do not have"), which fails identically on `origin/main` with this change stashed, so it is pre-existing and unrelated. - `node scripts/syntax-check.js`: 328 files, all OK. No new features: this hardens an existing guard and removes three copies of a string.
A document's format and version are read, not just written (#1520)
Some checks failed
CI / Classify the change (pull_request) Successful in 15s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 16s
CI / Test (Node 18) (pull_request) Failing after 3m40s
CI / Test (Node 20) (pull_request) Failing after 3m17s
CI / Server smoke test (pull_request) Successful in 35s
CI / Docker build (pull_request) Successful in 26s
CI / Test (Node 22) (pull_request) Failing after 3m8s
6409471ea6
The stamp was written by both the saver and serialize() and compared by nothing, so a
document stamped version: 99 or format: "bogus" loaded as if the number meant nothing.

- one stamp (DOCUMENT_FORMAT/DOCUMENT_VERSION) and one rule (stampProblem()) in the engine,
  enforced in Topology.fromJSON() so every loader inherits it;
- another format refused, a newer version refused rather than half-read, a non-positive
  or fractional version refused; an unstamped legacy document still loads;
- the server's three copies of the format string now call the same rule, the file header
  is written from the same constants, and a header that disagrees with its board is refused
  with both values named.
Author
Owner

Duplicate of #1575 — needs Jay's decision.

#1570 and #1575 are two independent fixes for the same issue (#1520: read the board document's format/version stamp instead of only writing it). Both are clean against main on their own, but they cannot both land: they rewrite the same lines.

Conflicting hunks (identical regions, different designs):

  • engine/topology.js — the stamp constants and the reader function:
    • #1570: DOC_FORMAT / DOC_VERSION / documentStampProblem(doc), plain Error.
    • #1575: DOCUMENT_FORMAT / DOCUMENT_VERSION / stampProblem(doc, who), err.code = 'E_BAD_DOCUMENT', also exposes Topology.DOCUMENT_FORMAT / Topology.DOCUMENT_VERSION / Topology.stampProblem.
  • engine/topology.js serialize() — format: DOC_FORMAT, version: DOC_VERSION vs format: DOCUMENT_FORMAT, version: DOCUMENT_VERSION.
  • engine/topology.js Topology.fromJSON() — both insert a stamp check at the same line before const topo = new Topology().
  • server/index.js saveTopologyNow() — header takes the pair from require('../engine') (#1570) vs from Topology.* (#1575).
  • server/index.js savedDocProblem() — #1570 checks envelope then board; #1575 additionally refuses a file whose header version and board version disagree, and prefixes errors with the file header: / its board:.
  • server/index.js documentShapeProblem() — same line, same replacement.
  • docs/ARCHITECTURE.md — different wording for the same paragraph.
  • Test files differ and do not overlap: test/document-stamp.test.js (200 lines, #1570) vs test/document-version-stamp.test.js (89 lines, #1575).

Only #1570 also touches CHANGELOG.md.

Recommendation: land #1570 first (earlier, larger test file, has the CHANGELOG entry), then let #1575 rebase and keep only the part that #1570 lacks — the header/board version-mismatch refusal and the E_BAD_DOCUMENT code. The alternative (land #1575, close #1570) loses the CHANGELOG entry and the 200-line test file.

Verified: neither was merged. Both rebase onto 0af8f64f with only these overlapping regions; each PR's own suites were not re-run here because a rebase of either one invalidates the other's diff.

needs Jay's decision — which stamp design ships, and whether the loser's tests are folded in.

**Duplicate of #1575 — needs Jay's decision.** #1570 and #1575 are two independent fixes for the same issue (#1520: read the board document's format/version stamp instead of only writing it). Both are clean against main on their own, but they cannot both land: they rewrite the same lines. Conflicting hunks (identical regions, different designs): - `engine/topology.js` — the stamp constants and the reader function: - #1570: `DOC_FORMAT` / `DOC_VERSION` / `documentStampProblem(doc)`, plain `Error`. - #1575: `DOCUMENT_FORMAT` / `DOCUMENT_VERSION` / `stampProblem(doc, who)`, `err.code = 'E_BAD_DOCUMENT'`, also exposes `Topology.DOCUMENT_FORMAT` / `Topology.DOCUMENT_VERSION` / `Topology.stampProblem`. - `engine/topology.js` `serialize()` — `format: DOC_FORMAT, version: DOC_VERSION` vs `format: DOCUMENT_FORMAT, version: DOCUMENT_VERSION`. - `engine/topology.js` `Topology.fromJSON()` — both insert a stamp check at the same line before `const topo = new Topology()`. - `server/index.js` `saveTopologyNow()` — header takes the pair from `require('../engine')` (#1570) vs from `Topology.*` (#1575). - `server/index.js` `savedDocProblem()` — #1570 checks envelope then board; #1575 additionally refuses a file whose header version and board version disagree, and prefixes errors with `the file header:` / `its board:`. - `server/index.js` `documentShapeProblem()` — same line, same replacement. - `docs/ARCHITECTURE.md` — different wording for the same paragraph. - Test files differ and do not overlap: `test/document-stamp.test.js` (200 lines, #1570) vs `test/document-version-stamp.test.js` (89 lines, #1575). Only #1570 also touches `CHANGELOG.md`. **Recommendation:** land #1570 first (earlier, larger test file, has the CHANGELOG entry), then let #1575 rebase and keep only the part that #1570 lacks — the header/board version-mismatch refusal and the `E_BAD_DOCUMENT` code. The alternative (land #1575, close #1570) loses the CHANGELOG entry and the 200-line test file. Verified: neither was merged. Both rebase onto `0af8f64f` with only these overlapping regions; each PR's own suites were not re-run here because a rebase of either one invalidates the other's diff. needs Jay's decision — which stamp design ships, and whether the loser's tests are folded in.
Author
Owner

Superseded — closing. #1570 landed on main as abda4f0d ("Read the board document's format/version stamp instead of only writing it (#1520)"), so #1520 is fixed on main and this branch would re-implement it on top of it: same three source files, same hunks (the serialize() stamp literal, the head of Topology.fromJSON(), the saveTopologyNow() header, savedDocProblem() and documentShapeProblem() in server/index.js, and the same docs/ARCHITECTURE.md paragraph).

What main now has (abda4f0d): DOC_FORMAT / DOC_VERSION / documentStampProblem(doc) in engine/topology.js, re-exported through engine/index.js, used by serialize(), fromJSON(), saveTopologyNow(), savedDocProblem() and documentShapeProblem(); legacy documents with no stamp still load; test/document-stamp.test.js (200 lines) covers it.

What this branch has that main does not, and what is therefore worth a separate PR or issue if it is wanted:

  1. a typed error, err.code = 'E_BAD_DOCUMENT', on the fromJSON() refusal;
  2. a saved file whose header version and board version disagree is refused with both values named (the file header says version X but its board says version Y);
  3. the constants are reachable from the class as Topology.DOCUMENT_FORMAT / Topology.DOCUMENT_VERSION.

None of those change behaviour main already relies on, so folding them in later is additive. Closing rather than rebasing because the change is already on main and a rebase here would produce a 5-file diff that duplicates abda4f0d line for line.

**Superseded — closing.** #1570 landed on main as `abda4f0d` ("Read the board document's format/version stamp instead of only writing it (#1520)"), so #1520 is fixed on main and this branch would re-implement it on top of it: same three source files, same hunks (the `serialize()` stamp literal, the head of `Topology.fromJSON()`, the `saveTopologyNow()` header, `savedDocProblem()` and `documentShapeProblem()` in `server/index.js`, and the same `docs/ARCHITECTURE.md` paragraph). What main now has (`abda4f0d`): `DOC_FORMAT` / `DOC_VERSION` / `documentStampProblem(doc)` in `engine/topology.js`, re-exported through `engine/index.js`, used by `serialize()`, `fromJSON()`, `saveTopologyNow()`, `savedDocProblem()` and `documentShapeProblem()`; legacy documents with no stamp still load; `test/document-stamp.test.js` (200 lines) covers it. What this branch has that main does **not**, and what is therefore worth a separate PR or issue if it is wanted: 1. a typed error, `err.code = 'E_BAD_DOCUMENT'`, on the `fromJSON()` refusal; 2. a saved file whose header version and board version disagree is refused with both values named (`the file header says version X but its board says version Y`); 3. the constants are reachable from the class as `Topology.DOCUMENT_FORMAT` / `Topology.DOCUMENT_VERSION`. None of those change behaviour main already relies on, so folding them in later is additive. Closing rather than rebasing because the change is already on main and a rebase here would produce a 5-file diff that duplicates `abda4f0d` line for line.
jaylouisw closed this pull request 2026-11-16 01:51:54 +00:00
Author
Owner

This branch conflicts with main, so it was not rebased:

docs/ARCHITECTURE.md engine/index.js engine/topology.js server/index.js test/document-version-stamp.test.js 

A conflict is a decision about behaviour rather than a mechanical fix, so this is left for a human. Rebasing by hand and force-pushing will let the automation pick it up again.

This branch conflicts with `main`, so it was not rebased: ``` docs/ARCHITECTURE.md engine/index.js engine/topology.js server/index.js test/document-version-stamp.test.js ``` A conflict is a decision about behaviour rather than a mechanical fix, so this is left for a human. Rebasing by hand and force-pushing will let the automation pick it up again.
Some checks failed
CI / Classify the change (pull_request) Successful in 15s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 16s
CI / Test (Node 18) (pull_request) Failing after 3m40s
CI / Test (Node 20) (pull_request) Failing after 3m17s
CI / Server smoke test (pull_request) Successful in 35s
CI / Docker build (pull_request) Successful in 26s
CI / Test (Node 22) (pull_request) Failing after 3m8s

Pull request closed

Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1575
No description provided.