asset workspace progress
This commit is contained in:
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user