BF-08 — AI-native client layer: typed SDK + reactive useClinicalQuery (LISTEN/NOTIFY) + propose-only local MCP server

[AJ112103]

BF-08 — the AI-native client layer

Ships the typed SDK, the reactive useClinicalQuery store over Postgres LISTEN/NOTIFY, and a local propose-only MCP server. This is the first place an untrusted agent enters the system, so the slice makes two things structural rather than hoped-for:

1. subject comes from the BF-13-verified membership row, never from client input. The last two slices' panels kept flagging that buildCcp/searchClinical trust an in-process subject. BF-08 closes it: generated method inputs are Omit<CoreInput, "subject"> and the client merges { ...callerInput, subject } session-last, so a subject smuggled in at runtime is always overwritten by the membership-derived one. This is the real control — subject.practiceId already failed closed against the GUC, but subject.role and subject.id are trusted straight into decide() and the audit row.
2. The MCP tool surface is a static, frozen, three-tool allowlist with no raw SQL/FHIRPath/shell/filesystem tool and no approve/commit tool. Handlers close over the session-bound SDK client only — no db/sql handle ever enters handler scope.

Commit chain

commit	author	contents
4af2037	operator prep (gate base)	migration 0011 NOTIFY substrate, sdk+mcp scaffolds + frozen deps, Dockerfile COPYs, depcruise mcp → sdk reconcile, sgrules, contract-drift reconcile, ledger
d45ce01	maker (Fable)	packages/sdk/** + packages/mcp/** only — 30 files, 30 tests
97a741c	harden wave (Opus probes)	one strengthened test oracle
403aec3	panel wave	canonical snapshot digest, MCP import allowlist, Object.freeze

Allowed-paths attribution verified: git diff --name-only 4af2037..d45ce01 lists only packages/sdk/** and packages/mcp/**. Every off-floor file (drizzle, sgrules, depcruise, knip, docker, loop) lives in the disclosed operator commits.

Design decisions (two independent Opus design reviews, pre-implementation)

• mcp → @bonfire/sdk, not mcp → core. Both reviewers converged: making the MCP re-implement verifyToken → resolveMembership → withTenant would create a second authz boundary that drifts — the classic fail-open. The depcruise rule was reconciled in prep (disclosed); sdk → mcp stays forbidden.
• get_context chains search → buildCcp entirely server-side. The SearchResponse never round-trips through the model, which removes the forged-receipt surface and the unbounded-results DoS lever (ccpInputSchema.response.results has no .max).
• The write tool is honest. writeScribeResource runs no decide() and appends no audit row — it is a live, ungoverned commit. The tool says so, returns a minimal confirmation, and fabricates no policy receipt. Contract acceptance H4 — memory spine: STATE ledger + bug-patterns KB + loop ratchet + VERDICT schema #8's receipt requirement is scoped to "the underlying read", which the two read tools satisfy.
• LISTEN before snapshot. The initial RLS-scoped snapshot runs inside onListen, so one idempotent path covers both first load and every reconnect; snapshot-then-listen would leave a missed-commit window.
• The NOTIFY payload is a constant table name. Channels have no ACLs and any role can pg_notify any channel, so tenant scoping of data never rides the wire: a spoofed NOTIFY is a harmless re-query, and emission requires the session's own RLS-scoped content digest to change.

De-risk (proven live before any code)

• Event-trigger stamping of the notify triggers survives projections:rebuild (8 triggers before and after); delivery is at-commit only (rollback → silence); listener latency ~2 ms against a 2 s budget.
• @modelcontextprotocol/sdk@1.29.0 + zod 4 + bun: unknown tool and off-schema argument are rejected before the handler runs, returned as isError results rather than JSON-RPC rejections (tests assert result.isError, not rejected promises).
• @microsoft/api-extractor@7.58.9 against TS 6.0.3: CI mode exits 0 on an identical report and 1 on drift; needs newlineKind: "lf" and customConditions: [] (BP-031's @bonfire/source condition would otherwise resolve deps to src).

Review: 5-agent panel + 6-lens adversarial harden pass

Zero HIGH/BLOCKING code defects. All three danger-class refuters (propose-only-broken, cross-tenant-leak, fail-open+injection) broke nothing at high confidence; the security auditor returned PASS. Attacks attempted and blocked: subject smuggling via spread order / __proto__ / getters (defeated by Omit + session-last merge + zod strip), forged receipt into get_context (server-side chain + receiptMatches), spoofed NOTIFY (constant payload + content-diff), off-schema and unlisted-tool calls (double validation, zero side effects), error-text injection (fixed code→static-string table; error.message never forwarded).

Findings that were real and are fixed here:

• U2 forensic gap (97a741c): session.test.ts asserted only the deny code, so the mutation "stop calling auditAuthFailure" left the whole suite green while failed-auth forensics vanished. Now oracled against the SYSTEM hash chain, keyed on a unique actor_id — deliberately not a count(*) delta, which races under turbo's parallel suites.
• U3 digest (403aec3): the snapshot hash used JSON.stringify(rows), leaning on postgres.js key order staying accidentally stable. Now sha256Hex(canonicalizeJson(JSON.parse(JSON.stringify(rows)))). The JSON round-trip is load-bearing and comes first: canonicalizeJson over driver rows would serialize a Date as {} (no own enumerable keys), collapsing every timestamp so a last_updated-only change would emit nothing. The round-trip normalizes Dates to ISO strings, then RFC-8785 sorts keys.
• MCP import allowlist (403aec3): no-egress-in-mcp was a denylist, evadable by anything it forgot. packages/mcp/src may now import only @bonfire/sdk, @bonfire/core, @modelcontextprotocol/sdk, zod, and its own modules; everything else fails closed. Inversion-proven: clean tree → ast-grep scan exit 0; a real import { readFileSync } from "node:fs" → exit 1; restored → exit 0. The same control written as a dependency-cruiser rule was rejected as inert — the config's includeOnly filters node builtins out of the graph, so it could never fire (proven by injection). Global-reachable vectors an import allowlist structurally cannot see (Bun.$, Bun.file, Bun.write, Bun.connect) were added to the denylist.

Verification status — please read before merging

Green at d45ce01: strict slice gate 14/14 (loop gate --slice BF-08 --base 4af2037 --strict), sdk 17/0, mcp 13/0, turbo gate 33/33 including both api-extractor CI gates.

Green at 403aec3 (this HEAD), DB-free: tsc -b, full-program eslint ., biome ci, ast-grep 13/13 + scan, check:comments, knip, jscpd, depcruise, semgrep, no inline suppressions.

Not re-run locally at this HEAD: the DB-backed suites and the strict gate. The dev machine's disk filled and the Docker daemon will not start, so 97a741c (test-only) and 403aec3 (which touches the reactive digest) have not been exercised against a live Postgres locally. CI is the live proof for this PR — it boots its own stack and runs the suites, bun run loop eval, conformance, and the round-trip/PHI gates. Do not merge on red CI.

Still owed after CI is green (operator, next session): the 7 danger inversions (mutate → RED → restore) against a live stack, a clean-room fresh-volume boot, and the panel's extra probe of the live tools/list inputSchema shape.

Deferred / accepted residuals (disclosed)

• The write path runs no decide() and appends no audit row — a real intra-tenant authz/audit gap, RLS-scoped and honestly described. BF-09 owns propose → approve → commit governance; a biller-session-proposes-must-be-denied eval belongs to that slice.
• packages/core/src/ccp/serialize.ts header fields are not JSON-encoded, contradicting that file's own docblock. Out of this slice's floor; non-exploitable today (each such field is a z.uuid(), a fixed FHIR literal, a DB-generated timestamp, or a static leaf-path entry — none can carry a newline). Flagged to the BF-07 owner.
• Per-statement pg_notify takes a cluster-wide commit lock: a tenant spamming writes is a throughput ceiling. Deliberate v0 posture; upgrade path is one coalesced NOTIFY per transaction.
• authenticate() has no outer try/catch (it trusts each dependency's Result contract). Proven still fail-closed: a throwing verifier rejects main(), the process exits non-zero, and the server is never constructed.
• propose_resource connotes staging that does not exist yet; the emphatic description and minimal confirmation output are the mitigation. Revisit the name when BF-09 lands real governance.
• Permanently-silent postgres.js reconnect gives no staleness guarantee — refresh() is the escape hatch, polling is the upgrade path. Only db.end() reclaims the listen socket.
• bf08-* Stage-2 evals + the no-raw-response-string-in-mcp-serialize sgrule are the post-merge close-out wave (loop/** is maker-forbidden). Ratchet candidates: BP-038 (mcp egress denylist), BP-039 (mcp import allowlist).
• Greptile waived — not wired to this repo.

🤖 Generated with Claude Code

[AJ112103]

CI green at 403aec3 — 12/12

The DB-backed build-test / test job is the live proof the local stack could not give (dev-host disk exhausted, Docker daemon down). It booted its own Postgres and ran the suites at this HEAD, so the two commits that were only DB-free-verified locally (97a741c, 403aec3) are now exercised against a real database:

• @bonfire/sdk:test — 18 tests (17 at d45ce01 + the new all-views (id, row_index) catalog assertion)
• @bonfire/mcp:test — 13 tests
• @bonfire/core:test 251, @bonfire/sql-on-fhir:test 56, @bonfire/api:test 18, seed 2, loop 199
• bun run loop eval — ✓ 29 passed, 0 failed (the pre-existing Stage-2 corpus still green with the 0011 NOTIFY trigger installed, which is acceptance ci: boot the compose stack for DB-backed product tests #10's regression clause)

This matters most for 403aec3: the reactive suite that passed includes the same-practice <2s emission test and the cross-tenant no-emission test (which proves practice A's re-query ran and the content digest suppressed the emit). That is the path the canonicalized snapshot digest changed, and it holds on a real database.

Plus the full static/quality set: typecheck, lint, format, structural (ast-grep 13/13 + scan), boundaries (depcruise), suppressions, semgrep, gitleaks (working tree + history), knip, jscpd, build.

Still owed before this is fully closed out (operator, once the dev host has disk)

CI proves the acceptance criteria; it does not prove the tests are load-bearing. These remain:

1. The 7 danger inversions (mutate → RED → restore): a 4th tool in ALLOWLIST; caller-last subject merge; delete the no-membership deny branch; stub auditAuthFailure; raw-interpolate a field in renderSearchText; remove the content-diff early return; main.ts continue-on-auth-failure.
2. Clean-room fresh-volume boot + loop gate --slice BF-08 --base 4af2037 --strict (was 14/14 at d45ce01).
3. The panel's extra probe: inspect the live tools/list inputSchema JSON. registerTool receives a full z.strictObject rather than a ZodRawShape; security is unaffected either way because tools.ts:91 re-parses with safeParse before the handler runs (and the shipped test asserts additionalProperties: false plus an isError + zero-audit-row oracle on a smuggled practiceId key), but the emitted schema shape deserves a direct look.

Two of the three sgrule guards added here were inversion-proven locally (ast-grep scan exit 0 clean → exit 1 with a real node:fs import → exit 0 restored). The dependency-cruiser version of that same rule was rejected as inert and reverted: the config's includeOnly filters node builtins out of the graph, so it could never fire — proven by injection rather than assumed.