277 lines
7.1 KiB
Markdown
277 lines
7.1 KiB
Markdown
# ASL/HOST/1 - Host Runtime Interface
|
|
|
|
Status: Draft
|
|
Owner: Architecture
|
|
Version: 0.1.0
|
|
SoT: No
|
|
Last Updated: 2026-01-17
|
|
Tags: [ops, host, admission, storage]
|
|
|
|
**Document ID:** `ASL/HOST/1`
|
|
**Layer:** O1 - Host runtime profile (node boundary)
|
|
|
|
**Depends on (normative):**
|
|
|
|
* `ASL/1-STORE`
|
|
* `ASL/LOG/1`
|
|
* `ASL/DAP/1`
|
|
* `ASL/DAM/1`
|
|
* `ASL/POLICY-HASH/1`
|
|
|
|
**Informative references:**
|
|
|
|
* `ASL/SYSTEM/1`
|
|
* `ASL/OFFLINE-ROOT-TRUST/1`
|
|
* `ENC-ASL-HOST/1`
|
|
* `ENC-ASL-LOG`
|
|
* `ASL/AUTH-HOST/1`
|
|
* `ASL/RESCUE-NODE/1`
|
|
|
|
---
|
|
|
|
## 0. Conventions
|
|
|
|
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be
|
|
interpreted as in RFC 2119.
|
|
|
|
ASL/HOST/1 defines host responsibilities and boundaries. It does not define
|
|
artifact semantics, encoding formats, or cryptographic algorithms.
|
|
|
|
---
|
|
|
|
## 1. Purpose and Scope
|
|
|
|
ASL/HOST/1 specifies the runtime contract between an ASL node and its host
|
|
environment. It covers:
|
|
|
|
* Domain lifecycle and admission state tracking
|
|
* Store handle provisioning for ASL/1-STORE and ASL/LOG/1
|
|
* Snapshot coordination and log append guarantees
|
|
* Resource and lease enforcement at the host boundary
|
|
|
|
Out of scope:
|
|
|
|
* Artifact semantics (ASL/1-CORE)
|
|
* On-disk encoding and byte layouts (ENC specs)
|
|
* Policy definition and authority semantics (ASL/AUTH layers)
|
|
|
|
---
|
|
|
|
## 2. Position in the Stack
|
|
|
|
ASL/HOST is the membrane between host services and ASL semantics.
|
|
|
|
```
|
|
+--------------------------+
|
|
| ASL/AUTH (policy, keys) |
|
|
+--------------------------+
|
|
| ASL/HOST (this spec) |
|
|
+--------------------------+
|
|
| ASL/1-STORE + ASL/LOG |
|
|
+--------------------------+
|
|
| Host FS / ZFS / POSIX |
|
|
+--------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Core Responsibilities (Normative)
|
|
|
|
An ASL host implementation MUST:
|
|
|
|
1. Provide stable store handles for ASL/1-STORE and ASL/LOG/1 operations.
|
|
2. Maintain domain lifecycle state and admission status.
|
|
3. Enforce admission outcomes and courtesy leases without leaking those
|
|
semantics into ASL/1-STORE.
|
|
4. Provide atomic append guarantees for log operations.
|
|
5. Coordinate snapshot creation and mounting.
|
|
6. Enforce local resource limits and error handling.
|
|
|
|
---
|
|
|
|
## 4. Core Concepts
|
|
|
|
| Concept | Definition |
|
|
| ----------------- | ------------------------------------------------------------------------- |
|
|
| **StoreHandle** | Opaque reference to a host-provided store instance |
|
|
| **StoreLocation** | Host-defined location where a store exists (path, URI, mount point, etc.) |
|
|
| **AppendUnit** | Minimum atomic write unit for the append-only log |
|
|
| **SnapshotID** | Opaque identifier of a host-provided snapshot |
|
|
| **HostClock** | Monotonic counter or timestamp source |
|
|
| **HostIdentity** | Unique machine or user identity for signing or domain minting |
|
|
|
|
---
|
|
|
|
## 4.1 Authority Enforcement (Normative)
|
|
|
|
An ASL host MUST NOT advance a domain unless it can prove authority to do so
|
|
from domain-local artifacts visible at the current snapshot.
|
|
|
|
Authority enforcement applies to all domains, including Common, group, and
|
|
personal domains.
|
|
|
|
---
|
|
|
|
## 5. Domain Model
|
|
|
|
### 5.1 Domain States
|
|
|
|
A host MUST track the following domain states:
|
|
|
|
* `UNRECOGNIZED`
|
|
* `COURTESY`
|
|
* `FULL`
|
|
* `SUSPENDED`
|
|
* `REVOKED`
|
|
|
|
---
|
|
|
|
### 5.3 Witness Modes (Informative)
|
|
|
|
Domains operate under one of the following authority modes:
|
|
|
|
| Mode | Meaning |
|
|
| ---------------- | --------------------------------------------- |
|
|
| `single-witness` | One domain/key may emit snapshots |
|
|
| `quorum-witness` | A threshold of domains may authorize emission |
|
|
| `self-authority` | This host's domain is the witness |
|
|
|
|
Witness mode is policy-defined. Hosts MUST enforce the mode discovered in
|
|
domain-local artifacts.
|
|
|
|
### 5.2 Domain Descriptor
|
|
|
|
Host-owned metadata MUST include:
|
|
|
|
```
|
|
domain_id
|
|
state
|
|
created_at
|
|
admitted_at
|
|
root_key_fingerprint
|
|
policy_hash
|
|
current_snapshot
|
|
current_logseq
|
|
```
|
|
|
|
The descriptor is derived state and MUST NOT be treated as authoritative
|
|
artifact content.
|
|
|
|
---
|
|
|
|
## 6. Domain Lifecycle Operations
|
|
|
|
### 6.1 Create
|
|
|
|
`CreateDomain(location) -> domain_id`
|
|
|
|
* MUST allocate an isolated domain root.
|
|
* MUST initialize empty store, log, and snapshot markers.
|
|
|
|
### 6.2 Admit
|
|
|
|
`AdmitDomain(dam, signature) -> AdmissionResult`
|
|
|
|
* MUST validate DAM schema and signature per `ASL/DAM/1`.
|
|
* MUST enforce policy hash compatibility per `ASL/POLICY-HASH/1`.
|
|
|
|
Admission outcomes MUST have the following effects:
|
|
|
|
| Outcome | Host Behavior |
|
|
| ---------------- | --------------------------------------- |
|
|
| ACCEPTED | Enable publishing, indexing, federation |
|
|
| ACCEPTED_LIMITED | Enable courtesy-only storage |
|
|
| DEFERRED | Domain exists but blocked |
|
|
| REJECTED | Domain remains isolated |
|
|
|
|
### 6.3 Suspend and Revoke
|
|
|
|
* `SUSPENDED` MUST block new writes.
|
|
* `REVOKED` MUST block all access except local inspection.
|
|
|
|
---
|
|
|
|
## 7. Store Handle Interface
|
|
|
|
A host MUST expose at least the following operations:
|
|
|
|
* `CreateStore(location) -> StoreHandle`
|
|
* `OpenStore(location) -> StoreHandle`
|
|
* `CloseStore(handle)`
|
|
|
|
The StoreHandle is opaque and scoped to a domain. Admission state MUST gate
|
|
capabilities exposed by the StoreHandle (see Section 7).
|
|
|
|
StoreLocation MAY be any filesystem path or mount. When creating a store, the
|
|
host SHOULD initialize the standard ASL store structure (blocks, index, log).
|
|
|
|
---
|
|
|
|
## 8. Admission-Gated Capabilities
|
|
|
|
Capabilities MUST be gated as follows:
|
|
|
|
| Capability | Courtesy | Full |
|
|
| ---------------- | -------- | ---- |
|
|
| allocate_block | yes | yes |
|
|
| seal_block | yes | yes |
|
|
| append_log | yes | yes |
|
|
| publish_snapshot | no | yes |
|
|
| federate_log | no | yes |
|
|
|
|
ASL/1-STORE and ASL/LOG MUST remain unaware of admission semantics.
|
|
|
|
---
|
|
|
|
## 9. Courtesy Leases
|
|
|
|
Courtesy leases are host-owned metadata attached to a domain. The host MUST
|
|
enforce lease limits without exposing courtesy state to ASL/1-STORE.
|
|
|
|
Enforcement MAY include:
|
|
|
|
* Storage caps
|
|
* Snapshot count limits
|
|
* Write blocking after expiry
|
|
|
|
---
|
|
|
|
## 10. Snapshot and Log Coordination
|
|
|
|
The host MUST ensure:
|
|
|
|
* Append-only log semantics with strict ordering
|
|
* Snapshot creation captures a consistent view of sealed segments
|
|
* Snapshot mounts are read-only and bounded by a log sequence
|
|
|
|
---
|
|
|
|
## 11. Error Model
|
|
|
|
Host operations MUST report deterministic error codes. Minimum set:
|
|
|
|
* `HOST_OK`
|
|
* `HOST_EXISTS`
|
|
* `HOST_NOT_FOUND`
|
|
* `HOST_IO_ERROR`
|
|
* `HOST_CONCURRENT_MODIFICATION`
|
|
* `HOST_ADMISSION_REJECTED`
|
|
* `HOST_LEASE_EXPIRED`
|
|
|
|
---
|
|
|
|
## 12. Security Considerations
|
|
|
|
* Admission verification MUST be performed before enabling federation or
|
|
publication.
|
|
* Private key material SHOULD NOT be required on the host except for explicit
|
|
authority operations.
|
|
* The host MUST treat all imported artifacts as untrusted until admission and
|
|
policy validation succeed.
|
|
|
|
---
|
|
|
|
## 13. Versioning
|
|
|
|
Backward-incompatible changes MUST bump the major version of ASL/HOST.
|