amduat-api/docs/federation-coordinator.md

# Federation Coordinator Middle Layer Spec

This document specifies the middle-layer coordinator that orchestrates federation
above the core C substrate. It remains transport- and policy-aware while keeping
core semantics unchanged.

## Scope and Goals

- Maintain per-domain replay bounds and an admitted set.
- Fetch and ingest published records from remotes.
- Build federation views via core APIs.
- Resolve missing bytes by fetching artifacts into a cache store.
- Keep storage layout private (no extents or blocks exposed).
- Align with tier1 federation semantics and replay determinism.
- Federation view is the union of admitted domains regardless of topology.

Non-goals:
- Re-implement core semantics in this layer.
- Introduce a single global snapshot ID (federation is per-domain).

## Core Dependencies

The coordinator calls into vendor core APIs (`vendor/amduat/include/amduat/fed/*`)
and MUST stay aligned with their signatures:

- `amduat_fed_registry_*` (persist per-domain admission state)
- `amduat_fed_ingest_validate` (record validation + conflict detection)
- `amduat_fed_replay_build` (deterministic replay per domain)
- `amduat_fed_view_build` + `amduat_fed_resolve` (build view and resolve ref-only)

Core expects per-domain replay bounds `{domain_id, snapshot_id, log_prefix}` and
does not handle transport, auth, caching policy, or remote fetch.

Alignment note: the daemon-layer API in this repo still needs updates to match
current vendor core types and signatures. This spec reflects vendor headers as
the source of truth.

Tier1 alignment (normative):
- `ASL/FEDERATION/1`
- `ASL/FEDERATION-REPLAY/1`
- `ASL/DOMAIN-MODEL/1`
- `ASL/POLICY-HASH/1`
- `ENC/ASL-CORE-INDEX/1` (canonical in `vendor/amduat/tier1/enc-asl-core-index-1.md`)

## Data Structures

### Registry State (per domain, persisted)
```
struct amduat_fed_domain_state {
  uint32_t domain_id;
  uint64_t snapshot_id;
  uint64_t log_prefix;
  uint64_t last_logseq;
  uint8_t admitted;
  uint8_t policy_ok;
  uint8_t reserved[6];
  amduat_hash_id_t policy_hash_id;
  amduat_octets_t policy_hash; /* Empty when unknown; caller-owned bytes. */
};
```

Registry bytes are stored via `amduat_fed_registry_store_*` in the local ASL
store; the coordinator owns admission workflows and policy compatibility checks.

### Admitted Set (in-memory)
```
struct amduat_fed_admitted_set {
  uint32_t *domain_ids;  // sorted, unique
  size_t len;
};
```

The admitted set is derived from registry entries with `admitted != 0` and
`policy_ok != 0`.

### Snapshot Vector (per view build)
```
struct amduat_fed_snapshot_vector {
  amduat_fed_view_bounds_t *bounds;
  size_t len;
  uint64_t vector_epoch;
};
```

### Record Staging (per fetch batch)
```
struct amduat_fed_record {
  amduat_fed_record_meta_t meta;
  amduat_fed_record_id_t id;
  uint64_t logseq;
  uint64_t snapshot_id;
  uint64_t log_prefix;
};
```

Records MUST carry the fields required by `ASL/FEDERATION-REPLAY/1`, and replay
ordering MUST be deterministic (sort by `logseq`, then canonical identity).
Record metadata includes visibility and optional cross-domain source identity.

### View and Policy Denies
```
struct amduat_fed_view_bounds {
  uint32_t domain_id;
  uint64_t snapshot_id;
  uint64_t log_prefix;
};

struct amduat_fed_policy_deny {
  amduat_fed_record_id_t id;
  uint32_t reason_code;
};
```

### Fetch Backlog / Retry State
```
struct amduat_fed_fetch_state {
  uint32_t domain_id;
  uint64_t next_snapshot_id;
  uint64_t next_log_prefix;
  uint64_t next_logseq;
  uint64_t backoff_ms;
  uint64_t last_attempt_ms;
  uint32_t consecutive_failures;
};
```

### Cache Store Metadata (optional)
```
struct amduat_fed_cache_policy {
  bool enabled;
  uint64_t max_bytes;
  uint64_t used_bytes;
  uint32_t ttl_seconds;
  uint32_t prefetch_depth;
};
```

## Coordinator Interfaces

### Configuration
```
struct amduat_fed_coord_cfg {
  const char *registry_path;
  amduat_asl_store_t *authoritative_store;
  amduat_asl_store_t *cache_store;    // optional
  amduat_asl_store_t *session_store;  // optional
  amduat_fed_transport transport;
  amduat_fed_cache_policy cache_policy;
  amduat_fed_policy_hooks policy_hooks;
};
```

### Lifecycle and Operations
```
int amduat_fed_coord_open(
    const struct amduat_fed_coord_cfg *cfg,
    struct amduat_fed_coord **out);

int amduat_fed_coord_close(struct amduat_fed_coord *c);

int amduat_fed_coord_load_registry(struct amduat_fed_coord *c);

int amduat_fed_coord_set_admitted(
    struct amduat_fed_coord *c,
    uint32_t domain_id,
    bool admitted);

int amduat_fed_coord_tick(struct amduat_fed_coord *c, uint64_t now_ms);

int amduat_fed_coord_resolve(
    struct amduat_fed_coord *c,
    amduat_reference_t ref,
    amduat_artifact_t *out);
```

## API Status

Planned coordinator surface (not yet implemented):
- `amduat_fed_coord_open`
- `amduat_fed_coord_close`
- `amduat_fed_coord_load_registry`
- `amduat_fed_coord_set_admitted`
- `amduat_fed_coord_tick`
- `amduat_fed_coord_resolve`

Implemented in core (already available):
- `amduat_fed_registry_*`
- `amduat_fed_ingest_validate`
- `amduat_fed_replay_build`
- `amduat_fed_view_build`
- `amduat_fed_resolve`

## Transport Abstraction

Minimal interface that hides protocol, auth, and topology:
```
struct amduat_fed_transport {
  int (*get_records)(
      void *ctx, uint32_t domain_id,
      uint64_t snapshot_id, uint64_t log_prefix,
      uint64_t from_logseq,
      amduat_fed_record_iter *out_iter);

  int (*get_artifact)(
      void *ctx, amduat_reference_t ref,
      amduat_sink *out_sink);
};
```

Transport MUST return records that can be validated with `amduat_fed_record_validate`
and MUST provide all fields required by `ASL/FEDERATION-REPLAY/1`.
Transport MUST NOT surface internal-only records from foreign domains.

## Storage and Encodings

- The coordinator stores records/artifacts via ASL store APIs and does not touch
  segment layouts or extents directly.
- Federation metadata in index records is encoded by core per
  `ENC/ASL-CORE-INDEX/1`; the coordinator must not override it.
- Cache store semantics are best-effort and do not affect authoritative state.

## Policies

- Admission is per-domain and controlled via registry entries and `policy_ok`.
- Policy compatibility uses `policy_hash_id` + `policy_hash` (ASL/POLICY-HASH/1).
- `policy_ok` is computed during admission by comparing local policy hash to the
  remote domain's published policy hash.
- Admission and policy compatibility MUST be enforced before any foreign state is
  admitted into the federation view.
- Per-record filtering, if used, MUST be deterministic and SHOULD be expressed
  as policy denies passed to `amduat_fed_view_build` rather than by dropping
  records before validation.
- Cache write policy is middle-layer only (fetch-on-miss, optional prefetch).
- Eviction is local (LRU or segmented queues) and must not leak layout.
- Conflict policy: reject on identity collision with differing metadata and keep
  bounds stable until operator intervention (ASL/FEDERATION-REPLAY/1).

## Sequencing and Consistency

- Deterministic views require a stable snapshot vector per build.
- Bounds advance only after successful ingest; they never move backwards.
- Before validation, records are ordered by `(logseq, canonical identity)` and
  filtered to `logseq <= log_prefix`.
- Tombstones and shadowing apply only within the source domain.
- Use `vector_epoch` to swap snapshot vectors atomically after a build.
- Persist registry updates atomically via `amduat_fed_registry_store_put` before
  swapping the snapshot vector.
- If a remote retracts or regresses, keep local bounds and mark domain degraded.

## Core Flow

### Startup
- Load registry.
- Derive admitted set from `admitted != 0` and `policy_ok != 0`.
- Build initial snapshot vector.

### Periodic Tick
- For each admitted domain, fetch records up to bound and validate.
- Update `last_logseq`, and advance bounds if remote snapshot moves forward.
- Build federation view using `amduat_fed_view_build` over the staged records,
  with optional policy denies derived from coordinator hooks.
- Swap snapshot vector atomically after registry updates.

### Resolve Loop
- Call `amduat_fed_resolve` against the latest built `amduat_fed_view_t`.
- If `AMDUAT_FED_RESOLVE_FOUND_REMOTE_NO_BYTES`, fetch bytes via transport into cache store.
- Retry resolve after cache write completes.

## Example Tick Pseudocode
```
int amduat_fed_coord_tick(struct amduat_fed_coord *c, uint64_t now_ms) {
  amduat_fed_snapshot_vector vec = build_snapshot_vector(c);
  clear(staged_records_all);
  build_policy_denies(&policy_denies, &policy_denies_len);

  for each domain in vec.bounds:
    bound = &vec.bounds[i];
    if !admitted(bound->domain_id) continue;
    if backoff_active(bound->domain_id, now_ms) continue;

    clear(staged_records);
    iter = transport.get_records(
        bound->domain_id,
        bound->snapshot_id,
        bound->log_prefix,
        state.next_logseq);
    while iter.next(record):
      if !amduat_fed_record_validate(&record):
        mark_domain_error(bound->domain_id);
        break;
      append(staged_records, record);

    sort_by_logseq_then_id(staged_records);
    clamp_to_log_prefix(staged_records, bound->log_prefix);

    rc = amduat_fed_ingest_validate(
        staged_records, staged_len, &err_index, &conflict_index);
    if rc == AMDUAT_FED_INGEST_ERR_CONFLICT:
      mark_domain_error(bound->domain_id);
      continue;
    if rc == AMDUAT_FED_INGEST_ERR_INVALID:
      mark_domain_error(bound->domain_id);
      continue;

    update_registry_bounds(bound->domain_id, state);
    append_all(staged_records_all, staged_records);

  amduat_fed_view_build(
      staged_records_all, staged_len_all,
      local_domain_id, vec.bounds, vec.len,
      policy_denies, policy_denies_len,
      &view);
  swap_snapshot_vector(c, build_snapshot_vector(c));
  return 0;
}
```

## Example Resolve Pseudocode
```
int amduat_fed_coord_resolve(
    struct amduat_fed_coord *c,
    amduat_reference_t ref,
    amduat_artifact_t *out) {
  view = c->last_view;
  rc = amduat_fed_resolve(&view, c->authoritative_store, ref, out);
  if (rc == AMDUAT_FED_RESOLVE_FOUND_REMOTE_NO_BYTES && c->cache_store) {
    rc = transport.get_artifact(ref, sink_for_cache(c->cache_store));
    if (rc == 0) {
      rc = amduat_fed_resolve(&view, c->authoritative_store, ref, out);
    }
  }
  return rc;
}
```

## Coordinator Wiring Example

```
amduat_fed_transport_unix_t unix_transport;
amduat_fed_coord_cfg_t cfg;
amduat_fed_coord_t *coord = NULL;

amduat_fed_transport_unix_init(&unix_transport, "amduatd.sock");
memset(&cfg, 0, sizeof(cfg));
cfg.local_domain_id = 1;
cfg.authoritative_store = &store;
cfg.cache_store = &cache_store;
cfg.transport = amduat_fed_transport_unix_ops(&unix_transport);

if (amduat_fed_coord_open(&cfg, &coord) == AMDUAT_FED_COORD_OK) {
  amduat_fed_coord_tick(coord, now_ms);
  amduat_fed_coord_resolve(coord, some_ref, &artifact);
  amduat_fed_coord_close(coord);
}
```