@polderlabs/bizar 6.3.0 → 7.0.0

package/packages/sdk/src/federation/policy.ts

@@ -0,0 +1,112 @@
+/**
+ * federation/policy.ts — PolicyEngine: enforces per-call envelope
+ * constraints (maxHops, action allowlist, peer blocklist).
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/application/policy-engine.ts`
+ * but stripped to the three checks the skeleton needs:
+ *
+ *   1. maxHops  — envelope.hopCount must be < budget.maxHops
+ *                 (default ceiling = 3 hops).
+ *   2. message  — envelope.messageType must be in the action
+ *                 allowlist.
+ *   3. peer     — source node must NOT be in the blocklist.
+ *
+ * `enforce(envelope, budget)` returns a discriminated result so
+ * callers can map directly to an MCP error string.
+ */
+
+import {
+  FEDERATION_MESSAGE_TYPES,
+  isFederationMessageType,
+  type EnvelopeBudget,
+  type FederationEnvelope,
+  type FederationMessageType,
+} from "./envelope.js";
+
+/** Hard ceiling on hops — matches the spec's "≤ 3" rule. */
+export const DEFAULT_MAX_HOPS = 3;
+
+export type PolicyDecision =
+  | { allowed: true }
+  | {
+      allowed: false;
+      denialReason:
+        | "max_hops_exceeded"
+        | "message_type_not_allowed"
+        | "peer_blocked"
+        | "budget_missing"
+        | "budget_invalid";
+    };
+
+export interface PolicyConfig {
+  /** Set of message kinds accepted by this node. Defaults to all
+   *  16 ruflo kinds — narrow via `allowedMessageTypes`. */
+  readonly allowedMessageTypes?: readonly FederationMessageType[];
+  /** Set of sourceNodeIds that are NEVER accepted (blocklist). */
+  readonly peerBlocklist?: readonly string[];
+  /** Override the default maxHops ceiling. */
+  readonly maxHops?: number;
+}
+
+export class PolicyEngine {
+  private readonly allowed: Set<FederationMessageType>;
+  private readonly blocked: Set<string>;
+  private readonly maxHops: number;
+
+  constructor(cfg: PolicyConfig = {}) {
+    this.allowed = new Set(cfg.allowedMessageTypes ?? FEDERATION_MESSAGE_TYPES);
+    this.blocked = new Set((cfg.peerBlocklist ?? []).map((s) => String(s)));
+    this.maxHops = cfg.maxHops ?? DEFAULT_MAX_HOPS;
+  }
+
+  /** Runtime mutator — narrow the allowlist after construction. */
+  allowMessageType(t: FederationMessageType): void {
+    this.allowed.add(t);
+  }
+
+  /** Runtime mutator — narrow the allowlist after construction. */
+  denyMessageType(t: FederationMessageType): void {
+    this.allowed.delete(t);
+  }
+
+  /** Runtime mutator — block / unblock a peer at runtime. */
+  setBlocked(nodeId: string, blocked: boolean): void {
+    if (blocked) this.blocked.add(nodeId);
+    else this.blocked.delete(nodeId);
+  }
+
+  /** Admit or reject an envelope given its budget context. */
+  enforce(envelope: FederationEnvelope, budget: EnvelopeBudget | undefined): PolicyDecision {
+    // 0. The budget object must exist — without it we can't enforce
+    // the maxHops ceiling.
+    if (!budget) return { allowed: false, denialReason: "budget_missing" };
+    if (typeof budget.maxHops !== "number" || !Number.isFinite(budget.maxHops)) {
+      return { allowed: false, denialReason: "budget_invalid" };
+    }
+
+    // 1. Peer blocklist
+    if (this.blocked.has(envelope.sourceNodeId)) {
+      return { allowed: false, denialReason: "peer_blocked" };
+    }
+
+    // 2. Message type allowlist
+    if (!isFederationMessageType(envelope.messageType)) {
+      return { allowed: false, denialReason: "message_type_not_allowed" };
+    }
+    if (!this.allowed.has(envelope.messageType)) {
+      return { allowed: false, denialReason: "message_type_not_allowed" };
+    }
+
+    // 3. maxHops — current hopCount must be strictly LESS than the
+    // ceiling. A freshly-origin envelope has hopCount=0 so a
+    // maxHops=3 budget admits it.
+    const hopCount = envelope.hopCount ?? 0;
+    const effectiveCeiling = Math.min(budget.maxHops, this.maxHops);
+    if (hopCount >= effectiveCeiling) {
+      return { allowed: false, denialReason: "max_hops_exceeded" };
+    }
+
+    return { allowed: true };
+  }
+}

package/packages/sdk/src/federation/trust.ts

@@ -0,0 +1,146 @@
+/**
+ * federation/trust.ts — TrustEvaluator: peer allowlist + recent fail
+ * rate + envelope age → trust score.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/application/trust-evaluator.ts`
+ * (computeScore shape), stripped down for the skeleton:
+ *
+ *   evaluate(envelope, peer) → { allowed, reason, score }
+ *
+ * Inputs:
+ *   - peer (PeerState): { nodeId, allowlisted, recentFailRate, lastSeenMs }
+ *   - envelope: FederationEnvelope
+ *
+ * Scoring (pure function):
+ *   baseScore = peer.allowlisted ? 0.6 : 0.0
+ *   freshness  = clamp(1 - ageMs / MAX_AGE_MS, 0, 1) * 0.2
+ *   reliability = clamp(1 - peer.recentFailRate, 0, 1) * 0.2
+ *   score = baseScore + freshness + reliability
+ *
+ * Decision:
+ *   allowed = peer.allowlisted AND ageMs <= MAX_AGE_MS AND score >= MIN_SCORE
+ *
+ * State — per-node recent fail rate + last-seen are tracked
+ * in a Map so repeated calls from the same peer update the
+ * picture. Failures can be recorded via `recordFailure(nodeId)`.
+ */
+
+import { envelopeAgeMs, type FederationEnvelope } from "./envelope.js";
+
+/** Maximum envelope age we'll trust (5 minutes — matches the
+ *  HMAC freshness window). Older envelopes fail freshness
+ *  independently of HMAC verification. */
+export const MAX_TRUST_AGE_MS = 5 * 60 * 1000;
+
+/** Minimum composite trust score required to admit an envelope. */
+export const MIN_TRUST_SCORE = 0.7;
+
+/** Number of recent failures tracked per peer for fail-rate calc. */
+const FAILURE_WINDOW = 20;
+
+export interface PeerState {
+  readonly nodeId: string;
+  readonly allowlisted: boolean;
+  /** Failure rate over the last `FAILURE_WINDOW` calls (0..1). */
+  readonly recentFailRate: number;
+  /** Last activity timestamp (ms epoch). Used as a tiebreaker. */
+  readonly lastSeenMs?: number;
+}
+
+export type TrustDecision =
+  | { allowed: true; score: number; reason: string }
+  | { allowed: false; score: number; reason: string };
+
+export class TrustEvaluator {
+  private readonly allowlist: Set<string>;
+  private readonly failHistory = new Map<string, { failures: boolean[]; lastSeenMs: number }>();
+
+  constructor(opts: { allowlist?: readonly string[] } = {}) {
+    this.allowlist = new Set((opts.allowlist ?? []).map((s) => String(s)));
+  }
+
+  /** Add or remove a node from the trust allowlist at runtime. */
+  setAllowlisted(nodeId: string, allowlisted: boolean): void {
+    if (allowlisted) this.allowlist.add(nodeId);
+    else this.allowlist.delete(nodeId);
+  }
+
+  isAllowlisted(nodeId: string): boolean {
+    return this.allowlist.has(nodeId);
+  }
+
+  /** Snapshot the per-peer state seen by `evaluate()`. */
+  getPeerState(nodeId: string, _now: number = Date.now()): PeerState {
+    const rec = this.failHistory.get(nodeId);
+    const total = rec?.failures.length ?? 0;
+    const failures = rec?.failures.filter((b) => b).length ?? 0;
+    return {
+      nodeId,
+      allowlisted: this.allowlist.has(nodeId),
+      recentFailRate: total === 0 ? 0 : failures / total,
+      lastSeenMs: rec?.lastSeenMs,
+    };
+  }
+
+  /** Record that an exchange with `nodeId` succeeded/failed. Sliding
+   *  window of `FAILURE_WINDOW` most-recent events. */
+  recordOutcome(nodeId: string, ok: boolean, now: number = Date.now()): void {
+    const rec = this.failHistory.get(nodeId) ?? { failures: [], lastSeenMs: now };
+    rec.failures.push(!ok);
+    if (rec.failures.length > FAILURE_WINDOW) rec.failures.shift();
+    rec.lastSeenMs = now;
+    this.failHistory.set(nodeId, rec);
+  }
+
+  /** Compute the trust score (0..1). Pure function — useful for tests
+   *  and for the orchestrator's `status` tool.
+   *
+   *   baseScore  = 0.3 if allowlisted else 0.0  (allowlist is necessary, not sufficient)
+   *   freshness  = (1 - ageMs / MAX_TRUST_AGE_MS) * 0.3  (envelope must be fresh)
+   *   reliability = (1 - peer.recentFailRate) * 0.4  (peer must be reliable)
+   *
+   *   MIN_TRUST_SCORE = 0.5 — a peer needs AT LEAST 2 of the 3 axes
+   *   in good standing to pass.
+   */
+  computeScore(envelope: FederationEnvelope, peer: PeerState, now: number = Date.now()): number {
+    if (!peer.allowlisted) return 0;
+    const baseScore = 0.3;
+    const ageMs = envelopeAgeMs(envelope, now);
+    const freshness = Math.max(0, Math.min(1, 1 - ageMs / MAX_TRUST_AGE_MS)) * 0.3;
+    const reliability = Math.max(0, Math.min(1, 1 - peer.recentFailRate)) * 0.4;
+    return Math.max(0, Math.min(1, baseScore + freshness + reliability));
+  }
+
+  /** Admit or reject an envelope based on the per-peer trust state. */
+  evaluate(envelope: FederationEnvelope, peer: PeerState, now: number = Date.now()): TrustDecision {
+    if (!peer.allowlisted) {
+      return {
+        allowed: false,
+        score: 0,
+        reason: `peer_not_allowlisted: ${peer.nodeId}`,
+      };
+    }
+    const ageMs = envelopeAgeMs(envelope, now);
+    if (ageMs > MAX_TRUST_AGE_MS) {
+      return {
+        allowed: false,
+        score: 0,
+        reason: `envelope_too_old: ${ageMs}ms`,
+      };
+    }
+    const score = this.computeScore(envelope, peer, now);
+    if (score < MIN_TRUST_SCORE) {
+      return {
+        allowed: false,
+        score,
+        reason: `score_below_floor: ${score.toFixed(3)} < ${MIN_TRUST_SCORE}`,
+      };
+    }
+    return {
+      allowed: true,
+      score,
+      reason: `score=${score.toFixed(3)} (peer_allowlisted=true, age=${ageMs}ms, fail_rate=${peer.recentFailRate.toFixed(3)})`,
+    };
+  }
+}

package/packages/sdk/src/index.ts

@@ -44,4 +44,71 @@ export {
 } from "./mcp/server.js";
 export type { SdkMcpToolDef, SdkMcpServerConfig } from "./mcp/server.js";
 
+// F-032 — Swarm coordination primitives.
+export {
+  BizarAgentRegistry,
+  bizarAgentRegistry,
+} from "./agent-registry.js";
+export type {
+  AgentRecord,
+  AgentStatus,
+  RegisterAgentInput,
+  RegisterAgentResult,
+  ListAgentsInput,
+  ListAgentsResult,
+  TerminateAgentInput,
+  TerminateAgentResult,
+} from "./agent-registry.js";
+
+export {
+  SwarmTopologyRegistry,
+  swarmTopologyRegistry,
+  initSwarm,
+  getSwarm,
+  listSwarms,
+  recordAgentInSwarm,
+  decommissionSwarm,
+  SWARM_TOPOLOGIES,
+  DEFAULT_TOPOLOGY,
+  DEFAULT_MAX_AGENTS,
+  DEFAULT_SWARM_ID,
+} from "./swarm-topology.js";
+export type {
+  SwarmRecord,
+  SwarmTopology,
+  InitSwarmInput,
+  InitSwarmResult,
+} from "./swarm-topology.js";
+
+// F-039 — Byzantine fault-tolerant consensus (thin PBFT port).
+export {
+  ByzantineConsensus,
+  type ByzantineConsensusOpts,
+  QueenCoordinator,
+  type QueenCoordinatorOpts,
+  createConsensus,
+  getSharedConsensus,
+  resetSharedConsensus,
+  type ConsensusHandle,
+  type CreateConsensusOpts,
+  PHASE_ORDER,
+  DEFAULT_QUORUM,
+  DEFAULT_PEER_COUNT,
+  DEFAULT_MAX_FAULTS,
+} from "./consensus/index.js";
+export type {
+  CommitResult,
+  ConsensusOpts,
+  ConsensusStatus,
+  Decision,
+  Phase,
+  ProposeResult,
+  Proposal,
+  ProposalSnapshot,
+  ProposalStatus,
+  Vote,
+  VoteResult,
+  ViewChangeResult,
+} from "./consensus/types.js";
+
 export { SDK_VERSION } from "./version.js";