From 8c930c3d2e85ac0cdc76d1bd979e2953932c7e9e Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 06:51:10 +0000 Subject: [PATCH] add packer agendas --- ... Boundaries, and Golden Pipeline Agenda.md | 106 +++++++++++++++ ...e, Registry, and Stable Identity Agenda.md | 78 +++++++++++ ...sets, and Virtual Asset Contract Agenda.md | 79 ++++++++++++ ...ifacts and Deterministic Packing Agenda.md | 121 ++++++++++++++++++ ...uarantine, and Workspace Hygiene Agenda.md | 80 ++++++++++++ ...al Build, Cache, and Watch Model Agenda.md | 77 +++++++++++ ... Surface and Mutating Operations Agenda.md | 84 ++++++++++++ ...ion, Versioning, and Trust Model Agenda.md | 101 +++++++++++++++ docs/packer/agendas/README.md | 11 ++ 9 files changed, 737 insertions(+) create mode 100644 docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md create mode 100644 docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md create mode 100644 docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md create mode 100644 docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md create mode 100644 docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md create mode 100644 docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md create mode 100644 docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md create mode 100644 docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md diff --git a/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md b/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md new file mode 100644 index 00000000..0e74af21 --- /dev/null +++ b/docs/packer/agendas/01.0. Packer Scope, Boundaries, and Golden Pipeline Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md b/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md new file mode 100644 index 00000000..0fa61955 --- /dev/null +++ b/docs/packer/agendas/01.1. Asset Workspace, Registry, and Stable Identity Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md b/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md new file mode 100644 index 00000000..4e51243e --- /dev/null +++ b/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md b/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md new file mode 100644 index 00000000..d15b51ac --- /dev/null +++ b/docs/packer/agendas/01.3. Build Artifacts and Deterministic Packing Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md b/docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md new file mode 100644 index 00000000..2e965134 --- /dev/null +++ b/docs/packer/agendas/01.4. Diagnostics, Doctor, Quarantine, and Workspace Hygiene Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md b/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md new file mode 100644 index 00000000..dec4782a --- /dev/null +++ b/docs/packer/agendas/01.5. Incremental Build, Cache, and Watch Model Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md b/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md new file mode 100644 index 00000000..1a87dd38 --- /dev/null +++ b/docs/packer/agendas/01.6. CLI Surface and Mutating Operations Agenda.md @@ -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. diff --git a/docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md b/docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md new file mode 100644 index 00000000..7d65ecfd --- /dev/null +++ b/docs/packer/agendas/01.7. Builder Integration, Versioning, and Trust Model Agenda.md @@ -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. diff --git a/docs/packer/agendas/README.md b/docs/packer/agendas/README.md index 45ba0cc8..f3224927 100644 --- a/docs/packer/agendas/README.md +++ b/docs/packer/agendas/README.md @@ -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.