# 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.