ATOCore/docs/architecture/engineering-query-catalog.md

# Engineering Query Catalog (V1 driving target)

## Purpose

This document is the **single most important driver** of the engineering
layer V1 design. The ontology, the schema, the relationship types, and
the human mirror templates should all be designed *to answer the queries
in this catalog*. Anything in the ontology that does not serve at least
one of these queries is overdesign for V1.

The rule is:

> If we cannot describe what question a typed object or relationship
> lets us answer, that object or relationship is not in V1.

The catalog is also the **acceptance test** for the engineering layer.
"V1 is done" means: AtoCore can answer at least the V1-required queries
in this list against the active project set (`p04-gigabit`,
`p05-interferometer`, `p06-polisher`).

## Structure of each entry

Each query is documented as:

- **id**: stable identifier (`Q-001`, `Q-002`, ...)
- **question**: the natural-language question a human or LLM would ask
- **example invocation**: how a client would call AtoCore to ask it
- **expected result shape**: the structure of the answer (not real data)
- **objects required**: which engineering objects must exist
- **relationships required**: which relationships must exist
- **provenance requirement**: what evidence must be linkable
- **tier**: `v1-required` | `v1-stretch` | `v2`

## Tiering

- **v1-required** queries are the floor. The engineering layer cannot
  ship without all of them working.
- **v1-stretch** queries should be doable with V1 objects but may need
  additional adapters.
- **v2** queries are aspirational; they belong to a later wave of
  ontology work and are listed here only to make sure V1 does not
  paint us into a corner.

## V1 minimum object set (recap)

For reference, the V1 ontology includes:

- Project, Subsystem, Component
- Requirement, Constraint, Decision
- Material, Parameter
- AnalysisModel, Result, ValidationClaim
- Artifact

And the four relationship families:

- Structural: `CONTAINS`, `PART_OF`, `INTERFACES_WITH`
- Intent: `SATISFIES`, `CONSTRAINED_BY`, `BASED_ON_ASSUMPTION`,
  `AFFECTED_BY_DECISION`, `SUPERSEDES`
- Validation: `ANALYZED_BY`, `VALIDATED_BY`, `SUPPORTS`,
  `CONFLICTS_WITH`, `DEPENDS_ON`
- Provenance: `DESCRIBED_BY`, `UPDATED_BY_SESSION`, `EVIDENCED_BY`,
  `SUMMARIZED_IN`

Every query below is annotated with which of these it depends on, so
that the V1 implementation order is unambiguous.

---

## Tier 1: Structure queries

### Q-001 — What does this subsystem contain?
- **question**: "What components and child subsystems make up
  Subsystem `<name>`?"
- **invocation**: `GET /entities/Subsystem/<id>?expand=contains`
- **expected**: `{ subsystem, contains: [{ id, type, name, status }] }`
- **objects**: Subsystem, Component
- **relationships**: `CONTAINS`
- **provenance**: each child must link back to at least one Artifact or
  source chunk via `DESCRIBED_BY` / `EVIDENCED_BY`
- **tier**: v1-required

### Q-002 — What is this component a part of?
- **question**: "Which subsystem(s) does Component `<name>` belong to?"
- **invocation**: `GET /entities/Component/<id>?expand=parents`
- **expected**: `{ component, part_of: [{ id, type, name, status }] }`
- **objects**: Component, Subsystem
- **relationships**: `PART_OF` (inverse of `CONTAINS`)
- **provenance**: same as Q-001
- **tier**: v1-required

### Q-003 — What interfaces does this subsystem have, and to what?
- **question**: "What does Subsystem `<name>` interface with, and on
  which interfaces?"
- **invocation**: `GET /entities/Subsystem/<id>/interfaces`
- **expected**: `[{ interface_id, peer: { id, type, name }, role }]`
- **objects**: Subsystem (Interface object deferred to v2)
- **relationships**: `INTERFACES_WITH`
- **tier**: v1-required (with simplified Interface = string label;
  full Interface object becomes v2)

### Q-004 — What is the system map for this project right now?
- **question**: "Give me the current structural tree of Project `<id>`."
- **invocation**: `GET /projects/<id>/system-map`
- **expected**: nested tree of `{ id, type, name, status, children: [] }`
- **objects**: Project, Subsystem, Component
- **relationships**: `CONTAINS`, `PART_OF`
- **tier**: v1-required

---

## Tier 2: Intent queries

### Q-005 — Which requirements does this component satisfy?
- **question**: "Which Requirements does Component `<name>` satisfy
  today?"
- **invocation**: `GET /entities/Component/<id>?expand=satisfies`
- **expected**: `[{ requirement_id, name, status, confidence }]`
- **objects**: Component, Requirement
- **relationships**: `SATISFIES`
- **provenance**: each `SATISFIES` edge must link to a Result or
  ValidationClaim that supports the satisfaction (or be flagged as
  `unverified`)
- **tier**: v1-required

### Q-006 — Which requirements are not satisfied by anything?
- **question**: "Show me orphan Requirements in Project `<id>` —
  requirements with no `SATISFIES` edge from any Component."
- **invocation**: `GET /projects/<id>/requirements?coverage=orphan`
- **expected**: `[{ requirement_id, name, status, last_updated }]`
- **objects**: Project, Requirement, Component
- **relationships**: absence of `SATISFIES`
- **tier**: v1-required (this is the killer correctness query — it's
  the engineering equivalent of "untested code")

### Q-007 — What constrains this component?
- **question**: "What Constraints apply to Component `<name>`?"
- **invocation**: `GET /entities/Component/<id>?expand=constraints`
- **expected**: `[{ constraint_id, name, value, source_decision_id? }]`
- **objects**: Component, Constraint
- **relationships**: `CONSTRAINED_BY`
- **tier**: v1-required

### Q-008 — Which decisions affect this subsystem or component?
- **question**: "Show me every Decision that affects `<entity>`."
- **invocation**: `GET /entities/<type>/<id>?expand=decisions`
- **expected**: `[{ decision_id, name, status, made_at, supersedes? }]`
- **objects**: Decision, plus the affected entity
- **relationships**: `AFFECTED_BY_DECISION`, `SUPERSEDES`
- **tier**: v1-required

### Q-009 — Which decisions are based on assumptions that are now flagged?
- **question**: "Are any active Decisions in Project `<id>` based on an
  Assumption that has been marked invalid or needs_review?"
- **invocation**: `GET /projects/<id>/decisions?assumption_status=needs_review,invalid`
- **expected**: `[{ decision_id, assumption_id, assumption_status }]`
- **objects**: Decision, Assumption
- **relationships**: `BASED_ON_ASSUMPTION`
- **tier**: v1-required (this is the second killer correctness query —
  catches fragile design)

---

## Tier 3: Validation queries

### Q-010 — What result validates this claim?
- **question**: "Show me the Result(s) supporting ValidationClaim
  `<name>`."
- **invocation**: `GET /entities/ValidationClaim/<id>?expand=supports`
- **expected**: `[{ result_id, analysis_model_id, summary, confidence }]`
- **objects**: ValidationClaim, Result, AnalysisModel
- **relationships**: `SUPPORTS`, `ANALYZED_BY`
- **provenance**: every Result must link to its AnalysisModel and an
  Artifact via `DESCRIBED_BY`
- **tier**: v1-required

### Q-011 — Are there any active validation claims with no supporting result?
- **question**: "Which active ValidationClaims in Project `<id>` have
  no `SUPPORTS` edge from any Result?"
- **invocation**: `GET /projects/<id>/validation?coverage=unsupported`
- **expected**: `[{ claim_id, name, status, last_updated }]`
- **objects**: ValidationClaim, Result
- **relationships**: absence of `SUPPORTS`
- **tier**: v1-required (third killer correctness query — catches
  claims that are not yet evidenced)

### Q-012 — Are there conflicting results for the same claim?
- **question**: "Show me ValidationClaims where multiple Results
  disagree (one `SUPPORTS`, another `CONFLICTS_WITH`)."
- **invocation**: `GET /projects/<id>/validation?coverage=conflict`
- **expected**: `[{ claim_id, supporting_results, conflicting_results }]`
- **objects**: ValidationClaim, Result
- **relationships**: `SUPPORTS`, `CONFLICTS_WITH`
- **tier**: v1-required

---

## Tier 4: Change / time queries

### Q-013 — What changed in this project recently?
- **question**: "List entities in Project `<id>` whose `updated_at`
  is within the last `<window>`."
- **invocation**: `GET /projects/<id>/changes?since=<iso>`
- **expected**: `[{ id, type, name, status, updated_at, change_kind }]`
- **objects**: any
- **relationships**: any
- **tier**: v1-required

### Q-014 — What is the decision history for this subsystem?
- **question**: "Show me all Decisions affecting Subsystem `<id>` in
  chronological order, including superseded ones."
- **invocation**: `GET /entities/Subsystem/<id>/decision-log`
- **expected**: ordered list with supersession chain
- **objects**: Decision, Subsystem
- **relationships**: `AFFECTED_BY_DECISION`, `SUPERSEDES`
- **tier**: v1-required (this is what a human-readable decision log
  is generated from)

### Q-015 — What was the trusted state of this entity at time T?
- **question**: "Reconstruct the active fields of `<entity>` as of
  timestamp `<T>`."
- **invocation**: `GET /entities/<type>/<id>?as_of=<iso>`
- **expected**: the entity record as it would have been seen at T
- **objects**: any
- **relationships**: status lifecycle
- **tier**: v1-stretch (requires status history table — defer if
  baseline implementation runs long)

---

## Tier 5: Cross-cutting queries

### Q-016 — Which interfaces are affected by changing this component?
- **question**: "If Component `<name>` changes, which Interfaces and
  which peer subsystems are impacted?"
- **invocation**: `GET /entities/Component/<id>/impact`
- **expected**: `[{ interface_id, peer_id, peer_type, peer_name }]`
- **objects**: Component, Subsystem
- **relationships**: `PART_OF`, `INTERFACES_WITH`
- **tier**: v1-required (this is the change-impact-analysis query the
  whole engineering layer exists for)

### Q-017 — What evidence supports this fact?
- **question**: "Give me the source documents and chunks that support
  the current value of `<entity>.<field>`."
- **invocation**: `GET /entities/<type>/<id>/evidence?field=<field>`
- **expected**: `[{ source_file, chunk_id, heading_path, score }]`
- **objects**: any
- **relationships**: `EVIDENCED_BY`, `DESCRIBED_BY`
- **tier**: v1-required (without this the engineering layer cannot
  pass the AtoCore "trust + provenance" rule)

### Q-018 — What is active vs superseded for this concept?
- **question**: "Show me the current active record for `<key>` plus
  the chain of superseded versions."
- **invocation**: `GET /entities/<type>/<id>?include=superseded`
- **expected**: `{ active, superseded_chain: [...] }`
- **objects**: any
- **relationships**: `SUPERSEDES`
- **tier**: v1-required

### Q-019 — Which components depend on this material?
- **question**: "List every Component whose Material is `<material>`."
- **invocation**: `GET /entities/Material/<id>/components`
- **expected**: `[{ component_id, name, subsystem_id }]`
- **objects**: Component, Material
- **relationships**: derived from Component.material field, no edge
  needed
- **tier**: v1-required

### Q-020 — What does this project look like as a project overview?
- **question**: "Generate the human-readable Project Overview for
  Project `<id>` from current trusted state."
- **invocation**: `GET /projects/<id>/mirror/overview`
- **expected**: formatted markdown derived from active entities
- **objects**: Project, Subsystem, Component, Decision, Requirement,
  ValidationClaim
- **relationships**: structural + intent
- **tier**: v1-required (this is the Layer 3 Human Mirror entry
  point — the moment the engineering layer becomes useful to humans
  who do not want to call APIs)

---

## v1-stretch (nice to have)

### Q-021 — Which parameters drive this analysis result?
- **objects**: AnalysisModel, Parameter, Result
- **relationships**: `ANALYZED_BY`, plus a new `DRIVEN_BY` edge

### Q-022 — Which decisions cite which prior decisions?
- **objects**: Decision
- **relationships**: `BASED_ON_DECISION` (new)

### Q-023 — Cross-project comparison
- **question**: "Are any Materials shared between p04, p05, and p06,
  and are their Constraints consistent?"
- **objects**: Project, Material, Constraint

---

## v2 (deferred)

### Q-024 — Cost rollup
- requires BOM Item, Cost Driver, Vendor — out of V1 scope

### Q-025 — Manufacturing readiness
- requires Manufacturing Process, Inspection Step, Assembly Procedure
  — out of V1 scope

### Q-026 — Software / control state
- requires Software Module, State Machine, Sensor, Actuator — out
  of V1 scope

### Q-027 — Test correlation across analyses
- requires Test, Correlation Record — out of V1 scope

---

## What this catalog implies for V1 implementation order

The 20 v1-required queries above tell us what to build first, in
roughly this order:

1. **Structural** (Q-001 to Q-004): need Project, Subsystem, Component
   and `CONTAINS` / `PART_OF` / `INTERFACES_WITH` (with Interface as a
   simple string label, not its own entity).
2. **Intent core** (Q-005 to Q-008): need Requirement, Constraint,
   Decision and `SATISFIES` / `CONSTRAINED_BY` / `AFFECTED_BY_DECISION`.
3. **Killer correctness queries** (Q-006, Q-009, Q-011): need the
   absence-of-edge query patterns and the Assumption object.
4. **Validation** (Q-010 to Q-012): need AnalysisModel, Result,
   ValidationClaim and `SUPPORTS` / `ANALYZED_BY` / `CONFLICTS_WITH`.
5. **Change/time** (Q-013, Q-014): need a write log per entity (the
   existing `updated_at` plus a status history if Q-015 is in scope).
6. **Cross-cutting** (Q-016 to Q-019): impact analysis is mostly a
   graph traversal once the structural and intent edges exist.
7. **Provenance** (Q-017): the entity store must always link to
   chunks/artifacts via `EVIDENCED_BY` / `DESCRIBED_BY`. This is
   non-negotiable and should be enforced at insert time, not later.
8. **Human Mirror** (Q-020): the markdown generator is the *last*
   thing built, not the first. It is derived from everything above.

## What is intentionally left out of V1

- BOM, manufacturing, vendor, cost objects (entire family deferred)
- Software, control, electrical objects (entire family deferred)
- Test correlation objects (entire family deferred)
- Full Interface as its own entity (string label is enough for V1)
- Time-travel queries beyond `since=<iso>` (Q-015 is stretch)
- Multi-project rollups (Q-023 is stretch)

## Open questions this catalog raises

These are the design questions that need to be answered in the next
planning docs (memory-vs-entities, conflict-model, promotion-rules):

- **Q-006, Q-011 (orphan / unsupported queries)**: do orphans get
  flagged at insert time, computed at query time, or both?
- **Q-009 (assumption-driven decisions)**: when an Assumption flips
  to `needs_review`, are all dependent Decisions auto-flagged or do
  they only show up when this query is run?
- **Q-012 (conflicting results)**: does AtoCore *block* a conflict
  from being saved, or always save and flag? (The trust rule says
  flag, never block — but the implementation needs the explicit nod.)
- **Q-017 (evidence)**: is `EVIDENCED_BY` mandatory at insert? If yes,
  how do we backfill entities extracted from older interactions where
  the source link is fuzzy?
- **Q-020 (Project Overview mirror)**: when does it regenerate?
  On every entity write? On a schedule? On demand?

These are the questions the next architecture docs in the planning
sprint should resolve before any code is written.

## Working rule

> If a v1-required query in this catalog cannot be answered against
> at least one of `p04-gigabit`, `p05-interferometer`, or
> `p06-polisher`, the engineering layer is not done.

This catalog is the contract.