Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

updated packer specs

Browse Source
This commit is contained in:
bQUARKz 2026-03-11 09:48:51 +00:00
parent f27b28c516
commit e3389e78b6
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
10 changed files with 951 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/packer/learn/README.md
View File

@ -45,3 +45,10 @@ If content grows, prefer:
- and consolidation of duplicated explanations.
The goal is a maintainable learning surface, not a passive archive.
## Current Learning Path
Start here:
1. [`mental-model-packer.md`](./mental-model-packer.md)
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)

95
docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md Normal file
View File

@ -0,0 +1,95 @@
# Asset Identity and Runtime Contract
This document explains the point that is easiest to get subtly wrong:
- `asset_id` is the stable artifact identity;
- `asset_name` is still a logical code-facing reference.
If you flatten those two concepts into one, the architecture starts drifting immediately.
## The Stable Side: `asset_id`
`asset_id` is allocated by the packer registry.
It is stable within the project and appears in runtime-facing artifacts.
Why this matters:
- preload uses `asset_id`;
- artifact identity survives move and rename;
- build outputs remain structurally stable even when authoring layout changes.
`asset_id` is the answer to:
> “Is this the same asset as before?”
## The Logical Side: `asset_name`
`asset_name` remains useful because game-facing code and runtime APIs still refer to assets by name in normal flows.
Why this matters:
- authors need a readable label;
- game code usually references assets semantically, not by integer literal;
- runtime lookup still uses names in parts of the current operational surface.
`asset_name` is the answer to:
> “What do humans and source code call this asset?”
## Why Not Use Only One Of Them?
If you use only `asset_name`:
- rename becomes identity breakage;
- preload/bootstrap integrity becomes fragile;
- build artifacts depend too much on mutable author intent.
If you use only `asset_id` everywhere today:
- source code becomes less ergonomic;
- authoring workflows become harder to read;
- the current runtime/game-facing API model would need stronger compile-time lowering infrastructure.
So the current architecture intentionally keeps both:
- stable identity for artifacts;
- logical naming for authoring and API usage.
## What Actually Happens In The Artifact?
The runtime-facing asset table carries both:
- `asset_id`
- `asset_name`
But they play different roles.
`asset_id`:
- defines stable identity;
- is used for preload/bootstrap integrity.
`asset_name`:
- stays in the table as descriptive/API-facing metadata;
- supports name-based lookup where that still exists.
## Why This Is Still Not The End Of The Story
There is still an open language/toolchain question:
- should source-level asset references remain name-based forever?
- or should the compiler eventually lower known references to stable IDs or resource handles?
That is a separate problem from the packer artifact identity model.
It belongs to language/frontend and runtime API design, not to the core packer identity rules.
## Practical Rule
When reading or implementing packer behavior, use this checklist:
- if the question is about stable artifact identity, think `asset_id`;
- if the question is about source naming or human-facing lookup, think `asset_name`;
- if the question is about preload/bootstrap correctness, prefer `asset_id`;
- if the question is about runtime/game API ergonomics, `asset_name` may still be intentionally present.

87
docs/packer/learn/mental-model-packer.md Normal file
View File

@ -0,0 +1,87 @@
# Packer Mental Model
The packer is not a cartridge shipper, not a runtime reader, and not a random file janitor.
It is the system that turns an asset workspace into stable asset artifacts.
The easiest way to understand it is through five questions.
## 1. What is the unit of management?
The unit is the managed asset root.
One managed asset:
- lives in one asset root directory;
- has one anchor `asset.json`;
- may include many internal files as inputs.
This is why an atlas, image bank, or grouped sound bundle can still be one asset.
The managed asset is the output unit, not each source file.
## 2. Where is the source of truth?
There are two different truths for two different jobs:
- `assets/.prometeu/index.json` tells the packer which assets are officially managed;
- each `asset.json` tells the packer what that asset declares locally.
This split matters.
Without it, copy/move/adopt flows become ambiguous very quickly.
## 3. What is the difference between `asset_id` and `asset_name`?
They are not the same thing.
`asset_id` is the stable identity.
It survives moves and renames.
`asset_name` is the logical reference label.
It is the thing source code and runtime-facing APIs may still use today.
That means:
- renaming `asset_name` is not an identity change;
- but it can still be an API-visible change.
This is the most important distinction to keep in your head while reading the packer and runtime contracts.
## 4. What is the runtime-facing artifact?
`assets.pa`.
That is the artifact the runtime reads.
It is authoritative for runtime-facing asset metadata.
Companion JSON files exist for Studio and tooling, but they do not replace the contract inside `assets.pa`.
## 5. Why is determinism so important?
Because the packer is not just a converter.
It is part of the contract chain between authoring, Studio, shipping, and runtime.
If equivalent inputs can produce different outputs accidentally, then:
- debugging becomes harder;
- caching becomes unreliable;
- artifact review gets noisy;
- runtime compatibility becomes more fragile.
That is why the packer decisions keep preferring:
- explicit declaration over inference;
- stable identity over convenience;
- canonical serialization over incidental serializer behavior;
- preview/apply over silent mutation.
## How To Read The Packer Specs
Use this order:
1. domain and boundary
2. workspace and identity
3. asset declaration
4. build artifacts
5. diagnostics and Studio integration
6. versioning and trust
That sequence moves from “what the packer is” to “how it behaves” to “how it stays safe over time”.

76
docs/packer/specs/1. Domain and Artifact Boundary Specification.md Normal file
View File

@ -0,0 +1,76 @@
# Domain and Artifact Boundary Specification
Status: Draft
Scope: Packer domain core boundary
Purpose: Define what the packer owns, what it emits, and where its responsibility stops.
## Authority and Precedence
This specification is grounded in:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
- [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md)
- [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md)
Runtime-side reading semantics for `assets.pa` are defined upstream in `../runtime/docs/runtime/specs/13-cartridge.md` and `../runtime/docs/runtime/specs/15-asset-management.md`.
## Normative Inputs
- project workspace with `assets/`
- packer registry and control data under `assets/.prometeu/`
- managed asset roots anchored by `asset.json`
## Core Rules
1. The packer owns asset workspace management and artifact production.
2. The packer emits the runtime-facing asset artifact `assets.pa`.
3. The packer may emit companion build artifacts for Studio and tooling.
4. The packer does not own cartridge shipping/publication.
5. A future shipper is a consumer of packer artifacts, not a co-author of the asset contract.
6. Runtime reading semantics are not redefined by the packer.
7. The packer must stop at artifact publication, not cartridge assembly.
## Packer-Owned Artifacts
The packer owns production of at least:
- `assets.pa`
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
- `asset.json`
- `assets/.prometeu/index.json`
## Runtime-Facing Boundary
`assets.pa` is the authoritative runtime-facing artifact.
Rules:
- the internal header of `assets.pa` is the runtime-facing source of truth for asset table and preload data;
- companion JSON outputs must not replace the internal header as the runtime contract;
- offsets and preload semantics must remain aligned with runtime specs.
## Future Shipper Boundary
The future shipper may consume packer artifacts to assemble cartridges.
Rules:
- the packer must not depend on a concrete shipper implementation now;
- shipper-specific workflow detail is deferred;
- published artifact names and meanings must remain documented and stable enough for later consumption.
## Non-Goals
- cartridge assembly flow
- package distribution format design
- runtime asset loading implementation detail
## Exit Criteria
This specification is complete enough when:
- packer ownership is unambiguous;
- runtime-facing artifact authority is explicit;
- future shipper integration is bounded without overdesign.

98
docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md Normal file
View File

@ -0,0 +1,98 @@
# Workspace, Registry, and Asset Identity Specification
Status: Draft
Scope: Managed asset roots, registry authority, and stable identity
Purpose: Define how the packer recognizes, tracks, and preserves asset identity.
## Authority and Precedence
This specification is grounded in:
- [`001-asset-workspace-registry-and-stable-identity-decision.md`](../decisions/001-asset-workspace-registry-and-stable-identity-decision.md)
## Normative Inputs
- `assets/`
- `assets/.prometeu/index.json`
- per-asset `asset.json`
## Core Rules
1. One managed asset equals one asset root directory.
2. One asset root contains exactly one anchor `asset.json`.
3. `assets/.prometeu/index.json` is the authoritative registry of managed assets.
4. `asset.json` is the authoritative asset-local declaration.
5. An asset root absent from the registry is not part of the managed build set.
## Identity Model
Each managed asset has:
- `asset_id`: stable project-local identity
- `asset_uuid`: stable long-lived identity for migration/tooling scenarios
The following are not primary identity:
- `asset_name`
- filesystem path
- internal input file names
`asset_name` may still be used by authoring and runtime-facing APIs as a logical reference label.
## Relocation and Rename
Moving or renaming an asset root does not change identity.
Rules:
- `asset_id` remains unchanged;
- `asset_uuid` remains unchanged;
- registry location is updated;
- relocation is not recreation.
Renaming `asset_name` is an API-visible change, but not an identity change.
## Orphan Anchors
An `asset.json` without a corresponding registry entry is an orphan declaration.
Rules:
- it does not enter the build automatically;
- it is diagnosable;
- it is adoptable only through explicit flow.
## Asset ID Allocation
`asset_id` allocation is registry-owned and strictly monotonic within a project.
Rules:
- allocation occurs at registration time;
- issued IDs are not silently recycled;
- allocator state is persisted in the registry;
- rollback is not baseline behavior.
## Structural Conflicts
Identity-bearing conflicts are structural errors.
Examples:
- duplicate or ambiguous anchors under managed expectations;
- manual copy that creates identity collision;
- registered root missing anchor.
## Non-Goals
- full `asset.json` schema
- asset format-specific metadata
- UI/editor workflow detail
## Exit Criteria
This specification is complete enough when:
- managed asset boundaries are unambiguous;
- registry authority is explicit;
- identity survives relocation without ambiguity.

146
docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md Normal file
View File

@ -0,0 +1,146 @@
# Asset Declaration and Virtual Asset Contract Specification
Status: Draft
Scope: Common `asset.json` contract
Purpose: Define the shared declaration model for raw and virtual assets.
## Authority and Precedence
This specification is grounded in:
- [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md)
## Core Rules
The common `asset.json` contract requires these top-level fields:
- `schema_version`
- `name`
- `type`
- `inputs`
- `output`
- `preload`
The common contract may also include:
- `build`
## Meaning of `name`
`name` is the logical asset reference label.
Rules:
- it is required;
- it is not the stable artifact identity;
- it may still be used by runtime-facing APIs and source-level workflows.
## Meaning of `type`
`type` identifies the authoring-side asset family.
Rules:
- it is not the runtime bank identity;
- the runtime-facing technical target belongs in `output.format`.
Examples:
- `image_bank`
- `sound_bank`
## Inputs
`inputs` is a structured object keyed by semantic role.
Rules:
- each key names an input role such as `sprites`, `palettes`, or `sources`;
- each value is a list of paths;
- paths are relative to the asset root;
- even a single input is represented as a list.
This model supports grouped virtual assets such as atlases and bank-style assets.
## Output
`output` is the runtime-relevant output declaration.
Required baseline fields:
- `output.format`
- `output.codec`
Optional baseline field:
- `output.metadata`
Rules:
- `output.format` defines the semantic/runtime format contract;
- `output.codec` defines storage/extraction behavior;
- `output.metadata` carries runtime-relevant format-specific detail;
- codec must remain explicit and must not be hidden inside format naming.
## Build
`build` is optional and process-oriented.
Rules:
- it may describe how authoring inputs are transformed or organized;
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
- `build` must not hide runtime-relevant semantics.
## Preload
Each managed asset must declare preload intent explicitly.
Baseline shape:
```json
{
"preload": {
"enabled": true
}
}
```
Rules:
- `preload.enabled` is required and boolean;
- preload participation is declared, not inferred;
- richer preload policy fields are deferred.
## Defaults and Materialization
Defaults that affect runtime-visible behavior must not remain hidden.
Rules:
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
- if materialized later, the resulting artifact must expose effective values explicitly.
## Versioning
The `asset.json` schema is versioned independently from:
- registry schema
- runtime-facing artifact schema
- format contract versions
Format-specific contracts evolve through values such as `TILES/indexed_v1`.
## Non-Goals
- field-level format schemas for every output family
- rich preload policies
- source-language lowering behavior for asset references
## Exit Criteria
This specification is complete enough when:
- the common `asset.json` shape is stable;
- raw and virtual assets share a coherent baseline contract;
- format-specific specs can build on it cleanly.

142
docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md Normal file
View File

@ -0,0 +1,142 @@
# Build Artifacts and Deterministic Packing Specification
Status: Draft
Scope: Runtime-facing artifacts and deterministic build behavior
Purpose: Define how the packer emits `assets.pa` and companion artifacts.
## Authority and Precedence
This specification is grounded in:
- [`003-build-artifacts-and-deterministic-packing-decision.md`](../decisions/003-build-artifacts-and-deterministic-packing-decision.md)
Runtime-side reading semantics remain upstream in:
- `../runtime/docs/runtime/specs/13-cartridge.md`
- `../runtime/docs/runtime/specs/15-asset-management.md`
## Core Rules
1. `assets.pa` is the authoritative runtime-facing artifact.
2. Companion JSON files do not replace the internal header as the runtime contract.
3. The global asset table order is deterministic by increasing `asset_id`.
4. The runtime-facing `asset_id` is the same stable `asset_id` allocated by the packer registry.
## `assets.pa` Structure
Baseline structure:
```text
[fixed binary prelude]
[canonical JSON header]
[binary payload region]
```
### Prelude Fields
The baseline prelude includes:
- `magic`
- `schema_version`
- `header_len`
- `payload_offset`
- `flags`
- `reserved`
Rules:
- `flags` and `reserved` exist from day 1;
- `flags = 0` unless later specified otherwise;
- `reserved = 0` unless later specified otherwise;
- `header_checksum` is not part of the baseline envelope contract.
## Canonical JSON Header
The header is serialized canonically.
Rules:
- UTF-8 encoding;
- no extra whitespace;
- object keys sorted lexicographically;
- arrays preserve declared order;
- canonicalization applies recursively;
- runtime-facing header values in v1 must avoid floating-point numbers.
## Header Contents
The header carries:
- `asset_table`
- `preload`
### Asset Table
`asset_table` is emitted as a deterministically ordered list of asset entries.
Rules:
- one entry per managed asset in the current build set;
- no secondary runtime-only identity layer;
- no synthetic dense reindexing layer;
- `asset_name` remains present as logical/API-facing metadata.
### Preload
Preload is emitted deterministically from per-asset declaration.
Rules:
- assets with `preload.enabled = false` do not appear in emitted preload data;
- assets with `preload.enabled = true` do appear;
- preload ordering is deterministic by increasing `asset_id`.
## Companion Artifacts
The baseline companion artifacts are:
- `build/asset_table.json`
- `build/preload.json`
- `build/asset_table_metadata.json`
Rules:
- `build/asset_table.json` mirrors `header.asset_table` 1:1;
- `build/preload.json` mirrors `header.preload` 1:1;
- `build/asset_table_metadata.json` is tooling-only;
- richer tooling data must not be added to the 1:1 mirror files.
## Alignment and Offsets
Alignment exists only when explicitly required by spec.
Rules:
- there is no implicit baseline alignment beyond envelope and format requirements;
- any required alignment must be normative and visible;
- emitted offsets are always relative to the payload region, never the start of the full file.
## Determinism
Equivalent build inputs must produce equivalent outputs.
Rules:
- no filesystem iteration dependence;
- no hidden defaults that affect output;
- no usage-based hot-first packing in the baseline contract;
- determinism is preferred over speculative physical-layout optimization.
## Non-Goals
- per-format payload internals for every output family
- future locality optimization policy
- cartridge-level integrity/signature strategy
## Exit Criteria
This specification is complete enough when:
- runtime-facing artifact authority is explicit;
- companion artifacts are bounded;
- emitted ordering and header behavior are deterministic.

156
docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md Normal file
View File

@ -0,0 +1,156 @@
# Diagnostics, Operations, and Studio Integration Specification
Status: Draft
Scope: Diagnostics, service operations, and Studio-facing event/reporting model
Purpose: Define how the packer exposes safe operational behavior to Studio and tooling.
## Authority and Precedence
This specification is grounded in:
- [`004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md`](../decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md)
- [`005-incremental-build-cache-and-watch-model-decision.md`](../decisions/005-incremental-build-cache-and-watch-model-decision.md)
- [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md)
## Diagnostics Model
Diagnostics are divided into:
- structural managed-world errors;
- advisory workspace hygiene diagnostics.
Rules:
- structural managed-world errors block builds;
- hygiene findings do not block baseline builds by default;
- workspace scanning is broader than build validation.
## Doctor Model
Baseline doctor behavior:
- managed-world validation by default;
- broader workspace hygiene scanning in expanded workspace mode;
- safe mechanical fix application only for baseline fix flows.
Unsafe automatic mutation is out of scope for baseline doctor behavior.
## Safety and Consent
Rules:
- destructive or relocational mutations require explicit consent;
- quarantine is explicit and reversible;
- duplicate content detection is advisory, not structurally invalid by itself;
- orphan anchors are diagnosable, not build-active.
## Studio-First Service Surface
The normative operational surface is service-based.
Baseline core services:
- `init_workspace`
- `register_asset`
- `adopt_asset`
- `forget_asset`
- `remove_asset`
- `list_assets`
- `get_asset_details`
- `doctor`
- `build`
## Operation Classes
Operations must distinguish:
- read-only operations;
- registry mutations;
- workspace mutations.
This distinction is part of the service semantics and must be visible to the UI.
## Preview/Apply Model
Sensitive mutations use staged intent.
Rules:
- preview or analysis precedes broad mutation where appropriate;
- safe-fix flows are modeled as services, not merely terminal flags;
- `forget_asset` and `remove_asset` remain distinct operations.
## Structured Responses
Service responses must be structured.
At minimum, the model should support fields equivalent to:
- `status`
- `summary`
- `affected_assets`
- `diagnostics`
- `proposed_actions`
- `applied_actions`
- `blockers`
## Asset Event Lane
The system includes a dedicated asset workspace event/reporting lane.
Responsibilities:
- observe relevant asset and registry changes;
- report diagnostics/build/cache activity to the UI;
- support live refresh and progress reporting;
- avoid blocking the main UI thread.
### Initial Event Set
The initial structured event set includes:
- `asset_discovered`
- `asset_changed`
- `diagnostics_updated`
- `build_started`
- `build_finished`
- `cache_hit`
- `cache_miss`
- `preview_ready`
- `action_applied`
- `action_failed`
- `progress_updated`
### Mutation Serialization
Mutating asset workflows are serialized semantically.
Rules:
- background observation and reporting may be continuous;
- conflicting sensitive mutations must not race arbitrarily;
- observable mutation behavior remains coherent from the UI perspective.
## Incremental and Watch Integration
Incremental behavior is an optimization only.
Rules:
- full and incremental builds must be observably equivalent;
- watch mode is optional in the baseline contract;
- watch does not authorize silent dangerous mutation.
## Non-Goals
- final visual design of Studio asset panels
- future CLI grammar
- remote/shared cache orchestration
## Exit Criteria
This specification is complete enough when:
- Studio-facing operational semantics are explicit;
- safety/preview/apply behavior is clear;
- event/reporting integration has a stable baseline.

122
docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md Normal file
View File

@ -0,0 +1,122 @@
# Versioning, Migration, and Trust Model Specification
Status: Draft
Scope: Artifact/schema versioning, migration ownership, and conservative trust boundaries
Purpose: Define how the packer evolves safely over time and what trust assumptions it makes.
## Authority and Precedence
This specification is grounded in:
- [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md)
## Core Rules
1. Versioning is explicit and per artifact/schema.
2. Migration applies only to artifacts the packer owns.
3. Compatibility is governed by a support window, not indefinite backward guarantees.
4. Inputs are untrusted until validated.
5. Baseline packer architecture does not execute arbitrary plugins or scripts.
## Explicit Versioning Surfaces
The packer versioning model applies to at least:
- `asset.json`
- `index.json`
- `assets.pa`
- the `assets.pa` header contract
- companion build artifacts where a stable reader exists
- packer-owned cache/control schemas where migration is supported
## Migration Ownership
The packer owns migration of artifacts it controls.
This includes:
- `asset.json`
- `index.json`
- packer-owned caches and control files
Rules:
- migration may be automatic within the supported window;
- unsupported versions fail clearly and early;
- migration failures must be diagnosable in Studio and CI.
## Runtime Compatibility Boundary
Runtime reading semantics for `assets.pa` belong upstream to runtime specs.
Rules:
- the packer implements the corresponding writer-side production contract;
- the packer must not redefine runtime reader semantics;
- companion artifacts do not redefine the runtime-facing contract.
## Future Shipper Boundary
The future shipper is a consumer of packer artifacts.
Rules:
- the shipper is not a current packer dependency;
- the shipper must not become a silent repair layer for invalid packer artifacts;
- shipper workflow detail is deferred until the shipper exists.
## Trust Model
The trust posture is conservative.
Untrusted until validated:
- source asset files;
- hand-edited or legacy declarations;
- imported external project content;
- legacy packer artifacts and control data.
Trusted only after:
- strict parse;
- structural validation;
- semantic validation;
- version compatibility check.
## Plugin and Script Execution
The baseline packer contract forbids arbitrary external execution as part of normal asset processing.
Rules:
- no untrusted plugins;
- no ad hoc script execution;
- no implicit foreign-code extension hooks.
Any future extensibility model requires a separate decision.
## Failure Surfacing
Version and migration failures must be actionable.
At minimum, diagnostics should make clear:
- the version found;
- the supported range or expectation;
- whether migration was attempted;
- whether manual action is required;
- whether the failure blocks build or Studio workflow.
## Non-Goals
- artifact signing strategy
- distribution security beyond current tooling trust posture
- remote/shared artifact registry behavior
## Exit Criteria
This specification is complete enough when:
- artifact versioning boundaries are explicit;
- migration ownership is unambiguous;
- trust assumptions are conservative and enforceable.

22
docs/packer/specs/README.md
View File

@ -52,3 +52,25 @@ Specs should normally be fed by:
4. then spec integration.
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
## Current Corpus
The current packer core corpus is:
1. [`1. Domain and Artifact Boundary Specification.md`](./1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
2. [`2. Workspace, Registry, and Asset Identity Specification.md`](./2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
3. [`3. Asset Declaration and Virtual Asset Contract Specification.md`](./3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
4. [`4. Build Artifacts and Deterministic Packing Specification.md`](./4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md)
5. [`5. Diagnostics, Operations, and Studio Integration Specification.md`](./5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
6. [`6. Versioning, Migration, and Trust Model Specification.md`](./6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md)
## Reading Order
Recommended order:
1. domain and artifact boundary;
2. workspace and identity;
3. asset declaration;
4. build artifacts;
5. diagnostics and Studio operation model;
6. versioning and trust.