246 lines
6.3 KiB
Markdown
246 lines
6.3 KiB
Markdown
|
# ASL-CORE-INDEX
|
|||
|
|
|
|||
|
|
### Semantic Addendum to ASL-CORE
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. Purpose
|
|||
|
|
|
|||
|
|
This document defines the **semantic model of the ASL index**, extending ASL-CORE artifact semantics to include **mapping artifacts to storage locations**.
|
|||
|
|
|
|||
|
|
The ASL index provides a **deterministic, snapshot-relative mapping** from artifact identities to byte locations within **immutable storage blocks**.
|
|||
|
|
|
|||
|
|
It specifies **what the index means**, not:
|
|||
|
|
|
|||
|
|
* How the index is stored or encoded
|
|||
|
|
* How blocks are allocated or packed
|
|||
|
|
* Performance optimizations
|
|||
|
|
* Garbage collection or memory strategies
|
|||
|
|
|
|||
|
|
Those are handled by:
|
|||
|
|
|
|||
|
|
* **ASL-STORE-INDEX** (store semantics and contracts)
|
|||
|
|
* **ENC-ASL-CORE-INDEX** (bytes-on-disk encoding)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. Scope
|
|||
|
|
|
|||
|
|
This document defines:
|
|||
|
|
|
|||
|
|
* Logical structure of index entries
|
|||
|
|
* Visibility rules
|
|||
|
|
* Snapshot and log interaction
|
|||
|
|
* Immutability and shadowing semantics
|
|||
|
|
* Determinism guarantees
|
|||
|
|
* Required invariants
|
|||
|
|
|
|||
|
|
It does **not** define:
|
|||
|
|
|
|||
|
|
* On-disk formats
|
|||
|
|
* Index segmentation or sharding
|
|||
|
|
* Bloom filters or probabilistic structures
|
|||
|
|
* Memory residency
|
|||
|
|
* Performance targets
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Terminology
|
|||
|
|
|
|||
|
|
* **Artifact**: An immutable sequence of bytes managed by ASL.
|
|||
|
|
* **ArtifactKey**: Opaque identifier for an artifact (typically a hash).
|
|||
|
|
* **Block**: Immutable storage unit containing artifact bytes.
|
|||
|
|
* **BlockID**: Opaque, unique identifier for a block.
|
|||
|
|
* **ArtifactLocation**: Tuple `(BlockID, offset, length)` identifying bytes within a block.
|
|||
|
|
* **Snapshot**: Checkpoint capturing a consistent base state of ASL-managed storage and metadata.
|
|||
|
|
* **Append-Only Log**: Strictly ordered log of index-visible mutations occurring after a snapshot.
|
|||
|
|
* **CURRENT**: The effective system state obtained by replaying the append-only log on top of a checkpoint snapshot.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Block Semantics
|
|||
|
|
|
|||
|
|
ASL-CORE introduces **blocks** minimally:
|
|||
|
|
|
|||
|
|
1. Blocks are **existential storage atoms** for artifact bytes.
|
|||
|
|
2. Each block is uniquely identified by a **BlockID**.
|
|||
|
|
3. Blocks are **immutable once sealed**.
|
|||
|
|
4. Addressing: `(BlockID, offset, length) → bytes`.
|
|||
|
|
5. No block layout, allocation, packing, or size semantics are defined at the core level.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Core Semantic Mapping
|
|||
|
|
|
|||
|
|
The ASL index defines a **total mapping**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
ArtifactKey → ArtifactLocation
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Semantic guarantees:
|
|||
|
|
|
|||
|
|
* Each visible `ArtifactKey` maps to exactly one `ArtifactLocation`.
|
|||
|
|
* Mapping is **immutable once visible**.
|
|||
|
|
* Mapping is **snapshot-relative**.
|
|||
|
|
* Mapping is **deterministic** given `(snapshot, log prefix)`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. ArtifactLocation Semantics
|
|||
|
|
|
|||
|
|
* `block_id` references an ASL block.
|
|||
|
|
* `offset` and `length` define bytes within the block.
|
|||
|
|
* Only valid for the lifetime of the referenced block.
|
|||
|
|
* No interpretation of bytes is implied.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Visibility Model
|
|||
|
|
|
|||
|
|
An index entry is **visible** if and only if:
|
|||
|
|
|
|||
|
|
1. The referenced block is sealed.
|
|||
|
|
2. A corresponding log record exists.
|
|||
|
|
3. The log record is ≤ CURRENT replay position.
|
|||
|
|
|
|||
|
|
**Consequences**:
|
|||
|
|
|
|||
|
|
* Entries referencing unsealed blocks are invisible.
|
|||
|
|
* Entries above CURRENT are invisible.
|
|||
|
|
* Visibility is binary (no gradual exposure).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. Snapshot and Log Semantics
|
|||
|
|
|
|||
|
|
* Snapshots act as **checkpoints**, not full state representations.
|
|||
|
|
* Index state at any time:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Index(CURRENT) = Index(snapshot) + replay(log)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
* Replay is strictly ordered, deterministic, and idempotent.
|
|||
|
|
* Snapshot and log entries are semantically equivalent once replayed.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. Immutability and Shadowing
|
|||
|
|
|
|||
|
|
### 9.1 Immutability
|
|||
|
|
|
|||
|
|
* Index entries are never mutated.
|
|||
|
|
* Once visible, an entry’s meaning never changes.
|
|||
|
|
* Blocks referenced by entries are immutable.
|
|||
|
|
|
|||
|
|
### 9.2 Shadowing
|
|||
|
|
|
|||
|
|
* Later entries may shadow earlier entries with the same `ArtifactKey`.
|
|||
|
|
* Precedence is determined by log order.
|
|||
|
|
* Snapshot boundaries do not alter shadowing semantics.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. Tombstones (Optional)
|
|||
|
|
|
|||
|
|
* Tombstone entries are allowed to invalidate prior mappings.
|
|||
|
|
* Semantics:
|
|||
|
|
|
|||
|
|
* Shadows previous entries for the same `ArtifactKey`.
|
|||
|
|
* Visibility follows the same rules as regular entries.
|
|||
|
|
* Existence and encoding of tombstones are optional.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. Determinism Guarantees
|
|||
|
|
|
|||
|
|
For fixed:
|
|||
|
|
|
|||
|
|
* Snapshot
|
|||
|
|
* Log prefix
|
|||
|
|
* ASL configuration
|
|||
|
|
* Hash algorithm
|
|||
|
|
|
|||
|
|
The index guarantees:
|
|||
|
|
|
|||
|
|
* Deterministic lookup results
|
|||
|
|
* Deterministic shadowing resolution
|
|||
|
|
* Deterministic visibility
|
|||
|
|
|
|||
|
|
No nondeterministic input may influence index semantics.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12. Separation of Concerns
|
|||
|
|
|
|||
|
|
* **ASL-CORE**: Defines artifact semantics and the existence of blocks as storage atoms.
|
|||
|
|
* **ASL-CORE-INDEX**: Defines how artifact keys map to blocks, offsets, and lengths.
|
|||
|
|
* **ASL-STORE-INDEX**: Defines lifecycle, replay, and visibility guarantees.
|
|||
|
|
* **ENC-ASL-CORE-INDEX**: Defines exact bytes-on-disk representation.
|
|||
|
|
|
|||
|
|
Index semantics **do not** prescribe:
|
|||
|
|
|
|||
|
|
* Block allocation
|
|||
|
|
* Packing strategies
|
|||
|
|
* Performance optimizations
|
|||
|
|
* Memory residency or caching
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 13. Normative Invariants
|
|||
|
|
|
|||
|
|
All conforming implementations must enforce:
|
|||
|
|
|
|||
|
|
1. No visibility without a log record.
|
|||
|
|
2. No mutation of visible index entries.
|
|||
|
|
3. No mutation of sealed blocks.
|
|||
|
|
4. Shadowing follows strict log order.
|
|||
|
|
5. Replay of snapshot + log uniquely defines CURRENT.
|
|||
|
|
6. ArtifactLocation always resolves to immutable bytes.
|
|||
|
|
|
|||
|
|
Violation of any invariant constitutes index corruption.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 14. Non-Goals (Explicit)
|
|||
|
|
|
|||
|
|
ASL-CORE-INDEX does **not** define:
|
|||
|
|
|
|||
|
|
* Disk layout or encoding
|
|||
|
|
* Segment structure, sharding, or bloom filters
|
|||
|
|
* GC policies or memory management
|
|||
|
|
* Small vs. large block packing
|
|||
|
|
* Federation or provenance mechanics
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 15. Relationship to Other Specifications
|
|||
|
|
|
|||
|
|
| Layer | Responsibility |
|
|||
|
|
| ------------------ | ---------------------------------------------------------- |
|
|||
|
|
| ASL-CORE | Defines artifact semantics and existence of blocks |
|
|||
|
|
| ASL-CORE-INDEX | Defines semantic mapping of ArtifactKey → ArtifactLocation |
|
|||
|
|
| ASL-STORE-INDEX | Defines store contracts to realize index semantics |
|
|||
|
|
| ENC-ASL-CORE-INDEX | Defines exact encoding on disk |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 16. Summary
|
|||
|
|
|
|||
|
|
The ASL index:
|
|||
|
|
|
|||
|
|
* Maps artifact identities to block locations deterministically
|
|||
|
|
* Is immutable once entries are visible
|
|||
|
|
* Resolves visibility via snapshots + append-only log
|
|||
|
|
* Supports optional tombstones
|
|||
|
|
* Provides a stable substrate for store, encoding, and higher layers like PEL
|
|||
|
|
|
|||
|
|
It answers **exactly one question**:
|
|||
|
|
|
|||
|
|
> *Given an artifact identity and a point in time, where are the bytes?*
|
|||
|
|
|
|||
|
|
Nothing more, nothing less.
|
|||
|
|
|
|||
|
|
|