# somhairles-dream-fsharp

F# implementation of the heritage boat modeling pipeline: a Blender-driven
artifact pipeline (CLI), an ASP.NET server that runs and observes artifact
runs, and a Fable/Three.js frontend that follows run progress live.

Architecture boundary: F# owns the frontend, backend, and orchestration
(pipeline, artifacts, verification, serving). Python (`bpy`) owns geometry
generation inside `stage/blender/fixture.py`. There is no F# geometry DSL.

## Layout

- `src/SomhairlesDream.Shared` — domain, run state, replay, artifact contracts
- `src/SomhairlesDream.Modeling` — pipeline, Blender process bridge, verifier
- `src/SomhairlesDream.Cli` — `run` and `verify` commands
- `src/SomhairlesDream.Server` — run API, SSE, static frontend host
- `src/SomhairlesDream.Frontend` — Fable browser app compiled to `public/`
- `stage/blender/fixture.py` — deterministic bpy fixture (3 steps, 7 objects)
- `public/` — static frontend served by the server (index, styles, JS bundle)
- `tests/` — xUnit test projects per layer

## Build and test

Requires .NET SDK 8 (pinned by `global.json`). Warnings are errors.

```sh
dotnet build SomhairlesDream.sln
dotnet test SomhairlesDream.sln
```

## Frontend (Fable)

`src/SomhairlesDream.Frontend` compiles to `public/`. Regenerate after edits:

```sh
dotnet fable src/SomhairlesDream.Frontend/SomhairlesDream.Frontend.fsproj \
  --outDir public --noRestore
```

The server project copies `public/**` into its build output
(`CopyToOutputDirectory=PreserveNewest`), so rerun `dotnet build` on the server
after regenerating the bundle.

## Server

```sh
dotnet run --project src/SomhairlesDream.Server
```

Environment variables (all optional):

- `SOMHAIRLES_ARTIFACT_ROOT` — artifact output root (default `.artifacts`)
- `SOMHAIRLES_STAGE_ROOT` — stage directory containing `blender/fixture.py`
  (default `stage`)
- `SOMHAIRLES_BPYTHON` — Python interpreter used to run the fixture
  (default `python3`)

Routes used by the frontend: `POST /api/runs/start`,
`GET /api/runs/events?projectId=...&runId=...` (run-scoped SSE),
`GET /api/artifacts/manifest`, `GET /api/artifacts/file`. The server binds to
the ASP.NET default (add `--urls http://127.0.0.1:8099` to match the legacy
port).

## CLI

```sh
dotnet run --project src/SomhairlesDream.Cli -- run [options]
dotnet run --project src/SomhairlesDream.Cli -- verify <manifest.json>
```

`run` options: `--project-id`, `--run-id`, `--base-id`, `--target-id`,
`--output-root`, `--stage-root`, `--python`, `--render`. `SOMHAIRLES_BPYTHON`
sets the default interpreter. Exit codes: `0` success, `2` usage, `3` bridge
failure, `4` pipeline/verify failure. On success it prints the manifest path.

A run produces, under `<output-root>/<projectId>/<runId>/`:

- `events.ndjson`, `manifest.json`
- `logs/01-foundation.log`, `02-frame.log`, `03-cabin.log`
- `steps/01-foundation.glb`, `02-frame.glb`, `03-cabin.glb`

`verify` recomputes hashes, checks log presence, path containment, object-ID
proofs, timestamps, and duplicate steps without needing Blender.

## Python interpreter for bpy

The fixture requires a Python that can `import bpy` (Blender as a module,
version >= 3.0.0). A system `python3` usually cannot. This project was
verified with a uv-managed environment at `/tmp/bpyenv/bin/python`
(`bpy 5.0.1`). Note that `/tmp` is ephemeral; recreate or point
`SOMHAIRLES_BPYTHON`/`--python` at any interpreter that provides `bpy`.

Example:

```sh
dotnet run --project src/SomhairlesDream.Cli -- run \
  --output-root .artifacts --python /tmp/bpyenv/bin/python
```

## Fixture limitations

- `stage/blender/fixture.py` is a deterministic placeholder geometry fixture
  (named cubes with `object_id` custom properties), not a production model.
- Bridge timeout is 120 seconds per step; the bridge requires the fixture to
  write its result JSON to `--result-output` (stdout/stderr are diagnostics
  only, retained as step logs).
- Renders are produced only with `--render` (512x512 PNG per step).
- Reimport verification counts objects (`2 -> 5 -> 7` across the three steps)
  and checks the `object_id` custom properties survive the GLB round-trip.

## Verification status

- Full solution test suite and Release build: clean (0 warnings/errors).
- Real CLI pipeline with `/tmp/bpyenv/bin/python`: 3 GLBs + logs + manifest,
  `verify` exit 0.
- Browser end-to-end behavior and production fidelity are NOT yet verified;
  the pipeline contract tests cover the generated bundle routes only.