finding: dispatcher `services.search` reports `handlerReady: true` for a slot with no mounted handler — the one slot #4318 did not reach

[hotlong]

What this is

A finding, latent for the same reason #7602 was: nothing registers the search slot today, so the wrong branch is unreachable on every host that exists. Surfaced while implementing #7602 (PR #7937), which fixed the sibling field on the same slot and left this one deliberately untouched — it is a separate decision on a separate field, and folding it into that PR would have widened a scoped card.

Observed

packages/runtime/src/http-dispatcher.ts, in getDiscoveryInfo()'s per-service status map:

search: searchRegistered ? svcAvailable(undefined, undefined, searchSvc) : svcUnavailable('search'),

svcAvailable() returns handlerReady: true for any occupant that carries no __serviceInfo self-description. The map's own contract, stated a few lines above it, is:

handlerReady: true means the dispatcher has a real, bound handler for this route.

The dispatcher has no handler for search — no search entry in route-ledger.ts, no branch in http-dispatcher.ts, and the call site passes route: undefined precisely because there is nothing to advertise. So a filled slot yields a record that says, in one breath, "no route" and "the handler is ready".

That is the contradiction #4318 named and closed for cache / queue / job. Its remedy is already in this file: svcInProcess(name, svc), which returns handlerReady: false plus inProcessServiceMessage(name) — "this is a kernel-internal contract with no HTTP surface", said honestly. search is the one slot of that shape that was not converted, and the only reason the omission never showed is that no ISearchService has ever been registered (CORE_SERVICE_PROVIDER records 'search': null).

Why this is a finding and not a bug

Identical grading to #7602: declared and served agree today, by coincidence of an empty slot. The wrong record can only be produced by a host that registers a search service, and none exists in either repository.

Why it was left out of PR #7937

• finding: the runtime dispatcher's capabilities.search is still presence-gated, so it over-promises the moment the slot is filled #7602's ruling was about capabilities.search — whether the capability is advertised. This is services.search.handlerReady — how the slot occupant is described. Different field, different producer contract (capabilities describes the host's HTTP surface; services describes what is registered), different remedy.
• finding: the runtime dispatcher's capabilities.search is still presence-gated, so it over-promises the moment the slot is filled #7602's declared file surface covered the capability block; PR fix(runtime): dispatcher capabilities.search answers a stated false, not bare slot presence (#7602) #7937 states this explicitly in its "out of scope" section rather than silently widening.

What a fix would look like

Almost certainly one line, mirroring #4318:

search: searchRegistered ? svcInProcess('search', searchSvc) : svcUnavailable('search'),

Worth deciding rather than assuming, on one point: inProcessServiceMessage('search')'s wording was written for kernel-internal contracts (cache/queue/job). A search engine is not kernel-internal in the same sense — it is an external engine with no dispatcher surface — so the message may want its own phrasing even if the handlerReady: false half is settled.

A fix should also carry a test: the same shape PR #7937 used for the capability — register a search service, assert handlerReady === false — since like every other assertion on this slot, it is vacuous unless the fixture fills it.

Filed unassigned and without a domain:* label so routing stays the triage seat's call (packages/runtime ⇒ domain:cli per the domain table, if that is the disposition).

Related: #4318 (the same contradiction, fixed for cache/queue/job), #7602 / PR #7937 (the capability half of this slot), #2462 / ADR-0076 D12 (honest self-report).

[hotlong]

Triage: promoted finding → pm:queue, routed domain:cli (packages/runtime/src/http-dispatcher.ts). Latent today (no ISearchService registered anywhere, as the card honestly grades), but promoted anyway: the remedy is the already-established #4318 pattern sitting in the same file (svcInProcess), the sibling field on the same slot just landed via PR #7937 with the exact test shape to copy, and the honest-self-report contract (#2462 / ADR-0076 D12) is the invariant being restored. A one-line fix plus a fixture-filled assertion now is cheaper than rediscovering the contradiction when someone registers a search service.

Lane discretion, flagged by the card and endorsed: inProcessServiceMessage('search')'s kernel-internal wording may want its own phrasing for an external-engine slot — pick one in the PR, don't block on it. Same-day churn check on http-dispatcher.ts (PR #7937 just merged into it).

Size/model suggestion: S mechanical, mode:subagent, model: sonnet.

---

Generated by Claude Code

[hotlong]

Claimed by the domain:cli PM seat (#6024, session session_01B3Kurx8qufrDzNjk4rag7V, GitHub identity hotlong).
Branch: claude/issue-7939-dispatcher-search-handler-ready · dispatch: mode:subagent, model: sonnet — taking the triage seat's S-mechanical sizing.

Same-day churn check done, and both halves confirmed on origin/main @ 8d80e12e7:

• PR fix(runtime): dispatcher capabilities.search answers a stated false, not bare slot presence (#7602) #7937 is in — http-dispatcher.ts:1403 reads search: { enabled: false }.
• The half it deliberately left is untouched — :1570 is still
  search: searchRegistered ? svcAvailable(undefined, undefined, searchSvc) : svcUnavailable('search').

So the two fields are adjacent in one file and were separated on purpose. The dev must not undo #7937's choice while fixing this one. Restating that boundary, since it is the whole reason this card exists separately:

• capabilities.search describes the host's HTTP surface → enabled: false, already landed.
• services.search describes what is registered → stays presence-gated. The bug is only that a filled slot is described as handlerReady: true, which contradicts the map's own stated contract.

Fix is the #4318 remedy already sitting in the same file: svcInProcess('search', searchSvc).

Lane discretion on the message wording, exercised here so the dev does not stall on it: inProcessServiceMessage's phrasing was written for kernel-internal contracts (cache/queue/job), and a search engine is not kernel-internal in that sense — it is an external engine with no dispatcher surface. Give it its own phrasing if the shared string would be inaccurate; keep the shared one if it reads true. Either is acceptable; say which you picked and why in the PR. Do not open a decision card for it.

⛔ The assertion is vacuous unless the fixture fills the slot — CORE_SERVICE_PROVIDER records 'search': null, so a test that does not register a search service passes no matter what the line says. Copy PR #7937's fixture shape: register a search service, then assert handlerReady === false. Reverse-verify against the current svcAvailable line and report the observed failure.

---

Generated by Claude Code

[hotlong]

{
 "issue": 7939,
 "status": "done",
 "branch": "claude/issue-7939-dispatcher-search-handler-ready",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/7965",
 "pr_url": "https://github.com/objectstack-ai/objectstack/pull/7965",
 "premise_still_valid": true,
 "summary": "packages/runtime/src/http-dispatcher.ts:1570 built services.search with svcAvailable(undefined, undefined, searchSvc), which defaults an unmarked occupant to handlerReady:true even though the dispatcher has no /search route or handler anywhere -- contradicting the map's own stated contract a few lines above. Replaced with the #4318 svcInProcess() remedy (handlerReady:false) plus search's own fallback message, since the shared inProcessServiceMessage 'Kernel-internal service' wording is false for an external search engine. capabilities.search (:1403, PR #7937/#7602) is untouched, exactly as the card's boundary required. Added a patch changeset.",
 "what_changed": "Same as summary -- see that field.",
 "tests": "New: 'reports an unmarked search occupant with no route and handlerReady false, not true (#7939)' and 'reports a self-describing search occupant ... still handlerReady false (#7939)' in http-dispatcher.test.ts, discovery honest capabilities (D12) block. pnpm --filter @objectstack/runtime exec vitest run src/http-dispatcher.test.ts --maxWorkers=2 -> 242/242 pass. pnpm --filter @objectstack/runtime typecheck -> clean. pnpm exec turbo run typecheck --concurrency=2 (repo-wide) -> 126/126 tasks green. node scripts/check-nul-bytes.mjs -> OK. Runtime TEST_DEBT (check:type-check-debt's hidden-test-layer number) re-measured directly via tsc --noEmit on a sibling tsconfig dropping the test exclude: 227, exactly matching the recorded ledger (my first draft measured 228 -- a +1 regression from writing info.services.search.route without the Record< string, any > cast the #4318 tests already use for this same route-less-type reason; fixed before pushing).",
 "tests_added": [
 "http-dispatcher.test.ts: 'reports an unmarked search occupant with no route and handlerReady false, not true (#7939)' -- registers a real unmarked search-service-shaped occupant (CORE_SERVICE_PROVIDER['search'] is null so an empty-slot test would be vacuous) and asserts enabled/status/handlerReady/route/message.",
 "http-dispatcher.test.ts: 'reports a self-describing search occupant (e.g. a dev stub) with its own status, still handlerReady false (#7939)' -- a __serviceInfo-marked occupant keeps its declared status/message, handlerReady stays false."
 ],
 "message_wording_choice": "Gave search its own phrasing instead of reusing svcInProcess's shared inProcessServiceMessage('search') string ('Kernel-internal service -- consumed in-process via the service registry'): that sentence is true for cache/queue/job (kernel-managed, in-process by construction) but false for search, whose occupant is an external engine (Elasticsearch/Meilisearch, per core-services.zod.ts's own REMEDY_DETAIL['search']), not a kernel-internal one. svcInProcess() gained an optional third fallbackMessage parameter (cache/queue/job call sites unchanged, no third argument, same message as before); search now reads 'Search engine registered, but the dispatcher has no HTTP route for the search slot -- no dedicated search endpoint is mounted on its behalf. Cross-object search, where a host serves it, is reported separately by capabilities.search.'",
 "reverse_verification": "Committed the fix first (a42af3b98), then git checkout HEAD~1 -- packages/runtime/src/http-dispatcher.ts (never git stash) to restore the pre-fix svcAvailable(...) line while keeping the new tests, then ran vitest -t '#7939'. Observed failure: 'AssertionError: services.search.handlerReady: expected true to be false' -- 1 failed, 1 passed, 240 skipped -- i.e. failed for exactly the described contradiction (handlerReady:true from the old line), not a compile error and not a vacuous empty-slot skip; the second (__serviceInfo-marked) test still passed as expected since svcAvailable already honors self-description. Restored via git checkout claude/issue-7939-dispatcher-search-handler-ready -- packages/runtime/src/http-dispatcher.ts and confirmed git status --short was empty (byte-identical to the committed fix), then re-ran the full file: 242/242 pass.",
 "open_questions": [],
 "out_of_scope_findings": [],
 "risks": [
 "None identified for live hosts: CORE_SERVICE_PROVIDER['search'] is null and nothing registers an ISearchService anywhere in either repository today, so no deployed host's discovery output actually changes -- the fix only corrects the shape for the day a search service is registered.",
 "capabilities.search is unaffected (verified untouched at :1403, still `{ enabled: false }`).",
 "Investigated whether metadata-protocol's own services.search (packages/metadata-protocol/src/protocol.ts) has a matching defect since it's the discovery document's other producer -- it does not: that producer genuinely mounts a real /api/v1/search handler via searchAll() regardless of slot registration, so its presence-gated route/handlerReady shape for search is legitimately different from the dispatcher's and is already deliberately pinned (packages/objectql/src/protocol-discovery.test.ts, 'should leave non-dispatcher-owned routes presence-gated'). No fix and no parity test were added there; not filed as a finding since it is existing, deliberate, tested behavior, not a defect.",
 "CI gate status at draft-PR time: only the Vercel preview status had reported (success/ignored-build-step); ESLint and TypeScript Type Check had not yet posted -- reporting now per the draft-PR-time contract (#6644 L2) rather than waiting."
 ],
 "schema_note": "This card's dispatch prompt specified a Final report field list (branch/pr_url/what_changed/tests_added/reverse_verification/risks[]) that differs from the standing os-dev system-prompt schema (pr/summary/tests/premise_still_valid/open_questions). Included fields from both schemas above rather than silently picking one, per the system prompt's instruction to surface such conflicts."
}

---

Generated by Claude Code