Foundations: Workspace, Runtime, and Build

Original Problem

The packer domain accumulated a long implementation wave covering workspace control, asset identity, scanning, mutations, diagnostics, deterministic planning, runtime snapshots, and cache reuse.

The historical PR chain was useful while the repository was converging, but it stopped being a good onboarding surface:

too much knowledge was spread across execution slices;
too much reasoning depended on chronological reconstruction;
too little of that knowledge was available as one stable mental model.

Consolidated Decision

The stable packer foundation is:

the workspace stays open and filesystem-first;
assets/.prometeu/index.json owns managed identity and inclusion state;
each asset root is anchored by asset.json;
the packer runtime serves coherent snapshot-backed reads;
writes are coordinated by the packer and become visible after durable commit;
build outputs are derived deterministically from validated, packer-owned state.

Final Model

1. Workspace and Identity

asset_id is the stable managed identifier used for ordering, inclusion, and runtime-facing tables;
asset_uuid is the local identity anchor that helps reconcile the same logical asset across path movement;
asset_name is the logical human-facing identifier and is not a substitute for managed identity;
asset.json describes authoring intent, not registry-owned bookkeeping.

2. Read and Write Authority

normal reads come from a coherent runtime snapshot rather than from ad hoc filesystem scans;
the filesystem still matters because it remains the durable authoring surface;
writes flow through packer-owned preview/apply semantics and one project-scoped serialized lane.

3. Deterministic Build Path

only validated managed assets enter the build path;
asset ordering is deterministic by increasing asset_id;
runtime-facing artifacts are emitted from canonical packer-owned planning and materialization rules;
companion artifacts mirror build authority rather than define parallel truth.

4. Runtime Snapshot Evolution

The later runtime wave refined the first foundation:

runtime state became explicitly project-scoped;
snapshot updates happen after successful write commit;
query services read from that runtime state;
cache layers exist to accelerate the same ownership model, not to bypass it.

Examples

Example: Why relocation does not create a new asset

If an asset root moves on disk, the packer should preserve the managed identity when the move is a relocation of the same logical asset.

That is why:

the registry owns stable managed identity;
path is mutable operational state;
relocation updates root tracking without inventing a new asset_id.

Example: Why filesystem order cannot define build order

Two equivalent workspaces may be traversed in different directory order. The build must still emit the same asset_table and payload layout.

That is why deterministic ordering is tied to managed identity, not traversal order.

Common Pitfalls and Anti-Patterns

Treating asset_name as if it were a stable runtime identifier.
Moving registry-owned fields into asset.json.
Recomputing semantic read models directly from Studio-side filesystem heuristics.
Letting build order depend on traversal order, cache insertion order, or UI ordering.
Treating cache state as semantic authority instead of as an optimization.

4.3 KiB Raw Blame History