makelore/.project-docs/30-worklog/tasks/20260826-ml07-data-service-sdk-skill-6b4e91c2.md

Task: Implement ML-07 generated Data Service SDK and bundled skill

Identity

• Task ID: 20260826-ml07-data-service-sdk-skill-6b4e91c2
• Mode: Feature
• Branch: codex/20260826-ml07-data-service-sdk-skill-6b4e91c2-ml07-data-service-sdk-skill
• Worktree: D:\Datas\OthersProjects\makelore-ml07-data-service-sdk-skill-6b4e91c2
• Base commit: 552c6162a5
• Owner: ml07-sdk-skill
• Status: Ready for integration

Scope

• Implement ML-07 from Data Service P0 spec sections 11–13 at exact base 552c6162a57894b713ea1f47d356fa48c0fc0cf1.
• Add the canonical TypeScript/JavaScript ESM SDK templates and bundled data-service Skill, register/package them through the existing coding-skill loader, and add focused SDK/install/registry/workflow tests.
• Preserve the Main-owned ephemeral runtime boundary and leave ML-08 merge integration and ML-09 review to the repository coordinator.

Intent And Constraints

• The generated SDK reads and validates globalThis.__MAKELORE_DATA__ on each call, uses only local injected endpoint/token capability, and exposes the frozen get/list/put/delete surface plus optional local add.
• SDK requests encode collection/document path segments, send exactly one strong If-Match for ifRevision, strictly parse DTO/error responses, avoid retries/cache/offline/subscription/schema/policy behavior, and return stable runtime_unavailable without network access for absent or invalid injection.
• Skill workflow is inspect → explain/propose → explicit intent → one data_service_configure → layout-aware verbatim template install → minimal source edit → data-enabled preview write/read-back → report configured collections and observed quota only after matching read-back. Configuration failure or project_identity_required causes zero source edits.
• Follow the existing bundled skill frontmatter/registry convention and use directly packaged assets/references; no npm package, seed endpoint, manifest, hash, migration, cloud URL, Works credential, retry/cache, or ML-08 changes.

Planning Gate

• Result: Passed on 2026-08-26 in the isolated worktree after check_project_docs.py and task_context.py start/status --json confirmed this task owns the exact branch, worktree, and base.
• Loaded repository AGENTS.md, maintain-project-docs, writing-for-agents and SKILL-MECHANICS, project-memory entry/current/decision/architecture/ domain/evidence/reflection/commitment/stale documents, the parent client task record, and server canonical spec sections 11–13, ML-07 ticket, integration contract, and accepted ADR.
• The parent client coordinator is a separate owner at its recorded frontier; its ML-01 through ML-06 integration is the stated exact base. No active peer declared a conflicting SDK/Skill ownership; historical planning records with placeholder scopes remain unknown but are outside these paths. Canonical project-positioning and success-criteria files retain placeholders/stale language, so the server spec/contract/ADR and parent task record are the authoritative task pointers.

Implementation Plan

1. Inspect current SDK/runtime seams, bundled skill registry/resource packaging, and existing test conventions; record the exact interfaces before writing red tests.
2. Add failing tests for the SDK contract, layout-aware install/repeat/conflict, Skill registration/package contents, and ordered workflow guards.
3. Implement the smallest canonical TS/JS assets, direct SDK helper behavior, registry/resource exposure, and Skill instructions/fixtures required by the tests.
4. Run focused tests, packaged-resource listing, typecheck/lint/build and deterministic regression checks; then complete this task record and drift gate with actual results.

Outcome

• Implemented ML-07 as a bundled, auditable Data Service Skill and paired TypeScript/JavaScript ESM SDK templates. The registry now advertises the opt-in data-service skill while the existing default skill selection stays unchanged. The Skill documents inspect/propose/explicit-intent/configure-once, layout-aware verbatim installation, conflict/no-op behavior, data-enabled preview put/get read-back, and post-verification reporting boundaries.
• The SDK reads and validates the injected loopback capability at every public operation, enforces contract version 1, encodes path segments, maps one strong If-Match, parses direct DTOs/errors strictly, freezes safe error projections, avoids retries and cloud fallbacks, and returns stable runtime_unavailable without network access when the capability is absent or invalid. Optional add only creates a local UUID before delegating to PUT.
• No ML-08 changes, npm package, seed endpoint, manifest/hash/migration layer, cloud URL/Works credential, or forbidden runtime feature was added. Skill installation remains agent-driven by the canonical markdown workflow; tests cover the documented direct-text policy with src TypeScript, src JavaScript, and root TypeScript fixtures.

Verification

• Initial red focused run before implementation: the new SDK/Skill test file failed because the canonical asset directory and workflow did not yet exist.
• Focused SDK/Skill suite after implementation: pnpm exec vitest run tests/unit/data-service-sdk-assets.test.ts --maxWorkers=1 — 1 file / 14 tests passed, covering both assets, runtime injection/no-network behavior, path/ETag/body/delete semantics, strict DTO/error projection, no retry, registry/package listing, workflow ordering, and first/repeat/conflict fixture policy.
• Adjacent focused suite: pnpm exec vitest run tests/unit/data-service-sdk-assets.test.ts tests/unit/skill-display.test.ts tests/unit/pi-resource-loader.test.ts tests/unit/pi-product-tools.test.ts --maxWorkers=1 — 4 files / 29 tests passed.
• pnpm test — 188 files / 1610 tests passed, 2 skipped.
• pnpm typecheck — passed, including direct TypeScript asset compilation.
• pnpm lint:check — 0 errors and 5 pre-existing warnings in src/pages/Home/index.tsx and src/pages/Makelore/index.tsx.
• pnpm run build:vite — renderer, Main, preload, and utility builds passed; existing dynamic-import and large-chunk warnings remain.
• pnpm test:electron:windows — 2 files / 4 tests passed.
• pnpm exec playwright test tests/e2e/project-configuration-skills.spec.ts --config=playwright.config.ts — 1 test passed.
• git diff --check — passed. Task-aware drift check passed and task_context.py complete returned READY_FOR_INTEGRATION for this task.
• The parent coordinator's inherited full E2E evidence records one unrelated, pre-existing timeout at tests/e2e/pi-coding-first-chat.spec.ts:575 while the current-model combobox remained disabled; this ML-07 task did not rerun or mask that failure.

Follow-ups

• Parent coordinator must cherry-pick the single ML-07 commit into its client integration branch, run code review/remediation, and perform the required real PostgreSQL plus signed-in data-enabled preview acceptance. Repository tests and the focused E2E above do not claim live-service success.

Promotion Candidates

• None recorded.