prometeu-studio/docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md

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/3. Asset Declaration and Virtual Asset Contract Specification.md
• ../specs/5. Diagnostics, Operations, and Studio Integration Specification.md
• ../specs/6. Versioning, Migration, and Trust Model Specification.md

Plans:

• ../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md

Cross-domain references:

• ../../studio/specs/4. Assets Workspace Specification.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.