updated packer agendas

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent 900a7e17dd
commit f27b28c516
14 changed files with 1008 additions and 64 deletions
@@ -18,7 +18,7 @@ Define the architectural boundary of the `packer` domain before the draft is dec
- packer must produce artifacts that can be consumed by `../runtime`,
- packer operations must be available as Studio-integrated services,
- packer does not build the cartridge,
- cartridge builder consumes packer outputs later.
- shipper 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.
@@ -30,7 +30,7 @@ The runtime already exposes normative constraints that the packer must treat as
- `1. Goals and Non-Goals`
- `2. Repository / Project Layout (Golden Pipeline)`
- `3. Crate Topology`
- `15. Integration with Cartridge Builder`
- `15. Integration with Cartridge Shipper`
## Runtime Normative Inputs
@@ -56,7 +56,7 @@ These points are already normative on the runtime side and should be treated as
## Key Questions
1. What is the exact ownership boundary between `packer` and `cartridge builder`?
1. What is the exact ownership boundary between `packer` and `shipper`?
2. Should `packer` be defined purely as offline asset tooling, or as a Studio-integrated service surface with optional CLI adapters?
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?
@@ -77,12 +77,12 @@ 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.
- Option A makes shipper integration more explicit and easier to spec.
- Option B may feel convenient short-term, but it risks collapsing packer and shipper concerns into one blurred tool boundary.
## Recommendation
Adopt Option A and make the packer/builder boundary explicit as a first-class architectural invariant.
Adopt Option A and make the packer/shipper boundary explicit as a first-class architectural invariant.
Also adopt this operational direction:
@@ -102,7 +102,7 @@ Also adopt this operational direction:
## Expected Spec Follow-up
- Packer domain charter or overview spec.
- Builder integration spec.
- Shipper integration spec.
- Artifact ownership and responsibility spec.
- Runtime artifact interface spec.
@@ -110,4 +110,4 @@ Also adopt this operational direction:
- Defining the detailed schema of `asset_table.json`.
- Defining individual asset formats.
- Designing cartridge builder internals.
- Designing cartridge shipper internals.
@@ -137,4 +137,4 @@ Direction:
- Final CLI UX for authoring these files.
- Incremental build internals.
- Cartridge builder consumption details.
- Cartridge shipper consumption details.
@@ -122,7 +122,7 @@ Adopt Option A with these fixed directions:
- `assets.pa` is the authoritative runtime-facing artifact;
- the `assets.pa` header is the authoritative runtime-facing descriptor;
- `build/asset_table.json` is a derived companion artifact for Studio, debugging, inspection, and builder/tooling integration;
- `build/asset_table.json` is a derived companion artifact for Studio, debugging, inspection, and shipper/tooling integration;
- global packing order is deterministic by increasing `asset_id`;
- preload emission is derived deterministically from per-asset `preload.enabled`;
- alignment exists only when explicitly required by spec;
@@ -176,4 +176,4 @@ Also adopt this companion-artifact direction:
- Asset workspace mutation commands.
- Quarantine behavior.
- Builder packaging flow.
- Shipper packaging flow.
@@ -2,7 +2,9 @@
## Status
Open
Closed
Resolved by [`004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md`](../decisions/004-diagnostics-doctor-quarantine-and-workspace-hygiene-decision.md).
## Purpose
@@ -2,7 +2,9 @@
## Status
Open
Closed
Resolved by [`005-incremental-build-cache-and-watch-model-decision.md`](../decisions/005-incremental-build-cache-and-watch-model-decision.md).
## Purpose
@@ -74,4 +76,4 @@ Adopt Option A:
- Full CLI command catalog.
- Asset registry identity rules.
- Cartridge builder integration.
- Cartridge shipper integration.
@@ -2,11 +2,13 @@
## Status
Open
Closed
Resolved by [`006-studio-first-asset-services-and-event-lane-decision.md`](../decisions/006-studio-first-asset-services-and-event-lane-decision.md).
## Purpose
Define the stable service and adapter contract for packer operations, especially operations that mutate registry state or user files.
Define the stable Studio-facing service contract for packer operations, especially operations that mutate registry state or user files.
## Context
@@ -26,13 +28,15 @@ The draft already lists a substantial command surface:
- `quarantine`
Historically, packer was framed as a CLI-first tool.
The current direction is different:
The current target is different:
- packer should be fully integrated with Studio;
- operations should exist as services;
- CLI, if retained, should be an adapter over those services.
- asset UI and packer services should evolve together;
- operations should exist as Studio-consumable services first;
- asset workflows should be observable through a dedicated background event lane for UI integration;
- CLI, if retained, should be treated as a later adapter rather than the design center.
This is enough surface area that operation semantics need architectural review before turning into normative service and CLI contracts.
This means the architectural work should focus on service semantics and UI integration points first, not on freezing a command-line contract too early.
## Source Sections
@@ -40,55 +44,75 @@ This is enough surface area that operation semantics need architectural review b
## Key Questions
1. Which operations are core v1 and which are aspirational?
2. Which identifiers must every command accept: name, id, uuid, path?
1. Which packer operations are core Studio services in v1 and which are later capabilities?
2. Which identifiers should Studio-facing services accept for normal asset workflows: name, id, uuid, root path?
3. Which operations 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. Which parts of the contract belong to Studio services versus optional CLI adapters?
7. Should adapter output contracts be stable for automation, or only JSON/structured output modes?
4. What requires explicit confirmation, preview, or staged apply behavior in Studio?
5. How should safe fix flows be exposed as service operations rather than CLI flags?
6. Which responses must be structured for UI consumption and automation?
7. What, if anything, should remain CLI-specific in the future adapter layer?
8. Should assets have a dedicated background event lane that reports changes, diagnostics, and build activity to the UI?
## Options
### Option A
Define a minimal stable v1 service surface and mark the rest as future or optional.
Define a minimal stable v1 Studio service surface and mark the rest as future or optional.
### Option B
Freeze the larger command catalog immediately.
Freeze a larger command catalog immediately.
## Tradeoffs
- Option A lowers the early compatibility burden.
- Option A matches the Studio-integrated direction better because services can stabilize before adapters.
- Option A matches the Studio-integrated direction better because services and UI can stabilize together before any CLI freeze.
- 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.
- Option B gives a bigger product surface up front, but it increases long-term compatibility cost around the wrong adapter.
## Recommendation
Adopt Option A and distinguish:
- required core services,
- optional adapters,
- optional future adapters,
- future operations not yet in the normative contract.
Current design target:
- Studio integration is primary;
- asset UI and packer services should be designed together;
- service contracts should describe intent, preview, apply, and result models suitable for UI workflows;
- asset-oriented operations should publish structured background events suitable for logs, progress, and live UI refresh;
- CLI should not drive the core architecture in this phase.
Also adopt this integration direction:
- the system should have a dedicated asset workspace event lane;
- this lane observes relevant asset and registry changes, triggers analysis/rebuild workflows as appropriate, and reports structured events to the UI;
- the architectural contract is the event/reporting surface, not a commitment to a specific threading primitive;
- dangerous mutations still require explicit user intent and must not be silently auto-applied by the background lane.
## Expected Decisions to Produce
1. Core v1 service set.
2. Mutation safety model.
1. Core v1 Studio service set.
2. Mutation safety and preview/apply model.
3. Identifier resolution rules.
4. Adapter and structured output expectations.
4. Structured response contracts for UI and automation.
5. Boundary between core services and future adapters.
6. Asset workspace event lane and structured event model for UI reporting.
## Expected Spec Follow-up
- Service operation contract spec.
- CLI adapter contract spec.
- Studio asset workflow integration spec.
- Mutation and confirmation policy spec.
- Command output contract spec.
- Structured response/output contract spec.
- Asset event/reporting integration spec.
## Non-Goals
- Asset payload binary layout.
- Format-specific `asset.json` rules.
- Detailed cache internals.
- Freezing a comprehensive CLI contract in the current phase.
@@ -1,18 +1,20 @@
# Builder Integration, Versioning, and Trust Model Agenda
# Shipper Integration, Versioning, and Trust Model Agenda
## Status
Open
Closed
Resolved by [`007-shipper-integration-versioning-and-trust-model-decision.md`](../decisions/007-shipper-integration-versioning-and-trust-model-decision.md).
## Purpose
Close the cross-domain contracts around builder integration, schema versioning, migrations, and the packer trust model.
Close the cross-domain contracts around shipper 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,
- shipper 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,
@@ -23,7 +25,7 @@ The first step should be to document the runtime-facing interface explicitly ins
## Source Sections
- `15. Integration with Cartridge Builder`
- `15. Integration with Cartridge Shipper`
- `16. Compatibility and Versioning`
- `17. Security and Trust Model`
@@ -48,7 +50,7 @@ These runtime specs already constrain packer evolution. The packer discussion sh
## Key Questions
1. Which integration points with builder are packer-owned versus shared contracts?
1. Which integration points with shipper 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?
@@ -62,7 +64,7 @@ These runtime specs already constrain packer evolution. The packer discussion sh
### Option A
Keep builder integration narrow, schema versioning explicit, and trust model conservative.
Keep shipper integration narrow, schema versioning explicit, and trust model conservative.
### Option B
@@ -80,7 +82,7 @@ Adopt Option A and treat schema evolution plus trust boundaries as first-class c
## Expected Decisions to Produce
1. Builder integration boundary.
1. Shipper integration boundary.
2. Schema versioning and migration policy.
3. Compatibility guarantees.
4. Security and trust invariants.
@@ -89,7 +91,7 @@ Adopt Option A and treat schema evolution plus trust boundaries as first-class c
## Expected Spec Follow-up
- Builder integration spec.
- Shipper integration spec.
- Schema versioning and migration spec.
- Security and trust model spec.
- Runtime reader and compatibility interface spec.
+4 -9
View File
@@ -4,14 +4,9 @@ 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`
There are currently no active packer agendas.
The first packer agenda wave (`01.0` through `01.7`) has been closed into decision records under [`../decisions/`](../decisions/).
## Purpose
@@ -47,7 +42,7 @@ A packer agenda should usually include:
- State the concrete decision the discussion is trying to produce.
- Prefer explicit tradeoffs over vague option lists.
- Avoid drafting large blocks of final normative spec text here.
- Be specific about packer scope: asset workspace, build artifacts, diagnostics, registry, builder boundary, and related contracts.
- Be specific about packer scope: asset workspace, build artifacts, diagnostics, registry, shipper boundary, and related contracts.
## Exit Rule