π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): ADR-101 federation status β Proposed β Accepted (Implemented)
Reuvend93fffa8dcc1
diff --git a/v3/docs/adr/ADR-101-federated-claims.md b/v3/docs/adr/ADR-101-federated-claims.mdindex 1a3677418e..0c9a88cd1b 100644--- a/v3/docs/adr/ADR-101-federated-claims.md+++ b/v3/docs/adr/ADR-101-federated-claims.md@@ -1,10 +1,10 @@# ADR-101: Federated Claims β Cross-Node Work Coordination via the Federation Plane-**Status**: Proposed-**Date**: 2026-05-05-**Version**: target v3.8.0 (post v3.7.x stabilization)+**Status**: Accepted β Implemented (Phases 1β3 + Component C wiring landed)+**Date**: 2026-05-05 (proposed) Β· **Updated**: 2026-05-09+**Version**: shipped in `@claude-flow/[email protected]` and `@claude-flow/[email protected]`**Supersedes**: nothing-**Related**: ADR-086 (Agent Federation), ADR-097 (Federation budget circuit breaker), commit `6f495369` (G2 Ed25519 signing in federation), `v3/@claude-flow/claims/` (existing local-only claims module), `v3/@claude-flow/plugin-agent-federation/` (existing federation runtime)+**Related**: ADR-086 (Agent Federation), ADR-097 (Federation budget circuit breaker), ADR-102 (CI smoke harness β federation policy-engine fix attested via witness), commit `6f495369` (G2 Ed25519 signing), `v3/@claude-flow/claims/`, `v3/@claude-flow/plugin-agent-federation/`## Context@@ -261,8 +261,67 @@ A separate `@claude-flow/federated-claims` that depends on both `@claude-flow/cl- The existing `IClaimRepository` and `IClaimEventStore` interfaces are already the right extension points. A sibling package would either duplicate them or re-export them, both of which add noise.- npm dependency graphs already track this fan-in; a sibling package buys nothing the existing package can't deliver via opt-in DI.+## Implementation status (2026-05-09)++All three phases are landed and present on `main`. Component C's+policy-engine wiring was completed as a follow-on fix during the+2026-05-08 CI cleanup. Witness manifest now attests the load-bearing+markers across the federation surface.++| Phase / Component | Status | Files | Commit(s) |+|---|---|---|---|+| **Phase 1** β HLC clock + skew-tolerant timestamps | Implemented | `v3/@claude-flow/claims/src/infrastructure/hlc.ts` + tests | `1f826fb9b feat(claims): ADR-101 Phase 1` |+| **Phase 2** β Federated repository + event-store adapters | Implemented | `claims/src/infrastructure/federated-claim-repository.ts`, `federated-event-store.ts`, `event-store.ts` + tests | `edc39f7da feat(claims): ADR-101 Phase 2` |+| **Phase 3** β Attested handoff envelopes (`claim-event`, `agent-handoff` message types) | Implemented | `plugin-agent-federation/src/domain/entities/federation-envelope.ts:17β19` | `cc6af4b77 feat(federation): ADR-101 Phase 3` |+| **Phase 3 follow-on** β `CLAIMS_FOR_MESSAGE_TYPE` policy-engine wiring | Implemented (2026-05-08) | `plugin-agent-federation/src/application/policy-engine.ts:65β73` | `3ba0b6141 fix(plugin-agent-federation): add CLAIMS_FOR_MESSAGE_TYPE entries for ADR-101 Component C` |+| **Phase 4** β Soak test, version bump, witness regen | Witness regen done; soak test deferred | `verification.md.json` (#82 entry, marker `'agent-handoff': ['federation:write', 'federation:spawn']`) | `779eb309b chore(witness): register ADR-101-C federation fix as #82` |++Combined merge: PR `#1777` brought Phases 1β3 onto `main` as `9d4a9ea96`.++### Claim-type mapping (Component C wiring)++The `CLAIMS_FOR_MESSAGE_TYPE` `Record` in `policy-engine.ts` was missing+entries for the two new ADR-101 message types after Phase 3 landed,+which broke `Build V3` for 3+ days (TS2739 exhaustiveness error). The+follow-on fix added:++```ts+'claim-event': ['federation:write'], // same shape as task-assignment+'agent-handoff': ['federation:write', 'federation:spawn'], // state mutation + agent-lifecycle authority+```++Rationale: `claim-event` is a broadcast of state mutation across peers+(matches `task-assignment`'s authorization shape). `agent-handoff`+reshapes who owns work β sibling of `agent-spawn` β so it requires+both write authority and spawn-lifecycle authority. Both fit the+consensus-required posture this ADR specifies.++### Regression coverage++- **Witness marker** (`#82` in `verification.md.json`): file `plugin-agent-federation/dist/application/policy-engine.js`, marker string `'agent-handoff': ['federation:write', 'federation:spawn']`. A future regression that drops either entry triggers `markerVerified=false` in CI's `witness-verify` job before reaching users.+- **TypeScript exhaustiveness check** on `Record<FederationMessageType, FederationClaimType[]>` is the compile-time safety net β adding a new `FederationMessageType` member without a `CLAIMS_FOR_MESSAGE_TYPE` entry breaks `Build V3`. (This is what surfaced the original gap.)++### Open questions resolved during implementation++| Original question | Resolution |+|---|---|+| Trust registry β share or separate? | Shared, gated by `CLAIMS_MIN_TRUST` config (default `WORKING`). |+| Behavior on partition? | Continue independently for non-causal events; fail-closed for handoffs (matches the consensus-required gate). |+| Vector clock GC? | Not yet implemented; deferred. Tracked as a follow-up issue (no incidents from accumulation observed in soak runs to date). |++### Deferred++- **Phase 4 soak test (3 nodes Γ 30 min Γ 1000 claims Γ 200 handoffs/min)** β not yet run on CI. Local soak runs have completed cleanly during development. Promoting to scheduled CI job is a follow-up; the witness marker provides the regression-detection floor in the interim.+- **Vector-clock GC via `peer-status: EVICTED`** β depends on ADR-097 Phase 2/3 EVICT events landing; partial dependency unblocked.+- **`CLAIMS_FEDERATION_ENABLED` feature flag** β implemented as documented but defaulting to `true` rather than `false` because the implementation cleared all gating concerns during PR review. If a user-visible regression surfaces, re-gating is a single-commit revert.++---+## Implementation plan+> Historical reference β the plan as proposed in 2026-05-05. See+> "Implementation status" above for what actually shipped.+Three phases, each independently mergeable. Each phase ships behind the feature flag `CLAIMS_FEDERATION_ENABLED` (default `false` until v3.8.0).### Phase 1 β HLC clock + skew-tolerant comparisons (1β2 days)