diff options
Diffstat (limited to 'docs/superpowers')
| -rw-r--r-- | docs/superpowers/plans/2026-09-20-artifact-pipeline-implementation.md | 49 | ||||
| -rw-r--r-- | docs/superpowers/specs/2026-09-20-artifact-pipeline-design.md | 32 |
2 files changed, 69 insertions, 12 deletions
diff --git a/docs/superpowers/plans/2026-09-20-artifact-pipeline-implementation.md b/docs/superpowers/plans/2026-09-20-artifact-pipeline-implementation.md new file mode 100644 index 0000000..e1cb4e6 --- /dev/null +++ b/docs/superpowers/plans/2026-09-20-artifact-pipeline-implementation.md @@ -0,0 +1,49 @@ +# Artifact Pipeline Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Complete the typed artifact pipeline from the shared contract through the Blender CLI, server SSE, and browser manifest link. + +**Architecture:** Keep `SomhairlesDream.Shared` as the wire contract, put deterministic artifact writing and Blender invocation in `SomhairlesDream.Modeling`, expose it through a thin CLI, and have the ASP.NET server run the same pipeline asynchronously. Preserve the existing replay store and UI path. + +**Tech Stack:** F#/.NET 8, ASP.NET Core minimal APIs, `System.Text.Json`, `System.Diagnostics.Process`, xUnit, Blender Python fixture. + +--- + +### Task 1: Align contracts and lifecycle validation + +**Files:** `src/SomhairlesDream.Shared/Artifact.fs`, `src/SomhairlesDream.Modeling/Definitions.fs`, `src/SomhairlesDream.Server/Store.fs`, and the corresponding Shared/Modeling/Server tests. + +- [ ] Add checkpoint `TotalSteps` and serialize it as flat camel-case JSON. +- [ ] Make design object IDs cumulative snapshots and require completion only after all ordered checkpoints. +- [ ] Verify focused tests and keep legacy `RunStore` behavior unchanged. + +### Task 2: Implement the Blender bridge and CLI + +**Files:** `src/SomhairlesDream.Modeling/BlenderBridge.fs`, `src/SomhairlesDream.Cli/Program.fs`, `stage/blender/fixture.py`, project files, and CLI/Modeling tests. + +- [ ] Add a process bridge using `ProcessStartInfo.ArgumentList`, bounded to 120 seconds, with structured result/error handling, an explicit result file, and retained stdout/stderr logs. +- [ ] Add the deterministic `bpy` fixture with step validation, object custom properties, GLB reimport verification, and optional PNG render. +- [ ] Add CLI `run` and `verify` exit-code behavior and test fake-bridge/argument paths. + +### Task 3: Wire server execution and SSE + +**Files:** `src/SomhairlesDream.Server/Program.fs`, `src/SomhairlesDream.Server/Store.fs`, server project/tests. + +- [ ] Add the Modeling reference and launch the same pipeline in a background task. +- [ ] Implement exact-run start, SSE, manifest, artifact, validation, conflict, and 404 responses. +- [ ] Add one-second stale observation without changing lifecycle status. + +### Task 4: Update browser and solution wiring + +**Files:** `src/SomhairlesDream.Frontend/App.fs`, `public/index.html`, `public/App.js`, and `SomhairlesDream.sln`. + +- [ ] Start a selected run, subscribe to its exact SSE stream, and expose `artifact-manifest-link` only on completion. +- [ ] Preserve replay behavior and the existing `Uint32BufferAttribute` mesh path. +- [ ] Include Modeling and CLI projects in the solution. + +### Task 5: Verify and publish + +- [ ] Run all project tests and builds. +- [ ] Run the real `bpy 5.0.1` integration and CLI verification, then server/browser checks. +- [ ] Review status/diff, commit only scoped project files, publish to the authorized bare repository, and verify `git ls-remote` plus cgit. 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 |