# ICD Drift Audit — SDK vs Backend

**Date:** 2026-03-23
**Method:** Compared `src/js/sw/sdk/api-domains.js` against `docs/ICD/*.md` and `server/main.go`.
**Principle:** ICD is the zone of truth. SDK must conform to it.

---

## A. SDK Bugs — Wrong method or path (fix in SDK)

| SDK Method | SDK Calls | Backend Route | Issue |
|---|---|---|---|
| `workflows.update(id, data)` | `PUT /workflows/:id` | `PATCH /workflows/:id` | `crud()` generates PUT; backend is PATCH → 404/405 |
| `workspaces.update(id, data)` | `PUT /workspaces/:id` | `PATCH /workspaces/:id` | Same — `crud()` generates PUT; backend is PATCH |
| `tasks.start(id, data)` | `POST /tasks/:id/start` | `POST /tasks/:id/run` | Path mismatch → 404 |
| `tasks.stop(id)` | `POST /tasks/:id/stop` | `POST /tasks/:id/kill` | Path mismatch → 404 |
| `dataPortability.deleteAccount(data)` | `POST /profile/delete` | `DELETE /me` | Both method and path wrong |

## B. SDK Bug — Duplicate key overwrites (fix in SDK)

`notifications` is defined **three times** as a top-level key in the `createDomains` return object:

1. **Line 186** — Domain #11 (has `prefs`, `setPref`, `delPref`, uses `POST` for markRead)
2. **Line 431** — Inside `admin` namespace (correct, no conflict)
3. **Line 501** — "Misc" section (uses `PATCH` for markRead, no preference methods)

JavaScript last-write-wins: #3 overwrites #1. The notification preference methods (`prefs`, `setPref`, `delPref`) are silently lost. The `markRead` method changes from POST to PATCH (PATCH matches the ICD, so #3 has the correct HTTP method but is missing methods).

**Fix:** Delete the duplicate at line 501. Merge its `del` method and `PATCH` fix into the domain #11 block at line 186.

## C. ICD Gaps — Endpoints exist in main.go, not documented in ICD

These endpoints are real (registered in main.go, used by the SDK) but have no ICD documentation.

| Endpoint | Belongs in ICD File | Notes |
|---|---|---|
| `POST /channels/:id/mark-read` | channels.md | SDK: `channels.markRead()` |
| `POST /channels/:id/generate-title` | channels.md | SDK: `channels.generateTitle()` |
| `POST /channels/:id/summarize` | channels.md | SDK: `channels.summarize()` |
| `GET /channels/:id/messages/:msgId/siblings` | channels.md | SDK: `channels.siblings()` |
| `GET /knowledge-bases-discoverable` | knowledge.md | SDK: `knowledge.discoverable()` |
| `GET /folders`, `POST`, `PUT /:id`, `DELETE /:id` | (new section) | Full CRUD, needs own ICD section or add to channels.md |
| `GET /users/search?q=...` | (new section) | SDK: `users.search()` |
| `POST /presence/heartbeat`, `GET /presence` | (new section) | SDK: `presence.heartbeat()` |
| `GET /usage` | (new section) | SDK: `usage.mine()` |
| `GET /groups/mine` | (new section) | SDK: `groups.mine()` |
| `GET /export/me` | utility.md | SDK: `dataPortability.exportMe()` |
| `DELETE /me` | utility.md | GDPR account deletion |
| `GET /git-credentials`, `POST`, `DELETE /:id` | (new section) | SDK: `git.credentials.*` |
| `POST /git-credentials/generate` | (new section) | Not in SDK — SSH key generation |
| `GET /git-credentials/:id/public-key` | (new section) | Not in SDK |
| `GET /tools` | (new section) | SDK: `tools.list()` |

## D. ICD-Documented Endpoints Missing from SDK

In the ICD but the SDK doesn't expose them. Add only as surfaces need them.

| Endpoint | ICD File | Notes |
|---|---|---|
| Workflow stages CRUD (`GET/POST/PUT/DELETE /workflows/:id/stages/*`) | workflows.md | Workflow editor needs these |
| `PATCH /workflows/:id/stages/reorder` | workflows.md | |
| `POST /workflows/:id/publish` | workflows.md | Team-scoped version exists in SDK |
| `POST /workflows/:id/start` | workflows.md | Instance creation |
| `GET /channels/:id/workflow/status` | workflows.md | |
| `POST /channels/:id/workflow/advance` | workflows.md | |
| Workspace archive (`download`, `upload`) | workspaces.md | |
| `POST /workspaces/:id/reconcile` | workspaces.md | |
| `GET /workspaces/:id/stats` | workspaces.md | |
| `GET /workspaces/:id/index-status` | workspaces.md | |
| `POST /workspaces/:id/git/clone`, `git/pull` | workspaces.md | |
| `GET /extensions/:id/manifest` | extensions.md | |
| `GET /extensions/tools` | extensions.md | |
| `POST /personas/:id/avatar`, `DELETE` | personas.md | User-scoped (admin-scoped exists) |
| `POST /knowledge-bases/:id/rebuild` | knowledge.md | |

## E. Response Shape Mismatches

| Endpoint | Response Shape | Convention | Notes |
|---|---|---|---|
| `GET /api-configs` | `{"configs": [...]}` | Should be `{"data": [...]}` | SDK `_unwrap` won't strip |
| `GET /admin/configs` | `{"configs": [...]}` | Should be `{"data": [...]}` | Same |
| `GET /admin/models` | `{"models": [...]}` | Should be `{"data": [...]}` | Same |
| `GET /admin/users` | `{"users": [...]}` | Should be `{"data": [...]}` | Same |

These use named keys instead of the `{"data": [...]}` envelope convention. The SDK's `_unwrap` doesn't strip these, so consumers get the envelope object.

---

## Recommended Priority

1. Fix §A (SDK 404s) — these are broken in production
2. Fix §B (duplicate notifications key)
3. Document §C (ICD gaps) — endpoints work, just undocumented
4. Add §D methods to SDK — only as surfaces need them
5. Migrate §E response shapes to `{"data": [...]}` — breaking change, defer