Project storage runtime: ADR-0015 + ADR-0004/0007 amendments
Designs track-2 lifecycle and persistence end-to-end: per-command write-through to db+yaml+csv+history.log gated by the combined db persistence logic with commit-db-last ordering; existence-only load with explicit rebuild command; --resume CLI flag backed by <data-root>/last_project; in-TUI list-with-browse picker; lock file for single-instance enforcement; fatal-banner-then-quit failure model (with --resume making restart cheap); fatal CSV row-load errors with full diagnosis; YYYYMMDD-word-word-word temp naming with display-name prettifier; collision-checked names for both temp and user-supplied projects. Project name lives only on the filesystem (not duplicated in YAML). ADR-0004 and ADR-0007 amended in place. requirements.md and CLAUDE.md updated; OOS-6 (global rolling history) tracked as deferred.
This commit is contained in:
@@ -2,7 +2,10 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
Accepted. Amended by [ADR-0015](0015-project-storage-runtime.md) —
|
||||
see the "Amendments" section at the end of this file for the
|
||||
specifics; the rest of this ADR remains the canonical reference
|
||||
for the project file format.
|
||||
|
||||
## Context
|
||||
|
||||
@@ -62,3 +65,38 @@ A project is a directory containing:
|
||||
- The `version` field opens the door to format migrations as the
|
||||
app evolves; old projects load by running registered migrators
|
||||
in sequence.
|
||||
|
||||
## Amendments
|
||||
|
||||
### Amendment 1 — runtime data flow ([ADR-0015](0015-project-storage-runtime.md))
|
||||
|
||||
The phrase "`playground.db` is a derived artifact" describes a
|
||||
*recovery* property: the database can always be reconstructed
|
||||
from `project.yaml` + `data/`. It does not describe runtime
|
||||
data flow.
|
||||
|
||||
At write time, all persistence targets (the SQLite database,
|
||||
`project.yaml`, the relevant `data/<table>.csv` files, and
|
||||
`history.log`) share a single source — the user's command — and
|
||||
are written alongside one another in a defined order (see
|
||||
ADR-0015 §6). None of the text files is "downstream" of the
|
||||
database at write time.
|
||||
|
||||
### Amendment 2 — `.db` rebuild trigger ([ADR-0015](0015-project-storage-runtime.md))
|
||||
|
||||
The "rebuild with confirmation when `.db` exists" semantics in
|
||||
the original Decision section are replaced by a simpler model:
|
||||
|
||||
- On load, if `playground.db` exists, it is opened as-is.
|
||||
- On load, if `playground.db` is missing, it is rebuilt
|
||||
silently from `project.yaml` + `data/`.
|
||||
- A new app-level command, `rebuild`, explicitly discards the
|
||||
current `playground.db` and reconstructs it from the text
|
||||
sources, with a confirmation prompt and a summary of what
|
||||
will be reconstructed.
|
||||
|
||||
The application does not attempt to detect drift between the
|
||||
database and the text sources automatically. `rebuild` is the
|
||||
explicit user-driven path for cases where drift exists (git
|
||||
pull over an existing `.db`, hand edits to YAML/CSV, recovery
|
||||
after a rare failure described in ADR-0015 §6).
|
||||
|
||||
Reference in New Issue
Block a user