Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add AI Author link to Firmament syntax docs

Yuechen Li0b6165159437
diff --git a/docs/development/HELIOS-OPENAI-AUTHOR-X0.md b/docs/development/HELIOS-OPENAI-AUTHOR-X0.md
new file mode 100644
index 00000000..f5daf8ad
--- /dev/null
+++ b/docs/development/HELIOS-OPENAI-AUTHOR-X0.md
@@ -0,0 +1,178 @@
+# Helios OpenAI author: first-provider integration
+
+Date: 2026-10-20 (America/Los_Angeles)
+
+## Result and qualification boundary
+
+The first provider path is implemented against the maintained Dominatus source
+checkout, replacing Leviathan's active Dominatus 0.3 package references. The model
+choices are GPT-6 Astra (`gpt-6-astra`), GPT-6.1 Sol (`gpt-6.1-sol`, default) and
+GPT-6 Luna (`gpt-6-luna`). The author confirmed the Luna spelling after checking
+the official model catalog.
+
+**Success for the bounded offline integration.** The user explicitly requested
+offline qualification. No paid/live inference, account model-access verification,
+or generated-part quality claim is made. Authenticated HTTP tests use a synthetic
+provider transport through the real endpoint/adapter; the UI reports missing
+credentials and disables Run rather than fabricating a response.
+
+This is not completion of the entire durable-agent/cloud-checkpoint proposal.
+Local recovery works; server-backed multi-file history remains an explicit next
+boundary.
+
+## Ownership
+
+| Owner | Responsibility |
+| --- | --- |
+| Dominatus.Llm.OptFlow | New explicit conversation/provider contract; OpenAI Responses function calls; original provider items and usage; incomplete/error handling |
+| Dominatus.Llm.Context | Current workspace manifest, content hashes and engineering requirements assembled into a budgeted packet; required-context omission rejects |
+| Leviathan | Authenticated, CSRF-protected gateway, active Helios installation check, fixed provider endpoint, server credential, registered tool schemas |
+| Helios | Explicit tool loop, candidate source state, cancellation/deadline, working-revision comparison, review/automatic apply, local checkpoints |
+| Aetheris public SDK/compiler | Profile/domain/syntax admission, actual candidate builds and measurement queries; no separate UI validator |
+
+The conversation adapter is additive. Existing `ILlmClient`, text/decision helpers
+and cassette formats are unchanged. Parameterless HttpClient transport construction
+is preserved; hosts can additionally inject an owned/factory HttpClient.
+The wire-level integration test exposed an existing content-header defect:
+`StringContent`'s default text/plain survived a declared application/json header
+because adding a second single-value Content-Type silently failed. The shared
+transport now replaces declared content headers. This was reproduced as a failing
+gateway test before repair and is covered in both the library and host tests.
+Opaque reasoning items are retained for stateless Responses continuation.
+`store: false` is explicit. A provider response cannot execute tools itself.
+
+The old vendored RustSimulator sample script remains linked in Leviathan as a
+legacy sample, but its active Core/OptFlow/Ariadne/LLM runtime comes from current
+Dominatus. No broad sample/game migration was attempted. Cross-version restore
+of archived 0.3 agent checkpoint files was not qualified by these tests.
+
+## Author workflow
+
+The agent chooses its engineering strategy. It can read project files, replace a
+unique exact source occurrence, create documents, inspect schema/outline, build
+the candidate and measure its built model. There is no per-edit permission prompt
+or arbitrary edit-count limit. It may author existing Firmament Assert statements;
+those are proposed checks rather than proof of the underlying assumptions.
+
+Tool edits affect a separate project copy and a separate SDK compiler worker.
+An invalid build is recorded as rejection. Changes must build before application,
+and application compares the captured working-source revision. Source changes by
+the human invalidate application. Changing engineering requirements clears an
+outstanding candidate. A normal workspace rebuild remains authoritative after
+application and retains the last valid geometry on failure.
+
+The default is automatic application after a successful build. Review mode shows
+before/after source per changed document and requires Apply candidate. Model
+switching is explicit; provider failure never selects another model silently.
+Task budget defaults to five minutes, adjustable in the panel. Cancellation stops
+HTTP work and terminates the isolated compiler worker. An applying transaction
+finishes rather than reporting that already-applied source was cancelled.
+
+The panel remains mounted while another utility tab is inspected. Closing the
+workspace cancels pending agent work. Conversation state is explicit but currently
+in memory; it is not a durable Dominatus HFSM task or a resumable server session.
+
+## Local checkpoint contract
+
+IndexedDB checkpoints capture all open workspace document strings, the root and
+the panel's engineering requirements. They are immutable entries. Recovery is
+saved before an AI task and before restore. Restoring creates a new state with a
+restored-from identity and retains later states; it never deletes the forward
+history. Invalid drafts can be stored and restored independently of build status.
+
+The real browser witness saved the original 50 x 40 x 8 mm mounting plate with
+its hole, changed it to an 80 x 40 x 8 mm plain box and changed its requirements,
+then restored the original source/requirements and the later state. Each restore
+ran the normal compiler/build path. History also survived a fresh editor reload.
+Switching Inspector/AI Author retained the restored requirements.
+
+Local mode has one local workspace history; authenticated project IDs separate
+their histories. Checkpoints are browser-local, not cloud backups. Embedded import
+text is retained with source; arbitrary external/binary resources are not newly
+captured by this implementation.
+
+The existing cloud Save endpoint accepts one source string. Once AI editing can
+create module files, calling that a complete save would lose intent. Helios now
+refuses cloud save for a multi-file workspace or an active non-root document.
+The next persistence task is a versioned complete project manifest in Leviathan
+and compatible open/save/publication/fork contracts, rather than another parallel
+save store.
+
+## Evidence
+
+| Lane | Result |
+| --- | --- |
+| Dominatus.Release.slnx, serial | 1,401 passed across 18 target suites; 8 external/live payment smoke cases skipped |
+| Dominatus.Llm.OptFlow.Tests | 694 passed on net8.0 and 694 on net10.0 |
+| Dominatus.Llm.Context.Tests | 70 passed on net8.0 and 70 on net10.0 |
+| Leviathan full solution | 54 passed, including authenticated provider fixtures and existing lifecycle/persistence tests |
+| Helios build:fast | Passed; existing bundle-size advisory |
+| Helios complete unit suite | 113 passed in 25 files |
+| Browser | Model picker, honest unconfigured state, source/requirements rollback and forward restore, reload persistence and utility-tab retention |
+
+The new tests cover preserved provider items, all three model IDs, rejected
+incomplete/unknown/duplicate/malformed tool calls, credential-safe errors, failed
+candidate admission, stale measurement refusal, isolated edits, cancellation of an
+in-flight compiler, multi-file checkpoints and refusal of partial cloud saves.
+
+No Aetheris compiler/kernel implementation changed in this pass. Its full kernel
+suite was not rerun for this provider/UI integration; this report does not reuse
+the previous sketcher pass's kernel totals as new evidence.
+
+Detailed logs and screenshot remain ignored local artifacts:
+
+- `artifacts/local/author-dominatus-release-tests.log`
+- `artifacts/local/author-dominatus-llm-tests.log`
+- `artifacts/local/author-dominatus-context-tests.log`
+- `artifacts/local/author-content-type-before.log` (intentional failing wire witness before repair)
+- `artifacts/local/author-server-tests.log`
+- `artifacts/local/author-helios-build.log`
+- `artifacts/local/author-helios-tests.log`
+- `artifacts/local/author/openai-panel-checkpoints.png`
+
+## Deployment and remaining boundaries
+
+Leviathan now requires the matching Dominatus source changes beside its checkout,
+or an explicit `DominatusSourceRoot`. There is a clear build error for an absent
+conversation API. Its Dockerfile accepts a named Dominatus build context:
+`docker build --build-context dominatus=../Dominatus .`. The image definition was
+updated but no Docker image build/deployment was qualified here. The eventual
+published package release should replace this coordinated source dependency.
+
+This first path uses the operator's server `OPENAI_API_KEY`, not per-user BYOK or
+ChatGPT-plan authentication. It is not qualification for an unrestricted public
+shared-key service. Existing auth and installation boundaries remain required.
+Requests are nonstreaming, with 8,192 maximum output tokens per provider turn, a
+1,000,000-character gateway request budget and a 2,000,000-character candidate
+source budget. Exceeding a budget fails explicitly; no source/context is silently
+truncated. Reported token counts cover completed turns and are not a billing
+guarantee for cancellation or failed requests.
+
+Still pending: live model access and engineering dogfood, server project manifests
+and history, export/import of checkpoints, durable conversation cassettes/task
+resume, streamed assistant output, per-user credential custody and other provider
+or local CLI-agent adapters. No deterministic live model replay is claimed.
+
+Public workflow: [AI author guide](../public/firmament/ai-author.md).
+
+## Version Control tab follow-up
+
+Checkpoint controls now live in a separate Version Control utility tab. The shared
+workspace owner retains one IndexedDB checkpoint store; moving its code out of
+the author module leaves existing browser histories intact. AI Author retains
+conversation state when switching tabs and still saves pre-task and applied-change
+recovery checkpoints. Restore rebuilds the full source workspace, restores its
+engineering requirements, and clears stale agent context and candidates. Save and
+restore wait for agent/project operations to finish.
+
+Qualification: Helios frontend build and all 116 tests in 26 files passed.
+Tests cover shell tab separation, normal rebuild on restore, all module sources,
+requirements, invalid drafts, retained later states, conversation drafts, automatic
+agent checkpoints, and exclusion of concurrent restore during an agent task.
+Browser qualification saved the mounting plate, built a temporary 80 × 40 × 8 mm
+box, restored the original plate with its hole, and confirmed the normal build
+finished without diagnostics. Existing histories remained readable. This is a
+frontend-only follow-up; no .NET code changed and no .NET hosts were launched.
+Evidence: `artifacts/local/version-control-build.log`,
+`artifacts/local/version-control-tests.log`, and
+`artifacts/local/author/version-control-tab.png`.
diff --git a/docs/public/firmament/ai-author.md b/docs/public/firmament/ai-author.md
new file mode 100644
index 00000000..03dd56b0
--- /dev/null
+++ b/docs/public/firmament/ai-author.md
@@ -0,0 +1,102 @@
+# AI author in Helios
+
+The AI Author panel connects to OpenAI, Claude and Gemini through Leviathan.
+Choose a provider, then a model. GPT-6.1 Sol remains the default. The server supplies
+the model catalog and reports credential configuration separately for each provider.
+A failed request never silently changes providers or models.
+
+| Provider | Models | Server environment variable |
+| --- | --- | --- |
+| OpenAI | GPT-6 Astra, GPT-6.1 Sol, GPT-6 Luna | `OPENAI_API_KEY` |
+| Claude | Opus 5.5, Sonnet 5.5, Haiku 5.5 | `ANTHROPIC_API_KEY` |
+| Gemini | Gemini 4 Argon, Gemini 3.8 Flash | `GEMINI_API_KEY` |
+
+The model IDs follow the [OpenAI catalog](https://developers.openai.com/api/docs/models),
+[Claude catalog](https://platform.claude.com/docs/en/models/overview), and
+[Gemini catalog](https://ai.google.dev/gemini-api/docs/models), checked October 20, 2026.
+Account access and quota still depend on each provider. These choices use the
+providers' APIs, independently of consumer chat subscriptions.
+
+## Connect
+
+Run Helios with its Leviathan backend and sign in. The account needs an active
+Helios installation. Configure the selected provider's key in the server environment
+before starting Leviathan. Only configure the providers you need; a missing key
+disables Run for that provider without disabling the others. The panel reports
+missing configuration explicitly. Never put keys in Firmament source or chat.
+This integration uses the operator's server credentials; it does not implement
+per-user key custody or consumer subscription sign-in. Requests consume the
+selected provider's server account API usage.
+
+The source workspace requires adjacent current Dominatus and Leviathan checkouts.
+Leviathan's `DominatusSourceRoot` build property can select another explicit
+Dominatus source location. Its old vendored snapshot is not the active runtime.
+For a Docker build from Leviathan, use
+`docker build --build-context dominatus=../Dominatus .`. The new Dominatus
+conversation adapters must ship together with this integration; they are not yet a
+published dependency version.
+
+## Work with the agent
+
+Changing provider or model starts a fresh conversation and discards any unapplied
+candidate. The current project, engineering requirements, unsent prompt and
+Version Control history remain. Switching utility tabs alone preserves the
+conversation. This keeps provider-specific reasoning signatures with the model
+that created them.
+
+Describe the part or change and enter any engineering requirements. The agent
+chooses its approach and can read project files, edit a separate candidate,
+request the compiler schema/outline, build, and query measurements. It can write
+Assert statements where the compiler supports them. An agent's proposed assertion
+does not independently establish that its assumptions are correct.
+Free-text requirements guide the agent; this pass does not automatically prove
+their satisfaction. Executable assertions and measurement results provide the
+checks that the compiler/kernel can actually perform.
+
+The initial tools edit exact source occurrences. They can create new project
+documents; they have no shell or arbitrary disk access. Measurements use the same
+SDK/kernel authority as the UI. The model must use actual measurement evidence;
+successful compilation does not prove manufacturability.
+
+By default, successfully built changes apply automatically. Turn off **Apply
+changes after a successful build** to review the candidate first. Each changed
+file shows its previous and proposed source. A rejected candidate never replaces
+the working project. If the human edits during a task, application rejects the
+stale revision. If the normal workspace rebuild subsequently fails, the last valid
+geometry remains and the source/draft failure is reported.
+
+The task time budget defaults to five minutes and can be changed. **Stop agent**
+cancels further provider/tool work and discards unapplied candidate changes. A
+transaction that has started applying is allowed to finish; checkpoints provide
+recovery. Token usage reports completed provider turns, not a billing guarantee
+for failed or cancelled requests.
+
+## Version Control
+
+Open the separate **Version Control** utility tab to save or restore a project state.
+AI Author stays focused on the conversation; switching tabs retains the conversation
+and any running task. Recovery
+checkpoints are also saved before an AI task and before restoring another state.
+They capture the root document, all document strings in the open workspace, and
+the current engineering requirements. Imported content already embedded in those
+documents is preserved. This is not an independent capture of arbitrary external
+filesystem assets.
+
+Restoring copies the saved state into a new current checkpoint and retains later
+checkpoints, so another state can be restored again. Invalid drafts can be saved
+and restored; saving is distinct from compiling successfully. Restoring rebuilds
+the source rather than pretending an old mesh proves the restored source valid.
+Restoring also restores engineering requirements and clears stale agent context
+and candidates. Save and restore controls wait for running agent tasks and project
+operations to finish.
+
+**These checkpoints live in this browser's IndexedDB.** Clearing browser storage
+removes them. They are not cloud backups. Local mode currently uses one local
+workspace history; signed-in projects have separate histories. Conversation
+transcripts are session state and are not durable resumable agent tasks.
+
+The existing cloud Save endpoint still persists a single source document. Helios
+refuses that operation for a multi-file workspace instead of marking a partial
+save as complete. Server-backed project manifests/checkpoint history, binary asset
+pinning, checkpoint export/import, durable agent replay/resume, streamed assistant
+text and local CLI-agent adapters remain follow-up work.
diff --git a/docs/public/firmament/syntax.md b/docs/public/firmament/syntax.md
index c8d00fe6..7c37dcb8 100644
--- a/docs/public/firmament/syntax.md
+++ b/docs/public/firmament/syntax.md
@@ -15,6 +15,8 @@ make it legal in every other domain.
For visual profile authoring in Helios, use **Command palette → New sketch part**.
The [sketch workspace](sketcher.md) edits the same dimensions and compile-time
parameters described here; its 2D preview is followed by the normal solid build.
+For agent-assisted source editing, see [AI Author](ai-author.md). It prepares
+candidate changes through the same compiler, with checkpoint recovery.
**Complete file — a plate with a through hole:**