v2 spine model: structure tree + first-class spine-side membership relation (supersedes grid framing)¶

Angelo › zettelkasten › Phase 2: Literature Review System › Workshop tab: Reading Syllabus (learn) + claim-centric Review/Outline (write) › Organizations: project-level lenses + spines (matrix builder redesign) › Spine promotion: materialize a matrix lens into a graph (cols+rows, bulk-attach)

Type: Decision · Status: active · Created: 2026-06-26

Design refinement raised during the Graph C spine-promotion review. The (rows x columns) grid is just the 2-D projection of a more general structure. Three refinements converge into one target model; documented as §11 of documents/260625_spine-promotion.md.

1) TWO EDGE CLASSES IN TWO PLACES. Semantic/structural links = substance (a note's claims/builds-on/related) — authored, persist forever, stay ON the note (base graph). The DEFAULT SPINE is nothing but these (organic structure, no schema, no materialized nodes). Spine membership = organization ('note is a member of node X of spine S') — derived, correctable, rebuildable, disposable. Make membership a FIRST-CLASS relation category (e.g. spine-member/routed-to), NOT overloaded onto input-to/component-of. Keep apex<->dimension structural; node->member is the new organizational relation.

2) MEMBERSHIP STORED SPINE-SIDE. Store membership in the spine graph (node --spine-member--> note), never on the base note. Payoffs dissolve current fix-cycle problems: teardown = delete the graph folder (no base-note scrub; kills the dangling-edge/P1-G problem); isolation is physical (two spines can't bleed; makes the P0-B link.graph==spine_ref guard unnecessary); base notes stay pristine across re-promote/relabel/drift/corrections. Cost: matrix readback (tables._note_links_to / _group_link_scopes) must traverse the spine graph instead of base-note outgoing links.

3) SPINE = STRUCTURE TREE, NOT GRID. build_scaffold hard-codes depth 1 (flat dimensions + separate hub axis). Generalize to a tree rooted at apex, each node component-of its parent to arbitrary depth (natural for a nested/bulleted schema; default spine is the organic version). dimension/hub become 'structure node at depth N'. A member attaches to ANY node incl. interior. Views are renderings: Outline = the tree full-depth (native); Matrix = a 2-axis flattening (pick levels for cols/rows, deeper collapses into the cell or becomes the pivot — grid is a view-config over the tree); Graph = nested halos. Implementation: _group_link_scopes becomes depth-aware; build_scaffold recurses; matrix gains a 'levels->rows/cols' config. DECISION TO CONFIRM: parent cell AGGREGATES descendants' members (rollup), matching component-of upward reads.

STATUS: target architecture. The shipped Graph C promotion went base-side and flat, so base-side scrub + link.graph isolation guard are SUPERSEDED by this — fold the migration in when v2 lands, don't double-pay. Queued behind the in-flight Graph C fix cycle so we don't rewrite storage+scaffold mid-fix. Note: §9b/§10 of the doc already anticipated spine-side edges; v2 confirms + adds the tree + first-class relation.

Referenced files¶

Source: memory entry deci-c11960f1.