niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat-api/ops/asl-host-1.md
Carl Niklas Rydberg fabace7616 Reorganize notes into tier1/ops docs
2026-01-17 10:33:23 +01:00

7.1 KiB
Raw Permalink 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:

  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.