Proposal G spec: PR-6 (deck portability) + PR-7 (art provenance) designs, docs (design/docs only) - #99
Merged
Conversation
Formalizes what the zero-knowledge, server-unbound crypto design already
implies: export/import of the complete encrypted bundle (no unlock
required for export - it's the same ciphertext the server already
holds), a versioned public format as the actual portability contract, a
standalone decrypt tool as the trust anchor ("if this site vanishes
tomorrow, your decks are still yours"), honest offline-attackability
limits, and an explicit rejection of any server-bound key material.
Nothing built in this commit - the owner's addendum was explicit that
this lands with a later PR-6.
Also updates the doc's stale header status line (still said "BUILDING...
PR1/PR2 opened" from before any of the 5 sequenced PRs had merged) now
that schema+backend (#85), sign-in relocation (#86), the saved-decks API
(#94, recreated after #88's base-deletion auto-close), the crypto module
(#89), and the frontend UI wiring (#93) have all landed on master - and
adds the portability sentence to the legal data-inventory paragraph, per
the addendum's explicit instruction.
Task-end wiki/docs check (CLAUDE.md): this changed what a USER sees (My Decks page, editor Save/breadcrumb, navbar sign-in) - all 5 sequenced PRs (#85, #86, #94, #89, #93) are now merged, so there's real behavior to document. Covers the zero-knowledge crypto mental model, backend endpoints/constants, frontend file map, the still-design-only PR-5/PR-6 addenda, and the owner-only Discord-credentials/legal-review pointers. Added to docs/README.md's flat index. Wiki note (cloud session, per CLAUDE.md convention): the project's GitHub wiki itself (a separate, generated-view target from docs/) likely wants a new "Saved Decks" user-facing page once this feature is visible in production - flagging here rather than editing it directly, since that's the documented cloud-session convention.
Per-slot provenance (driveId, sourceName, sourceType, optional contentPhash, indexedBy) in a future deckPayload version (bumps formatVersion per PR-6's own versioning rule), so an un-indexed slot renders a direct-from-drive thumbnail with a "not in this catalog" badge + origin link instead of breaking. States the moderation-bypass rationale explicitly (user's own private data, client-side fetch, never served/cached by this server) rather than leaving it implicit. XML 2.0 gains three optional, backwards-compatible attributes for third-party phash->federation-verdict joins. Hard line: provenance never enters the federation verdict export, which stays conclusions-only. Addendum clarifications folded in: importing any XML version with un-indexed drive IDs still leaves those slots viewable via the same direct-drive rendering (the badge/link only appear with 2.0+ provenance present); web PDF export of un-indexed slots is explicitly out of scope for PR-7 (v1 answer is view + print-via-desktop-tool guidance, not a foregone-conclusion export fallback). Nothing built - per the owner's explicit instruction, this is spec-only. Also updates docs/features/saved-decks.md's "not yet built" list and the proposal doc's Future-work/header pointers to include PR-7 alongside PR-5/PR-6.
WilfordGrimley
changed the title
…nces The Plans & proposals status table still said HOLD for Proposal G even though the core build has fully shipped (only the PR-5/6/7 addenda remain HOLD) - matches proposal-c's existing PARTIAL precedent for the same shape (some shipped, some still HOLD). Also fixed the features/saved-decks.md summary bullet, which still said "PR-5/PR-6" before PR-7 was added.
Two small fields added to PR-6's encrypted-payload envelope: revision (int, incremented per save) and modifiedAt (timestamp) - private inside the payload like everything else, bumping formatVersion per PR-6/PR-7's shared versioning rule. Purpose: makes an export/import round-trip self-describing (a bundle can be compared against the server's current copy without any server-side plaintext comparison) and seeds any future cross-instance sync with conflict-detection for free. Also adds a "Deck roaming" future-work paragraph after "Deck sharing": cross-instance blob sync is ZK-compatible in principle (only ciphertext would travel, never keys) but is a full protocol in its own right (discovery, consent, conflict surfacing, deletion propagation) - explicitly out of scope until federation has real peers to sync between. Manual export/import (PR-6) is the supported path today; the new revision/modifiedAt fields exist in part to make that manual path safe without committing to automatic sync's unsolved questions. Nothing built - design-only, per the owner's instruction.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Design-only addenda to
docs/proposals/proposal-g-user-accounts-saved-decks.md, per the owner's explicit "design only, nothing built" instructions — no product code in this PR. Also addsdocs/features/saved-decks.mdnow that all 5 sequenced Proposal G PRs (#85, #86, #94, #89, #93) have merged.PR-6: deck portability
Formalizes what the zero-knowledge, server-unbound crypto design already implies rather than adding new capability: export/import of the complete encrypted bundle (no unlock required for export — it's the same ciphertext the server already holds), a versioned public format as the actual portability contract, a standalone decrypt tool as the trust anchor ("if this site vanishes tomorrow, your decks are still yours"), honest offline-attackability limits (identical exposure to what a server breach already carries), and an explicit rejection of any server-bound key material.
Follow-up addendum: two small fields added to the encrypted payload itself —
revision(int, incremented per save) andmodifiedAt(timestamp), private like everything else inside it, bumpingformatVersion. Makes an export/import round-trip self-describing (compare a bundle's copy against the server's current one without any server-side plaintext comparison) and seeds any future cross-instance sync with conflict-detection for free. Also adds a "Deck roaming" future-work paragraph: cross-instance blob sync is ZK-compatible in principle (only ciphertext travels, never keys) but is a full protocol of its own (discovery, consent, conflict surfacing, deletion propagation) — explicitly out of scope until federation has real peers. Manual export/import (PR-6) is the supported path today; the new fields make that path safe.PR-7: art provenance
Per-slot provenance (
driveId,sourceName,sourceType, optionalcontentPhash,indexedBy) in a futuredeckPayloadversion (bumpsformatVersionper PR-6's own versioning rule), so an un-indexed slot renders a direct-from-drive thumbnail with a "not in this catalog" badge + origin link instead of breaking. States the moderation-bypass rationale explicitly (user's own private data, client-side fetch, never served/cached by this server). XML 2.0 gains three optional, backwards-compatible attributes for third-party phash→federation-verdict joins. Hard line: provenance never enters the federation verdict export, which stays conclusions-only. Importing any XML version with un-indexed drive IDs still leaves slots viewable via direct-drive rendering; web PDF export of un-indexed slots is explicitly out of scope for PR-7 (view + print-via-desktop-tool guidance for v1, not a foregone export fallback).Docs
Added
docs/features/saved-decks.md(crypto mental model, backend endpoints/constants, frontend file map, the still-design-only PR-5/6/7 addenda, owner-only pointers) and indexed it indocs/README.md, since all 5 real Proposal G PRs are now merged and there's real, user-facing behavior to document. Updated the proposal doc's stale header status line and Future-work pointers to include all three addenda. Also caught and fixed a real staleness bug:docs/README.md's "Plans & proposals" status table still said HOLD for Proposal G after the core build shipped — changed to PARTIAL (matching the existing proposal-c precedent for the same shape).Wiki note (cloud session, per this repo's CLAUDE.md convention): the project's GitHub wiki itself likely wants a new "Saved Decks" user-facing page now that this feature is live — flagged here rather than edited directly, since editing the wiki isn't something a cloud session does per that convention.
Checklist
pre-commitand installed the hooks withpre-commit installbefore creating any commits.python3 .github/scripts/docs_lint.pyclean on every commit.prettier --checkclean on every commit.Generated by Claude Code