99 lines
2.8 KiB
Markdown
99 lines
2.8 KiB
Markdown
|
# 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.
|