CLUE-550 Stage 2: Class-wide slots + get-or-create via pointer

[scytacki]

CLUE-550 Stage 2 — Class-wide slots + get-or-create via pointer

Stage 2 of the class-wide collaborative documents work. It makes the app auto-create a class-wide collaborative document — the Driving Question Board (DQB) is the default slot — exactly once per class per unit, server-race-free, reusing the CLUE-524 canonical-pointer engine. There is no UI yet (Sort Work sectioning, titling, presentation, and editing are Stage 3); this PR creates the documents but shows nothing.

Builds on the concurrent/kind axes and kind registry from Stage 1 (base branch CLUE-550-concurrent-kind-axes). The target architecture and per-axis status live in docs/document-axes/README.md (this PR flips the roadmap's creation-factory row to in progress and extends the canonical row to class+unit).

How a class-wide document is modeled

It is the same generic collaborative document as a group doc, differentiated only by orthogonal fields — no new document type:

Concern	Value
Behavior (concurrent history, non-owner editable)	concurrent: true (Stage-1 axis)
Identity	kind (e.g. drivingQuestionBoard), registered with metadataFields: { concurrent: true }
Scope	context_id (classHash) + unit; no offeringId/groupId
Pointer slot	canonical: <kind> (label = kind)
Legacy type tag	type: "group" (transitional, Stages 1–3)
RTDB owner	class-scoped synthetic uid class_<classHash> (mirrors group docs' group_<offeringId>_<groupId>)

Because it carries concurrent: true and type: "group", Stage-1's behavior wiring (concurrent history manager, non-owner write-sync, class-wide read) already applies to it with no new branches.

What's in the PR

1. classWideDocuments unit config — an authored array of { kind, title } slots on UnitConfiguration, read as stores.appConfig.classWideDocuments. This is the correct home for the authored DQB title.
2. Field-based canonical pointer builder — replaces the group-specific getGroupCanonicalPointerPath with one getCanonicalPointerPath(scope, label) that derives the path from the scope fields present: canonical/v1/classes/<classHash> / (offerings/<offeringId> | units/<unit>) / [groups/<groupId>] / slots/<label>. The units/ segment is used only when there is no offering, so the group pointer path is byte-identical (no migration). A future problem/planning pointer (offering + owner) slots in as a users/<owner> segment — documented, not built.
3. firestore.rules class+unit pointer — canonicalPointerPath rewritten to build the same path field-by-field (path() + string concat), gated by hasCanonicalScope (a non-empty offering or unit field — a field written as null counts as absent scope); plus a new immutable pointer write-guard match block canonical/v1/classes/{classId}/units/{unit}/slots/{label}.
4. Kind-registry-driven creation — a class-wide document is created with createDocument({ type: "group", kind }); its registered ownerType: "class" / scopeType: "classUnit" drive the rest. getDocumentOwner returns the synthetic class owner class_<classHash>, getDocumentScopeFields stamps context_id + unit (no offeringId/groupId), and getDocumentKindMetadataFields(kind) stamps kind + concurrent — so the document is stamped correctly with no class-wide-specific branch, and the kind (e.g. drivingQuestionBoard) is not mis-stamped as "group".
5. getOrCreateClassWideDocument({ kind, title }) — builds the class+unit pointer path with the slot's kind as the label and delegates to the existing race-safe getOrCreateCanonicalDocument.
6. Auto-creation on unit open — createDeclaredClassWideDocuments() registers each declared slot's kind and fires one getOrCreateClassWideDocument per slot inside DB.connect()'s unitLoadedPromise.then block, fire-and-forget (the pointer transaction converges all class members to one doc per slot). A malformed or duplicate kind throws in registerDocumentKind and is caught and skipped, so one bad author entry never blocks the others.
7. Verification + roadmap — emulator tests for two-client pointer convergence and the review-issue-Curriculum/Investigation/Problem/Section models #6 ordering, plus the document-axes roadmap status flip.

Notes for reviewers

• No data migration. Class-wide documents are unreleased.
• Security surface is small: no RTDB rules change (the class subtree is already class-member-writable); no Firestore create/update change beyond the pointer path (a class member can already create a doc with their own context_id; the create carries no canonical, which is granted only by the pointer-claim update).
• Review issue Curriculum/Investigation/Problem/Section models #6 (drift-guard weakening) is a verified no-op — the history.length === 0 weakening lived only in the superseded original DQB PR and is in neither this branch nor master. The metadata-before-history ordering is structurally guaranteed because getOrCreateCanonicalDocument writes the Firestore metadata before the document is opened; the emulator test verifies this rather than changing drift-guard code.
• Dormant for any unit that declares no classWideDocuments. The demo/units/qa unit now declares one drivingQuestionBoard slot so the create/pointer flow can be exercised end-to-end (see Testing); production curriculum units declare none.
• Two things flagged for the Stage-3 plan (not issues here): the eager open of each slot doc on unit load (cost + ensuring a type:"group" doc with no offering/group doesn't leak into existing type-based enumerations), and confirming the concurrent history-write path is authorized for the class_<classHash> synthetic owner when editing is wired.

Testing

• Unit (Jest): config resolution; the field-based pointer builder (group byte-identical + class+unit); class+unit creation stamping (scope, kind, concurrent; no offeringId/groupId/canonical); getOrCreateClassWideDocument fast/create paths; per-slot auto-creation.
• Rules (emulator, canonical-pointers-rules): class-member create/read of the class+unit pointer; immutability; cross-class denial; canonical-claim-confirmed-by-pointer; two-client convergence; Curriculum/Investigation/Problem/Section models #6 readability; plus a class-scoped (unit: null) doc cannot claim canonical. 25/25 green.
• Whole-repo check:types and lint:build clean.
• Manual end-to-end: the demo/units/qa unit declares a drivingQuestionBoard class-wide slot (src/public/demo/units/qa/content.json). Loading that unit auto-creates one class-wide document per class+unit and claims its canonical pointer, so the Firestore metadata document (owner class_<classHash>, unit, kind: "drivingQuestionBoard", concurrent: true) and the classes/<classHash>/units/<unit>/slots/drivingQuestionBoard pointer can be inspected in the emulator/console.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 95.33333% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.05%. Comparing base (11f18e7) to head (15c5f57).

Files with missing lines	Patch %	Lines
src/lib/db.ts	92.68%	6 Missing ⚠️
src/models/document/document-kinds.ts	98.03%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2928      +/-   ##
==========================================
+ Coverage   86.02%   86.05%   +0.02%     
==========================================
  Files         977      977              
  Lines       55660    55742      +82     
  Branches    14671    14692      +21     
==========================================
+ Hits        47884    47971      +87     
+ Misses       7758     7753       -5     
  Partials       18       18              

Flag	Coverage Δ
cypress	?
cypress-regression	71.84% <81.37%> (+0.24%)	⬆️
cypress-smoke	41.66% <78.62%> (+0.36%)	⬆️
jest	56.56% <70.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cypress]

collaborative-learning    Run #19702

Run Properties:   Passed #19702  •  15c5f57d20: Merge remote-tracking branch 'origin/master' into CLUE-550-class-wide-slots

Project	collaborative-learning
Branch Review	CLUE-550-class-wide-slots
Run status	Passed #19702
Run duration	10m 23s
Commit	15c5f57d20: Merge remote-tracking branch 'origin/master' into CLUE-550-class-wide-slots
Committer	Scott Cytacki
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	1
Pending	5
Skipped	0
Passing	220
View all changes introduced in this branch ↗︎

[scytacki]

The failing Cypress test seems to be random. It failed one time for me before and then passed after a re-run.

[tealefristoe]

Looks good 👍

I left a bunch of comments, which I hope are helpful, but take them or leave them as you like. If any show a misunderstanding on my part, please let me know. I'm trying to wrap my head around all of this.

[scytacki]

@tealefristoe thank you for the thorough review. I do think this is worthwhile especially in this part of the codebase.