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

Federation registry
- Tracks known domains, admission status, policy hash, and last admitted {SnapshotID, LogPrefix}.
- Enforces DAP + policy compatibility prior to admitting remote state.
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}.
Resolver
- Resolves ArtifactKey using local store + federation view.
- Does not mutate store/index as part of GET semantics.

Data model (suggested)

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

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:

Local domain internal + published state at local {SnapshotID, LogPrefix}.
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)

Replay ordering determinism across two domains with interleaved logseq.
Tombstone shadowing is domain-local.
Imported record metadata preserved in view and survives rebuild.
Conflict: same ArtifactKey with different bytes across domains rejected.
Bound replay by {SnapshotID, LogPrefix} produces stable view.

5.5 KiB Raw Blame History