amduat/docs/oss-backend-adapter-boundary.md

# OSS Backend Adapter Boundary

Status: Draft
Purpose: Define architectural boundaries, responsibilities, and conformance requirements for implementing the OSS backend stack (MinIO, JanusGraph, Cassandra, Elasticsearch, etc.) as spec-compliant adapters.

---

# 1. Architectural Position

The OSS backend is an implementation of store/query surfaces, not a semantic extension.

It implements:
1. ASL/1-STORE.
2. TGK/STORE/1.
3. Optional: TGK/PROV/1.
4. Optional: derived projections (ES, lakehouse).

It does not redefine:
1. Core semantics (ASL/1-CORE, PEL/1-CORE, TGK/1-CORE).
2. Canonical encoding (ENC/ASL1-CORE).
3. Identity derivation (ASL/1-CORE and HASH/ASL1).

---

# 2. Authority and Responsibility Model

## 2.1 Authoritative Components

Authoritative state resides in:
1. Deployed ASL/1-STORE implementation.
2. Deterministic TGK projection derived from ASL state.

Adapters must preserve this.

## 2.2 Derived Components

The following are derived projections:
1. Elasticsearch.
2. IPFS.
3. Lakehouse snapshots.
4. AI outputs.

Derived components must:
1. Be replayable.
2. Be observationally equivalent.
3. Never redefine semantics.

---

# 3. Adapter Modules

This document defines four adapter classes.

## 3.1 ASL Store Adapter (MinIO or S3)

### Purpose

Implements ASL/1-STORE.

### Responsibilities

1. Accept `put(Artifact) -> Reference`.
2. Enforce canonical encoding validation.
3. Persist artifact bytes under canonical identity.
4. Implement `get(Reference) -> Artifact | NotFound`.
5. Map backend errors to canonical error model.

### Non-Responsibilities

1. Computing identity (handled by core logic).
2. Interpreting artifact contents.
3. Modifying encoding.
4. Adding metadata not declared by spec.

### Determinism Requirements

1. Same Artifact → same Reference.
2. Same Reference → identical bytes returned.
3. No backend-specific mutation.

### Configuration Surface

1. Endpoint.
2. Credentials.
3. Bucket name.
4. Retry policy.
5. Multipart threshold.
6. Timeout policy.

---

## 3.2 TGK Store Adapter (JanusGraph plus Cassandra)

### Purpose

Implements TGK/STORE/1.

### Responsibilities

1. Provide required query operations defined in TGK/STORE/1.
2. Enforce canonical `(hash_id, digest)` ordering.
3. Maintain deterministic projection behavior.
4. Map errors to spec-defined error model.

### Non-Responsibilities

1. Creating semantic edges (done via EdgeArtifacts).
2. Redefining graph semantics.
3. Implicitly inferring relationships.
4. Providing authoritative ordering outside spec.

### Determinism Requirements

1. Same ASL state → same TGK answers.
2. Same queries → same ordered results.
3. Ordering must not depend on Janus internal traversal order.

### Ordering Enforcement Point

Ordering MUST be applied:
1. Explicitly in the adapter layer, or
2. In a canonical result transformation layer.

Never rely on backend default sort semantics.

---

## 3.3 Projection Adapter (Elasticsearch)

### Purpose

Accelerate search and filtering.

### Responsibilities

1. Project canonical artifact metadata.
2. Optionally project EdgeArtifacts.
3. Maintain replayable checkpoint.
4. Expose lag metric.
5. Enforce schema versioning.

### Non-Responsibilities

1. Authoritative artifact reads.
2. Authoritative graph queries.
3. Deterministic ordering.

### Verification Requirement

Any ES-derived candidate results must be:
1. Confirmed via ASL/1-STORE.
2. Ordered via TGK/STORE/1 logic before returning to clients.

---

## 3.4 Snapshot or Lakehouse Adapter (Future)

### Purpose

Batch export and audit workflows.

### Responsibilities

1. Snapshot export from authoritative state.
2. Versioned dataset generation.
3. Replay equivalence validation.

### Non-Responsibilities

1. Live semantic authority.
2. Mutation of ASL state.

---

# 4. Adapter Error Taxonomy

All adapters must map backend-specific errors into a canonical internal taxonomy:
1. NotFound.
2. InvalidArtifact.
3. PermissionDenied.
4. TransientIO.
5. InternalError.

No backend-specific error types may leak across the adapter boundary.

---

# 5. Conformance Gates

No adapter may be merged or promoted unless:

## 5.1 ASL Adapter

1. Passes ASL/1-STORE conformance suite.
2. Passes replay equivalence test.
3. Passes cross-backend equivalence test.

## 5.2 TGK Adapter

1. Passes TGK/STORE/1 required query suite.
2. Passes deterministic ordering test.
3. Passes cross-backend equivalence test.

## 5.3 Projection Adapter

1. System passes integration tests with projection disabled.
2. Rebuild equivalence test passes.
3. Lag metric exposed and validated.

---

# 6. Observability Contract

All adapters must expose:
1. Health endpoint.
2. Error metrics.
3. Operation latency metrics.
4. Determinism assertion failures.
5. Projection lag, if applicable.

---

# 7. Security Boundary

Adapters must:
1. Not embed secrets in artifacts.
2. Respect per-TypeTag redaction policies before indexing.
3. Enforce explicit credential configuration.
4. Avoid implicit trust of backend defaults.

---

# 8. Interaction with Conformance Harness

Adapter design is subordinate to the Phase 0 harness.

Implementation order:
1. Conformance harness operational.
2. Adapter scaffold.
3. Adapter passes harness.
4. Integration and load testing.

No adapter bypasses this sequence.

---

# 9. Design Outcome

This boundary ensures:
1. Thin adapters.
2. Zero semantic drift.
3. Deterministic reproducibility.
4. Backend substitutability.
5. Operational scalability without semantic mutation.

The OSS backend becomes:

An infrastructure implementation of store/query surfaces, not an evolution of the semantic core.

---

# Where You Are Now (Strategic Position)

You now have:
1. Semantic core locked.
2. Execution boundary defined.
3. Indexing contract defined.
4. Backend boundary defined.
5. Implementation phases defined.

You are ready to:
1. Design adapter scaffolds.
2. Build Phase 0 conformance harness.
3. Begin MinIO adapter implementation safely.