92 lines
4.3 KiB
Markdown
92 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
1. the workspace stays open and filesystem-first;
|
|
2. `assets/.prometeu/index.json` owns managed identity and inclusion state;
|
|
3. each asset root is anchored by `asset.json`;
|
|
4. the packer runtime serves coherent snapshot-backed reads;
|
|
5. writes are coordinated by the packer and become visible after durable commit;
|
|
6. 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.
|
|
|
|
## References
|
|
|
|
- Specs:
|
|
- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
|
|
- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
|
|
- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
|
|
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
|
- Related learn:
|
|
- [`./mental-model-packer.md`](./mental-model-packer.md)
|
|
- [`./mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
|