diff --git a/docs/federation-implementation-notes.md b/docs/federation-implementation-notes.md new file mode 100644 index 0000000..8e61f86 --- /dev/null +++ b/docs/federation-implementation-notes.md @@ -0,0 +1,170 @@ +# Federation Implementation Notes (Core) + +Status: Draft +Owner: Architecture +Version: 0.1.0 +SoT: No +Last Updated: 2025-02-XX + +## Purpose + +These notes bind the federation semantics docs to concrete core-library +responsibilities, APIs, and data structures. The intent is to keep +federation logic inside the core substrate and keep daemon/frontends thin. + +## Normative inputs + +Core semantics and replay: +- tier1/asl-federation-1.md +- tier1/asl-federation-replay-1.md +- tier1/asl-store-index-1.md +- tier1/enc-asl-core-index-1.md + +Admission and policy gating: +- tier1/asl-dap-1.md +- tier1/asl-policy-hash-1.md +- tier1/asl-domain-model-1.md +- tier1/asl-dam-1.md + +Contextual alignment: +- tier1/asl-system-1.md +- tier1/asl-encrypted-blocks-1.md + +## Scope (core library) + +Federation MUST be implemented as core substrate logic: +- Deterministic federation view construction. +- Replay ordering and bounds per domain. +- Imported record metadata preservation (domain_id, visibility, + cross_domain_source). +- Tombstone and shadowing behavior per domain. + +The following are explicitly out of scope for core: +- Transport protocols (HTTP, IPC, gossip). +- Peer discovery and operational orchestration. +- Admin UX and deployment wiring. + +## Responsibilities + +1) Federation registry + - Tracks known domains, admission status, policy hash, and + last admitted {SnapshotID, LogPrefix}. + - Enforces DAP + policy compatibility prior to admitting remote state. + +2) Federation view cache + - Materializes a deterministic view from local state + admitted + published records from other domains. + - Stores imported records with origin metadata for replay. + - Tracks per-domain replay high-water {domain_id, logseq}. + +3) Resolver + - Resolves ArtifactKey using local store + federation view. + - Does not mutate store/index as part of GET semantics. + +## Data model (suggested) + +```c +typedef struct { + uint32_t domain_id; + uint64_t snapshot_id; + uint64_t log_prefix; + uint64_t last_logseq; + uint8_t admitted; // boolean + uint8_t policy_ok; // boolean + uint8_t reserved[6]; +} amduat_fed_domain_state_t; + +typedef struct { + uint32_t domain_id; + uint8_t visibility; // 0 internal, 1 published + uint8_t has_source; // 0/1 + uint16_t reserved0; + uint32_t source_domain; +} amduat_fed_record_meta_t; + +typedef struct { + amduat_fed_record_meta_t meta; + amduat_asl_artifact_key_t key; + amduat_asl_artifact_location_t loc; + uint64_t logseq; + uint64_t snapshot_id; + uint64_t log_prefix; +} amduat_fed_index_record_t; +``` + +Notes: +- Imported records MUST retain domain_id and cross-domain source metadata. +- Tombstones must retain domain_id/visibility for domain-local shadowing. + +## Core API sketch + +```c +typedef struct amduat_fed_registry_t amduat_fed_registry_t; +typedef struct amduat_fed_view_t amduat_fed_view_t; + +amduat_fed_registry_t *amduat_fed_registry_open(...); +void amduat_fed_registry_close(amduat_fed_registry_t *); + +// Admission + policy gating +bool amduat_fed_admit_domain(amduat_fed_registry_t *, domain_id, policy_hash, ...); +bool amduat_fed_set_domain_state(amduat_fed_registry_t *, domain_id, + snapshot_id, log_prefix); + +// Ingest published records for a domain (already transported). +bool amduat_fed_ingest_records(amduat_fed_registry_t *, domain_id, + const amduat_fed_index_record_t *records, + size_t count); + +// Build or refresh a deterministic federation view. +amduat_fed_view_t *amduat_fed_view_build(amduat_fed_registry_t *, + const amduat_asl_store_t *local_store, + const amduat_asl_index_state_t *local_state); + +// Resolve via local store + federated view. +amduat_asl_store_error_t amduat_fed_resolve( + const amduat_fed_view_t *view, + const amduat_asl_artifact_key_t *key, + amduat_bytes_t *out_bytes); +``` + +Notes: +- Transport fetch is not part of resolve; it only consumes ingested records. +- The daemon can choose to fetch missing bytes when resolve reports a remote + location but local bytes are absent. + +## Replay and view construction + +Rules are as per ASL/FEDERATION-REPLAY/1: +- Records are ordered by (logseq asc, canonical identity tie-break). +- Replay is bounded by {SnapshotID, LogPrefix} per domain. +- Tombstones shadow only within their source domain. +- Imported entries keep domain_id + cross_domain_source. + +The view is the union of: +1) Local domain internal + published state at local {SnapshotID, LogPrefix}. +2) Admitted foreign published state at each domain's {SnapshotID, LogPrefix}. + +## Cache and storage + +Federation view storage MAY be: +- In-memory (ephemeral), or +- On-disk index segments with federation metadata populated. + +If remote bytes are fetched, they MUST be written to a cache store that is +logically separate from the authoritative local store (policy-controlled). + +## Error reporting + +Core resolve should distinguish: +- NOT_FOUND (no record in local or federation view) +- FOUND_REMOTE_NO_BYTES (record exists in view but bytes missing locally) +- INTEGRITY_ERROR (hash mismatch on bytes) +- POLICY_DENIED (domain admitted but record filtered by policy) + +## Tests (minimal) + +1) Replay ordering determinism across two domains with interleaved logseq. +2) Tombstone shadowing is domain-local. +3) Imported record metadata preserved in view and survives rebuild. +4) Conflict: same ArtifactKey with different bytes across domains rejected. +5) Bound replay by {SnapshotID, LogPrefix} produces stable view. diff --git a/tier1/asl-dam-1.md b/tier1/asl-dam-1.md new file mode 100644 index 0000000..43ceb2e --- /dev/null +++ b/tier1/asl-dam-1.md @@ -0,0 +1,148 @@ +# 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 +* **Authority scope**: explicit actions this DAM authorizes within the 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 + scope[] : AuthorityScope +} + +PrincipalEntry { + principal_id : Hash + public_key : PublicKey + roles[] : Role +} +``` + +The DAM is immutable once published. Rotation is performed by publishing a new DAM. + +### 4.1 Authority Scope + +The optional `scope[]` constrains what this DAM authorizes. If omitted, scope is +assumed to include all roles defined in this document. + +```text +AuthorityScope = { + "produce", + "execute", + "publish", + "federate", + "audit" +} +``` + +--- + +## 5. Admission and Pinning (Normative) + +Before a DAM is trusted, a receiving domain MUST: + +1. Admit the domain (see `ASL/DAP/1`). +2. Pin the DAM artifact to a snapshot. +3. Pin the DAM's `policy_hash` for that snapshot lineage. + +--- + +## 6. 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. The action is within the DAM's declared `scope[]` (if present). + +--- + +## 7. 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. + +--- + +## 8. Idempotency and Rotation + +* Replaying the same snapshot + DAM MUST yield identical authority decisions. +* Rotation is done by publishing a new DAM and referencing it in new snapshots. +* Old snapshots remain valid with the DAM they reference. + +--- + +## 9. Non-Goals + +* Encoding format +* Key rotation workflow +* Live revocation + +--- + +## 10. 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. diff --git a/tier1/asl-dap-1.md b/tier1/asl-dap-1.md new file mode 100644 index 0000000..7c12854 --- /dev/null +++ b/tier1/asl-dap-1.md @@ -0,0 +1,165 @@ +# 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 Record (Normative) + +The receiving domain MUST persist an admission record that is snapshot-pinned: + +```text +AdmissionRecord { + domain_id + dam_hash + policy_hash + admitted_scope[] + decision + decision_epoch +} +``` + +The `decision_epoch` is a monotonically increasing local counter (not wall time). + +--- + +## 5. 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. + +--- + +## 6. 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. + +--- + +## 7. Scope Enforcement (Normative) + +* Admission scope MUST gate federation view construction and replay admission. +* A receiving domain MUST NOT admit state outside the granted scope. +* Scope changes require a new admission decision and updated AdmissionRecord. + +--- + +## 8. 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. + +--- + +## 9. Non-Goals + +* Transport format +* PKI integration +* Live revocation or liveness checks + +--- + +## 10. Summary + +ASL/DAP/1 defines a deterministic admission process for domains, with optional courtesy leasing for rescue and bootstrap scenarios. diff --git a/tier1/asl-domain-model-1.md b/tier1/asl-domain-model-1.md new file mode 100644 index 0000000..400bb56 --- /dev/null +++ b/tier1/asl-domain-model-1.md @@ -0,0 +1,164 @@ +# ASL/DOMAIN-MODEL/1 -- Domain Topology and Publication Semantics + +Status: Draft +Owner: Architecture +Version: 0.1.0 +SoT: No +Last Updated: 2025-01-17 +Tags: [domains, authority, publication, federation] + +**Document ID:** `ASL/DOMAIN-MODEL/1` +**Layer:** L2 -- Domain topology and delegation semantics (no transport) + +**Depends on (normative):** + +* `ASL/DAM/1` +* `ASL/DAP/1` +* `ASL/POLICY-HASH/1` +* `ASL/FEDERATION/1` +* `ASL/LOG/1` + +**Informative references:** + +* `ASL/OCS/1` -- offline certificate system +* `ASL/OFFLINE-ROOT-TRUST/1` +* `ASL/SYSTEM/1` -- unified system view + +--- + +## 0. Conventions + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119. + +ASL/DOMAIN-MODEL/1 defines domain topology and publication semantics. It does not define transport, storage layout, or encoding. + +--- + +## 1. Purpose + +This document defines how domains relate, how authority is delegated, and how publication is made safe and explicit. +It provides a stable mental model for personal, group, and shared domains without introducing implicit trust. + +--- + +## 2. First Principles (Normative) + +1. **No implicit inheritance.** Domains are not hierarchical by default; trust is explicit. +2. **Authority is explicit.** Authority is defined by DAM + certificates; it is never implied by naming or topology. +3. **Publication is explicit.** Visibility is controlled by index metadata and policy, not by storage or naming. +4. **Determinism is preserved.** All cross-domain visibility MUST be replayable from snapshots and logs. + +--- + +## 3. Domain Roles (Common, Personal, Working) + +These roles are semantic patterns; a deployment MAY create many instances. + +### 3.1 Common Domain + +A shared, conservative domain for stable artifacts and schemas. + +Properties: + +* High trust threshold +* Read-mostly, slow-changing +* Publishes broadly + +### 3.2 Personal Domain + +A domain anchored to a single personal identity and authority. + +Properties: + +* Root of local agency +* Owns offline roots and DAM +* Decides what to publish and to whom + +### 3.3 Working / Ephemeral Domains + +Task-focused domains created under delegated authority. + +Properties: + +* Narrow policy and scope +* Often short-lived +* Results MAY be promoted to personal or common domains + +--- + +## 4. Delegation and Authority (Normative) + +Delegation is explicit and certificate-based. + +Rules: + +* A domain MAY delegate authority to a new domain by issuing a `domain_root` certificate (ASL/OCS/1). +* Delegation MUST be recorded in the receiving domain's DAM and policy hash. +* Delegation does not create inheritance: the delegating domain does not gain automatic visibility into the new domain. + +--- + +## 5. Publication and Visibility (Normative) + +Publication is a visibility decision, not a storage action. + +Rules: + +* Only published artifacts are eligible for cross-domain visibility. +* Publication state MUST be encoded in index metadata (ENC-ASL-CORE-INDEX). +* Blocks and storage layouts MUST NOT be treated as publication units. +* Publication of snapshots (or snapshot hashes) is allowed but MUST NOT imply data publication. + +--- + +## 6. Cross-Domain Trust and Admission (Normative) + +Trust is established by explicit admission and policy compatibility. + +Rules: + +* A receiving domain MUST admit an external domain (ASL/DAP/1) before including its state. +* Policy hash compatibility MUST be checked before accepting published artifacts. +* A domain MAY pin a trusted foreign domain without reciprocal trust. + +--- + +## 7. Safe Publication Patterns (Informative) + +### 7.1 Personal to Personal Archive + +``` +personal/rescue -> personal/archive +``` + +* Publish explicitly from the working domain to an archival domain. +* Only published artifacts are visible across the boundary. + +### 7.2 Personal to Group Domain + +``` +personal/project -> group/shared +``` + +* Requires admission by the group domain and policy compatibility. +* No unilateral publishing into the group domain. + +### 7.3 Personal to Public Domain + +``` +personal/public -> common/public +``` + +* One-way trust is permitted. +* Public domain pins the personal domain; the personal domain need not pin the public domain. + +--- + +## 8. Non-Goals + +ASL/DOMAIN-MODEL/1 does not define: + +* Transport or replication protocols +* Encoding formats +* Storage layouts or filesystem assumptions +* Governance workflows beyond admission and policy compatibility diff --git a/tier1/asl-encrypted-blocks-1.md b/tier1/asl-encrypted-blocks-1.md new file mode 100644 index 0000000..786d4de --- /dev/null +++ b/tier1/asl-encrypted-blocks-1.md @@ -0,0 +1,113 @@ +# ASL/ENCRYPTED-BLOCKS/1 -- Encrypted Block Storage Across Domains + +Status: Draft +Owner: Architecture +Version: 0.1.0 +SoT: No +Last Updated: 2025-01-17 +Tags: [encryption, blocks, federation, storage] + +**Document ID:** `ASL/ENCRYPTED-BLOCKS/1` +**Layer:** L2 -- Encrypted storage semantics (no transport) + +**Depends on (normative):** + +* `ASL-STORE-INDEX` +* `ASL/FEDERATION/1` +* `ASL/LOG/1` + +**Informative references:** + +* `ASL/DOMAIN-MODEL/1` +* `ASL/POLICY-HASH/1` + +--- + +## 0. Conventions + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119. + +ASL/ENCRYPTED-BLOCKS/1 defines semantics for storing encrypted blocks across domains. It does not define encryption algorithms, key management, or transport. + +--- + +## 1. Purpose + +This document defines how encrypted blocks may be stored in a foreign domain without transferring semantic authority or decryption capability. + +--- + +## 2. Core Principle (Normative) + +A domain MAY store encrypted blocks for another domain, but MUST NOT assert semantic meaning for those bytes. + +Meaning is owned by the domain that holds the decryption keys and index entries. + +--- + +## 3. Encryption Model (Normative) + +### 3.1 Block Encryption + +Before sealing, a block MAY be encrypted: + +``` +plaintext_block + -> encrypt(K) + -> ciphertext_block + -> BlockID = H(ciphertext_block) +``` + +Rules: + +* Encryption occurs before sealing. +* `BlockID` is computed over ciphertext bytes. +* Deterministic encryption is NOT required. + +### 3.2 Key Ownership + +* Encryption keys are owned by the originating domain. +* Keys MUST NOT be federated or embedded in index metadata. +* Decryption metadata MUST remain local to the originating domain. + +--- + +## 4. Foreign Domain Storage (Normative) + +A foreign domain storing encrypted blocks: + +* Treats ciphertext blocks as opaque bytes. +* MAY retain or GC blocks under its local policy. +* MUST NOT create semantic index entries for those blocks. + +--- + +## 5. Originating Domain References (Normative) + +The originating domain: + +* Maintains index entries referencing the ciphertext `BlockID`. +* Applies normal visibility, log, and snapshot rules. +* Uses local decryption metadata to materialize plaintext. + +--- + +## 6. Cross-Domain References (Informative) + +Two references are distinct: + +* **Storage reference:** foreign domain stores ciphertext blocks. +* **Semantic reference:** originating domain records artifact visibility and meaning. + +Foreign storage does not imply federation of semantics. + +--- + +## 7. Non-Goals + +ASL/ENCRYPTED-BLOCKS/1 does not define: + +* Key exchange or key discovery +* Encryption algorithm choices +* Transport or replication protocols +* Storage layout or block packing rules diff --git a/tier1/asl-federation-1.md b/tier1/asl-federation-1.md new file mode 100644 index 0000000..900715b --- /dev/null +++ b/tier1/asl-federation-1.md @@ -0,0 +1,186 @@ +# 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. | +| Federation view | A deterministic view constructed by combining local internal state with admitted published state from other domains. | + +--- + +## 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. + * Imported entries MUST preserve origin metadata (domain identity and visibility) for deterministic replay. + +--- + +## 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. +* Replay of federated state MUST be bounded by the source domain's `{SnapshotID, LogPrefix}`. + +--- + +## 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. Federation View Construction + +To construct a federation view for a domain: + +1. Start with the local domain's internal + published state at `{SnapshotID, LogPrefix}`. +2. For each admitted foreign domain, include only published state that is: + + * Visible under that domain's `{SnapshotID, LogPrefix}`, and + * Allowed by the receiving domain's admission and policy rules. + +3. Apply normal ASL index shadowing and tombstone rules within each domain's log order. + +Federation MUST NOT bypass ASL/LOG/1 ordering or ASL/1-CORE-INDEX semantics. + +--- + +## 7. Cross-Domain Operations + +1. **Import published artifacts** + + * A domain MAY import a published artifact from another domain. + * Imported artifacts MUST be treated as immutable. + * Import MUST be gated by admission and policy compatibility (see `ASL/DAP/1` and `ASL/POLICY-HASH/1`). + +2. **Export published artifacts** + + * Internal artifacts MAY be promoted to published state. + * Promotion MUST be snapshot-bound and log-ordered. + * Publication MUST respect the domain's policy hash and DAM roles. + +3. **Federation log propagation** + + * Each domain maintains its own append-only log. + * Federation MAY replicate published log-visible state. + +--- + +## 8. 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. + +--- + +## 9. 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. + +--- + +## 10. 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 | + +--- + +## 11. Non-Goals + +* Transport protocols +* Network replication +* Witness signatures +* Domain admission and trust policy + +--- + +## 12. 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. diff --git a/tier1/asl-federation-replay-1.md b/tier1/asl-federation-replay-1.md new file mode 100644 index 0000000..1802607 --- /dev/null +++ b/tier1/asl-federation-replay-1.md @@ -0,0 +1,170 @@ +# 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 +* `ASL/DAP/1` -- admission gating +* `ASL/POLICY-HASH/1` -- policy compatibility + +--- + +## 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. Replay Record Requirements + +Each propagated record MUST be replayable without external context. Records MUST carry: + +* `domain_id` (source domain) +* `record_type` (artifact, PER, TGK edge, tombstone) +* `logseq` (source-domain ordering) +* `snapshot_id` and `log_prefix` bounds for which the record is visible +* Canonical identity (ArtifactKey or Canonical Edge Key) +* Visibility metadata (internal/published, cross-domain source when applicable) + +Records MAY include optional integrity fields (hashes, signatures), but replay MUST +remain deterministic without them. + +--- + +## 4. Propagation Rules + +### 4.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. +* Imported entries MUST preserve origin metadata (domain identity and visibility). + +### 4.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. + +--- + +## 5. 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. + +--- + +## 6. Snapshot Bounds + +* Replay MUST be bounded by `{SnapshotID, LogPrefix}`. +* Records with `logseq` greater than the replay prefix MUST be ignored. +* Replay MUST use the source domain's `{SnapshotID, LogPrefix}` as the bound for imported state. + +--- + +## 7. Federation View Construction + +Receivers construct a federation view by combining: + +1. Local domain state at `{SnapshotID, LogPrefix}`. +2. Admitted foreign published state bounded by the source domain's `{SnapshotID, LogPrefix}`. + +Admission and policy compatibility MUST be enforced before any foreign state is admitted. + +--- + +## 8. Tombstones and Shadowing + +* Tombstones MUST be replayed in log order and apply only within their source domain. +* A tombstone from domain A MUST NOT shadow artifacts from domain B. +* Shadowing is resolved per-domain using ASL/LOG/1 order and ASL/1-CORE-INDEX semantics. + +--- + +## 9. 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. + +--- + +## 10. Replay State and Idempotency + +Replay MUST be idempotent: + +* Re-applying the same record set MUST NOT change the resulting state. +* Receivers SHOULD track `{domain_id, logseq}` high-water marks per peer. +* Checkpointing MUST be aligned to `{SnapshotID, LogPrefix}` boundaries. + +--- + +## 11. Provenance and Audit + +Receivers SHOULD maintain: + +* Last applied `logseq` per peer +* Snapshot provenance tables for applied records + +This supports deterministic audit and replay verification. + +--- + +## 12. Non-Goals + +* Transport protocol selection +* Streaming formats +* Compression or batching + +--- + +## 13. Summary + +ASL/FEDERATION-REPLAY/1 defines a deterministic replay ordering and conflict rules to ensure federation is reproducible across nodes and snapshots. diff --git a/tier1/asl-policy-hash-1.md b/tier1/asl-policy-hash-1.md new file mode 100644 index 0000000..69af032 --- /dev/null +++ b/tier1/asl-policy-hash-1.md @@ -0,0 +1,159 @@ +# 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 + reserved0 : u32 +} +``` + +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. Defaults and Validation (Normative) + +All fields MUST be present. Defaults apply only to explicit values: + +* `allowed_roles[]` MAY be empty (no roles allowed) +* `trusted_domains[]` MAY be empty (no domains trusted) +* `min_snapshot_retention` MAY be 0 (no minimum) +* `reserved0` MUST be 0 + +A policy is invalid if any boolean is outside {0,1} or if `version` is unsupported. + +--- + +## 5. 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 + +--- + +## 6. Hash Computation + +``` +policy_bytes = CanonicalSerialize(DomainPolicy) +policy_hash = HASH(policy_bytes) +``` + +The hash algorithm is SHA-256 unless explicitly overridden by domain policy. + +--- + +## 7. Storage Locations + +The policy hash SHOULD be stored in: + +* Domain Authority Manifest (DAM) +* Snapshot metadata +* Federation metadata +* Optional PER metadata + +--- + +## 8. 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 + +--- + +## 9. 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.