todo

Domain-model review guide

Datatype review guide

Start with one datatype below. Its Current State records implementation; Future State (Proposed) contains architecture recommendations. Edit/comment on those proposed answers to refine the contract.

These are working review drafts, not ticket resolutions. GitHub remains the decision record: after a human decision, record its resolution there and replace the local proposed answer with the agreed contract and resolution link. This update does not close tickets, change dependency edges or adopt new glossary definitions. Shared glossary wording and runtime/schema changes wait for those decisions.

Datatype	Review here	Wayfinder question owner
Note	Type descriptor versus placement, provenance and tags; each note flavor	Pick the note-type taxonomy and where type lives
BlockRevision	Meaning/kinds, extension criteria and persistence mapping	Name and bound the segment taxonomy
Page#Mode and write destinations	Source authority, modes, local actions and save destinations	Define the mode-resolution rule matrix (read-only vs edit)
BlockRevision	Per-kind presentation/editing and recovery	Map every segment kind to edit and read-only rendering
Effort	Owning note, registry projection, validation and matching	Resolve effort linkage and indexable effort metadata
collection	Query inclusion versus placement, dates and Catalog boundaries	Decide collection-page membership: WQL segment vs pageId
BlockRevision	Existing research carried forward with source-write/lifecycle caveats	Research: CodeMirror 6 patterns for mode-aware block widgets — already closed research
Page#Syntax and dashboard composition	Teaching source, canvas layout and live local examples	Resolve syntax pages as typed notes
Page#Composition completeness questions	Cross-datatype acceptance, not another storage model	Assemble the crosswalk & behavioral spec
Note-Page-WQL-Alignment	Audit of Note vs Page data ownership, semantic conflations, and WQL query composition	Audit: Note vs Page WQL Alignment
Supporting datatypes keep their own focused questions: BlockIndexRow for derived-search identity/lifecycle; Session and Attachment for non-source save destinations; EventRecord for recorded-fact ownership; Tag/NoteTag for classification; FieldSourceRecord for reversible contributions.

Remaining human choices stay beside their datatype: supported descriptors, default modes, acceptable source normalization, effort rename/delete and invalid-draft policy, collection dates/order/expansion, and syntax conversion boundaries. No new Widget, Syntax or Dashboard database type is invented to host those questions.

The visual canvas and the separate results→sessions/meta→configuration proposals are not migration instructions from this review. The existing field-catalog value/count/backfill documents remain unchanged where no typed-note contract changes.

Table outline

Existing schema reference. The “New name” column records separate, unimplemented rename proposals. Corpus identity exceptions are explained in BlockIndexRow; this table does not establish universal foreign-key guarantees.

Table	New name	PK	FK (field → table)	Indexes	Notes
[[Page|page]]		id	—	by-date (date, unique); by-slug (slug, unique)
[[Effort|efforts]]		slug	derivation.parentSlug → [[Effort|efforts]] (self)	by-discipline (baseAttributes.discipline); by-source (registrySource)
[[Note|notes]]		id	pageId → Page; sourceId → Note	by-slug (slug, unique); by-page (pageId)	No note-level content hash proposed by this review
[[BlockRevision|block_revisions]]		[noteId, blockId, version]	noteId → Note	by-note (noteId); by-block ([noteId, blockId])	Immutable saved block states; retained after block/Note deletion
[[Session|sessions]]	sessions	id	noteId → [[Note|notes]]; blockId + blockVersion → [[BlockRevision|block_revisions]]; pageId → [[Page|page]]; blockContentId → [[BlockIndexRow|block_index]] (hash join)	by-note (noteId); by-completed (createdAt); by-content (blockContentId); by-block (blockId)
[[BlockIndexRow|block_index]]		id	noteId → [[Note|notes]]; blockId + blockVersion → [[BlockRevision|block_revisions]]	by-note (noteId); by-content (blockContentId); by-type (dataType)
[[Attachment|attachments]]		id	noteId → [[Note|notes]]; pageId → [[Page|page]]; resultId → [[Session|sessions]]	by-note (noteId); by-time (createdAt); by-page (pageId); by-result (resultId)
[[EventRecord|events]]		id	resultId → [[Session|sessions]]; noteId → [[Note|notes]]; pageId → [[Page|page]]; effortSlug → [[Effort|efforts]].slug; blockId + blockVersion → [[BlockRevision|block_revisions]]; blockContentId → [[BlockIndexRow|block_index]] (hash join)	by-timestamp (timestamp); by-result-grain ([resultId, grain]); by-content-grain ([blockContentId, grain]); by-effort (effortSlug); by-outputType (outputType); by-grain (grain); by-metric-date (metricDateKeys, multiEntry)
[[Tag|tags]]		id	—	by-label (label, unique); by-type (type)
[[NoteTag|note_tags]]		id	noteId → [[Note|notes]]; tagId → [[Tag|tags]]	by-note (noteId); by-tag (tagId)
[[FieldCatalogEntry|field_catalog]]		id	—	by-path (path)
[[FieldSourceRecord|field_sources]]		id	id → [[Note|notes]] or [[Session|sessions]] (polymorphic entityKind:recordId); contributions[].fieldId → [[FieldCatalogEntry|field_catalog]]	—
[[FieldValueRecord|field_values]]		[fieldId, value]	fieldId → [[FieldCatalogEntry|field_catalog]]	by-field (fieldId)
[[CatalogBackfillState|field_catalog_meta]]		id (singleton 'backfill')	—	—
[[Configuration|meta]]	configuration	key	—	—	Renamed document to Configuration.md; live store remains meta

Route & Unification Realignment Checklist

Items in domain model plans requiring updates to align with screens/README.md and current router conventions:

Domain Model Plan	Current Plan Gap	Alignment Required	Alignment Status
Note	Lacks dual-ID contract (noteId + pageId); assumes route-based slug addressing	Update to reflect dual IDs on query/provider output: noteId for editor (/notes/:noteId), pageId for page render (/p/:slug).	Aligned: doc updated; HistoryEntry, IndexedDBContentProvider, and entryMapper now populate pageId.
Page	Defines only calendar date and custom slug; omits /p/:slug umbrella	Formulate /p/:slug as generic render for any slug (/c, /e, /d are specialized views). Formalize multi-note composition preserving per-note edit boundaries.	Aligned: doc updated; /p/:slug umbrella and /c, /e, /d routing recognized across app.
collection	Treats feeds as permanent separate corpus; uses legacy /collections/:slug	Mark feeds as transitional (converging into dated collections). Align routes with /c/:slug, /c/:slug/:date, and /notes/:noteId for post items.	Aligned: doc updated; routes canonicalized to /c/:slug and /notes/:noteId; feed store migration tracked in #1031.
Effort	Uses legacy /effort/:slug; leaves effort-as-note persistence ambiguous	Align route with /e/:slug (specialized /p/:slug). Document transition from standalone registry record (efforts store) to note-backed effort entity.	Aligned: doc updated; /e/:slug route cutover landed; note-backed storage cutover tracked in #1030.
Session	Carries legacy /results and /results/:resultId route references	Replace all references with /sessions, /sessions/:sessionId, and /session/:date. Ensure outgoing links target /notes/:noteId.	Aligned: doc updated; DB v21 flattened table and /sessions/:sessionId routing active.
BlockIndexRow	Links deep results to legacy /collections/:cat/:name paths	Align deep link generation: emit /notes/:noteId for stored notes and /c/:cat/:page-slug for corpus items.	Aligned: doc updated; entryOpenHref emits canonical paths for all block rows.