319 lines
6.8 KiB
Markdown
319 lines
6.8 KiB
Markdown
# ASL/LOG/1 — Append-Only Semantic Log
|
|
|
|
Status: Draft
|
|
Owner: Niklas Rydberg
|
|
Version: 0.1.0
|
|
SoT: No
|
|
Last Updated: 2025-11-16
|
|
Linked Phase Pack: N/A
|
|
Tags: [deterministic, log, snapshot]
|
|
|
|
<!-- Source: /amduat-api/tier1/asl-log-1.md | Canonical: /amduat/tier1/asl-log-1.md -->
|
|
|
|
**Document ID:** `ASL/LOG/1`
|
|
**Layer:** L1 — Domain log semantics (no transport)
|
|
|
|
**Depends on (normative):**
|
|
|
|
* `ASL/STORE-INDEX/1` — store lifecycle and replay contracts (pending spec)
|
|
|
|
**Informative references:**
|
|
|
|
* `ASL/1-CORE-INDEX` — index semantics
|
|
* `TGK/1` — TGK edge visibility and traversal alignment
|
|
* `ENC/ASL-LOG/1` — bytes-on-disk encoding profile
|
|
* `ENC/ASL-CORE-INDEX/1` — index segment encoding
|
|
* `ASL/SYSTEM/1` — unified system view (PEL/TGK/federation alignment)
|
|
|
|
© 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/LOG/1 defines **semantic log behavior**. It does not define transport, replication protocols, or storage layout.
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
ASL/LOG/1 defines the **authoritative, append-only log** for an ASL domain.
|
|
|
|
The log records **semantic commits** that affect:
|
|
|
|
* Index segment visibility
|
|
* Tombstone policy
|
|
* Snapshot anchoring
|
|
* Optional publication metadata
|
|
|
|
The log is the **sole source of truth** for reconstructing CURRENT state.
|
|
|
|
---
|
|
|
|
## 2. Core Properties (Normative)
|
|
|
|
An ASL log MUST be:
|
|
|
|
1. Append-only
|
|
2. Strictly ordered
|
|
3. Deterministically replayable
|
|
4. Hash-chained
|
|
5. Snapshot-anchorable
|
|
6. Binary encoded per `ENC-ASL-LOG`
|
|
7. Forward-compatible
|
|
|
|
---
|
|
|
|
## 3. Log Model
|
|
|
|
### 3.1 Log Sequence
|
|
|
|
Each record has a monotonically increasing `logseq`:
|
|
|
|
```
|
|
logseq: uint64
|
|
```
|
|
|
|
* Assigned by the domain authority
|
|
* Total order within a domain
|
|
* Never reused
|
|
|
|
### 3.2 Hash Chain
|
|
|
|
Each record commits to the previous record:
|
|
|
|
```
|
|
record_hash = H(prev_record_hash || logseq || record_type || payload_len || payload)
|
|
```
|
|
|
|
This enables tamper detection, witness signing, and federation verification.
|
|
|
|
### 3.3 Record Envelope
|
|
|
|
All log records share a common envelope whose **exact byte layout** is defined
|
|
in `ENC-ASL-LOG`. The envelope MUST include:
|
|
|
|
* `logseq` (monotonic sequence number)
|
|
* `record_type` (type tag)
|
|
* `payload_len` (bytes)
|
|
* `payload` (type-specific bytes)
|
|
* `record_hash` (hash-chained integrity)
|
|
|
|
---
|
|
|
|
## 4. Record Types (Normative)
|
|
|
|
## 4.0 Common Payload Encoding (Informative)
|
|
|
|
The byte-level payload schemas are defined in `ENC-ASL-LOG`. The shared
|
|
artifact reference encoding is:
|
|
|
|
```c
|
|
typedef struct {
|
|
uint32_t hash_id;
|
|
uint16_t digest_len;
|
|
uint16_t reserved0; // must be 0
|
|
uint8_t digest[digest_len];
|
|
} ArtifactRef;
|
|
```
|
|
|
|
### 4.1 SEGMENT_SEAL
|
|
|
|
Declares an index segment visible.
|
|
|
|
Payload (encoding):
|
|
|
|
```c
|
|
typedef struct {
|
|
uint64_t segment_id;
|
|
uint8_t segment_hash[32];
|
|
} SegmentSealPayload;
|
|
```
|
|
|
|
Semantics:
|
|
|
|
* From this `logseq` onward, the referenced segment is visible for lookup and replay.
|
|
* Segment MUST be immutable.
|
|
* All referenced blocks MUST already be sealed.
|
|
* Segment contents are not re-logged.
|
|
|
|
### 4.2 TOMBSTONE
|
|
|
|
Declares an artifact inadmissible under domain policy.
|
|
|
|
Payload (encoding):
|
|
|
|
```c
|
|
typedef struct {
|
|
ArtifactRef artifact;
|
|
uint32_t scope;
|
|
uint32_t reason_code;
|
|
} TombstonePayload;
|
|
```
|
|
|
|
Semantics:
|
|
|
|
* Does not delete data.
|
|
* Shadows prior visibility.
|
|
* Applies from this logseq onward.
|
|
* `scope` and `reason_code` are opaque to ASL/LOG/1 and MUST NOT affect
|
|
shadowing or replay order; they are preserved for policy/diagnostic layers.
|
|
|
|
### 4.3 TOMBSTONE_LIFT
|
|
|
|
Supersedes a previous tombstone.
|
|
|
|
Payload (encoding):
|
|
|
|
```c
|
|
typedef struct {
|
|
ArtifactRef artifact;
|
|
uint64_t tombstone_logseq;
|
|
} TombstoneLiftPayload;
|
|
```
|
|
|
|
Semantics:
|
|
|
|
* References an earlier TOMBSTONE.
|
|
* Does not erase history.
|
|
* Only affects CURRENT at or above this logseq.
|
|
* A lift cancels only the referenced tombstone record for the same artifact;
|
|
other tombstones for the artifact remain effective unless separately lifted.
|
|
|
|
### 4.4 SNAPSHOT_ANCHOR
|
|
|
|
Binds semantic state to a snapshot.
|
|
|
|
Payload (encoding):
|
|
|
|
```c
|
|
typedef struct {
|
|
uint64_t snapshot_id;
|
|
uint8_t root_hash[32];
|
|
} SnapshotAnchorPayload;
|
|
```
|
|
|
|
Semantics:
|
|
|
|
* Defines a replay checkpoint.
|
|
* Enables log truncation below anchor with care.
|
|
|
|
### 4.5 ARTIFACT_PUBLISH (Optional)
|
|
|
|
Marks an artifact as published.
|
|
|
|
Payload (encoding):
|
|
|
|
```c
|
|
typedef struct {
|
|
ArtifactRef artifact;
|
|
} ArtifactPublishPayload;
|
|
```
|
|
|
|
Semantics:
|
|
|
|
* Publication is domain-local.
|
|
* Federation layers may interpret this metadata.
|
|
|
|
### 4.6 ARTIFACT_UNPUBLISH (Optional)
|
|
|
|
Withdraws publication.
|
|
|
|
Payload (encoding):
|
|
|
|
```c
|
|
typedef struct {
|
|
ArtifactRef artifact;
|
|
} ArtifactUnpublishPayload;
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Replay Semantics (Normative)
|
|
|
|
To reconstruct CURRENT:
|
|
|
|
1. Load latest snapshot anchor (if any).
|
|
2. Initialize visible segments from that snapshot.
|
|
3. Replay all log records with `logseq > snapshot.logseq`.
|
|
4. Apply records in order:
|
|
|
|
* SEGMENT_SEAL -> add segment
|
|
* TOMBSTONE -> update policy state
|
|
* TOMBSTONE_LIFT -> override policy
|
|
* PUBLISH/UNPUBLISH -> update visibility metadata
|
|
|
|
Replay MUST be deterministic.
|
|
|
|
---
|
|
|
|
## 6. Index Interaction
|
|
|
|
* Index segments contain index entries.
|
|
* The log never records individual index entries.
|
|
* Visibility is controlled solely by SEGMENT_SEAL.
|
|
* Index rebuild = scan visible segments + apply policy.
|
|
|
|
---
|
|
|
|
## 7. Garbage Collection Constraints
|
|
|
|
* A segment may be GC'd only if:
|
|
|
|
* No snapshot references it.
|
|
* No log replay <= CURRENT requires it.
|
|
|
|
* Log truncation is only safe at SNAPSHOT_ANCHOR boundaries.
|
|
|
|
---
|
|
|
|
## 8. Versioning & Extensibility
|
|
|
|
* Unknown record types MUST be skipped and MUST NOT break replay.
|
|
* Payloads are opaque outside their type.
|
|
* New record types may be added in later versions.
|
|
|
|
---
|
|
|
|
## 9. Non-Goals
|
|
|
|
ASL/LOG/1 does not define:
|
|
|
|
* Federation protocols
|
|
* Network replication
|
|
* Witness signatures
|
|
* Block-level events
|
|
* Hydration / eviction
|
|
* Execution receipts
|
|
|
|
---
|
|
|
|
## 10. Invariant (Informative)
|
|
|
|
> If it affects visibility, admissibility, or authority, it goes in the log.
|
|
> If it affects layout or performance, it does not.
|
|
|
|
---
|
|
|
|
## 10. Summary
|
|
|
|
ASL/LOG/1 defines the minimal semantic log needed to reconstruct CURRENT.
|
|
|
|
If it affects visibility or admissibility, it goes in the log. If it affects layout or performance, it does not.
|