scholarr: implement the frozen data-model schema #8

New issue

Open

opened 2026-08-20 11:32:25 +02:00 by justinzeus · 0 comments

justinzeus commented

2026-08-20 11:32:25 +02:00

Owner

Charter: runbooks/rewrite/charter.md

Goal

The docs/specs/data-model.md schema exists as real SQLite migrations in the Go backend, matching the frozen spec exactly.

Constraints

BLOCKED, and Forgejo holds the block. This issue carries real dependencies on justinzeus/scholarr#1 through justinzeus/scholarr#7, the seven owner decisions D1 to D7. Forgejo refuses to close an issue with open dependencies, so the charter's rule that "no implementation starts before the spec is owner-frozen" is enforced by the tracker rather than by convention. Do not remove a dependency to get moving; answer the decision.
The freeze is not just the seven answers: the owner must also approve any resulting spec edits and mark the spec frozen. An implementation started against an answered-but-unfrozen spec is the same mistake in a different coat.
Card C.2 and every later build card are also downstream of the freeze. This issue is the first thing that may start after it, not a parallel track.
Doctrine that binds the schema, from the charter: SQLite only, and the write path must fit a serialized-writer design from the very first migration; FollowedAuthor is the source-agnostic root entity; publications are global and deduplicated, follows and read state are per user; merges are audited and undoable; names are never identity keys; no row or workflow may permit application-initiated Google network contact.
The spec's own storage conventions are binding: internal INTEGER PRIMARY KEY joins, immutable UUIDv7 public_id on externally-referenced rows (subject to D1), UTC Unix-millisecond INTEGER timestamps, INTEGER NOT NULL CHECK (value IN (0, 1)) booleans, row_version on mutable rows for undo conflict checks, and closed-set CHECK constraints only where the value set will not grow.
A CHECK-encoded invariant cannot be altered in place. SQLite requires a guarded create-copy-verify-swap rebuild. Decide deliberately which invariants are worth that cost before writing the first migration.
runbooks/rewrite/testing-strategy.md governs the test obligations and release gates for this card.
The 22 numbered falsifiable acceptance tests rewritten during the review are the acceptance surface, not a suggestion.

Acceptance

All seven decision issues are closed and the spec is marked frozen by the owner
Migrations create every table in the frozen spec, with the invariants placed where the spec says (table CHECK versus application code)
The 22 numbered acceptance tests from the spec pass
The serialized-writer contract is exercised by a concurrency test, not just asserted in a comment
No code path in the migration or model layer can reach a Google endpoint

Next action

Nothing here. Move justinzeus/scholarr#1 through justinzeus/scholarr#7; this issue unblocks itself when they close.

Charter: runbooks/rewrite/charter.md ## Goal The `docs/specs/data-model.md` schema exists as real SQLite migrations in the Go backend, matching the frozen spec exactly. ## Constraints - **BLOCKED, and Forgejo holds the block.** This issue carries real dependencies on justinzeus/scholarr#1 through justinzeus/scholarr#7, the seven owner decisions `D1` to `D7`. Forgejo refuses to close an issue with open dependencies, so the charter's rule that "no implementation starts before the spec is owner-frozen" is enforced by the tracker rather than by convention. Do not remove a dependency to get moving; answer the decision. - The freeze is not just the seven answers: the owner must also approve any resulting spec edits and mark the spec frozen. An implementation started against an answered-but-unfrozen spec is the same mistake in a different coat. - Card C.2 and every later build card are also downstream of the freeze. This issue is the first thing that may start after it, not a parallel track. - Doctrine that binds the schema, from the charter: **SQLite only**, and the write path must fit a **serialized-writer** design from the very first migration; **`FollowedAuthor`** is the source-agnostic root entity; publications are **global and deduplicated**, follows and read state are **per user**; merges are **audited and undoable**; names are never identity keys; **no row or workflow may permit application-initiated Google network contact**. - The spec's own storage conventions are binding: internal `INTEGER PRIMARY KEY` joins, immutable UUIDv7 `public_id` on externally-referenced rows (subject to `D1`), UTC Unix-millisecond `INTEGER` timestamps, `INTEGER NOT NULL CHECK (value IN (0, 1))` booleans, `row_version` on mutable rows for undo conflict checks, and closed-set `CHECK` constraints only where the value set will not grow. - **A CHECK-encoded invariant cannot be altered in place.** SQLite requires a guarded create-copy-verify-swap rebuild. Decide deliberately which invariants are worth that cost before writing the first migration. - `runbooks/rewrite/testing-strategy.md` governs the test obligations and release gates for this card. - The 22 numbered falsifiable acceptance tests rewritten during the review are the acceptance surface, not a suggestion. ## Acceptance - [ ] All seven decision issues are closed and the spec is marked frozen by the owner - [ ] Migrations create every table in the frozen spec, with the invariants placed where the spec says (table `CHECK` versus application code) - [ ] The 22 numbered acceptance tests from the spec pass - [ ] The serialized-writer contract is exercised by a concurrency test, not just asserted in a comment - [ ] No code path in the migration or model layer can reach a Google endpoint ## Next action Nothing here. Move justinzeus/scholarr#1 through justinzeus/scholarr#7; this issue unblocks itself when they close.