319 lines
5.7 KiB
Markdown
319 lines
5.7 KiB
Markdown
Great, this is the right moment to freeze something *small, sharp, and survivable*.
|
||
|
||
Below is a **clean, minimal, boring-on-purpose** definition of a **Start Log Language v0.1** that:
|
||
|
||
* Matches ASL-STORE-INDEX precisely
|
||
* Keeps one authoritative log
|
||
* Avoids over-specifying future policy / federation
|
||
* Is stable enough to build against now
|
||
* Leaves room for evolution without breakage
|
||
|
||
I’ll call it **ASL-LOG v0.1**.
|
||
|
||
---
|
||
|
||
# ASL-LOG v0.1
|
||
|
||
**Append-Only Semantic Log for ASL Domains**
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
ASL-LOG defines the **authoritative, append-only log** for an ASL domain.
|
||
|
||
The log records **semantic commits** that affect:
|
||
|
||
* Artifact visibility
|
||
* Index segment visibility
|
||
* Policy (e.g. tombstones)
|
||
* Authority state
|
||
* Snapshot anchoring
|
||
|
||
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**
|
||
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 || record_type || payload)
|
||
```
|
||
|
||
This enables:
|
||
|
||
* Tamper detection
|
||
* Witness signing
|
||
* Federation verification
|
||
|
||
---
|
||
|
||
## 4. Record Envelope (v0.1)
|
||
|
||
All log records share a common envelope.
|
||
|
||
```c
|
||
struct asl_log_record_v1 {
|
||
uint64_t logseq;
|
||
uint32_t record_type;
|
||
uint32_t payload_len;
|
||
uint8_t payload[payload_len];
|
||
uint8_t record_hash[32]; // e.g. SHA-256
|
||
};
|
||
```
|
||
|
||
Notes:
|
||
|
||
* Encoding is little-endian
|
||
* `record_hash` hashes the full record except itself
|
||
* Hash algorithm is fixed for v0.1
|
||
|
||
---
|
||
|
||
## 5. Record Types (v0.1)
|
||
|
||
### 5.1 SEGMENT_SEAL (Type = 0x01)
|
||
|
||
**The most important record in v0.1**
|
||
|
||
Declares an index segment visible.
|
||
|
||
```c
|
||
struct segment_seal_v1 {
|
||
uint64_t segment_id;
|
||
uint8_t segment_hash[32];
|
||
};
|
||
```
|
||
|
||
Semantics:
|
||
|
||
> From this `logseq` onward, the referenced index segment is visible
|
||
> for lookup and replay.
|
||
|
||
Rules:
|
||
|
||
* Segment must be immutable
|
||
* All referenced blocks must already be sealed
|
||
* Segment contents are not re-logged
|
||
|
||
---
|
||
|
||
### 5.2 ARTIFACT_PUBLISH (Type = 0x02) (Optional v0.1)
|
||
|
||
Marks an artifact as published.
|
||
|
||
```c
|
||
struct artifact_publish_v1 {
|
||
uint64_t artifact_key;
|
||
};
|
||
```
|
||
|
||
Semantics:
|
||
|
||
* Publication is domain-local
|
||
* Federation layers may interpret this
|
||
|
||
---
|
||
|
||
### 5.3 ARTIFACT_UNPUBLISH (Type = 0x03) (Optional v0.1)
|
||
|
||
Withdraws publication.
|
||
|
||
```c
|
||
struct artifact_unpublish_v1 {
|
||
uint64_t artifact_key;
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
### 5.4 TOMBSTONE (Type = 0x10)
|
||
|
||
Declares an artifact inadmissible under domain policy.
|
||
|
||
```c
|
||
struct tombstone_v1 {
|
||
uint64_t artifact_key;
|
||
uint32_t scope; // e.g. EXECUTION, INDEX, PUBLICATION
|
||
uint32_t reason_code; // opaque to ASL-LOG
|
||
};
|
||
```
|
||
|
||
Semantics:
|
||
|
||
* Does not delete data
|
||
* Shadows prior visibility
|
||
* Applies from this logseq onward
|
||
|
||
---
|
||
|
||
### 5.5 TOMBSTONE_LIFT (Type = 0x11)
|
||
|
||
Supersedes a previous tombstone.
|
||
|
||
```c
|
||
struct tombstone_lift_v1 {
|
||
uint64_t artifact_key;
|
||
uint64_t tombstone_logseq;
|
||
};
|
||
```
|
||
|
||
Rules:
|
||
|
||
* Must reference an earlier TOMBSTONE
|
||
* Does not erase history
|
||
* Only affects CURRENT ≥ this logseq
|
||
|
||
---
|
||
|
||
### 5.6 SNAPSHOT_ANCHOR (Type = 0x20)
|
||
|
||
Binds semantic state to a filesystem snapshot.
|
||
|
||
```c
|
||
struct snapshot_anchor_v1 {
|
||
uint64_t snapshot_id;
|
||
uint8_t root_hash[32]; // hash of snapshot-visible state
|
||
};
|
||
```
|
||
|
||
Semantics:
|
||
|
||
* Defines a replay checkpoint
|
||
* Enables log truncation below anchor (with care)
|
||
|
||
---
|
||
|
||
### 5.7 DOMAIN_AUTH_UPDATE (Type = 0x30) (Optional v0.1)
|
||
|
||
Updates trusted domain authorities.
|
||
|
||
```c
|
||
struct domain_auth_update_v1 {
|
||
uint8_t cert_hash[32];
|
||
uint32_t action; // ADD or REVOKE
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Replay Semantics (Normative)
|
||
|
||
To reconstruct CURRENT:
|
||
|
||
1. Load latest snapshot anchor (if any)
|
||
2. Initialize visible segments from 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 → update visibility metadata
|
||
|
||
Replay **must be deterministic**.
|
||
|
||
---
|
||
|
||
## 7. 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
|
||
|
||
---
|
||
|
||
## 8. 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
|
||
|
||
---
|
||
|
||
## 9. Versioning & Extensibility
|
||
|
||
* Unknown `record_type`:
|
||
|
||
* Must be skipped
|
||
* Must not break replay
|
||
* Payloads are opaque outside their type
|
||
* v0.1 fixes:
|
||
|
||
* Hash algorithm
|
||
* Endianness
|
||
* Core record types
|
||
|
||
Future versions may:
|
||
|
||
* Add new record types
|
||
* Add optional fields (new struct versions)
|
||
* Introduce compression or batching
|
||
|
||
---
|
||
|
||
## 10. What v0.1 Deliberately Does *Not* Include
|
||
|
||
* Federation protocols
|
||
* Network replication
|
||
* Witness signatures
|
||
* Block-level events
|
||
* Hydration / eviction
|
||
* Execution receipts (PERs)
|
||
|
||
Those live *above* ASL-LOG.
|
||
|
||
---
|
||
|
||
## 11. One-sentence invariant (keep this)
|
||
|
||
> **If it affects visibility, admissibility, or authority, it goes in the log.
|
||
> If it affects layout or performance, it does not.**
|
||
|
||
---
|
||
|
||
If you want next steps, the natural continuations are:
|
||
|
||
* **ASL-LOG test vectors**
|
||
* **Minimal C writer/reader API**
|
||
* **Formal CURRENT reconstruction pseudocode**
|
||
* **Mapping ASL-LOG → federation streams**
|
||
|
||
But v0.1 as written is *enough to build real systems against* without regret.
|
||
|