scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-09-19 00:03:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
fabro/docs-internal/run-directory-keys.md
Bryan Helmkamp c1507b57a3
refactor(scratch): remove store-backed diff and blob cache writes 
Stop writing scratch final.patch files now that diffs are projected from
run state, and remove the unused cache/artifacts/values plumbing while
keeping runtime/blobs materialization intact.

Update tests and run-directory docs to match the current scratch contract.
2026-04-07 22:31:59 -04:00

2.3 KiB
Raw Blame History

Run Scratch Files

This document maps the files that still live under a run scratch directory. Durable run state lives in the run store and metadata branch; scratch is mostly local runtime state and caches.

Scope:

  • Scratch root: ~/.fabro/scratch/YYYYMMDD-{run_id}/
  • This covers local run files only
  • Persistent store keys live in lib/crates/fabro-store/src/keys.rs
  • Artifact object-store keys live in lib/crates/fabro-store/src/artifact_store.rs

There is no _init.json anymore. Run existence in the database is determined by stored run events, and local scratch directories are managed separately under scratch/.

Root-Level Files

File Purpose Source
workflow_bundle.json Bundled workflow input used by start to restore workflow_path and bundled child workflows/files Written during create from the resolved workflow bundle
run.pid Legacy detached-run pid file from older runs Legacy only; current flows do not rely on it

Local-Only Directories

These paths are local runtime state, not canonical event projections.

Path Purpose
worktree/ Git worktree used by checkpointed runs
runtime/blobs/ Materialized local blob payloads for file-backed fabro+blob:// references
runtime/worker.stderr.log Server-managed worker stderr capture
cache/artifacts/files/ Captured artifact files organized by node and retry
nodes/{manager_node}_{visit}/child/ Nested scratch root for manager-loop child workflows

Reconstructed / Exported Files

These names are still real, but they are no longer live scratch files by default:

  • Metadata branch files such as run.json, start.json, checkpoint.json, and retro.json
  • fabro store dump exports such as run.json, start.json, status.json, checkpoint.json, conclusion.json, retro.json, events.jsonl, and per-node prompt/response/status/stdout/stderr files
  • Retro-agent temp uploads named progress.jsonl, checkpoint.json, run.json, and start.json inside the retro sandbox

Notes

  • Artifact binaries are no longer stored in the SlateDB keyspace. They live in ArtifactStore; the run scratch tree only contains local cached copies when a workflow stage writes them to disk.
  • Final diffs for checkpointed runs are projected from the run store; they are no longer written as scratch files.