asset workspace progress
This commit is contained in:
+175
@@ -0,0 +1,175 @@
|
||||
# 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.
|
||||
@@ -5,6 +5,7 @@ This directory contains packer decision records.
|
||||
Retained packer decision records:
|
||||
|
||||
- [`Concurrency, Observability, and Studio Adapter Boundary Decision.md`](./Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md)
|
||||
- [`Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](./Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md)
|
||||
|
||||
The first packer decision wave was already consolidated into:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user