KB-51CB

02 — Full Runner / Executor Discovery

4 min read Revision 1
dot-runnerrunner-discoveryagent_apiiu-cutter2026-06-04

02 — Full Runner / Executor Discovery (Workstream A)

Goal: end ambiguity about execution. Searched DB (tables/functions) + host filesystem (ssh root) + containers + config.

Finding: execution is layered, not absent

The prior "no DOT runner exists" was true only for the agent_api subset. Four distinct execution layers exist:

1. iu-cutter-v0.6 — TRUE_DRY_RUN_RUNNER_EXISTS (powers job:cut)

/opt/incomex/dot/iu-cutter-v0.6/ — full Python orchestrator: cli.py, cutter_agent/dryrun.py, prod_iu_adapter.py, state machine, ledger. Sidecar /opt/incomex/dot/iu-cutter-v0.6-o7-sidecar/o7_live_dryrun_runner.py (report 05-runner-or-cli-authoring-result.md):

  • read-only DB only (context_pack_readonly + set_session(readonly=True));
  • orchestrator.__execution_enabled__ is False kill-switch asserted, never assigned;
  • Mode.LIVE refused → raises ProductionExecutionNotAuthorized;
  • every phase Mode.DRYRUN against in-memory simulator; mutation structurally impossible;
  • regression baseline 366/366 tests OK (Python 3.12.3). → This is why job:cut is the only verified candidate — it has a real runner with a real dry-run mode.

2. IU-command layer dot_iu_command_run — TRUE_PLAN_RUNNER_EXISTS

dot_iu_command_catalog = 54 commands (collection/health/lifecycle/piece/read). dot_iu_command_run columns: run_mode, run_status, mutating, params_digest, gate_snapshot, evidence. Live distribution: verify/verified 20, apply/applied 19, verify/verified(mut) 5, apply/refused 3, plan/refused 2, others. Gate refusals fire — the plan/verify/apply pattern works today. Grain: keyed by command_name, no process_run_id → not a process-runtime ledger (different grain than process observation).

3. dot-hc-executor — generic executor for system_health_checks

/opt/incomex/dot/bin/dot-hc-executor (Đ22 §4.3, v1.5.0): --dry-run --only-check --self-test, dispatches by executor_type (no switch-case on check code), RO SQL only (forbids DML/DDL/privilege tokens), logs via fn_log_issue, lockfile + heartbeat, NT9 isolated. Paired dot-hc-executor-verify. Scope = health checks, not the KG process family.

4. DOT_KG agent_api subset — BLOCKED_BY_MISSING_AGENT_API_CONTRACT

grep for any agent_api dispatch source across /opt/incomex (excluding docs/context-packs) = empty. No source binds DOT_KG_* codes → an agent_api invocation. incomex-agent-data is the MCP/agent-data backend, not a DOT dispatcher. agent_api DOTs have script_path=NULL, operation=NULL, no function_name. Conclusion: the 12 agent_api KG DOTs have 0 execution records because no runner/endpoint/contract maps a DOT code to an invocation. Improvising the EXPLAIN reasoning by hand = a MOCK, not "the DOT ran" → would be fake verification. → MOCK_ONLY_POSSIBLE.

KG engine mix (36 DOTs)

engine n dry-run feasibility
agent_api 12 requires agent_api plan-only contract (BLOCKED)
hybrid 10 partial — needs both function + agent contract
pg_function 14 invocable, but function_name unregistered; invocation = REAL_RUN (gated off) → RUNNER_CAN_BE_IMPLEMENTED_NOW

Classification per layer

  • iu-cutter / job:cut → TRUE_DRY_RUN_RUNNER_EXISTS
  • dot_iu_command_run → TRUE_PLAN_RUNNER_EXISTS (IU-command grain)
  • dot-hc-executor → executor exists (health-check scope)
  • DOT_KG agent_api (pilot) → BLOCKED_BY_MISSING_AGENT_API_CONTRACT / MOCK_ONLY_POSSIBLE
  • DOT_KG pg_function → RUNNER_CAN_BE_IMPLEMENTED_NOW

No ambiguity remains about why 103/303 DOTs (and specifically the 12 agent_api KG DOTs) have 0 execution records: there is no dispatcher binding their codes to invocations, and usage_count/last_executed are backfill/zero.

Back to Knowledge Hub knowledge/dev/reports/architecture/dot-process-discovery-runner-dryrun-ui-registration-readiness-2026-06-04/02-full-runner-executor-discovery.md