diff --git a/docs/architecture/engineering-query-catalog.md b/docs/architecture/engineering-query-catalog.md new file mode 100644 index 0000000..9c201c8 --- /dev/null +++ b/docs/architecture/engineering-query-catalog.md @@ -0,0 +1,380 @@ +# 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.