gobha
b7746c3004
Co-authored-by: gobha <jasafpro@gmail.com> Co-committed-by: gobha <jasafpro@gmail.com>
96 lines
5.2 KiB
Markdown
96 lines
5.2 KiB
Markdown
# 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
|