# Draft Family Consistency Guide
*Lead artifact — governs ATD, HITL, AEPB, APAE. Updated at -01.*

---

## 1. Canonical Term Table

Every term that appears in more than one draft. The **Authoritative Draft** column is
where the definitive definition lives; all others MUST reference it normatively.

| Term | Definition | Auth. Draft | Also used in |
|------|-----------|-------------|-------------|
| **Agent** | Autonomous software entity performing tasks, making decisions, communicating with peers or humans. | AEM §3 | ATD, HITL, AEPB, APAE |
| **Task** | Discrete unit of work performed by one agent, recorded as a single ECT node. | AEM §3 | ATD, HITL |
| **Workflow** | Set of tasks linked by dependencies, forming a DAG. Identified by ECT `wid` claim. | AEM §3 | ATD, AEPB |
| **DAG** | Directed acyclic graph of ECT parent references (`par` claims). Execution graph AND delegation graph (ACP-DAG-HITL). | AEM §3 | ATD, HITL, AEPB, APAE |
| **Checkpoint** | ECT node recording agent state before a consequential action, enabling rollback. | AEM §3 / ATD §4 | APAE |
| **HITL Point** | Position in workflow where human intervention is required or available. | AEM §3 | ATD, HITL |
| **Override** | Human-initiated command altering agent autonomous operation, taking precedence over agent decisions. | AEM §3 / HITL §3 | ATD |
| **Trust Score** | Float in [0.0, 1.0] representing assessed reliability of one agent by another. AIMD update model. | AEM §3 / APAE §4 | ATD (constraint), AEPB |
| **Protocol Binding** | Mapping between ecosystem semantics and a specific A2A communication protocol. | AEM §3 / AEPB §1 | ATD, HITL |
| **Assurance Level** | Degree of cryptographic/audit protection on ECTs: L1 (unsigned), L2 (signed JWT), L3 (signed + ledger). | AEM §3 (via ECT) | HITL, AEPB, APAE |
| **Assurance Profile** | Named configuration selecting which trust/verification/provenance mechanisms are required. | APAE §7 | AEM, AEPB |
| **Blast Radius** | Set of agents and systems affected by a single failure. | ATD §3 | — |
| **Circuit Breaker** | Mechanism preventing cascading failures by stopping requests to a failing downstream. | ATD §3/§6 | — |
| **Rollback** | Process of reverting agent actions and state to a prior checkpoint. | ATD §3/§7 | APAE |
| **Operator** | Human user authorized to issue override commands. | HITL §3 | APAE |
| **Approval Gate** | DAG node blocking workflow until human approves. | HITL §3/§8 | AEM |
| **Translation Gateway** | Service converting messages between two agent protocols; records each hop as ECT node. | AEPB §3/§6 | AEM |
| **Capability Document** | JSON object describing protocols an agent supports, served at `/.well-known/aepb`. | AEPB §3/§4 | — |
| **Trust Event** | Interaction outcome causing trust score adjustment; derived from ECTs. | APAE §3/§4 | — |
| **Behavior Specification** | Machine-readable declaration of permitted agent actions and constraints. | APAE §3/§5 | — |
| **Provenance Chain** | Sequence of ECT nodes recording how data was produced, transformed, consumed. | APAE §3/§6 | AEM |
| **Lifecycle State** | One of: `active`, `deprecated`, `draining`, `retired`. | AEPB §7 | — |

---

## 2. ECT Extension Namespace Table

All `ext` claim prefixes used across the family. Each companion draft owns one namespace.
AEM §4 (How ECT Extensions Work) is the authoritative cross-reference table.

| Namespace | Owner | Example claims |
|-----------|-------|----------------|
| `atd.*` | ATD | `atd.reversible`, `atd.severity`, `atd.circuit_state`, `atd.rollback_uri`, `atd.ttl`, `atd.resource_cpu`, `atd.resource_memory_mb` |
| `hitl.*` | HITL | `hitl.level`, `hitl.operator_id`, `hitl.prior_state`, `hitl.scope`, `hitl.constraints`, `hitl.ttl`, `hitl.reason` |
| `aepb.*` | AEPB | `aepb.source_protocol`, `aepb.dest_protocol`, `aepb.gateway_id`, `aepb.translation_warnings`, `aepb.agent_version` |
| `apae.*` | APAE | `apae.trust_score`, `apae.confidence`, `apae.hops`, `apae.subject`, `apae.compliance_status`, `apae.data_source`, `apae.data_classification` |

**Rule**: No draft may use another draft's `ext` namespace prefix without a normative
cross-reference to that draft.

---

## 3. ACP-DAG-HITL Constraint Namespace Table

All `constraints` field names used in ACP-DAG-HITL DAG node policies.

| Namespace | Owner | Example fields |
|-----------|-------|----------------|
| `atd.*` | ATD | `atd.checkpoint_policy`, `atd.circuit_threshold`, `atd.circuit_window_s`, `atd.resource_cpu`, `atd.resource_memory_mb`, `atd.resource_timeout_s`, `atd.resource_priority` |
| `hitl.*` | HITL | `hitl.required_role`, `hitl.timeout_s`, `hitl.timeout_action` (via ACP-DAG-HITL natively) |
| `aepb.*` | AEPB | `aepb.allowed_source_protocols`, `aepb.allowed_dest_protocols`, `aepb.max_translation_hops` |
| `apae.*` | APAE | `apae.min_trust`, `apae.min_confidence`, `apae.assurance_profile` |

---

## 4. `exec_act` Value Registry (Family)

All `exec_act` values registered or requested by drafts in this family.
IANA registry requested by AEM; each companion draft populates it.

| Value | Owner | Meaning |
|-------|-------|---------|
| `atd:checkpoint` | ATD | State snapshot before consequential action |
| `atd:error` | ATD | Error signal with severity and type |
| `atd:circuit_open` | ATD | Circuit breaker opened |
| `atd:circuit_close` | ATD | Circuit breaker returned to CLOSED |
| `atd:rollback_request` | ATD | Initiate rollback to checkpoint |
| `atd:rollback_result` | ATD | Result of rollback attempt |
| `atd:workflow_start` | ATD | Workflow began execution |
| `atd:workflow_complete` | ATD | Workflow reached terminal state |
| `hitl:override` | HITL | Human override command |
| `hitl:ack` | HITL | Agent acknowledgment of override |
| `hitl:resume` | HITL | Resume from PAUSE |
| `hitl:lift` | HITL | Lift any active override |
| `hitl:approval_request` | HITL | Workflow blocked at approval gate |
| `hitl:approval_granted` | HITL | Human approved continuation |
| `hitl:approval_denied` | HITL | Human denied continuation |
| `aepb:translate` | AEPB | Protocol translation hop |
| `aepb:translate_error` | AEPB | Translation failed |
| `aepb:shutdown` | AEPB | Agent completed graceful shutdown |
| `aepb:lifecycle_change` | AEPB | Agent lifecycle state transition |
| `apae:trust_assertion` | APAE | Sharing trust score for a peer |
| `apae:trust_revoke` | APAE | Revoking delegations due to low trust |
| `apae:compliance_check` | APAE | Behavior verification result |
| `apae:quarantine` | APAE | Agent quarantined (trust below floor) |

---

## 5. Cross-Reference Rules

Which drafts MUST cite which others, and for what claims.

| Draft | MUST normatively cite | For what |
|-------|----------------------|---------|
| ATD | AEM | Terminology (agent, task, workflow, DAG, assurance level) |
| ATD | ECT (I-D.nennemann-wimse-ect) | Token format, DAG structure, `exec_act` registry |
| ATD | ACP-DAG-HITL (I-D.nennemann-agent-dag-hitl-safety) | Policy layer, HITL escalation |
| ATD | HITL (this family) | HITL escalation on irreversible error/failed rollback |
| HITL | AEM | Terminology |
| HITL | ECT | Override/ack as ECT nodes |
| HITL | ACP-DAG-HITL | Trigger conditions, required roles, decision records |
| AEPB | AEM | Terminology, layered architecture |
| AEPB | ECT | Translation ECT format, `Execution-Context` header |
| AEPB | ACP-DAG-HITL | Protocol constraints as node constraints |
| AEPB | HITL (this family) | HITL callback routing through protocol bindings |
| APAE | AEM | Assurance levels (L1/L2/L3), assurance profiles |
| APAE | ECT | Trust events from ECT outcomes, audit ledger at L3 |
| APAE | ACP-DAG-HITL | Trust thresholds and profile as node constraints |
| APAE | ATD | Checkpoint requirement in profiles; rollback as trust event |
| APAE | HITL (this family) | HITL requirement in Standard/Regulated profiles |

---

## 6. Inconsistencies Found in -00 Drafts

Issues identified during review; fixed in -01 versions.

| # | Issue | Location | Fix in -01 |
|---|-------|----------|-----------|
| 1 | AEM §3 defines "Assurance Level" as "Defined by ECT" but does not list L1/L2/L3 inline; APAE §7 table is the clearest definition. | AEM -00 §3 | AEM -01 §3 adds inline L1/L2/L3 table. |
| 2 | ATD uses `atd.severity` levels (info/warning/error/critical) in §4 but no other draft references these values; they need to be in the canonical table. | ATD -00 §4 | Added to §4 normative list; noted in this guide. |
| 3 | HITL defines 4 override levels (PAUSE/CONSTRAIN/STOP/TAKEOVER) but AEM §4 table only calls them "HITL" without distinguishing levels. | AEM -00, HITL -00 | AEM -01 adds override level reference; HITL -01 adds an L0-L3 HITL intensity table to complement override levels. |
| 4 | AEPB well-known URI is `/.well-known/aepb` but HITL uses `/.well-known/hitl/...` — two different sub-path patterns. Fine, but should be noted for implementors. | AEPB -00, HITL -00 | Both -01s add a note about the well-known URI structure. |
| 5 | APAE references `apae.peer_trust_score` in a HITL rule (§4.5) but the term `peer_trust_score` is not defined as an `ext` claim elsewhere. | APAE -00 §4.5 | APAE -01 clarifies this is a runtime context value derived from the trust table, not an ECT claim. |
| 6 | ATD rollback endpoint is `POST /atd/rollback` (not a well-known URI), while HITL uses well-known URIs. Inconsistency in endpoint naming convention. | ATD -00 §7, HITL -00 §5 | ATD -01 updates rollback endpoint to `/.well-known/atd/rollback` for consistency. |
| 7 | No draft defines a `wf_id` / `wid` claim format. AEM mentions `wid` from ECT but ECT draft details need to be normatively cited. | AEM -00 §3 | All -01s add normative reference to ECT for `wid`. |