140 lines
3.1 KiB
Markdown
140 lines
3.1 KiB
Markdown
|
# ASL/INDEXES/1 -- Index Taxonomy and Relationships
|
||
|
|
|
||
|
|
Status: Draft
|
||
|
|
Owner: Architecture
|
||
|
|
Version: 0.1.0
|
||
|
|
SoT: No
|
||
|
|
Last Updated: 2025-01-17
|
||
|
|
Linked Phase Pack: N/A
|
||
|
|
Tags: [indexes, content, structural, materialization]
|
||
|
|
|
||
|
|
<!-- Source: /amduat-api/tier1/asl-indexes-1.md | Canonical: /amduat/tier1/asl-indexes-1.md -->
|
||
|
|
|
||
|
|
**Document ID:** `ASL/INDEXES/1`
|
||
|
|
**Layer:** L2 -- Index taxonomy (no encoding)
|
||
|
|
|
||
|
|
**Depends on (normative):**
|
||
|
|
|
||
|
|
* `ASL/1-CORE-INDEX`
|
||
|
|
* `ASL/STORE-INDEX/1`
|
||
|
|
|
||
|
|
**Informative references:**
|
||
|
|
|
||
|
|
* `ASL/SYSTEM/1`
|
||
|
|
* `TGK/1`
|
||
|
|
* `ENC/ASL-CORE-INDEX/1`
|
||
|
|
|
||
|
|
© 2025 Niklas Rydberg.
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
Except where otherwise noted, this document (text and diagrams) is licensed under
|
||
|
|
the Creative Commons Attribution 4.0 International License (CC BY 4.0).
|
||
|
|
|
||
|
|
The identifier registries and mapping tables (e.g. TypeTag IDs, HashId
|
||
|
|
assignments, EdgeTypeId tables) are additionally made available under CC0 1.0
|
||
|
|
Universal (CC0) to enable unrestricted reuse in implementations and derivative
|
||
|
|
specifications.
|
||
|
|
|
||
|
|
Code examples in this document are provided under the Apache License 2.0 unless
|
||
|
|
explicitly stated otherwise. Test vectors, where present, are dedicated to the
|
||
|
|
public domain under CC0 1.0.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 0. Conventions
|
||
|
|
|
||
|
|
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
|
||
|
|
|
||
|
|
ASL/INDEXES/1 defines index roles and relationships. It does not define encodings or storage layouts.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
|
||
|
|
This document defines the minimal set of indexes used by ASL systems and their dependency relationships.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Index Taxonomy (Normative)
|
||
|
|
|
||
|
|
ASL systems use three distinct indexes:
|
||
|
|
|
||
|
|
### 2.1 Content Index
|
||
|
|
|
||
|
|
Purpose: map semantic identity to bytes.
|
||
|
|
|
||
|
|
```
|
||
|
|
ArtifactKey -> ArtifactLocation
|
||
|
|
```
|
||
|
|
|
||
|
|
Properties:
|
||
|
|
|
||
|
|
* Snapshot-relative and append-only
|
||
|
|
* Deterministic replay
|
||
|
|
* Optional tombstone shadowing
|
||
|
|
|
||
|
|
This is the ASL/1-CORE-INDEX and is the only index that governs visibility.
|
||
|
|
|
||
|
|
### 2.2 Structural Index
|
||
|
|
|
||
|
|
Purpose: map structural identity to a derivation DAG node.
|
||
|
|
|
||
|
|
```
|
||
|
|
SID -> DAG node
|
||
|
|
```
|
||
|
|
|
||
|
|
Properties:
|
||
|
|
|
||
|
|
* Deterministic and rebuildable
|
||
|
|
* Does not imply materialization
|
||
|
|
* May be in-memory or persisted
|
||
|
|
|
||
|
|
### 2.3 Materialization Cache
|
||
|
|
|
||
|
|
Purpose: record previously materialized content for a structural identity.
|
||
|
|
|
||
|
|
```
|
||
|
|
SID -> ArtifactKey
|
||
|
|
```
|
||
|
|
|
||
|
|
Properties:
|
||
|
|
|
||
|
|
* Redundant and safe to drop
|
||
|
|
* Recomputable from DAG + content index
|
||
|
|
* Pure performance optimization
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. Dependency Rules (Normative)
|
||
|
|
|
||
|
|
Dependencies MUST follow this direction:
|
||
|
|
|
||
|
|
```
|
||
|
|
Structural Index -> Materialization Cache -> Content Index
|
||
|
|
```
|
||
|
|
|
||
|
|
Rules:
|
||
|
|
|
||
|
|
* The Content Index MUST NOT depend on the Structural Index.
|
||
|
|
* The Structural Index MUST NOT depend on stored bytes.
|
||
|
|
* The Materialization Cache MAY depend on both.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. PUT/GET Interaction (Informative)
|
||
|
|
|
||
|
|
* PUT registers structure (if used), resolves to an ArtifactKey, and updates the Content Index.
|
||
|
|
* GET consults only the Content Index and reads bytes from the store.
|
||
|
|
* The Structural Index and Materialization Cache are optional optimizations for PUT.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. Non-Goals
|
||
|
|
|
||
|
|
ASL/INDEXES/1 does not define:
|
||
|
|
|
||
|
|
* Encodings for any index
|
||
|
|
* Storage layout or sharding
|
||
|
|
* Query operators or traversal semantics
|