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.