diff --git a/README.md b/README.md index 39dc266..0d50b51 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ axme-conformance/ The traceability map shows how conformance checks are anchored to spec families, runtime behaviors, and SDK methods. -![Conformance Traceability Map](docs/diagrams/04-conformance-traceability-map.svg) +![Conformance Traceability Map](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/platform/04-conformance-traceability-map.svg) *Each check cell links a spec contract (from `axme-spec`) to a runtime behavior (tested against `axme-control-plane`) and an SDK binding (tested per SDK). Green = passing, yellow = partial, red = failing or not yet implemented.* @@ -89,7 +89,7 @@ The traceability map shows how conformance checks are anchored to spec families, Conformance results feed the audit trail. Every check run produces an evidence record that maps to the access control and policy enforcement layer. -![Audit Trail Map](docs/diagrams/08-audit-trail-map.svg) +![Audit Trail Map](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/intents/08-audit-trail-map.svg) *Audit evidence is structured: which check ran, against which endpoint, with which actor identity, what the result was. Evidence records are stored in the CI artifact archive.* @@ -99,7 +99,7 @@ Conformance results feed the audit trail. Every check run produces an evidence r Schema governance checks validate that schema changes in `axme-spec` do not introduce backward-incompatible breaks for existing consumers. -![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) *The compatibility check compares the new schema against all previously registered consumer versions. A breaking change fails the gate and requires a new schema version.* @@ -109,7 +109,7 @@ Schema governance checks validate that schema changes in `axme-spec` do not intr The most complex conformance domain covers the three-way conflict between a `resume` call, an in-flight `controls` update, and a `policy` mutation arriving at the same instant. -![Resume, Controls, and Policy Conflict Resolution](docs/diagrams/11-resume-controls-policy-conflict-resolution.svg) +![Resume, Controls, and Policy Conflict Resolution](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/intents/11-resume-controls-policy-conflict-resolution.svg) *Conflict resolution rules: `resume` wins over `controls` if the intent is in a terminal `WAITING_*` state. `policy_generation` CAS prevents concurrent `policy` mutations from stomping each other. All conflicts are recorded in the audit trail.* diff --git a/docs/diagrams/04-conformance-traceability-map.svg b/docs/diagrams/04-conformance-traceability-map.svg deleted file mode 100644 index fa1510d..0000000 --- a/docs/diagrams/04-conformance-traceability-map.svg +++ /dev/null @@ -1,134 +0,0 @@ - - - - - - -conformance - - - -SPEC - -axme-spec -(schemas + OpenAPI) - - - -SDK - -axme-sdk-* -(SDK tests) - - - -SPEC->SDK - - - - - -CONF - -axme-conformance -(conformance suite) - - - -SPEC->CONF - - - - - -CP - -axme-control-plane -(runtime) - - - -SPEC->CP - - - - - -DOCS - -axme-docs -(documentation) - - - -SPEC->DOCS - - - - - -E2E - -E2E tests - - - -SDK->E2E - - - - - -CONF->E2E - - - - - -CP->E2E - - - - - -RES - -pass? - - - -E2E->RES - - - - - -CERT - -conformance certified - - - -RES->CERT - - -yes - - - -GAP - -gap → spec issue / impl fix - - - -RES->GAP - - -no - - - 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/08-audit-trail-map.svg b/docs/diagrams/08-audit-trail-map.svg deleted file mode 100644 index 2af19d8..0000000 --- a/docs/diagrams/08-audit-trail-map.svg +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - -audit_trail - - - -CALL - -Caller / Service A -API call - - - -GW - -AXME Cloud API -process request - - - -CALL->GW - - - - - -STORE - -Policy/State Store -mutate intent - - - -GW->STORE - - - - - -OBS - -Observability -trace_id, status, latency - - - -GW->OBS - - - - - -RESP - -Caller -API response - - - -GW->RESP - - -return - - - -WHY - -mutation type? - - - -STORE->WHY - - - - - -AUDIT - -Audit Trail -write event - - - -AUDIT->RESP - - - - - -POL - -Audit: policy_update -old/new generation -patch summary - - - -WHY->POL - - -policy mutation - - - -STAT - -Audit: status_update -old/new status -reason - - - -WHY->STAT - - -status mutation - - - -REJ - -Audit: mutation_rejected -reason, actor - - - -WHY->REJ - - -rejected - - - -POL->AUDIT - - - - - -STAT->AUDIT - - - - - -REJ->AUDIT - - - - - -ERR - -Observability -error counter + latency - - - -REJ->ERR - - - - - diff --git a/docs/diagrams/11-resume-controls-policy-conflict-resolution.svg b/docs/diagrams/11-resume-controls-policy-conflict-resolution.svg deleted file mode 100644 index 5563e5a..0000000 --- a/docs/diagrams/11-resume-controls-policy-conflict-resolution.svg +++ /dev/null @@ -1,146 +0,0 @@ - - - - - - -resume_policy - - - -INT - -Intent: WAITING - - - -RES - -POST /intents/:id/resume - - - -INT->RES - - - - - -CTRL - -PATCH /intents/:id/controls - - - -INT->CTRL - - - - - -POL - -PATCH /intents/:id/policy - - - -INT->POL - - - - - -GATE - -policy grants -allow resume? - - - -RES->GATE - - - - - -CASC - -policy_generation -matches? - - - -CTRL->CASC - - - - - -POL->CASC - - - - - -EXEC - -resume execution - - - -GATE->EXEC - - -yes - - - -DENY - -403 Forbidden - - - -GATE->DENY - - -no - - - -APPLY - -apply delta - - - -CASC->APPLY - - -yes - - - -CONF - -409 Conflict -(retry with fresh generation) - - - -CASC->CONF - - -no - - - -APPLY->EXEC - - - - -