Files
makelore/.project-docs/30-worklog/tasks/20260826-ml03-main-data-service-7c4e2b18.md
T

4.3 KiB

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: 5ac08d509f
  • 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.