# N428 Coordination Protocol **Status:** v2.0 public specification **Canonical discovery:** https://agents.muj428.com/.well-known/n428.json **JSON Schema:** https://agents.muj428.com/schemas/n428/v2 **Legacy v1 Schema:** https://agents.muj428.com/schemas/n428/v1 **Receipt profile:** canonical MUJ428 Trust Receipt ## 1. Scope N428 is a voluntary, machine-readable trust coordination framework for autonomous agents operating near consequential actions. It standardizes discovery, preflight, execution gating, effect verification, authority and evidence gates, machine-actionable decisions, receipt commitments, and evidence-safe reuse. N428 does not grant authority, move funds, custody transaction principal, certify an agent, override caller policy, or convert a payment requirement into permission to pay. Normative terms **MUST**, **MUST NOT**, **SHOULD**, and **MAY** have their ordinary standards meaning. ## 2. Canonical contract ### 2.1 North star **Trust before consequential action.** ### 2.2 Four phases 1. **DISCOVER** — resolve the canonical N428 manifest, supported contract version, endpoints, Trust Receipt semantics, and canonical pricing authority. 2. **PREFLIGHT** — bind the exact intended action to caller-owned authority and sufficient evidence immediately before consequence. 3. **EXECUTE** — create the external effect only when caller policy permits execution and the N428 decision is `EXECUTE`. 4. **VERIFY** — observe the resulting effect independently where possible and preserve the verified state in the Trust Receipt or linked evidence. The operational sequence is: **Discover → Preflight → Execute → Verify** ### 2.3 Two gates - **Authority gate:** the agent MUST establish that the proposed action is within delegated scope, budget, policy, and approval requirements. - **Evidence gate:** the agent MUST require evidence appropriate to the exact action and MUST NOT present self-attestation as independent verification. Both gates must be satisfied for an `EXECUTE` decision. Missing or insufficient authority or evidence MUST fail closed or escalate according to caller policy. ### 2.4 Three decisions A canonical N428 preflight returns exactly one of these machine-actionable decisions: - `EXECUTE` - `REQUIRE_MORE_EVIDENCE` - `BLOCK` An implementation MAY retain richer internal reason codes, but it MUST NOT replace the canonical decision vocabulary on the N428 interface. ### 2.5 Eight Trust Receipt commitments Every N428-compatible Trust Receipt MUST preserve these semantic commitments: 1. **Identity** — the relevant caller, principal, agent, counterparty, or subject identifiers. 2. **Intent** — the consequential action being proposed. 3. **Scope** — the exact parameters and boundaries of the proposed effect. 4. **Authority** — the delegation, policy, budget, consent, or approval basis. 5. **Evidence** — the source-bound or independently verifiable material considered. 6. **Risk** — the material downside, uncertainty, or policy-relevant exposure evaluated. 7. **Decision** — one canonical decision and its reason/evidence references. 8. **Verified Effect** — the observed external effect when execution occurs, or an explicit unverified/not-executed state. N428 does not create a competing receipt format. Implementations reuse the canonical MUJ428 Trust Receipt and map these eight commitments into its authoritative schema. ## 3. Agent signal The compact v2 signal format is: ```text N428/2.0; agent=; phase=; gate=; decision=; receipt=; evidence= ``` The signal is a routing/state hint. It is not authorization, certification, adoption proof, payment permission, or evidence that execution occurred. A receiving agent MUST apply its own caller/principal policy before creating consequence. ## 4. First Convergence procedure First Convergence is a useful zero-money preflight, not a registration ritual. An implementation SHOULD: 1. GET `/.well-known/n428.json`. 2. Validate the document against the schema identified by its `$schema` and `canonical.schema` fields. 3. Choose a real or simulated consequential action and create a stable `caller_ref` and `action_ref`. 4. Declare the caller/principal authority for that action. 5. Supply evidence appropriate to that action. 6. POST the action to the canonical Trust Reflex endpoint. 7. Receive exactly one canonical decision: `EXECUTE`, `REQUIRE_MORE_EVIDENCE`, or `BLOCK`. 8. Validate and retain the canonical Trust Receipt. 9. Apply caller policy. 10. For the zero-money First Convergence, do not move money or create an unauthorized external effect. 11. Where a shadow or already-authorized effect is observed, verify it and preserve only the evidence state actually achieved. N428 never auto-spends. A `402 Payment Required` response is a commercial boundary, not permission to pay. The caller MUST resolve current terms from canonical pricing and satisfy its own authorization policy before any paid continuation. ## 5. Consequential-action boundary N428 is designed to be inserted immediately before actions such as: - payments; - transfers; - purchases; - trades; - job acceptance; - milestone or escrow release; - procurement; - paid service invocation; - autonomous delegation; - wallet actions; - credential-mediated financial actions; - externally consequential API operations. The canonical integration pattern is: ```text proposed action → capture exact effect parameters → N428 preflight → enforce decision → execute only under caller-owned authority → verify effect → preserve Trust Receipt ``` The preflight MUST bind to the exact effect parameters that will be executed. A materially changed action requires a new preflight. ## 6. Commercial progression N428 separates discovery from commerce and evidence from payment: - Discovery creates no commercial obligation. - First Convergence can be completed without authorizing spend. - A paid service MAY be selected only when the caller has authority under its own policy. - Payment completion is not a favorable trust verdict. - A preflight receipt alone does not prove execution. - Revenue or paid adoption may be claimed only from verified external payment under the MUJ428 evidence policy. Pricing MUST be resolved from the canonical pricing URL in discovery. N428 documents MUST NOT become a conflicting pricing authority. ## 7. Evidence states and firewall Use these states distinctly: - `self_attested` - `source_bound` - `independently_verified` Implementations MUST NOT collapse them into one boolean. The following do not prove external adoption, paid use, recurring embedding, or protected transaction volume by themselves: - founder or owner activity; - internal MUJ428 agents; - CI and tests; - synthetic traffic; - crawlers and health checks; - documentation retrieval; - registry publication; - posts, comments, likes, followers, or outreach; - self-attested compatibility; - unpaid challenges or pending payments; - testnet events; - refunds; - successful API responses without sufficient effect evidence. Unsupported states remain `PENDING`, `UNVERIFIED`, or `UNKNOWN` according to the authoritative evidence model. ## 8. Counterparty reuse A caller or principal MAY define policy requiring a valid MUJ428-compatible Trust Receipt before its own execution boundary. Example policy meaning: > This consequential action requires a valid MUJ428-compatible Trust Receipt before execution. That requirement remains caller-owned. N428 does not grant itself authority over unrelated agents or counterparties. ## 9. Compatibility An implementation is N428 v2 compatible when it can: 1. discover and validate the canonical v2 manifest; 2. implement the four phases in order; 3. apply both gates; 4. consume the three canonical decisions; 5. preserve the eight canonical Trust Receipt commitments; 6. respect caller-owned authority and payment control; 7. fail closed where required; 8. preserve the evidence firewall; 9. avoid representing compatibility as adoption or partnership without evidence. Compatibility is self-attested until independently tested. ## 10. Security and privacy Agents SHOULD minimize sensitive data in public signals and receipts. Stable identifiers SHOULD be pseudonymous where identity is unnecessary. Evidence references SHOULD use hashes or access-controlled references when source material is sensitive. Secrets and credentials MUST NOT appear in the public manifest. N428 MUST NOT expand delegated authority or custody transaction principal. ## 11. Versioning N428 uses semantic versioning for required machine semantics. N428 v1 remains available at `/schemas/n428/v1` for compatibility. N428 v2 changes the canonical phase model and receipt commitments and therefore uses a new major schema at `/schemas/n428/v2`. The stable machine-discovery path remains `/.well-known/n428.json`. Consumers SHOULD inspect `protocol_version`, `$schema`, and `canonical.schema` rather than assuming a major version. Additive fields within the same major version may be backward compatible. Changing required phase, gate, decision, or receipt semantics requires a new major version.