Repository navigation
id: design amendment to boards v1 for identity and content-hash contracts (#2054) #6164
Description
Design amendment candidate for #2054, identified while comparing the governing design with the current implementation for #5525. This issue records unresolved protocol contracts; it does not block PR #6158, which only adds signed GamePost metadata.
Decisions needed before changing these existing wire contracts
- Board ID derivation. id: design: ID boards v1 #2054 §1 says derive the stable board ID from (creator signing key, random nonce), but the current ^[[0mBoard.board_id^[[0m is a creator-chosen validated string. Specify the domain separator, nonce bytes/size, derivation and encoding, duplicate behavior, and compatibility for already-published roots.
- Content hashes. ^[[0mboards::ArtifactHash^[[0m is lower-case SHA-256 and is used by attachments/assets; ^[[0mdocuments::DocumentRef^[[0m / Iroh blobs use BLAKE3 plus length verification, while the merged id: PoC: game-post with async turn passing — tic-tac-toe as a board post, signed turns, concession result, save-point fork (from #2053) #2266 PoC package reference uses SHA-256. Specify the hash and size contract per board attachment, theme asset and game package, including verification/migration of existing signed objects.
- Pinned view provenance. id: design: ID boards v1 #2054 invariants 97 and 108 require a saved view to identify configuration, frontier and resolution, but current ^[[0mBoardView^[[0m has no provenance fields and the design does not specify their representation. Decide the smallest reproducible view receipt before adding persistence or relying on saved projections.
Guardrail
Do not silently change hashes or board IDs in implementation. Either record a design amendment in #2054/doc with explicit compatibility rules, or affirm the existing v1 choices and amend the design to match. Related implementation umbrella: #5525.
Acceptance criteria
- Board ID derivation: the contract is decided and recorded in id: design: ID boards v1 #2054/doc — domain separator, nonce size/derivation/encoding, duplicate behavior, and compatibility for already-published roots — or the existing creator-chosen validated string is affirmed as v1 and the design amended to match.
- Content hashes: the hash + size contract per artifact class (board attachment, theme asset, game package) is decided and recorded, including verification/migration of existing signed objects.
- Pinned view provenance: the smallest reproducible view receipt (configuration, frontier, resolution) is specified, or provenance is explicitly deferred with the reason recorded.
- No implementation change silently alters board IDs or hashes before these decisions land (guardrail in the body); PR feat(id): wire signed game posts into board objects (#5525) #6158 remains unblocked throughout.
Metadata
Metadata
Assignees
Labels
Package/app: id (pkgs/ or apps/ in this repo)Medium: expected under 1 day of workA design proposal (design-architect): multi-step, phased, decision-bearingIntake review done: acceptance criteria, links, and normalized labels addedOrdinary priority (the default)Queue task is parked (waiting on CI, time, or an event)Filed directly by a humanQueue or user escalation stateQueue packet kind: verify, reproduce, and route this itemQueue worker lifecycle state
Activity
developing-today commentedon Nov 5, 2026
CODE-1786
dezren39 commentedon Nov 5, 2026
Intake review
developing-today commentedon Nov 5, 2026
🤖 Agent note · handed off
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
dezren39 commentedon Nov 5, 2026
Agent note - handed off
ses_e5e5390b43affeBxmOXPQMZ4Uidezren39 commentedon Nov 5, 2026
Triage — current main (00a294a)
Disposition: still live; keep #6164 open as a design-amendment/decision record. It is not already handled or superseded. No code changes were made.
Evidence and scoped fix path
(creator signing key, random nonce)but leaves the derivation details unstated (design §1). CurrentBoard.board_idis instead a creator-chosen string with only length/character validation (boards.rs, validator). Amend id: design: ID boards v1 #2054 to choose one contract and, if derivation is chosen, specify domain separator, nonce size/encoding, duplicate behavior, and compatibility for already-published roots.ArtifactHashis canonical lower-case SHA-256 (boards.rs);DocumentRefuses BLAKE3 plus a byte length and verifies both (documents.rs, verification). The design amendment needs a per-class hash/size/verification and compatibility rule for attachments, theme assets, and game packages. In particular, existing signed objects cannot be rewritten in place; spell out any additive migration/new-version path. Current main also hasGamePostRefpointing at a same-board Post rather than a dedicated GamePost object; PR feat(id): wire signed game posts into board objects (#5525) #6158 is still open and introduces metadata only.BoardViewreturns the projection without a receipt/provenance field (boards.rs). Specify the smallest reproducible receipt or explicitly defer it with rationale.Blocker and ordering
Resolve these choices in
doc/2026-11-01_design_id2054.md(linked from #2054) before changing serialized board IDs/hash semantics or relying on saved-view provenance. Do not block PR #6158 as scoped; its metadata-only slice must not silently redefine these contracts. Land the amendment/affirmation before unblocking #6160's package/hash-sensitive async-turn work; #6161 follows #6160. #6163 remains separately gated on #5858 and #5679. #6160 is currently blocked and #6161 parked. Keep #6164 open until the design record is updated, then close it as the amendment record.