Skip to content

docs(specs): align stale spec references with the code - #113

Open
xgreenx wants to merge 8 commits into
mainfrom
specs/stale-references
Open

xgreenx wants to merge 8 commits into
mainfrom
specs/stale-references

Conversation

@xgreenx

@xgreenx xgreenx commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

The spec contradicted the contracts, the popup package or itself in nine places. No REQ id is minted.

Changes

  • Chain Profile duties: add fee path, fee unit and rejection rollback (REQ-COMMON-34B, -42) to the definition, §2 table, REQ-CHAIN-01, TEST-CHAIN-01 and the libid.md owner table. EVM answers them in new §3.5 (chain-profiles.md:139): msg.value in wei, exact match, revert.
  • Handle vectors: name handles.json v1 (44 vectors; max 15/39/62 bytes) and the outer 0x20 trim before the @ strip (platform-ceremonies.md:177).
  • X identity path: /users/me becomes /2/users/me (platform-ceremonies.md:760).
  • SP-DELIVERY-01 added to both §12 enforced lists.
  • Roles: §11 adds Deployment and Verifier Governance Process, and notes Prover. §2 defines the Deployment as the OAuth Bridge operator, who chooses the enabled Identity Platforms (ceremony-common.md:135).
  • References: WHATWG URL, FIPS 180-4, Keccak-256 (not SHA3-256) (ceremony-common.md:1580).
  • Verified result: libid.md:74 lists all eight REQ-COMMON-05E fields.
  • REQ-POPUP-CONTROL-04A: rejects a closed handle. With no handle it performs no browser operation and resolves, as connection.ts:467-483 does. TEST-POPUP-07 now matches.
  • Popup provenance: headings now match the docs, and the table adds REQ-POPUP-CONTROL-08.

Verified

  • lint_spec.py specs/*.md: main 79 errors / 99 warnings, branch 79 / 97, no new finding kinds.
  • Each constant was checked against the code: CeremonyProfile.sol:57, HandleNormalizer.sol, NotaryService.sol:108, CeremonyProofVerifier.sol:117, connection.test.ts:693-711.
  • External links return 200; handles.json is identical at v0.17.0 and main.

Not verified / known issues

  • §3.5 constrains only a Consumer that lets the revert propagate. No REQ forbids a Consumer from catching it.

🤖 Generated with Claude Code

REQ-COMMON-34B and REQ-COMMON-42 make each Chain Profile define the
native value-transfer path, the fee unit, and how a rejected call leaves
no value moved, but the profile duty list and the EVM profile stopped at
four duties. The EVM profile now answers them as the contracts do: call
value in wei, exact at every hop, and a revert that unwinds the path.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
The handle profile pointed at a vector table it never named. It is
version 1 of handles.json in libid-contracts, and that table and every
normalizer trim outer 0x20 bytes before the @ strip, a step the criteria
prose left out.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
The common rules bind the Deployment and the Verifier Governance Process
with MUSTs, yet §11 named neither and §2 never defined the Deployment.
Both §12 lists left out SP-DELIVERY-01, which REQ-COMMON-29..31 and the
platform delivery rules uphold. §13 omitted the URL serializer, SHA-256
and Keccak-256, the last easy to confuse with SHA3-256.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
REQ-PLAT-32B called the X identity session /users/me while the rest of
the spec and the pinned request line use /2/users/me. The overview named
three of the eight fields REQ-COMMON-05E returns.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
REQ-POPUP-CONTROL-04A both rejected an absent handle and let a pending
native-anchor binding point the anchor. The package rejects a closed
handle and, with binding pending, points the anchor and resolves, as its
docs and tests say; the requirement and TEST-POPUP-07 now say so too.
The provenance table cited connection.md headings that do not exist and
had no row for REQ-POPUP-CONTROL-08.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
No REQ forbids a Consumer from catching the Proof Verifier's revert, so
§3.5 now states the no-state-change outcome for a Consumer that lets it
propagate. The Notary Service receives the fee rather than passing it.
The §1 scope and the libid.md owner table still named only the four
committed-value duties.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
The OAuth Bridge configures one registration per enabled platform and no
version list; the Application takes the versions from the Distribution's
versions.json. The Deployment therefore chooses which Identity Platforms
new ceremonies may use, and withdraws a failing profile by disabling its
platform.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
A blocked PopupWindow.open leaves no handle and no anchor to bind.
connection.ts treats every handle-less state alike: it points the anchor
when one still dispatches and resolves, which connection.test.ts checks
with a blocked handle and no anchor. REQ-POPUP-CONTROL-04A now keys on
the absent handle. The DELIVER provenance row cited a message-port.md
heading by a shortened name.

Assisted-by: Claude Opus 5.5
Signed-off-by: xgreenx <xgreenx9999@gmail.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://specs-stale-references.previews.lib.id, https://specs-stale-references-libid.grounded-systems.workers.dev (commit 0e41ed4)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://9f8c698b.previews.lib.id, https://9f8c698b-libid.grounded-systems.workers.dev 0e41ed4 2026-10-05T13:38:09.259Z Visit the dashboard ↗

This branch has not been deployed

No deployments
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