amduat-api/notes/asl-federation.md

# ASL-FEDERATION SPECIFICATION

---

## 1. Purpose

The Federation Specification defines the **multi-domain model** for ASL-based storage systems, including:

* Domains: logical separation of artifacts and snapshots
* Published vs internal state
* Cross-domain visibility rules
* Snapshot identity and consistency guarantees
* Integration with index, store, PEL, and provenance layers

It ensures **determinism, traceability, and reproducibility** across federated deployments.

---

## 2. Core Concepts

| Term                       | Definition                                                                                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Domain**                 | A logical namespace or administrative boundary for artifacts and snapshots. Each domain manages its own set of artifacts, blocks, and snapshots. |
| **Published state**        | Artifacts, blocks, and snapshots exposed outside the domain.                                                                                     |
| **Internal state**         | Artifacts, blocks, and snapshots restricted to a domain; not visible to other domains.                                                           |
| **Snapshot identity**      | Globally unique identifier for a snapshot within a domain; used to reconstruct CURRENT.                                                          |
| **Cross-domain reference** | An artifact in one domain referencing a published artifact from another domain.                                                                  |

---

## 3. Domain Semantics

1. **Domain isolation**

   * Each domain has its own CAS/ASL storage and index layers.
   * Artifacts and blocks in internal state are **invisible outside the domain**.

2. **Published state**

   * Artifacts marked as published are **visible to other domains**.
   * Published artifacts must satisfy **full ASL-STORE-INDEX invariants**: deterministic, immutable, snapshot-safe.

3. **Cross-domain artifact references**

   * Only **published artifacts** may be referenced by other domains.
   * References are **read-only**; the referenced artifact cannot be modified in the original domain.
   * Indexed in the consuming domain as standard `ArtifactKey → ArtifactLocation`.

4. **Federated snapshots**

   * Snapshots in each domain maintain **local visibility** for internal state.
   * Published snapshots may be **federated** to other domains to expose deterministic CURRENT state.

---

## 4. Snapshot Identity

* **Domain-local snapshot IDs** are unique per domain.
* **Federated snapshot IDs** combine domain ID + local snapshot ID.

  * Ensures **global uniqueness** across federation.
* **Snapshot references** may include cross-domain artifacts, but the mapping is **immutable and deterministic**.

---

## 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:

  * Only entries pointing to visible artifacts/blocks are visible in a domain’s CURRENT.
  * Determinism is guaranteed per domain’s view of CURRENT.

---

## 6. Cross-Domain Operations

1. **Import published artifacts**

   * A domain may import a published artifact from another domain.
   * The imported artifact is **treated as immutable**; its original domain cannot alter it.
   * Execution receipts may include imported artifacts as inputs.

2. **Export published artifacts**

   * Internal artifacts may be **promoted** to published state.
   * Requires sealing and pinning to snapshot for determinism.
   * Once published, the artifact may be referenced by other domains.

3. **Federation log / synchronization**

   * Each domain maintains its **own append-only log**.
   * Published changes can be propagated to other domains via log replication.
   * Snapshot + log replay ensures deterministic reconstruction across domains.

---

## 7. Provenance & Traceability

* **Execution receipts** can include cross-domain references.

* **Trace graphs** preserve:

  * Original domain of artifacts
  * Snapshot ID in the original domain
  * Deterministic DAG execution per snapshot

* **Provenance guarantees**:

  1. Artifact immutability
  2. Deterministic execution reproducibility
  3. Traceable lineage across domains

---

## 8. Normative Invariants

1. **Determinism:** Reconstructing CURRENT in any domain yields the same artifact graph given the same snapshot + log.
2. **Immutability:** Published artifacts and snapshots cannot be modified.
3. **Domain isolation:** Internal artifacts are never exposed outside their domain.
4. **Federation safety:** Cross-domain references are read-only and preserve deterministic execution.
5. **Snapshot integrity:** Federated snapshots reference only published artifacts; replay reproduces CURRENT.

---

## 9. Integration with Existing Layers

| Layer                | Role in Federation                                                                             |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| ASL-CORE             | Blocks and artifacts remain immutable; no change                                               |
| ASL-CORE-INDEX       | Artifact → Block mapping is domain-local; published artifacts are indexed across domains       |
| ASL-STORE-INDEX      | Sealing, retention, and snapshot pinning apply per domain; GC respects cross-domain references |
| ENC-ASL-CORE-INDEX   | Encoding of index entries may include domain and visibility flags for federation (`tier1/enc-asl-core-index.md`) |
| PEL                  | DAG execution may include imported artifacts; determinism guaranteed per domain snapshot       |
| PEL-PROV / PEL-TRACE | Maintains provenance including cross-domain artifact lineage                                   |

---

## 10. Summary

The Federation Specification formalizes:

* Domains and logical separation
* Published vs internal state
* Cross-domain artifact visibility and reference rules
* Snapshot identity and deterministic reconstruction across domains
* Integration with index, store, PEL, and provenance layers

It ensures **multi-domain determinism, traceability, and reproducibility** while leaving semantics and storage-layer policies unchanged.