amduat/docs/adapter-error-taxonomy.md

Adapter Error Taxonomy

Status: Draft Scope: Canonical error mapping for ASL and TGK adapters and derived projections, used by conformance tests to prevent drift.

---

1. Purpose

This taxonomy defines a canonical internal error set. Adapters MUST map backend-specific errors into these categories so that conformance tests remain stable across backends.

---

2. Canonical Error Set

2.1 ASL Store Errors

Canonical enum (from include/amduat/asl/store.h):

1. AMDUAT_ASL_STORE_ERR_INTEGRITY
2. AMDUAT_ASL_STORE_ERR_UNSUPPORTED
3. AMDUAT_ASL_STORE_ERR_NOT_FOUND
4. AMDUAT_ASL_STORE_ERR_IO

2.2 TGK Graph Store Errors

Canonical enum (from include/amduat/tgk/store.h):

1. GS_ERR_NOT_EDGE
2. GS_ERR_ARTIFACT_ERROR
3. GS_ERR_UNSUPPORTED
4. GS_ERR_INTEGRITY

2.3 Projection Errors (Derived Indexers)

Canonical categories:

1. NotFound
2. PermissionDenied
3. TransientIO
4. InvalidDocument
5. InternalError

Projection errors must never be surfaced as authoritative ASL or TGK errors.

---

3. Mapping Rules

3.1 ASL/1-STORE Mapping

1. ERR_NOT_FOUND → AMDUAT_ASL_STORE_ERR_NOT_FOUND
2. ERR_INTEGRITY → AMDUAT_ASL_STORE_ERR_INTEGRITY
3. ERR_UNSUPPORTED → AMDUAT_ASL_STORE_ERR_UNSUPPORTED
4. Backend I/O or transport failure → AMDUAT_ASL_STORE_ERR_IO

Notes:

1. ASL/1-STORE does not standardize I/O or auth errors; those must map to ERR_IO for conformance tests.
2. A put collision on identical reference with different bytes MUST map to ERR_INTEGRITY.

3.2 TGK/STORE/1 Mapping

1. Reference resolves to non-edge artifact → GS_ERR_NOT_EDGE
2. Artifact-layer integrity failure during resolve → GS_ERR_ARTIFACT_ERROR
3. Unsupported profile/encoding → GS_ERR_UNSUPPORTED
4. Detected graph-level corruption → GS_ERR_INTEGRITY

Notes:

1. GS_ERR_ARTIFACT_ERROR is required for artifact-level conflicts; do not use GS_ERR_INTEGRITY.
2. Backend-specific errors must be normalized to the canonical TGK error set.

3.3 Projection Adapter Mapping

1. Index missing doc → NotFound
2. Authorization failure → PermissionDenied
3. Timeout, transport, or retryable failure → TransientIO
4. Schema or decode failure → InvalidDocument
5. Unknown failure → InternalError

Projection errors are operational only and must not be treated as ASL/TGK semantic failures.

---

4. Test Requirements

Conformance tests MUST include:

1. ASL: get on missing ref → ERR_NOT_FOUND.
2. ASL: put collision → ERR_INTEGRITY.
3. ASL: unsupported config → ERR_UNSUPPORTED.
4. ASL: I/O failure path → ERR_IO.
5. TGK: resolve_edge on non-edge → GS_ERR_NOT_EDGE.
6. TGK: artifact integrity conflict → GS_ERR_ARTIFACT_ERROR.
7. TGK: unsupported encoding/profile → GS_ERR_UNSUPPORTED.

---

5. Non-Goals

1. Backend-specific error codes.
2. Retry policy definitions.
3. Human-readable error messaging conventions.