updated packer agendas
This commit is contained in:
@@ -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.
|
||||
|
||||
+1
-1
@@ -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.
|
||||
|
||||
+3
-1
@@ -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.
|
||||
|
||||
+11
-9
@@ -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,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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user