feat(kb): knowledge graph lifecycle and scoped retrieval on v3-ai

[rschlaefli]

What This Adds

This PR establishes the Klicker-owned knowledge-base lifecycle on v3-ai:

1. Lecturers can create knowledge bases, add document and website resources, dispatch ingestion, and attach a knowledge base to a course chatbot.
2. Knowledge-graph builds use the append-only KBGraphBuild ledger as the canonical lifecycle and publication record, with quota reservation, cost settlement, recovery, and retention behavior.
3. Chat resolves scoped retrieval from the owning thread and exposes the published knowledge graph without introducing a second graph-version lifecycle.

How It Works

Area	Behavior
Data model	Adds KB, KBResource, and the append-only KBGraphBuild ledger, including dispatch claims, cost accounting, publication pointers, retention metadata, and additive migrations.
Lecturer UI	Mounts packages/kb-management in frontend-manage for KB CRUD, document upload, website ingestion, graph status, and chatbot binding.
Graph runtime	Adds the FalkorDB-backed graph package, GraphML archive/export support, digest-based publication, and provider request cancellation.
GraphQL and Hatchet	Adds authenticated KB operations, quota and accounting services, ingestion workflows, stranded-build recovery, and maintenance jobs.
Chat	Mints short-lived ES256 scope tokens from the owning thread and carries (chatbotId, participantId, kbId, sessionId) through retrieval.
Delivery	Wires local runtime, deployment configuration, workers, tests, generated GraphQL artifacts, engineering docs, ADRs 0009–0018, and the production roadmap.

Important Details

• Merge with a merge commit; do not squash. This branch contains 48 Patrick Louis Aldover-authored commits whose authorship must be preserved.
• KBGraphBuild is the canonical version record. activeGraphBuildId and publishedGraphBuildId are the only liveness pointers; there is no separate KBGraphVersion lifecycle.
• Merge commit 65a209e52 reconciles the complete feature with current v3-ai at cb4b82429, preserving both sides across source, configuration, generated GraphQL, and lockfile paths.
• 9fb54d47f aborts timed-out provider requests and waits for settlement before reusing capacity. 789bc7285 preserves Next.js server-action constraints while retaining the typed MCP client API.
• c546f16d8 makes the canonical prisma-data test command run both retained test suites and keeps test:run as a compatibility alias.

Branch Coverage

• Base: live v3-ai at cb4b82429
• Head: c546f16d8
• Reviewed: 183 commits from v3-ai..HEAD; full diff 295 files, +40,921/−567
• Substantive size: 240 files, +33,759/−223 after excluding the lockfile, generated GraphQL outputs, and project/
• Covered: data model and migrations, lecturer management UI, graph runtime, GraphQL API, Hatchet lifecycle, scoped chat retrieval, deployment/runtime wiring, tests, ADRs, and roadmap

Review Focus

• Cost reservation and settlement: double charge, quota bypass, and leaked reservations after failures.
• Dispatch claims and recovery: duplicate dispatch, worker death, ambiguous provider correlation, and timeout cancellation.
• Authorization: KB CRUD, graph rebuild, chatbot attachment, owning-thread lookup, and scope-token minting.
• Retention: GraphML archive clocks, purge clocks after KB deletion, and permanent build-ledger history.
• Deployment coupling: graph provider endpoint, worker workflow name, environment wiring, and secret-versus-ConfigMap boundaries.

Verification

Current head c546f16d8:

• Repository commit hooks passed: staged gitleaks, 29 package type checks, formatting, lint, syncpack, AGENTS, removed-doc, and Prisma-sync checks.
• Normal pre-push pnpm run build passed: 26/26 tasks. Existing Rollup, Next.js i18n, large-page-data, and MISSING_MESSAGE warnings remained non-fatal.
• pnpm --filter @klicker-uzh/prisma-data test and test:run both passed; the Node suite ran 4/4 tests and the environment-dependent Vitest suite remained 6/6 skipped as designed.
• pnpm --filter @klicker-uzh/graphql generate produced no tracked diff. Chat passed 609/609 tests; Hatchet passed 101/101 tests, including timeout-abort regression coverage.
• Exact-head GitHub checks are running. No terminal CI result is claimed yet.

Failed/Warning:

• One exact-DevPod root check:all attempt stopped in the unrelated Analytics lint task: CPython 3.14 recreated its environment, pandas 2.2.2 fell back to a source build, and the image had no C compiler. The exact-head repository hooks and full build subsequently passed.
• devrouter lifecycle commands could not acquire the host route-update lock. Verification used the already-running exact DevPod through devpod ssh; no lock or unrelated runtime was interrupted.

Not run:

• No live graph-builder E2E against the external provider; that remains a separately authorized integration proof.
• No exact-head authenticated browser pass for this infrastructure finalization range. The child UX PR enhance(kb): streamline knowledge base management #5540 owns the current lecturer-page browser proof.

Security / Privacy

• A final read-only review found no blocking or ordinary correctness, security, concurrency, data-integrity, SSRF, cross-system, or server-action findings.
• The hardcoded CIDRs in publicUrl.ts are intentional public network metadata for the SSRF denylist. All ten Sonar threads were answered with this rationale and resolved.
• Scope tokens are server-minted ES256 tokens with owning-thread context, unique identifiers, and short expiry. The participant identifier remains inside Klicker.
• No secrets, personal data, or bulk exports were introduced. Local fixtures are synthetic.

Blocking Before Merge

• Exact-head GitHub checks must reach an accepted terminal state.
• The owner must explicitly authorize the merge, and the merge must preserve commit authorship with a merge commit.

Follow-Up After Merge

• Merge child PR enhance(kb): streamline knowledge base management #5540 after restacking and exact-head UI verification.
• Adapt the question-generation stack to the succeeded and published canonical KBGraphBuild ledger.
• Complete separately authorized live provider and GraphML restore proofs.

Local Session Artifacts

Machine-local pointers for a session resuming this branch, not review evidence.

• Worktree: trees/rs/kb-v3-ai-finalization in repository klicker-uzh
• Review reports: project/_local/reviews/2026-08-25-pr-5424-*.md
• Environment: DevPod rs-kb-v3-ai-finalization; use only while this finalization session remains active

[sonarqubecloud]

Quality Gate passed

Issues
105 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.2% Duplication on New Code

See analysis details on SonarQube Cloud