# Hardware program: an Omnigraph use case

Requirements, budgets, interfaces and verification for a hardware program, with "verified" and "over budget" worked out from the evidence on every read.

| | |
|---|---|
| Category | Hardware |
| Graph ID | program |
| Sample data | Petrel, a fictional 150 kg Earth-observation satellite: 153 nodes, 296 edges |
| Schema | 15 node types, 28 edge types |
| Stored queries | 39 reads, 21 writes |
| Source | https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/hardware-program |

## Node types

### Engineer

A person or an AI agent who owns work, records results and raises findings.

- `slug: String` (key)
- `name: String`
- `team: String?`
- `kind: enum(human, agent)`

### Requirement

A need the system must meet: a mission goal, a system requirement, or a subsystem design criterion.

Instruction for agents: Write a design criterion as a checkable limit (quantity, comparator, limit_value, unit) rather than a paragraph. Every requirement except a mission goal derives from a parent, has one owner and names a verification method. Anything an agent drafts stays review_status ai_generated until a person reviews it.

- `slug: String` (key)
- `title: String`
- `statement: String`
- `tier: enum(mission, system, design_criterion)`
- `source: enum(customer, launch_provider, regulatory, internal, derived)`
- `maturity: enum(assumed, proposed, verified, frozen)`
- `method: enum(analysis, inspection, demonstration, test, simulation)`
- `rationale: String?`
- `safety_critical: Bool`
- `quantity: String?`
- `comparator: enum(max, min)?`
- `limit_value: F64?`
- `unit: String?`
- `review_status: enum(ai_generated, human_reviewed, approved)`
- `updated_at: DateTime`
- `embedding: Vector(3072)?`

### Assumption

A placeholder the design depends on until evidence confirms or replaces it.

- `slug: String` (key)
- `statement: String`
- `confidence: enum(low, medium, high)`
- `rationale: String?`
- `revisit_by: Date?`

### Standard

An external standard or document requirements must comply with, referenced by its public identifier.

- `slug: String` (key)
- `identifier: String`
- `title: String`

### Block

An architecture element: the system, a subsystem, an assembly or a component.

- `slug: String` (key)
- `name: String`
- `level: enum(system, subsystem, assembly, component)`
- `maturity: enum(tentative, stable, frozen)`
- `description: String?`

### Interface

A contract between two blocks: what flows across it and within which limits.

- `slug: String` (key)
- `name: String`
- `kind: enum(electrical, data, mechanical, thermal, rf)`
- `definition: String`
- `maturity: enum(tentative, stable, frozen)`

### Parameter

A design value of one block, such as its mass or power draw. Budgets add these up.

- `slug: String` (key)
- `name: String`
- `quantity: String`
- `value: F64`
- `unit: String`
- `basis: enum(assumed, estimated, calculated, measured)`

### Variant

A product configuration. A requirement with no AppliesTo link applies to every variant.

- `slug: String` (key)
- `name: String`
- `description: String?`

### TestCase

A verification activity. Its status is the outcome of its latest run, written in the same commit as that run.

- `slug: String` (key)
- `title: String`
- `method: enum(analysis, inspection, demonstration, test, simulation)`
- `environment: String?`
- `status: enum(not_run, pass, fail)`
- `last_run_at: DateTime?`
- `last_measured: F64?`
- `unit: String?`

### TestRun

One execution of a test case, with its evidence.

- `slug: String` (key)
- `outcome: enum(pass, fail, aborted)`
- `measured_value: F64?`
- `unit: String?`
- `run_at: DateTime`
- `notes: String?`
- `report: Blob?`

### Iteration

A bounded design-build-test loop with a learning goal and exit criteria.

- `slug: String` (key)
- `name: String`
- `learning_goal: String`
- `exit_criteria: String`
- `status: enum(planned, active, done)`

### Milestone

A design review or gate. Passing it records the graph commit it baselined.

- `slug: String` (key)
- `name: String`
- `kind: enum(srr, pdr, cdr, trr, frr, internal)`
- `date: Date`
- `status: enum(planned, passed, passed_with_actions)`
- `baseline_commit: String?`

### Risk

A failure mode, scored 1-5 for severity and likelihood.

- `slug: String` (key)
- `title: String`
- `failure_mode: String`
- `effect: String`
- `severity: I32`
- `likelihood: I32`
- `status: enum(open, mitigated, accepted, closed)`

### Decision

A trade or design decision, with its rationale and whether it can be undone cheaply.

- `slug: String` (key)
- `question: String`
- `choice: String`
- `rationale: String`
- `reversible: Bool`
- `decided_at: Date`
- `status: enum(proposed, decided, superseded)`

### Finding

The result of a check on a requirement, raised by a person or an agent and resolved by a person.

- `slug: String` (key)
- `check: String`
- `severity: enum(info, warning, error)`
- `message: String`
- `status: enum(open, accepted, dismissed)`
- `raised_at: DateTime`

## Edge types

- `Requirement -[DerivesFrom]-> Requirement` The source requirement was derived from the target. Requirements form a web, not a tree.
- `Requirement -[Supersedes]-> Requirement`
- `Requirement -[AllocatedTo]-> Block` The block that must meet the requirement; budgets add up the parameters beneath it.
- `Requirement -[Constrains]-> Interface`
- `Requirement -[Bounds]-> Parameter` The requirement sets the limit on this design value.
- `Requirement -[AppliesTo]-> Variant`
- `Requirement -[InScope]-> Iteration` The iteration must verify this requirement.
- `Requirement -[CompliesWith]-> Standard` The requirement's stance on one clause of a standard.
- `Requirement -[Mitigates]-> Risk`
- `Requirement -[RequirementAssumes]-> Assumption`
- `Requirement -[RequirementOwner]-> Engineer`
- `Block -[PartOf]-> Block`
- `Interface -[Connects]-> Block` Each interface joins exactly two blocks.
- `Parameter -[Characterizes]-> Block`
- `Parameter -[ParameterAssumes]-> Assumption`
- `Interface -[InterfaceAssumes]-> Assumption`
- `Block -[BlockOwner]-> Engineer`
- `Interface -[InterfaceOwner]-> Engineer`
- `Risk -[RiskOn]-> Block`
- `TestCase -[Verifies]-> Requirement`
- `TestCase -[Measures]-> Parameter` The design value the test actually measures; it should be one its requirements bound.
- `TestCase -[TestOwner]-> Engineer`
- `TestRun -[RunOf]-> TestCase`
- `TestRun -[RunIn]-> Iteration`
- `Milestone -[Closes]-> Iteration` The review that ends this iteration.
- `Decision -[Affects]-> Requirement`
- `Finding -[FindingOn]-> Requirement`
- `Finding -[RaisedBy]-> Engineer`

Full schema: https://github.com/ModernRelay/omnigraph-cookbooks/blob/main/hardware-program/schema.pg

## Questions it answers

### Does each budget still close?

Each budget requirement's limit beside the total of the design values beneath its block, and whether the total violates it.

```graphql
// A budget is a requirement with a quantity and a limit, allocated to a block;
// it adds up every Parameter of that quantity on blocks beneath that block.
// `violated` compares the total with the limit by the requirement's
// comparator; margin policy (how close is too close) stays the caller's.
query budget_rollup() @description("Each budget requirement's limit beside the total of the design values beneath its block, and whether the total violates it.") {
    match {
        $r: Requirement
        $r.quantity is not null
        $r allocatedTo $b
        $c partOf{1,8} $b
        $p characterizes $c
        $p.quantity = $r.quantity
    }
    return {
        $r.slug, $r.quantity, $r.comparator, $r.limit_value, $r.unit,
        sum($p.value) as allocated, count(distinct $p) as contributors,
        (max($r.comparator) = "max" and sum($p.value) > max($r.limit_value))
            or (max($r.comparator) = "min" and sum($p.value) < max($r.limit_value)) as violated
    }
    order { $r.slug asc }
    limit 200
}
```

### If this requirement changes, which test results no longer hold?

Test cases verifying the changed requirement or anything derived from it: their results may no longer hold.

```graphql
query impacted_tests($slug: String) @description("Test cases verifying the changed requirement or anything derived from it: their results may no longer hold.") {
    match {
        $r: Requirement { slug: $slug }
        $d derivesFrom{1,8} $r
        $t verifies $d
    }
    return { $t.slug, $t.title, $t.status, $d.slug as verifies }
    order { $t.slug asc }
    limit 500
}
```

### Which mission goals does this requirement serve?

Every requirement this one derives from, up to the mission goals it serves.

```graphql
query trace_up($slug: String) @description("Every requirement this one derives from, up to the mission goals it serves.") {
    match {
        $r: Requirement { slug: $slug }
        $r derivesFrom{1,8} $p
    }
    return { $p.slug, $p.tier, $p.title }
    order { $p.slug asc }
    limit 200
}
```

### Which requirements has no test verified?

Requirements below mission level that no test case verifies.

```graphql
query unverified_requirements() @description("Requirements below mission level that no test case verifies.") {
    match {
        $r: Requirement
        $r.tier != "mission"
        not { $t verifies $r }
    }
    return { $r.slug, $r.title, $r.tier, $r.method }
    order { $r.slug asc }
    limit 1000
}
```

## Stored queries

### queries/mutations.gq

- `propose_requirement` (write): Add a proposed requirement derived from a parent, allocated to a block and owned by one engineer.
- `revise_requirement` (write): Replace a requirement's wording and limit if it is unchanged since it was read. Passing tests that ran before the change become stale.
- `set_maturity` (write): Move a requirement between assumed, proposed, verified and frozen if it is unchanged since it was read.
- `review_requirement` (write): Record a person's review (human_reviewed or approved) of a requirement if it is unchanged since it was read.
- `link_derivation` (write): Record that one requirement derives from another.
- `allocate` (write): Allocate a requirement to an architecture block.
- `constrain_interface` (write)
- `bound_parameter` (write): Record that a requirement sets the limit on a design value.
- `scope_to_iteration` (write): Put a requirement in scope of an iteration; the review that closes it checks it.
- `set_compliance` (write): Record or replace a requirement's stance (comply, deviate, not_applicable) on one clause of a standard.
- `set_parameter` (write): Update a design value and how it was obtained (assumed, estimated, calculated, measured).
- `set_interface_maturity` (write): Move an interface between tentative, stable and frozen.
- `set_assumption` (write): Update how far an assumption can be trusted and when to revisit it.
- `record_test_run` (write): Record a pass or fail run of a test case in an iteration, with its report, and update the test case's status.
- `record_aborted_run` (write): Record a run that did not complete; the test case keeps its status.
- `link_verification` (write): Record that a test case verifies a requirement.
- `record_baseline` (write): Mark a planned review passed (passed or passed_with_actions) and record the graph commit it baselined.
- `raise_finding` (write): Raise a finding (info, warning, error) against a requirement.
- `resolve_finding` (write): Accept or dismiss an open finding.
- `record_decision` (write): Record a trade or design decision and the requirement it affects.
- `set_risk_status` (write): Move a risk between open, mitigated, accepted and closed.

### queries/program.gq

- `requirement`: One requirement with every property except its embedding.
- `requirements_by_tier`: Requirements of one tier (mission, system or design_criterion), most recently changed first.
- `trace_up`: Every requirement this one derives from, up to the mission goals it serves.
- `why_exists`: Why a block exists: the requirements allocated to it and the mission goals they derive from.
- `impacted_requirements`: Requirements derived, directly or transitively, from the one being changed, with their owners.
- `impacted_tests`: Test cases verifying the changed requirement or anything derived from it: their results may no longer hold.
- `impacted_interfaces`: Interfaces constrained by the changed requirement or anything derived from it.
- `requirement_tests`: Test cases that verify one requirement directly.
- `budget_rollup`: Each budget requirement's limit beside the total of the design values beneath its block, and whether the total violates it.
- `budget_contributors`: The design values that add up to one budget, largest first.
- `limit_check`: Each single-value limit beside the design value it bounds, and whether the value violates it.
- `limit_violations`: Design values that break the single-value limit a requirement sets on them.
- `unverified_requirements`: Requirements below mission level that no test case verifies.
- `failing_requirements`: Requirements with a test case whose latest run failed.
- `stale_verification`: Passing tests that ran before their requirement last changed: the pass may no longer hold.
- `measurement_mismatch`: Tests that verify a requirement but measure a design value that requirement does not bound.
- `test_status_summary`: How many test cases are passing, failing or not yet run.
- `test_history`: Every run of one test case, newest first.
- `gate_unverified`: Requirements in scope of the iteration a review closes that no test case verifies yet.
- `gate_not_passing`: Requirements in scope of the review's iteration with a verifying test that has failed or not run.
- `gate_unfrozen_interfaces`: Interfaces constrained by requirements in the review's scope that are not yet frozen.
- `gate_stale_verification`: Requirements in scope of the review's iteration whose passing test ran before the requirement last changed.
- `open_risks`: Open risks, most severe and most likely first, with the block they sit on.
- `unmitigated_risks`: Open or accepted risks that no requirement mitigates.
- `interfaces`: Every interface with the blocks it joins and its maturity.
- `untested_interfaces`: Interfaces whose constraining requirements have no passing test.
- `assumptions_under_frozen_work`: Low- or medium-confidence assumptions that frozen requirements still rest on.
- `assumptions_due`: Assumptions whose revisit date has passed.
- `unowned_requirements`: Requirements with no owner.
- `untraced_requirements`: Derived or internal requirements with no parent requirement.
- `unexplained_components`: Components with no requirement allocated to them or to the subsystem or assembly above them.
- `awaiting_review`: Requirements an agent drafted that no person has reviewed yet.
- `open_findings`: Unresolved findings, oldest first, with who raised them.
- `compliance_matrix`: Every requirement's stance on the clauses of one standard, with its justification.
- `variant_requirements`: Requirements that apply only to one variant; requirements with no variant link apply to all.
- `decisions_affecting`: Decisions that changed or justified a requirement.
- `milestones`: Design reviews with their status and the commit each one baselined.
- `search_requirements`: Requirements matching words in their title or statement.
- `similar_requirements`: Requirements closest in meaning to the text. Needs embeddings.

## Run it

```bash
git clone https://github.com/ModernRelay/omnigraph-cookbooks
cd omnigraph-cookbooks
export COOKBOOK=$PWD/hardware-program
omnigraph cluster validate --config "$COOKBOOK"
omnigraph cluster apply --target "$COOKBOOK" --config "$COOKBOOK" --as act-admin --json
```

The full local setup (server, sample data, queries): https://github.com/ModernRelay/omnigraph-cookbooks#local-setup

Source: https://www.omnigraph.dev/use-cases/hardware-program
