Fuente: ddx-documentation/adr/0021-diagnosis-engine.md
- **Status:** Accepted (plan `diagnosis-engine`, reconciled 2026-11-12). - **Refines:** [ADR 0015](/es/docs/adr/0015-entity-kernel) (entity kernel), [ADR 0016](/es/docs/adr/0016-sse-bus) (one realtime path), [ADR 0017](/es/docs/adr/0017-bff-layered) (BFF only), [ADR 0014](/es/docs/adr/0014-unified-settings) (settings registry). - **Plan:** `plans/diagnosis-engine/` (`_index.md`, `_invariants.md`). - **Design sources:** IBIS diagnosis backend and the ADE spec, re-implemented with `@origin` lines. No HMS code, likelihood values, packs or FHIR coupling were copied. - **Docs:** [osprey-engine.md](/es/docs/osprey-engine) §Diagnosis engine, [features.md](/es/docs/features) §5g, [settings.md](/es/docs/settings) §Diagnosis keys. ## Context Osprey gained a per-specialty diagnosis engine. A doctor enters one patient or a cohort. The engine retrieves over curated disease cards, scores deterministically, asks the doctor targeted questions, and returns a report, standard guidance, a checklist, an orientation and a scorecard (a cohort gets a summary). Cards are versioned and change only through a reviewed loop fed by doctor feedback and by unattended research. Constraints that shaped the decisions: - Patient data must never leave the host (no web search, no non-Dudoxx model). - A clinical outcome must be replayable and auditable: the same evidence gives the same result. - Osprey workspace contracts win on HOW: BFF only, Centrifugo only, Postgres `osprey.event` as authority, inventory-only pages, four locales, settings registry for every tunable. - Deep runs cannot suspend; a diagnosis run must wait for the doctor's answers. ## Decision 1. **Model-free deterministic core.** `packages/ddx-diagnosis-core` (`@ddx/diagnosis-core`) holds scoring (log-odds Bayes with a seeded Monte Carlo interval), expected-information-gain questions, red flags, must-not-miss, fail-closed safety and the deterministic outputs. It imports no model, Mastra, pg or network module. The same evidence set gives the same `resultHash` with zero model calls. 2. **Knowledge is engine-owned and shared; the case is kernel-owned.** Cards, concepts, labels, revisions, evidence and packs live in the engine `osprey` schema (`sql/017`), with no tenant, user or patient column. Casework (`dx_run`, `dx_question`, `dx_output`, `dx_feedback`, `sql/018`) is owner-scoped. The `DiagnosisCase` aggregate lives in `ddx_main` as the kernel entity `diagnosisCase`, so org ACL, audit and list views come from the kernel. Cards are read through the bridge like deep runs, so no new kernel backing path was needed. 3. **No new lane, no new event type, no deep-content fork.** A dedicated workflow `osprey-diagnosis` mirrors deep-content. Progress rides `progress.data.dx` (`DxProgressData`), and the doctor's questions ride `run.suspended` kind `form`. The workflow suspends at a step; deep runs cannot. A suspended run holds no lease. A run lease of kind `diagnosis` (`run_claim.kind` widened by `sql/018`) is adopted by the recovery sweep, which restarts the run from its snapshot. 4. **Hybrid retrieval.** Concept lookup is a normalisation cascade (code, exact label, `pg_trgm` trigram, vector, else unmapped). Candidates are fused by reciprocal-rank fusion over pack findings, Qdrant `osprey_dx_knowledge` chunks and finding overlap. The collection dimension comes from `DUDOXX_EMBEDDING_DIMENSION`, never a literal. 5. **Every tunable is a `module.diagnosis.*` setting.** The 19 keys travel in the run-start body (`DxSettings`), never in the `x-osprey-settings` header (the engine rejects unknown header keys). Code constants are seeds only. 6. **Fail-closed safety.** A red flag pins must-not-miss cards and raises urgency. A check that cannot run is `blocked_unknown`, never `pass`. Guidance is withheld on `blocked` and `blocked_unknown`, and the UI shows both as a blocking banner. Report sentences without a resolvable evidence id are stripped. Every output carries the doctor-review disclaimer. 7. **Governed curation.** A card revision reaches `published` only through `decide()` with a real reviewer id AND a passing promotion gate. Seeds publish only through the operator-run `osprey dx pack install`. Proposals come from doctor feedback (`feedbackMinSupport`) or from the curator. The promotion gate replays the specialty gold set; must-not-miss recall below the published baseline is `gate_failed`, with no override. Top-5 recall may drop by at most `gateTop5Tolerance`. 8. **The curator is a client of deep-content.** It builds a research brief from card fields only, imports no casework module (so it carries no patient data), starts a deep-content run on a dedicated system session, and turns the finished run into PENDING proposals. It never publishes. Every ddx-api node fires the scheduler tick; the engine dedups by the unique `dx_curator_job` window key. 9. **Authority split on the API.** The case routes run under the caller's org role. Proposal decisions and the manual curator tick are platform super-admin only. The engine permission `diagnosis:curate` is a handler grant added after `PlatformRoleGuard` admitted the caller, never mapped to an org role. `diagnosis:system` is a system permission for the scheduler only. 10. **Pseudonymous intake.** `DxPatientIntake` is strict: no name, birth date or record id. Intake never appears in kernel summary projections, live events or Centrifugo payloads. ## Consequences - Clinical results are replayable. The eval harness has an outside judge: suite `dx-eval-golden` scores each specialty's gold set (20 cases each for dermatology, gastroenterology and cardiology; must-not-miss recall 1.0 at seed time) and `dx-core-determinism` replays hashes. - "Learns" is measurable: a proposal that regresses must-not-miss recall cannot publish. - Knowledge changes are slow by design. Each change needs a human reviewer, and the curator output waits in the queue. - The curator depends on deep-content. A change to that module's start contract affects the curator. - The three specialties ship as seed packs (`osprey-dx-pack/1`, semver 0.1.0, 12 cards each). A new specialty needs a pack, a gold set and a baseline entry. - Not built (deferred): FHIR/EHR integration, paid external medical APIs, MDR certification work, a drug-interaction plane, a chat catalogue tool for diagnosis, CSV cohort import, per-org card overlays. ## Rejected alternatives - **Reuse the deep-content workflow and runtime.** Deep runs cannot suspend, so the doctor could not answer questions. - **Cards in `ddx_main` as kernel entities.** Cards are shared knowledge with immutable revisions, and the engine needs them next to the trigram and vector index. A kernel entity adds a backing path for no gain. - **Model-scored differentials.** They are not replayable and cannot be gated by a gold-set judge. ## Verification ```sh test -f ddx-documentation/adr/0021-diagnosis-engine.md rg -q -i 'diagnosis' ddx-documentation/features.md ddx-documentation/osprey-engine.md pnpm -C ddx-osprey-engine osprey suite run dx-core-determinism dx-eval-golden dx-run-live dx-curator-live ``` --- Last reconciled: 2026-11-12 · plan diagnosis-engine task 036
diagnosis-engine, reconciled 2026-11-12).plans/diagnosis-engine/ (_index.md, _invariants.md).@origin lines. No HMS
code, likelihood values, packs or FHIR coupling were copied.Osprey gained a per-specialty diagnosis engine. A doctor enters one patient or a cohort. The engine retrieves over curated disease cards, scores deterministically, asks the doctor targeted questions, and returns a report, standard guidance, a checklist, an orientation and a scorecard (a cohort gets a summary). Cards are versioned and change only through a reviewed loop fed by doctor feedback and by unattended research.
Constraints that shaped the decisions:
osprey.event as
authority, inventory-only pages, four locales, settings registry for every tunable.packages/ddx-diagnosis-core (@ddx/diagnosis-core) holds
scoring (log-odds Bayes with a seeded Monte Carlo interval), expected-information-gain questions,
red flags, must-not-miss, fail-closed safety and the deterministic outputs. It imports no model,
Mastra, pg or network module. The same evidence set gives the same resultHash with zero model calls.osprey schema (sql/017), with no tenant, user
or patient column. Casework (dx_run, dx_question, dx_output, dx_feedback, sql/018) is
owner-scoped. The DiagnosisCase aggregate lives in ddx_main as the kernel entity
diagnosisCase, so org ACL, audit and list views come from the kernel. Cards are read through the
bridge like deep runs, so no new kernel backing path was needed.osprey-diagnosis
mirrors deep-content. Progress rides progress.data.dx (DxProgressData), and the doctor's
questions ride run.suspended kind form. The workflow suspends at a step; deep runs cannot.
A suspended run holds no lease. A run lease of kind diagnosis (run_claim.kind widened by
sql/018) is adopted by the recovery sweep, which restarts the run from its snapshot.pg_trgm
trigram, vector, else unmapped). Candidates are fused by reciprocal-rank fusion over pack findings,
Qdrant osprey_dx_knowledge chunks and finding overlap. The collection dimension comes from
DUDOXX_EMBEDDING_DIMENSION, never a literal.module.diagnosis.* setting. The 19 keys travel in the run-start body
(DxSettings), never in the x-osprey-settings header (the engine rejects unknown header keys).
Code constants are seeds only.blocked_unknown, never pass. Guidance is withheld on blocked and
blocked_unknown, and the UI shows both as a blocking banner. Report sentences without a
resolvable evidence id are stripped. Every output carries the doctor-review disclaimer.published only through decide() with a real
reviewer id AND a passing promotion gate. Seeds publish only through the operator-run
osprey dx pack install. Proposals come from doctor feedback (feedbackMinSupport) or from the
curator. The promotion gate replays the specialty gold set; must-not-miss recall below the
published baseline is gate_failed, with no override. Top-5 recall may drop by at most
gateTop5Tolerance.dx_curator_job
window key.diagnosis:curate is a handler grant added after PlatformRoleGuard admitted the caller, never
mapped to an org role. diagnosis:system is a system permission for the scheduler only.DxPatientIntake is strict: no name, birth date or record id. Intake
never appears in kernel summary projections, live events or Centrifugo payloads.dx-eval-golden
scores each specialty's gold set (20 cases each for dermatology, gastroenterology and cardiology;
must-not-miss recall 1.0 at seed time) and dx-core-determinism replays hashes.osprey-dx-pack/1, semver 0.1.0, 12 cards each). A new
specialty needs a pack, a gold set and a baseline entry.ddx_main as kernel entities. Cards are shared knowledge with immutable revisions, and
the engine needs them next to the trigram and vector index. A kernel entity adds a backing path for
no gain.Last reconciled: 2026-11-12 · plan diagnosis-engine task 036
adr/
deploy/
research/
test -f ddx-documentation/adr/0021-diagnosis-engine.mdrg -q -i 'diagnosis' ddx-documentation/features.md ddx-documentation/osprey-engine.mdpnpm -C ddx-osprey-engine osprey suite run dx-core-determinism dx-eval-golden dx-run-live dx-curator-live