# Engineering Ontology V1

## Purpose

Define the first practical engineering ontology that can sit on top of AtoCore and represent a real engineering project as structured knowledge.

This ontology is intended to be:
- useful to machines
- inspectable by humans through derived views
- aligned with AtoCore trust / provenance rules
- expandable across mechanical, FEM, electrical, software, manufacturing, and operations

## Goal

Represent a project as a **system of objects and relationships**, not as a pile of notes.

The ontology should support queries such as:
- what is this subsystem?
- what requirements does this component satisfy?
- what result validates this claim?
- what changed recently?
- what interfaces are affected by a design change?
- what is active vs superseded?

## Object Families

### Project structure
- Project
- System
- Subsystem
- Assembly
- Component
- Interface

### Intent / design logic
- Requirement
- Constraint
- Assumption
- Decision
- Rationale
- Risk
- Issue
- Open Question
- Change Request

### Physical / technical definition
- Material
- Parameter
- Equation
- Configuration
- Geometry Artifact
- CAD Artifact
- Tolerance
- Operating Mode

### Analysis / validation
- Analysis Model
- Load Case
- Boundary Condition
- Solver Setup
- Result
- Validation Claim
- Test
- Correlation Record

### Manufacturing / delivery
- Manufacturing Process
- Vendor
- BOM Item
- Part Number
- Assembly Procedure
- Inspection Step
- Cost Driver

### Software / controls / electrical
- Software Module
- Control Function
- State Machine
- Signal
- Sensor
- Actuator
- Electrical Interface
- Firmware Artifact

### Evidence / provenance
- Source Document
- Transcript Segment
- Image / Screenshot
- Session
- Report
- External Reference
- Generated Summary

## Minimum Viable V1 Scope

Initial implementation should start with:
- Project
- Subsystem
- Component
- Requirement
- Constraint
- Decision
- Material
- Parameter
- Analysis Model
- Result
- Validation Claim
- Artifact

This is enough to represent meaningful project state without trying to model everything immediately.

## Core Relationship Types

### Structural
- `CONTAINS`
- `PART_OF`
- `INTERFACES_WITH`

### Intent / logic
- `SATISFIES`
- `CONSTRAINED_BY`
- `BASED_ON_ASSUMPTION`
- `AFFECTED_BY_DECISION`
- `SUPERSEDES`

### Validation
- `ANALYZED_BY`
- `VALIDATED_BY`
- `SUPPORTS`
- `CONFLICTS_WITH`
- `DEPENDS_ON`

### Artifact / provenance
- `DESCRIBED_BY`
- `UPDATED_BY_SESSION`
- `EVIDENCED_BY`
- `SUMMARIZED_IN`

## Example Statements

- `Subsystem:Lateral Support CONTAINS Component:Pivot Pin`
- `Component:Pivot Pin CONSTRAINED_BY Requirement:low lateral friction`
- `Decision:Use GF-PTFE pad AFFECTS Subsystem:Lateral Support`
- `AnalysisModel:M1 static model ANALYZES Subsystem:Reference Frame`
- `Result:deflection case 03 SUPPORTS ValidationClaim:vertical stiffness acceptable`
- `Artifact:NX assembly DESCRIBES Component:Reference Frame`
- `Session:gen-004 UPDATED_BY_SESSION Component:Vertical Support`

## Shared Required Fields

Every major object should support fields equivalent to:
- `id`
- `type`
- `name`
- `project_id`
- `status`
- `confidence`
- `source_refs`
- `created_at`
- `updated_at`
- `notes` (optional)

## Suggested Status Lifecycle

For objects and claims:
- `candidate`
- `active`
- `superseded`
- `invalid`
- `needs_review`

## Trust Rules

1. An object may exist before it becomes trusted.
2. A generated markdown summary is not canonical truth by default.
3. If evidence conflicts, prefer:
   1. trusted current project state
   2. validated structured records
   3. reviewed derived synthesis
   4. raw evidence
   5. historical notes
4. Conflicts should be surfaced, not silently blended.

## Mapping to the Existing Knowledge Base System

### KB-CAD can map to
- System
- Subsystem
- Component
- Material
- Decision
- Constraint
- Artifact

### KB-FEM can map to
- Analysis Model
- Load Case
- Boundary Condition
- Result
- Validation Claim
- Correlation Record

### Session generations can map to
- Session
- Generated Summary
- object update history
- provenance events

## Human Mirror Possibilities

Once the ontology exists, AtoCore can generate pages such as:
- project overview
- subsystem page
- component page
- decision log
- validation summary
- requirement trace page

These should remain **derived representations** of structured state.

## Recommended V1 Deliverables

1. minimal typed object registry
2. minimal typed relationship registry
3. evidence-linking support
4. practical query support for:
   - component summary
   - subsystem current state
   - requirement coverage
   - result-to-claim mapping
   - decision history

## What Not To Do In V1

- do not model every engineering concept immediately
- do not build a giant graph with no practical queries
- do not collapse structured objects back into only markdown
- do not let generated prose outrank structured truth
- do not auto-promote trusted state too aggressively

## Summary

Ontology V1 should be:
- small enough to implement
- rich enough to be useful
- aligned with AtoCore trust philosophy
- capable of absorbing the existing engineering Knowledge Base work

The first goal is not to model everything.
The first goal is to represent enough of a real project that AtoCore can reason over structure, not just notes.