Remove Git usage from graph flows: adopt filesystem-based persistence (no automated commits)

[rowan-stein]

User request

Remove any Git usage from the graph-related flows. Changes must continue to be recorded on disk, but there should be no automated commits. During startup, do not select a Git branch for the graph data directory. Eliminate any other Git-dependent operations in these flows.

Summary of current state (from research)

• Graph persistence is Git-backed via GitGraphRepository (packages/platform-server/src/graph/gitGraph.repository.ts).
• Startup ensures/creates a Git repo and checks out a configured branch (GRAPH_BRANCH), committing initial contents if needed.
• Every graph upsert stages and commits changes with Git; rollback uses git restore.
• Reads may fall back to HEAD using git ls-tree and git show when the working tree is inconsistent.
• Controllers and docs refer to Git-specific errors like COMMIT_FAILED.

Proposed changes (Git-free persistence)

1. Configuration

• Introduce GRAPH_DATA_PATH (default ./data/graph).
• Replace GRAPH_BRANCH with GRAPH_DATASET (default main) and/or an active-dataset.txt pointer in GRAPH_DATA_PATH.
• Deprecate GRAPH_BRANCH (map to GRAPH_DATASET if set, otherwise ignore).

2. Filesystem layout

<GRAPH_DATA_PATH>/
  active-dataset.txt
  datasets/
    <dataset>/
      graph.meta.yaml
      variables.yaml (optional)
      nodes/*.yaml
      edges/*.yaml
      snapshots/
        <version>/ ... snapshot content ...

3. Repository implementation

• Add FsGraphRepository to replace GitGraphRepository with no Git invocations.
• Atomic writes: temp files + rename + directory fsync; safe deletes.
• Snapshot/fallback: after each committed upsert, record a journal and optionally snapshot; readers fall back to the latest committed snapshot if working files are corrupted.
• Concurrency: keep a per-dataset lock file (e.g., .graph.lock).
• Error semantics: replace COMMIT_FAILED with PERSIST_FAILED; keep LOCK_TIMEOUT.

4. DI & controllers

• Bind GraphRepository to FsGraphRepository in graph-domain.module.ts.
• Update controllers to remove Git-specific error mapping and to reflect new semantics.

5. Migration

• Provide a graph-migrate-to-fs utility or one-shot startup flag:
  • Read current working state and write it into the new dataset path using atomic writes.
  • Optionally archive .git to .git.backup-<timestamp> and leave deletion to operators.

6. Documentation

• Replace docs/graph/git-store.md with docs/graph/fs-store.md describing the new model.
• Update packages/platform-server/README.md to remove Git semantics and COMMIT_FAILED references.

Acceptance criteria

• No graph flow executes any Git command or requires a .git directory.
• Server startup requires no branch selection; active graph is resolved via GRAPH_DATASET and/or active-dataset.txt.
• Graph changes persist to disk and survive restarts; versioning is maintained.
• Migration preserves existing graph data without loss.

Open questions

• Do we need multiple datasets (previously branches) or a single active dataset suffices initially?
• Is a snapshot history needed for user features (rollback/audit) or primarily for crash safety?
• May the migration tool read from Git one last time to ensure correctness, or must it avoid Git entirely as well?
• Expected scale/frequency of writes to calibrate snapshot cadence.

Implementation plan (single PR)

• Add new config keys and deprecate GRAPH_BRANCH.
• Implement FsGraphRepository with atomic write + snapshot fallback.
• Switch DI to use FsGraphRepository and update controllers.
• Add migration tool/flag and docs.
• Update references and remove Git-specific docs/errors.
• Add integration test that runs without a .git dir for graph data.

Linked research provides detailed file paths and methods for current Git interactions.