# Task: Implement ML-03 Main cloud client and Host routes

## Identity

- Task ID: 20260826-ml03-main-data-service-7c4e2b18
- Mode: Feature
- Branch: codex/20260826-ml03-main-data-service-7c4e2b18-ml03-main-data-service
- Worktree: D:\Datas\OthersProjects\makelore-ml03-main-data-service-7c4e2b18
- Base commit: 5ac08d509f8962a3c2c0ec1b1afef84a435f116d
- Owner: codex-ml03
- Status: Ready for integration

## Scope

- Implement the Main-owned Data Service cloud client and the fixed operational
  Host routes from ML-03, including strict DTO/error projection, session token
  refresh/replay, active durable-project resolution, destructive confirmations,
  and route registration before the Works catch-all.
- Expose one `DataServiceOperations` adapter through the coding composition for
  Host routes and the later Pi product-tool ticket.
- Add focused client/adapter/route/registration tests without changing preview
  sessions, Pi tools, Renderer credential handling, or loopback transport.

## Intent And Constraints

- Base is the exact post-ML-01 commit `5ac08d509f8962a3c2c0ec1b1afef84a435f116d`.
- Keep Works Square session ownership in the existing Main session service. A
  logical request may replay only once after an authoritative upstream 401;
  timeout, disconnect, 5xx, and other ambiguous failures are never replayed.
- Derive owner/project identity from `requireActiveRealProjectWithIdentity()`;
  caller-controlled owner, durable project ID, local path, token, and endpoint
  inputs are not accepted. `listProjects` is the only owner-wide operation.
- Keep request and upstream response parsing bounded and strict, project only
  documented fields, and return the safe Host envelope. Keep canonical project
  memory unchanged in feature mode.
- Preserve existing Host dispatcher behavior and register Data Service before
  `handleWorksRoutes`; do not add preview capability, generated SDK, Pi tools,
  or unrelated retry/loopback changes in this ticket.

## Outcome

- Implemented the Main-owned Data Service cloud client, strict shared DTOs, and the
  single `DataServiceOperations` adapter. Active operations resolve the durable ID
  through `requireActiveRealProjectWithIdentity()`; owner-wide `listProjects` is the
  only operation without active-project resolution. Request/upstream JSON is bounded,
  remote DTOs and accepted error context are projected to safe fields, and only an
  authoritative cloud 401 can trigger one refresh/replay. Ambiguous transport and
  upstream failures are never retried or exposed.
- Added the fixed `/api/works/data-service` Host routes with strict bodies, query
  allowlists, strong `If-Match` projection, literal destructive confirmations, and
  no caller-controlled owner, durable project ID, local path, token, or endpoint.
  Registered the handler before the Works catch-all and added a regression test for
  that precedence. The owner-wide list supports the documented recovery sequence:
  identify an orphan, explicitly bind a disposable local project in the UI, then
  confirm removal while that project is active.
- Wired the adapter through coding composition for Host and the later Pi tool slice;
  no preview sessions, Pi tools, Renderer credentials, second session store, or
  loopback transport changes were added.

## Verification

- `pnpm exec vitest run tests/unit/data-service-client.test.ts
  tests/unit/data-service-routes.test.ts
  tests/unit/data-service-server-registration.test.ts --maxWorkers=1` — 3 files,
  17 tests passed.
- `pnpm exec vitest run tests/unit/coding-core-routes.test.ts
  tests/unit/coding-project-identity.test.ts tests/unit/host-api-proxy.test.ts
  tests/unit/works-routes.test.ts --maxWorkers=1` — 4 files, 82 tests passed.
- `pnpm typecheck` — passed.
- `pnpm lint:check` — 0 errors; 5 existing warnings remain in
  `src/pages/Home/index.tsx` and `src/pages/Makelore/index.tsx`.
- `git diff --check` — passed (only existing LF/CRLF normalization warnings on
  modified files).

## Follow-ups

- Run signed-in cross-repository acceptance against the reviewed Works Square server
  branch, including real PostgreSQL behavior and the UI bind/recovery flow.
- ML-04 should consume this `DataServiceOperations` seam for in-process parent-worker
  tools and preserve the trusted project-path equality check when its context is
  available.

## Promotion Candidates

- None recorded.