Files

Anto01 cbf9e03ab9 feat(engineering): V1-0 write-time invariants (F-1 + F-5 hook + F-8)

Phase V1-0 of the Engineering V1 Completion Plan. Establishes the
write-time invariants every later phase depends on so no later phase
can leak invalid state into the entity store.

F-1 shared-header fields per engineering-v1-acceptance.md:45:
  - entities.extractor_version (default "", EXTRACTOR_VERSION="v1.0.0"
    written by service.create_entity)
  - entities.canonical_home (default "entity")
  - entities.hand_authored (default 0, INTEGER boolean)
  Idempotent ALTERs in both _apply_migrations (database.py) and
  init_engineering_schema (service.py). CREATE TABLE also carries the
  columns for fresh DBs. _row_to_entity tolerates old rows without
  them so tests that predate V1-0 keep passing.

F-8 provenance enforcement per promotion-rules.md:243:
  create_entity raises ValueError when source_refs is empty and
  hand_authored is False. New kwargs hand_authored and
  extractor_version threaded through the API (EntityCreateRequest)
  and the /wiki/new form body (human wiki writes set hand_authored
  true by definition). The non-negotiable invariant: every row either
  carries provenance or is explicitly flagged as hand-authored.

F-5 synchronous conflict-detection hook on active create per
engineering-v1-acceptance.md:99:
  create_entity(status="active") now runs detect_conflicts_for_entity
  with fail-open per conflict-model.md:256. Detector errors log a
  warning but never 4xx-block the write (Q-3 "flag, never block").

Doc note added to engineering-ontology-v1.md recording that `project`
IS the `project_id` per "fields equivalent to" wording. No storage
rename.

Backfill script scripts/v1_0_backfill_provenance.py reports and
optionally flags existing active entities that lack provenance.
Idempotent. Supports --dry-run and --invalidate-instead.

Tests: 10 new in test_v1_0_write_invariants.py covering F-1 fields,
F-8 raise + bypass, F-5 hook on active + no-hook on candidate, Q-3
fail-open, Q-4 partial scope_only=active excludes candidates.

Three pre-existing conflict tests adapted to read list_open_conflicts
rather than re-run the detector (which now dedups because the hook
already fired at create-time). One API test adds hand_authored=true
since its fixture has no source_refs.

conftest.py wraps create_entity so tests that don't pass source_refs
or hand_authored default to hand_authored=True (tests author their
own fixture data — reasonable default). Production paths (API route,
wiki form, graduation scripts) all pass explicit values and are
unaffected.

Test count: 533 -> 543 (+10). Full suite green in 77.86s.

Pending: Codex review on the branch before squash-merge to main.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 14:39:30 -04:00

5.8 KiB

Raw Blame History

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)
extractor_version (V1-0)
canonical_home (V1-0)

Naming note (V1-0, 2026-04-22). The AtoCore entities table and Entity dataclass name the project-identifier field project, not project_id. This doc's "fields equivalent to" wording allows that naming flexibility — the project field on entity rows IS the project_id per spec. No storage rename is planned; downstream readers should treat entity.project as the project identifier. This was resolved in Codex's third-round audit of the V1 Completion Plan (see docs/plans/engineering-v1-completion-plan.md).

Suggested Status Lifecycle

For objects and claims:

candidate
active
superseded
invalid
needs_review

Trust Rules

An object may exist before it becomes trusted.
A generated markdown summary is not canonical truth by default.
If evidence conflicts, prefer:
1. trusted current project state
2. validated structured records
3. reviewed derived synthesis
4. raw evidence
5. historical notes
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

minimal typed object registry
minimal typed relationship registry
evidence-linking support
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.

5.8 KiB Raw Blame History