@mannyc1/ts-release 0.0.5 → 0.0.7

package/ARCHITECTURE.md

@@ -1,8 +1,10 @@
 # Architecture
 
-`@mannyc1/ts-release` is library-first and CLI-second.
+`@mannyc1/ts-release` is artifact-first, library-first, and CLI-second.
 
-The package turns release intent into typed data, plans, evidence, and approved operations. The CLI and GitHub Action are adapters over those workflows.
+The package turns release intent into staged artifacts, installable artifact
+variants, target-specific distribution plans, evidence, and approved operations.
+The CLI and GitHub Action are adapters over those workflows.
 
 ## Target Boundary
 
@@ -35,9 +37,10 @@ than reaching into CLI modules.
 
 ## Current Module Taxonomy
 
-- `domain/` contains durable schema-backed data models, typed errors, and scalar schemas owned by their semantic domain modules, such as release names in `domain/release`, target IDs in `domain/target`, artifact IDs in `domain/artifact`, operation IDs in `domain/operation`, and evidence IDs in `domain/evidence`.
+- `domain/` contains durable schema-backed data models, typed errors, and scalar schemas owned by their semantic domain modules, such as release names in `domain/release`, target IDs in `domain/target`, artifact IDs and installable variants in `domain/artifact`, operation IDs in `domain/operation`, and evidence IDs in `domain/evidence`.
 - `config/` parses and validates release config into domain values.
-- `planner/` normalizes release intent, builds plans, renders plans, executes operation data through injected services, records evidence, reports status, resumes safe work, and reconciles remote state.
+- `artifacts/` defines the recipe staging adapter and registry boundary. Recipes are data until a runtime provides a staging layer.
+- `planner/` normalizes release intent, builds artifact inventory, carries installable variants, builds plans, renders plans, executes operation data through injected services, records evidence, and reconciles modeled remote state.
 - `targets/` models ecosystem-specific target semantics and produces operation data. Target modules may describe commands and HTTP checks, but they do not execute them.
 - `host/` defines injectable command and HTTP services plus live or test implementations.
 - `workflows/` contains reusable application workflows over config files, init/scaffolding plans, diagnostics, evidence files, and live target/HTTP composition. This is the high-level programmatic surface.
@@ -56,8 +59,9 @@ The normal flow is:
 ```text
 domain <- config
 domain <- planner <- targets
+domain <- artifacts
 domain <- host
-workflows -> config/planner/host/targets
+workflows -> config/artifacts/planner/host/targets
 apps/release-ts runtime -> host/workflows/platform layers
 apps/release-ts cli -> workflows/runtime boundary
 apps/ts-release-action runtime -> host/workflows/platform layers
@@ -70,14 +74,15 @@ apps/ts-release-action action -> workflows/runtime boundary
 
 There is no public `./api` facade, and the root package export stays empty. The public workflow modules are named after the work they own:
 
-- `./workflows` for the curated opt-in `Config`, `Init`, `Diagnostics`, `Evidence`, and `Live` namespaces.
+- `./workflows` for the curated opt-in `Distribution`, `Config`, `Init`, `Diagnostics`, `Evidence`, and `Live` namespaces.
+- `./workflows/distribution` for the artifact-first high-level distribution facade.
 - `./workflows/config` for config-file release workflows.
 - `./workflows/init` for data-first scaffolding previews and approved writes.
 - `./workflows/diagnostics` for static config, auth, and CI readiness reports.
 - `./workflows/evidence` for reusable evidence persistence.
 - `./workflows/live` for runtime-neutral live target and HTTP services.
 
-The `./workflows` facade lives at `src/workflows/index.ts` and should only re-export workflow namespaces. Use exact workflow leaf imports for maximum tree-shaking or direct option-class access, and lower-level `domain/`, `config/`, `planner/`, `host/`, and `targets/` subpaths when a caller needs more control than the workflow modules provide.
+The `./workflows` facade lives at `src/workflows/index.ts` and should only re-export workflow namespaces. Use `Distribution` for the product path: stage artifacts, plan distribution, render target files, execute approved operations, verify, and reconcile. Use exact workflow leaf imports for maximum tree-shaking or direct option-class access, and lower-level `domain/`, `config/`, `planner/`, `host/`, and `targets/` subpaths when a caller needs more control than the workflow modules provide.
 
 ## Boundary Rules
 
@@ -86,7 +91,7 @@ The `./workflows` facade lives at `src/workflows/index.ts` and should only re-ex
 - Reusable effectful operations use `Effect.fn`; inline orchestration bodies use `Effect.gen`.
 - Durable models, options, target variants, and typed errors use `Schema.Class`, `Schema.TaggedClass`, and `Schema.TaggedErrorClass`.
 - Layers are provided at CLI, action, runtime, script, application, and test boundaries.
-- Config parsing, evidence persistence, status, resume, reconciliation, and release execution are library workflows, not CLI behavior.
+- Config parsing, artifact staging, distribution planning, evidence persistence, reconciliation, and approved execution are library workflows, not CLI behavior.
 - Terminal formatting, argv parsing, and `--out` file writing belong in
   `apps/release-ts/src/cli/`.
 - GitHub Action input parsing, output names, step summaries, and evidence artifact