fix(kb,hft): document strategy trust model; runtime shape guard on HFT_TextReranker

[sroussey]

Why

Two High-severity findings from a security review of PR #484 (the KB strategy refactor).

H1 — IKbStrategyTarget is an undocumented trusted-code boundary

An installed IKbAiStrategy receives an IKbStrategyTarget that exposes the KB's full low-level storage surface (upsertDocument, deleteChunksForDocument, upsertChunksBulk, similaritySearch, hybridSearch). These operations bypass any application-level access control because scoping is implemented via virtual dispatch on the target instance — a malicious or buggy strategy can violate the scoping contract by routing data through a different KB. This trusted-code boundary needs to be documented so operators do not load strategies from untrusted sources, user input, or remote registries.

H2 — HFT_TextReranker cast was loose and accessed .score without validation

const rawResults = (await (reranker as unknown as (
  inputs: Array<{ text: string; text_pair: string }>,
  options?: Record<string, unknown>
) => Promise<Array<...>>)(pairs, { top_k: 1 })) as Array<...>;

const scores: number[] = rawResults.map((r) => {
  if (Array.isArray(r)) return r[0]?.score ?? 0; // silent fallback hides real bugs
  return r.score;                                 // unchecked .score access
});

A transformers.js pipeline producing a different shape (mismatched task, wrong field names, null entries) would silently return garbage scores rather than fail loudly.

What

• TSDoc trust-model paragraphs on IKbAiStrategy and IKbStrategyTarget spelling out that strategies are TRUSTED CODE and must not be loaded from untrusted sources.
• Pointer TSDoc on KnowledgeBase and setAiStrategy linking back to the trust model.
• Replaced the as unknown as cast with a runtime isScored shape guard.
• Added KbRerankerOutputError (co-located with TextRerankerTask in @workglow/ai, exported from the package barrel so callers instanceof-test).
• Extracted the validation as validateAndExtractRerankerScores(rawResults, modelPath): number[] — pure helper, no side effects, fully unit-testable. The run-fn delegates to it.
• Removed the silent ?? 0 fallback so a missing score now throws KbRerankerOutputError with the model path and a truncated shape snippet.
• Added shape-validation tests in packages/test/src/test/rag/HFT_TextReranker.shape.test.ts.
• Re-exported HFT_TextReranker (and the new helper) from @workglow/huggingface-transformers/ai-runtime so tests can reach them without deep-path imports.

Stacking

This PR is stacked: its base is claude/loving-mendel-bS9js-pr484 (the head of PR #496) so #496's fixes (rerank firstStageMinimum floor + KbSearchTask scoreThreshold forwarding) are preserved. Merge order: #484 → #496 → this PR.

Verification

• bun run build:types — confirm the new error class + helper typecheck cleanly across @workglow/ai and @workglow/huggingface-transformers.
• cd packages/test && bun test src/test/rag/HFT_TextReranker.shape.test.ts — exercise the shape guard (3 negative cases + valid mixed-form case + diagnostic-payload case).
• cd packages/test && bun test src/test/rag/ — regression check on the rest of the RAG suite.

Defense-in-depth (deferred)

A Proxy wrapper that enforces the KB's scope on every strategy-target call was considered (intercept upsertDocument / similaritySearch / etc. on the proxy and refuse calls that try to escape the installed ScopedKnowledgeBase). Deferred to a follow-up issue:

• adds per-call overhead on every low-level storage method;
• ScopedKnowledgeBase virtual-dispatch already provides the primary boundary;
• the trust model documented here is the higher-leverage fix for the immediate finding.

Risks

• Other hand-rolled getPipeline stubs elsewhere in the codebase may currently return shapes the old code silently absorbed via ?? 0. They will now throw KbRerankerOutputError instead. Grep for text-classification pipeline stubs before merging.
• Adding HFT_TextReranker to the ai-runtime barrel grows the runtime surface by one named export; the symbol is small and benign.

Rollback

Two independent commit groups so each H can be reverted on its own:

• docs(kb): … — H1 (TSDoc-only on KB types; no runtime change).
• fix(hft): … / test(hft): … — H2 (runtime guard + test).

---

https://claude.ai/code/session_01LkKCHC8q6b5e7Nwvc8L3M6

---

Generated by Claude Code

[sroussey]

Cherry-picked all 4 commits (ad6553b, a1ca800, 68ca1b1, 0a693f9) into claude/search-with-rerank-Rl4IX (PR #484) as bbbb76e, 839a257, 77391c0, efe16cf. The setAiStrategy trust-model pointer was merged into the existing method (its location had moved on the target branch since this PR was authored, so the rebased version added it next to the already-present method rather than reintroducing a duplicate block). Closing as integrated.

---

Generated by Claude Code