updated packer specs
This commit is contained in:
parent
f27b28c516
commit
e3389e78b6
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -45,3 +45,10 @@ If content grows, prefer:
|
|||||||
- and consolidation of duplicated explanations.
|
- and consolidation of duplicated explanations.
|
||||||
|
|
||||||
The goal is a maintainable learning surface, not a passive archive.
|
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)
|
||||||
|
|||||||
@ -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
87
docs/packer/learn/mental-model-packer.md
Normal 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”.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -52,3 +52,25 @@ Specs should normally be fed by:
|
|||||||
4. then spec integration.
|
4. then spec integration.
|
||||||
|
|
||||||
If a spec edit would require guessing an unresolved design choice, stop and surface the missing decision first.
|
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.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user