diff --git a/README.md b/README.md index b4582b1..3e372af 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ axme-spec/ The AXP envelope wraps every intent. It carries the payload, sender identity, schema version, idempotency key, and a cryptographic signature applied at the gateway boundary. -![AXP Protocol Envelope](docs/diagrams/01-protocol-envelope.svg) +![AXP Protocol Envelope](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/01-protocol-envelope.svg) *Each field in the envelope is normatively defined here. The runtime and all SDKs must conform to these field names, types, and validation rules.* @@ -86,7 +86,7 @@ The AXP envelope wraps every intent. It carries the payload, sender identity, sc Schemas follow a three-phase lifecycle: stable → deprecated → removed. Breaking changes require a new major schema version. Additive changes are backward-compatible. -![Versioning and Deprecation Flow](docs/diagrams/02-versioning-and-deprecation-flow.svg) +![Versioning and Deprecation Flow](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/02-versioning-and-deprecation-flow.svg) *A schema version enters deprecation with a minimum 90-day notice period. Clients targeting a deprecated version receive `Deprecation` response headers. Removal is announced in the migration guide.* @@ -96,7 +96,7 @@ Schemas follow a three-phase lifecycle: stable → deprecated → removed. Break All schema changes go through a governance review before landing. The compatibility matrix ensures no existing consumer breaks across patch and minor versions. -![Schema Governance and Compatibility](docs/diagrams/04-schema-governance-compatibility.svg) +![Schema Governance and Compatibility](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/04-schema-governance-compatibility.svg) *Governance steps: proposal → impact analysis → compatibility check → reviewer sign-off → merge → changelog entry → docs sync.* @@ -106,7 +106,7 @@ All schema changes go through a governance review before landing. The compatibil Intent schemas are typed by `intent_type`. The payload field is a structured JSON object defined per type — not a free-form blob. This ensures every intent carries a machine-readable, versioned contract. -![Intent Payload Extensibility and Semantic Schemas](docs/diagrams/09-intent-payload-extensibility-and-semantic-schemas.svg) +![Intent Payload Extensibility and Semantic Schemas](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/intents/09-intent-payload-extensibility-and-semantic-schemas.svg) *Businesses define their own `intent_type` namespaces. The platform validates the payload against the registered schema for that type. Custom fields are allowed in designated extension zones.* @@ -116,7 +116,7 @@ Intent schemas are typed by `intent_type`. The payload field is a structured JSO All error responses follow a uniform model: HTTP status + machine-readable error code + retriability hint. -![Public API Error Model and Retriability](docs/diagrams/02-error-model-retriability.svg) +![Public API Error Model and Retriability](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/02-error-model-retriability.svg) *`4xx` errors are client errors and are not retried. `5xx` errors carry a `Retry-After` hint. Idempotency-safe operations can be safely retried with the original idempotency key.* diff --git a/docs/diagrams/01-protocol-envelope.svg b/docs/diagrams/01-protocol-envelope.svg deleted file mode 100644 index 96d611e..0000000 --- a/docs/diagrams/01-protocol-envelope.svg +++ /dev/null @@ -1,194 +0,0 @@ - - - - - - -protocol_envelope - - - -ENV - -Intent Envelope - - - -ID - -intent_id - - - -ENV->ID - - - - - -TYPE - -intent_type -(e.g. finance.approve_payment.v1) - - - -ENV->TYPE - - - - - -FROM - -from_agent - - - -ENV->FROM - - - - - -TO - -to_agent - - - -ENV->TO - - - - - -COR - -correlation_id - - - -ENV->COR - - - - - -REP - -reply_to - - - -ENV->REP - - - - - -PAY - -payload -(free JSON object) - - - -ENV->PAY - - - - - -TS - -created_at / updated_at - - - -ENV->TS - - - - - -STS - -status -CREATED→…→COMPLETED - - - -ENV->STS - - - - - -POL - -workflow_control_policy - - - -ENV->POL - - - - - -GRAN - -grants -(delegated permissions) - - - -POL->GRAN - - - - - -CTRL - -controls -(timeout_seconds) - - - -POL->CTRL - - - - - -ENV2 - -envelope -(retry / ttl / expires_at) - - - -POL->ENV2 - - - - - -PG - -policy_generation -(CAS version counter) - - - -POL->PG - - - - - diff --git a/docs/diagrams/02-error-model-retriability.svg b/docs/diagrams/02-error-model-retriability.svg deleted file mode 100644 index 77e6098..0000000 --- a/docs/diagrams/02-error-model-retriability.svg +++ /dev/null @@ -1,197 +0,0 @@ - - - - - - -error_model - - - -ERR - -API Error Response - - - -CODE - -HTTP status code - - - -ERR->CODE - - - - - -BODY - -error body - - - -ERR->BODY - - - - - -C4xx - -4xx Client Errors - - - -CODE->C4xx - - - - - -C5xx - -5xx Server Errors - - - -CODE->C5xx - - - - - -ECODE - -error_code (machine-readable) - - - -BODY->ECODE - - - - - -MSG - -message (human-readable) - - - -BODY->MSG - - - - - -DET - -details (field issues array) - - - -BODY->DET - - - - - -RID - -request_id - - - -BODY->RID - - - - - -RET - -retriable? - - - -C4xx->RET - - - - - -C5xx->RET - - - - - -DROP - -do not retry - - - -RET->DROP - - -400/403/404/409/410 - - - -BO - -exponential backoff + jitter - - - -RET->BO - - -429/500/502/503/408/504 - - - -LIM - -max attempts? - - - -BO->LIM - - - - - -DLQ - -dead-letter / alert - - - -LIM->DLQ - - -exceeded - - - -RETRY - -retry request - - - -LIM->RETRY - - -ok - - - diff --git a/docs/diagrams/02-versioning-and-deprecation-flow.svg b/docs/diagrams/02-versioning-and-deprecation-flow.svg deleted file mode 100644 index 445be3e..0000000 --- a/docs/diagrams/02-versioning-and-deprecation-flow.svg +++ /dev/null @@ -1,126 +0,0 @@ - - - - - - -versioning - - - -REQ - -API Request - - - -VERS - -version header? - - - -REQ->VERS - - - - - -DEF - -use default version - - - -VERS->DEF - - -missing - - - -CHK - -supported? - - - -VERS->CHK - - -present - - - -ROUT - -versioned handler - - - -DEF->ROUT - - - - - -CHK->ROUT - - -yes - - - -WARN - -add Deprecation header - - - -CHK->WARN - - -deprecated - - - -REJ - -reject 410 Gone - - - -CHK->REJ - - -sunset passed - - - -RESP - -Response - - - -ROUT->RESP - - - - - -WARN->ROUT - - - - - -REJ->RESP - - - - - diff --git a/docs/diagrams/04-schema-governance-compatibility.svg b/docs/diagrams/04-schema-governance-compatibility.svg deleted file mode 100644 index b2c7758..0000000 --- a/docs/diagrams/04-schema-governance-compatibility.svg +++ /dev/null @@ -1,117 +0,0 @@ - - - - - - -schema_governance - - - -REG - -Schema Registry - - - -COMPAT - -backward compatible? - - - -REG->COMPAT - - - - - -MERGE - -merge / publish new version - - - -COMPAT->MERGE - - -yes - - - -BREAK - -breaking change policy - - - -COMPAT->BREAK - - -no - - - -NOTIFY - -notify consumers via changelog - - - -MERGE->NOTIFY - - - - - -NEWVER - -new major version namespace - - - -BREAK->NEWVER - - - - - -COEX - -old + new coexist until sunset - - - -NEWVER->COEX - - - - - -DEP - -deprecate old - - - -COEX->DEP - - - - - -SUN - -sunset old after grace period - - - -DEP->SUN - - - - - diff --git a/docs/diagrams/09-intent-payload-extensibility-and-semantic-schemas.svg b/docs/diagrams/09-intent-payload-extensibility-and-semantic-schemas.svg deleted file mode 100644 index 6e3ff4d..0000000 --- a/docs/diagrams/09-intent-payload-extensibility-and-semantic-schemas.svg +++ /dev/null @@ -1,151 +0,0 @@ - - - - - - -payload_ext - - - -BASE - -Base Intent Fields - - - -TYPE - -intent_type - - - -BASE->TYPE - - - - - -FROM - -from_agent - - - -BASE->FROM - - - - - -TO - -to_agent - - - -BASE->TO - - - - - -PAY - -payload: free JSON - - - -BASE->PAY - - - - - -BIZ - -business domain data -(amount / currency / order_id) - - - -PAY->BIZ - - - - - -SEMA - -semantic schema registered? - - - -PAY->SEMA - - - - - -VAL - -validate against JSON Schema - - - -SEMA->VAL - - -yes - - - -OPAQ - -store opaque -(no validation) - - - -SEMA->OPAQ - - -no - - - -ACC - -accept intent - - - -VAL->ACC - - -pass - - - -REJ - -reject 422 - - - -VAL->REJ - - -fail - - - -OPAQ->ACC - - - - -