Files
streamline/docs/eddy/knowledge-catalog.md
T
2026-11-16 17:26:44 -08:00

48 lines
3.4 KiB
Markdown

# Eddy knowledge catalog v1
Reference materials, not executable distribution. All complete categories (source-bug,
devicesim, app-compat, unknown) are accepted and initially Enabled. Classification is
diagnostic metadata. It does not select replay behavior or require administrator/model approval.
The old compat API remains unchanged for old clients; new clients do not execute that feed.
Authenticated POST /api/eddy/knowledge accepts {document, files}, where files maps SHA-256
to base64. Document schema is eddy-knowledge-v1: id, title, category, confidence,
problem {description, steps, expected, actual, cause, signature?},
solution {description, kind, validation, rollback, contract?}, observedEnvironment,
origin {task?, derivedFrom?, legacy?}, attachments [{name, role, mediaType, sha256, bytes}].
Kinds: frida-js, devicesim-diff, launch-config, advice. JS needs a code attachment;
DeviceSim diff needs a diff attachment. Screenshots are optional and should contain only relevant evidence.
24 attachments maximum, 8 MiB each, 32 MiB total; text fields bounded and assets hash-checked.
An author can revise their record; an SSO administrator can also revise.
Eddy clients sign in through browser SSO (`eddy auth login`); ordinary employees receive a knowledge-only session without requesting an API key.
See [client SSO](client-sso.md) for the grant flow, session lifetime and deployment order.
Repeated content returns its immutable revision receipt; a new revision never undoes Disable.
GET /api/eddy/knowledge/feed?cursor=...&limit=50 delivers all enabled materials, independent
of installed baseline. Stable watermark pagination and serialized change sequence allocation
prevent skipped concurrent writes. A subsequent incremental pass catches writes after the
watermark. Disable is a tombstone; clients remove it from default retrieval without deleting
task edits already created from it. A concurrent disable can make an attachment unavailable;
clients keep the prior cursor and restart a full visibility scan on 404.
GET /knowledge/:id/:revision and /knowledge/assets/:hash read content; disabled content
is restricted to administrators. Baseline identity remains metadata for relevance and
local execution checks.
Administrator APIs under /api/eddy/admin:
- GET /knowledge: paged full catalog including Disabled, with latest action actor/time.
- POST /knowledge/:id/state with {enabled: boolean}: audited Enable / Disable.
- GET /knowledge/:id/export: ZIP containing knowledge.json, receipt.json, problem.md,
solution.md and every attachment. The extracted package is compatible with Eddy knowledge save.
Deployment: apply drizzle/0031_eddy_knowledge_catalog.sql before serving these routes.
Then explicitly run scripts/migrate-eddy-knowledge.ts against the intended database.
It preserves old material, author/ID/revision provenance and stopped states, never modifies
old-client compat states and skips imported revisions on repeat. Invalid/missing payloads
are reported for follow-up rather than silently discarded or fabricated.
Unsolved observations remain in the historical audit store; they are not invented solutions.
Review migration output before switching users to the new knowledge view.
Local validation: TEST_DATABASE_URL must point to a dedicated local PostgreSQL database.
Run bun test control-server/test/eddy_catalog.integration.test.ts and the existing
eddy_flow.integration.test.ts separately (both close their connection pool).