From dde45c76a6b56e615ba812f2c73065517b6e008b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Fri, 7 Aug 2026 20:13:39 +0200 Subject: [PATCH 1/8] Run CodeQL against the TypeScript tree Static analysis was the one class of check the pipeline had no answer for: lint catches style, the type checker catches shape, the tests catch behaviour, and nothing walked the data flow from an untrusted input to a sink. This is GitHub's default setup written out as a workflow file, so the query suite, the excluded paths and the schedule sit in the diff rather than behind a settings toggle. Pull requests and a weekly run on the default branch. No push trigger: everything reaches main through a pull request that was already analysed, and the weekly run is what keeps the Security tab current. src/generated is excluded. Extracting the 9 MB Prisma client costs minutes and can produce nothing anyone would act on, because the fix for anything found in there is to regenerate it. --- .github/workflows/codeql.yml | 73 ++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 .github/workflows/codeql.yml diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 000000000..286f9d079 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,73 @@ +name: CodeQL + +# Static analysis for the TypeScript tree. This is GitHub's default setup +# expressed as a workflow file rather than enabled from the repository +# settings, so the query suite, the excluded paths and the schedule are +# reviewable in the diff like everything else here. +# +# Deliberately NOT on `push: main`. The weekly run already analyses the +# default branch, which is what keeps the Security tab current, and every +# change reaches `main` through a pull request that is analysed on the way +# in. Adding a push trigger would analyse the same tree a second time +# minutes later for no additional signal. +on: + pull_request: + branches: [main] + schedule: + # Mondays, 04:27 UTC. Off the hour so the run does not queue behind + # everyone else's midnight cron. + - cron: "27 4 * * 1" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: codeql-${{ github.ref }} + cancel-in-progress: true + +jobs: + analyze: + name: Analyse javascript-typescript + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read + # Required to write the results into the repository's code-scanning + # alerts. Free for public repositories. + security-events: write + # Required by the CodeQL action to read workflow run metadata. + actions: read + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # `build-mode: none` is the correct mode for JavaScript/TypeScript — + # CodeQL extracts from source and needs neither a compile step nor + # installed dependencies. + # + # The excluded paths are all generated or vendored output. Chief + # among them is `src/generated`, the ~9 MB Prisma client with a + # 224 KB inline schema literal in it: extracting that costs real + # minutes and can produce nothing actionable, because nobody edits + # it and the fix for anything found there is `pnpm prisma generate`. + - name: Initialise CodeQL + uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6 + with: + languages: javascript-typescript + build-mode: none + config: | + paths-ignore: + - src/generated + - .next + - dist + - coverage + - playwright-report + - test-results + - public + + - name: Analyse + uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6 + with: + category: "/language:javascript-typescript" From 460049bf679a8c97cb5bc996d72499177d4f79aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Fri, 7 Aug 2026 20:13:54 +0200 Subject: [PATCH 2/8] Scan the lockfile with dev dependencies and the published image, daily Two questions the existing scans cannot answer. The dependency audit runs with --prod, which is the right scope for a blocking gate but leaves a gap: a dev dependency can still ship. pdfjs-dist is the case that made this concrete. It sits in devDependencies, and rasterize-pdf.ts imports it at runtime, so standalone output tracing copies it into the production image where the prod-scoped audit has never looked. Trivy reads 627 packages out of pnpm-lock.yaml without --include-dev-deps and 1455 with it; pdfjs-dist is only in the second set. Trivy's help text lists the flag as npm/yarn/gradle only, but it works on the pnpm lockfile too, which is worth knowing before someone deletes it as a no-op. The container scan builds the image from the current main. Nobody runs that image. What self-hosters pull is the one built from the last release tag, and an advisory published after the tag lands against an image nothing is about to rebuild. So the second job scans ghcr.io/mbombeck/ healthlog:latest instead of a local build. Schedule only, no push or pull_request trigger, because the change- triggered half is already covered and would just run twice. The lockfile job reports into code scanning without failing: widening to dev dependencies surfaces transitive tool advisories by the dozen, and a red badge from day one gets muted inside a week. The image job fails on CRITICAL, after its own report has been uploaded by a separate step. --- .github/workflows/trivy.yml | 164 ++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 .github/workflows/trivy.yml diff --git a/.github/workflows/trivy.yml b/.github/workflows/trivy.yml new file mode 100644 index 000000000..235c8ea63 --- /dev/null +++ b/.github/workflows/trivy.yml @@ -0,0 +1,164 @@ +name: Trivy Scheduled Scan + +# Two scans that the per-change gates cannot do, on a daily cadence. +# +# What already exists and is NOT repeated here: +# - `security.yml` → `dependency-audit` runs `pnpm audit --prod` on every +# push and pull request, blocking on HIGH/CRITICAL. +# - `security.yml` → `docker-security` builds the image on a push to `main` +# and runs `trivy image` against it, blocking on HIGH/CRITICAL. +# +# Both are change-triggered, and both answer "is this change safe". Neither +# answers "is what we shipped last week still safe", because an advisory +# published today lands against an image nobody is about to rebuild. That is +# what the schedule is for. There is deliberately no push or pull_request +# trigger: adding one would run the same scan the `docker-security` job +# already ran, minutes later, on the same tree. +on: + schedule: + # Daily, 05:17 UTC. + - cron: "17 5 * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: trivy-scheduled + cancel-in-progress: true + +jobs: + filesystem: + name: Lockfile (including dev dependencies) + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + security-events: write + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # `pnpm audit --prod` is the blocking gate and it is scoped to + # production dependencies on purpose: a dev-only advisory should not + # stop a release. The gap that scoping leaves is that "dev dependency" + # and "not in the image" are not the same statement. + # + # `pdfjs-dist` is the worked example. It sits in `devDependencies`, + # and `src/lib/documents/rasterize-pdf.ts` imports it at runtime, so + # Next's standalone output tracing copies it into the production + # image. `pnpm audit --prod` cannot see it. This scan can: without + # the flag Trivy reads 627 packages out of `pnpm-lock.yaml`, with it + # 1455, and `pdfjs-dist` is only in the second set. + # + # Trivy's own `--help` lists the flag as supported for npm, yarn and + # gradle. It works on `pnpm-lock.yaml` too; the help text is behind + # the parser. Verified against this repository before this workflow + # was written, and worth re-checking if the package count ever + # collapses back to the production figure. + # + # Report-only, and that is a deliberate choice rather than a soft + # one. The findings this widening surfaces are overwhelmingly + # transitive dev-tool advisories with fixes available upstream; + # failing the run on them from day one produces a red badge that gets + # muted within a week, and a muted signal is worse than none. The + # SARIF upload puts every finding in the repository's code-scanning + # alerts, which persist, notify, and can be triaged one at a time. + # The blocking answer to "does this ship" stays where it is, in + # `security.yml`. + - name: Trivy filesystem scan + uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0 + env: + # No action input maps to `--include-dev-deps`; Trivy reads every + # flag from a `TRIVY_`-prefixed environment variable, so this is + # the documented way to reach it through the action. + TRIVY_INCLUDE_DEV_DEPS: "true" + with: + scan-type: fs + scan-ref: . + scanners: vuln + format: sarif + output: trivy-filesystem.sarif + severity: "CRITICAL,HIGH,MEDIUM" + limit-severities-for-sarif: true + exit-code: "0" + # Generated Prisma client. Nobody edits it, the fix for anything + # found in it is `pnpm prisma generate`, and it is ~9 MB. + skip-dirs: src/generated + + - name: Upload results + uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6 + with: + sarif_file: trivy-filesystem.sarif + category: trivy-filesystem + + published-image: + name: Published image + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + packages: read + security-events: write + + steps: + # The `docker-security` job scans an image it just built from the + # current `main`. This one scans the image operators actually pull, + # which is the one built from the last release tag and unchanged + # since. The two answer different questions and the gap between them + # widens every day a release stays out. + # + # Trivy resolves the multi-arch manifest to the runner's platform, so + # this covers `linux/amd64`. The arm64 manifest shares every + # application layer and differs only in native binaries. + - name: Log in to GitHub Container Registry + uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + # `.trivyignore` lives at the repository root and Trivy reads it + # automatically, so the suppressions the blocking gate already + # carries apply here too and the two scans cannot disagree about + # what is accepted. + - name: Checkout for .trivyignore + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # Fails on CRITICAL only. A critical advisory against the image + # self-hosters are running right now is worth a red badge and a + # notification; HIGH goes to code scanning with everything else, + # because the release pipeline already refuses to publish an image + # carrying one and anything that appears here appeared after the + # fact. + - name: Trivy published-image scan + uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0 + with: + scan-type: image + image-ref: ghcr.io/mbombeck/healthlog:latest + scanners: vuln + format: sarif + output: trivy-published-image.sarif + severity: "CRITICAL,HIGH,MEDIUM" + limit-severities-for-sarif: true + exit-code: "0" + + - name: Upload results + uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6 + with: + sarif_file: trivy-published-image.sarif + category: trivy-published-image + + # Separate table pass so the SARIF upload above always runs, even + # when this one fails the job. A scan whose failure suppresses its + # own report is a scan you have to re-run by hand to read. + - name: Fail on a critical finding in the published image + uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0 + with: + scan-type: image + image-ref: ghcr.io/mbombeck/healthlog:latest + scanners: vuln + format: table + severity: "CRITICAL" + exit-code: "1" From b713ed8c3490d9fb02b29719af8b5457b4d091af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Fri, 7 Aug 2026 20:14:04 +0200 Subject: [PATCH 3/8] Score the supply chain against the OpenSSF criteria Most of what Scorecard looks for this repository already does: Actions pinned by commit SHA, a security policy with a private reporting path, Dependabot with auto-merge, keyless signing on the release image, a branch-protected trunk. The value is not the score, it is that the checks keep running after the person who set them up has moved on, and that anyone evaluating the project can read the result without being given CI access. publish_results is on, which is what makes the score citable. It reads repository metadata and the workflow files; nothing about the code or its contents goes anywhere. The token is an OIDC exchange, the same mechanism the release workflow already uses to sign the image. No badge in the README yet. The public API has no entry for this repository until the first run publishes one, and the badge URL currently renders 'invalid repo path'. It goes in once there is a score behind it. --- .github/workflows/scorecard.yml | 60 +++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 .github/workflows/scorecard.yml diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 000000000..0fb4bcd82 --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,60 @@ +name: OpenSSF Scorecard + +# Automated checks against the OpenSSF's supply-chain criteria: are Actions +# pinned by SHA, is there a security policy, are dependencies updated +# automatically, is the release pipeline signed, is there a fuzzing or a +# static-analysis story. Most of what it looks for this repository already +# does; the value is that it keeps looking after the person who set it up +# has moved on to something else. +# +# `publish_results: true` sends the result to the OpenSSF's public API, +# which is what makes the score citable by anyone evaluating the project +# without asking for CI access. Nothing about the code or its contents +# leaves; the checks read repository metadata and the workflow files. +on: + # Re-score when a branch-protection rule changes, since several checks + # read exactly that. + branch_protection_rule: + schedule: + # Tuesdays, 07:20 UTC. + - cron: "20 7 * * 2" + workflow_dispatch: + +permissions: read-all + +jobs: + analysis: + name: Score supply-chain practices + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + # Write the findings into the repository's code-scanning alerts. + security-events: write + # Publish the result to the public API. This is an OIDC token + # exchange, the same mechanism the release workflow uses for keyless + # image signing; no long-lived credential is involved. + id-token: write + contents: read + actions: read + + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # Scorecard reads the repository through the API, not through the + # checkout, and leaving the token in `.git/config` would hand it + # to anything else running in the job. + persist-credentials: false + + - name: Run analysis + uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4 + with: + results_file: scorecard-results.sarif + results_format: sarif + publish_results: true + + - name: Upload results + uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6 + with: + sarif_file: scorecard-results.sarif + category: scorecard From fd2bd67ff31e42f99dc99eb46c58be6c7d1126c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= Date: Fri, 7 Aug 2026 21:40:41 +0200 Subject: [PATCH 4/8] feat(labs): keep the reference range a report prints beside a value MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A lab runs its own method on its own device, so the window a physician evaluates a value against is the one printed next to it on that report, not a catalog band averaged over every lab. Reading a report pulled the value and dropped that range: the extraction asked for it, the commit handed it to the biomarker resolver, and the resolver only uses it when it mints a NEW marker. For every analyte the user already had — the normal case after a first panel — the printed range was read and then thrown away. Add `sourceReferenceLow` / `sourceReferenceHigh` / `sourceReferenceText` to `LabResult` and carry the range from the report to the reading. The text is stored whether or not numbers can be read out of it, because "bis 5,0" and "negativ" state a window too; a range that could not be parsed is kept verbatim, never replaced with invented bounds. `resolveEffectiveReferenceRange` is the one place the precedence lives: the source window wins for that single reading, and the catalog stays the net for readings without one. A printed string with no derivable bound does not displace the catalog. Every surface that judges a reading routes through it — the API verdict, the doctor report, the insights blocks and per-marker assessment, the coach snapshot, the MCP read and the FHIR `referenceRange` — so a value cannot read in range on one surface and out on another. The API keeps `referenceLow` / `referenceHigh` as the window in force, so a client that reads only those two renders the right range and the right verdict with no change of its own; the catalog band, the source window, its origin and a divergence flag ride alongside for clients that want to show both. Read side: the chart draws the source window as a second, visually distinct band with the reading it came from named beneath it, the reading rows name the printed range and the catalog band where the two disagree, and the doctor-report PDF prints the report's own string with a footnote naming the saved range. Entry side: one optional field on the lab form, folded away until asked for, and the printed range is editable on the scan review screen. The range parser covers the notations German and English reports actually print — two-sided, one-sided, comma or dot decimals, thousands separators, trailing units — reads units without ever converting them, and refuses to guess on anything ambiguous. --- docs/api/openapi.yaml | 181 ++++++++++- messages/de.json | 26 +- messages/en.json | 26 +- messages/es.json | 26 +- messages/fr.json | 26 +- messages/it.json | 26 +- messages/pl.json | 26 +- .../migration.sql | 14 + prisma/schema.prisma | 34 +- ...en-outcome-response-consumer-guard.test.ts | 7 + .../api/admin/backups/[id]/restore/route.ts | 3 + .../inbound/[id]/facts/[factId]/route.ts | 1 + src/app/api/insights/labs-changes/route.ts | 6 + src/app/api/labs/[id]/route.ts | 35 ++ src/app/api/labs/ocr/commit/route.ts | 15 +- src/app/api/labs/route.ts | 16 +- .../__tests__/lab-biomarker-detail.test.tsx | 7 + src/components/labs/lab-biomarker-chart.tsx | 129 +++++++- src/components/labs/lab-form.tsx | 73 +++++ src/components/labs/lab-history-list.tsx | 9 +- src/components/labs/lab-list.tsx | 5 + src/components/labs/ocr-review-dialog.tsx | 1 + src/components/labs/ocr-review-types.ts | 3 + src/components/labs/ocr-row-editor.tsx | 26 ++ src/components/labs/source-range-note.tsx | 69 ++++ src/components/labs/types.ts | 22 +- src/components/labs/use-ocr-extract.ts | 1 + src/lib/ai/coach/labs-snapshot.ts | 21 +- .../clinical-records-notes-section.ts | 59 +++- src/lib/doctor-report-types.ts | 15 + src/lib/doctor-report/clinical-records.ts | 22 +- src/lib/documents/commit.ts | 26 +- src/lib/documents/extract.ts | 14 +- src/lib/export/records-backup.ts | 7 + .../fhir/__tests__/lab-observations.test.ts | 25 ++ src/lib/fhir/resources/labs.ts | 17 +- src/lib/fhir/types.ts | 7 + .../insights/__tests__/labs-changes.test.ts | 12 +- src/lib/insights/biomarker-status.ts | 37 ++- .../insights/correlation-channel-series.ts | 3 + src/lib/insights/feature-blocks.ts | 17 +- src/lib/insights/labs-changes.ts | 25 +- .../effective-reference-range.test.ts | 128 ++++++++ .../__tests__/parse-reference-range.test.ts | 219 +++++++++++++ src/lib/labs/__tests__/serialise.test.ts | 3 + src/lib/labs/ocr-extract.ts | 21 +- src/lib/labs/parse-reference-range.ts | 207 ++++++++++++ src/lib/labs/reference-range.ts | 110 +++++++ src/lib/labs/serialise.ts | 196 ++++++++---- src/lib/mcp/rich-reads.ts | 17 +- src/lib/openapi/routes/labs.ts | 17 +- src/lib/openapi/routes/ocr.ts | 17 +- src/lib/validations/backup.ts | 5 + src/lib/validations/inbound-documents.ts | 18 ++ src/lib/validations/labs-ocr.ts | 20 ++ src/lib/validations/labs.ts | 60 ++++ .../lab-source-reference-range.test.ts | 298 ++++++++++++++++++ 57 files changed, 2281 insertions(+), 175 deletions(-) create mode 100644 prisma/migrations/0303_lab_source_reference_range/migration.sql create mode 100644 src/components/labs/source-range-note.tsx create mode 100644 src/lib/labs/__tests__/effective-reference-range.test.ts create mode 100644 src/lib/labs/__tests__/parse-reference-range.test.ts create mode 100644 src/lib/labs/parse-reference-range.ts create mode 100644 tests/integration/lab-source-reference-range.test.ts diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index eddfd2b8c..6ee4395b9 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -9147,6 +9147,16 @@ paths: type: number referenceHigh: type: number + sourceReferenceLow: + type: number + sourceReferenceHigh: + type: number + sourceReferenceText: + anyOf: + - type: string + maxLength: 120 + - type: string + const: "" takenAt: type: string format: date-time @@ -9254,6 +9264,22 @@ paths: anyOf: - type: number - type: "null" + sourceReferenceLow: + anyOf: + - type: number + - type: "null" + sourceReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceText: + anyOf: + - anyOf: + - type: string + maxLength: 120 + - type: string + const: "" + - type: "null" takenAt: type: string format: date-time @@ -9430,6 +9456,12 @@ paths: type: number referenceHigh: type: number + referenceText: + anyOf: + - type: string + maxLength: 120 + - type: string + const: "" takenAt: type: string format: date-time @@ -11616,6 +11648,11 @@ paths: anyOf: - type: number - type: "null" + referenceText: + anyOf: + - type: string + maxLength: 120 + - type: "null" effectiveDate: anyOf: - type: string @@ -32970,6 +33007,30 @@ components: anyOf: - type: number - type: "null" + catalogReferenceLow: + anyOf: + - type: number + - type: "null" + catalogReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceLow: + anyOf: + - type: number + - type: "null" + sourceReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceText: + anyOf: + - type: string + - type: "null" + referenceOrigin: + $ref: "#/components/schemas/LabReferenceRangeOrigin" + referenceDivergesFromCatalog: + type: boolean takenAt: type: string source: @@ -32992,6 +33053,13 @@ components: - unit - referenceLow - referenceHigh + - catalogReferenceLow + - catalogReferenceHigh + - sourceReferenceLow + - sourceReferenceHigh + - sourceReferenceText + - referenceOrigin + - referenceDivergesFromCatalog - takenAt - source - hasNote @@ -32999,12 +33067,31 @@ components: - createdAt - updatedAt additionalProperties: false - description: A stored lab result. Exactly one of `value` (numeric) or `valueText` (qualitative, e.g. "negativ") is - non-null; `rangeStatus` is always `unknown` for a qualitative row (no number to classify). `biomarkerId` links - the user-scoped catalog marker (null for legacy free-text rows); when linked, `analyte` / `unit` / - `referenceLow` / `referenceHigh` are RESOLVED server-side from the Biomarker — the client renders them and never - recomputes the range. The encrypted note is never echoed in list rows; `hasNote` flags its presence and the - single-resource GET returns the decrypted `note`. + description: >- + A stored lab result. Exactly one of `value` (numeric) or `valueText` (qualitative, e.g. "negativ") is non-null; + `rangeStatus` is always `unknown` for a qualitative row (no number to classify). `biomarkerId` links the + user-scoped catalog marker (null for legacy free-text rows); when linked, `analyte` / `unit` are RESOLVED + server-side from the Biomarker. + + + Three reference windows ride on the row and the server says which one applies. `referenceLow` / `referenceHigh` + are the window IN FORCE and the one `rangeStatus` was computed from — read these to render the range and you are + correct without doing any resolution of your own. `sourceReferenceLow` / `sourceReferenceHigh` / + `sourceReferenceText` are the range this reading's own report printed (the text verbatim, kept even when no + numbers could be read out of it). `catalogReferenceLow` / `catalogReferenceHigh` are the Biomarker band. + `referenceOrigin` names the winner and `referenceDivergesFromCatalog` is true when the report's window and the + catalog band state different limits — a surface showing only one of the two is showing a partial answer. The + client renders these values and never recomputes the range. The encrypted note is never echoed in list rows; + `hasNote` flags its presence and the single-resource GET returns the decrypted `note`. + LabReferenceRangeOrigin: + type: string + enum: + - source + - catalog + - none + description: Which window `referenceLow` / `referenceHigh` came from. `source` = the range printed on this reading's own + report, which wins for that reading because it is the window the physician evaluated the value against. + `catalog` = the user's Biomarker band, the net for readings with no printed range. `none` = no window on file. LabReferenceRangeStatus: type: string enum: @@ -33012,9 +33099,9 @@ components: - below - above - unknown - description: "Server-computed, NEUTRAL reference-range verdict. `unknown` when the lab reported no usable bounds. - Inclusive bounds: a value on the limit reads in-range. The badge that renders this must stay calm and - informative — not an alarming red." + description: "Server-computed, NEUTRAL reference-range verdict, always against `referenceLow` / `referenceHigh` (the + window in force for that reading). `unknown` when no usable bounds are on file. Inclusive bounds: a value on the + limit reads in-range. The badge that renders this must stay calm and informative — not an alarming red." CreateLabResultResponse: type: object properties: @@ -33082,6 +33169,30 @@ components: anyOf: - type: number - type: "null" + catalogReferenceLow: + anyOf: + - type: number + - type: "null" + catalogReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceLow: + anyOf: + - type: number + - type: "null" + sourceReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceText: + anyOf: + - type: string + - type: "null" + referenceOrigin: + $ref: "#/components/schemas/LabReferenceRangeOrigin" + referenceDivergesFromCatalog: + type: boolean takenAt: type: string source: @@ -33106,6 +33217,13 @@ components: - unit - referenceLow - referenceHigh + - catalogReferenceLow + - catalogReferenceHigh + - sourceReferenceLow + - sourceReferenceHigh + - sourceReferenceText + - referenceOrigin + - referenceDivergesFromCatalog - takenAt - source - rangeStatus @@ -33288,6 +33406,14 @@ components: anyOf: - type: number - type: "null" + referenceText: + anyOf: + - type: string + - type: "null" + description: The reference range EXACTLY as printed on the report, verbatim ("3,5 - 5,0", "< 116", "bis 5,0", + "negativ"). `referenceLow` / `referenceHigh` carry the same window reduced to numbers WHEN it reduces to + numbers; this field carries it either way, so a window stated in words is not lost between the report and + the reading. takenAt: anyOf: - type: string @@ -33325,6 +33451,7 @@ components: - unit - referenceLow - referenceHigh + - referenceText - takenAt - confidence - biomarkerMatch @@ -33422,6 +33549,34 @@ components: anyOf: - type: number - type: "null" + catalogReferenceLow: + anyOf: + - type: number + - type: "null" + catalogReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceLow: + anyOf: + - type: number + - type: "null" + sourceReferenceHigh: + anyOf: + - type: number + - type: "null" + sourceReferenceText: + anyOf: + - type: string + - type: "null" + referenceOrigin: + type: string + enum: + - source + - catalog + - none + referenceDivergesFromCatalog: + type: boolean takenAt: type: string source: @@ -33449,6 +33604,13 @@ components: - unit - referenceLow - referenceHigh + - catalogReferenceLow + - catalogReferenceHigh + - sourceReferenceLow + - sourceReferenceHigh + - sourceReferenceText + - referenceOrigin + - referenceDivergesFromCatalog - takenAt - source - hasNote @@ -33456,6 +33618,7 @@ components: - createdAt - updatedAt additionalProperties: false + description: A written reading. Its reference window resolves exactly as it does on `/api/labs` — see `LabResult`. ListBiomarkersEnvelope: type: object properties: diff --git a/messages/de.json b/messages/de.json index bd178a38a..dfdfd8e3e 100644 --- a/messages/de.json +++ b/messages/de.json @@ -281,7 +281,9 @@ "familyHistoryTitle": "Familienanamnese", "familyHistoryColRelationship": "Verwandtschaft", "familyHistoryColCondition": "Erkrankung", - "familyHistoryColAgeAtOnset": "Alter bei Beginn" + "familyHistoryColAgeAtOnset": "Alter bei Beginn", + "labsSourceRangeNote": "* Der Referenzbereich stammt aus dem Befund und weicht vom gespeicherten Bereich ab:", + "labsCatalogRangeLabel": "gespeicherter Bereich" }, "errorBoundary": { "title": "Da ist etwas schiefgelaufen", @@ -8037,7 +8039,12 @@ "qualitativePlaceholder": "z. B. negativ", "qualNegative": "negativ", "qualPositive": "positiv", - "qualBorderline": "grenzwertig" + "qualBorderline": "grenzwertig", + "sourceRange": "Bereich laut Befund", + "sourceRangePlaceholder": "z. B. 3,5 - 5,0 oder < 5", + "sourceRangeAdd": "+ Bereich aus dem Befund ergänzen", + "sourceRangeHint": "Optional. Gilt nur für diesen Wert; dein gespeicherter Bereich bleibt unverändert.", + "sourceRangeUnparsed": "Wird so übernommen — daraus ließ sich kein Zahlenbereich lesen." }, "backToLabs": "Zurück zu den Laborwerten", "hasNote": "Notiz", @@ -8068,7 +8075,10 @@ "90": "90 T", "365": "1 J", "all": "Alle" - } + }, + "sourceRangeLabel": "Befundbereich", + "sourceBandLegend": "Zweites Band: der Bereich aus dem Befund vom {date}.", + "sourceBandMixed": "Zweites Band: der Bereich aus dem neuesten Befund. Frühere Befunde im Zeitraum nennen andere Bereiche." }, "biomarker": { "manageTitle": "Biomarker", @@ -8243,11 +8253,17 @@ "fileTooLarge": "Datei ist zu groß (max. 12 MB).", "fileType": "Lade ein JPEG, PNG, WebP oder PDF hoch.", "extractFailed": "Der Befund konnte nicht gelesen werden. Versuche ein schärferes Foto.", - "pdfNeedsAnthropic": "PDF-Scannen benötigt einen Claude-Bildanbieter; lade stattdessen ein Foto hoch." + "pdfNeedsAnthropic": "PDF-Scannen benötigt einen Claude-Bildanbieter; lade stattdessen ein Foto hoch.", + "refTextLabel": "Bereich wie gedruckt", + "refTextPlaceholder": "z. B. 3,5 - 5,0" }, "loadMoreReadings": "Weitere Werte laden", "documentsLink": "Befund-Dokumente", - "notLinkedYet": "Noch keinem Biomarker zugeordnet" + "notLinkedYet": "Noch keinem Biomarker zugeordnet", + "sourceRange": { + "fromReport": "Befundbereich {range}", + "catalogDiffers": "dein Bereich {range}" + } }, "modules": { "cycle": { diff --git a/messages/en.json b/messages/en.json index 62a606b7c..5b7f7c10d 100644 --- a/messages/en.json +++ b/messages/en.json @@ -281,7 +281,9 @@ "familyHistoryTitle": "Family history", "familyHistoryColRelationship": "Relative", "familyHistoryColCondition": "Condition", - "familyHistoryColAgeAtOnset": "Age at onset" + "familyHistoryColAgeAtOnset": "Age at onset", + "labsSourceRangeNote": "* The reference range comes from the report itself and differs from the saved range:", + "labsCatalogRangeLabel": "saved range" }, "errorBoundary": { "title": "Something went wrong", @@ -8037,7 +8039,12 @@ "qualitativePlaceholder": "e.g. negative", "qualNegative": "negative", "qualPositive": "positive", - "qualBorderline": "borderline" + "qualBorderline": "borderline", + "sourceRange": "Range printed on the report", + "sourceRangePlaceholder": "e.g. 3.5 - 5.0 or < 5", + "sourceRangeAdd": "+ Add the range from the report", + "sourceRangeHint": "Optional. Applies to this reading only; your saved range stays as it is.", + "sourceRangeUnparsed": "Kept as written — no numeric range read from it." }, "backToLabs": "Back to lab results", "hasNote": "Note", @@ -8068,7 +8075,10 @@ "90": "90d", "365": "1y", "all": "All" - } + }, + "sourceRangeLabel": "Report range", + "sourceBandLegend": "Second band: the range printed on the report of {date}.", + "sourceBandMixed": "Second band: the range printed on the most recent report. Earlier reports in view state different ranges." }, "biomarker": { "manageTitle": "Biomarkers", @@ -8243,11 +8253,17 @@ "fileTooLarge": "File is too large (max 12 MB).", "fileType": "Upload a JPEG, PNG, WebP, or PDF.", "extractFailed": "Couldn't read the report. Try a clearer photo.", - "pdfNeedsAnthropic": "PDF scanning needs a Claude vision provider; upload a photo instead." + "pdfNeedsAnthropic": "PDF scanning needs a Claude vision provider; upload a photo instead.", + "refTextLabel": "Range as printed", + "refTextPlaceholder": "e.g. 3.5 - 5.0" }, "loadMoreReadings": "Load more readings", "documentsLink": "Lab report documents", - "notLinkedYet": "Not linked to a biomarker yet" + "notLinkedYet": "Not linked to a biomarker yet", + "sourceRange": { + "fromReport": "Report range {range}", + "catalogDiffers": "your range {range}" + } }, "modules": { "cycle": { diff --git a/messages/es.json b/messages/es.json index 95921a55c..ba654e6b7 100644 --- a/messages/es.json +++ b/messages/es.json @@ -281,7 +281,9 @@ "familyHistoryTitle": "Antecedentes familiares", "familyHistoryColRelationship": "Parentesco", "familyHistoryColCondition": "Afección", - "familyHistoryColAgeAtOnset": "Edad de inicio" + "familyHistoryColAgeAtOnset": "Edad de inicio", + "labsSourceRangeNote": "* El rango de referencia procede del propio informe y difiere del rango guardado:", + "labsCatalogRangeLabel": "rango guardado" }, "errorBoundary": { "title": "Algo ha salido mal", @@ -8037,7 +8039,12 @@ "qualitativePlaceholder": "p. ej. negativo", "qualNegative": "negativo", "qualPositive": "positivo", - "qualBorderline": "límite" + "qualBorderline": "límite", + "sourceRange": "Rango impreso en el informe", + "sourceRangePlaceholder": "p. ej. 3,5 - 5,0 o < 5", + "sourceRangeAdd": "+ Añadir el rango del informe", + "sourceRangeHint": "Opcional. Se aplica solo a esta lectura; tu rango guardado no cambia.", + "sourceRangeUnparsed": "Se guarda tal cual: no se pudo leer un rango numérico." }, "backToLabs": "Volver a los resultados", "hasNote": "Nota", @@ -8068,7 +8075,10 @@ "90": "90 d", "365": "1 a", "all": "Todo" - } + }, + "sourceRangeLabel": "Rango del informe", + "sourceBandLegend": "Segunda banda: el rango impreso en el informe del {date}.", + "sourceBandMixed": "Segunda banda: el rango impreso en el informe más reciente. Informes anteriores del periodo indican rangos distintos." }, "biomarker": { "manageTitle": "Biomarcadores", @@ -8243,11 +8253,17 @@ "fileTooLarge": "El archivo es demasiado grande (máx. 12 MB).", "fileType": "Sube un JPEG, PNG, WebP o PDF.", "extractFailed": "No se pudo leer el informe. Prueba con una foto más nítida.", - "pdfNeedsAnthropic": "El escaneo de PDF necesita un proveedor de visión de Claude; sube una foto en su lugar." + "pdfNeedsAnthropic": "El escaneo de PDF necesita un proveedor de visión de Claude; sube una foto en su lugar.", + "refTextLabel": "Rango tal como aparece", + "refTextPlaceholder": "p. ej. 3,5 - 5,0" }, "loadMoreReadings": "Cargar más mediciones", "documentsLink": "Documentos de resultados", - "notLinkedYet": "Aún no vinculado a un biomarcador" + "notLinkedYet": "Aún no vinculado a un biomarcador", + "sourceRange": { + "fromReport": "Rango del informe {range}", + "catalogDiffers": "tu rango {range}" + } }, "modules": { "cycle": { diff --git a/messages/fr.json b/messages/fr.json index 60ceddd0d..88e3e18fa 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -281,7 +281,9 @@ "familyHistoryTitle": "Antécédents familiaux", "familyHistoryColRelationship": "Lien de parenté", "familyHistoryColCondition": "Affection", - "familyHistoryColAgeAtOnset": "Âge au début" + "familyHistoryColAgeAtOnset": "Âge au début", + "labsSourceRangeNote": "* La plage de référence provient du compte rendu lui-même et diffère de la plage enregistrée :", + "labsCatalogRangeLabel": "plage enregistrée" }, "errorBoundary": { "title": "Une erreur est survenue", @@ -8037,7 +8039,12 @@ "qualitativePlaceholder": "p. ex. négatif", "qualNegative": "négatif", "qualPositive": "positif", - "qualBorderline": "limite" + "qualBorderline": "limite", + "sourceRange": "Plage imprimée sur le compte rendu", + "sourceRangePlaceholder": "p. ex. 3,5 - 5,0 ou < 5", + "sourceRangeAdd": "+ Ajouter la plage du compte rendu", + "sourceRangeHint": "Facultatif. Ne vaut que pour cette mesure ; votre plage enregistrée reste inchangée.", + "sourceRangeUnparsed": "Conservé tel quel : aucune plage numérique n'a pu en être lue." }, "backToLabs": "Retour aux résultats", "hasNote": "Note", @@ -8068,7 +8075,10 @@ "90": "90 j", "365": "1 a", "all": "Tout" - } + }, + "sourceRangeLabel": "Plage du compte rendu", + "sourceBandLegend": "Deuxième bande : la plage imprimée sur le compte rendu du {date}.", + "sourceBandMixed": "Deuxième bande : la plage imprimée sur le compte rendu le plus récent. Des comptes rendus antérieurs de la période indiquent d'autres plages." }, "biomarker": { "manageTitle": "Biomarqueurs", @@ -8243,11 +8253,17 @@ "fileTooLarge": "Le fichier est trop volumineux (max. 12 Mo).", "fileType": "Importez un JPEG, PNG, WebP ou PDF.", "extractFailed": "Impossible de lire le compte rendu. Essayez une photo plus nette.", - "pdfNeedsAnthropic": "Le scan PDF nécessite un fournisseur de vision Claude ; importez plutôt une photo." + "pdfNeedsAnthropic": "Le scan PDF nécessite un fournisseur de vision Claude ; importez plutôt une photo.", + "refTextLabel": "Plage telle qu'imprimée", + "refTextPlaceholder": "p. ex. 3,5 - 5,0" }, "loadMoreReadings": "Charger plus de mesures", "documentsLink": "Documents de résultats", - "notLinkedYet": "Pas encore lié à un biomarqueur" + "notLinkedYet": "Pas encore lié à un biomarqueur", + "sourceRange": { + "fromReport": "Plage du compte rendu {range}", + "catalogDiffers": "votre plage {range}" + } }, "modules": { "cycle": { diff --git a/messages/it.json b/messages/it.json index fac161835..a29739d32 100644 --- a/messages/it.json +++ b/messages/it.json @@ -281,7 +281,9 @@ "familyHistoryTitle": "Anamnesi familiare", "familyHistoryColRelationship": "Parentela", "familyHistoryColCondition": "Condizione", - "familyHistoryColAgeAtOnset": "Età di esordio" + "familyHistoryColAgeAtOnset": "Età di esordio", + "labsSourceRangeNote": "* L'intervallo di riferimento proviene dal referto stesso e differisce da quello salvato:", + "labsCatalogRangeLabel": "intervallo salvato" }, "errorBoundary": { "title": "Qualcosa è andato storto", @@ -8037,7 +8039,12 @@ "qualitativePlaceholder": "es. negativo", "qualNegative": "negativo", "qualPositive": "positivo", - "qualBorderline": "borderline" + "qualBorderline": "borderline", + "sourceRange": "Intervallo stampato sul referto", + "sourceRangePlaceholder": "es. 3,5 - 5,0 oppure < 5", + "sourceRangeAdd": "+ Aggiungi l'intervallo dal referto", + "sourceRangeHint": "Facoltativo. Vale solo per questa misura; l'intervallo salvato resta invariato.", + "sourceRangeUnparsed": "Conservato così com'è: non è stato letto alcun intervallo numerico." }, "backToLabs": "Torna ai risultati", "hasNote": "Nota", @@ -8068,7 +8075,10 @@ "90": "90 g", "365": "1 a", "all": "Tutto" - } + }, + "sourceRangeLabel": "Intervallo del referto", + "sourceBandLegend": "Seconda banda: l'intervallo stampato sul referto del {date}.", + "sourceBandMixed": "Seconda banda: l'intervallo stampato sul referto più recente. Referti precedenti nel periodo indicano intervalli diversi." }, "biomarker": { "manageTitle": "Biomarcatori", @@ -8243,11 +8253,17 @@ "fileTooLarge": "Il file è troppo grande (max 12 MB).", "fileType": "Carica un JPEG, PNG, WebP o PDF.", "extractFailed": "Impossibile leggere il referto. Prova con una foto più nitida.", - "pdfNeedsAnthropic": "La scansione PDF richiede un provider di visione Claude; carica invece una foto." + "pdfNeedsAnthropic": "La scansione PDF richiede un provider di visione Claude; carica invece una foto.", + "refTextLabel": "Intervallo come stampato", + "refTextPlaceholder": "es. 3,5 - 5,0" }, "loadMoreReadings": "Carica altre misurazioni", "documentsLink": "Documenti dei referti", - "notLinkedYet": "Non ancora collegato a un biomarcatore" + "notLinkedYet": "Non ancora collegato a un biomarcatore", + "sourceRange": { + "fromReport": "Intervallo del referto {range}", + "catalogDiffers": "il tuo intervallo {range}" + } }, "modules": { "cycle": { diff --git a/messages/pl.json b/messages/pl.json index 8e8b9e4bd..a56973762 100644 --- a/messages/pl.json +++ b/messages/pl.json @@ -281,7 +281,9 @@ "familyHistoryTitle": "Wywiad rodzinny", "familyHistoryColRelationship": "Pokrewieństwo", "familyHistoryColCondition": "Schorzenie", - "familyHistoryColAgeAtOnset": "Wiek zachorowania" + "familyHistoryColAgeAtOnset": "Wiek zachorowania", + "labsSourceRangeNote": "* Zakres referencyjny pochodzi z samego wyniku i różni się od zapisanego zakresu:", + "labsCatalogRangeLabel": "zapisany zakres" }, "errorBoundary": { "title": "Coś poszło nie tak", @@ -8037,7 +8039,12 @@ "qualitativePlaceholder": "np. ujemny", "qualNegative": "ujemny", "qualPositive": "dodatni", - "qualBorderline": "graniczny" + "qualBorderline": "graniczny", + "sourceRange": "Zakres wydrukowany na wyniku", + "sourceRangePlaceholder": "np. 3,5 - 5,0 lub < 5", + "sourceRangeAdd": "+ Dodaj zakres z wyniku", + "sourceRangeHint": "Opcjonalne. Dotyczy tylko tego pomiaru; zapisany zakres pozostaje bez zmian.", + "sourceRangeUnparsed": "Zapisane bez zmian — nie odczytano z tego zakresu liczbowego." }, "backToLabs": "Wróć do wyników", "hasNote": "Notatka", @@ -8068,7 +8075,10 @@ "90": "90 d", "365": "1 r", "all": "Wszystko" - } + }, + "sourceRangeLabel": "Zakres z wyniku", + "sourceBandLegend": "Drugie pasmo: zakres wydrukowany na wyniku z {date}.", + "sourceBandMixed": "Drugie pasmo: zakres z najnowszego wyniku. Wcześniejsze wyniki w tym okresie podają inne zakresy." }, "biomarker": { "manageTitle": "Biomarkery", @@ -8243,11 +8253,17 @@ "fileTooLarge": "Plik jest za duży (maks. 12 MB).", "fileType": "Prześlij plik JPEG, PNG, WebP lub PDF.", "extractFailed": "Nie udało się odczytać wyniku. Spróbuj wyraźniejszego zdjęcia.", - "pdfNeedsAnthropic": "Skanowanie PDF wymaga dostawcy wizji Claude; prześlij zamiast tego zdjęcie." + "pdfNeedsAnthropic": "Skanowanie PDF wymaga dostawcy wizji Claude; prześlij zamiast tego zdjęcie.", + "refTextLabel": "Zakres tak jak wydrukowano", + "refTextPlaceholder": "np. 3,5 - 5,0" }, "loadMoreReadings": "Wczytaj więcej pomiarów", "documentsLink": "Dokumenty wyników badań", - "notLinkedYet": "Jeszcze niepowiązane z biomarkerem" + "notLinkedYet": "Jeszcze niepowiązane z biomarkerem", + "sourceRange": { + "fromReport": "Zakres z wyniku {range}", + "catalogDiffers": "twój zakres {range}" + } }, "modules": { "cycle": { diff --git a/prisma/migrations/0303_lab_source_reference_range/migration.sql b/prisma/migrations/0303_lab_source_reference_range/migration.sql new file mode 100644 index 000000000..d4f6644c1 --- /dev/null +++ b/prisma/migrations/0303_lab_source_reference_range/migration.sql @@ -0,0 +1,14 @@ +-- Per-reading source reference range on a lab result. +-- +-- A lab report prints the window its own method and device produce, right +-- beside the value, and that window is what a physician evaluates against. +-- Until now the document reading pulled the value and dropped the range. +-- These three columns carry it: the derived numeric bounds where the printed +-- string yields them, plus the report's verbatim string, which is stored +-- whether or not it parsed. Nothing is backfilled — an existing row genuinely +-- has no source range on file and stays NULL. + +ALTER TABLE "lab_results" + ADD COLUMN "source_reference_low" DOUBLE PRECISION, + ADD COLUMN "source_reference_high" DOUBLE PRECISION, + ADD COLUMN "source_reference_text" TEXT; diff --git a/prisma/schema.prisma b/prisma/schema.prisma index fa1aeaa28..7adb641be 100644 --- a/prisma/schema.prisma +++ b/prisma/schema.prisma @@ -5005,9 +5005,41 @@ model LabResult { /// reference bounds + range verdict are meaningless for a qualitative row. valueText String? @map("value_text") unit String - /// Optional reference-range bounds as reported by the lab. + /// Reference-range bounds stamped onto the row at write time. Despite the + /// name these are NOT the lab's printed range: since v1.18.1 every write + /// path copies the linked `Biomarker`'s `lowerBound` / `upperBound` here as + /// historical truth, so a later catalog edit does not silently rewrite a + /// past reading. The range the LAB printed lives in `sourceReference*`. referenceLow Float? @map("reference_low") referenceHigh Float? @map("reference_high") + + /// The reference range as PRINTED ON THE SOURCE REPORT for this one reading. + /// + /// Labs run different methods on different devices, so the window a + /// physician evaluates against is the one printed beside the value on that + /// report — not a catalog band that averages every lab. These three columns + /// carry it: the parsed numeric bounds where a bound could be derived, and + /// `sourceReferenceText` as the report's own verbatim string ("< 5", + /// "bis 5,0", "negativ", "siehe Befund"). The text is kept whenever the + /// source printed one, parseable or not — absence reads as absence, and a + /// window that could not be derived is never invented. + /// + /// Precedence: for a single reading the source bounds win over the catalog + /// band; the catalog stays the net for readings that carry no source range. + /// `resolveEffectiveReferenceRange` in `src/lib/labs/reference-range.ts` is + /// the one place that rule is expressed, and every surface that judges a + /// reading routes through it. + /// + /// Plaintext, not `*Encrypted`: that suffix marks user prose (`noteEncrypted` + /// here, `Biomarker.contextEncrypted` next door). This is a structured + /// lab-report field of exactly the class of the plaintext `analyte` / `unit` + /// / `value` / `valueText` columns beside it — `valueText` already carries + /// the actual clinical RESULT ("positiv") in the clear, so encrypting the + /// window that result is judged against would protect strictly less while + /// making the column unreadable to the SQL the read paths run. + sourceReferenceLow Float? @map("source_reference_low") + sourceReferenceHigh Float? @map("source_reference_high") + sourceReferenceText String? @map("source_reference_text") /// When the sample was taken (UTC instant; wall-clock anchoring is the /// reader's concern per the schema's UTC-only convention). takenAt DateTime @map("taken_at") diff --git a/src/__tests__/written-outcome-response-consumer-guard.test.ts b/src/__tests__/written-outcome-response-consumer-guard.test.ts index 904107571..335b152f5 100644 --- a/src/__tests__/written-outcome-response-consumer-guard.test.ts +++ b/src/__tests__/written-outcome-response-consumer-guard.test.ts @@ -724,6 +724,13 @@ const OCR_EXCEPTIONS: Readonly> = { "inserted.unit": OCR_ROW_EXCEPTION, "inserted.referenceLow": OCR_ROW_EXCEPTION, "inserted.referenceHigh": OCR_ROW_EXCEPTION, + "inserted.catalogReferenceLow": OCR_ROW_EXCEPTION, + "inserted.catalogReferenceHigh": OCR_ROW_EXCEPTION, + "inserted.sourceReferenceLow": OCR_ROW_EXCEPTION, + "inserted.sourceReferenceHigh": OCR_ROW_EXCEPTION, + "inserted.sourceReferenceText": OCR_ROW_EXCEPTION, + "inserted.referenceOrigin": OCR_ROW_EXCEPTION, + "inserted.referenceDivergesFromCatalog": OCR_ROW_EXCEPTION, "inserted.takenAt": OCR_ROW_EXCEPTION, "inserted.source": OCR_ROW_EXCEPTION, "inserted.hasNote": OCR_ROW_EXCEPTION, diff --git a/src/app/api/admin/backups/[id]/restore/route.ts b/src/app/api/admin/backups/[id]/restore/route.ts index 3c22417f3..d57c7fc0f 100644 --- a/src/app/api/admin/backups/[id]/restore/route.ts +++ b/src/app/api/admin/backups/[id]/restore/route.ts @@ -894,6 +894,9 @@ const handler = apiHandler( unit: lab.unit, referenceLow: lab.referenceLow ?? null, referenceHigh: lab.referenceHigh ?? null, + sourceReferenceLow: lab.sourceReferenceLow ?? null, + sourceReferenceHigh: lab.sourceReferenceHigh ?? null, + sourceReferenceText: lab.sourceReferenceText ?? null, takenAt: new Date(lab.takenAt), source: lab.source, noteEncrypted: diff --git a/src/app/api/documents/inbound/[id]/facts/[factId]/route.ts b/src/app/api/documents/inbound/[id]/facts/[factId]/route.ts index 042b1387e..498a7ce25 100644 --- a/src/app/api/documents/inbound/[id]/facts/[factId]/route.ts +++ b/src/app/api/documents/inbound/[id]/facts/[factId]/route.ts @@ -57,6 +57,7 @@ function editToFactData(edit: InboundFactEdit): FactData { unit: edit.unit ?? null, referenceLow: edit.referenceLow ?? null, referenceHigh: edit.referenceHigh ?? null, + referenceText: edit.referenceText ?? null, effectiveDate: edit.effectiveDate ?? null, }; return data; diff --git a/src/app/api/insights/labs-changes/route.ts b/src/app/api/insights/labs-changes/route.ts index 452af57da..ddfde9972 100644 --- a/src/app/api/insights/labs-changes/route.ts +++ b/src/app/api/insights/labs-changes/route.ts @@ -46,6 +46,9 @@ export const GET = apiHandler(async () => { value: true, referenceLow: true, referenceHigh: true, + sourceReferenceLow: true, + sourceReferenceHigh: true, + sourceReferenceText: true, takenAt: true, }, orderBy: { takenAt: "desc" }, @@ -58,6 +61,9 @@ export const GET = apiHandler(async () => { value: r.value as number, referenceLow: r.referenceLow, referenceHigh: r.referenceHigh, + sourceReferenceLow: r.sourceReferenceLow, + sourceReferenceHigh: r.sourceReferenceHigh, + sourceReferenceText: r.sourceReferenceText, takenAt: r.takenAt, })), ); diff --git a/src/app/api/labs/[id]/route.ts b/src/app/api/labs/[id]/route.ts index d143259fb..34afa72a7 100644 --- a/src/app/api/labs/[id]/route.ts +++ b/src/app/api/labs/[id]/route.ts @@ -143,6 +143,12 @@ export const PUT = apiHandler( // historical columns the serialiser ignores. Reject the attempt with a // 422 rather than silently no-op, so the client never believes an edit // landed. Edit such fields on the Biomarker itself instead. + // + // `sourceReference*` is deliberately NOT on that list. The catalog band is + // a property of the marker; the source window is a property of THIS + // reading — it is what one report printed beside one value — so it is + // editable on a linked row and there is nothing on the biomarker to edit + // it on instead. const isLinked = existing.biomarkerId !== null; if ( isLinked && @@ -194,6 +200,15 @@ export const PUT = apiHandler( if (d.unit !== undefined) data.unit = d.unit; if (d.referenceLow !== undefined) data.referenceLow = d.referenceLow; if (d.referenceHigh !== undefined) data.referenceHigh = d.referenceHigh; + if (d.sourceReferenceLow !== undefined) { + data.sourceReferenceLow = d.sourceReferenceLow; + } + if (d.sourceReferenceHigh !== undefined) { + data.sourceReferenceHigh = d.sourceReferenceHigh; + } + if (d.sourceReferenceText !== undefined) { + data.sourceReferenceText = d.sourceReferenceText; + } if (d.takenAt !== undefined) data.takenAt = d.takenAt; // Inverted-range guard for a PARTIAL bound update. The schema-level @@ -212,6 +227,20 @@ export const PUT = apiHandler( errorCode: "labs.update.referenceRangeInvalid", }); } + // The same partial-update hole exists on the source window, and closes the + // same way. + if ( + isInvertedRange( + effectiveBound(d.sourceReferenceLow, existing.sourceReferenceLow), + effectiveBound(d.sourceReferenceHigh, existing.sourceReferenceHigh), + ) + ) { + return apiError( + "sourceReferenceLow must not exceed sourceReferenceHigh", + 422, + { errorCode: "labs.update.sourceReferenceRangeInvalid" }, + ); + } if (d.note !== undefined) { data.noteEncrypted = d.note ? encryptNoteToBytes(d.note) : null; } @@ -239,6 +268,9 @@ export const PUT = apiHandler( panel: existing.panel, referenceLow: existing.referenceLow, referenceHigh: existing.referenceHigh, + sourceReferenceLow: existing.sourceReferenceLow, + sourceReferenceHigh: existing.sourceReferenceHigh, + sourceReferenceText: existing.sourceReferenceText, takenAt: existing.takenAt, }, after: { @@ -249,6 +281,9 @@ export const PUT = apiHandler( panel: updated.panel, referenceLow: updated.referenceLow, referenceHigh: updated.referenceHigh, + sourceReferenceLow: updated.sourceReferenceLow, + sourceReferenceHigh: updated.sourceReferenceHigh, + sourceReferenceText: updated.sourceReferenceText, takenAt: updated.takenAt, }, redacted: d.note !== undefined ? ["note"] : [], diff --git a/src/app/api/labs/ocr/commit/route.ts b/src/app/api/labs/ocr/commit/route.ts index d6bd0b431..b8700562e 100644 --- a/src/app/api/labs/ocr/commit/route.ts +++ b/src/app/api/labs/ocr/commit/route.ts @@ -33,6 +33,7 @@ import { withIdempotency } from "@/lib/idempotency"; import { enqueueReminderSatisfy } from "@/lib/jobs/reminder-satisfy"; import { emitDataArrival } from "@/lib/arrivals/emit-shared"; import { resolveOrMintBiomarker } from "@/lib/labs/biomarker-store"; +import { parseReferenceRange } from "@/lib/labs/parse-reference-range"; import { serialiseLabResult } from "@/lib/labs/serialise"; import { linkOcrLabsToVaultDocument, @@ -151,12 +152,19 @@ async function commitOcrRows(request: NextRequest) { } const isQualitative = row.valueText !== undefined; + // The window the scan read off the report. The confirmed numeric bounds + // win over a re-parse of the string (the human may have corrected them on + // the review screen); the string rides along either way. + const printed = parseReferenceRange(row.referenceText, row.unit); + const sourceLow = row.referenceLow ?? printed?.low ?? null; + const sourceHigh = row.referenceHigh ?? printed?.high ?? null; + const sourceText = printed?.text ?? null; const biomarker = await resolveOrMintBiomarker(user.id, { analyte: row.analyte, // A qualitative reading has no numeric unit / range. unit: isQualitative ? (row.unit ?? "") : (row.unit as string), - referenceLow: isQualitative ? null : (row.referenceLow ?? null), - referenceHigh: isQualitative ? null : (row.referenceHigh ?? null), + referenceLow: isQualitative ? null : sourceLow, + referenceHigh: isQualitative ? null : sourceHigh, panel: row.panel ?? null, }); @@ -173,6 +181,9 @@ async function commitOcrRows(request: NextRequest) { unit: biomarker.unit, referenceLow: biomarker.lowerBound, referenceHigh: biomarker.upperBound, + sourceReferenceLow: isQualitative ? null : sourceLow, + sourceReferenceHigh: isQualitative ? null : sourceHigh, + sourceReferenceText: isQualitative ? null : sourceText, takenAt: row.takenAt, source: "OCR", noteEncrypted: null, diff --git a/src/app/api/labs/route.ts b/src/app/api/labs/route.ts index 1ab53c06c..60e325499 100644 --- a/src/app/api/labs/route.ts +++ b/src/app/api/labs/route.ts @@ -184,6 +184,9 @@ async function postLabResult(request: NextRequest) { unit, referenceLow, referenceHigh, + sourceReferenceLow, + sourceReferenceHigh, + sourceReferenceText, takenAt, note, source, @@ -248,6 +251,13 @@ async function postLabResult(request: NextRequest) { unit: biomarker.unit, referenceLow: biomarker.lowerBound, referenceHigh: biomarker.upperBound, + // The window this reading's own report printed, kept beside the catalog + // stamp rather than folded into it: it governs THIS reading's verdict, + // and the catalog band stays the net for every reading without one. A + // qualitative reading has no window to record. + sourceReferenceLow: isQualitative ? null : (sourceReferenceLow ?? null), + sourceReferenceHigh: isQualitative ? null : (sourceReferenceHigh ?? null), + sourceReferenceText: isQualitative ? null : (sourceReferenceText ?? null), takenAt, // v1.25 (iOS #36) — provenance: the on-device-OCR path posts // `source: "OCR"`; an omitted field stays "MANUAL" so the legacy @@ -258,6 +268,7 @@ async function postLabResult(request: NextRequest) { }, }); invalidateUserHealthScore(user.id); + const dto = serialiseLabResult(created, biomarker); await auditLog("labResult.create", { userId: user.id, @@ -275,6 +286,9 @@ async function postLabResult(request: NextRequest) { structured: biomarkerId !== undefined, // v1.25 (iOS #36) — provenance of the reading ("MANUAL" | "OCR"). source: source ?? "MANUAL", + // Which window governs this reading's verdict, so a dashboard can see + // how often a report's own range displaces the catalog band. + referenceOrigin: dto.referenceOrigin, }, }); @@ -298,5 +312,5 @@ async function postLabResult(request: NextRequest) { source: "manual", }).catch(() => {}); - return apiSuccess(serialiseLabResult(created, biomarker), 201); + return apiSuccess(dto, 201); } diff --git a/src/components/labs/__tests__/lab-biomarker-detail.test.tsx b/src/components/labs/__tests__/lab-biomarker-detail.test.tsx index bec4b97b6..a58b764ac 100644 --- a/src/components/labs/__tests__/lab-biomarker-detail.test.tsx +++ b/src/components/labs/__tests__/lab-biomarker-detail.test.tsx @@ -64,6 +64,13 @@ function reading(id: string, value: number, takenAt: string): LabResultDto { unit: "mg/dL", referenceLow: 0, referenceHigh: 100, + catalogReferenceLow: 0, + catalogReferenceHigh: 100, + sourceReferenceLow: null, + sourceReferenceHigh: null, + sourceReferenceText: null, + referenceOrigin: "catalog", + referenceDivergesFromCatalog: false, takenAt, source: "MANUAL", hasNote: false, diff --git a/src/components/labs/lab-biomarker-chart.tsx b/src/components/labs/lab-biomarker-chart.tsx index 96a48fad9..db6612d54 100644 --- a/src/components/labs/lab-biomarker-chart.tsx +++ b/src/components/labs/lab-biomarker-chart.tsx @@ -17,6 +17,7 @@ import { Button } from "@/components/ui/button"; import { CHART_HEIGHT_PX } from "@/lib/charts/constants"; import { prefersReducedMotion } from "@/lib/charts/reduced-motion"; import { formatLabValue } from "@/lib/labs/format-value"; +import { formatReferenceRange } from "@/lib/labs/reference-range"; import { useTranslations, useFormatters } from "@/lib/i18n/context"; import { RichChartTooltip, type RichTooltipRow } from "../charts/chart-tooltip"; @@ -32,6 +33,15 @@ import type { LabResultDto } from "./types"; * MUTED primary fill — never a danger colour — honouring the no-alarming- * colour rule. Every reading carries the same y-axis unit because a chart is * one biomarker only. + * + * A SECOND band draws the window a source report printed, when the readings in + * view carry one. It is visually distinct from the catalog band — an outlined + * band in the chart's secondary hue against the catalog's filled primary — and + * both stay muted; the in/out verdict is the badge's job, never the chart's + * colour. The source window is a per-reading fact, so the band is drawn from + * the NEWEST reading in view that carries one and the legend dates it. When + * the readings in view carry more than one distinct printed window the legend + * says so rather than implying one window covered the whole series. */ const RANGE_DAYS = [ @@ -46,6 +56,26 @@ type RangeKey = (typeof RANGE_DAYS)[number]["key"]; interface ChartPoint { timestamp: number; value: number; + /** The window this reading was judged against, for the tooltip. */ + referenceLow: number | null; + referenceHigh: number | null; + referenceOrigin: LabResultDto["referenceOrigin"]; + sourceReferenceText: string | null; +} + +/** The source window drawn as the second band, resolved from the readings in view. */ +interface SourceBand { + low: number | null; + high: number | null; + /** The reading the band was taken from. */ + takenAt: number; + /** True when the readings in view printed more than one distinct window. */ + mixed: boolean; +} + +/** Identity of a printed window, for counting distinct ones. */ +function bandKey(low: number | null, high: number | null): string { + return `${low ?? ""}|${high ?? ""}`; } export function LabBiomarkerChart({ @@ -87,9 +117,37 @@ export function LabBiomarkerChart({ return filtered.map((r) => ({ timestamp: new Date(r.takenAt).getTime(), value: r.value, + referenceLow: r.referenceLow, + referenceHigh: r.referenceHigh, + referenceOrigin: r.referenceOrigin, + sourceReferenceText: r.sourceReferenceText, })); }, [readings, range, nowMs]); + // The source band: the newest in-view reading whose report printed a window + // with usable bounds. Readings without one contribute nothing — an absent + // window is absent, not a reason to widen or narrow the band. + const sourceBand = useMemo(() => { + const withWindow = points.filter( + (p) => + p.referenceOrigin === "source" && + (p.referenceLow !== null || p.referenceHigh !== null), + ); + if (withWindow.length === 0) return null; + const newest = withWindow.reduce((a, b) => + b.timestamp > a.timestamp ? b : a, + ); + const distinct = new Set( + withWindow.map((p) => bandKey(p.referenceLow, p.referenceHigh)), + ); + return { + low: newest.referenceLow, + high: newest.referenceHigh, + takenAt: newest.timestamp, + mixed: distinct.size > 1, + }; + }, [points]); + // Y domain wraps both the data and the reference window so the band is // always visible even when every reading sits inside it. const yDomain = useMemo<[number, number]>(() => { @@ -97,15 +155,23 @@ export function LabBiomarkerChart({ const candidates = [...values]; if (lowerBound != null) candidates.push(lowerBound); if (upperBound != null) candidates.push(upperBound); + // The source band has to fit too, or the second band is drawn off-canvas + // and the chart silently shows one window while claiming two. + if (sourceBand?.low != null) candidates.push(sourceBand.low); + if (sourceBand?.high != null) candidates.push(sourceBand.high); if (candidates.length === 0) return [0, 1]; const min = Math.min(...candidates); const max = Math.max(...candidates); const pad = (max - min || Math.abs(max) || 1) * 0.1; return [min - pad, max + pad]; - }, [points, lowerBound, upperBound]); + }, [points, lowerBound, upperBound, sourceBand]); const animate = !prefersReducedMotion(); const primary = "var(--primary)"; + // A second muted hue from the chart palette. Distinct from the primary band + // by hue AND by treatment (outline vs fill), so the two are told apart + // without relying on colour alone. + const secondary = "var(--chart-2)"; return (
@@ -185,6 +251,42 @@ export function LabBiomarkerChart({ strokeDasharray="4 4" /> ) : null} + {/* The source window — outlined, not filled, so it reads as a + second band over the catalog one rather than a second fill + competing with it. Same no-alarm-colour rule. */} + {sourceBand && + sourceBand.low != null && + sourceBand.high != null ? ( + + ) : null} + {sourceBand && + sourceBand.low != null && + sourceBand.high == null ? ( + + ) : null} + {sourceBand && + sourceBand.high != null && + sourceBand.low == null ? ( + + ) : null} { const active = props.active ?? false; @@ -201,6 +303,22 @@ export function LabBiomarkerChart({ color: primary, }, ]; + // Name the window THIS reading was judged against. Two + // readings on one chart can carry different printed windows, + // so the band alone cannot answer it per point. + if (point.referenceOrigin === "source") { + rows.push({ + name: t("labs.chart.sourceRangeLabel"), + value: + point.sourceReferenceText ?? + `${formatReferenceRange( + point.referenceLow, + point.referenceHigh, + formatLabValue, + )} ${unit}`.trim(), + color: secondary, + }); + } return ( + {sourceBand ? ( +

+ {sourceBand.mixed + ? t("labs.chart.sourceBandMixed") + : t("labs.chart.sourceBandLegend", { + date: fmt.dateShortSmart(new Date(sourceBand.takenAt)), + })} +

+ ) : null}
)} diff --git a/src/components/labs/lab-form.tsx b/src/components/labs/lab-form.tsx index 476c5da8a..4e865e9dd 100644 --- a/src/components/labs/lab-form.tsx +++ b/src/components/labs/lab-form.tsx @@ -22,6 +22,7 @@ import { import { Textarea } from "@/components/ui/textarea"; import { apiGet, apiPost } from "@/lib/api/api-fetch"; import { localizedApiError } from "@/lib/api/localized-error"; +import { parseReferenceRange } from "@/lib/labs/parse-reference-range"; import { formatReferenceRange } from "@/lib/labs/reference-range"; import { formatLabValue } from "@/lib/labs/format-value"; import { useTranslations } from "@/lib/i18n/context"; @@ -118,6 +119,13 @@ export function LabForm({ const [valueText, setValueText] = useState(""); const [takenAt, setTakenAt] = useState(defaultTakenAtValue); const [note, setNote] = useState(""); + // The window the paper report printed for THIS reading. Optional and folded + // away by default: most entries are typed against a catalog marker and never + // need it, and a field nobody fills is a field in the way. One text input, + // because that is how a report states it — "3,5 - 5,0", "< 5", "bis 5,0". + // The bounds are derived from what is typed; what is typed is kept verbatim. + const [sourceRangeOpen, setSourceRangeOpen] = useState(false); + const [sourceRange, setSourceRange] = useState(""); // v1.30.1 H3 — which submit button is in flight, so the OTHER one doesn't // also show a spinner. `!== null` replaces the old plain `submitting` // boolean for every disabled check below. @@ -193,11 +201,27 @@ export function LabForm({ setPendingAction(keepOpen ? "saveAndAddAnother" : "save"); try { + // Parse client-side so the user sees the derived window before saving, + // and send BOTH: the bounds where they could be read, the text always. + const printed = isQualitative + ? null + : parseReferenceRange(sourceRange, selected?.unit); const created = await apiPost("/api/labs", { biomarkerId, ...(isQualitative ? { valueText: qualitativeValue } : { value: numericValue }), + ...(printed + ? { + ...(printed.low !== null + ? { sourceReferenceLow: printed.low } + : {}), + ...(printed.high !== null + ? { sourceReferenceHigh: printed.high } + : {}), + sourceReferenceText: printed.text, + } + : {}), takenAt: new Date(takenAt).toISOString(), ...(note.trim() ? { note: note.trim() } : {}), }); @@ -221,6 +245,8 @@ export function LabForm({ setValue(""); setValueText(""); setNote(""); + // The next analyte off the same report has its own printed window. + setSourceRange(""); setError(null); onSavedKeepOpen?.(created); // Return focus to wherever the next entry starts so the flow @@ -252,6 +278,20 @@ export function LabForm({ ) : ""; + // What the typed string resolved to, shown back so the user can see whether + // a window was read out of it before the reading is saved. When none was, + // the hint says the text is kept as written rather than staying silent. + const parsedSourceRange = parseReferenceRange(sourceRange, selected?.unit); + const sourceRangeHint = parsedSourceRange + ? parsedSourceRange.low === null && parsedSourceRange.high === null + ? t("labs.form.sourceRangeUnparsed") + : `${formatReferenceRange( + parsedSourceRange.low, + parsedSourceRange.high, + formatLabValue, + )} ${selected?.unit ?? ""}`.trim() + : ""; + const footerNode = ( <> {onCancel ? ( @@ -415,6 +455,39 @@ export function LabForm({

) : null} + {resultType === "numeric" ? ( +
+ {sourceRangeOpen ? ( + <> + + setSourceRange(e.target.value)} + placeholder={t("labs.form.sourceRangePlaceholder")} + maxLength={120} + autoFocus + /> +

+ {sourceRangeHint || t("labs.form.sourceRangeHint")} +

+ + ) : ( + + )} +
+ ) : null} +