niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Add federation and trust/policy tier1 specs

Browse source
This commit is contained in:
Carl Niklas Rydberg 2026-01-17 08:52:02 +01:00
parent d8b30f268d
commit a5537e13d3
11 changed files with 1375 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
tier1/asl-dam-1.md Normal file
View file

@ -0,0 +1,112 @@
# ASL/DAM/1 -- Domain Authority Manifest
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [authority, trust, policy, domains]
**Document ID:** `ASL/DAM/1`
**Layer:** L2 -- Authority semantics (no encoding)
**Depends on (normative):**
* `ASL/POLICY-HASH/1`
**Informative references:**
* `ASL/OCS/1` -- offline certificate system
* `ASL/OFFLINE-ROOT-TRUST/1` -- offline root policy
* `PER/SIGNATURE/1` -- PER signature verification
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/DAM/1 defines the **logical structure and semantics** of the Domain Authority Manifest. It does not define an encoding.
---
## 1. Purpose
The Domain Authority Manifest (DAM) defines **who may assert authority** on behalf of a domain.
It binds domain identity to principals, roles, and a policy hash.
---
## 2. Core Concepts
* **Principal**: a cryptographic public key
* **Role**: capability granted to a principal
* **Policy hash**: canonical hash binding policy constraints to a domain
---
## 3. Roles (Minimal Set)
| Role | Capability |
| ---------- | ---------- |
| produce | Create internal artifacts |
| execute | Emit PERs |
| publish | Publish artifacts/snapshots |
| federate | Export published state |
| audit | Verify only, no mutations |
Roles are **capabilities**, not identities.
---
## 4. Logical Schema
```text
DomainAuthorityManifest {
domain_id : DomainID
version : u32
root_key : PublicKey
principals[] : PrincipalEntry
policy_hash : Hash
}
PrincipalEntry {
principal_id : Hash
public_key : PublicKey
roles[] : Role
}
```
The DAM is immutable once published. Rotation is performed by publishing a new DAM.
---
## 5. Validation Rules (Normative)
A node MUST reject any action unless:
1. The DAM artifact is visible in the relevant snapshot.
2. The DAM hash matches the snapshot reference (if recorded).
3. The action is signed by a principal listed in the DAM.
4. The principal has the required role.
5. The DAM `root_key` is certified by the offline root trust chain.
---
## 6. Policy Binding
The DAM `policy_hash` binds the domain to a specific policy document. If policy changes, a new DAM MUST be published and referenced by new snapshots.
---
## 7. Non-Goals
* Encoding format
* Key rotation workflow
* Live revocation
---
## 8. Summary
ASL/DAM/1 defines the minimal authority document for a domain, binding principals and roles to a policy hash under an offline root trust chain.

138
tier1/asl-dap-1.md Normal file
View file

@ -0,0 +1,138 @@
# ASL/DAP/1 -- Domain Admission Protocol
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [admission, trust, federation]
**Document ID:** `ASL/DAP/1`
**Layer:** L2 -- Admission semantics (no transport)
**Depends on (normative):**
* `ASL/DAM/1`
* `ASL/POLICY-HASH/1`
**Informative references:**
* `ASL/OCS/1` -- offline certificate system
* `ASL/OFFLINE-ROOT-TRUST/1`
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/DAP/1 defines **admission semantics** for recognizing external domains. It does not define transport.
---
## 1. Purpose
The Domain Admission Protocol defines how a receiving domain evaluates and admits an applicant domain before any federation or trust is granted.
---
## 2. Actors
| Actor | Role |
| ----- | ---- |
| Applicant Domain | Domain requesting admission |
| Receiving Domain | Domain evaluating admission |
| Operator | Optional human/policy agent |
---
## 3. Admission Object Model
An admission request MUST include:
* Domain Authority Manifest (DAM)
* Proof of possession of the DAM root key
* Requested admission scope
* Optional courtesy lease request
No artifacts, blocks, or logs are required for admission.
---
## 4. Admission Flow (Normative)
1. **Submission**
* Applicant sends DAM and proof of root-key possession.
2. **Structural validation**
* Receiving domain verifies DAM schema and signature.
* Policy hash integrity MUST be verified.
3. **Policy compatibility**
* Receiving domain evaluates requested scope and policy alignment.
4. **Decision**
* Outcomes: ACCEPTED, ACCEPTED_LIMITED, DEFERRED, REJECTED.
---
## 5. Admission Guarantees
If accepted:
* DomainID is recognized by the receiving domain.
* Root key and policy hash are pinned.
* Admission scope is enforced for federation.
Admission does not imply trust in artifacts beyond the granted scope.
---
## 6. Courtesy Lease (Optional)
A courtesy lease is a **bounded, revocable grant of resources** without semantic trust.
```text
CourtesyLease {
lease_id
domain_id
granted_by_domain
resources: {
storage_bytes
block_count
snapshot_count
}
duration: {
start_time
end_time
}
constraints: {
encrypted_only: boolean
no_federation: boolean
no_public_indexing: boolean
}
}
```
Courtesy storage MAY be deleted upon lease expiry. Courtesy does not grant federation or publication rights.
---
## 7. Non-Goals
* Transport format
* PKI integration
* Live revocation or liveness checks
---
## 8. Summary
ASL/DAP/1 defines a deterministic admission process for domains, with optional courtesy leasing for rescue and bootstrap scenarios.

165
tier1/asl-federation-1.md Normal file
View file

@ -0,0 +1,165 @@
# ASL/FEDERATION/1 -- Core Federation Semantics
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [federation, domains, visibility, determinism]
**Document ID:** `ASL/FEDERATION/1`
**Layer:** L2 -- Federation semantics (no transport, no encodings)
**Depends on (normative):**
* `ASL/1-CORE`
* `ASL/1-CORE-INDEX`
* `ASL/LOG/1`
* `ASL-STORE-INDEX`
**Informative references:**
* `ENC-ASL-CORE-INDEX` -- domain/visibility fields (`tier1/enc-asl-core-index.md`)
* `ASL/SYSTEM/1` -- unified system view
* `ASL/FEDERATION-REPLAY/1` -- cross-node deterministic replay
* `ASL/DAM/1` -- Domain Authority Manifest
* `ASL/POLICY-HASH/1` -- policy hash
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/FEDERATION/1 defines **semantic rules** for multi-domain visibility and cross-domain references. It does not define transport, replication, or encodings.
---
## 1. Purpose
ASL/FEDERATION/1 defines the **multi-domain model** for ASL-based systems:
* Domain isolation and visibility rules
* Published vs internal state
* Cross-domain reference constraints
* Snapshot identity and deterministic reconstruction
---
## 2. Core Concepts
| Term | Definition |
| -------------------- | ---------- |
| Domain | Logical namespace with its own ASL store, log, and snapshot lineage. |
| Internal state | Artifacts/snapshots visible only within the domain. |
| Published state | Artifacts/snapshots visible to other domains. |
| Federated snapshot | Snapshot with visibility state that may be imported by other domains. |
| Cross-domain reference | Reference to a published artifact from another domain. |
---
## 3. Domain Semantics
1. **Domain isolation**
* Each domain has its own store, index, and log.
* Internal state is invisible outside the domain.
2. **Published state**
* Published artifacts and snapshots are visible to other domains.
* Published artifacts MUST satisfy ASL immutability and snapshot safety rules.
3. **Cross-domain references**
* Only published artifacts MAY be referenced by other domains.
* Cross-domain references are read-only and immutable.
* The consuming domain indexes imported artifacts using normal ASL index semantics.
---
## 4. Snapshot Identity
* Snapshot IDs are unique per domain.
* Federated snapshot identity is `(DomainID, SnapshotID)`.
* A federated snapshot MAY include cross-domain references only to published artifacts.
---
## 5. Visibility Rules
| Object | Internal Domain | Other Domains |
| ----------------------------------- | --------------- | ------------------- |
| Internal artifact | visible | hidden |
| Published artifact | visible | visible (read-only) |
| Internal snapshot | visible | hidden |
| Published snapshot | visible | visible |
| Block supporting published artifact | visible | visible |
| Block supporting internal artifact | visible | hidden |
* Index entries follow the same visibility rules.
* Determinism is defined per-domain and per-snapshot view.
---
## 6. Cross-Domain Operations
1. **Import published artifacts**
* A domain MAY import a published artifact from another domain.
* Imported artifacts MUST be treated as immutable.
2. **Export published artifacts**
* Internal artifacts MAY be promoted to published state.
* Promotion MUST be snapshot-bound and log-ordered.
3. **Federation log propagation**
* Each domain maintains its own append-only log.
* Federation MAY replicate published log-visible state.
---
## 7. Provenance and Traceability
* Execution receipts MAY include cross-domain inputs.
* Provenance MUST preserve origin domain and snapshot identity.
* Deterministic replay MUST be possible given `{Snapshot, LogPrefix}` for each domain.
---
## 8. Normative Invariants
1. **Determinism:** Reconstructing CURRENT in a domain yields the same visible state given the same snapshot and log prefix.
2. **Immutability:** Published artifacts and snapshots are immutable.
3. **Domain isolation:** Internal artifacts and snapshots are never visible to other domains.
4. **Federation safety:** Cross-domain references are read-only.
5. **Snapshot integrity:** Federated snapshots reference only published artifacts.
---
## 9. Integration with Other Layers
| Layer | Role in Federation |
| ------------------ | ------------------ |
| ASL/1-CORE | Artifact immutability and identity |
| ASL/1-CORE-INDEX | Semantic mapping and shadowing |
| ASL-STORE-INDEX | Sealing, retention, snapshot pinning |
| ASL/LOG/1 | Log-ordered visibility |
| ENC-ASL-CORE-INDEX | Domain/visibility metadata in records |
---
## 10. Non-Goals
* Transport protocols
* Network replication
* Witness signatures
* Domain admission and trust policy
---
## 11. Summary
ASL/FEDERATION/1 defines the semantic rules for multi-domain visibility and cross-domain reference. It keeps federation deterministic, snapshot-safe, and read-only across domain boundaries.

121
tier1/asl-federation-replay-1.md Normal file
View file

@ -0,0 +1,121 @@
# ASL/FEDERATION-REPLAY/1 -- Cross-Node Deterministic Replay
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [federation, replay, determinism, tgk, pel]
**Document ID:** `ASL/FEDERATION-REPLAY/1`
**Layer:** L2 -- Federation replay semantics (no transport)
**Depends on (normative):**
* `ASL/FEDERATION/1`
* `ASL/LOG/1`
* `ASL/1-CORE-INDEX`
* `TGK/1`
**Informative references:**
* `ASL/SYSTEM/1` -- unified system view
* `ENC-ASL-CORE-INDEX` -- domain metadata
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/FEDERATION-REPLAY/1 defines **deterministic replay rules** for federated propagation. It does not define network protocols or encodings.
---
## 1. Purpose
This document defines how artifacts, PERs, and TGK edges are propagated and replayed across federation nodes while preserving deterministic reconstruction.
---
## 2. Core Inputs
* **ArtifactKey**: canonical identifier for artifacts and PERs
* **SnapshotID**: snapshot boundary for replay
* **logseq**: append-only ordering within a domain
* **Canonical Edge Key**: TGK edge identity
---
## 3. Propagation Rules
### 3.1 Artifacts and PERs
* Artifacts and PERs are propagated with their `ArtifactKey` and `logseq`.
* Only artifacts visible under a published snapshot MAY be propagated.
* Duplicate ArtifactKeys MUST be de-duplicated by identity.
### 3.2 TGK Edges
* TGK edges are propagated with their canonical edge identity and `logseq`.
* Edge propagation MUST preserve the same snapshot/log visibility constraints as artifacts.
---
## 4. Deterministic Replay Ordering
Replay order MUST be deterministic across nodes:
1. Sort by `logseq` ascending
2. Tie-break by canonical identity (ArtifactKey or Canonical Edge Key)
This ordering MUST be applied identically by all receivers.
---
## 5. Snapshot Bounds
* Replay MUST be bounded by `{SnapshotID, LogPrefix}`.
* Records with `logseq` greater than the replay prefix MUST be ignored.
---
## 6. Conflict Handling
1. **ArtifactKey collision**
* If bytes match existing artifact: discard duplicate.
* If bytes differ: reject and flag conflict.
2. **TGK edge conflicts**
* Multiple edges with the same canonical identity are resolved by log order and tombstone rules.
3. **PER conflicts**
* PERs with identical inputs and program identity but divergent outputs MUST be rejected.
---
## 7. Provenance and Audit
Receivers SHOULD maintain:
* Last applied `logseq` per peer
* Snapshot provenance tables for applied records
This supports deterministic audit and replay verification.
---
## 8. Non-Goals
* Transport protocol selection
* Streaming formats
* Compression or batching
---
## 9. Summary
ASL/FEDERATION-REPLAY/1 defines a deterministic replay ordering and conflict rules to ensure federation is reproducible across nodes and snapshots.

85
tier1/asl-log-1.md
View file

@ -18,7 +18,7 @@ Tags: [deterministic, log, snapshot]
* `ASL/1-CORE-INDEX` — index semantics * `ASL/1-CORE-INDEX` — index semantics
* `TGK/1` — TGK edge visibility and traversal alignment * `TGK/1` — TGK edge visibility and traversal alignment
* `ENC-ASL-LOG` — bytes-on-disk encoding profile (if defined) * `ENC-ASL-LOG` — bytes-on-disk encoding profile (`tier1/enc-asl-log.md`)
* `ENC-ASL-CORE-INDEX` — index segment encoding (`tier1/enc-asl-core-index.md`) * `ENC-ASL-CORE-INDEX` — index segment encoding (`tier1/enc-asl-core-index.md`)
* `ASL/SYSTEM/1` — unified system view (PEL/TGK/federation alignment) * `ASL/SYSTEM/1` — unified system view (PEL/TGK/federation alignment)
@ -56,7 +56,8 @@ An ASL log MUST be:
3. Deterministically replayable 3. Deterministically replayable
4. Hash-chained 4. Hash-chained
5. Snapshot-anchorable 5. Snapshot-anchorable
6. Forward-compatible 6. Binary encoded per `ENC-ASL-LOG`
7. Forward-compatible
--- ---
@ -79,19 +80,53 @@ logseq: uint64
Each record commits to the previous record: Each record commits to the previous record:
``` ```
record_hash = H(prev_record_hash || record_type || payload) record_hash = H(prev_record_hash || logseq || record_type || payload_len || payload)
``` ```
This enables tamper detection, witness signing, and federation verification. 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. 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 ### 4.1 SEGMENT_SEAL
Declares an index segment visible. Declares an index segment visible.
Payload (encoding):
```c
typedef struct {
uint64_t segment_id;
uint8_t segment_hash[32];
} SegmentSealPayload;
```
Semantics: Semantics:
* From this `logseq` onward, the referenced segment is visible for lookup and replay. * From this `logseq` onward, the referenced segment is visible for lookup and replay.
@ -103,6 +138,16 @@ Semantics:
Declares an artifact inadmissible under domain policy. Declares an artifact inadmissible under domain policy.
Payload (encoding):
```c
typedef struct {
ArtifactRef artifact;
uint32_t scope;
uint32_t reason_code;
} TombstonePayload;
```
Semantics: Semantics:
* Does not delete data. * Does not delete data.
@ -113,6 +158,15 @@ Semantics:
Supersedes a previous tombstone. Supersedes a previous tombstone.
Payload (encoding):
```c
typedef struct {
ArtifactRef artifact;
uint64_t tombstone_logseq;
} TombstoneLiftPayload;
```
Semantics: Semantics:
* References an earlier TOMBSTONE. * References an earlier TOMBSTONE.
@ -123,6 +177,15 @@ Semantics:
Binds semantic state to a snapshot. Binds semantic state to a snapshot.
Payload (encoding):
```c
typedef struct {
uint64_t snapshot_id;
uint8_t root_hash[32];
} SnapshotAnchorPayload;
```
Semantics: Semantics:
* Defines a replay checkpoint. * Defines a replay checkpoint.
@ -132,6 +195,14 @@ Semantics:
Marks an artifact as published. Marks an artifact as published.
Payload (encoding):
```c
typedef struct {
ArtifactRef artifact;
} ArtifactPublishPayload;
```
Semantics: Semantics:
* Publication is domain-local. * Publication is domain-local.
@ -141,6 +212,14 @@ Semantics:
Withdraws publication. Withdraws publication.
Payload (encoding):
```c
typedef struct {
ArtifactRef artifact;
} ArtifactUnpublishPayload;
```
--- ---
## 5. Replay Semantics (Normative) ## 5. Replay Semantics (Normative)

115
tier1/asl-ocs-1.md Normal file
View file

@ -0,0 +1,115 @@
# ASL/OCS/1 -- Offline Certificate System
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [certificates, authority, offline]
**Document ID:** `ASL/OCS/1`
**Layer:** L2 -- Certificate semantics (no encoding)
**Depends on (normative):**
* `ASL/OFFLINE-ROOT-TRUST/1`
* `ASL/DAM/1`
* `ASL/POLICY-HASH/1`
**Informative references:**
* `PER/SIGNATURE/1` -- PER signature validation
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/OCS/1 defines certificate semantics as immutable artifacts. It does not define encodings.
---
## 1. Purpose
The Offline Certificate System (OCS) anchors domain authority in offline root keys and allows deterministic, offline verification of authority.
---
## 2. Core Principle
Certificates are **immutable ASL artifacts**, not live credentials.
They are:
* Signed once
* Snapshot-pinned
* Replayable
* Verified offline
---
## 3. Authority Certificate Artifact
### 3.1 Logical Structure
```text
AuthorityCertificate {
subject_type : enum { domain_root, principal }
subject_id : Hash
subject_pubkey : PublicKey
domain_id : DomainID
roles[] : Role
policy_hash : Hash
issued_by : PublicKey
version : u32
}
```
### 3.2 Semantics
* `domain_root`: certifies a domain root key for DAM issuance.
* `principal`: certifies a principal key for roles under a policy hash.
---
## 4. Offline Signing Workflow
1. Online domain prepares an AuthorityRequest.
2. Offline root signs an AuthorityCertificate.
3. Certificate artifact is imported and snapshot-pinned.
No online checks are required after import.
---
## 5. DAM Validation Chain
A DAM is valid iff:
1. DAM root key is certified by a `domain_root` certificate.
2. Certificate `policy_hash` matches DAM `policy_hash`.
3. Certificate signature validates against the offline root set.
---
## 6. Revocation Model
There is no live revocation. Revocation is performed by publishing a new DAM and new certificates, and referencing them in new snapshots.
---
## 7. Federation Verification
When receiving state from another domain:
1. Load snapshot
2. Resolve DAM and AuthorityCertificate artifacts
3. Verify against configured offline root set
4. Apply policy hash compatibility rules
---
## 8. Summary
ASL/OCS/1 defines immutable authority certificates signed by offline roots and bound to policy hashes, enabling deterministic, offline trust validation.

110
tier1/asl-offline-root-trust-1.md Normal file
View file

@ -0,0 +1,110 @@
# ASL/OFFLINE-ROOT-TRUST/1 -- Offline Root Trust
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [trust, roots, offline, authority]
**Document ID:** `ASL/OFFLINE-ROOT-TRUST/1`
**Layer:** L2 -- Trust anchors (no encoding)
**Depends on (normative):**
* `ASL/DAM/1`
**Informative references:**
* `ASL/OCS/1` -- offline certificate system
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/OFFLINE-ROOT-TRUST/1 defines the **offline root trust model** for domains. It does not define encodings.
---
## 1. Purpose
Offline roots define domain legitimacy. They are offline, auditable, and deterministic. They do not provide availability guarantees.
---
## 2. Root Set Definition
A domain MUST trust a fixed, explicit set of offline root public keys:
```text
OfflineRootSet {
version : u32
root_keys[] : PublicKey
threshold : u8
}
```
The root set is snapshot-pinned and rarely changed.
---
## 3. Recommended Root Count
Recommended size: **1 to 3** root keys.
* 1 root: personal or small domains
* 2 roots: separation of duties
* 3 roots: high-value domains
---
## 4. Threshold Rules
* Default threshold is 1.
* If threshold > 1, it MUST be fixed and explicit.
* Verification MUST be order-independent.
---
## 5. What Roots May Sign
Offline roots MAY sign only:
* AuthorityCertificate artifacts
* Root rotation artifacts
* Policy ratification artifacts (optional)
Roots MUST NOT sign artifacts, PERs, snapshots, or TGK edges.
---
## 6. Root Rotation
Root rotation is a constitutional change:
1. Define new root set
2. Old roots sign rotation artifact
3. New snapshots reference the new root set
4. Old snapshots remain valid
---
## 7. Validation Algorithm
To validate authority:
1. Load snapshot
2. Resolve DAM
3. Resolve AuthorityCertificate artifacts
4. Verify certificates against offline root set
5. Check threshold
No timestamps or online checks are required.
---
## 8. Summary
ASL/OFFLINE-ROOT-TRUST/1 defines a small, explicit offline root set that anchors authority and preserves deterministic replay.

145
tier1/asl-policy-hash-1.md Normal file
View file

@ -0,0 +1,145 @@
# ASL/POLICY-HASH/1 -- Policy Hash Specification
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [policy, hash, federation, trust]
**Document ID:** `ASL/POLICY-HASH/1`
**Layer:** L2 -- Policy binding semantics (no encoding)
**Depends on (normative):**
* `ASL/FEDERATION/1`
**Informative references:**
* `ASL/DAM/1` -- Domain Authority Manifest
* `ASL/DAP/1` -- Domain admission
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
ASL/POLICY-HASH/1 defines the logical structure and hashing rules for policy documents. It does not define transport or storage encodings.
---
## 1. Purpose
The policy hash binds domain rules to snapshots, authority, and federation decisions without embedding mutable policy text into artifacts.
---
## 2. Policy Coverage (Normative)
The policy hash MUST cover semantic constraints that affect correctness or trust:
1. Publication rules
2. Execution rules
3. Federation rules
4. Retention and GC constraints
5. Visibility rules
---
## 3. Logical Structure
```text
DomainPolicy {
version : u32
publication_policy : PublicationPolicy
execution_policy : ExecutionPolicy
federation_policy : FederationPolicy
retention_policy : RetentionPolicy
visibility_policy : VisibilityPolicy
}
```
Section schemas (minimal):
```text
PublicationPolicy {
require_signature : bool
allowed_roles[] : Role
snapshot_required : bool
}
ExecutionPolicy {
per_signature_required : bool
allowed_roles[] : Role
deterministic_only : bool
}
FederationPolicy {
export_published_only : bool
require_snapshot : bool
trusted_domains[] : DomainID
}
RetentionPolicy {
gc_unpublished_allowed : bool
min_snapshot_retention : u32
}
VisibilityPolicy {
internal_hidden : bool
published_read_only : bool
}
```
---
## 4. Canonicalization Rules (Normative)
The policy hash MUST be computed from canonical bytes:
1. Field order fixed
2. Arrays sorted lexicographically
3. No whitespace or comments
4. Integers encoded big-endian
5. Booleans encoded as 0x00 or 0x01
6. No optional fields omitted; defaults must be explicit
---
## 5. Hash Computation
```
policy_bytes = CanonicalSerialize(DomainPolicy)
policy_hash = HASH(policy_bytes)
```
The hash algorithm is SHA-256 unless explicitly overridden by domain policy.
---
## 6. Storage Locations
The policy hash SHOULD be stored in:
* Domain Authority Manifest (DAM)
* Snapshot metadata
* Federation metadata
* Optional PER metadata
---
## 7. Policy Evolution
Policy changes MUST NOT mutate history. A new policy requires:
1. New policy document
2. New policy hash
3. New DAM
4. New snapshots referencing the new hash
---
## 8. Summary
ASL/POLICY-HASH/1 defines a minimal, deterministic policy hash that binds domain rules to authority and snapshots without embedding mutable policy text into artifacts.

87
tier1/asl-store-index.md
View file

@ -103,7 +103,56 @@ Snapshots and log positions are required for checkpointing, federation, and dete
--- ---
## 4. Block Lifecycle Semantics ## 4. PUT/GET Contract (Normative)
### 4.1 PUT Signature
```
put(artifact) -> (ArtifactKey, IndexState)
```
* `ArtifactKey` is the content identity (ASL/1-CORE-INDEX).
* `IndexState = (SnapshotID, LogPosition)` after the PUT is admitted.
### 4.2 PUT Semantics
1. **Structural registration (if applicable)**: if a structural index (SID -> DAG) exists, it MUST register the artifact and reuse existing SID entries.
2. **Materialization (if applicable)**: if the artifact is lazy, materialize deterministically to derive `ArtifactKey`.
3. **Deduplication**: lookup `ArtifactKey` at CURRENT. If present, PUT MUST succeed without writing bytes or adding a new index entry.
4. **Storage**: if absent, write bytes to one or more sealed blocks and produce `ArtifactLocation`.
5. **Index mutation**: append an index entry mapping `ArtifactKey -> ArtifactLocation` and record visibility via log order.
### 4.3 PUT Guarantees
* PUT is idempotent for identical artifacts.
* No visible index entry points to mutable or missing bytes.
* Visibility follows log order and seal rules defined in this document.
### 4.4 GET Signature
```
get(ArtifactKey, IndexState?) -> bytes | NOT_FOUND
```
* `IndexState` defaults to CURRENT when omitted.
### 4.5 GET Semantics
1. Resolve `ArtifactKey -> ArtifactLocation` using `Index(snapshot, log_prefix)`.
2. If no entry exists, return `NOT_FOUND`.
3. Otherwise, read exactly the referenced `(BlockID, offset, length)` bytes and return them verbatim.
GET MUST NOT mutate state or trigger materialization.
### 4.6 Failure Semantics
* Partial writes MUST NOT become visible.
* Replay of snapshot + log after crash MUST reconstruct a valid CURRENT.
* Implementations MAY use caching, but MUST preserve determinism.
---
## 5. Block Lifecycle Semantics
| Event | Description | Semantic Guarantees | | Event | Description | Semantic Guarantees |
| ------------------ | ------------------------------------- | ------------------------------------------------------------- | | ------------------ | ------------------------------------- | ------------------------------------------------------------- |
@ -120,7 +169,7 @@ Notes:
--- ---
## 5. Segment Lifecycle Semantics ## 6. Segment Lifecycle Semantics
### 5.1 Creation ### 5.1 Creation
@ -143,7 +192,7 @@ Notes:
--- ---
## 6. Visibility and Lookup Semantics ## 7. Visibility and Lookup Semantics
### 6.1 Visibility Rules ### 6.1 Visibility Rules
@ -171,7 +220,7 @@ Determinism:
--- ---
## 7. Snapshot Interaction ## 8. Snapshot Interaction
* Snapshots capture the set of **sealed blocks** and **sealed index segments** at a point in time. * Snapshots capture the set of **sealed blocks** and **sealed index segments** at a point in time.
* Blocks referenced by a snapshot are **pinned** and cannot be garbage-collected until snapshot expiration. * Blocks referenced by a snapshot are **pinned** and cannot be garbage-collected until snapshot expiration.
@ -191,7 +240,7 @@ Segment and block visibility rules:
--- ---
## 8. Garbage Collection ## 9. Garbage Collection
Eligibility for GC: Eligibility for GC:
@ -211,7 +260,7 @@ Outcome:
--- ---
## 9. Tombstone Semantics ## 10. Tombstone Semantics
* Optional marker to invalidate prior mappings. * Optional marker to invalidate prior mappings.
* Visibility rules identical to regular index entries. * Visibility rules identical to regular index entries.
@ -219,9 +268,9 @@ Outcome:
--- ---
## 10. Small vs Large Block Handling ## 11. Small vs Large Block Handling
### 10.1 Definitions ### 11.1 Definitions
| Term | Meaning | | Term | Meaning |
| ----------------- | --------------------------------------------------------------------- | | ----------------- | --------------------------------------------------------------------- |
@ -229,22 +278,24 @@ Outcome:
| **Large block** | Block containing artifact bytes ≥ `T_small`. | | **Large block** | Block containing artifact bytes ≥ `T_small`. |
| **Mixed segment** | Segment containing both small and large blocks (discouraged). | | **Mixed segment** | Segment containing both small and large blocks (discouraged). |
| **Packing** | Combining multiple small artifacts into a single physical block. | | **Packing** | Combining multiple small artifacts into a single physical block. |
| **BlockID** | Opaque identifier for a block; addressing is identical for all sizes. |
Small vs large classification is **store-level only** and transparent to ASL-CORE and index layers. Small vs large classification is **store-level only** and transparent to ASL-CORE and index layers.
`T_small` is configurable per deployment.
### 10.2 Packing Rules ### 11.2 Packing Rules
1. **Small blocks may be packed together** to reduce storage overhead. 1. **Small blocks may be packed together** to reduce storage overhead.
2. **Large blocks are never packed with other artifacts**. 2. **Large blocks are never packed with other artifacts**.
3. Mixed segments are **allowed but discouraged**; index semantics remain identical. 3. Mixed segments are **allowed but discouraged**; implementations MAY warn when mixing occurs.
### 10.3 Segment Allocation Rules ### 11.3 Segment Allocation Rules
1. Small blocks are allocated into segments optimized for packing efficiency. 1. Small blocks are allocated into segments optimized for packing efficiency.
2. Large blocks are allocated into segments optimized for sequential I/O. 2. Large blocks are allocated into segments optimized for sequential I/O.
3. Segment sealing and visibility rules remain unchanged. 3. Segment sealing and visibility rules remain unchanged.
### 10.4 Indexing and Addressing ### 11.4 Indexing and Addressing
All blocks are addressed uniformly: All blocks are addressed uniformly:
@ -255,7 +306,7 @@ ArtifactLocation = [ArtifactExtent...]
Packing does **not** affect index semantics or determinism. Multi-extent ArtifactLocations are allowed. Packing does **not** affect index semantics or determinism. Multi-extent ArtifactLocations are allowed.
### 10.5 GC and Retention ### 11.5 GC and Retention
1. Packed small blocks can be reclaimed only when **all contained artifacts** are unreachable. 1. Packed small blocks can be reclaimed only when **all contained artifacts** are unreachable.
2. Large blocks are reclaimed per block. 2. Large blocks are reclaimed per block.
@ -264,7 +315,7 @@ Invariant: GC must never remove bytes still referenced by CURRENT or snapshots.
--- ---
## 11. Crash and Recovery Semantics ## 12. Crash and Recovery Semantics
* Open segments or unsealed blocks may be lost; no invariant is broken. * Open segments or unsealed blocks may be lost; no invariant is broken.
* Recovery procedure: * Recovery procedure:
@ -278,7 +329,7 @@ Invariant: GC must never remove bytes still referenced by CURRENT or snapshots.
--- ---
## 12. Normative Invariants ## 13. Normative Invariants
1. Sealed blocks are immutable. 1. Sealed blocks are immutable.
2. Index entries referencing blocks are immutable once visible. 2. Index entries referencing blocks are immutable once visible.
@ -290,7 +341,7 @@ Invariant: GC must never remove bytes still referenced by CURRENT or snapshots.
--- ---
## 13. Non-Goals ## 14. Non-Goals
* Disk-level encoding (ENC-ASL-CORE-INDEX). * Disk-level encoding (ENC-ASL-CORE-INDEX).
* Memory layout or caching. * Memory layout or caching.
@ -300,7 +351,7 @@ Invariant: GC must never remove bytes still referenced by CURRENT or snapshots.
--- ---
## 14. Relationship to Other Layers ## 15. Relationship to Other Layers
| Layer | Responsibility | | Layer | Responsibility |
| ------------------ | ---------------------------------------------------------------------------- | | ------------------ | ---------------------------------------------------------------------------- |
@ -311,7 +362,7 @@ Invariant: GC must never remove bytes still referenced by CURRENT or snapshots.
--- ---
## 15. Summary ## 16. Summary
The tier1 ASL-STORE-INDEX specification: The tier1 ASL-STORE-INDEX specification:

213
tier1/enc-asl-log.md Normal file
View file

@ -0,0 +1,213 @@
# ENC-ASL-LOG
### Encoding Specification for ASL Append-Only Log
---
## 1. Purpose
This document defines the **exact encoding** of the ASL append-only log.
It translates **ASL/LOG/1** semantics into a deterministic **bytes-on-disk** format.
It does **not** define log semantics (see `ASL/LOG/1`).
---
## 2. Encoding Principles
1. **Little-endian** integers
2. **Packed structures** (no compiler padding)
3. **Forward-compatible** versioning via header fields
4. **Deterministic serialization**: identical log content -> identical bytes
5. **Hash-chained integrity** as defined by ASL/LOG/1
---
## 3. Log File Layout
```
+----------------+
| LogHeader |
+----------------+
| LogRecord[] |
+----------------+
```
* **LogHeader**: fixed-size, mandatory, begins file
* **LogRecord[]**: append-only entries, variable number
---
## 4. LogHeader
```c
#pragma pack(push,1)
typedef struct {
uint64_t magic; // "ASLLOG01"
uint32_t version; // Encoding version (1)
uint32_t header_size; // Total header bytes including this struct
uint64_t flags; // Reserved, must be zero for v1
} LogHeader;
#pragma pack(pop)
```
Notes:
* `magic` is ASCII bytes: `0x41 0x53 0x4c 0x4c 0x4f 0x47 0x30 0x31`
* `version` allows forward compatibility
---
## 5. LogRecord Envelope
Each record is encoded as:
```c
#pragma pack(push,1)
typedef struct {
uint64_t logseq; // Monotonic sequence number
uint32_t record_type; // Record type tag
uint32_t payload_len; // Payload byte length
uint8_t payload[payload_len];
uint8_t record_hash[32]; // Hash-chained integrity (SHA-256)
} LogRecord;
#pragma pack(pop)
```
Hash chain rule (normative):
```
record_hash = H(prev_record_hash || logseq || record_type || payload_len || payload)
```
* `prev_record_hash` is the previous record's `record_hash`
* For the first record, `prev_record_hash` is 32 bytes of zero
* `H` is SHA-256 for v1
Readers MUST skip unknown `record_type` values using `payload_len` and MUST
continue replay without failure.
---
## 6. Record Type IDs (v1)
These type IDs bind the ASL/LOG/1 semantics to bytes-on-disk:
| Type ID | Record Type |
| ------- | ------------------ |
| 0x01 | SEGMENT_SEAL |
| 0x10 | TOMBSTONE |
| 0x11 | TOMBSTONE_LIFT |
| 0x20 | SNAPSHOT_ANCHOR |
| 0x30 | ARTIFACT_PUBLISH |
| 0x31 | ARTIFACT_UNPUBLISH |
---
## 6.1 Payload Schemas (v1)
All payloads are little-endian and packed. Variable-length fields are encoded
inline and accounted for by `payload_len`.
### 6.1.1 ArtifactRef
```c
#pragma pack(push,1)
typedef struct {
uint32_t hash_id; // Hash algorithm identifier
uint16_t digest_len; // Digest length in bytes
uint16_t reserved0; // Must be 0
uint8_t digest[digest_len];
} ArtifactRef;
#pragma pack(pop)
```
Notes:
* `digest_len` MUST be > 0.
* If StoreConfig fixes the hash, `digest_len` MUST match that hash's length.
### 6.1.2 SEGMENT_SEAL (Type 0x01)
```c
#pragma pack(push,1)
typedef struct {
uint64_t segment_id; // Store-local segment identifier
uint8_t segment_hash[32]; // SHA-256 over the segment file bytes
} SegmentSealPayload;
#pragma pack(pop)
```
### 6.1.3 TOMBSTONE (Type 0x10)
```c
#pragma pack(push,1)
typedef struct {
ArtifactRef artifact;
uint32_t scope; // Opaque to ASL/LOG/1
uint32_t reason_code; // Opaque to ASL/LOG/1
} TombstonePayload;
#pragma pack(pop)
```
### 6.1.4 TOMBSTONE_LIFT (Type 0x11)
```c
#pragma pack(push,1)
typedef struct {
ArtifactRef artifact;
uint64_t tombstone_logseq; // logseq of the tombstone being lifted
} TombstoneLiftPayload;
#pragma pack(pop)
```
### 6.1.5 SNAPSHOT_ANCHOR (Type 0x20)
```c
#pragma pack(push,1)
typedef struct {
uint64_t snapshot_id;
uint8_t root_hash[32]; // Hash of snapshot-visible state
} SnapshotAnchorPayload;
#pragma pack(pop)
```
### 6.1.6 ARTIFACT_PUBLISH (Type 0x30)
```c
#pragma pack(push,1)
typedef struct {
ArtifactRef artifact;
} ArtifactPublishPayload;
#pragma pack(pop)
```
### 6.1.7 ARTIFACT_UNPUBLISH (Type 0x31)
```c
#pragma pack(push,1)
typedef struct {
ArtifactRef artifact;
} ArtifactUnpublishPayload;
#pragma pack(pop)
```
---
## 7. Versioning Rules
* `version = 1` for this specification.
* New record types MAY be added without bumping the version.
* Layout changes to `LogHeader` or `LogRecord` require a new version.
---
## 8. Relationship to Other Layers
| Layer | Responsibility |
| ---------------- | ------------------------------------------------ |
| ASL/LOG/1 | Semantic log behavior and replay rules |
| ASL-STORE-INDEX | Store lifecycle and snapshot/log contracts |
| ENC-ASL-LOG | Exact byte layout for log encoding (this doc) |
| ENC-ASL-CORE-INDEX | Exact byte layout for index segments |

105
tier1/per-signature-1.md Normal file
View file

@ -0,0 +1,105 @@
# PER/SIGNATURE/1 -- PER Signature Layout
Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-01-17
Tags: [per, signatures, determinism]
**Document ID:** `PER/SIGNATURE/1`
**Layer:** L2 -- Execution receipt signatures (no encoding)
**Depends on (normative):**
* `ASL/DAM/1`
* `ASL/LOG/1`
**Informative references:**
* `ASL/POLICY-HASH/1`
* `TGK/1` -- linking signatures via edges
---
## 0. Conventions
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
PER/SIGNATURE/1 defines the logical signature payload and validation steps for PER artifacts. It does not define encodings.
---
## 1. Purpose
A PER signature certifies that a deterministic execution occurred under a specific snapshot, with specific inputs, producing a specific output.
---
## 2. Canonical Signing Payload
```text
PERSignaturePayload {
domain_id : DomainID
snapshot_id : SnapshotID
per_artifact_id : ArtifactID
input_artifact_ids[] : ArtifactID (sorted)
program_id : ProgramID
logseq : u64
}
```
---
## 3. Canonicalization Rules (Normative)
1. Byte order: big-endian
2. Arrays: sorted lexicographically by ArtifactID
3. No optional fields
4. No timestamps or environment data
---
## 4. Signature Object
```text
PERSignature {
payload_hash : Hash
public_key : PublicKey
signature : Signature
algorithm : SigAlgorithm
}
```
---
## 5. Validation Procedure (Normative)
To validate a PER:
1. Load snapshot
2. Resolve DAM
3. Recompute canonical payload
4. Verify signature against `public_key`
5. Verify `public_key` is in DAM and has `execute` role
6. Verify `snapshot_id` and `logseq` match visibility constraints
If any step fails, the PER MUST be rejected as authoritative.
---
## 6. Failure Modes
| Condition | Result |
| ------------------ | ------------------------- |
| Missing signature | PER is informational only |
| Invalid signature | Reject PER |
| Key not in DAM | Reject PER |
| Snapshot mismatch | Reject PER |
| Input mismatch | Reject PER |
---
## 7. Summary
PER/SIGNATURE/1 defines a minimal, deterministic signature payload and validation procedure for PER artifacts.