Skip to content

architecture.md

Latest commit

 

History

History
676 lines (557 loc) · 31.1 KB

architecture.md

File metadata and controls

676 lines (557 loc) · 31.1 KB
Raw

DeltaGit Architecture

Status: PLANNED / DOCUMENTATION ONLY / BLOCKED ON LAYERFS MATURITY

Authority date: 2026-08-23

DeltaGit is not ready for implementation. This document describes the intended product architecture once LayerFS has a stable, reusable, evidence-backed engine, SDK, and projection boundary.

This file and the normative product specification are the current DeltaGit planning authorities. Earlier files under docs/ remain exploratory history and are superseded wherever they conflict with these two documents.

LayerFS stores immutable filesystem states. DeltaGit records operations over those states. Git publishes selected states into the existing Git ecosystem.

1. Current truth

Area Status What may be claimed
DeltaGit product Planned Architecture and requirements only
DeltaGit examples and experiments Exploratory Demonstrations, not product or performance authority
LayerFS G5 Blocked prerequisite Benchmark-private trust/projection work; terminal reusable contract still required
LayerFS G6 Specified, not implemented Design for arbitrary-size expected-local canonical edits and portable range resolution
Git interoperability Planned Reuse Git objects, refs, commands, remotes, and GitHub; do not reimplement Git
Agent/sandbox integration Future product adapters Must remain outside LayerFS canonical identity 
flowchart LR
    G5["LayerFS G5 terminal PASS"] --> G6["LayerFS G6-T / G6-V / G6-N"]
    G6 --> PX["Reusable core / engine / SDK / VFS extraction"]
    PX --> MH["History, rollback, storage, resource maturity gates"]
    MH --> DG["DeltaGit implementation may begin"]

    classDef blocked fill:#f8d7da,stroke:#842029,color:#842029;
    class DG blocked;
Loading

DeltaGit work stops at documentation and product-neutral requirements until all four prerequisite nodes pass. Evolving LayerFS benchmark binaries or private schemas are not an API contract.

2. System boundary

flowchart TB
    subgraph Products["Products built above DeltaGit"]
        A1["Git for agents"]
        A2["Multi-agent sandbox"]
        A3["IDE / CI / local automation"]
    end

    subgraph DeltaGit["DeltaGit enhancement plane"]
        AD["Provider adapters"]
        RT["Command runtime / operation supervisor"]
        OP["Operation log and mutation journal"]
        SR["Sessions, refs, checkpoints, rollback, fork"]
        GP["Git promotion policy"]
    end

    subgraph LayerFS["Mature LayerFS core"]
        SDK["Stable SDK / VFS boundary"]
        CORE["CAS + CDC + COW + canonical trees"]
        ENG["Detached durable roots, deltas, authentication"]
        RES["Range resolver and root-to-root diff"]
    end

    subgraph Projection["Projection adapters"]
        VIRT["SDK / virtual filesystem"]
        NATIVE["clone / reflink / native projection"]
        EXPORT["cold compatibility export"]
    end

    subgraph Git["Git compatibility plane"]
        OBJ["blobs / trees / commits"]
        REF["branches / tags / merge / rebase"]
        REM["fetch / push / GitHub"]
    end

    Products --> AD --> RT --> OP --> SR
    SR --> SDK
    SDK --> CORE
    SDK --> ENG
    SDK --> RES
    RES --> VIRT
    RES --> NATIVE
    RES --> EXPORT
    SR --> GP --> OBJ --> REF --> REM
Loading

Ownership table

Concern Owner Explicitly not owned by
Canonical paths, objects, roots, CDC, CAS, COW LayerFS DeltaGit, Git, agent adapters
Arbitrary canonical file replacement and range resolution LayerFS G6 DeltaGit journal, projection driver
Detached root durability and reconciliation LayerFS engine Command runtime, Git exporter
Product-visible SessionHead selection DeltaGit metadata authority LayerFS singleton head, projection, Git exporter
Tool/command operation lifecycle DeltaGit runtime LayerFS, Git
Changed-path/range observation and coalescing DeltaGit workspace layer LayerFS canonical identity
Session heads, checkpoints, rollback, fork policy DeltaGit LayerFS object format, Git remote protocol
Shells, stdio, deadlines, process-tree cleanup Runtime supervisor LayerFS, Git
Provider hook payloads and tool IDs Thin provider adapter Runtime supervisor, LayerFS
Git blobs, trees, commits, refs, merge/rebase, remotes Git LayerFS, DeltaGit core
Native filesystem mechanics Projection/OS adapter Canonical LayerFS format
Agent identity, prompts, tasks, sandbox policy Product above DeltaGit LayerFS canonical roots

3. Identity and version model

Do not collapse content state, operation history, and Git publication into one identifier.

flowchart LR
    ROOT["LayerFS RootId\nfilesystem content state"]
    OP["DeltaGit OperationId\nwhat happened"]
    REV["DeltaGit CheckpointId\nroot + operation ancestry"]
    SREF["DeltaGit SessionHead\nmutable name for a checkpoint"]
    GIT["Git commit OID\npublished Git history"]

    OP --> REV
    ROOT --> REV
    REV --> SREF
    REV -->|"promote"| GIT
Loading
Identity Meaning Mutability Canonical LayerFS input?
ObjectId Canonical object bytes Immutable Yes
RootId Exact logical filesystem state Immutable Yes
OperationId One supervised tool/command lifecycle Immutable record No
CheckpointId Operation ancestry plus resulting RootId Immutable No
SessionHead Current selected checkpoint for a workspace/session Mutable with compare-and-swap No
Git object ID Git-compatible published object/commit Immutable No

Equal filesystem bytes reached through different operation histories retain the same RootId but may have different CheckpointIds. Agent, prompt, command, timestamp, branch, and Git metadata never affect LayerFS object or root identity.

4. Per-operation lifecycle

The checkpoint boundary is one logical tool operation, not each low-level write(2) call.

sequenceDiagram
    participant A as Agent adapter
    participant D as DeltaGit runtime
    participant P as Process tree
    participant J as Mutation observer
    participant L as LayerFS
    participant R as SessionHead authority

    A->>D: prepare(original tool input, cwd, deadline)
    D->>D: persist operation record and pin parent root R0
    D->>P: launch in the operation view
    P->>J: create / write / truncate / rename / delete
    J-->>D: bounded append-only observations
    D->>P: wait for process group to drain
    D->>J: seal and coalesce ChangedSet
    D->>L: prepare detached child(parent=R0, ChangedSet)
    L-->>D: requested root R1, LayerDeltaId, prepared handle
    D->>D: durably persist CheckpointIntent(requested=R1)
    D->>L: commit prepared detached child R1
    L->>L: one root-durability COMMIT
    L-->>D: durable root R1 and change summary
    D->>R: atomically bind checkpoint and CAS SessionHead C0 -> C1/R1
    R-->>D: product-visible SessionHead outcome
    D->>D: seal OperationId -> C0 / C1
    D-->>A: operation result + checkpoint
Loading

Runtime state machine

stateDiagram-v2
    [*] --> Prepared
    Prepared --> Running
    Running --> Draining: shell exits or cancellation begins
    Draining --> Quiescing: process group is empty
    Quiescing --> Sealing: journal complete
    Sealing --> Sealed: checkpoint and head update succeed
    Sealing --> NoChange: root unchanged
    Sealing --> Discarded: policy discards private view
    Sealing --> Failed: capture/checkpoint fails
    Running --> Escaped: process escapes observable lifecycle
    Failed --> Recovery
    Escaped --> Recovery
    Recovery --> Sealed: safely reconciled
    Recovery --> Abandoned: retained for manual action
Loading

Execution and filesystem results are orthogonal:

ExecutionOutcome FilesystemDisposition
Success, NonZero, Signaled, TimedOut, Cancelled, LaunchFailed Sealed, NoChange, Discarded, Failed, IncompleteEscaped

A cancelled or timed-out command that retains changes still drains, seals, checkpoints, and reconciles normally. Cancellation alone never implies discard.

For a no-change operation, preparation proves R1 == R0; LayerFS performs zero root transactions/COMMITs. DeltaGit still creates checkpoint C1 and moves SessionHead C0/R0 -> C1/R0 in one metadata transaction so per-tool history remains complete.

PostToolUse, tool return, output polling, and a shell's exit are telemetry, not lifecycle authority. The operation closes only after its process group has drained and the workspace reaches the frozen quiescence rule.

Acknowledgement boundaries

command accepted
    < command/process completed
    < mutation journal sealed
    < detached LayerFS root durable
    < DeltaGit SessionHead visible
    < virtual workspace shows selected root
    < native projection durable
    < cold standalone export complete

No earlier acknowledgement may be relabeled as a later one.

5. Mutation observation and correctness

Mutation observation is a DeltaGit input to LayerFS; it is not a substitute for LayerFS identity, detached-root durability, or SessionHead validation.

flowchart LR
    ST["Structured Edit / Write"] -->|"exact path and range"| CS["ChangedSet"]
    VFS["Mutation-aware VFS"] -->|"exact filesystem events"| CS
    W["OS watcher"] -->|"discovery hint"| CS
    CMD["Opaque native command"] --> OBS{"Mutation-aware boundary?"}
    OBS -->|"yes"| CS
    OBS -->|"no"| REC["frozen exact reconciliation or incomplete"]
    REC --> CS
    CS --> N["normalize and coalesce"]
    N --> CP["LayerFS checkpoint"]
Loading
Source Authority Expected discovery cost Limitation
Structured file tool Exact requested paths/ranges Changed ranges Must detect out-of-band writes
Mutation-aware virtual filesystem Exact observed operations Events/changed paths Future integration
Runtime-native journal Exact only for routed writes Events/changed paths Bypasses are invisible
OS watcher Hint Events Drops/coalescing/races require reconciliation
APFS clone alone None for mutation discovery N/A Cheap storage copy is not a journal
Frozen exact reconciliation Correct fallback with immutable snapshot or proven writer exclusion Potentially all paths Timing silence/quiescence alone is not authority

The initial product may use a correct final-state reconciliation fallback. It must not claim O(changed paths) unless the observation boundary proves that all writes passed through it.

An exact reconciliation receipt binds the operation ID, immutable view or writer-exclusion proof, base root, scan boundary and start/end, journal sequence/custody status, and final root/digest. Journal gaps or overflow revoke journal completeness; sealing is allowed only if this independently frozen reconciliation succeeds, otherwise the operation remains incomplete.

The permanent operation pipeline is:

append-only observations
        |
streaming coalescer
        |
ChangedSet { creates, updates/ranges, deletes, renames, metadata }
        |
one LayerFS parent-root -> child-root checkpoint

Do not retain an unbounded in-memory event log. Large journals remain on disk and are reduced through bounded batches to final path/range state.

6. Checkpoint cost model

The desired mature path is:

flowchart LR
    R0["Parent root R0"] --> CH["Changed paths and ranges"]
    CH --> FC["Changed-file canonical edits\nCAS + CDC + G6 extents"]
    FC --> NS["Changed namespace paths\nCOW ancestors"]
    NS --> PUB["One detached-root durability COMMIT"]
    PUB --> R1["New immutable root R1"]

    R0 -. "unchanged objects/subtrees reused" .-> R1
Loading

For K changed paths, changed bytes Delta, bounded local CDC work W, file-tree height Hf, and namespace-tree height Hp, the ordinary target is:

checkpoint work
  ~= O(journal bytes + K*Hp + Delta + W + changed file-tree paths)
     + one DeltaGit CheckpointIntent durability transaction
     + one LayerFS root-durability transaction
     + one DeltaGit checkpoint/SessionHead transaction

That equation is for a state-changing operation. A no-change operation skips the intent and LayerFS root COMMIT and performs only the DeltaGit checkpoint/SessionHead transaction.

The architecture forbids these hidden costs on a claimed ordinary fast path:

full workspace scan
complete changed-file rescan when exact ranges are available
remaining-file suffix mapping replay after an ordinary G6 rejoin
full native materialization
replay of every historical operation
a second canonical root publication or hidden SessionHead transition

SessionHead is the sole DeltaGit-visible selection authority. A durable detached child root is unreachable product state until the DeltaGit metadata transaction binds its CheckpointId and successfully moves the session head. Before dispatching the root COMMIT, DeltaGit persists a CheckpointIntent binding the operation, expected checkpoint/head, parent root, requested root, requested LayerDeltaId, and ChangedSet digest. That intent is the recovery bridge across the three honest durability boundaries. A later admitted joint transaction may combine them but is not assumed.

An adversarial CDC non-rejoin, missing change authority, or unsupported native route may still require an explicit suffix/full fallback. It is reported as a fallback, never pooled into the expected-local claim.

Avoid a permanent delta-chain filesystem

Good during an open operation:
    bounded journal + ChangedSet overlay

Good at checkpoint:
    one directly readable immutable LayerFS root

Rejected as the permanent index:
    lookup path by replaying every operation delta back to the base

Operation history is retained in DeltaGit. Filesystem lookup resolves the selected LayerFS root directly.

7. Rollback, restore, and fork

flowchart LR
    R0["R0"] -->|"op-1"| R1["R1"] -->|"op-2"| R2["R2"] -->|"op-3"| R3["R3"]
    S["session/main"] --> R3
    S -. "logical rollback" .-> R1
    F["session/fork"] -. "metadata-only fork" .-> R1
    F -->|"new op"| R4["R4"]
Loading
Operation Core action Intended complexity Excluded work
Logical rollback Compare-and-swap SessionHead to retained CheckpointId/root Metadata + durability class Content rewrite, full scan
Fork Create another SessionHead at an existing CheckpointId/root Metadata class Workspace copy
Virtual switch Install selected root in a virtual view Root/generation class Native reconstruction
Native reconcile Diff projected root to selected root and update output Changed routes or honest fallback Not part of logical rollback timer
Cold restore/export Rebuild complete standalone workspace Full output size Never called near-constant
Full verification Authenticate selected closure Full reachable closure Never hidden in rollback ACK

Rollback never deletes the abandoned future immediately. Objects remain while reachable from another session, checkpoint, pinned reader, in-flight publication, or retention policy.

8. Read and projection model

flowchart TB
    ROOT["Selected immutable LayerFS root"]
    ROOT --> SDK["Direct SDK range resolver"]
    ROOT --> VF["Virtual filesystem adapter"]
    ROOT --> NF["Native projection adapter"]
    ROOT --> CE["Cold exporter"]

    SDK --> RR["requested-range work"]
    VF --> RR
    NF --> ROUTE{"best qualified route"}
    ROUTE --> CL["clone / sparse patch"]
    ROUTE --> RF["range reflink / tail route"]
    ROUTE --> FB["honest full fallback"]
    CE --> FULL["Theta(output bytes)"]
Loading
Endpoint Portable expectation after mature G6 Platform dependency
Direct SDK read Tree height + intersecting extents + returned bytes None beyond storage engine
Virtual-file read Same resolver work plus adapter/cache overhead FUSE/FSKit/ProjFS equivalent
Same-size native patch Changed ranges after qualified clone Filesystem clone support
Tail append/truncate Changed tail/metadata after qualified clone Filesystem support
Middle size-changing native projection Reflink/extent operation where available; suffix/full fallback otherwise Filesystem and alignment
Cold full export Complete output Universal fallback

The portable win is the immutable root, measured extent resolver, and exact root-to-root diff. Projection drivers opportunistically preserve locality; no OS-specific extent or path enters canonical identity.

9. Git compatibility and promotion

DeltaGit does not replace Git. A selected DeltaGit revision is promoted into ordinary Git objects before a normal Git branch is published.

flowchart LR
    OPS["DeltaGit operations\nop1 -> op2 -> op3"] --> SEL["Selected LayerFS root"]
    SEL --> WALK["Stream logical files and directories"]
    WALK --> BLOB["Git blobs"]
    BLOB --> TREE["Git trees"]
    TREE --> COMMIT["Git commit"]
    COMMIT --> UPDATE["git update-ref"]
    UPDATE --> PUSH["ordinary git push / GitHub"]

    OPS -. "default: squash local operations" .-> COMMIT
Loading
DeltaGit owns Git continues to own
Per-operation history before promotion Blob/tree/commit object formats
Session/workspace refs Persistent Git branches and tags
Rollback and fork between local checkpoints Merge, rebase, cherry-pick, merge-base
Operation provenance Diff, log, grep, show, patch formats
Selection and promotion policy Fetch, push, remotes, GitHub protocol
LayerFS-to-Git identity cache Git object validation and ref update semantics

The first lossless export subset is deliberately narrow: regular files, directories containing representable descendants, an admitted canonical path set, and the frozen executable-bit mapping. Empty directories, symlinks until LayerFS admits them, hard links, devices, sockets, FIFOs, xattrs, ACLs, and other unrepresentable state produce typed UnsupportedGitExport; the Git ref does not move. Silent omission is forbidden.

The first exporter should reuse Git plumbing. A custom Git implementation, pack format, remote protocol, or merge engine is out of scope unless profiling later proves a specific plumbing bottleneck.

10. Runtime and provider adapters

flowchart LR
    C["Codex hook"] --> A["Provider adapter"]
    CL["Claude hook"] --> A
    O["Other provider"] --> A
    A --> RUN["deltagit-run --operation ID"]
    RUN --> SUP["Provider-neutral supervisor"]
    SUP --> SH["shell / process group / stdio"]
    SUP --> OP["DeltaGit operation lifecycle"]
Loading
Input Owner Rule
Original command Adapter stores exact value Runner receives an operation ID, not a re-quoted command
Effective cwd Adapter + runtime Relative paths resolve inside the selected view
Deadline Runtime Applies to the process group, not output polling
Yield/wait timeout Provider transport Does not close the operation
Stdin continuation Provider transport + runtime Continues the same operation
Background mode Provider transport Operation stays open until descendants drain
Cancellation Provider + runtime Kill/drain group, then seal exact cancelled state

The exact command lives only in a size-capped private operation record with restrictive local custody and is redacted from default reports. Full environment values are not retained by default; store only required safe metadata plus a digest unless a separately admitted encrypted/private policy requires more. Oversize command, environment, or provenance input fails before child launch. Runtime output is streamed through bounded buffers with explicit backpressure/truncation/cancellation or failure status; it cannot be known at preflight. Recovery never reruns the original command.

Arbitrary Bash strings are never rewritten by broad path substitution. Full absolute-path transparency requires a real virtual filesystem or equivalent namespace boundary. Relative-path working-directory redirection and structured file-tool mapping are narrower, explicitly labeled compatibility modes.

11. Concurrency model

LayerFS supplies generic filesystem primitives; DeltaGit products decide how many sessions or agents use them.

flowchart TB
    BASE["Root R0"]
    BASE --> A["Session A pins R0"]
    BASE --> B["Session B pins R0"]
    A -->|"detached child + head A CAS"| RA["Root RA"]
    B -->|"detached child + head B CAS"| RB["Root RB"]

    A --> C1["two operations expect head A0"]
    C1 -->|"first head CAS wins"| RA2["Head A1"]
    C1 -->|"second head CAS"| STALE["typed stale-head conflict"]

    R1["Reader pinned R0"] -. "continues exact old-root read" .-> BASE
    R2["New readers"] --> RA
    R2 --> RB
Loading

Hard core semantics:

immutable root-pinned readers
detached child roots permit independent session histories
one SessionHead publication per state-changing checkpoint
SessionHead compare-and-swap prevents lost update within that session
no hidden retry or automatic merge
bounded aggregate memory and descriptors

Automatic disjoint-edit rebase, overlapping conflict resolution, multi-parent revision records, and product-level merge policy are later DeltaGit features. G6 DiffSplice is a useful primitive, not a merge engine.

12. Trust, security, and recovery

Trust boundary

Boundary Required rule
LayerFS default Verified remains default
Local development optimization TrustedLocalDev must be explicit and Store-lifetime
Object access Every fetched/new/incumbent object identity check remains unconditional
Trusted history Never becomes Verified authority; Verified reopen performs its required scrub
LayerFS root durability One detached-root writer transaction/COMMIT and exact reconciliation
DeltaGit visibility One checkpoint/SessionHead transaction; sole product-visible pointer
Rollback freshness Not protected without external monotonic authority
DeltaGit metadata Never changes LayerFS object/root identity
Native projection Derived, replaceable state; never canonical authority

Runtime security boundary

DeltaGit command supervision is not a security sandbox. Filesystem namespace, network, credentials, resource quotas, user identity, and process isolation belong to the hosting sandbox/runtime. DeltaGit must record escaped or unobservable operations rather than silently claiming complete attribution.

Recovery flow

flowchart TD
    ORPHAN["Operation record exists after restart"] --> P{"Process group still owned?"}
    P -->|"yes"| REATTACH["reattach / continue observing"]
    P -->|"no"| STATE{"Journal and workspace state"}
    STATE --> INTENT{"CheckpointIntent present?"}
    INTENT --> FINAL["reconcile requested root, then finalize head"]
    INTENT --> CANCEL["mark cancelled and retain evidence"]
    STATE --> CANCEL["mark cancelled and retain evidence"]
    STATE --> ABANDON["mark abandoned for manual recovery"]
    FINAL --> RECON["reconcile LayerFS root and session ref"]
Loading

An operation record is persisted before child launch. Failed stdout, stderr, exit status, timing, journal, and reconciliation evidence remain inspectable.

13. Storage, retention, and garbage collection

flowchart TB
    REFS["Session refs / retained checkpoints"] --> REACH["Reachability roots"]
    PINS["Open readers / in-flight publications"] --> REACH
    GIT["Promotion or retention policy"] --> REACH
    REACH --> WALK["LayerFS reachability walk"]
    WALK --> LIVE["retained immutable objects"]
    WALK --> DEAD["unreachable candidates"]
    DEAD --> GC["future separately qualified GC"]
Loading

CAS and COW reduce duplication; they do not make infinite operation history free. LayerFS must first prove exact per-revision storage slope, root pinning, long-history read/reopen behavior, and a safe reachability model. DeltaGit then owns retention policy. Destructive GC remains a separate, explicitly gated implementation.

14. LayerFS maturity gate for DeltaGit

DeltaGit implementation remains blocked until every row passes through the same reusable product path that DeltaGit would consume.

Gate Required evidence Why DeltaGit needs it
G5 terminal closure Honest trust, reopen/edit, projection, history/resource result Do not build on benchmark-private shortcuts
G6 arbitrary edit locality Insert/delete/replace/multi-splice at varied size/position with explicit fallback Frequent tool checkpoints must follow actual deltas
Stable reusable boundary Core/engine/SDK/VFS APIs; benchmark calls those APIs No reimplementation inside DeltaGit
Detached child roots and multi-root reads Two sessions can commit children of one parent without moving a singleton head Independent forks require non-global publication
Deterministic prepare/commit split Requested root/delta known before dispatch and recoverable from a durable intent Two-store crash recovery needs exact requested identity
Frequent edit history 1/10/100/1,000 revisions without latency or resource drift Per-tool checkpoints create long histories
Logical rollback/fork Root/ref switch with zero content rewrite Product-defining operation
Storage efficiency Exact changed/new/reused bytes and per-revision slope Cheap checkpoints/forks must be real
Range and virtual reads Requested-range work independent of full export Active work must not rematerialize everything
Crash/reconciliation Every publication/reopen ambiguity closes exactly Operation history cannot point to partial roots
Bounded concurrency Pinned readers, stale-head conflict, writer progress, bounded Q/RSS Safe composition by higher-level products
Promotion-readiness audit Same product code, arbitrary roots, no fixture hacks DeltaGit must consume without semantic rewrites 
flowchart LR
    FAIL["Any gate REVISE / missing"] --> WAIT["DeltaGit remains design-only"]
    PASS["All gates PASS"] --> MVP["DeltaGit local-operation MVP eligible"]
Loading

15. Staged future architecture

These stages are sequencing constraints, not current implementation work.

Stage Deliverable Depends on Deliberately excluded
0 — LayerFS substrate Mature reusable roots, edits, ranges, rollback/fork primitives G5, G6, product extraction DeltaGit product code
1 — Local operation MVP deltagit-run, one session, bounded mutation observation, one checkpoint per operation Stage 0 Merge, multiple providers, remote sync
2 — Git promotion Stream selected root to Git blobs/trees/commit and update a normal ref Stage 1 Custom Git protocol or pack implementation
3 — Virtual workspace Exact root-pinned view, absolute-path transparency, projection coalescing Stage 1 + qualified adapter General container runtime
4 — Collaboration Multiple session refs, explicit conflicts, optional rebase/merge metadata Stages 1–3 Agent reasoning and orchestration policy
5 — Retention lifecycle Retention policy and separately qualified GC Proven reachability/pins Concurrent GC without evidence

16. Architectural invariants

  1. Every visible workspace view identifies one exact immutable LayerFS root.
  2. Every sealed operation identifies its parent root, resulting root, status, and observation/capture authority.
  3. One logical tool operation produces at most one state-changing detached LayerFS root commit and one SessionHead publication.
  4. A no-change operation produces no LayerFS root commit but does create a new CheckpointId and moves SessionHead to it while retaining the same root.
  5. Rollback and fork change refs; they do not rewrite canonical content.
  6. Native projections are derived and replaceable. They never become root or object authority.
  7. Operation history is not the filesystem lookup structure.
  8. Provider/tool/session metadata never enters canonical LayerFS identity.
  9. Expected-head rejects lost updates; no hidden retry or automatic merge changes an operation's meaning.
  10. Git promotion produces ordinary Git objects and refs before ordinary push.
  11. DeltaGit reuses Git merge/rebase/remote behavior instead of replacing it.
  12. Performance claims name the exact boundary: journal, checkpoint, logical rollback, virtual visibility, native projection, or cold export.
  13. Unsupported observation or projection routes fall back honestly and are never relabeled as expected-local.
  14. Memory, descriptors, pending work, journals, and temporary outputs are bounded and close at terminal state.

17. Source authority and known open risks

Planning sources

Open architecture risks

Risk Consequence Required closure before implementation/claim
LayerFS optimized path remains benchmark-private DeltaGit would duplicate semantics Stable reusable boundary and anti-cheat audit
LayerFS exposes only one singleton visible head Independent sessions conflict incorrectly Detached child-root commit or admitted generic named-ref contract
Requested root is not durable before LayerFS dispatch Lost acknowledgement cannot identify the intended child Prepare root/delta, persist CheckpointIntent, then dispatch
No complete mutation-aware workspace boundary Opaque commands can bypass journal Virtual filesystem or honest reconciliation fallback
Native APFS middle insert/delete remains suffix-sensitive Physical workspace may lag canonical checkpoint Virtual primary view or explicit projection fallback
Long retained histories grow storage Per-tool checkpoints become unbounded Measured slope, retention roots, GC specification
One SQLite writer serializes publications High checkpoint concurrency may queue Measure; do not add pools/retries before evidence
TrustedLocalDev has weaker freshness semantics Misleading product safety claim Explicit opt-in, Verified default, exact limitations
Runtime supervision is not sandbox isolation Escaped writes/processes or credential exposure Compose with a real sandbox; record escaped state
Commands/environments contain secrets or exceed bounds Evidence leak or unbounded operation records Prospective caps, private custody, default redaction, oversize failure
Git export identity cache could become stale Wrong Git object reuse Bind cache entries to exact LayerFS and Git formats
Merge/rebase semantics are not designed Same-root concurrent edits can conflict Keep typed stale-head now; design collaboration later

The architecture is eligible for implementation only after the LayerFS maturity gate passes. Until then, this file is a product contract and a requirements consumer—not evidence that DeltaGit or its runtime exists.