Skip to content

ARC-ADR-058 — Sharded Holonic Board Coordination

One line: How the platform shards and isolates the global graph backlog into lightweight, branch-scoped board shards to prevent write collisions and query bottlenecks across parallel agent swarms.

Context and Problem Statement

The Holonic Unified Board Architecture (ARC-ADR-035) establishes a graph-first work management registry stored in ArcadeDB. However, as the fleet scales to hundreds of parallel agent runtimes, a single monolithic board creates severe operational constraints: - Query Saturation: Hundreds of agents querying the global graph backlog concurrently creates database locks and raises read latency. - Context Overflow: Fetching the entire backlog forces agents to process irrelevant tasks, bloating their LLM context windows and increasing token costs. - State Write-Collisions: Sibling agents working on related features risk writing conflicting status transitions or modifying the same task cards concurrently, leading to split-brain. - Security & Scope Bleed: Standard Kanban boards do not restrict write access at the file-territory or component level, risking unauthorized task alterations by autonomous agents.

We need a way to partition (shard) the board into branch-scoped, isolated task contexts that agents can consume safely and efficiently.

Decision Drivers

  • Safe Scope Isolation: Agents must only query and mutate task nodes within their assigned workspace bounds.
  • Sub-100ms Query Latency: Task lists and kanban visual states must load instantly.
  • Asymmetric Concurrency: Humans and multiple agent swarms must read and modify task states in parallel without lock-file collisions.
  • Style & Branding Consistency: Visual board renderers must represent safety constraints, blocked dependencies, and task ownership scopes using our W3C DTCG design system tokens.

Considered Options

Option A — Monolithic Global Query Scoping

Keep a single global graph database and enforce agent boundaries via runtime SQL/Cypher filters in the REST API. - Pros: - Simple database setup (single ArcadeDB instance). - No complex merge/synchronization cycles between board views. - Cons: - Database bottleneck under concurrent agent query loads. - No physical isolation: if the API filter fails, agents can see and write to any task card in the organization. - High query latency when traversing nested parent-child trees dynamically.

Option B — Virtual Git-Backed Board Shards (Folder-as-Board)

Store task cards as structured files (e.g. JSON files) inside the repository's .agent/tasks/ directory, letting our Holographic Virtual Filesystem (HVFS) handle versioning, branching, and merges. - Pros: - Inherits VFS zero-copy branching, staging, and sub-millisecond execution speeds. - Merging task moves uses standard VFS merge and conflict resolution. - Cons: - Graph query capabilities (SPARQL, traversal) are lost on flat file structures. - High UI rendering cost (requires parsing and parsing files instead of indexing DB nodes).

Option C — Sharded Holonic Board Coordination (Chosen)

Partition the global backlog graph into isolated, branch-scoped Board Shards (SQLite databases in local agent workspaces), synchronized asynchronously with the master ArcadeDB registry via event streams and Hybrid Logical Clock (HLC) merges. - Pros: - Complete Read Isolation: The agent only sees tasks in its local SQLite board shard (matches its active CapabilityGrant scope). - Lock-Free Concurrency: Multiple writers commit changes to separate local shards concurrently. - Durable Merges: Changes are synchronized back to the ArcadeDB master using HLC timestamps (ARC-ADR-038) to resolve status collisions safely. - Cons: - Requires maintaining metadata synchronization between SQLite shards and ArcadeDB.

Decision

Adopt Option C (Sharded Holonic Board Coordination). Implement database-backed board sharding, separating active agent workspaces into isolated task views mapped to their git branches.

1. Board Shard Projection Lifecycle

    [ ArcadeDB Master Graph ] (Global Backlog)
               │
      Create Workspace Branch
               │
               ▼
     [ Board Shard Projector ] (Filters by CapabilityGrant)
               │
               ▼
      [ Local SQLite Shard ] (Workspace Board) 
        - Epics / Features / Stories in active branch
        - Local changes written instantly (status: done, etc.)
               │
         Commit / Merge
               │
               ▼
     [ HLC Sync Engine ] (Resolves conflicts via ARC-ADR-038)
               │
               ▼
    [ ArcadeDB Master Graph ] (Aggregated state)
  1. Workspace Projection: When an agent checks out a branch (ut vfs checkout task-wi-302), the UDA projector fetches the task subgraph matching the agent's CapabilityGrant scope and materializes a local SQLite database (.vfs_board.db) in the agent workspace.
  2. Local Mutations: The agent queries and updates tasks locally via standard SQL commands against .vfs_board.db (zero network latency).
  3. Upstream Synchronization: When the agent commits (ut vfs commit), VFS uploads the local database transaction logs. The sync engine processes events chronologically using HLC timestamps, updating the global ArcadeDB graph.

2. UI Safety-Style Boundaries

Any visual rendering of board shards in our frontend console (React/D3) must enforce the design system tokens (theme.css) to represent safety boundaries:

  • Clearance Borders: Delegated feature scopes are surrounded by a brand purple (#7c3aed) outline, signaling the agent's active execution boundaries.
  • Blocked Edges: Task cards carrying open Blocker relators are rendered in semantic red (#ef4444) with a pulse animation.
  • Ownership Tones: Cards assigned to active autonomous swarms display a lime (#84cc16) status glow, distinguishing them from human-assigned tasks (zinc slate).

Consequences

  • + Sub-Millisecond Queries: Local SQLite reads eliminate API network calls during agent execution loops.
  • + Zero Collision Hazards: Sibling swarms modify separate SQLite databases; database index locks do not block threads.
  • + Built-In Compliance Audit: All board changes flow through event-sourced logs, verifying that every task status transition is linked to an authorized CapabilityGrant and a resolving Decision.
  • − Merge Conflicts: Parallel modifications to the same story status must be resolved via the HLC sync engine (mitigated by aborting and escalating to HITL coordinator if conflicts overlap).
  • − Sync Overhead: Adds synchronization latency when a human updates a card on the global cockpit (requires NATS push events to invalidate active SQLite shards).

Alternatives Considered

  • Git-backed JSON Boards (Option B): Rejected because it forces the UI to parse large JSON files for graphs, leading to low FPS rendering and lack of SPARQL capabilities.