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 93.83562% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.18%. Comparing base (f681050) to head (51b4117).

Files with missing lines	Patch %	Lines
src/lib/db.ts	90.00%	8 Missing ⚠️
src/models/document/document-kinds.ts	97.95%	1 Missing ⚠️

Additional details and impacted files

@@                        Coverage Diff                        @@
##           CLUE-550-concurrent-kind-axes    #2928      +/-   ##
=================================================================
+ Coverage                          86.14%   86.18%   +0.04%     
=================================================================
  Files                                937      937              
  Lines                              53374    53453      +79     
  Branches                           14100    14122      +22     
=================================================================
+ Hits                               45981    46071      +90     
+ Misses                              7377     7366      -11     
  Partials                              16       16              

Flag	Coverage Δ
cypress-regression	73.25% <82.26%> (+0.24%)	⬆️
cypress-smoke	42.37% <79.43%> (+0.37%)	⬆️
jest	55.66% <67.80%> (+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 #19564

Run Properties:   Passed #19564  •  51b4117a42: docs: note the demo/units/qa manual-verification path in the stage-2 spec [CLUE-...

Project	collaborative-learning
Branch Review	CLUE-550-class-wide-slots
Run status	Passed #19564
Run duration	09m 46s
Commit	51b4117a42: docs: note the demo/units/qa manual-verification path in the stage-2 spec [CLUE-...
Committer	Scott Cytacki
View all properties for this run ↗︎

---

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

[Copilot]

Pull request overview

Adds Stage 2 support for class-wide collaborative “slot” documents (e.g., DQB) by extending the kind/axis registry, generalizing canonical pointer paths to be scope-field-driven, and auto-creating declared class-wide documents on unit load. This fits into the document-axes refactor by moving more creation-time behavior (owner/scope derivation) behind the kind registry while reusing the existing canonical-pointer get-or-create transaction for race-free convergence.

Changes:

• Introduces classWideDocuments in unit configuration and exposes it via ConfigurationManager/AppConfigModel.
• Generalizes canonical pointer paths into a versioned canonical/v1/.../slots/<label> layout and updates Firestore rules + emulator tests accordingly.
• Adds class-wide doc creation (class_<classHash> owner, class+unit scope) and fire-and-forget auto-creation on unit open, plus Jest coverage for metadata stamping and pointer convergence logic.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/models/stores/unit-configuration.ts	Adds classWideDocuments authored unit config surface.
src/models/stores/configuration-manager.ts	Exposes classWideDocuments via config manager getter.
src/models/stores/app-config-model.ts	Surfaces classWideDocuments on stores.appConfig.
src/models/stores/app-config-model.test.ts	Tests config resolution for classWideDocuments.
src/models/document/document-utils.ts	Uses kind registry to resolve display titles first (incl. class-wide slot titles).
src/models/document/document-utils.test.ts	Adds tests for group vs class-wide title resolution behavior.
src/models/document/document-kinds.ts	Expands kind registry to include owner/scope derivation + optional static titles.
src/models/document/document-kinds.test.ts	Adds coverage for owner selection, scope field selection, and title resolution.
src/lib/scoped-document-pointers.ts	Replaces group-only pointer builder with scope-driven canonical/v1/.../slots/... builder.
src/lib/scoped-document-pointers.test.ts	Tests pointer paths for group scope vs class+unit scope.
src/lib/db.ts	Implements kind-driven owner/scope stamping, class-wide get-or-create, and unit-load auto-creation.
src/lib/db.test.ts	Adds unit tests for Firestore metadata stamping and class-wide pointer get-or-create flows.
src/lib/db-types.ts	Collapses group/class-wide RTDB metadata shape under transitional type:"group".
firestore.rules	Moves pointers under canonical/v1, adds class+unit create scope, updates canonical path helper.
firebase-test/src/canonical-pointers-rules.test.ts	Adds emulator tests for class+unit pointer rules + canonical-claim integrity.
docs/superpowers/specs/2026-07-23-clue-550-stage-2-class-wide-slots-design.md	New design spec documenting Stage 2 scope, pointer layout, and creation strategy.
docs/document-metadata/metadata-fields.md	Updates metadata-field documentation around RTDB classHash handling.
docs/document-axes/target-architecture.md	Refines axis/scope guidance toward field guards over kind/type branching.
docs/document-axes/README.md	Updates roadmap/status notes for Stage 2 progress.

Comments suppressed due to low confidence (1)

src/lib/db.ts:759

• getOrCreateGroupDocument() builds a pointer path using user.offeringId but doesn’t validate it. If offeringId is empty/undefined, getCanonicalPointerPath() will produce a path that doesn’t match the allowed pointer create scopes (and the group owner uid can be malformed), causing hard-to-diagnose failures. Fail fast when offeringId is missing.

    const groupId = user.currentGroupId;
    if (!groupId) {
      return Promise.reject("Cannot create group document because user is not in a group.");
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.