Skip to content

refactor(runtime-host): remove the uncalled execution.inspect.resolve operation - #3936

Open
liuxiaocs7 wants to merge 1 commit into
apache:mainfrom
liuxiaocs7:liuxiaocs7/refactor-runtime-host-remove-the-uncalled-execut
Open

refactor(runtime-host): remove the uncalled execution.inspect.resolve operation#3936
liuxiaocs7 wants to merge 1 commit into
apache:mainfrom
liuxiaocs7:liuxiaocs7/refactor-runtime-host-remove-the-uncalled-execut

Conversation

@liuxiaocs7

@liuxiaocs7 liuxiaocs7 commented Aug 26, 2026

Copy link
Copy Markdown
Member

Summary

execution.inspect exposed two operations, but Desktop calls only execution.inspect.query (with kind: 'turn_trace' and the Session/Turn trace kinds). execution.inspect.resolve was registered in the protocol, the operation table, and the coordinator, yet had no non-test caller anywhere in the repository — a second inspection contract that no shipped surface reads.

This removes resolve end to end across every layer that maintained it:

  • Protocol (execution-inspect.ts): the operation spec, its input/output decoders and assertions, the ExecutionInspectCandidate / ExecutionInspectEntityKind types, the candidate decoder, and the EXECUTION_INSPECT_CANDIDATE_MAX_ITEMS limit.
  • Operation table (operations.ts): the execution.inspect.resolve entry. ExecutionInspectOperationKey collapses to just query automatically.
  • Coordinator (execution-inspect-coordinator.ts): the handler entry, #resolve, its #findSession / #findRunInSession / compareCandidates helpers, and the now single-value failure() helper (assertion dropped).
  • Storage: ExecutionAgentRunReader.findRunsById — the only reader reachable exclusively from resolve — plus the resolve-only core_agent_runs_identity SQLite index. AgentRunIdentitySearchResult / assertIdentitySearchLimit stay; listSessionRunsBounded shares them.
  • Compatibility epoch: bumped RUNTIME_HOST_COMPATIBILITY_EPOCH 53 → 54 (rebased onto main, which claimed 52 for the durable steering echo and 53 for Message admission) so a peer that still knows resolve fails the handshake rather than sending a removed operation mid-connection (same treatment oauth.account.usage.fetch received).
  • Retired credential grant: registered execution.inspect.resolve as a retired operation grant so an access file issued before the removal releases the grant on decode instead of throwing RuntimeHostAccessInputError and blocking Host startup.
  • Storage schema: bumped the core-execution schema version 5 → 6 and drop the stale index on upgrade so existing databases reconcile to the new target schema.

execution.inspect.query and all four of its result kinds (session, agent_run, turn_trace, session_trace_page) — including the Turn/Session trace paths Desktop renders — are untouched.

Fixes #3932

Verification

  • Typecheck: @maka/core, @maka/storage, and @maka/runtime build clean; @maka/storage and @maka/runtime-host both pass tsc --noEmit with zero errors. (An earlier run reported a workhub-coordination-action-gate.test.ts type error; that was a stale-dependency-dist artifact from building out of order and does not reproduce on a clean full build — noted here for transparency since the first revision's description mentioned it.)
  • Affected suites pass locally (node --test on built output):
    • runtime-host: execution-inspect-protocol, execution-inspect-coordinator, execution-inspect-uds, protocol (incl. the new epoch-54 test), access-credential-metadata (incl. the new retired-grant regression test), handshake-compatibility.
    • storage: sqlite-core-execution-store (incl. the new "drops the obsolete AgentRun identity index on upgrade" migration test).
  • Lint/format: biome check clean on all changed files.

Migration / Rollout

Removing resolve is a wire-contract change, so the compatibility epoch is bumped (mixed-version peers fail the handshake by design) and the core-execution schema version is bumped so an upgraded Host drops the obsolete index on first open. Both paths have regression tests. Access files that recorded the resolve grant now decode cleanly with the grant released.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: Claude Opus (via Claude Code) — traced the reachable set, performed the end-to-end deletion, added the epoch/credential/schema retirements and their tests. Both commits carry a Generated-by: Claude Opus trailer.

Checklist

  • Tests cover the change and fail without it — the epoch bump, retired grant, and index drop each have a regression test that fails on the pre-change behavior; the deleted resolve tests are removed and the retained query suites still pass.
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary / Migration above (handshake boundary + storage migration; no change to any shipped feature)
  • No

@liuxiaocs7

Copy link
Copy Markdown
Member Author

Pushed a follow-up (8900bd2) extending the removal to the parts of the reachable set the first pass missed:

  • Compatibility epoch 51 → 52 — an old peer that still knows execution.inspect.resolve now fails the handshake instead of sending a removed operation mid-connection (the same treatment oauth.account.usage.fetch got). Pinned with a protocol test.
  • Retired credential grant — an access file issued before the removal previously threw RuntimeHostAccessInputError: Unknown Runtime Host operation grant: execution.inspect.resolve and blocked Host startup. execution.inspect.resolve is now a retired grant, released on decode; added an old-access-file regression test.
  • Storage schema 5 → 6 — dropped the resolve-only core_agent_runs_identity index and drop it on upgrade so existing databases reconcile to the new target schema; added a migration test.
  • Cleanup — collapsed the now single-value failure() helper and removed its type assertion.

Also correcting the first revision's note: the workhub-coordination-action-gate.test.ts type error was a stale-dependency-dist artifact from building out of order — it does not reproduce on a clean full build, and @maka/storage + @maka/runtime-host both pass tsc --noEmit with zero errors. The PR description is updated accordingly.

@liuxiaocs7
liuxiaocs7 force-pushed the liuxiaocs7/refactor-runtime-host-remove-the-uncalled-execut branch 3 times, most recently from d89c04c to be9417e Compare August 26, 2026 16:28
… operation

execution.inspect exposed two operations, but Desktop calls only
execution.inspect.query. execution.inspect.resolve was registered in the
protocol, the operation table, and the coordinator, yet had no non-test caller
anywhere in the repository, leaving a second inspection contract that no
shipped surface reads.

Remove resolve end to end across every layer that maintained it:

- Protocol: the operation spec with its input/output decoders and assertions,
  the ExecutionInspectCandidate / ExecutionInspectEntityKind types, the
  candidate decoder, and the EXECUTION_INSPECT_CANDIDATE_MAX_ITEMS limit.
- Operation table: the execution.inspect.resolve entry;
  ExecutionInspectOperationKey collapses to just query automatically.
- Coordinator: the handler entry, #resolve, its #findSession /
  #findRunInSession / compareCandidates helpers, and the now single-value
  failure() helper (type assertion dropped).
- Storage: ExecutionAgentRunReader.findRunsById -- the only reader reachable
  exclusively from resolve -- and the resolve-only core_agent_runs_identity
  SQLite index. AgentRunIdentitySearchResult and assertIdentitySearchLimit stay;
  listSessionRunsBounded shares them.
- Compatibility epoch: bump RUNTIME_HOST_COMPATIBILITY_EPOCH to 53 so a peer
  that still knows resolve fails the handshake instead of sending a removed
  operation mid-connection.
- Retired credential grant: register execution.inspect.resolve as a retired
  operation grant so an access file issued before the removal releases the
  grant on decode rather than throwing RuntimeHostAccessInputError and blocking
  Host startup.
- Storage schema: bump the core-execution schema version to 6 so existing
  databases drop the obsolete index on upgrade.

execution.inspect.query and all four of its result kinds (session, agent_run,
turn_trace, session_trace_page), including the Turn/Session trace paths Desktop
renders, are untouched. Adds protocol, retired-grant, and schema-migration
regression tests.

Fixes apache#3932

Generated-by: Claude Opus
@liuxiaocs7
liuxiaocs7 force-pushed the liuxiaocs7/refactor-runtime-host-remove-the-uncalled-execut branch from be9417e to b3fd88e Compare August 26, 2026 18:00
@github-actions github-actions Bot added the effort/M Under 500 readable lines label Aug 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(runtime-host): remove the uncalled execution.inspect.resolve operation

1 participant