Skip to content

Files Changed: persist explicit session lineage roots and typed edges #1075

Closed

Description

@jeonghun-jj-lee

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 full or partial parent create typed parent-child edges that resolve to the same root; a pre-epoch legacy parent 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

Deliberation Resolution

  • LineageMode is one of legacy, partial, or full. A session created before capability rollout stays legacy; its first opted-in tracked mutation opens one partial epoch at a recorded boundary time.
  • A registered task or session spawn from a full or partial parent inherits that parent's root and mode. A spawn from a legacy parent before a partial epoch starts a distinct full root and retains only non-aggregating legacy_parent provenance.
  • Once a legacy session opens its partial epoch, it is a partial parent; every later registered spawn inherits that partial root and is labelled partial.
  • task_spawn and session_spawn are disjoint edge kinds. A fork has no lineage edge and always starts a distinct full root.
  • 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.

Metadata

Metadata

Labels

hitlNeeds human review before merge

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions