docs(specs): document the packument _rev contract in S11

João Pereirarequested to merge
jdrpereira/s11-spec-packument-rev into main

Context

S11's Deprecate and unpublish flows section pins {rev} to the latest active npm_versions.id and states the packument generator returns that value as _rev. But the Packument generation section — the one plan Step 25 was scoped from, "verbatim" — never enumerates the full packument's top-level fields, so _rev emission was never scoped to any step and the generator shipped without it. The npm CLI builds every unpublish URL from ._rev, so both real-client flows (npm unpublish <pkg>@<version> and --force) currently send .../-rev/undefined and die with 400 rev_invalid.

What this MR does

  • Packument generation: enumerate the full form's top-level fields (_id, _rev, name, dist-tags, versions, plus the per-version _id), define _rev as the latest active npm_versions.id (omitted when no active version exists), and cross-reference the unpublish flows so the two sections cannot drift apart again. Notes that _rev preserves cached-blob determinism (row-derived, not wall clock).
  • Acceptance criteria: append one item pinning _rev emission (appended, not inserted — AC numbers are cited by code comments and the plan's mapping table).
  • Stale {rev} shape: two sentences still described the pre-UUIDv7 decimal/int64 token; both now say "does not parse as a UUID", matching the implementation.
  • Plan Step 25: one line added to the unit-suite enumeration for the _rev assertion.

The implementation fix (generator emits _rev, with unit tests and a real-npm-CLI validation) follows in a separate MR.

Related to #143 (closed)

Merge request reports