[kentare]

What and why

The Kudos pilot from #92 as a draft, so its code and the evidence behind ADR 0040 in #125 can be read and linked. It is the spike and is not for merge as it stands: code that matches the ADR comes in its own PRs. It is stacked on #91 (the Marker service), so the diff shows only the pilot.

apps/api, apps/worker        # a separate knowledge server (KNOWLEDGE_DATABASE_URL), boot warning
packages/ingest              # stored Marker conversions, embedding cache, page-first chunks, KUDOS by UUID list
packages/providers-pgvector  # halfvec, stores for conversions and cached vectors
packages/port-embedding      # query and passage purposes
packages/eval/src/scripts/kudos-pilot-compare.ts   # Typesense and pgvector runs, per-question verdicts
benchmarks/
├── benchlib/                # from #126, unchanged
└── kudos-pilot/
    ├── engines/             # Typesense and pgvector
    ├── embeddings/          # 17 embedding setups, and genki's search step by step
    └── indexes/             # HNSW, IVFFlat and binary quantisation at a million vectors

What the benchmarks found, each from its results/report.md:

• Engines: pgvector finds the right document in the top ten for 95.8% of the 76 draft questions and Typesense for 84.6%: +11.2 points (+3.0 to +19.9). Against Typesense with its phrase step off, +7.5 (−0.7 to +16.5), not significant.
• Embeddings: ten versions of five models share the first tier by vector search alone; pplx-embed-v1-0.6b leads it, +8.9 points of page MRR over text-embedding-3-large. Inside genki's search every model ends up within about two points of text-embedding-3-large.
• Search steps: fusing keyword search with the vectors costs the most page MRR (−21.2 for pplx-embed, −9.3 for text-embedding-3-large). ColBERT orders pages no better than text-embedding-3-large's vectors.
• Indexes: HNSW finds 99% of the true nearest Kudos pages at a million vectors; binary quantisation matches it with an index eight times smaller.

The full write-up is in a comment on #29.

How it was tested

• npm run format:check, npm run lint, npm run typecheck and npm run boundaries pass; npx vitest run packages/eval passes (70 tests). npm test: 4,713 tests pass and one fails, the console's revisjon test in apps/console/src/app.test.tsx; this PR doesn't change apps/console, and the test passes on a branch with newer main.

• Each benchmark's report rebuilds from its results/ alone (report.py in engines, embeddings and indexes). python -m unittest test_report in engines and embeddings passes: the report refuses verdicts graded on an older reference, and every side is graded on every question of each view. benchlib's own tests pass.

• The runs themselves need the local pilot setup (two Postgres containers, a local Typesense copy, Marker and the embedding servers); benchmarks/kudos-pilot/README.md has the commands.

• npm run check passes (all but that one console test)

Checklist

• Every new rule has a test whose name states it
• User-facing text is in the i18n catalogues, in bokmål and English, with no em-dashes (no user-facing text)
• Vendor SDKs stay in packages/providers-*
• ADRs, docs and docs/architecture/modules are updated if a contract, boundary or module changed (ADR 0022 is amended here; ADR 0040 in Propose the knowledge database #125 replaces the design)
• No secrets, personal data or local paths

Merge danger

Door: two-way while it stays a draft. Merging it would bring the spike's ingest and storage changes into main, which ADR 0040 replaces.

Blast radius: none until merged.