feat(scan): opt-in multi-modal scan orchestration

[scotty595]

Summary

• New export governance-sdk/scan/multi-modal with a pluggable extractor registry and the scanMultiModal() orchestrator. Closes the bypass where image / PDF / audio blocks pass through enforce() unscanned.
• Ships orchestration only — actual OCR / PDF parsers / ASR are caller-supplied, preserving the zero-runtime-dep promise.
• Mirrors the existing InjectionClassifier pattern: async scanner interface + global registry + pre-enforce() invocation.

API surface

```ts
import {
registerModalityScanner,
scanMultiModal,
isFailClosed,
} from 'governance-sdk/scan/multi-modal';

registerModalityScanner('image', {
extractText: async (block) => ocrEngine.recognize(block),
});

const scan = await scanMultiModal(blocks, {
enabled: ['text', 'image'],
onMissingScanner: 'block',
onExtractError: 'block',
timeoutMs: 5_000,
});

if (isFailClosed(scan)) { /* block before enforce() */ }
// otherwise feed scan.text into the existing detectInjection / hybridDetect
```

Defaults (deliberately conservative)

• enabled: ['text'] — every other modality off until explicitly opted in
• onMissingScanner: 'skip', onExtractError: 'skip'
• timeoutMs: 30_000 per block

Failure modes (all surface in result.blocked[])

• no_scanner — enabled but no extractor registered
• extract_error — scanner threw (sync or async) or returned non-string
• extract_timeout — exceeded timeoutMs
• extract_empty — scanner returned null / undefined

Tests

20 new tests in src/scan/multi-modal.test.ts covering: defaults, opt-in modes, sync-throw and async-rejection paths, timeouts via Promise.race + setTimeout cleanup, registry CRUD, isFailClosed with mixed reasons. Full suite 1,392 / 0.

Merge order note

Modifies the README "Limitations" multi-modal bullet. If the README honesty pass PR merges first, this branch will have a trivial conflict on that one bullet — both edits are mine, easy resolve. Either way works; suggest merging the docs PR first.

Out of scope (follow-ups)

• Framework adapters (Anthropic / Vercel AI / Genkit / LlamaIndex / Bedrock) auto-calling scanMultiModal on detection of non-text blocks. Today the caller wires it in their host code.
• Optional reference packages (e.g. governance-sdk-scan-tesseract) shipping default extractors as separate peer-deps. Keeps the core SDK zero-dep.

Test plan

• npm run build clean
• npm test — 1,392 / 0
• Reviewer skims src/scan/multi-modal.ts for the timeout / sync-throw paths
• Reviewer confirms package.json exports field is correct

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds new security-adjacent scanning behavior and a new public export surface; incorrect host wiring or misunderstandings of failClosed/default opt-in semantics could lead to gaps or unintended blocking, though the change is additive and well-tested.

Overview
Adds a new governance-sdk/scan/multi-modal export that orchestrates opt-in text extraction for image/pdf/audio content blocks via a global registry (registerModalityScanner, unregisterModalityScanner, clearModalityScanners) and returns concatenated text plus structured scan outcomes and a pre-evaluated failClosed flag (isFailClosed helper).

Introduces timeout handling and explicit failure classification (no_scanner, extract_error, extract_timeout) while treating null/undefined extractor returns as benign “no text” results, backed by a comprehensive new test suite. Updates both READMEs to document that multi-modal scanning is now available but remains opt-in with caller-supplied OCR/PDF/ASR to preserve zero runtime deps.

^{Reviewed by Cursor Bugbot for commit f89155f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit df978db. Configure here.}