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.

Tool	Purpose
colony_propose_action	Submit an action proposal; returns the full GateResult
colony_record_outcome	Record the actual consequence of an executed action
colony_agent_profile	Read an agent's current trust profile and role
colony_status	Dashboard snapshot: signals, budget usage, role distribution, recent consequences
colony_pheromone_query	Sense pheromone strength at a specific location and signal type
colony_falsify_plan	Adversarially evaluate any plan dict without running the full gate
colony_pruning_report	List stale or broken module locations identified by the pruning daemon
colony_tick	Advance 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

Navigation Links

• Parent Directory: codomyrmex
• Project Root: ../../../README.md
• Agents Reference: AGENTS.md
• Formal Specification: SPEC.md
• MCP Tools: MCP_TOOL_SPECIFICATION.md
• Stigmergy Integration: agentic_memory/stigmergy

Runtime invariant crosswalk

all_invariants_hold accepts observed cumulative budget snapshots, gate results, and consequence records alongside profiles and pheromone strengths. It checks budget monotonicity, ternary decision closure, and canonical trust-update bounds. Start a new budget snapshot sequence after each period reset. Omitted inputs are vacuous checks; passing diagnostics do not establish external execution or scientific acceptance. See SPEC.md for individual predicates and the real subsystem integration regression.