Repository navigation
Files Changed: persist explicit session lineage roots and typed edges #1075
Description
Files Changed: persist explicit session lineage roots and typed edges
Important
Problem - Files Changed cannot aggregate child work safely because task-parent links, session-spawn metadata, and forks have incompatible meanings. A durable ledger needs one explicit definition of which sessions share a root.
Approach - Persist a lineage root for every new session and typed edges for registered task and session-spawn operations. Forks always start a separate root. Root-owned receipt projections survive child archival or deletion under root retention policy.
Scope - in: root creation, typed edges, fork separation, child lifecycle, legacy-session boundary, and queryable lineage. out: mutation receipts, evidence, UI aggregation, and external-file changes.
Assumptions - Parent #972 defines the full-provenance contract. Existing task and explicit session-spawn paths provide the only eligible lineage edges.
Acceptance Criteria
- Every newly created session has exactly one lineage root.
- Registered task and session-spawn paths from a
fullorpartialparent create typed parent-child edges that resolve to the same root; a pre-epochlegacyparent follows the explicit non-aggregating legacy-parent rule. - A fork creates a distinct root and never inherits mutation ownership or external evidence.
- Child archival and deletion preserve the root-permitted origin projection without retaining child-private state beyond policy.
- Pre-existing sessions resolve as legacy and are never reconstructed into a false lineage.
- A lineage query returns only the root and its registered descendants, never unrelated concurrent sessions.
Testing Decisions
- Extend session lifecycle coverage for root creation, typed task edges, explicit session-spawn edges, forks, archival, deletion, and legacy migration.
- Add isolation cases with concurrent roots sharing a project and worktree.
Key Decisions
- Lineage is an explicit persisted relation, not an inference from transcript metadata or directory overlap.
- Session forks remain independent roots even when copied transcript content references an ancestor.
Constraints & Invariants
- Root ownership does not grant child access to another session's private evidence.
- Child removal cannot leave a dangling origin reference in a retained root receipt.
Prior Art
- Parent Files Changed: full session-lineage mutation ledger #972
- Existing task-parent and explicit session-spawn relationships
Deliberation Resolution
LineageModeis one oflegacy,partial, orfull. A session created before capability rollout stayslegacy; its first opted-in tracked mutation opens onepartialepoch at a recorded boundary time.- A registered task or session spawn from a
fullorpartialparent inherits that parent's root and mode. A spawn from alegacyparent before a partial epoch starts a distinctfullroot and retains only non-aggregatinglegacy_parentprovenance. - Once a legacy session opens its partial epoch, it is a
partialparent; every later registered spawn inherits that partial root and is labelled partial. task_spawnandsession_spawnare disjoint edge kinds. A fork has no lineage edge and always starts a distinctfullroot.- A retained origin projection contains only origin session ID, display title, edge kind, and deletion timestamp. Child-private context, evidence, and transcript content never survive child deletion through the root ledger.
- Default lineage queries return active descendants. Files Changed requests retained deleted-origin projections only when rendering existing receipt history, never as navigable child sessions.
Source
Part of #972.
Activity