niklas/amduat-api

Fork 0

Carl Niklas Rydberg fabace7616 Reorganize notes into tier1/ops docs

2026-01-17 10:33:23 +01:00

7.1 KiB

Raw Blame History

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:

Provide stable store handles for ASL/1-STORE and ASL/LOG/1 operations.
Maintain domain lifecycle state and admission status.
Enforce admission outcomes and courtesy leases without leaking those semantics into ASL/1-STORE.
Provide atomic append guarantees for log operations.
Coordinate snapshot creation and mounting.
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.

7.1 KiB Raw Blame History