Skip to main content

colony_kernel

Version: v1.3.0 | Status: Active | Last Updated: July 2026

Purpose​

The Colony Kernel is a proposal-evaluation control plane for codomyrmex's artificial ecology thesis: a codebase is treated as a colony in which agents, modules, and human operators interact through a process-local signal field. Subsystems deposit chemical-analogy traces carrying success, failure, risk, and dependency information, and the kernel evaluates proposals against the accumulated field, reported consequence history, budget state, completeness, and agent trust. A proposal touching a location with strong FAILURE or RISK pressure faces a higher gate barrier than an otherwise identical proposal at a clean target. Caller-reported outcomes update the field and trust profile, while pruning scans nominate candidates for review. The ordinary MCP path remains caller-reported and unattested. Optional and required direct-kernel modes add a signed, hash-linked local proposal→verdict→authorization→receipt→outcome ledger; that ledger still does not observe external actuation, enforce downstream actions, or establish production benefit.

Architecture​

The kernel wires eight cooperating responsibilities. models.py supplies shared value objects, while ColonyKernel explicitly sequences falsification, budget, role, gate, consequence, signal, and pruning operations. Cross-subsystem dependencies are documented rather than hidden.

graph TB
    CK["ColonyKernel<br/>Top-level integration"]
    subgraph subsystems["Colony Control Plane — 8 Subsystems"]
        PS["PheromoneStore<br/>Stigmergy + Signal semantics"]
        RL["ResourceLedger<br/>7-dimension budget"]
        AG["ActuationGate<br/>Weighted additive score"]
        CM["ConsequenceMemory<br/>SQLite + Trust deltas"]
        RA["RoleAdapter<br/>Deterministic role ladder"]
        PD["PruningDaemon<br/>Stale module detection"]
        FW["FalsificationWorker<br/>10 adversarial vectors"]
    end

    CK --> PS & RL & AG & CM & RA & PD & FW
    FW --> AG
    PS --> AG
    CM --> RA

    style CK fill:#1e3a8a,color:#fff,stroke:#3b82f6
    style AG fill:#7c3aed,color:#fff
    style PS fill:#0f766e,color:#fff
    style RL fill:#0f766e,color:#fff
    style CM fill:#0f766e,color:#fff
    style RA fill:#0f766e,color:#fff
    style PD fill:#0f766e,color:#fff
    style FW fill:#0f766e,color:#fff

Quick Start​

from codomyrmex.colony_kernel.kernel import ColonyKernel
from codomyrmex.colony_kernel.models import ActionProposal, ResourceCost

# Instantiate once per process — all subsystem state lives here.
kernel = ColonyKernel()

# Propose an action: falsification, budget, and trust checks run automatically.
proposal = ActionProposal(
    agent_id="engineer-1",
    agent_type="repair_agent",
    action_type="patch_file",
    target="codomyrmex.git_operations.core",
    rationale="Fix off-by-one error in branch name parser identified in test_branch_names.py",
    expected_outcome="All 42 git_operations tests pass with no regressions",
    budget_estimate=ResourceCost(llm_calls=3, runtime_seconds=12.0, risk_level=0.1),
    rollback_plan="git revert HEAD~1 if tests fail post-merge",
    evidence={"test_ids": ["test_branch_names.py::test_slash_in_name"]},
)

result = kernel.propose_action(proposal)
print(result.decision)   # GateDecision.REFUSE for a brand-new SANDBOX agent
print(result.gate_score) # 0.0 on the SANDBOX hard-override path

# Ordinary outcome reporting is a separate, caller-driven operation. It is
# available when attestation is disabled (the default) or optional.
record = kernel.record_outcome(
    proposal=proposal,
    outcome={"summary": "patch applied; git rebase succeeded", "repair_needed": False},
    tests_passed=True,
    human_feedback="good",
)
print(record.trust_delta)  # positive delta added to engineer-1's profile

# Inspect colony state.
status = kernel.colony_status()
print(status["budget_usage"]["llm_calls"])  # {"used": 3, "max": 500}

# Advance one tick — evaporates pheromone traces.
kernel.tick()

For a locally authenticated lifecycle, construct ColonyKernelConfig(attestation_mode="required", attestation_secret_key=...), then call propose_action(), authorize_execution(), record_execution_receipt(), and record_attested_outcome() in order. Required mode rejects every direct record_outcome() call, including one made after a receipt, so the outcome event cannot bypass the ledger. This establishes local linkage and tamper detection; receipt content and outcome content are still supplied by callers and are not independent observations of an external tool or environment.

The Core Loop​

The colony runs a continuous seven-phase cycle:

sequenceDiagram
    participant Agent
    participant CK as ColonyKernel
    participant FW as FalsificationWorker
    participant RL as ResourceLedger
    participant RA as RoleAdapter
    participant AG as ActuationGate
    participant CM as ConsequenceMemory
    participant PF as Pheromone Field

    Agent->>CK: propose_action(proposal)
    CK->>FW: evaluate_plan(proposal)
    FW-->>CK: findings[]
    CK->>RL: check_budget(estimate)
    RL-->>CK: (approved, reason)
    CK->>RA: update(profile)
    RA-->>CK: role
    CK->>AG: evaluate(proposal, profile, findings, budget)
    AG-->>CK: GateResult(decision, score)
    CK-->>Agent: GateResult

    alt decision == EXECUTE
        Agent->>Agent: perform action
        Agent->>CK: record_outcome(result)
        CK->>CM: record(consequence)
        CM->>CM: compute_trust_delta()
        CK->>PF: deposit(SUCCESS) or deposit(FAILURE)
        CK->>PF: deposit(DEPENDENCY)
        CK->>RA: update(profile)
    end

    Note over PF: tick() evaporates all traces
    Note over PF: FAST decay: 0.30/tick
    Note over PF: NORMAL decay: 0.10/tick
    Note over PF: SLOW decay: 0.02/tick

Integration​

The colony kernel depends on exactly one external codomyrmex module: agentic_memory.stigmergy.

  • agentic_memory.stigmergy.field.TraceField — the backing store for pheromone traces. PheromoneStore wraps it with colony-specific compound keys ("{location}:{signal_type.value}"), source trust multipliers, and ColonySignal-aware deposit logic.
  • agentic_memory.stigmergy.models.StigmergyConfig — passed through to TraceField to configure evaporation rate, minimum strength floor, and maximum trace count.

ConsequenceMemory uses the Python standard library sqlite3 directly. No ORM or third-party persistence library is required.

Other colony-kernel imports are explicit: subsystem classes share models.py, and the integration layer coordinates them. ActuationGate may query both the pheromone store and consequence memory; PruningDaemon may query the pheromone store.

MCP Tools​

Eight MCP tools expose the colony kernel to AI agents via Model Context Protocol. All tools route through a module-level ColonyKernel singleton.

ToolPurpose
colony_propose_actionSubmit an action proposal; returns the full GateResult
colony_record_outcomeRecord the actual consequence of an executed action
colony_agent_profileRead an agent's current trust profile and role
colony_statusDashboard snapshot: signals, budget usage, role distribution, recent consequences
colony_pheromone_querySense pheromone strength at a specific location and signal type
colony_falsify_planAdversarially evaluate any plan dict without running the full gate
colony_pruning_reportList stale or broken module locations identified by the pruning daemon
colony_tickAdvance the colony one time-step and evaporate pheromone traces

See MCP_TOOL_SPECIFICATION.md for full JSON schemas and examples.

Health Check​

Run the Colony Kernel health check via the Codomyrmex CLI doctor:

# Colony Kernel only
codomyrmex doctor --colony

# All checks (includes Colony Kernel)
codomyrmex doctor --all

# Programmatic access
from codomyrmex.cli.doctor import check_colony_kernel
results = check_colony_kernel()

The doctor verifies: imports, kernel instantiation, propose→record lifecycle, and status output.

Tests​

Tests live in tests/unit/colony_kernel/. Run with:

uv run pytest tests/unit/colony_kernel/ -v

Deterministic replay artifact​

The checked-in paired-locality contract can be replayed without external services:

uv run python scripts/replay_colony_kernel.py

The command runs the fixed-input case twice, compares semantic outputs, and writes output/data/colony_kernel_replay.json. The record includes proposal identities, decisions, pressure observations, assertion results, source/config provenance when generated through the manuscript pipeline, and digests. It intentionally models a caller-reported failure; it is not an execution-attestation or external benchmark.

Evidence-first research surfaces​

The additive attestation.py, reference.py, formal.py, and research/ surfaces extend the replay contract without changing its schema. In optional mode callers may choose the linked lifecycle while the ordinary outcome path remains available. In required mode the kernel accepts state-changing outcomes only through record_attested_outcome() after an EXECUTE verdict, authorization, and execution receipt. HMAC is the local default and Ed25519 is optional and explicit. The ledger authenticates local event linkage, not the truth of external execution. The reference interpreter and formal bridge return structured counterexamples or unavailable states rather than implying proof when an optional solver is absent.

research/ runs deterministic synthetic paired cases, persistence/restart fixtures, and declared probabilistic adapters offline. Its numerical settings are example/initial configurable values, not calibrated or universal constants. Run uv run python scripts/run_colony_research.py --output output/research/colony_kernel_offline.json --seed 0 to create a local manifest and hashed artifact. No external benchmark or provider traffic is performed.

The test suite follows the zero-mock policy: all tests use real ColonyKernel instances with db_path=":memory:". No unittest.mock, no MagicMock. Coverage target: ≥ 60% (project-wide gate).

Key test modules:

  • test_models.py — data contract validation for all dataclasses and enums
  • test_kernel.py — full propose/record/tick round-trips
  • test_actuation_gate.py — gate score calculations and threshold routing
  • test_consequence_memory.py — SQLite persistence and trust delta computation
  • test_falsification_worker.py — each attack vector in isolation
  • test_pruning_daemon.py — staleness detection via pheromone field state
  • test_mcp_tools.py — all eight MCP tool round-trips against the singleton