makelore/.project-docs/30-worklog/tasks/20260901-web-search-mlw02-client-c8e4a2d1.md

Task: Implement MLW-02 Web Search Main client and adapter

Identity

• Task ID: 20260901-web-search-mlw02-client-c8e4a2d1
• Mode: Feature
• Branch: codex/20260901-web-search-mlw02-client-c8e4a2d1-web-search-mlw02-client
• Worktree: D:\Datas\OthersProjects\makelore-web-search-mlw02-client-c8e4a2d1
• Base commit: f3874e9070
• Owner: web-search-mlw02-implementer
• Status: Ready for Integration

Scope

• Implement MLW-02 from exact client coordinator frontier f3874e90706692094f0f22fca465923143e23c7e and frozen server DTO/context frontier a49c696ebc4213e3d62ece780961efbe17576f8e.
• Add the Main-only electron/services/web-search-client.ts with closed input, fixed route, Works authentication/one-refresh behavior, bounded DTO parsing, same-operation reconciliation, and honest billing receipt projection.
• Add electron/coding-plugins/adapters/web-search.ts as the code-owned hosted adapter. It validates closed input and confirmation, invokes the shared MLW-01 admission resolver, supplies trusted project/request identity, and maps server outcomes without exposing Provider details or calculating Token Points.
• Make only the minimal shared contract changes required by the new platform_metered/not_started and Main-only receipt_unavailable billing statuses: shared/data-service.ts, shared/coding-conversation-product-tool-protocol.ts, and the Registry billing validator in electron/coding-plugins/registry.ts.
• Add focused Web Search, billing/parser, adapter, and conversation contract tests within the ticket's owned test paths.
• Do not modify Renderer, composition, Pi worker/resource, Package Store, effective resolver, server, MLW-03 paths, or any user/coordinator worktree.

Intent And Constraints

• Project Context Loaded: client AGENTS.md, the complete maintain-project-docs skill and document-system reference, TDD and implement-spec instructions, required project-memory entry points, peer task records, and Web Search design/implementation spec §12 were read before planning.
• Concurrent Task Gate: Passed. task_context.py start created this isolated feature task from the exact coordinator frontier; status identity matches the task ID, owner, mode, branch, absolute worktree, and base. The user root and client coordinator worktrees remain untouched.
• Planning Gate: Passed. The older broad Web Search coordinator/integration and completed MLW-01 records were inspected read-only. MLW-01 is the only direct dependency and its exact source commit is integrated at this task's base; this task owns different files. No unresolved semantic conflict remains.
• Frozen server context is the typed Web Search route/receipt contract at a49c696ebc4213e3d62ece780961efbe17576f8e; client code must not invent Provider/model/key/URL/payload authority or a generic invoke surface.
• Main retains Works credentials, route, logical IDs, reconciliation and raw server receipt projection. The client never calculates points, exposes query beyond the typed request boundary, or forwards Provider response/header/raw error data to Pi/Renderer.
• Transport uncertainty and reserved/dispatched responses reuse the same logical operation and exact request body for one bounded window of at most 155 seconds. A 429 is non-retryable and preserves only bounded Retry-After; a new user confirmation must create a new logical operation.
• TDD vertical slices: closed parser/fixed request, auth refresh, reconciliation and receipt states, adapter mappings, then shared billing/protocol validator changes and regression gates. One source commit with this task record, clean worktree, and READY_FOR_INTEGRATION handoff are required. No push, PR, deploy, publish, or real OpenAI call.

Outcome

• Added the Main-only WebSearchClient with the exact typed hosted route, closed request/response parsing, one Works-token refresh, whole-response bounds, bounded same-operation reconciliation, and honest projection of the server-owned receipt. Transport ambiguity and in-progress receipts reuse the same logical operation/body for at most 155 seconds; an exhausted window returns only plugin_receipt_unavailable and never invents an amount.
• Added the code-owned Web Search Plugin adapter. It validates the exact query/confirmed input, resolves the frozen Release admission through the MLW-01 helper, and supplies only trusted durable project/request identity to Main. Complete succeeded and result-bearing pending_review responses are usable; result-less submission_unknown, 429, admission/auth/input failures, and receipt uncertainty retain their bounded business code and billing state.
• Extended the shared billing union, Registry validator, and conversation parser only for Main-owned platform_metered/receipt_unavailable while retaining the existing platform_metered/not_started state for every pre-transaction failure.
• Final review corrected two frozen-contract mismatches: source title/URL bounds now exactly match Server 240/4096, and the adapter preserves MLW-01 plugin_release_unavailable / plugin_account_changed admission failures instead of collapsing them into a generic backend error.
• No composition, Renderer, Pi worker/resource, Package Store, effective resolver, Server, Provider/model/key/URL authority, generic invoke, deploy, publish, or live Provider call was added.

Verification

• Concurrent/Planning Gate identity remained exact after recovery: same task, owner, worktree, branch, and base f3874e90706692094f0f22fca465923143e23c7e; the coordinator and user root worktrees were not modified.
• The original delegated turn was interrupted after preserving the complete owned test/product diff but before returning its red/green ledger. A second delegated recovery also stalled without changing files. The parent coordinator then became the sole writer in this same owned worktree; no task release, rebuild, reset, stash, clean, or concurrent edit occurred.
• First observable recovered focused run: 3 files / 32 tests passed. Contract review regressions for exact source bounds and both admission failure codes brought the final focused result to 3 files / 35 tests passed.
• Adjacent hosted admission, Game Resource, Registry, conversation, Marketplace-client and timeline regression: 11 files / 114 tests passed.
• pnpm run typecheck passed. Owned-file ESLint passed. Full pnpm run lint:check passed with zero errors and the unchanged five warnings in Home/Makelore outside this task.
• Full unit suite passed: 214 files / 1748 tests, 2 staged-runtime skips; the pressure suite passed 1/1. pnpm run build:vite passed Renderer, Main, Preload, and utility builds with only existing chunk/dynamic-import notices.
• Final diff, project-docs, document-drift, task-context completion, sole-parent, and clean-worktree facts are recorded by the source commit handoff.

Follow-ups

• None recorded.

Promotion Candidates

• None recorded.