315 lines
6.1 KiB
Markdown
315 lines
6.1 KiB
Markdown
|
Great — this is the **right moment** to define it, because everything underneath (artifacts, DAGs, indexes, snapshots, logs) is now solid.
|
|||
|
|
|
|||
|
|
What follows is a **clean, minimal, *normative* ASL-STORE put/get contract** that:
|
|||
|
|
|
|||
|
|
* Sits *between* ASL-CORE / ASL-CORE-INDEX and any concrete storage engine
|
|||
|
|
* Is compatible with your snapshot + log semantics
|
|||
|
|
* Does **not** assume classical vs quantum
|
|||
|
|
* Makes caching, deduplication, and replay possible
|
|||
|
|
* Avoids over-specifying performance or layout
|
|||
|
|
|
|||
|
|
Think of this as **the membrane between semantics and mechanics**.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# ASL-STORE — Put/Get Contract (Normative)
|
|||
|
|
|
|||
|
|
## 1. Purpose
|
|||
|
|
|
|||
|
|
ASL-STORE defines the **operational contract** by which:
|
|||
|
|
|
|||
|
|
* Artifacts are **materialized and stored**
|
|||
|
|
* Artifact content becomes **visible** via the ASL-CORE-INDEX
|
|||
|
|
* Stored content is **retrieved deterministically**
|
|||
|
|
|
|||
|
|
ASL-STORE answers exactly two questions:
|
|||
|
|
|
|||
|
|
> **PUT**: How does an artifact become stored and indexed?
|
|||
|
|
> **GET**: How are bytes retrieved once indexed?
|
|||
|
|
|
|||
|
|
Nothing more.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. Scope
|
|||
|
|
|
|||
|
|
ASL-STORE defines:
|
|||
|
|
|
|||
|
|
* The **PUT lifecycle**
|
|||
|
|
* The **GET lifecycle**
|
|||
|
|
* Required interactions with:
|
|||
|
|
|
|||
|
|
* Content Index (ASL-CORE-INDEX)
|
|||
|
|
* Structural DAG
|
|||
|
|
* Materialization cache
|
|||
|
|
* Visibility and determinism rules
|
|||
|
|
|
|||
|
|
ASL-STORE does **not** define:
|
|||
|
|
|
|||
|
|
* Block allocation strategy
|
|||
|
|
* File layout
|
|||
|
|
* IO APIs
|
|||
|
|
* Concurrency primitives
|
|||
|
|
* Caching policies
|
|||
|
|
* Garbage collection
|
|||
|
|
* Replication mechanics
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Actors and Dependencies
|
|||
|
|
|
|||
|
|
ASL-STORE operates in the presence of:
|
|||
|
|
|
|||
|
|
* **Artifact DAG** (SID-addressed)
|
|||
|
|
* **Materialization Cache** (`SID → CID`, optional)
|
|||
|
|
* **Content Index** (`CID → ArtifactLocation`)
|
|||
|
|
* **Block Store** (opaque byte storage)
|
|||
|
|
* **Snapshot + Log** (for index visibility)
|
|||
|
|
|
|||
|
|
ASL-STORE **must not** bypass the Content Index.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. PUT Contract
|
|||
|
|
|
|||
|
|
### 4.1 PUT Signature (Semantic)
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
put(artifact) → (CID, IndexState)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Where:
|
|||
|
|
|
|||
|
|
* `artifact` is an ASL artifact (possibly lazy, possibly quantum)
|
|||
|
|
* `CID` is the semantic content identity
|
|||
|
|
* `IndexState = (SnapshotID, LogPosition)` after the put
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4.2 PUT Semantics (Step-by-step)
|
|||
|
|
|
|||
|
|
The following steps are **logically ordered**.
|
|||
|
|
An implementation may optimize, but may not violate the semantics.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
#### Step 1 — Structural registration (mandatory)
|
|||
|
|
|
|||
|
|
* The artifact **must** be registered in the Structural Index (SID → DAG).
|
|||
|
|
* If an identical SID already exists, it **must be reused**.
|
|||
|
|
|
|||
|
|
> This guarantees derivation identity independent of storage.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
#### Step 2 — CID resolution (lazy, cache-aware)
|
|||
|
|
|
|||
|
|
* If `(SID → CID)` exists in the Materialization Cache:
|
|||
|
|
|
|||
|
|
* Use it.
|
|||
|
|
* Otherwise:
|
|||
|
|
|
|||
|
|
* Materialize the artifact DAG
|
|||
|
|
* Compute the CID
|
|||
|
|
* Cache `(SID → CID)`
|
|||
|
|
|
|||
|
|
> Materialization may recursively invoke child artifacts.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
#### Step 3 — Deduplication check (mandatory)
|
|||
|
|
|
|||
|
|
* Lookup `CID` in the Content Index at CURRENT.
|
|||
|
|
* If an entry exists:
|
|||
|
|
|
|||
|
|
* **No bytes are written**
|
|||
|
|
* **No new index entry is required**
|
|||
|
|
* PUT completes successfully
|
|||
|
|
|
|||
|
|
> This is **global deduplication**.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
#### Step 4 — Physical storage (conditional)
|
|||
|
|
|
|||
|
|
If no existing entry exists:
|
|||
|
|
|
|||
|
|
* Bytes corresponding to `CID` **must be written** to a block
|
|||
|
|
* A concrete `ArtifactLocation` is produced:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
ArtifactLocation = Sequence[BlockSlice]
|
|||
|
|
|
|||
|
|
BlockSlice = (BlockID, offset, length)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
No assumptions are made about block layout.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
#### Step 5 — Index mutation (mandatory)
|
|||
|
|
|
|||
|
|
* Append a **PUT log entry** to the Content Index:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
CID → ArtifactLocation
|
|||
|
|
```
|
|||
|
|
* The entry is **not visible** until the log position is ≤ CURRENT.
|
|||
|
|
|
|||
|
|
> This is the *only* moment storage becomes visible.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4.3 PUT Guarantees
|
|||
|
|
|
|||
|
|
After successful PUT:
|
|||
|
|
|
|||
|
|
* The artifact’s CID:
|
|||
|
|
|
|||
|
|
* Is stable
|
|||
|
|
* Is retrievable
|
|||
|
|
* Will resolve to immutable bytes
|
|||
|
|
* The Content Index state:
|
|||
|
|
|
|||
|
|
* Advances monotonically
|
|||
|
|
* Is replayable
|
|||
|
|
* Repeating PUT with the same artifact:
|
|||
|
|
|
|||
|
|
* Is idempotent
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. GET Contract
|
|||
|
|
|
|||
|
|
### 5.1 GET Signature (Semantic)
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
get(CID, IndexState?) → bytes | NOT_FOUND
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Where:
|
|||
|
|
|
|||
|
|
* `CID` is the content identity
|
|||
|
|
* `IndexState` is optional:
|
|||
|
|
|
|||
|
|
* Defaults to CURRENT
|
|||
|
|
* May specify `(SnapshotID, LogPosition)`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5.2 GET Semantics
|
|||
|
|
|
|||
|
|
1. Resolve `CID → ArtifactLocation` using:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Index(snapshot, log_prefix)
|
|||
|
|
```
|
|||
|
|
2. If no entry exists:
|
|||
|
|
|
|||
|
|
* Return `NOT_FOUND`
|
|||
|
|
3. Otherwise:
|
|||
|
|
|
|||
|
|
* Read exactly `(length)` bytes from `(BlockID, offset)`
|
|||
|
|
* Return bytes **verbatim**
|
|||
|
|
|
|||
|
|
No interpretation is applied.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5.3 GET Guarantees
|
|||
|
|
|
|||
|
|
* Returned bytes are:
|
|||
|
|
|
|||
|
|
* Immutable
|
|||
|
|
* Deterministic
|
|||
|
|
* Content-addressed
|
|||
|
|
* GET never triggers materialization
|
|||
|
|
* GET never mutates state
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Visibility Rules
|
|||
|
|
|
|||
|
|
An index entry is visible **if and only if**:
|
|||
|
|
|
|||
|
|
1. The referenced block is sealed
|
|||
|
|
2. The log entry position ≤ CURRENT log position
|
|||
|
|
3. The snapshot + log prefix includes the entry
|
|||
|
|
|
|||
|
|
ASL-STORE must respect these rules strictly.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Failure Semantics (Minimal)
|
|||
|
|
|
|||
|
|
ASL-STORE must guarantee:
|
|||
|
|
|
|||
|
|
* No visible index entry points to missing or mutable bytes
|
|||
|
|
* Partial writes must not become visible
|
|||
|
|
* Replaying snapshot + log after crash yields a valid index
|
|||
|
|
|
|||
|
|
No stronger guarantees are required at this level.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. Determinism Contract
|
|||
|
|
|
|||
|
|
For fixed:
|
|||
|
|
|
|||
|
|
* SnapshotID
|
|||
|
|
* LogPosition
|
|||
|
|
* Artifact DAG
|
|||
|
|
* Hash algorithms
|
|||
|
|
|
|||
|
|
ASL-STORE guarantees:
|
|||
|
|
|
|||
|
|
* Same CID
|
|||
|
|
* Same ArtifactLocation resolution
|
|||
|
|
* Same GET results
|
|||
|
|
|
|||
|
|
This is the foundation for:
|
|||
|
|
|
|||
|
|
* Federation
|
|||
|
|
* Replication
|
|||
|
|
* Provenance
|
|||
|
|
* Certification
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. Relationship to q-bits (Explicit)
|
|||
|
|
|
|||
|
|
ASL-STORE:
|
|||
|
|
|
|||
|
|
* Is **agnostic** to q-bits
|
|||
|
|
* Sees only:
|
|||
|
|
|
|||
|
|
* CIDs
|
|||
|
|
* Bytes
|
|||
|
|
* Does not care how CIDs were derived
|
|||
|
|
|
|||
|
|
Quantum artifacts affect **materialization**, not storage semantics.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. Summary (Mental Model)
|
|||
|
|
|
|||
|
|
You can summarize ASL-STORE like this:
|
|||
|
|
|
|||
|
|
> **PUT** = “Make this artifact real, once, forever”
|
|||
|
|
> **GET** = “Given identity and time, give me the bytes”
|
|||
|
|
|
|||
|
|
Everything else is someone else’s problem — by design.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
If you want, next we can:
|
|||
|
|
|
|||
|
|
* define **crash consistency boundaries**
|
|||
|
|
* add **federated PUT/GET**
|
|||
|
|
* define **certificates binding DAG → CID → Snapshot**
|
|||
|
|
* show **how LLM outputs become artifacts**
|
|||
|
|
* or formalize **overlay indexes** (concepts, domains, ontologies)
|
|||
|
|
|
|||
|
|
This layer is now solid enough to build *anything* above it.
|
|||
|
|
|