niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat-api/tier1/asl-indexes-1.md
Carl Niklas Rydberg fabace7616 Reorganize notes into tier1/ops docs
2026-01-17 10:33:23 +01:00

2.3 KiB
Raw Blame History

ASL/INDEXES/1 -- Index Taxonomy and Relationships

Status: Draft Owner: Architecture Version: 0.1.0 SoT: No Last Updated: 2025-01-17 Tags: [indexes, content, structural, materialization]

Document ID: ASL/INDEXES/1 Layer: L2 -- Index taxonomy (no encoding)

Depends on (normative):

  • ASL/1-CORE-INDEX
  • ASL-STORE-INDEX

Informative references:

  • ASL/SYSTEM/1
  • TGK/1

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