275 lines
5.8 KiB
Markdown
275 lines
5.8 KiB
Markdown
# 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.
|