Read the board document's format/version stamp instead of only writing it (#1520) #1570

Merged
jaylouisw merged 1 commit from fix/1116-0006 into main 2026-11-16 01:43:29 +00:00
Owner

Fixes #1520

format and version were written in two hand-copied places (engine/topology.js serialize() and server/index.js's file envelope) and read by nothing. Topology.fromJSON({format:'lab', version:99, devices:[], links:[]}) built a board without a word, so a document that said it was another format, or a generation this build has never heard of, loaded silently. A guard that looks like a guard and is none.

What changed:

  • DOC_FORMAT / DOC_VERSION are the single pair of constants; both writers use them.
  • documentStampProblem(doc) reads the stamp. Every door asks it: Topology.fromJSON() (throws), the saved-file reader, and POST /load (400 E_BAD_DOCUMENT).
  • Refusals name both what the document claimed and what this build reads, e.g. this document was written by a newer PacketForge (version 99); this build reads version 1 and older.
  • A document with no stamp still loads - that is every file written before the check - so old boards are unaffected.
  • docs/ARCHITECTURE.md says what is now read; CHANGELOG entry added under Unreleased/Fixed.

Tests (test/document-stamp.test.js, 31 assertions): the stamp written equals the stamp read; a wrong format, a newer version, a string version, version 0 and a negative version are each refused with a message naming what it said; a stamp-less document and the current version still load; the server neither restates the literal nor skips the check; and over HTTP a version-2 document is a 400 while a stamp-less one and a current one are 200.

Gates: node scripts/syntax-check.js 328 files OK; full npm test 258 suites / 9418 assertions, 1 failure that is pre-existing on origin/main (spec-vs-description: the four edgecore/AS4610-* specs claim 2x 20G QSFP+ they do not have, from #1555 - verified by running that suite on a clean origin/main worktree).

Fixes #1520 `format` and `version` were written in two hand-copied places (`engine/topology.js` `serialize()` and `server/index.js`'s file envelope) and read by nothing. `Topology.fromJSON({format:'lab', version:99, devices:[], links:[]})` built a board without a word, so a document that said it was another format, or a generation this build has never heard of, loaded silently. A guard that looks like a guard and is none. What changed: - `DOC_FORMAT` / `DOC_VERSION` are the single pair of constants; both writers use them. - `documentStampProblem(doc)` reads the stamp. Every door asks it: `Topology.fromJSON()` (throws), the saved-file reader, and `POST /load` (400 `E_BAD_DOCUMENT`). - Refusals name both what the document claimed and what this build reads, e.g. `this document was written by a newer PacketForge (version 99); this build reads version 1 and older`. - A document with **no** stamp still loads - that is every file written before the check - so old boards are unaffected. - `docs/ARCHITECTURE.md` says what is now read; CHANGELOG entry added under Unreleased/Fixed. Tests (`test/document-stamp.test.js`, 31 assertions): the stamp written equals the stamp read; a wrong format, a newer version, a string version, version 0 and a negative version are each refused with a message naming what it said; a stamp-less document and the current version still load; the server neither restates the literal nor skips the check; and over HTTP a version-2 document is a 400 while a stamp-less one and a current one are 200. Gates: `node scripts/syntax-check.js` 328 files OK; full `npm test` 258 suites / 9418 assertions, 1 failure that is pre-existing on `origin/main` (`spec-vs-description`: the four `edgecore/AS4610-*` specs claim 2x 20G QSFP+ they do not have, from #1555 - verified by running that suite on a clean `origin/main` worktree).
Read the board document's format/version stamp instead of only writing it (#1520)
Some checks failed
CI / Classify the change (pull_request) Successful in 19s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 20) (pull_request) Failing after 3m17s
CI / Test (Node 18) (pull_request) Failing after 3m30s
CI / Server smoke test (pull_request) Successful in 38s
CI / Docker build (pull_request) Successful in 24s
CI / Test (Node 22) (pull_request) Failing after 3m21s
5a99dc66f4
The stamp was written twice - serialize() and the server's file envelope, two
hand-copied literals - and read by nothing: fromJSON() turned
{format:'lab', version:99} into a board with no complaint, so the version
guard everyone would assume exists was decoration.

One pair of constants (DOC_FORMAT, DOC_VERSION) and one reader
(documentStampProblem()). The engine loader throws on a stamp it cannot read,
and the saved-file reader and POST /load answer 400 / a load refusal through
the same function, naming what the document claimed and what this build reads.
A document with no stamp still loads: that is every file written before the
check existed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-16 01:43:18 +00:00
jaylouisw force-pushed fix/1116-0006 from 5a99dc66f4
Some checks failed
CI / Classify the change (pull_request) Successful in 19s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 19s
CI / Test (Node 20) (pull_request) Failing after 3m17s
CI / Test (Node 18) (pull_request) Failing after 3m30s
CI / Server smoke test (pull_request) Successful in 38s
CI / Docker build (pull_request) Successful in 24s
CI / Test (Node 22) (pull_request) Failing after 3m21s
to 9cf0333604
Some checks failed
CI / Classify the change (pull_request) Successful in 17s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 23s
CI / Docker build (pull_request) Failing after 12m47s
CI / Server smoke test (pull_request) Failing after 12m54s
CI / Test (Node 22) (pull_request) Failing after 13m5s
CI / Test (Node 20) (pull_request) Failing after 13m8s
CI / Test (Node 18) (pull_request) Failing after 13m18s
2026-11-16 01:43:20 +00:00
Compare
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.
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!1570
No description provided.