Issue: #13126

Measured at investigate/13126-homeboy-core-kernel based on c56e9f889 plus this report. The investigation treats homeboy-core as the kernel. It does not propose another kernel crate.

Decision

homeboy-core is the minimal generic kernel for a durable automation execution:

• resolve declared targets, workspaces, source identities, and artifact locations;
• select and execute a declared local or remote placement;
• own generic lifecycle identity, durable run/artifact/evidence persistence, and recovery of those records;
• define extension discovery, readiness, invocation, and typed provider dispatch;
• enforce generic policy: secrets/redaction, resource limits, cancellation, confirmation, output envelopes, and compatibility checks; and
• expose versioned, ecosystem-neutral contracts required on both sides of a controller/runner or extension handoff.

homeboy-core must not own a command family, an ecosystem grammar, a specific provider implementation, a release/deploy policy, or a capability-specific persistence projection. homeboy-cli is the composition root: it selects command packages and registers their adapters. Contract crates below core are appropriate only when they carry a versioned, cross-boundary vocabulary. A compatibility re-export is migration evidence, not permanent kernel API.

Target direction:

contracts + primitives
        ^
homeboy-core (generic execution, persistence, extension dispatch)
        ^
capability crates (`homeboy-agents`, runner, audit, fuzz, release, ...)
        ^
homeboy-cli command composition + installed extension commands
        ^
homeboy binary

No arrow points from homeboy-core to a capability implementation. A capability may depend on a contract crate, core, and another explicitly required capability; it must not make every unrelated capability part of the default binary.

Current Measurements

Bounded local measurements used cargo metadata --no-deps, cargo tree, and Git tracked source counts. They do not create a second Cargo target directory.

The root binary depends on homeboy-cli and homeboy-core (Cargo.toml:58-76). Therefore every homeboy-cli production dependency is in the default product graph. cargo tree -p homeboy-cli --edges normal --depth 1 confirms all 15 domain implementations are direct edges, including Agents, Lab Runner, Fuzz, Issues, Triage, Tunnel, Refactor, Rig, Release, and Deploy.

The expected graph impact is structural and measurable before timing claims:

Clean/warm duration and binary-size deltas are intentionally not asserted here. The worktree has no existing target/ directory, and creating a clean target just to benchmark a documentation investigation would duplicate a large build. The implementation issues must record clean and warm timings using the managed shared target, cargo build -p homeboy, cargo test -p homeboy-cli, artifact size, and the same commit before/after.

Current CI is not a substitute for this measurement. Recent main Release workflows were repeatedly cancelled; the latest completed required-gate and release-integrity workflows succeeded, but do not report a capability-isolated build delta.

Violations

Capability Decisions

Consumer And Schema Inventory

The inspected read-only sibling consumer is homeboy-extensions. It has concrete agent-runtime request/outcome, readiness, artifact, and fuzz-manifest consumers; it also documents Release/Deploy as product behavior. This proves those typed schemas and command spellings require a migration window. It did not provide a Tunnel, Issues, or Triage API consumer. Repository-local consumers include the generated CLI reference, command tests, and the Homeboy release workflow.

Persisted compatibility is more important than Rust paths:

• runs, artifacts, trace, findings, triage, and publication intent tables are migrated by core (observation/store/schema.rs:17-212), so capability extraction must preserve core read access and migration ownership.
• Agent-task retry identity is indexed from runs.metadata_json (schema.rs:190-196), so mixed old/new writers need identical JSON shape.
• Controller runtime pins are explicitly migrated to homeboy/controller-runtime-pin/v2 (controller_runtime.rs:1138-1208).
• Extension-facing Agent Task schemas are v1 strings, not private Rust types. New capability packages must accept the existing schema versions before any producer changes.

Mixed-version rollout rule: land contract readers first, then dual-register old and new command/provider paths, then switch writers, then remove a compatibility re-export only after extension fixtures, persisted-record readers, workflow calls, and command JSON output have compatibility proof. Never couple a schema migration to a package-location move without rollback-compatible readers.

Ordered Sequence

1. Add descriptor-driven capability registration and a test that fails when a compiled capability has no registration. This is the prerequisite for deletion.
2. Move Audit/Refactor adapters and ecosystem grammar knowledge above core through the existing #2240/#6855 tracks; remove core’s direct Audit edges.
3. Establish optional command-package composition for Fuzz, Issues/Triage, and Tunnel while preserving their command/result schemas and generated help.
4. Measure the default graph, warm/clean build, focused tests, and binary size against the same shared target before claiming a reduction.
5. Migrate proven external Rust callers off homeboy-core/homeboy-cli re-exports; delete aliases rather than preserving a second permanent API.
6. Relocate CLI-only core modules under their owner only when it enables a deleted dependency or public API. Otherwise leave them unchanged: pure reshuffling has no kernel outcome.
7. Re-evaluate Rig and remote operations after optional composition exists. Keep Release/Deploy and Runs/Evidence unchanged unless new consumer evidence shows a graph reduction without breaking operations.

Existing And New Trackers

• Reused: #2240, #6855, #6766, #8010, #8015, and #11143.
• New: #13141: Optionalize Fuzz, Issues/Triage, and Tunnel through descriptor-driven CLI composition.

Residual Risks

• Cargo feature flags alone do not create installable capability packages or a stable dynamic command ABI. The implementation must choose a typed package and registration mechanism before deleting static edges.
• homeboy-cli currently owns a large typed Commands enum. Dynamic commands require explicit argument/result contracts and command-surface generation; they cannot be hidden behind an untyped subprocess convention.
• Core SQLite tables include capability-specific projections. Moving writers must retain their core migration/read ownership until an independently versioned persistence boundary exists.
• The sibling scan was intentionally read-only and limited to the available homeboy-extensions checkout plus repository workflows. Each implementation PR must repeat a targeted organization-wide consumer search before deleting a command spelling or re-export.

AI Assistance

OpenAI GPT-5.6 Sol via OpenCode inspected the source graph, Cargo metadata, runtime registration, persisted schemas, CI evidence, and the available Homeboy Extensions consumer checkout, then drafted this architecture report. Chris Huber remains responsible for the proposal and all subsequent changes.