diff options
| author | Somhairle H. Marisol <[email protected]> | 2026-09-21 00:58:15 +0800 |
|---|---|---|
| committer | Somhairle H. Marisol <[email protected]> | 2026-09-21 00:58:15 +0800 |
| commit | 7b29dbff7e43e87741476f47df17ad1582b16546 (patch) | |
| tree | 4c9d0832b4e4edd77e59e9cb0a88abf5e729a9f9 /docs/superpowers/specs | |
| parent | 47add3088d50f12c5f48591f26c53cdb59d8283b (diff) | |
| download | somhairles-dream-fsharp-7b29dbff7e43e87741476f47df17ad1582b16546.tar.gz | |
feat(pipeline): add runnable artifact pipeline increment
[Change Nature]
- This commit adds the first runnable increment of the F# artifact
pipeline: CLI, server, frontend bundle, stage fixture, and tests.
It is feature work, not a bug fix.
[New Capability]
- CLI `run` executes the three-step Blender fixture through the process
bridge and writes GLBs, step logs, events, and a manifest; `verify`
validates a manifest without Blender.
- Server exposes run start, run-scoped SSE, artifact manifest/file
routes, and serves the Fable frontend from its build output.
- Frontend starts runs, follows run-scoped SSE progress, and links the
artifact manifest on completion.
[Implementation]
- Shared layer holds domain, run state, replay, and artifact contracts;
Modeling holds the pipeline, 120s bridge timeout, and result-file
protocol; stage/blender/fixture.py owns geometry in Python (bpy owns
geometry, F# owns orchestration).
- Fable bundle is regenerated into public/ and copied by the server
project; solution includes all projects with warnings-as-errors.
- README documents build, Fable, server, interpreter/env, fixture
limitations, and current verification status.
[Impact]
- Verified: 40/40 solution tests pass; Release build 0 warnings/errors;
real CLI run with bpy 5.0.1 produced 3 GLBs, 3 logs, and a
verify-clean manifest; isolated-port server smoke flow succeeded.
- Not yet verified: browser end-to-end behavior and production
fidelity. Artifacts and caches are gitignored.
Diffstat (limited to 'docs/superpowers/specs')
| -rw-r--r-- | docs/superpowers/specs/2026-09-20-artifact-pipeline-design.md | 32 |
1 files changed, 20 insertions, 12 deletions
diff --git a/docs/superpowers/specs/2026-09-20-artifact-pipeline-design.md b/docs/superpowers/specs/2026-09-20-artifact-pipeline-design.md index 4fe314c..ab0fd6d 100644 --- a/docs/superpowers/specs/2026-09-20-artifact-pipeline-design.md +++ b/docs/superpowers/specs/2026-09-20-artifact-pipeline-design.md @@ -48,9 +48,9 @@ namespaced IDs such as `heritage.foundation` are valid. `checkpoint`, `heartbeat`, `complete`, or `fail`. - `ArtifactChange`: object ID, change kind, and human-readable summary. - `RenderArtifact`: relative PNG path, SHA-256, byte count, and export time. -- `StepArtifact`: step metadata, immutable relative GLB path, SHA-256, byte - count, actual Blender export timestamp, source object IDs, verified object - IDs from GLB reimport, changes, and optional render. +- `StepArtifact`: step metadata, immutable relative GLB path, retained process + log path, SHA-256, byte count, actual Blender export timestamp, source object + IDs, verified object IDs from GLB reimport, changes, and optional render. - `ArtifactManifest`: schema version, run IDs, lifecycle timestamps, Blender version, ordered step artifacts, and final status. @@ -90,6 +90,10 @@ Each run is isolated at: .artifacts/<projectId>/<runId>/ events.ndjson manifest.json + logs/ + 01-foundation.log + 02-frame.log + 03-cabin.log steps/ 01-foundation.glb 02-frame.glb @@ -111,10 +115,11 @@ status is `complete`. The `Complete` event is appended after the rename; a crash or event-log failure at that point leaves the manifest authoritative and is recovered as complete on the next inspection, without deleting or rewriting it. A manifest is never published if any required step fails before -the commit point. `verify` recomputes all -recorded hashes, checks paths stay inside the run directory, checks the source -and verified object ID sets recorded by the bridge, checks timestamps, and -rejects duplicate step paths. Reimport is performed by the real stage +the commit point. `verify` recomputes all recorded hashes, checks retained +process logs are present and non-empty, checks paths stay inside the run +directory, checks the source and verified object ID sets recorded by the +bridge, checks timestamps, and rejects duplicate step paths. Reimport is +performed by the real stage integration command before the manifest is written; `verify` does not need Blender and validates the recorded proof plus the design's expected ID set. @@ -140,15 +145,18 @@ The bridge protocol is fixed. The F# process invokes: ```text <python> stage/blender/fixture.py --step-id <id> --output <tmp.glb> - [--render-output <tmp.png>] + --result-output <tmp.result.json> [--render-output <tmp.png>] ``` `<python>` comes from `--python` or `SOMHAIRLES_BPYTHON`; the default is `python3`. The script must import `bpy` and report version `>= 3.0.0`. Exit 0 -prints exactly one JSON result object containing `ok`, `blenderVersion`, -`exportedAt`, `objectIds`, `verifiedObjectIds`, `glbBytes`, and optional -`renderPath`/`renderedAt`. Exit 2 means invalid step or arguments, exit 3 -means missing/unsupported `bpy`, and exit 4 means export or render failure. +writes exactly one JSON result object to `--result-output` containing `ok`, +`blenderVersion`, `exportedAt`, `objectIds`, `verifiedObjectIds`, `glbBytes`, +and optional `renderPath`/`renderedAt`. Standard output and standard error are +diagnostic streams only; the bridge retains both in the step log so incidental +Blender output cannot corrupt result parsing. Exit 2 means invalid step or +arguments, exit 3 means missing/unsupported `bpy`, and exit 4 means export or +render failure. The bridge timeout is 120 seconds per step. `exportedAt` is emitted by Python immediately after the successful GLB export; F# rejects a missing or non-UTC timestamp. `verifiedObjectIds` comes from reimporting the just-written GLB and |
