asset workspace progress

This commit is contained in:
2026-03-24 13:42:44 +00:00
parent 4c8190cc31
commit 59e1ad5ecf
286 changed files with 7156 additions and 8898 deletions
@@ -20,10 +20,11 @@ This specification consolidates the initial packer agenda and decision wave into
2. One asset root contains exactly one anchor `asset.json`.
3. `assets/.prometeu/index.json` is the authoritative registry of registered assets.
4. `asset.json` is the authoritative asset-local declaration.
5. An asset root absent from the registry is `unregistered`.
6. `unregistered` assets are always `excluded` from build participation.
7. Registered assets may be `included` or `excluded` from build participation without losing identity.
8. The baseline build set includes registered assets whose registry entry is marked as build-included.
5. `asset.json` must carry the stable `asset_uuid` identity anchor for that asset root.
6. An asset root absent from the registry is `unregistered`.
7. `unregistered` assets are always `excluded` from build participation.
8. Registered assets may be `included` or `excluded` from build participation without losing identity.
9. The baseline build set includes registered assets whose registry entry is marked as build-included.
## Identity Model
@@ -33,6 +34,12 @@ Each registered asset has:
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
- `included_in_build`: build participation flag persisted in the registry
Identity authority is intentionally split:
- `asset_uuid` is anchored locally in `asset.json`;
- `asset_id` is allocated and persisted by the registry;
- registry-managed location and build participation remain catalog concerns in `index.json`.
The following are not primary identity:
- `asset_name`
@@ -41,6 +48,18 @@ The following are not primary identity:
`asset_name` may still be used by authoring and runtime-facing APIs as a logical reference label.
## Local Identity Anchor
`asset_uuid` is the stable asset-local identity anchor.
Rules:
- `asset_uuid` must be present in `asset.json`;
- `asset_uuid` is stable across relocate and rename flows;
- `asset_uuid` is not allocated from path shape or `asset_name`;
- `asset_uuid` allows the packer to reconcile manual workspace changes with the registry/catalog model;
- `asset_uuid` does not replace registry authority over `asset_id`, build participation, or managed root tracking.
## Relocation and Rename
Moving or renaming an asset root does not change identity.
@@ -62,7 +81,8 @@ Rules:
- it is excluded from the build automatically;
- it is diagnosable;
- it becomes registered only through explicit flow.
- it becomes registered only through explicit flow;
- its local `asset_uuid` still matters for structural validation and future reconcile behavior.
## Build Participation
@@ -94,7 +114,21 @@ Examples:
- duplicate or ambiguous anchors under registered expectations;
- manual copy that creates identity collision;
- registered root missing anchor.
- registered root missing anchor;
- duplicate `asset_uuid` across different asset roots;
- registry/catalog location that no longer matches the asset root carrying the expected `asset_uuid`;
- `asset.json` missing or malformed in a root expected to preserve identity.
## Reconcile Expectations
The packer may need to reconcile registry/catalog state against the authoring workspace.
Rules:
- manual move or rename of an asset root must not imply identity loss by itself;
- reconcile should prefer `asset_uuid` when matching a durable asset identity across changed paths;
- path drift must not silently rebind one registered asset to another distinct `asset_uuid`;
- unresolved identity drift remains diagnosable until explicit repair or successful reconcile.
## Non-Goals
@@ -13,6 +13,7 @@ This specification consolidates the initial packer agenda and decision wave into
The common `asset.json` contract requires these top-level fields:
- `schema_version`
- `asset_uuid`
- `name`
- `type`
- `inputs`
@@ -23,6 +24,19 @@ The common contract may also include:
- `build`
## Meaning of `asset_uuid`
`asset_uuid` is the stable asset-local identity anchor.
Rules:
- it is required;
- it must be stable across relocate and rename flows;
- it is not the project-local runtime artifact identity;
- it is not a substitute for registry-owned `asset_id`;
- it exists so the asset root can preserve identity even when path-based assumptions drift;
- it must remain compatible with packer reconcile behavior and migration flows.
## Meaning of `name`
`name` is the logical asset reference label.
@@ -90,6 +104,17 @@ Rules:
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
- `build` must not hide runtime-relevant semantics.
## Operational State Exclusion
`asset.json` is a declaration artifact, not a catalog cache.
Rules:
- transient UI state must not be stored in `asset.json`;
- registry-managed fields such as `asset_id` and `included_in_build` must not be duplicated into `asset.json`;
- packer cache or snapshot bookkeeping must not be materialized into `asset.json` as normal operational state;
- `asset.json` should remain focused on identity anchoring plus declared authoring/packing behavior.
## Preload
Each registered asset must declare preload intent explicitly.
@@ -44,6 +44,26 @@ Rules:
The normative operational surface is service-based.
The packer is a filesystem-first operational runtime.
Rules:
- the active project may maintain a coherent in-memory operational snapshot;
- normal read requests should be served from that coherent snapshot when the runtime is active;
- the runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring store;
- the durable authoring workspace remains the persisted source of truth after successful commit.
### Embedded Bootstrap Rule
When the packer is embedded inside another host such as Studio, the host must bootstrap the packer integration explicitly.
Rules:
- the embedded packer runtime must receive a typed event bus reference from the host when shared host visibility is part of the integration contract;
- that reference is the baseline path for packer publish/subscribe integration in the embedded host;
- the embedded packer runtime must not quietly create a disconnected parallel event system when host integration expects shared operational visibility;
- in Studio, this shared typed event bus reference is owned by the Studio `Container`.
Baseline core services:
- `init_workspace`
@@ -66,6 +86,26 @@ Operations must distinguish:
This distinction is part of the service semantics and must be visible to the UI.
## Runtime State and Visibility
The packer runtime must make operational freshness explicit.
At minimum, the model should support states equivalent to:
- `healthy`
- `stale`
- `diverged`
- `committing`
- `reconciling`
- `failed`
Rules:
- successful durable commit defines the visibility boundary for committed write state;
- reads must not present torn in-progress writes as committed truth;
- background divergence detection may move a project or asset view into stale/diverged/reconciling state;
- Studio may render these states, but must not invent their semantics.
## Concurrency Model
The packer concurrency model is conservative and project-scoped.
@@ -84,6 +124,13 @@ Rules:
- build/write on the same project is serialized unless a future spec introduces an explicit transactional coordination model;
- background observation may continue while a serialized write lane is active, but it must not publish misleading post-state before commit visibility.
### Write Ownership
- writes on one project execute through a packer-owned write lane;
- caller timing must not define final write interleaving semantics;
- preview generation may occur before the final commit section when safe;
- apply/commit remains the packer-owned visibility boundary.
## Preview/Apply Model
Sensitive mutations use staged intent.
@@ -102,6 +149,7 @@ At minimum, the model should support fields equivalent to:
- `status`
- `summary`
- `runtime_state`
- `affected_assets`
- `diagnostics`
- `proposed_actions`
@@ -118,6 +166,7 @@ Responsibilities:
- report diagnostics/build/cache activity to the UI;
- support live refresh and progress reporting;
- avoid blocking the main UI thread.
- surface operational freshness and reconcile transitions when they affect Studio-visible state.
### Initial Event Set
@@ -135,6 +184,8 @@ The initial structured event set includes:
- `action_failed`
- `progress_updated`
Additional runtime/reconcile state events may exist as the operational runtime evolves, but adapters must preserve their causal meaning instead of collapsing them into generic refresh noise.
### Mutation Serialization
Mutating asset workflows are serialized semantically.
@@ -148,6 +199,7 @@ Rules:
- preview generation may run outside the final commit section, but apply/commit remains serialized;
- build and sensitive mutation apply must not interleave on the same project in a way that obscures final state;
- cancellation or failure must leave the observable project state in a coherent post-operation condition.
- divergence detection must not silently rewrite user-authored workspace content as if it were a normal mutation apply.
### Event Envelope
@@ -169,6 +221,7 @@ Rules:
- `operation_id` is stable for the full lifecycle of one logical operation;
- `sequence` is monotonic within one operation;
- adapters may remap event shapes for UI consumption, but must not invent causal relationships not present in packer events.
- embedded hosts should preserve the same typed event bus reference across packer bootstrap and adapter wiring so subscription and publication stay causally coherent.
### Event Ordering and Coalescing
@@ -42,6 +42,7 @@ Rules:
- migration may be automatic within the supported window;
- unsupported versions fail clearly and early;
- migration failures must be diagnosable in Studio and CI.
- migration may need to preserve or repair identity-bearing fields such as `asset_uuid` without fabricating a different asset identity silently.
## Runtime Compatibility Boundary
@@ -73,6 +74,7 @@ Untrusted until validated:
- hand-edited or legacy declarations;
- imported external project content;
- legacy packer artifacts and control data.
- runtime snapshot observations that have not yet been reconciled against changed workspace files.
Trusted only after:
@@ -80,6 +82,7 @@ Trusted only after:
- structural validation;
- semantic validation;
- version compatibility check.
- reconcile or refresh when divergence between snapshot and filesystem has been detected.
## Plugin and Script Execution
@@ -102,6 +105,7 @@ At minimum, diagnostics should make clear:
- the version found;
- the supported range or expectation;
- whether migration was attempted;
- whether identity-bearing fields or registry/catalog alignment were implicated;
- whether manual action is required;
- whether the failure blocks build or Studio workflow.