Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Link engineering assistance from the AI author guide

Yuechen Lic01003c1112c
diff --git a/docs/development/HELIOS-ENGINEERING-CAPABILITIES-X0.md b/docs/development/HELIOS-ENGINEERING-CAPABILITIES-X0.md
new file mode 100644
index 00000000..03dbfdec
--- /dev/null
+++ b/docs/development/HELIOS-ENGINEERING-CAPABILITIES-X0.md
@@ -0,0 +1,137 @@
+# Helios engineering capabilities and Dominatus async actuation
+
+Date: 2026-10-20
+
+## Result
+
+The first native capability pass works through real Helios uploads, authenticated
+Leviathan endpoints, Microsoft Semantic Kernel schema generation/typed invocation,
+and the existing compiler-backed candidate workflow. It adds practical reference
+lookup, parts-catalog filtering, typed parameter proposals and draft review ZIPs.
+No Semantic Kernel agent, planner or orchestration loop was introduced.
+
+**Success for the bounded native pass.** Live supplier services and Microsoft 365
+delivery are not implemented or claimed. Their remaining boundary is connected
+account authorization/token custody plus concrete provider adapters, rather than
+another change to the authoring or async execution model. No live LLM calls or
+account model-access checks were made; the earlier offline qualification decision
+remains in force.
+
+## Ownership and async roles
+
+| Layer | Responsibility |
+| --- | --- |
+| OptFlow Ai.Act / Ai.Await | Agent workflow dispatch, logical suspension and completion evidence |
+| C# async / await | Implementation of HTTP, storage and plugin operations |
+| Dominatus AsyncActuationHandler | Shared nonblocking operation contract; immutable invocation identity and cancellation |
+| ActuatorHost | Existing policy admission; task ownership; owner-tick terminal delivery; in-flight bookkeeping; shutdown |
+| Semantic Kernel | Native plugin metadata, nested DTO binding and function invocation |
+| Leviathan | Account/installation admission, reference storage and exact registered function grant |
+| Helios | Selected reference IDs, candidate state, source-revision checks, builds, review download and checkpoints |
+| Aetheris | Source legality, compiled geometry, measurements and format-specific export admission |
+
+An agent state issues Ai.Act and yields Ai.Await; its operation handler awaits I/O.
+An ASP.NET request awaits that same handler directly after its own admission, without
+inventing an AiWorld or polling ticks. A direct call does not silently execute
+ActuatorHost policies. The per-request registered grant still bounds SK invocation.
+
+Already-completed successful ValueTasks retain immediate completion semantics.
+Pending operations return immediately. Their observed results cross a queue and
+publish typed/untyped completion on the owning tick, once, in dispatch-ID order
+within the observed batch. Continuations cannot access the world through the new
+context. Cancellation wins over late success; removed agents receive no callbacks.
+Dispose cancels and suppresses publication; DisposeAsync additionally awaits owned
+observers. Shutdown still depends on cooperative cancellation; it cannot terminate
+arbitrary managed code or reverse an external effect.
+
+Tasks/continuations are not checkpoint data. Logical IDs and existing recorded
+completion/replay evidence remain the runtime contract. No durable live-call resume
+is claimed. The detailed convention is in Dominatus
+docs/actuators/ASYNC-ACTUATION.md.
+
+## Useful capability surface
+
+- Reference import: TXT/Markdown lines, PDF pages, DOCX paragraphs, CSV records and
+ XLSX worksheet cells. Original bytes and extracted data remain in the account's
+ existing object store, with SHA-256 identity. Another account cannot read them.
+- Native SK tools: search_references, read_reference, find_parts, bind_parameters
+ and prepare_review. Function schemas come from SK metadata; there is no second
+ independently maintained DTO schema or SK-controlled tool loop.
+- Parts filtering returns source rows and cell addresses. It does not certify fit,
+ infer units, fetch live stock/prices or place orders.
+- Parameter bindings require explicit units and finite literal numeric cells.
+ Unknown columns, duplicate/invalid parameter names, unsupported units and formulas
+ reject. Cached spreadsheet formula values are not recalculated evidence.
+- Review preparation validates reference locators and captures source hashes,
+ requirements, exact cited evidence and open issues. It remains an unapproved draft.
+- export_review requires a current successful candidate build and a matching review
+ manifest. It packages actual admitted SDK exports, source and review.json.
+ Export failure or stale source produces no new package; existing export admission
+ remains authoritative, including missing drawing requirements.
+
+Engineering references live under Files, keeping Version Control and AI Author
+separate. A checkpoint captures selected reference IDs; server documents remain
+server-owned. Import/task/restore actions exclude one another. Upload cancellation
+belongs to the component lifetime. Changing attachments invalidates stale agent
+context and unapplied candidates.
+
+## Qualification
+
+| Check | Result |
+| --- | --- |
+| Dominatus Release.slnx | 1,409 passed, 8 live-payment cases skipped, 18 target suites |
+| Dominatus Llm.OptFlow.Tests | 708 passed on net8.0 and 708 on net10.0 |
+| Dominatus Actuators.SemanticKernel.Tests | 70 passed on net8.0 and 70 on net10.0 |
+| Leviathan full solution | 64 passed |
+| Helios frontend build/full tests | Build passed; 123 tests in 28 files passed |
+| New source witness through CLI | validate/build succeeded; STEP analysis confirmed bounds and topology |
+| Actual browser | Uploaded requirements/catalog; attached both; built witness; detached catalog; restored checkpoint and both selections |
+| Review ZIP production packager | Bundled actual CLI STEP and source; round-trip verified unchanged STEP hash |
+
+The fixture is fixtures/Regression/EngineeringEvidence. Its requirements and catalog
+are explicitly synthetic. The built witness has bounds X/Y [-28,28] mm and Z [0,6]
+mm, one body, seven faces (six planes and one cylinder), 15 edges and 12 vertices.
+No tolerances or approval were invented. The STEP bytes retained in the review ZIP
+have SHA-256 da56f7401354c092cb7079cc749c92a3724abe16c28081d97bffd3158968914f.
+
+Detailed logs and the ZIP remain under ignored artifacts/local: sk-dominatus-full.log,
+sk-llm-full.log, sk-adapter-tests.log, sk-leviathan-full.log, sk-helios-tests.log,
+sk-plate-validate.json, sk-plate-build.json, sk-plate-analyze.json,
+sk-review-artifact.log, engineering-review.zip and author/engineering-references.png.
+
+The ZIP artifact is an offline packaging witness, not a live model-authored review.
+Gateway tests use synthetic provider HTTP responses through the real adapters.
+Document-format tests generate real PDF, DOCX and XLSX bytes in memory. The full
+Aetheris kernel suite was not rerun: no compiler/kernel/exporter C# changed. The
+actual CLI and Web SDK paths were used for the new source witness.
+
+## Repairs found during qualification
+
+- Nested JSON previously failed before SK could perform its typed binding. Cloned
+ JsonElements now survive the input document lifetime and bind through SK itself.
+- Structured SK results previously depended on ToString; DTOs now serialize as JSON.
+- The archive library's typed-array identity checks could treat cross-realm source
+ buffers as directories. The production packager normalizes views; tests assert
+ extracted source text, export bytes, citations and hashes.
+- Files used a full-height project explorer, burying references below blank space.
+ The explorer now takes its content height.
+- SK's transitive Pkcs 9.0.0 dependency triggered vulnerability diagnostics.
+ The owner pins patched 9.0.21. Dependency guards now inspect actual XML references
+ and Graph name segments, avoiding the false match in Cryptography.
+
+## Remaining explicit boundaries
+
+This is not a repository-wide async migration. SemanticKernelActuationHandler and
+LlmTextActuationHandler use the new contract. HTTP, process, HomeAssistant,
+streaming and synchronous LLM-scoring adapters still have legacy blocking paths.
+Streaming requires owner-thread progress delivery; model-backed scoring should
+obtain evidence asynchronously before deterministic scoring. Those migrations have
+a defined destination now; no additional async model is needed.
+
+PDF OCR/layout interpretation, Excel formula evaluation, XLSX named-table range
+selection, vector search, external supplier adapters, Graph/OAuth document access,
+SharePoint/OneDrive publication and external review synchronization remain outside
+this first native pass. The document library and review manifests are evidence
+surfaces, not automatic standards compliance or manufacturing certification.
+
+Public workflow: [Engineering assistance](../public/firmament/engineering-assistance.md).
diff --git a/docs/public/firmament/ai-author.md b/docs/public/firmament/ai-author.md
index 03dd56b0..733a4945 100644
--- a/docs/public/firmament/ai-author.md
+++ b/docs/public/firmament/ai-author.md
@@ -38,6 +38,9 @@ published dependency version.
## Work with the agent
+For specifications, catalog lookup, spreadsheet parameter proposals and draft
+review ZIPs, see [Engineering references and review packages](engineering-assistance.md).
+
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
diff --git a/docs/public/firmament/engineering-assistance.md b/docs/public/firmament/engineering-assistance.md
new file mode 100644
index 00000000..329a2795
--- /dev/null
+++ b/docs/public/firmament/engineering-assistance.md
@@ -0,0 +1,69 @@
+# Engineering references and review packages
+
+Helios AI Author can use attached specifications, datasheets, parts catalogs and
+parameter sheets. Semantic Kernel exposes typed tool schemas and invokes the
+registered functions. Dominatus retains effect execution; Aetheris remains the
+authority for source admission, geometry and measurements.
+
+## Attach evidence
+
+Open **Files → Engineering references**, sign in through Leviathan, and add a TXT,
+Markdown, text-bearing PDF, DOCX, CSV or XLSX file. Select the references the current
+workspace should expose to the agent. Up to ten can be attached. Files are limited
+to 4 MiB, PDFs to 100 pages, and tables to 2,000 data rows and 64 columns.
+
+References stay in your server account, including their original bytes. Another
+account cannot retrieve them by guessing an ID. Checkpoints preserve attachment
+IDs alongside source; they are not independent backups of the server's originals.
+Changing attachments clears stale agent context and unapplied candidates.
+
+Reference tools return the document's SHA-256 and its page, paragraph, line or cell
+location. PDF extraction requires selectable text; no OCR is performed. Complex
+PDF reading order is not an interpretation guarantee. Tables are read from CSV
+records or XLSX worksheets with a literal header row. Headers must be nonempty and
+unique. Formulas are flagged; cached formula results are never admitted as typed
+engineering parameters. Export formula-derived data as explicit values first.
+
+## Ask the agent
+
+Examples:
+
+- “Read the attached motor datasheet and cite the mounting pitch before editing.”
+- “Filter this bearing catalog for boreMm = 8 and outerDiameterMm ≤ 22. Show the
+ source rows before choosing a candidate.”
+- “Bind widthMm to width in mm and angleDeg to angle in degrees. Make the two
+ variants from this parameter sheet, then build and compare their bounds.”
+- “Prepare a review package against the attached requirements, noting unresolved
+ tolerances and inspection requirements.”
+
+Catalog filters are literal numeric comparisons against explicitly named columns.
+They return candidates, not a fit certification or live price/availability quote.
+No live supplier connection is implied. Units must come from the source or user.
+Parameter projection requires explicit units: mm, cm, m, in, deg, rad or scalar.
+It returns proposals with cell provenance; it does not bypass source editing or
+compilation. The agent must still author valid Firmament and obtain build evidence.
+
+## Review export
+
+The agent first prepares a draft manifest with cited requirements/comments and
+open issues. The manifest is tied to hashes of the current source documents.
+After a successful candidate build, it can request export_review with admitted
+formats, such as STEP and PDF when the compiler offers both for that model.
+
+**Download draft review package** appears in AI Author when export succeeds.
+The ZIP contains all candidate source documents, actual compiler exports, their
+hashes, and review.json with cited evidence, source hashes, compiler bounds and
+open issues. A stale manifest, failed build or failed exporter produces no new
+package. The package describes a candidate and is explicitly not engineering
+approval. It does not invent tolerances or sign drawn/checked/approved fields.
+
+Source evidence, model inference and compiler measurements are different kinds of
+evidence. Compilation alone does not prove manufacturability or requirements
+compliance. Human review remains visible in the package's draft status.
+
+This pass implements native Semantic Kernel tools. Live supplier APIs,
+SharePoint/OneDrive delivery, OAuth connected accounts and external review/comment
+synchronization are not implemented. Existing PDF/STEP/etc. exporters remain the
+export authority; SK does not redraw or reconstruct them.
+
+For the agent connection and checkpoint workflow, see [AI Author](ai-author.md).
diff --git a/fixtures/Regression/EngineeringEvidence/README.md b/fixtures/Regression/EngineeringEvidence/README.md
new file mode 100644
index 00000000..8059c30a
--- /dev/null
+++ b/fixtures/Regression/EngineeringEvidence/README.md
@@ -0,0 +1,15 @@
+# Engineering evidence witness
+
+These are synthetic qualification inputs, not manufacturer specifications or
+supplier offers. Upload requirements.md and catalog.csv through Helios Files →
+Engineering references. Ask the agent to filter boreMm ≥ 8 and widthMm ≤ 60,
+bind widthMm to width in mm, and prepare a draft review package.
+
+The selected synthetic row is M23, width 56 mm and bore 8 mm. plate.firmament is
+the corresponding source witness: 56 × 56 × 6 mm with an 8 mm through hole.
+Expected bounds are X/Y [-28, 28] mm and Z [0, 6] mm. The exact volume is
+18,816 − 96π mm³. The source remains the geometry authority.
+
+The automated host tests also generate real PDF, DOCX and XLSX inputs in memory;
+formula cells reject parameter binding. Detailed local qualification logs belong
+under artifacts/local, not this fixture directory.
diff --git a/fixtures/Regression/EngineeringEvidence/catalog.csv b/fixtures/Regression/EngineeringEvidence/catalog.csv
new file mode 100644
index 00000000..71a3f5b9
--- /dev/null
+++ b/fixtures/Regression/EngineeringEvidence/catalog.csv
@@ -0,0 +1,3 @@
+sku,widthMm,boreMm
+M17,42,5
+M23,56,8
diff --git a/fixtures/Regression/EngineeringEvidence/plate.firmament b/fixtures/Regression/EngineeringEvidence/plate.firmament
new file mode 100644
index 00000000..8be9aeda
--- /dev/null
+++ b/fixtures/Regression/EngineeringEvidence/plate.firmament
@@ -0,0 +1,7 @@
+Model ReferencePlate {
+ units: mm
+ Box stock { size: [56mm, 56mm, 6mm] }
+ Modify stock {
+ Hole<Shaft> bore { on: +Z center: Point2(0mm, 0mm) diameter: 8mm end: ThroughAll }
+ }
+}
diff --git a/fixtures/Regression/EngineeringEvidence/requirements.md b/fixtures/Regression/EngineeringEvidence/requirements.md
new file mode 100644
index 00000000..20c44d24
--- /dev/null
+++ b/fixtures/Regression/EngineeringEvidence/requirements.md
@@ -0,0 +1,4 @@
+# Synthetic plate requirement
+The plate is 56 mm wide, 56 mm long and 6 mm thick.
+The centered through hole is 8 mm in diameter.
+Tolerances and manufacturing approval remain unspecified and must be reviewed.