Skip to content

Freeze the surfacepin-jcs-v2 format; release 1.6.1 - #7

Merged
yellowgram merged 5 commits into
mainfrom
spec-freeze-jcs-v2
Oct 20, 2026
Merged

yellowgram merged 5 commits into
mainfrom
spec-freeze-jcs-v2

Conversation

@yellowgram

Copy link
Copy Markdown
Owner

Freezes the lockfile format at canonicalization surfacepin-jcs-v2 in lockfile v3 and prepares release 1.6.1. No change to behavior, the lockfile format or any digest.

  • SPEC.md §0: format freeze and compatibility promise. Any future need ships as a new, separately named profile. Existing jcs-v1 and jcs-v2 lockfiles stay verifiable. Unknown profiles exit 2.
  • SPEC.md §3.1: exact string rules, and both existing differences from RFC 8785 (a repeated member name keeps its last value; an unpaired surrogate hashes as U+FFFD).
  • Golden fixtures: testdata/golden/jcs-v2/ holds the byte-exact output of SurfacePin 1.6.0 for two surfaces, plus 10 value vectors. Roots, lockfile hashes, input hashes and the hash of golden.json are pinned in the test.
  • Real lockfile v2 from the published surfacepin@1.2.0 (root 21e88a5125e9d687ef27d1fbe4e3259c20a0fd6b0b8a0300d5cc3d5fbb371317). The other jcs-v1 fixture roots are pinned too.
  • Clearer wording for five error messages. Exit codes are unchanged.
  • Version 1.6.1.

Local checks on the head eafea07:

  • 160/160 tests on Node 20, 22 and 24.
  • pack-smoke passes, and the packed CLI reproduces both golden lockfiles byte for byte.
  • The published 1.6.0 writes the same golden lockfiles.
  • gitleaks finds no leaks.
  • Mutation testing (including after regenerating every fixture): every mutant fails by assertion.

Please merge with rebase or a merge commit, not squash, so the five commits stay.

yellowgram added 5 commits October 20, 2026 12:32
SPEC.md now opens with the freeze: jcs-v2 in lockfile v3 is exactly what
SurfacePin 1.6.0 writes and will not change; any future need ships as a new,
separately named profile; existing jcs-v1 and jcs-v2 lockfiles stay
verifiable; unknown profiles are rejected. The spec also states the string
rules exactly, both existing differences from RFC 8785 (repeated member
names keep the last value; unpaired surrogates hash as U+FFFD), the 1.4
change in what jcs-v1 hashes, that the instructions source is transport,
and that new lockfile sections arrive only with a new profile. Internal
shorthand is replaced with plain wording. README links to the promise and
says Node 22+, matching engines.
testdata/golden/jcs-v2 holds the byte-exact canonical bytes, lockfiles and
SHA-256 hashes SurfacePin 1.6.0 writes for two representative surfaces, plus
ten value-level encoding vectors. The test pins the roots, lockfile hashes,
input hashes and the hash of golden.json itself, so regenerating fixtures
cannot hide a change.

testdata/basic.v2.lock.json is a real lockfile v2 written by the published
surfacepin@1.2.0. A new test pins its root and those of the other jcs-v1
fixtures and verifies each through the library and the CLI.
…nknown canonicalization

A lockfile with version "3" (a string) now reports got "3" instead of
got 3, and an unknown profile such as "surfacepin-jcs-v2 " (trailing space)
is shown quoted. Canonical JSON errors name both profiles that share the
encoder. Exit codes and pass/fail are unchanged.
SPEC.md and README.md ship in the npm package, so the package content
changes. Behavior, lockfile format and digests do not.
@yellowgram
yellowgram merged commit 9d843dd into main Oct 20, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant