176 lines
9.8 KiB
Markdown
176 lines
9.8 KiB
Markdown
# Filesystem-First Operational Runtime and Reconcile Boundary Decision
|
|
|
|
Status: Accepted
|
|
Date: 2026-03-15
|
|
Domain Owner: `docs/packer`
|
|
Cross-Domain Impact: `docs/studio`
|
|
|
|
## Context
|
|
|
|
The current packer model already has the right core separation:
|
|
|
|
- `assets/.prometeu/index.json` is the authoritative registry/catalog for managed assets;
|
|
- each asset root is anchored by `asset.json`;
|
|
- `asset.json` is the authoring-side declaration of how that asset is packed;
|
|
- Studio is meant to consume packer-owned operational semantics instead of recreating them locally.
|
|
|
|
What is still missing is a clear architectural decision for how the packer should behave operationally at runtime.
|
|
|
|
The repository now needs an answer to these questions:
|
|
|
|
1. should the packer remain a collection of direct filesystem services, recomputing state per request;
|
|
2. should the packer become a pure database-style system that displaces the open filesystem workflow;
|
|
3. or should it become a filesystem-first operational runtime that maintains an in-memory snapshot while preserving the workspace as the durable authoring surface.
|
|
|
|
The wrong answer here would create product friction.
|
|
|
|
If the packer behaves like a pure database, it will fight the real creative workflow where developers:
|
|
|
|
- edit files with their preferred tools;
|
|
- move directories manually when needed;
|
|
- inspect and version workspace files directly;
|
|
- expect the Studio to help organize work, not imprison it.
|
|
|
|
At the same time, if the packer stays purely filesystem-per-call, it will remain too expensive, too incoherent under concurrent use, and too weak as the operational source of truth for Studio.
|
|
|
|
## Decision
|
|
|
|
The following direction is adopted:
|
|
|
|
1. `prometeu-packer` remains `filesystem-first`.
|
|
2. The packer becomes a `project-scoped operational runtime`, not a pure database.
|
|
3. The packer maintains an in-memory project snapshot for live operational reads and write coordination.
|
|
4. The durable authoring workspace on disk remains the final persisted source of truth.
|
|
5. The packer owns request/response read and write APIs over that runtime snapshot.
|
|
6. Writes execute through a packer-owned project write lane and become durably visible only after commit succeeds.
|
|
7. The packer will support background divergence detection between runtime snapshot and filesystem state.
|
|
8. Divergence detection must surface reconcile state explicitly; it must not silently invent or hide semantic repairs.
|
|
9. Studio remains a frontend consumer of packer responses, commands, and events.
|
|
10. When embedded inside Studio, the packer runtime is bootstrapped with a typed event bus reference supplied by the Studio bootstrap container.
|
|
|
|
## Adopted Constraints
|
|
|
|
### 1. Filesystem-First Authority
|
|
|
|
- the asset workspace under `assets/` remains the authoring environment;
|
|
- `asset.json` remains the asset-local declaration contract;
|
|
- `assets/.prometeu/index.json` remains the authoritative registry/catalog for managed assets;
|
|
- the packer runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring format.
|
|
|
|
### 2. Identity and Declaration Split
|
|
|
|
- `asset_id`, `included_in_build`, and registry-managed location tracking remain registry/catalog concerns;
|
|
- `asset.json` remains primarily a declaration of the asset contract and packing inputs/outputs;
|
|
- `asset.json` may carry the asset-local identity anchor needed for reconcile, specifically `asset_uuid`;
|
|
- `asset.json` must not become a dumping ground for transient UI state, cache state, or catalog-derived bookkeeping that belongs in `index.json` or other packer-owned control files.
|
|
|
|
### 3. Snapshot-Backed Read Semantics
|
|
|
|
- normal read APIs should serve from a coherent in-memory project snapshot;
|
|
- the packer must not require a full workspace recomputation for every normal read call once the runtime is active;
|
|
- concurrent reads may proceed when they observe a coherent snapshot generation;
|
|
- reads must not expose torn intermediate write state as committed truth.
|
|
|
|
### 4. Packer-Owned Write Execution
|
|
|
|
- write operations on one project are coordinated by the packer, not by caller timing;
|
|
- the baseline policy remains a single-writer semantic lane per project;
|
|
- write intent may compute previews before final commit when safe;
|
|
- final apply/commit remains serialized per project;
|
|
- successful durable commit defines post-write visibility.
|
|
|
|
### 5. Durable Commit Boundary
|
|
|
|
- the packer runtime may stage write changes in memory before disk commit;
|
|
- partially applied intermediate state must not be presented as durably committed truth;
|
|
- commit failure must leave the project in an explicitly diagnosable condition;
|
|
- recovery and reconcile rules must be designed as packer behavior, not delegated to Studio guesswork.
|
|
|
|
### 6. Divergence Detection and Reconcile
|
|
|
|
- a future packer-owned background observation path may detect divergence between runtime snapshot and filesystem state;
|
|
- this path exists to keep the runtime honest with respect to manual or external edits;
|
|
- divergence must result in explicit runtime state such as stale, diverged, reconciling, or failed;
|
|
- the packer must not silently rewrite user content just because divergence was observed;
|
|
- reconcile is an explicit packer-owned behavior and must preserve causality in events and responses.
|
|
|
|
### 7. Studio Consumer Boundary
|
|
|
|
- Studio consumes packer read responses, write outcomes, and packer-native lifecycle events;
|
|
- Studio may render stale/diverged/reconciling states, but must not invent packer-side reconcile semantics;
|
|
- Studio must not become the owner of filesystem-vs-snapshot conflict resolution;
|
|
- the Studio integration contract should remain command-oriented and event-driven.
|
|
|
|
### 8. Embedded Event Bus Bootstrap
|
|
|
|
- when the packer is embedded inside Studio, it must receive a typed event bus reference during bootstrap instead of creating an unrelated local event system;
|
|
- that reference is used for packer event publication and any packer-side subscription/unsubscription behavior needed by the embedded runtime;
|
|
- in Studio, the owner of that typed event bus reference is the application container;
|
|
- the Studio `Container` must be initialized as part of Studio boot before packer-backed workspaces or adapters start consuming packer services.
|
|
|
|
## Why This Direction Was Chosen
|
|
|
|
- It preserves the developer's open creative workflow around normal files and directories.
|
|
- It keeps the packer useful as an organizing and coordinating system instead of turning it into an opaque silo.
|
|
- It allows fast and coherent reads for Studio and tooling.
|
|
- It gives write coordination, commit visibility, and operational causality one owner.
|
|
- It creates a realistic path toward future background divergence detection without pretending that the filesystem stopped mattering.
|
|
|
|
## Explicit Non-Decisions
|
|
|
|
This decision does not define:
|
|
|
|
- the final class/module names of the packer runtime implementation;
|
|
- the final executor/thread primitive used internally;
|
|
- the exact event vocabulary for all future reconcile states;
|
|
- the final automatic-vs-manual reconcile policy for each drift scenario;
|
|
- a watch-service or daemon transport implementation;
|
|
- remote or multi-process synchronization;
|
|
- a pure database persistence model.
|
|
|
|
## Implications
|
|
|
|
- the packer runtime track must preserve `index.json` plus `asset.json` as the durable workspace artifacts;
|
|
- `asset.json` should evolve carefully to support local identity anchoring without absorbing catalog-only fields;
|
|
- the runtime snapshot should be described as an operational cache/projection with authority for live service behavior, not as a new authoring truth;
|
|
- mutation, doctor, build, and read services should converge on the same runtime state model;
|
|
- future drift detection work must be designed together with diagnostics, refresh, and reconcile surfaces in Studio.
|
|
- embedded Studio wiring must preserve one container-owned typed event bus reference instead of fragmented packer-local bus ownership.
|
|
|
|
## Propagation Targets
|
|
|
|
Specs:
|
|
|
|
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
|
- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
|
|
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
|
- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
|
|
|
|
Plans:
|
|
|
|
- [`../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md)
|
|
|
|
Cross-domain references:
|
|
|
|
- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md)
|
|
|
|
Implementation surfaces:
|
|
|
|
- future packer project-runtime/bootstrap code
|
|
- snapshot-backed read services
|
|
- project write-lane and durable commit pipeline
|
|
- drift detection and reconcile state reporting
|
|
- Studio packer adapters for stale/diverged/reconciling operational states
|
|
- Studio bootstrap/container wiring for the shared typed event bus reference
|
|
|
|
## Validation Notes
|
|
|
|
This decision is correctly implemented only when all of the following are true:
|
|
|
|
- developers may continue to inspect and edit asset workspace files directly;
|
|
- packer reads are coherent without requiring full recomputation on each normal request;
|
|
- same-project writes remain serialized by the packer;
|
|
- Studio does not observe torn committed truth during write activity;
|
|
- divergence between runtime snapshot and filesystem state can be detected and surfaced explicitly;
|
|
- Studio remains a consumer of packer-owned reconcile and lifecycle semantics rather than inventing them.
|