KBLayerComposer

KBLayerComposer.compose_recall composes recall across the four canonical layer scopes:

Scope	Source	Precedence
PRIVATE	The tenant's own silo	0 (highest)
HIERARCHICAL	Parent organisation (read-only, replicated)	1
MARKETPLACE	Subscribed external corpora (federated)	2
GLOBAL	Curated read-only platform corpus	3 (lowest)

Smaller precedence wins.

Resolution flow

1. resolve_layers(ctx) returns the active LayerHandle list for the tenant. Defaults to [PRIVATE]; populates the other three when the tenant's kb_subscriptions rows + parent-org link + global-corpus replication offsets are set.
2. For each layer, fan out the recall:
   • PRIVATE runs against the tenant's own IMemoryEngine (default HierarchicalRAGAdapter).
   • HIERARCHICAL / MARKETPLACE / GLOBAL run against the alphaswarm_kb_federation reverse-proxy when the layer has a federation_endpoint.
3. Apply BitemporalMerger.merge_layers to dedupe by entity id with precedence-aware ordering. Losers land in metadata.dissenting_layers.
4. Re-rank by (precedence, score, recency).

Conflict resolution

Conflict	Resolution
Same entity, different value	Higher-precedence layer wins; loser exposed in dissenting_layers.
Temporal disagreement (valid_to/valid_from overlap)	Both kept; downstream as_of reconstructs the timeline.
Edge contradiction (new edge supersedes old)	Old edge's expired_at = now(); not deleted.

Caching + invalidation

• Per-subscriber result cache keyed by (subscriber_tenant, source_tenant, dataset, query_hash) with a 60s TTL (default).
• OpenFGA Watch events for subscription.{granted,revoked,updated} flush impacted cache entries via the alphaswarm:kb:bitmap Redis pub/sub channel.

When NOT to use compose_recall

• Single-corpus recall against your tenant's own private corpus → use data.kb.recall (faster, no federation overhead).
• Bulk re-indexing / improve / forget — these are always per-corpus.