ATOCore/docs/architecture/tool-handoff-boundaries.md

# Tool Hand-off Boundaries (KB-CAD / KB-FEM and friends)

## Why this document exists

The engineering layer V1 will accumulate typed entities about
projects, subsystems, components, materials, requirements,
constraints, decisions, parameters, analysis models, results, and
validation claims. Many of those concepts also live in real
external tools — CAD systems, FEM solvers, BOM managers, PLM
databases, vendor portals.

The first big design decision before writing any entity-layer code
is: **what is AtoCore's read/write relationship with each of those
external tools?**

The wrong answer in either direction is expensive:

- Too read-only: AtoCore becomes a stale shadow of the tools and
  loses the trust battle the moment a value drifts.
- Too bidirectional: AtoCore takes on responsibilities it can't
  reliably honor (live sync, conflict resolution against external
  schemas, write-back validation), and the project never ships.

This document picks a position for V1.

## The position

> **AtoCore is a one-way mirror in V1.** External tools push
> structured exports into AtoCore. AtoCore never pushes back.

That position has three corollaries:

1. **External tools remain the source of truth for everything they
   already manage.** A CAD model is canonical for geometry; a FEM
   project is canonical for meshes and solver settings; KB-CAD is
   canonical for whatever KB-CAD already calls canonical.
2. **AtoCore is the source of truth for the *AtoCore-shaped*
   record** of those facts: the Decision that selected the geometry,
   the Requirement the geometry satisfies, the ValidationClaim the
   FEM result supports. AtoCore does not duplicate the external
   tool's primary representation; it stores the structured *facts
   about* it.
3. **The boundary is enforced by absence.** No write endpoint in
   AtoCore ever generates a `.prt`, a `.fem`, an export to a PLM
   schema, or a vendor purchase order. If we find ourselves wanting
   to add such an endpoint in V1, we should stop and reconsider
   the V1 scope.

## Why one-way and not bidirectional

Bidirectional sync between independent systems is one of the
hardest problems in engineering software. The honest reasons we
are not attempting it in V1:

1. **Schema drift.** External tools evolve their schemas
   independently. A bidirectional sync would have to track every
   schema version of every external tool we touch. That is a
   permanent maintenance tax.
2. **Conflict semantics.** When AtoCore and an external tool
   disagree on the same field, "who wins" is a per-tool, per-field
   decision. There is no general rule. Bidirectional sync would
   require us to specify that decision exhaustively.
3. **Trust hierarchy.** AtoCore's whole point is the trust
   hierarchy: trusted project state > entities > memories. If we
   let entities push values back into the external tools, we
   silently elevate AtoCore's confidence to "high enough to write
   to a CAD model", which it almost never deserves.
4. **Velocity.** A bidirectional engineering layer is a
   multi-year project. A one-way mirror is a months project. The
   value-to-effort ratio favors one-way for V1 by an enormous
   margin.
5. **Reversibility.** We can always add bidirectional sync later
   on a per-tool basis once V1 has shown itself to be useful. We
   cannot easily walk back a half-finished bidirectional sync that
   has already corrupted data in someone's CAD model.

## Per-tool stance for V1

| External tool | V1 stance | What AtoCore reads in | What AtoCore writes back |
|---|---|---|---|
| **KB-CAD** (Antoine's CAD knowledge base) | one-way mirror | structured exports of subsystems, components, materials, parameters via a documented JSON or CSV shape | nothing |
| **KB-FEM** (Antoine's FEM knowledge base) | one-way mirror | structured exports of analysis models, results, validation claims | nothing |
| **NX / Siemens NX** (the CAD tool itself) | not connected in V1 | nothing direct — only what KB-CAD exports about NX projects | nothing |
| **PKM (Obsidian / markdown vault)** | already connected via the ingestion pipeline (Phase 1) | full markdown/text corpus per the ingestion-waves doc | nothing |
| **Gitea repos** | already connected via the ingestion pipeline | repo markdown/text per project | nothing |
| **OpenClaw** (the LLM agent) | already connected via the read-only helper skill on the T420 | nothing — OpenClaw reads from AtoCore | nothing — OpenClaw does not write into AtoCore |
| **AtoDrive** (operational truth layer, future) | future: bidirectional with AtoDrive itself, but AtoDrive is internal to AtoCore so this isn't an external tool boundary | n/a in V1 | n/a in V1 |
| **PLM / vendor portals / cost systems** | not in V1 scope | nothing | nothing |

## What "one-way mirror" actually looks like in code

AtoCore exposes an ingestion endpoint per external tool that
accepts a structured export and turns it into entity candidates.
The endpoint is read-side from AtoCore's perspective (it reads
from a file or HTTP body), even though the external tool is the
one initiating the call.

Proposed V1 ingestion endpoints:

```
POST /ingest/kb-cad/export       body: KB-CAD export JSON
POST /ingest/kb-fem/export       body: KB-FEM export JSON
```

Each endpoint:

1. Validates the export against the documented schema
2. Maps each export record to an entity candidate (status="candidate")
3. Carries the export's source identifier into the candidate's
   provenance fields (source_artifact_id, exporter_version, etc.)
4. Returns a summary: how many candidates were created, how many
   were dropped as duplicates, how many failed schema validation
5. Does NOT auto-promote anything

The KB-CAD and KB-FEM teams (which is to say, future-you) own the
exporter scripts that produce these JSON bodies. Those scripts
live in the KB-CAD / KB-FEM repos respectively, not in AtoCore.

## The export schemas (sketch, not final)

These are starting shapes, intentionally minimal. The schemas
will be refined in `kb-cad-export-schema.md` and
`kb-fem-export-schema.md` once the V1 ontology lands.

### KB-CAD export shape (starting sketch)

```json
{
  "exporter": "kb-cad",
  "exporter_version": "1.0.0",
  "exported_at": "2026-04-07T12:00:00Z",
  "project": "p05-interferometer",
  "subsystems": [
    {
      "id": "subsystem.optical-frame",
      "name": "Optical frame",
      "parent": null,
      "components": [
        {
          "id": "component.lateral-support-pad",
          "name": "Lateral support pad",
          "material": "GF-PTFE",
          "parameters": {
            "thickness_mm": 3.0,
            "preload_n": 12.0
          },
          "source_artifact": "kb-cad://p05/subsystems/optical-frame#lateral-support"
        }
      ]
    }
  ]
}
```

### KB-FEM export shape (starting sketch)

```json
{
  "exporter": "kb-fem",
  "exporter_version": "1.0.0",
  "exported_at": "2026-04-07T12:00:00Z",
  "project": "p05-interferometer",
  "analysis_models": [
    {
      "id": "model.optical-frame-modal",
      "name": "Optical frame modal analysis v3",
      "subsystem": "subsystem.optical-frame",
      "results": [
        {
          "id": "result.first-mode-frequency",
          "name": "First-mode frequency",
          "value": 187.4,
          "unit": "Hz",
          "supports_validation_claim": "claim.frame-rigidity-min-150hz",
          "source_artifact": "kb-fem://p05/models/optical-frame-modal#first-mode"
        }
      ]
    }
  ]
}
```

These shapes will evolve. The point of including them now is to
make the one-way mirror concrete: it is a small, well-defined
JSON shape, not "AtoCore reaches into KB-CAD's database".

## What AtoCore is allowed to do with the imported records

After ingestion, the imported records become entity candidates
in AtoCore's own table. From that point forward they follow the
exact same lifecycle as any other candidate:

- they sit at status="candidate" until a human reviews them
- the reviewer promotes them to status="active" or rejects them
- the active entities are queryable via the engineering query
  catalog (Q-001 through Q-020)
- the active entities can be referenced from Decisions, Requirements,
  ValidationClaims, etc. via the V1 relationship types

The imported records are never automatically pushed into trusted
project state, never modified in place after import (they are
superseded by re-imports, not edited), and never written back to
the external tool.

## What happens when KB-CAD changes a value AtoCore already has

This is the canonical "drift" scenario. The flow:

1. KB-CAD exports a fresh JSON. Component `component.lateral-support-pad`
   now has `material: "PEEK"` instead of `material: "GF-PTFE"`.
2. AtoCore's ingestion endpoint sees the same `id` and a different
   value.
3. The ingestion endpoint creates a new entity candidate with the
   new value, **does NOT delete or modify the existing active
   entity**, and creates a `conflicts` row linking the two members
   (per the conflict model doc).
4. The reviewer sees an open conflict on the next visit to
   `/conflicts`.
5. The reviewer either:
   - **promotes the new value** (the active is superseded, the
     candidate becomes the new active, the audit trail keeps both)
   - **rejects the new value** (the candidate is invalidated, the
     active stays — useful when the export was wrong)
   - **dismisses the conflict** (declares them not actually about
     the same thing, both stay active)

The reviewer never touches KB-CAD from AtoCore. If the resolution
implies a change in KB-CAD itself, the reviewer makes that change
in KB-CAD, then re-exports.

## What about NX directly?

NX (Siemens NX) is the underlying CAD tool that KB-CAD wraps.
**NX is not connected to AtoCore in V1.** Any facts about NX
projects flow through KB-CAD as the structured intermediate. This
gives us:

- **One schema to maintain.** AtoCore only has to understand the
  KB-CAD export shape, not the NX API.
- **One ownership boundary.** KB-CAD owns the question of "what's
  in NX". AtoCore owns the question of "what's in the typed
  knowledge base".
- **Future flexibility.** When NX is replaced or upgraded, only
  KB-CAD has to adapt; AtoCore doesn't notice.

The same logic applies to FEM solvers (Nastran, Abaqus, ANSYS):
KB-FEM is the structured intermediate, AtoCore never talks to the
solver directly.

## The hard-line invariants

These are the things V1 will not do, regardless of how convenient
they might seem:

1. **No write to external tools.** No POST/PUT/PATCH to any
   external API, no file generation that gets written into a
   CAD/FEM project tree, no email/chat sends.
2. **No live polling.** AtoCore does not poll KB-CAD or KB-FEM on
   a schedule. Imports are explicit pushes from the external tool
   into AtoCore's ingestion endpoint.
3. **No silent merging.** Every value drift surfaces as a
   conflict for the reviewer (per the conflict model doc).
4. **No schema fan-out.** AtoCore does not store every field that
   KB-CAD knows about. Only fields that map to one of the V1
   entity types make it into AtoCore. Everything else is dropped
   at the import boundary.
5. **No external-tool-specific logic in entity types.** A
   `Component` in AtoCore is the same shape regardless of whether
   it came from KB-CAD, KB-FEM, the PKM, or a hand-curated
   project state entry. The source is recorded in provenance,
   not in the entity shape.

## What this enables

With the one-way mirror locked in, V1 implementation can focus on:

- The entity table and its lifecycle
- The two `/ingest/kb-cad/export` and `/ingest/kb-fem/export`
  endpoints with their JSON validators
- The candidate review queue extension (already designed in
  `promotion-rules.md`)
- The conflict model (already designed in `conflict-model.md`)
- The query catalog implementation (already designed in
  `engineering-query-catalog.md`)

None of those are unbounded. Each is a finite, well-defined
implementation task. The one-way mirror is the choice that makes
V1 finishable.

## What V2 might consider (deferred)

After V1 has been live and demonstrably useful for a quarter or
two, the questions that become reasonable to revisit:

1. **Selective write-back to KB-CAD for low-risk fields.** For
   example, AtoCore could push back a "Decision id linked to this
   component" annotation that KB-CAD then displays without it
   being canonical there. Read-only annotations from AtoCore's
   perspective, advisory metadata from KB-CAD's perspective.
2. **Live polling for very small payloads.** A daily poll of
   "what subsystem ids exist in KB-CAD now" so AtoCore can flag
   subsystems that disappeared from KB-CAD without an explicit
   AtoCore invalidation.
3. **Direct NX integration** if the KB-CAD layer becomes a
   bottleneck — but only if the friction is real, not theoretical.
4. **Cost / vendor / PLM connections** for projects where the
   procurement cycle is part of the active engineering work.

None of these are V1 work and they are listed only so the V1
design intentionally leaves room for them later.

## Open questions for the V1 implementation sprint

1. **Where do the export schemas live?** Probably in
   `docs/architecture/kb-cad-export-schema.md` and
   `docs/architecture/kb-fem-export-schema.md`, drafted during
   the implementation sprint.
2. **Who runs the exporter?** A scheduled job on the KB-CAD /
   KB-FEM hosts, triggered by the human after a meaningful
   change, or both?
3. **Is the export incremental or full?** Full is simpler but
   more expensive. Incremental needs delta semantics. V1 starts
   with full and revisits when full becomes too slow.
4. **How is the exporter authenticated to AtoCore?** Probably
   the existing PAT model (one PAT per exporter, scoped to
   `write:engineering-import` once that scope exists). Worth a
   quick auth design pass before the endpoints exist.

## TL;DR

- AtoCore is a one-way mirror in V1: external tools push,
  AtoCore reads, AtoCore never writes back
- Two import endpoints for V1: KB-CAD and KB-FEM, each with a
  documented JSON export shape
- Drift surfaces as conflicts in the existing conflict model
- No NX, no FEM solvers, no PLM, no vendor portals, no
  cost/BOM systems in V1
- Bidirectional sync is reserved for V2+ on a per-tool basis,
  only after V1 demonstrates value