# 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 ``?" - **invocation**: `GET /entities/Subsystem/?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 `` belong to?" - **invocation**: `GET /entities/Component/?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 `` interface with, and on which interfaces?" - **invocation**: `GET /entities/Subsystem//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 ``." - **invocation**: `GET /projects//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 `` satisfy today?" - **invocation**: `GET /entities/Component/?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 `` — requirements with no `SATISFIES` edge from any Component." - **invocation**: `GET /projects//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 ``?" - **invocation**: `GET /entities/Component/?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 ``." - **invocation**: `GET /entities//?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 `` based on an Assumption that has been marked invalid or needs_review?" - **invocation**: `GET /projects//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 ``." - **invocation**: `GET /entities/ValidationClaim/?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 `` have no `SUPPORTS` edge from any Result?" - **invocation**: `GET /projects//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//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 `` whose `updated_at` is within the last ``." - **invocation**: `GET /projects//changes?since=` - **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 `` in chronological order, including superseded ones." - **invocation**: `GET /entities/Subsystem//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 `` as of timestamp ``." - **invocation**: `GET /entities//?as_of=` - **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 `` changes, which Interfaces and which peer subsystems are impacted?" - **invocation**: `GET /entities/Component//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 `.`." - **invocation**: `GET /entities///evidence?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 `` plus the chain of superseded versions." - **invocation**: `GET /entities//?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 ``." - **invocation**: `GET /entities/Material//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 `` from current trusted state." - **invocation**: `GET /projects//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=` (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.