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

add packer agendas

Browse Source
This commit is contained in:
bQUARKz 2026-03-11 06:51:10 +00:00
parent d95dfa296c
commit 8c930c3d2e
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
9 changed files with 737 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md Normal file
View File

@ -0,0 +1,106 @@
# Packer Scope, Boundaries, and Golden Pipeline Agenda
## Status
Open
## Purpose
Define the architectural boundary of the `packer` domain before the draft is decomposed into normative specs.
## Context
`Prometeu Packer.md` already establishes a strong direction:
- packer owns asset management,
- packer produces `build/assets.pa`,
- packer produces `build/asset_table.json`,
- packer must produce artifacts that can be consumed by `../runtime`,
- packer does not build the cartridge,
- cartridge builder consumes packer outputs later.
This is a good draft direction, but it still needs to be closed as an explicit domain contract.
The interface between packer outputs and `../runtime` should be documented first, before it is treated as implementation detail.
The runtime already exposes normative constraints that the packer must treat as upstream contract, not as optional design space.
## Source Sections
- `1. Goals and Non-Goals`
- `2. Repository / Project Layout (Golden Pipeline)`
- `3. Crate Topology`
- `15. Integration with Cartridge Builder`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- `assets.pa` is the runtime-facing asset artifact consumed by the current runtime;
- cartridges that declare `Asset` capability must provide valid `assets.pa`;
- runtime bootstrap must fail early when the asset capability is declared but `assets.pa` is missing or invalid;
- `assets.pa` v1 is autocontained and contains:
- fixed binary prelude,
- JSON header,
- binary payload region.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- the runtime consumes `assets.pa` as the primary cartridge asset artifact;
- the runtime-facing contract is bank-centric;
- `asset_table` and `preload` are loaded from inside `assets.pa`;
- payload slices are resolved relative to `payload_offset`;
- the runtime must not require the full `assets.pa` payload to remain resident in RAM as its baseline operating mode.
These points are already normative on the runtime side and should be treated as hard inputs for packer-side discussion.
## Key Questions
1. What is the exact ownership boundary between `packer` and `cartridge builder`?
2. Should `packer` be defined purely as offline asset tooling, or also as a reusable library surface for IDE and watch integrations?
3. Which project directories are normative for packer behavior, and which are merely conventional?
4. Should packer be allowed to read `src/` or compiler outputs at all, or only operate on `assets/` plus project metadata?
5. Is `build/asset_table.json` a packer-owned artifact contract or a shared cross-domain contract?
6. Which packer-produced artifact is the runtime-facing contract, and what must be documented before code depends on it?
7. Which parts of the runtime-facing `assets.pa` contract are already closed by runtime specs and therefore outside packer-side redesign scope?
## Options
### Option A
Keep packer strictly scoped to `assets/` workspace management and production of packer outputs only.
### Option B
Allow packer to absorb more cartridge preparation responsibilities over time.
## Tradeoffs
- Option A keeps the architecture cleaner and reduces domain leakage.
- Option A makes builder integration more explicit and easier to spec.
- Option B may feel convenient short-term, but it risks collapsing packer and builder concerns into one blurred tool boundary.
## Recommendation
Adopt Option A and make the packer/builder boundary explicit as a first-class architectural invariant.
## Expected Decisions to Produce
1. Packer domain boundary.
2. Ownership of `assets.pa` and `asset_table.json`.
3. Relationship between CLI, core library, and future integrations.
4. Normative project layout expectations.
5. Runtime-facing artifact ownership and documentation responsibility.
6. Explicit statement that runtime specs 13 and 15 are upstream constraints for `assets.pa`.
## Expected Spec Follow-up
- Packer domain charter or overview spec.
- Builder integration spec.
- Artifact ownership and responsibility spec.
- Runtime artifact interface spec.
## Non-Goals
- Defining the detailed schema of `asset_table.json`.
- Defining individual asset formats.
- Designing cartridge builder internals.

78
docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md Normal file
View File

@ -0,0 +1,78 @@
# Asset Workspace, Registry, and Stable Identity Agenda
## Status
Open
## Purpose
Close the packer model for managed assets, registry truth, anchor files, and stable asset identity.
## Context
The draft proposes a Git-like workspace:
- `assets/` may be messy,
- `assets/.prometeu/index.json` is the source of truth,
- a managed asset is anchored by `asset.json`,
- each asset has `asset_id` and `asset_uuid`.
This is the core model of the packer. If it stays vague, all later specs become unstable.
## Source Sections
- `4. Mental Model: A "Git-like" Asset Workspace`
- `5. Core Concepts`
- `6. Directory Structure and Control Files`
## Key Questions
1. Is `index.json` the sole source of truth, or does `asset.json` also carry authority?
2. What is the exact relationship between registry entry and anchor file?
3. Which fields are stable identity and which are mutable presentation?
4. Can an asset move directories without changing identity?
5. How should orphaned `asset.json` files be interpreted?
6. What is the normative lifecycle of `asset_id` allocation and persistence?
## Options
### Option A
Treat `index.json` as the authoritative registry and `asset.json` as the asset-local contract.
### Option B
Treat both as co-authoritative and reconcile divergences dynamically.
## Tradeoffs
- Option A is easier to reason about and easier to validate.
- Option A enables clean diagnostics when local anchor and registry diverge.
- Option B increases reconciliation complexity and invites ambiguous conflict handling.
## Recommendation
Adopt Option A:
- `index.json` is the authoritative registry,
- `asset.json` is the authoritative asset-local declaration,
- divergence between them must be explicit and diagnosable.
## Expected Decisions to Produce
1. Registry authority model.
2. Managed asset lifecycle.
3. Identity model for `asset_id`, `asset_uuid`, name, and path.
4. Rules for relocation, adoption, forgetting, and removal.
## Expected Spec Follow-up
- Workspace and control files spec.
- Managed asset and identity spec.
- Registry consistency and validation spec.
## Non-Goals
- Detailed build output layout.
- CLI syntax for every command.
- Format-specific `asset.json` payload definitions.

79
docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md Normal file
View File

@ -0,0 +1,79 @@
# Asset Specification, Raw Assets, and Virtual Asset Contract Agenda
## Status
Open
## Purpose
Define the contract of `asset.json`, including the split between raw assets, virtual assets, and format-specific output specs.
## Context
The draft already proposes:
- `asset.json` as the anchor spec,
- common fields for all assets,
- explicit pipeline declaration for virtual assets,
- future format families such as `TILES/indexed_v1` and `SOUNDS/pcm16le_v1`.
This needs decomposition into a stable common contract plus future format-specific specs.
## Source Sections
- `5.3 Asset Types (Bank Targets)`
- `5.4 Raw vs Virtual Assets`
- `7. Asset Specification: asset.json`
- `14. Virtual Assets (Deep Explanation)`
## Key Questions
1. Which fields belong to every `asset.json` regardless of type?
2. Which parts of the file are common packer contract versus format-specific contract?
3. How explicit must virtual build steps be?
4. Where should defaults live, and when must they be materialized?
5. Is `type` the bank target, the user-facing kind, or both?
6. How should packer version output formats independently from registry and descriptor schemas?
## Options
### Option A
Keep a small common `asset.json` contract and push all output-specific rules into dedicated format specs.
### Option B
Keep a richer monolithic `asset.json` contract in one central spec.
## Tradeoffs
- Option A scales better as new asset formats are added.
- Option A keeps the core packer spec smaller and more stable.
- Option B looks simpler initially but becomes harder to evolve without coupling unrelated formats together.
## Recommendation
Adopt Option A:
- a compact common `asset.json` contract,
- format-specific normative specs for each output family,
- explicit virtual asset declarations with deterministic materialization rules.
## Expected Decisions to Produce
1. Common `asset.json` schema boundary.
2. Raw versus virtual asset contract.
3. Versioning strategy for asset format specs.
4. Rules for defaults and explicit materialization.
## Expected Spec Follow-up
- Common asset specification spec.
- Virtual asset contract spec.
- Format-specific specs such as `TILES/indexed_v1`.
## Non-Goals
- Final CLI UX for authoring these files.
- Incremental build internals.
- Cartridge builder consumption details.

121
docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md Normal file
View File

@ -0,0 +1,121 @@
# Build Artifacts and Deterministic Packing Agenda
## Status
Open
## Purpose
Close the contract for packer build outputs and the determinism rules that make them reproducible.
## Context
The draft proposes two core build artifacts:
- `build/assets.pa`
- `build/asset_table.json`
At least one of these artifacts must form a documented interface that `../runtime` can consume safely.
That runtime-facing contract should be specified before the implementation hardens around incidental file structure.
It also states strong determinism requirements:
- deterministic asset order,
- deterministic derived outputs,
- explicit materialization of inferred defaults.
This is a strong basis for normative packer output specs.
## Source Sections
- `8. Build Artifacts Produced by the Packer`
- `9. Determinism Rules`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- `assets.pa` is the runtime-facing artifact;
- `assets.pa` v1 is an autocontained binary with:
- fixed binary prelude,
- JSON header,
- binary payload region;
- the fixed prelude contains, at minimum:
- `magic`,
- `schema_version`,
- `header_len`,
- `payload_offset`;
- the JSON header carries:
- `asset_table`,
- `preload`.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- `asset_table` entries currently expose:
- `asset_id`,
- `asset_name`,
- `bank_type`,
- `offset`,
- `size`,
- `decoded_size`,
- `codec`,
- `metadata`;
- `offset` is relative to the payload region inside `assets.pa`, not to the start of the full file;
- `preload` is boot-time input only;
- runtime loading is based on `open_slice` over payload slices;
- the runtime must not require the entire payload to stay resident in RAM.
These are already normative runtime-facing requirements and should be treated as baseline constraints for packer output design.
## Key Questions
1. How should the packer spec mirror the already normative `assets.pa` v1 envelope from runtime specs 13 and 15?
2. Which fields in `asset_table.json` are still tooling-only if the runtime-facing contract lives primarily inside `assets.pa`?
3. Is asset order always `asset_id` order, or can format-specific constraints override it?
4. How should alignment be expressed and validated?
5. What exactly counts as determinism for virtual asset pipelines?
6. Which inferred values must be written back versus only emitted in build outputs?
7. Which packer-side metadata is intentionally excluded from the runtime-facing contract?
8. How should packer document `preload` lifecycle and `offset` semantics so they match runtime reader behavior?
## Options
### Option A
Keep `assets.pa` simple and push structure into `asset_table.json`.
### Option B
Embed more self-description into `assets.pa` itself.
## Tradeoffs
- Option A keeps runtime payload compact and keeps metadata easier to evolve.
- Option A matches the current draft direction and reduces double-modeling.
- Option B may help standalone introspection, but it risks splitting authority across two artifacts.
## Recommendation
Adopt Option A and make `asset_table.json` the authoritative descriptor for ROM slice structure.
## Expected Decisions to Produce
1. v1 artifact boundary and ownership.
2. Deterministic ordering and alignment rules.
3. Descriptor schema responsibilities.
4. Materialization requirements for inferred values.
5. Runtime-facing artifact contract and reader expectations.
6. Packer-side restatement of the runtime-owned `assets.pa` envelope and slice semantics.
## Expected Spec Follow-up
- Packed ROM artifact spec.
- Asset table descriptor spec.
- Determinism and reproducibility spec.
- Runtime consumption interface spec.
## Non-Goals
- Asset workspace mutation commands.
- Quarantine behavior.
- Builder packaging flow.

80
docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md Normal file
View File

@ -0,0 +1,80 @@
# Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda
## Status
Open
## Purpose
Define the packer as a "sanity guardian" with explicit diagnostics, workspace scanning, quarantine, and garbage collection behavior.
## Context
One of the strongest ideas in the draft is that packer should help users survive a messy `assets/` workspace.
The document already sketches:
- structured diagnostics,
- `doctor` modes,
- orphan and duplicate detection,
- quarantine,
- garbage collection.
This deserves a dedicated decision because it strongly shapes user trust in the tool.
## Source Sections
- `10. Diagnostics and the "Sanity Guardian" Chain`
- `12. Quarantine and Garbage Collection`
## Key Questions
1. Which diagnostics are build-blocking versus advisory?
2. What is the normative distinction between registry validation and workspace hygiene scanning?
3. Which automatic fixes are considered safe?
4. What operations require explicit consent?
5. How should quarantine be modeled: reversible staging area or semi-managed trash bin?
6. How aggressive should duplicate and orphan detection be?
## Options
### Option A
Keep a strict separation:
- registry errors block builds,
- workspace hygiene warnings inform users,
- destructive or moving operations always require explicit consent.
### Option B
Let doctor apply broader automatic remediation by default.
## Tradeoffs
- Option A is safer and easier to trust.
- Option A aligns with the draft's explicit-user-consent direction.
- Option B may save time in some cases, but it raises risk of surprising workspace mutations.
## Recommendation
Adopt Option A and make reversibility plus explicit consent core packer invariants.
## Expected Decisions to Produce
1. Diagnostic classes and severities.
2. Scope and modes of `doctor`.
3. Safety model for `--fix`, `gc`, and quarantine.
4. Workspace hygiene responsibilities of the packer.
## Expected Spec Follow-up
- Diagnostics contract spec.
- Doctor and workspace scan spec.
- Quarantine and garbage collection spec.
## Non-Goals
- Detailed asset format validation rules.
- Final watch mode design.
- Runtime-facing artifact schemas.

77
docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md Normal file
View File

@ -0,0 +1,77 @@
# Incremental Build, Cache, and Watch Model Agenda
## Status
Open
## Purpose
Define how packer caches, fingerprints, and optional watch behavior should work without compromising determinism.
## Context
The draft proposes:
- fingerprint tracking in `assets/.prometeu/cache/fingerprints.json`,
- incremental rebuilds,
- strong hashing,
- optional watch mode.
This area is operationally important but easy to underspecify.
## Source Sections
- `11. Incremental Build, Cache, and Fingerprints`
- `13.10 prometeu packer watch`
## Key Questions
1. Which fingerprints are authoritative for cache invalidation?
2. When are `mtime` and size only hints versus hard cache keys?
3. What outputs may be reused from cache, and under which conditions?
4. Does watch mode belong in v1 spec or only as non-normative future work?
5. How should cache invalidation be surfaced to users and diagnostics?
6. How do we guarantee that incremental behavior never changes final outputs?
## Options
### Option A
Specify cache behavior conservatively and keep watch mode optional or non-normative in the first wave.
### Option B
Make watch mode and aggressive incremental behavior part of the early normative contract.
## Tradeoffs
- Option A reduces spec risk and keeps determinism easier to enforce.
- Option A allows cache internals to evolve while the artifact contract stabilizes first.
- Option B may be attractive for UX, but it increases the amount of behavior that must be frozen too early.
## Recommendation
Adopt Option A:
- deterministic outputs first,
- conservative cache spec,
- watch mode optional until the underlying invariants are stable.
## Expected Decisions to Produce
1. Cache authority and invalidation model.
2. Fingerprint contract.
3. Normative versus non-normative status of watch mode.
4. Safety rules for incremental reuse.
## Expected Spec Follow-up
- Cache and fingerprints spec.
- Incremental build guarantees spec.
- Optional watch mode spec or deferred note.
## Non-Goals
- Full CLI command catalog.
- Asset registry identity rules.
- Cartridge builder integration.

84
docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md Normal file
View File

@ -0,0 +1,84 @@
# CLI Surface and Mutating Operations Agenda
## Status
Open
## Purpose
Define the stable CLI contract for packer commands, especially commands that mutate registry state or user files.
## Context
The draft already lists a substantial command surface:
- `init`
- `add`
- `adopt`
- `forget`
- `rm`
- `list`
- `show`
- `doctor`
- `build`
- `watch`
- `gc`
- `quarantine`
This is enough surface area that command semantics need architectural review before turning into normative CLI specs.
## Source Sections
- `13. CLI Commands (Comprehensive)`
## Key Questions
1. Which commands are core v1 and which are aspirational?
2. Which identifiers must every command accept: name, id, uuid, path?
3. Which commands mutate registry only versus mutate workspace files?
4. What requires confirmation, force flags, or dry-run support?
5. How explicit should `--fix` and auto-materialization behavior be?
6. Should CLI output contracts be stable for automation, or only JSON/structured output modes?
## Options
### Option A
Define a minimal stable v1 CLI and mark the rest as future or optional.
### Option B
Freeze the larger command catalog immediately.
## Tradeoffs
- Option A lowers the early compatibility burden.
- Option A gives room to validate mutating operations safely before promising too much.
- Option B gives a bigger product surface up front, but it increases long-term compatibility cost.
## Recommendation
Adopt Option A and distinguish:
- required core commands,
- optional commands,
- future commands not yet in the normative CLI contract.
## Expected Decisions to Produce
1. Core v1 command set.
2. Mutation safety model.
3. Identifier resolution rules.
4. Structured output and automation expectations.
## Expected Spec Follow-up
- CLI command contract spec.
- Mutation and confirmation policy spec.
- Command output contract spec.
## Non-Goals
- Asset payload binary layout.
- Format-specific `asset.json` rules.
- Detailed cache internals.

101
docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md Normal file
View File

@ -0,0 +1,101 @@
# Builder Integration, Versioning, and Trust Model Agenda
## Status
Open
## Purpose
Close the cross-domain contracts around builder integration, schema versioning, migrations, and the packer trust model.
## Context
The tail of the draft contains several cross-cutting commitments:
- cartridge builder consumes packer outputs,
- `../runtime` must be able to read the packer-produced artifact contract,
- multiple JSON artifacts carry `schema_version`,
- packer must migrate older schemas or emit actionable diagnostics,
- packer is offline tooling and must not execute untrusted scripts.
These topics are cross-domain and should be discussed together before hardening the specs.
The first step should be to document the runtime-facing interface explicitly instead of leaving it implicit in tooling behavior.
## Source Sections
- `15. Integration with Cartridge Builder`
- `16. Compatibility and Versioning`
- `17. Security and Trust Model`
## Runtime Normative Inputs
From `../runtime/docs/runtime/specs/13-cartridge.md`:
- cartridges may contain optional `assets.pa`;
- when `Asset` capability is declared, valid `assets.pa` is required before asset bootstrap;
- runtime validation failure must happen before preload execution;
- `assets.pa` is the runtime-facing asset artifact for the current runtime.
From `../runtime/docs/runtime/specs/15-asset-management.md`:
- the runtime-facing asset model is bank-centric;
- `preload` is boot-time input only;
- runtime residency and bank ownership are independent from VM heap ownership;
- asset loading uses slice-based access over `assets.pa`;
- schema-bearing runtime-facing structures already exist and must be versioned carefully.
These runtime specs already constrain packer evolution. The packer discussion should focus on how to honor and document this contract on the tooling side.
## Key Questions
1. Which integration points with builder are packer-owned versus shared contracts?
2. Which artifacts need explicit migration policy?
3. Is backward compatibility required for all schema versions or only within a support window?
4. What counts as trusted configuration versus untrusted input data?
5. Can packer ever execute plugin-like transformations, or is that forbidden by architecture?
6. How should migration failures be surfaced to users and CI?
7. How should the runtime reader contract be versioned and documented?
8. Which compatibility guarantees apply specifically to `../runtime` consumption?
9. Which parts of the runtime-facing contract are owned by runtime specs versus packer-owned companion specs?
## Options
### Option A
Keep builder integration narrow, schema versioning explicit, and trust model conservative.
### Option B
Allow broader extensibility and looser compatibility commitments.
## Tradeoffs
- Option A is easier to secure and specify.
- Option A supports reliable CI and migration diagnostics.
- Option B may feel more flexible, but it introduces major review and safety burden early.
## Recommendation
Adopt Option A and treat schema evolution plus trust boundaries as first-class contracts.
## Expected Decisions to Produce
1. Builder integration boundary.
2. Schema versioning and migration policy.
3. Compatibility guarantees.
4. Security and trust invariants.
5. Runtime consumption contract and versioning boundary.
6. Ownership split between runtime normative specs and packer-side companion documentation.
## Expected Spec Follow-up
- Builder integration spec.
- Schema versioning and migration spec.
- Security and trust model spec.
- Runtime reader and compatibility interface spec.
## Non-Goals
- CLI ergonomics for all commands.
- Detailed asset format transformation pipelines.
- Workspace hygiene behavior.

11
docs/packer/agendas/README.md
View File

@ -2,6 +2,17 @@
This directory contains active packer discussion agendas.
## Active Agendas
1. `01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md`
2. `01.1. Asset Workspace, Registry, and Stable Identity Agenda.md`
3. `01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md`
4. `01.3. Build Artifacts and Deterministic Packing Agenda.md`
5. `01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md`
6. `01.5. Incremental Build, Cache, and Watch Model Agenda.md`
7. `01.6. CLI Surface and Mutating Operations Agenda.md`
8. `01.7. Builder Integration, Versioning, and Trust Model Agenda.md`
## Purpose
An agenda exists to drive a decision.