Skip to content

Commit 5b3b22b

Browse files
omoshola-oomoshola-o
committed
Add 52/52 edge case tests and federation hints documentation
- Added 70 new edge case tests across 6 test files (settlement, negotiation, verity, identity, discovery, adapter) bringing coverage from 30 to 52/52 - Added 8 new invalid JSON examples for schema validation - Updated edge-cases.md registry marking all 52 cases as TESTED - Added federation_hints example to README.md - Updated settlement-intent schema
1 parent 538bd51 commit 5b3b22b

16 files changed

Lines changed: 1290 additions & 4 deletions

‎README.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
AI agents can think, reason, code, search, and orchestrate. But when two agents need to do business with each other, there is no shared language for how that happens.
1818

19-
No standard way to negotiate a price. No way to escrow funds against a conditional outcome. No way to split payment across five agents that contributed to one result. No way to prove, months later, exactly why a settlement resolved the way it did.
19+
No standard way to negotiate a price. No way to hold funds pending verification of a conditional outcome. No way to split payment across five agents that contributed to one result. No way to prove, months later, exactly why a settlement resolved the way it did.
2020

2121
Stripe and OpenAI built ACP for agent-assisted shopping. Google built AP2 for human-authorized agent payments. Coinbase built x402 for pay-per-request API access.
2222

@@ -70,7 +70,7 @@ OFFER -> COUNTER -> ACCEPT or REJECT
7070

7171
Four states. Time-bound offers. Conditional pricing. SLA declared before execution. Every state transition signed and permanent.
7272

73-
### Conditional Escrow
73+
### Conditional Hold
7474

7575
The primitive is not "Agent A pays Agent B." It is: Agent A locks funds. Agent B performs work. A verifiable condition is checked. Funds release if the condition passes. No money ever sits in limbo.
7676

@@ -103,6 +103,23 @@ agent-to-agent settlements and human-auditable financial records:
103103
- **Causal chains** — multi-agent workflow graphs are fully navigable
104104
- **External attestation** — probabilistic verifiers sign their results cryptographically
105105

106+
### Federation Hints
107+
108+
The `AgentManifest` supports an optional `federation_hints` field for cross-registry portability. When an agent is registered on multiple XAP-compatible registries, `federation_hints` lets counterparties discover those alternate registrations and verify portable identity proofs.
109+
110+
```json
111+
{
112+
"federation_hints": {
113+
"also_registered_at": [
114+
"https://other-registry.example.com"
115+
],
116+
"identity_portable_proof": "xap_port_proof_abc123"
117+
}
118+
}
119+
```
120+
121+
The `also_registered_at` array lists other registry URLs where the same agent identity is registered. The `identity_portable_proof` is a cryptographic token that any listed registry can verify to confirm the agent controls the same key pair. This enables multi-registry discovery without centralized coordination.
122+
106123
### Append-Only Reputation
107124

108125
An agent's execution history is permanently attached to its identity. Trust is computable rather than assumed.

‎xap/schemas/settlement-intent.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"$schema": "https://json-schema.org/draft/2020-12/schema",
33
"$id": "https://xap.agentralabs.tech/schemas/v0.2/settlement-intent.json",
44
"title": "SettlementIntent",
5-
"description": "XAP v0.2 — The escrow instruction. Funds lock, conditions verify, funds release or refund. The core primitive. Every field, every constraint, every failure mode defined with zero ambiguity.",
5+
"description": "XAP v0.2 — The conditional hold instruction. Funds lock, conditions verify, funds release or refund. The core primitive. Every field, every constraint, every failure mode defined with zero ambiguity.",
66
"type": "object",
77
"required": [
88
"settlement_id",
@@ -57,7 +57,7 @@
5757
"payer_agent": {
5858
"type": "string",
5959
"pattern": "^agent_[a-f0-9]{8}$",
60-
"description": "Agent locking funds into escrow."
60+
"description": "Agent locking funds into a payment hold. BREAKING: field rename needed in v0.4 — escrow → payment_hold"
6161
},
6262
"payee_agents": {
6363
"type": "array",

‎xap/tests/invalid/agent-identity/duplicate-agent-id.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"agent_id": "agent_BADFORMAT",
3+
"public_key": "ed25519:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=",
4+
"key_version": 1,
5+
"key_status": "active",
6+
"capabilities": [
7+
{
8+
"name": "text_summarization",
9+
"version": "1.0.0",
10+
"pricing": {"model": "fixed", "amount_minor_units": 300, "currency": "USD", "per": "request"},
11+
"sla": {"max_latency_ms": 3000, "availability_bps": 9900}
12+
}
13+
],
14+
"reputation": {
15+
"total_settlements": 0,
16+
"success_rate_bps": 0,
17+
"disputes": 0,
18+
"dispute_resolution_rate_bps": 0,
19+
"last_updated": "2026-03-09T12:00:00Z"
20+
},
21+
"xap_version": "0.2.0",
22+
"status": "active",
23+
"registered_at": "2026-03-09T12:00:00Z",
24+
"last_active_at": "2026-03-09T12:00:00Z",
25+
"signature": "ed25519:c2lnbmF0dXJlX2V4YW1wbGVfYmFzZTY0X2VuY29kZWQ="
26+
}

‎xap/tests/invalid/agent-identity/org-without-team-id.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"agent_id": "agent_7f3a9b2c",
3+
"public_key": "ed25519:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=",
4+
"key_version": 1,
5+
"key_status": "active",
6+
"team_id": "team_e5f6a7b8",
7+
"capabilities": [
8+
{
9+
"name": "text_summarization",
10+
"version": "1.0.0",
11+
"pricing": {"model": "fixed", "amount_minor_units": 300, "currency": "USD", "per": "request"},
12+
"sla": {"max_latency_ms": 3000, "availability_bps": 9900}
13+
}
14+
],
15+
"reputation": {
16+
"total_settlements": 0,
17+
"success_rate_bps": 0,
18+
"disputes": 0,
19+
"dispute_resolution_rate_bps": 0,
20+
"last_updated": "2026-03-09T12:00:00Z"
21+
},
22+
"xap_version": "0.2.0",
23+
"status": "active",
24+
"registered_at": "2026-03-09T12:00:00Z",
25+
"last_active_at": "2026-03-09T12:00:00Z",
26+
"signature": "ed25519:c2lnbmF0dXJlX2V4YW1wbGVfYmFzZTY0X2VuY29kZWQ="
27+
}

‎xap/tests/invalid/settlement-intent/currency-mismatch.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"settlement_id": "stl_4b7c9e2f",
3+
"negotiation_id": "neg_8a2f4c1d",
4+
"state": "PENDING_LOCK",
5+
"payer_agent": "agent_7f3a9b2c",
6+
"payee_agents": [{"agent_id": "agent_2d8e5f1a", "share_bps": 10000, "role": "primary_executor"}],
7+
"total_amount_minor_units": 500,
8+
"currency": "eur",
9+
"adapter": "stripe",
10+
"conditions": [{"condition_id": "cond_a1b2", "type": "deterministic", "check": "http_status_200", "verifier": "engine", "required": true}],
11+
"timeout_seconds": 30,
12+
"on_timeout": "full_refund",
13+
"on_partial_completion": "pro_rata",
14+
"on_failure": "full_refund",
15+
"chargeback_policy": "proportional",
16+
"idempotency_key": "idem_9c3f2a1b",
17+
"finality_class": "reversible",
18+
"xap_version": "0.2.0",
19+
"created_at": "2026-03-15T14:30:00Z",
20+
"signature": "ed25519:c2V0dGxlbWVudF9zaW1wbGVfc2ln"
21+
}

‎xap/tests/invalid/settlement-intent/duplicate-idempotency-key.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"settlement_id": "stl_4b7c9e2f",
3+
"negotiation_id": "neg_8a2f4c1d",
4+
"state": "PENDING_LOCK",
5+
"payer_agent": "agent_7f3a9b2c",
6+
"payee_agents": [{"agent_id": "agent_2d8e5f1a", "share_bps": 10000, "role": "primary_executor"}],
7+
"total_amount_minor_units": 500,
8+
"currency": "USD",
9+
"adapter": "stripe",
10+
"conditions": [{"condition_id": "cond_a1b2", "type": "deterministic", "check": "http_status_200", "verifier": "engine", "required": true}],
11+
"timeout_seconds": 30,
12+
"on_timeout": "full_refund",
13+
"on_partial_completion": "pro_rata",
14+
"on_failure": "full_refund",
15+
"chargeback_policy": "proportional",
16+
"idempotency_key": "idem_DUPLICATE",
17+
"finality_class": "reversible",
18+
"xap_version": "0.2.0",
19+
"created_at": "2026-03-15T14:30:00Z",
20+
"signature": "ed25519:c2V0dGxlbWVudF9zaW1wbGVfc2ln"
21+
}

‎xap/tests/invalid/settlement-intent/zero-amount.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"settlement_id": "stl_4b7c9e2f",
3+
"negotiation_id": "neg_8a2f4c1d",
4+
"state": "PENDING_LOCK",
5+
"payer_agent": "agent_7f3a9b2c",
6+
"payee_agents": [{"agent_id": "agent_2d8e5f1a", "share_bps": 10000, "role": "primary_executor"}],
7+
"total_amount_minor_units": 0,
8+
"currency": "USD",
9+
"adapter": "stripe",
10+
"conditions": [{"condition_id": "cond_a1b2", "type": "deterministic", "check": "http_status_200", "verifier": "engine", "required": true}],
11+
"timeout_seconds": 30,
12+
"on_timeout": "full_refund",
13+
"on_partial_completion": "pro_rata",
14+
"on_failure": "full_refund",
15+
"chargeback_policy": "proportional",
16+
"idempotency_key": "idem_9c3f2a1b",
17+
"finality_class": "reversible",
18+
"xap_version": "0.2.0",
19+
"created_at": "2026-03-15T14:30:00Z",
20+
"signature": "ed25519:c2V0dGxlbWVudF9zaW1wbGVfc2ln"
21+
}

‎xap/tests/invalid/verity-receipt/chain-break-missing-entry.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"verity_id": "vrt_a1b2c3d4",
3+
"settlement_id": "stl_4b7c9e2f",
4+
"decision_type": "condition_verification",
5+
"decision_timestamp": "2026-03-15T14:30:28Z",
6+
"input_state": {
7+
"settlement_state": "PENDING_VERIFICATION",
8+
"contract_terms": {"pricing": {"amount_minor_units": 500, "currency": "USD"}, "sla": {"max_latency_ms": 5000}, "conditions": [{"condition_id": "cond_a1b2", "type": "deterministic"}]},
9+
"agent_states": [{"agent_id": "agent_2d8e5f1a", "role": "primary_executor"}]
10+
},
11+
"rules_applied": {
12+
"rules_version": "0.2.0",
13+
"rules_hash": "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
14+
"applicable_rules": [{"rule_id": "cond_check", "rule_description": "Check condition", "evaluated": true, "result": "pass"}]
15+
},
16+
"computation": {"steps": [{"step_number": 1, "operation": "evaluate_condition", "inputs": {"condition_id": "cond_a1b2"}, "output": {"passed": true}, "deterministic": true}], "total_steps": 1, "computation_duration_ms": 3},
17+
"outcome": {"decision": "release_funds", "settlement_state_after": "SETTLED", "outcome_classification": "SUCCESS"},
18+
"replay_hash": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
19+
"confidence_bps": 10000,
20+
"chain_previous_verity_hash": "sha256:INVALID_HASH_FORMAT_NOT_HEX_SHOULD_FAIL_VALIDATION_MISSING_ENT",
21+
"chain_position": 3,
22+
"xap_version": "0.2.0",
23+
"verity_engine_version": "0.2.0",
24+
"verity_signature": "ed25519:dmVyaXR5X3NpbXBsZV9zaWduYXR1cmU="
25+
}

‎xap/tests/invalid/verity-receipt/evidence-hash-mismatch.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"verity_id": "vrt_a1b2c3d4",
3+
"settlement_id": "stl_4b7c9e2f",
4+
"decision_type": "condition_verification",
5+
"decision_timestamp": "2026-03-15T14:30:28Z",
6+
"input_state": {
7+
"settlement_state": "PENDING_VERIFICATION",
8+
"contract_terms": {"pricing": {"amount_minor_units": 500, "currency": "USD"}, "sla": {"max_latency_ms": 5000}, "conditions": [{"condition_id": "cond_a1b2", "type": "deterministic"}]},
9+
"agent_states": [{"agent_id": "agent_2d8e5f1a", "role": "primary_executor"}],
10+
"dispute_evidence": {"submitted_by": "agent_2d8e5f1a", "evidence_type": "screenshot", "evidence_hash": "sha256:ZZZZZZ_TAMPERED_HASH_NOT_MATCHING_ORIGINAL_EVIDENCE_CONTENTZZZ"}
11+
},
12+
"rules_applied": {
13+
"rules_version": "0.2.0",
14+
"rules_hash": "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
15+
"applicable_rules": [{"rule_id": "evidence_check", "rule_description": "Verify evidence hash", "evaluated": true, "result": "fail"}]
16+
},
17+
"computation": {"steps": [{"step_number": 1, "operation": "verify_evidence", "inputs": {"evidence_hash": "sha256:TAMPERED"}, "output": {"valid": false}, "deterministic": true}], "total_steps": 1, "computation_duration_ms": 2},
18+
"outcome": {"decision": "evidence_tampered", "settlement_state_after": "DISPUTED", "outcome_classification": "FAIL"},
19+
"replay_hash": "sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
20+
"confidence_bps": 10000,
21+
"chain_position": 1,
22+
"xap_version": "0.2.0",
23+
"verity_engine_version": "0.2.0",
24+
"verity_signature": "ed25519:dmVyaXR5X3NpbXBsZV9zaWduYXR1cmU="
25+
}

‎xap/tests/invalid/verity-receipt/replay-hash-mismatch.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"verity_id": "vrt_a1b2c3d4",
3+
"settlement_id": "stl_4b7c9e2f",
4+
"decision_type": "condition_verification",
5+
"decision_timestamp": "2026-03-15T14:30:28Z",
6+
"input_state": {
7+
"settlement_state": "PENDING_VERIFICATION",
8+
"contract_terms": {"pricing": {"amount_minor_units": 500, "currency": "USD"}, "sla": {"max_latency_ms": 5000}, "conditions": [{"condition_id": "cond_a1b2", "type": "deterministic"}]},
9+
"agent_states": [{"agent_id": "agent_2d8e5f1a", "role": "primary_executor"}]
10+
},
11+
"rules_applied": {
12+
"rules_version": "0.2.0",
13+
"rules_hash": "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
14+
"applicable_rules": [{"rule_id": "cond_check", "rule_description": "Check condition", "evaluated": true, "result": "pass"}]
15+
},
16+
"computation": {"steps": [{"step_number": 1, "operation": "evaluate_condition", "inputs": {"condition_id": "cond_a1b2"}, "output": {"passed": true}, "deterministic": true}], "total_steps": 1, "computation_duration_ms": 3},
17+
"outcome": {"decision": "release_funds", "settlement_state_after": "SETTLED", "outcome_classification": "SUCCESS"},
18+
"replay_hash": "sha256:INVALID_NOT_64_HEX_CHARS_replay_hash_that_does_not_match_at_all",
19+
"confidence_bps": 10000,
20+
"chain_position": 1,
21+
"xap_version": "0.2.0",
22+
"verity_engine_version": "0.2.0",
23+
"verity_signature": "ed25519:dmVyaXR5X3NpbXBsZV9zaWduYXR1cmU="
24+
}

0 commit comments

Comments
 (0)