# Architecture

## Purpose

Graph Engineering Architect is a design-time control framework. It does not schedule agents or grant permissions. It makes the control contract reviewable before a runtime implements it.

The root contract is:

```text
human-owned outcome
        |
        v
execution loop -> independent verification -> constrain | veto
        |                    |
        v                    v
counter-signals         reality anchors
        |                    |
        +------> arbitration + governance
                              |
                              v
                     human approval gate
                              |
                              v
                   continue | rollback | stop
```

## Classification before construction

| Mode | Use when | Persistent control artifacts |
| --- | --- | --- |
| Direct | One bounded action has no useful feedback cycle | Usually none |
| Loop | One dominant goal and one trustworthy verifier support meaningful retries | `.loop/<slug>/` via Loop Engineering Co-Builder |
| Graph | Several loops, objectives, speeds, evidence sources, or authorities interact | `.graph/<slug>/` plus node-level loops where justified |

Multiple steps or multiple agents do not automatically justify a graph. A graph is justified by interacting control responsibilities.

## Node kinds

| Kind | Responsibility | Typical authority |
| --- | --- | --- |
| `execution_loop` | Act to improve the target | May change bounded operational variables |
| `verification_loop` | Test claimed progress independently | May fail or constrain a candidate |
| `counter_metric_loop` | Detect cheap wins and side effects | May halt expansion when thresholds are breached |
| `audit_loop` | Check data, definitions, and provenance | May invalidate evidence |
| `arbitration` | Resolve declared conflicts | Applies a human-approved priority policy |
| `governance_loop` | Review goals and thresholds slowly | Proposes changes; does not silently apply them |
| `anchor` | Bind claims to reality | Frozen against optimization |
| `human_gate` | Own irreducible judgment | Approves goals, anchors, permissions, release, and risk acceptance |
| `stop_handoff` | Preserve truthful terminal state | Stops, rolls back, escalates, or hands off |

## Edge semantics

Every edge must name both its control relation and the artifact crossing it.

| Relation | Meaning |
| --- | --- |
| `feeds` | Supplies an input without control authority |
| `observes` | Monitors state or evidence |
| `verifies` | Tests a claim against criteria |
| `constrains` | Limits allowed actions or parameters |
| `vetoes` | Blocks a transition or release |
| `escalates` | Transfers unresolved judgment upward |
| `arbitrates` | Resolves a declared conflict |
| `revises` | Proposes or applies an authorized reference change |
| `anchors` | Binds a claim to grounded evidence |
| `hands_off` | Transfers resumable state and next action |

Edges such as “communicates with” are rejected because they do not define evidence or authority.

## Grounding invariants

An acceptable graph must preserve these invariants:

1. The root outcome has a named human owner.
2. At least one anchor is independent of the optimizing loop.
3. The optimizing loop cannot edit, hide, or redefine the anchor.
4. Evaluation independence covers data provenance, not only evaluator identity.
5. Goal changes require human approval.
6. Frozen items and stop conditions are explicit.
7. Completion requires fresh anchored evidence and a usable handoff.

## Composition with Loop Engineering

Graph Engineering owns the topology and cross-loop governance. Loop Engineering owns the internal state machine of a bounded loop.

For example, `execution_loop` may be implemented as a `.loop/model-improvement/` contract. Its node-level improvement proposal may suggest a new threshold, but the graph-level `human_gate` must approve that change before the governance contract changes.

This preserves a key separation:

```text
node learns how to act better
        !=
node gains authority to redefine what better means
```

## What structural validation proves

`validate_graph.py` checks:

- required top-level fields;
- recognized node and edge kinds;
- unique nodes and no dangling edges;
- execution, independent verification, counter-signal or audit, anchor, human gate, and stop/handoff responsibilities;
- frozen anchors;
- human approval for goal changes;
- arbitration, approval, and terminal-state rules;
- at least one explicit verification check.

It cannot prove that a source is actually independent, that an organization will respect a veto, or that the root outcome is worth pursuing. Those require domain evidence and human judgment.