# .aieng Package Contract

The `.aieng` package is a ZIP archive that serves as the stable artifact
contract between all components of the platform. CAD tools, AI agents, the
web UI, and validation tooling all operate on the same package. CAD tools are
replaceable; the package format persists.

---

## Format Overview

A `.aieng` file is a standard ZIP archive with a well-defined internal
directory layout. Members are UTF-8 encoded JSON, YAML, or Markdown files
except where noted.

---

## Current Package Layout

Members marked **required** must be present for a package to be considered
minimally valid. Members marked **optional** are written when the relevant
pipeline stage has run.

```
<package>.aieng (ZIP)
│
├── manifest.json               REQUIRED  — model identity, version, source metadata
│
├── geometry/
│   ├── source.step             optional  — original uploaded STEP
│   ├── normalized.step         optional  — normalised STEP (topology-stable IDs)
│   └── topology_map.json       optional  — B-rep entities: bodies, faces, edges, vertices
│
├── graph/
│   ├── feature_graph.json      optional  — parametric feature graph
│   ├── aag.json                optional  — attributed adjacency graph
│   └── constraints.json        optional  — typed constraint list (simulation_target, protect_region, ...)
│
├── objects/
│   └── interface_graph.json    optional  — assembly interface edges
│
├── task/
│   ├── task_spec.json          optional  — task specification (or .yaml)
│   ├── task_spec.yaml          optional
│   └── design_targets.yaml     optional  — explicit engineering design targets / requirements (not solver results)
│
├── simulation/
│   ├── cae_imports/
│   │   ├── parsed_materials.json         optional  — materials imported from CAE tool
│   │   ├── parsed_boundary_conditions.json  optional
│   │   └── parsed_loads.json             optional
│   ├── cae_mapping.json        optional  — geometry ↔ simulation entity mapping
│   ├── preprocessing_summary.json     optional  — honest CAE setup readiness summary (artifact presence only)
│   ├── preprocessing_summary.md       optional  — human/LLM-readable markdown derived from preprocessing_summary.json
│   ├── simulation_run_summary.json    optional  — honest simulation run metadata summary (recorded runs only)
│   ├── simulation_run_summary.md      optional  — human/LLM-readable markdown derived from simulation_run_summary.json
│   ├── mesh/                          optional  — generated FEM mesh (PR 3B)
│   │   ├── mesh_<size>mm.inp          optional  — CalculiX `.inp` mesh generated by FreeCAD/Gmsh
│   │   └── mesh_metadata.json         optional  — mesh generation provenance: `mesh_size_mm`, `element_type`, `source_geometry`, `generated_at`
│   ├── runs/
│   │   └── <run_id>/
│   │       ├── solver_run.json        optional  — solver run metadata (schema 0.1)
│   │       ├── run_manifest.json      optional  — run manifest
│   │       ├── solver_log.txt         optional  — solver log reference
│   │       └── solver_input.inp       optional  — solver input deck
│
├── results/
│   ├── evidence_index.json     optional  — indexed evidence items (solver_result, mesh_evidence, ...)
│   ├── result_summary.json     optional  — honest CAE/post-processing summary (artifact presence only; no solver execution). May include `design_target_comparisons` when evidence is available.
│   ├── postprocessing_summary.md  optional  — human/LLM-readable markdown derived from result_summary.json
│   ├── computed_metrics.json   optional  — externally computed post-processing metrics (imported, not generated here)
│   └── solver/
│       └── result.json         optional  — solver result evidence (external; not generated here)
│
├── validation/
│   ├── status.yaml             optional  — overall validation status, solver_mesh_status
│   ├── completeness_report.json  optional
│   └── evidence_report.json    optional
│
├── provenance/
│   └── tool_trace.json         optional  — ordered record of every tool that touched the package
│
├── ai/
│   ├── summary.md              optional  — human/AI-readable model summary (Markdown)
│   └── claim_map.json          optional  — engineering claims, each backed by evidence references
│
└── README_FOR_AI.md            optional  — high-level orientation for AI context windows
```

---

## Three Package States

### State 1 — CAD-only

Minimum viable package. STEP imported, topology extracted, feature graph
populated, AI summary written.

CAE fields in `cae` summary:
- `present: false`
- `results_available: false`
- `available_fields: []`

UI behaviour: Three.js viewer active; CAE panel hidden.

Required members: `manifest.json`, at least one of `geometry/topology_map.json`
or `graph/feature_graph.json`.

### State 2 — CAE setup (no solver results)

CAE context is present: constraints, boundary conditions, loads, materials,
and/or a simulation mapping have been imported. No solver has run; no result
evidence exists.

CAE fields in `cae` summary:
- `present: true`
- `results_available: false`
- `available_fields: []` or populated from `constraints.json` metric keywords

UI behaviour: CAE panel visible ("only CAE context detected");
field selector shown if `available_fields` non-empty;
Three.js viewer renders CAD geometry without field overlay.

Members expected: `simulation/cae_imports/`, `graph/constraints.json`,
optionally `simulation/cae_mapping.json`.

### State 3 — Solver results present

Evidence of actual solver execution exists in `results/evidence_index.json`
with `evidence_type: "solver_result"` entries.

CAE fields in `cae` summary:
- `present: true`
- `results_available: true`
- `available_fields: ["stress", "displacement"]` (from constraint metrics
  and/or `validation/status.yaml → solver_mesh_status`)

UI behaviour: CAE panel shows "results available" badge; field selector active.

> **Important:** The current `GET /api/projects/{id}/fields/{field_name}`
> endpoint returns a *synthetic descriptor* (`format: "vertex_synthetic"`,
> `basis: "y_normalized"`) when real FRD field data is absent or misaligned.
> The Three.js viewer shows an explicit label: **"合成预览，不可用于工程判断"**.
> When real FRD data is present and bbox-aligned, the label reads **"FRD真实数据"**;
> when present but suspiciously aligned, it reads **"FRD数据存在，但几何坐标可能不一致"**.
> Real solver field data (VTK, HDF5, per-node JSON) is not yet served directly.

---

### State 3b — Imported computed metrics present

Externally computed post-processing metrics have been imported into
`results/computed_metrics.json`. These metrics are produced by external
post-processors, solver adapters, or CAD/CAE software exporters. `aieng` does
not compute them and does not parse VTU/FRD/ODB numerical fields directly.

`results/computed_metrics.json` schema (version `"0.1"`):
- `metrics_source.tool` — name of the external tool that produced the metrics.
- `metrics_source.software` — software name/version.
- `load_cases[].id` — load case identifier.
- `load_cases[].metrics` — metric objects such as `max_von_mises_stress`,
  `max_displacement`, `minimum_safety_factor`, each with `value`, `unit`,
  optional `location`, and optional `field`.

When `computed_metrics.json` is present, `result_summary.json` sets
`computed_values.extrema_computed: true` and populates top-level metric fields
from the imported data. The summary clearly labels these as imported/external.

---

## Evidence vs Claim

These two concepts are strictly separated throughout the package format.

**Evidence** (`results/evidence_index.json`):
- Records what happened and what was measured.
- Written automatically by tools after execution.
- `verification_status` can be `available`, `not_run`, `pending`, etc.
- Evidence is never a claim.

**Claims** (`ai/claim_map.json`):
- Engineering assertions derived from evidence.
- Only `aieng_update_claim` (in `aieng_freecad_mcp`) may advance a claim.
- Claim advancement requires explicit invocation and evidence backing.
- Surrogate/mock results do not advance claims.

---

## Versioning

The package format uses a `format_version` field in structured JSON members
(e.g. `graph/constraints.json`, `results/evidence_index.json`). Current
version: `"0.1.0"`.

Schema definitions live in `aieng/schemas/`.

---

## What the Platform Does With the Package

| Component | Operation |
|-----------|-----------|
| `aieng` CLI | Creates and enriches package (ZIP I/O, member generation) |
| `aieng_freecad_mcp` | Reads package for context; writes evidence and tool trace |
| `aieng-ui` backend | Reads package for project summary; passes path to provider adapter |
| `aieng-ui` runtime | Writes post-processing artifacts back into the package (e.g. `results/computed_metrics.json`) so the package remains the evidence source of truth |
| `aieng-ui` frontend | Displays summary fields; renders viewer asset |
| `aieng` preprocessing summary | Reads setup artifacts; writes `simulation/preprocessing_summary.json` and `.md` |
| AI agents | Read package members via `aieng serve` MCP tools or `aieng-ui` REST API |

---

## Design Targets (`task/design_targets.yaml`)

`task/design_targets.yaml` is a **first-class package resource** that encodes engineering requirements and design intent separately from solver results.

### Supported target types

| Target type | Meaning | Comparator examples |
|---|---|---|
| `mass_reduction_target` | Reduce mass by a threshold percentage | `reduce_by_at_least` |
| `absolute_mass_target` | Total mass must meet a bound | `<=`, `>=`, `==` |
| `minimum_safety_factor` | Safety factor floor | `>=` |
| `maximum_von_mises_stress` | Stress ceiling | `<=` |
| `maximum_displacement` | Displacement ceiling | `<=` |
| `preserved_interface` | Feature or interface must not be removed | `preserve` |
| `objective_priority` | Policy ordering when targets conflict | `priority` |

### Supported comparators

`<=`, `<`, `>=`, `>`, `==`, `within_range`, `preserve`, `reduce_by_at_least`, `priority`

### Boundary rules

- Design targets are **requirements**, not solver results. They live in `task/`, not `results/`.
- `result_summary.json` may contain a `design_target_comparisons` block that maps each target against actual evidence. Comparison statuses are `pass`, `fail`, `unknown`, or `not_evaluated`.
- `unknown` means the required evidence artifact is missing. `not_evaluated` means no comparison logic has been run.
- Comparison results **do not constitute engineering certification**. A `pass` only means the available evidence meets the stated threshold.
- Comparisons **must not automatically advance `claim_map.json`**. Claim advancement requires explicit invocation.
- `format_version` is `"0.1.0"` (legacy flat format with `id`/`metric`/`operator`/`value`) or `"0.1.1"` (modern format with `target_id`/`target_type`/`comparator`/`threshold`/`description`/`priority`). Both are accepted by the validator.

---

## What the Platform Does Not Do

- Does not store solver executables inside the package.
- Mesh files (`simulation/mesh/*.inp`) are stored when `cae.generate_mesh` runs with real FreeCAD/Gmsh. When FreeCAD is unavailable, no fake mesh artifact is written.
- Does not auto-advance claims from solver output — explicit update required.
- Does not guarantee face-ID stability across topology-changing edits.
- Does not automatically remap boundary conditions after geometry changes
  (marks as `needs_review` instead).
