test(tests): R2 freeze — archive envelopes of the three golden reports and the frozen N-1 reader

Envelopes exported by the TypeScript domain before the Rust switch (FR, no
logos, fixed export time) are the semantic oracle of the switch (D-R11:
key order may change, values may not). The shipped Zod schemas are copied
verbatim under packages/core-wasm/tests/n-1 (develop 1a7ee7d) so a rollback
reader stays testable after packages/domain is deleted at R5.
This commit is contained in:
bchanot committed 2026-10-13 23:53:12 +02:00
1 parent 1a7ee7d9ac
commit 3114d67959
29 files changed
+8581 -46

No files matched your search

+1
View File
@@ -16,6 +16,7 @@
},
"dependencies": {
"@faunosteo/anatomy": "workspace:*",
"@faunosteo/core-wasm": "workspace:*",
"@faunosteo/domain": "workspace:*",
"@faunosteo/pdf": "workspace:*",
"@faunosteo/supabase": "workspace:*",
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+60
View File
@@ -0,0 +1,60 @@
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
import {
readReportDocument,
ReportSchema,
type Report,
} from '@faunosteo/domain'
import type { SheetIndex } from '@/services/sheetIndex'
import { FIXTURES_DIR } from './goldens'
import {
leavesAsV2Report,
legacyLeaves,
loadLegacyBaseline,
} from './legacyLeaves'
/**
* The three reports the Step 6 goldens and the R2 envelope freeze are drawn
* from: the Step 5 v2 archive fixture migrated, the v3 demo report, and a v2
* report whose sphenoid and ssb findings the migration cannot place.
*/
export const GOLDEN_REPORTS = ['v2full', 'demo', 'v2unresolved'] as const
export type GoldenReportName = (typeof GOLDEN_REPORTS)[number]
export interface GoldenReports {
reports: Record<GoldenReportName, Report>
/** Findings the migration flagged in `v2unresolved`. */
unresolvedOfV2Unresolved: number
}
const readJson = (name: string): unknown =>
JSON.parse(readFileSync(resolve(FIXTURES_DIR, name), 'utf8'))
/** sphenoid + ssb (the families the migration cannot place) plus one leaf that resolves. */
function buildV2Unresolved(sheet: SheetIndex) {
const leaves = legacyLeaves(loadLegacyBaseline())
const unresolvedFamilies = leaves.filter(
(l) => l.zoneId === 'sphenoid' || l.zoneId === 'ssb',
)
const resolved = leaves.find((l) => l.zoneId === 'frontal')!
return readReportDocument(
leavesAsV2Report([...unresolvedFamilies, resolved]),
sheet.sheet.migrationMap,
)
}
export function buildGoldenReports(sheet: SheetIndex): GoldenReports {
const v2unresolved = buildV2Unresolved(sheet)
return {
reports: {
v2full: readReportDocument(
readJson('report-v2.full.json'),
sheet.sheet.migrationMap,
).report,
demo: ReportSchema.parse(readJson('report-v3.demo.json')),
v2unresolved: v2unresolved.report,
},
unresolvedOfV2Unresolved: v2unresolved.unresolvedFindings,
}
}
@@ -0,0 +1,83 @@
/**
* R2 freeze (RUST_ARCHITECTURE_REVIEW VI.1, VI.2 R2): the archive envelope
* (PDF attachment) of the three golden reports, exported by the application
* path with fixed inputs (FR, every logo slot empty, 1×1 raster, fixed
* export time), committed as the TypeScript domain wrote it before the
* switch to the Rust core. Whatever writes the attachment afterwards, it
* must parse with the frozen N-1 reader and be deep-equal to the frozen
* envelope; only the key order may differ (D-R11). `MAKE_R2_FREEZE=1`
* writes the files: never once the switch has landed without an owner
* decision.
*/
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { resolve } from 'node:path'
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
import { readAttachmentBytes } from '@faunosteo/pdf'
import {
readArchiveDocument,
ReportArchiveEnvelopeSchema,
} from '@faunosteo/core-wasm/n-1'
import { exportReportToPdf } from '@/pdf/export'
import type { SheetIndex } from '@/services/sheetIndex'
import { loadTestSheet } from '../helpers/sheet'
import { FIXTURES_DIR, ONE_PX_PNG } from '../helpers/goldens'
import {
buildGoldenReports,
GOLDEN_REPORTS,
type GoldenReports,
} from '../helpers/goldenReports'
vi.mock('@/pdf/browserRasterizer', () => ({
browserRasterizer: vi.fn(async () => ONE_PX_PNG),
}))
vi.mock('@/pdf/branding', async () => {
const { brandingOf } = await import('../helpers/goldens')
return { loadBranding: vi.fn(() => brandingOf('nologos')) }
})
const FREEZE_DIR = resolve(FIXTURES_DIR, 'goldens/r2')
const MAKE_FREEZE = process.env.MAKE_R2_FREEZE === '1'
const EXPORTED_AT = new Date('2026-10-13T09:00:00.000Z')
let sheet: SheetIndex
let golden: GoldenReports
beforeAll(async () => {
sheet = await loadTestSheet()
golden = buildGoldenReports(sheet)
vi.spyOn(console, 'warn').mockImplementation(() => undefined)
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(EXPORTED_AT)
})
afterAll(() => {
vi.useRealTimers()
vi.restoreAllMocks()
})
async function exportedAttachment(
name: (typeof GOLDEN_REPORTS)[number],
): Promise<string> {
const { pdf } = await exportReportToPdf(golden.reports[name], sheet, {
locale: 'fr',
})
return new TextDecoder().decode(await readAttachmentBytes(pdf))
}
describe.each(GOLDEN_REPORTS)('archive envelope of %s', (name) => {
const file = resolve(FREEZE_DIR, `envelope.${name}.fr.nologos.json`)
it('matches the frozen envelope and the N-1 reader accepts it', async () => {
const text = await exportedAttachment(name)
if (MAKE_FREEZE) {
mkdirSync(FREEZE_DIR, { recursive: true })
writeFileSync(file, text)
}
const data: unknown = JSON.parse(text)
expect(data).toEqual(JSON.parse(readFileSync(file, 'utf8')))
expect(ReportArchiveEnvelopeSchema.safeParse(data).success).toBe(true)
const outcome = readArchiveDocument(data, sheet.sheet.migrationMap)
expect(outcome.origin).toBe('envelope_v1')
expect(outcome.archive).not.toBeNull()
expect(outcome.snapshotRejected).toBeUndefined()
}, 30_000)
})
+8 -39
View File
@@ -12,22 +12,17 @@ import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest'
import { PDFDocument } from 'pdf-lib'
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
import {
buildSheetSnapshot,
readReportDocument,
ReportSchema,
type Report,
} from '@faunosteo/domain'
import { buildSheetSnapshot, type Report } from '@faunosteo/domain'
import { exportReportToPdf } from '@/pdf/export'
import { importReportFromPdf } from '@/pdf/import'
import type { SheetIndex } from '@/services/sheetIndex'
import type { Locale } from '@/i18n/types'
import { loadTestSheet } from '../helpers/sheet'
import {
leavesAsV2Report,
legacyLeaves,
loadLegacyBaseline,
} from '../helpers/legacyLeaves'
buildGoldenReports,
GOLDEN_REPORTS,
type GoldenReportName,
} from '../helpers/goldenReports'
import {
checkGolden,
FIXTURES_DIR,
@@ -54,43 +49,17 @@ vi.mock('@/pdf/branding', async () => {
return { loadBranding: vi.fn(() => brandingOf(logoMode.current)) }
})
const REPORTS = ['v2full', 'demo', 'v2unresolved'] as const
type ReportName = (typeof REPORTS)[number]
const REPORTS = GOLDEN_REPORTS
const MODES: readonly LogoMode[] = ['nologos', 'logos']
const BARE_PDF = resolve(FIXTURES_DIR, 'report-v3.bare.pdf')
const readJson = (name: string): unknown =>
JSON.parse(readFileSync(resolve(FIXTURES_DIR, name), 'utf8'))
let sheet: SheetIndex
let reports: Record<ReportName, Report>
let reports: Record<GoldenReportName, Report>
let unresolvedOfV2Unresolved = 0
/** sphenoid + ssb (the families the migration cannot place) plus one leaf that resolves. */
function buildV2Unresolved(): Report {
const leaves = legacyLeaves(loadLegacyBaseline())
const unresolvedFamilies = leaves.filter(
(l) => l.zoneId === 'sphenoid' || l.zoneId === 'ssb',
)
const resolved = leaves.find((l) => l.zoneId === 'frontal')!
const outcome = readReportDocument(
leavesAsV2Report([...unresolvedFamilies, resolved]),
sheet.sheet.migrationMap,
)
unresolvedOfV2Unresolved = outcome.unresolvedFindings
return outcome.report
}
beforeAll(async () => {
sheet = await loadTestSheet()
reports = {
v2full: readReportDocument(
readJson('report-v2.full.json'),
sheet.sheet.migrationMap,
).report,
demo: ReportSchema.parse(readJson('report-v3.demo.json')),
v2unresolved: buildV2Unresolved(),
}
;({ reports, unresolvedOfV2Unresolved } = buildGoldenReports(sheet))
vi.spyOn(console, 'warn').mockImplementation(() => undefined)
})
afterAll(() => vi.restoreAllMocks())
+6 -3
View File
@@ -2,12 +2,13 @@
"name": "@faunosteo/core-wasm",
"version": "0.1.0",
"private": true,
"description": "Faunosteo core compiled to WebAssembly: loader, generated TypeScript types of the contracts, and the R0 proofs (panic, serialisation, size)",
"description": "Faunosteo core compiled to WebAssembly: runtime loader, generated TypeScript types of the contracts, the frozen N-1 reader, and the R0 proofs (panic, serialisation, size)",
"license": "MIT",
"type": "module",
"exports": {
".": "./src/index.ts",
"./types": "./types/index.ts"
"./types": "./types/index.ts",
"./n-1": "./tests/n-1/index.ts"
},
"scripts": {
"typecheck": "tsc -p tsconfig.json --noEmit",
@@ -17,12 +18,14 @@
"build": "tsc -p tsconfig.json --noEmit"
},
"devDependencies": {
"@faunosteo/domain": "workspace:*",
"@types/node": "^20.19.41",
"eslint": "^9.17.0",
"globals": "^15.14.0",
"typescript": "^5.7.2",
"typescript-eslint": "^8.19.0",
"vitest": "^3.2.7"
},
"dependencies": {
"zod": "^3.24.1"
}
}
@@ -0,0 +1,44 @@
import {
AnatomicalSheetDocumentSchema,
SHEET_DOCUMENT_SCHEMA_VERSION,
type AnatomicalSheetDocument,
type LocalizedText,
} from './schema'
export interface NewSheetDocumentParams {
species_id: string
name: LocalizedText
}
export const MAIN_VIEW_ID = 'view-main'
/**
* Starting point of a new sheet: shape-valid so it can be saved as a draft
* at once, but not publishable until the main view gets its SVG asset.
*/
export function createEmptySheetDocument(
params: NewSheetDocumentParams,
): AnatomicalSheetDocument {
return AnatomicalSheetDocumentSchema.parse({
schema_version: SHEET_DOCUMENT_SCHEMA_VERSION,
species_id: params.species_id,
name: params.name,
description: {},
scope_disclaimer: {},
attribution: { authors: [], license: null, notes: null },
vertebral_config: { regions: [] },
references: [],
categories: [],
views: [
{
id: MAIN_VIEW_ID,
kind: 'main',
name: { fr: 'Vue principale', en: 'Main view' },
svg_asset_id: null,
view_box: null,
},
],
annotations: [],
finding_zones: [],
})
}
@@ -0,0 +1,4 @@
export * from './schema'
export * from './validate'
export * from './create'
export * from './sheet-index'
@@ -0,0 +1,327 @@
import { z } from 'zod'
/**
* Canonical anatomical sheet document, schema_version 2.
*
* Shape contract of docs/development/ANATOMICAL_SHEET_MODEL.md §2. Every
* object is strict: a canonical document must not silently carry fields no
* version of the schema defines. Cross-references (view ids, zone ids,
* reference ids…) are checked by validateSheetDocument, not here, so a
* draft with dangling references can still be saved.
*
* Version 2 (Step 4c): shared bibliographic `references` registry cited by
* `reference_ids`, `review_status` on findings and annotations, optional
* `count_range` on vertebral regions. No version 1 document was ever
* published, so version 1 is not read any more.
*/
export const SHEET_DOCUMENT_SCHEMA_VERSION = 2
/** Ids are never derived from labels, so translations never move them. */
export const STABLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/
export const StableIdSchema = z.string().regex(STABLE_ID_PATTERN)
/** Region codes are free (C, T, L, S, Cd for the horse), case included. */
export const RegionCodeSchema = z
.string()
.regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,15}$/)
export const LocalizedTextSchema = z
.object({ fr: z.string().min(1), en: z.string().min(1) })
.strict()
export const LocalizedOptionalTextSchema = z
.object({ fr: z.string().optional(), en: z.string().optional() })
.strict()
/**
* How far the sheet content was checked against references. `inherited` =
* taken over from a previous source without review; `reviewed` = checked
* and cited; `to_confirm` = changed or added on documented grounds, still
* awaiting a professional's confirmation.
*/
export const ReviewStatusSchema = z.enum(['inherited', 'reviewed', 'to_confirm'])
const CountRangeSchema = z
.object({ min: z.number().int().min(1), max: z.number().int().min(1) })
.strict()
/**
* `count` is the usual number of vertebrae (what the picker shows by
* default); `count_range` states the documented individual variation so a
* report may record a vertebra beyond the usual count. Null = no variation.
*/
export const VertebralRegionSchema = z
.object({
code: RegionCodeSchema,
name: LocalizedTextSchema,
count: z.number().int().min(1),
count_range: CountRangeSchema.nullable().default(null),
})
.strict()
const HexColorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/)
export const AnnotationCategorySchema = z
.object({
id: StableIdSchema,
name: LocalizedTextSchema,
color: HexColorSchema.nullable(),
})
.strict()
const CoordinateSchema = z.number().finite()
export const ViewBoxSchema = z
.object({
min_x: CoordinateSchema,
min_y: CoordinateSchema,
width: CoordinateSchema.positive(),
height: CoordinateSchema.positive(),
})
.strict()
/** Null asset on a detail view means "parent asset cropped by view_box". */
const viewCommon = {
id: StableIdSchema,
name: LocalizedTextSchema,
svg_asset_id: z.string().uuid().nullable(),
view_box: ViewBoxSchema.nullable(),
}
const MainViewSchema = z
.object({ ...viewCommon, kind: z.literal('main') })
.strict()
const DetailViewSchema = z
.object({
...viewCommon,
kind: z.literal('detail'),
parent_view_id: StableIdSchema,
})
.strict()
/** Views form a tree: a detail names its parent, any depth. */
export const SheetViewSchema = z.discriminatedUnion('kind', [
MainViewSchema,
DetailViewSchema,
])
const CircleSchema = z
.object({
type: z.literal('circle'),
cx: CoordinateSchema,
cy: CoordinateSchema,
r: CoordinateSchema.positive(),
})
.strict()
const PolygonSchema = z
.object({
type: z.literal('polygon'),
points: z.array(z.tuple([CoordinateSchema, CoordinateSchema])).min(3),
})
.strict()
const PathSchema = z
.object({ type: z.literal('path'), d: z.string().min(1) })
.strict()
export const GeometrySchema = z.discriminatedUnion('type', [
CircleSchema,
PolygonSchema,
PathSchema,
])
/** Explicit on every annotation: absence no longer carries meaning. */
export const LateralitySchema = z.enum([
'unpaired',
'bilateral',
'left',
'right',
])
const annotationCommon = {
id: StableIdSchema,
view_id: StableIdSchema,
category_id: StableIdSchema,
laterality: LateralitySchema,
geometry: GeometrySchema.nullable(),
review_status: ReviewStatusSchema.default('inherited'),
/** Marker colour of this annotation; null = the category colour. */
color: HexColorSchema.nullable().default(null),
}
/** Observable annotations link to findings through one explicit field. */
const observableFields = {
...annotationCommon,
name: LocalizedTextSchema,
finding_zone_id: StableIdSchema.nullable(),
vertebral_region_code: RegionCodeSchema.nullable(),
}
const PointAnnotationSchema = z
.object({ ...observableFields, kind: z.literal('point') })
.strict()
const ZoneAnnotationSchema = z
.object({ ...observableFields, kind: z.literal('zone') })
.strict()
/** Navigation only: a trigger never carries findings. */
const DetailTriggerAnnotationSchema = z
.object({
...annotationCommon,
kind: z.literal('detail_trigger'),
name: LocalizedTextSchema.nullable(),
opens_view_id: StableIdSchema,
})
.strict()
export const AnnotationSchema = z.discriminatedUnion('kind', [
PointAnnotationSchema,
ZoneAnnotationSchema,
DetailTriggerAnnotationSchema,
])
/** Documents are shared across users: only web links, never javascript: URLs. */
const HttpUrlSchema = z
.string()
.url()
.refine((url) => /^https?:\/\//i.test(url), 'http(s) URL expected')
/**
* One bibliographic reference, declared once in the document and cited by
* id from any number of findings (an anatomy atlas backs hundreds of
* entries). `citation` is the human-readable form (author, title, edition,
* year, publisher or journal, location in the work when known).
*/
export const ReferenceSchema = z
.object({
id: StableIdSchema,
type: z.enum(['book', 'journal', 'standard', 'legal', 'web', 'manual']),
citation: z.string().min(1),
url: HttpUrlSchema.nullable().default(null),
doi: z.string().min(1).nullable().default(null),
})
.strict()
export type Reference = z.infer<typeof ReferenceSchema>
export type ReviewStatus = z.infer<typeof ReviewStatusSchema>
export type LocalizedText = z.infer<typeof LocalizedTextSchema>
export type LocalizedOptionalText = z.infer<typeof LocalizedOptionalTextSchema>
/** Parsed node: every optional key of the authoring form is filled in. */
export interface FindingNode {
id: string
name: LocalizedText
description: LocalizedOptionalText
requires_vet_referral: boolean
reference_ids: string[]
review_status: ReviewStatus
children: FindingNode[]
}
/** Authoring form: leaves stay lean, hundreds of them carry no empty keys. */
export interface FindingNodeInput {
id: string
name: LocalizedText
description?: LocalizedOptionalText
requires_vet_referral?: boolean
reference_ids?: string[]
review_status?: ReviewStatus
children?: FindingNodeInput[]
}
export const FindingNodeSchema: z.ZodType<
FindingNode,
z.ZodTypeDef,
FindingNodeInput
> = z.lazy(() =>
z
.object({
id: StableIdSchema,
name: LocalizedTextSchema,
description: LocalizedOptionalTextSchema.default({}),
requires_vet_referral: z.boolean().default(false),
reference_ids: z.array(StableIdSchema).default([]),
review_status: ReviewStatusSchema.default('inherited'),
children: z.array(FindingNodeSchema).default([]),
})
.strict(),
)
/** Typed business buckets; creators may add their own as 'custom'. */
export const FindingCategoryKindSchema = z.enum([
'dysfunction',
'consultation_reason',
'anamnesis',
'custom',
])
export const FindingCategorySchema = z
.object({
id: StableIdSchema,
kind: FindingCategoryKindSchema,
name: LocalizedTextSchema,
description: LocalizedOptionalTextSchema.default({}),
reference_ids: z.array(StableIdSchema).default([]),
review_status: ReviewStatusSchema.default('inherited'),
children: z.array(FindingNodeSchema),
})
.strict()
export const FindingZoneSchema = z
.object({
id: StableIdSchema,
name: LocalizedTextSchema,
categories: z.array(FindingCategorySchema),
})
.strict()
const AttributionSchema = z
.object({
authors: z.array(z.string().min(1)),
license: z.string().min(1).nullable(),
notes: z.string().min(1).nullable(),
})
.strict()
const VertebralConfigSchema = z
.object({ regions: z.array(VertebralRegionSchema) })
.strict()
export const AnatomicalSheetDocumentSchema = z
.object({
schema_version: z.literal(SHEET_DOCUMENT_SCHEMA_VERSION),
species_id: StableIdSchema,
name: LocalizedTextSchema,
description: LocalizedOptionalTextSchema,
scope_disclaimer: LocalizedOptionalTextSchema,
attribution: AttributionSchema,
vertebral_config: VertebralConfigSchema,
references: z.array(ReferenceSchema),
categories: z.array(AnnotationCategorySchema),
views: z.array(SheetViewSchema),
annotations: z.array(AnnotationSchema),
finding_zones: z.array(FindingZoneSchema),
})
.strict()
export type AnatomicalSheetDocument = z.output<
typeof AnatomicalSheetDocumentSchema
>
export type AnatomicalSheetDocumentInput = z.input<
typeof AnatomicalSheetDocumentSchema
>
export type VertebralRegion = z.infer<typeof VertebralRegionSchema>
export type AnnotationCategory = z.infer<typeof AnnotationCategorySchema>
export type ViewBox = z.infer<typeof ViewBoxSchema>
export type SheetView = z.infer<typeof SheetViewSchema>
export type Geometry = z.infer<typeof GeometrySchema>
export type Laterality = z.infer<typeof LateralitySchema>
export type Annotation = z.infer<typeof AnnotationSchema>
export type FindingCategoryKind = z.infer<typeof FindingCategoryKindSchema>
export type FindingCategory = z.output<typeof FindingCategorySchema>
export type FindingZone = z.output<typeof FindingZoneSchema>
@@ -0,0 +1,127 @@
import type {
AnatomicalSheetDocument,
Annotation,
FindingCategory,
FindingNode,
FindingZone,
LocalizedText,
SheetView,
VertebralRegion,
} from './schema'
/**
* Read-only lookups over a sheet document. Everything the editor and the
* PDF engine derive from the sheet (zone names, finding paths, spine
* regions, trigger targets) comes from the document here, by stable id:
* no label drives logic. The index keeps the source it was built from so a
* caller gets back exactly what it passed (a loaded sheet with its migration
* map, or an archived snapshot).
*/
/** The minimum a sheet source carries: provenance, document, SVG text by asset id. */
export interface SheetIndexSource {
ref: { documentSha256: string }
document: AnatomicalSheetDocument
assets: Readonly<Record<string, string>>
}
export type ObservableAnnotation = Extract<
Annotation,
{ kind: 'point' | 'zone' }
>
export interface SheetIndex<S extends SheetIndexSource = SheetIndexSource> {
sheet: S
mainView: SheetView
view(id: string): SheetView | undefined
annotation(id: string): Annotation | undefined
annotationsOfView(viewId: string): Annotation[]
findingZone(id: string): FindingZone | undefined
/** The category or node at a path, undefined when absent from the sheet. */
nodeAt(
zoneId: string,
path: readonly string[],
): FindingCategory | FindingNode | undefined
regions(): VertebralRegion[]
region(code: string): VertebralRegion | undefined
/** The annotation that opens the vertebra picker for a region on a view. */
spineAnnotation(
regionCode: string,
viewId: string,
): ObservableAnnotation | undefined
/** Whether an annotation opens the vertebra picker. */
isSpine(annotationId: string): boolean
name(annotation: Annotation): LocalizedText
}
/** The label in a locale, the other locale as fallback, '' when none. */
export function pickLabel(
text: LocalizedText | null | undefined,
locale: 'fr' | 'en',
): string {
if (!text) return ''
return locale === 'en' ? text.en || text.fr : text.fr || text.en
}
export function isObservable(
a: Annotation | undefined,
): a is ObservableAnnotation {
return a !== undefined && a.kind !== 'detail_trigger'
}
function nodeAtPath(
zone: FindingZone | undefined,
path: readonly string[],
): FindingCategory | FindingNode | undefined {
if (!zone || path.length === 0) return undefined
let node: FindingCategory | FindingNode | undefined = zone.categories.find(
(c) => c.id === path[0],
)
for (const segment of path.slice(1)) {
if (!node) return undefined
node = node.children.find((n) => n.id === segment)
}
return node
}
export function buildSheetIndex<S extends SheetIndexSource>(
sheet: S,
): SheetIndex<S> {
const { document } = sheet
const views = new Map(document.views.map((v) => [v.id, v]))
const annotations = new Map(document.annotations.map((a) => [a.id, a]))
const zones = new Map(document.finding_zones.map((z) => [z.id, z]))
const regions = new Map(
document.vertebral_config.regions.map((r) => [r.code, r]),
)
const mainView = document.views.find((v) => v.kind === 'main')
if (!mainView) throw new Error('sheet has no main view')
return {
sheet,
mainView,
view: (id) => views.get(id),
annotation: (id) => annotations.get(id),
annotationsOfView: (viewId) =>
document.annotations.filter((a) => a.view_id === viewId),
findingZone: (id) => zones.get(id),
nodeAt: (zoneId, path) => nodeAtPath(zones.get(zoneId), path),
regions: () => document.vertebral_config.regions,
region: (code) => regions.get(code),
spineAnnotation: (code, viewId) =>
document.annotations.find(
(a): a is ObservableAnnotation =>
isObservable(a) &&
a.view_id === viewId &&
a.vertebral_region_code === code,
),
isSpine: (id) => {
const a = annotations.get(id)
return isObservable(a) && a.vertebral_region_code !== null
},
name: (a) =>
a.kind === 'detail_trigger'
? (a.name ?? views.get(a.opens_view_id)?.name ?? { fr: '', en: '' })
: a.name,
}
}
@@ -0,0 +1,494 @@
import type {
AnatomicalSheetDocument,
Annotation,
FindingNode,
SheetView,
VertebralRegion,
} from './schema'
/**
* Integrity tier of the sheet model (ANATOMICAL_SHEET_MODEL.md §2.1).
*
* The shape tier (Zod) accepts dangling references so drafts can be saved
* mid-edit; this tier lists every inconsistency for the editor and gates
* publication. Each rule is one function; codes are part of the contract
* shared with the SQL re-check (private.sheet_document_issues).
*/
export type SheetIssueSeverity = 'error' | 'warning'
export interface SheetIssue {
code: string
severity: SheetIssueSeverity
path: string
message: string
}
type Rule = (doc: AnatomicalSheetDocument) => SheetIssue[]
type ObservableAnnotation = Exclude<Annotation, { kind: 'detail_trigger' }>
type TriggerAnnotation = Extract<Annotation, { kind: 'detail_trigger' }>
type DetailView = Extract<SheetView, { kind: 'detail' }>
/** A sibling level of the finding tree: categories or node children. */
interface FindingLevelItem {
id: string
reference_ids: readonly string[]
children: readonly FindingNode[]
}
function error(code: string, path: string, message: string): SheetIssue {
return { code, severity: 'error', path, message }
}
function warning(code: string, path: string, message: string): SheetIssue {
return { code, severity: 'warning', path, message }
}
/** Indexes of entries whose value already appeared earlier in the list. */
function repeatedIndexes(values: readonly string[]): number[] {
const seen = new Set<string>()
const repeated: number[] = []
values.forEach((value, index) => {
if (seen.has(value)) repeated.push(index)
seen.add(value)
})
return repeated
}
function duplicateIssues(
values: readonly string[],
code: string,
pathOf: (index: number) => string,
): SheetIssue[] {
return repeatedIndexes(values).map((index) =>
error(code, pathOf(index), `Duplicate id "${values[index]}"`),
)
}
function isObservable(
annotation: Annotation,
): annotation is ObservableAnnotation {
return annotation.kind !== 'detail_trigger'
}
function isTrigger(annotation: Annotation): annotation is TriggerAnnotation {
return annotation.kind === 'detail_trigger'
}
function viewsById(doc: AnatomicalSheetDocument): Map<string, SheetView> {
const byId = new Map<string, SheetView>()
for (const view of doc.views) if (!byId.has(view.id)) byId.set(view.id, view)
return byId
}
/** Rendering starts from a single root drawing. */
const checkMainViewCount: Rule = (doc) => {
const count = doc.views.filter((view) => view.kind === 'main').length
if (count === 1) return []
return [
error('view.main.count', 'views', `Expected 1 main view, found ${count}`),
]
}
const checkViewIdsUnique: Rule = (doc) =>
duplicateIssues(
doc.views.map((view) => view.id),
'view.id.duplicate',
(index) => `views[${index}].id`,
)
const checkViewParentsExist: Rule = (doc) => {
const byId = viewsById(doc)
return doc.views.flatMap((view, index) =>
view.kind === 'detail' && !byId.has(view.parent_view_id)
? [
error(
'view.parent.missing',
`views[${index}].parent_view_id`,
`Parent view "${view.parent_view_id}" does not exist`,
),
]
: [],
)
}
/**
* True when the parent chain loops before reaching the main view. A
* missing parent ends the walk: that case is view.parent.missing.
*/
function loopsBeforeMain(view: DetailView, byId: Map<string, SheetView>) {
const visited = new Set<string>([view.id])
let current: SheetView = view
while (current.kind === 'detail') {
const parent = byId.get(current.parent_view_id)
if (!parent) return false
if (visited.has(parent.id)) return true
visited.add(parent.id)
current = parent
}
return false
}
const checkViewParentCycles: Rule = (doc) => {
const byId = viewsById(doc)
return doc.views.flatMap((view, index) =>
view.kind === 'detail' && loopsBeforeMain(view, byId)
? [
error(
'view.parent.cycle',
`views[${index}].parent_view_id`,
`Parent chain of "${view.id}" never reaches the main view`,
),
]
: [],
)
}
function isOpenedFromParent(
view: DetailView,
doc: AnatomicalSheetDocument,
): boolean {
return doc.annotations.some(
(annotation) =>
isTrigger(annotation) &&
annotation.opens_view_id === view.id &&
annotation.view_id === view.parent_view_id,
)
}
/** A detail view nobody can open is dead content for the practitioner. */
const checkViewsReachable: Rule = (doc) => {
const byId = viewsById(doc)
return doc.views.flatMap((view, index) =>
view.kind === 'detail' &&
byId.has(view.parent_view_id) &&
!isOpenedFromParent(view, doc)
? [
error(
'view.unreachable',
`views[${index}]`,
`No detail_trigger in "${view.parent_view_id}" opens "${view.id}"`,
),
]
: [],
)
}
/** Every view must have something to draw: its own asset or a crop. */
function viewAssetIssue(view: SheetView, index: number): SheetIssue[] {
if (view.svg_asset_id !== null) return []
if (view.kind === 'main') {
return [
error(
'view.asset.missing',
`views[${index}].svg_asset_id`,
`Main view "${view.id}" has no SVG asset`,
),
]
}
if (view.view_box !== null) return []
return [
error(
'view.asset.missing',
`views[${index}].view_box`,
`Detail view "${view.id}" has neither an asset nor a view_box`,
),
]
}
const checkViewAssets: Rule = (doc) => doc.views.flatMap(viewAssetIssue)
/** Report points are keyed by annotation id across every view. */
const checkAnnotationIdsUnique: Rule = (doc) =>
duplicateIssues(
doc.annotations.map((annotation) => annotation.id),
'annotation.id.duplicate',
(index) => `annotations[${index}].id`,
)
const checkAnnotationViews: Rule = (doc) => {
const byId = viewsById(doc)
return doc.annotations.flatMap((annotation, index) =>
byId.has(annotation.view_id)
? []
: [
error(
'annotation.view.missing',
`annotations[${index}].view_id`,
`View "${annotation.view_id}" does not exist`,
),
],
)
}
const checkAnnotationCategories: Rule = (doc) => {
const ids = new Set(doc.categories.map((category) => category.id))
return doc.annotations.flatMap((annotation, index) =>
ids.has(annotation.category_id)
? []
: [
error(
'annotation.category.missing',
`annotations[${index}].category_id`,
`Category "${annotation.category_id}" does not exist`,
),
],
)
}
/** A trigger opens a direct child of the view it is drawn in. */
function opensChildOfOwnView(
trigger: TriggerAnnotation,
byId: Map<string, SheetView>,
): boolean {
const target = byId.get(trigger.opens_view_id)
return target?.kind === 'detail' && target.parent_view_id === trigger.view_id
}
const checkTriggerTargets: Rule = (doc) => {
const byId = viewsById(doc)
return doc.annotations.flatMap((annotation, index) =>
isTrigger(annotation) && !opensChildOfOwnView(annotation, byId)
? [
error(
'annotation.opens_view.invalid',
`annotations[${index}].opens_view_id`,
`"${annotation.opens_view_id}" is not a detail child of ` +
`"${annotation.view_id}"`,
),
]
: [],
)
}
const checkAnnotationFindingZones: Rule = (doc) => {
const ids = new Set(doc.finding_zones.map((zone) => zone.id))
return doc.annotations.flatMap((annotation, index) =>
isObservable(annotation) &&
annotation.finding_zone_id !== null &&
!ids.has(annotation.finding_zone_id)
? [
error(
'annotation.finding_zone.missing',
`annotations[${index}].finding_zone_id`,
`Finding zone "${annotation.finding_zone_id}" does not exist`,
),
]
: [],
)
}
const checkAnnotationRegions: Rule = (doc) => {
const codes = new Set(doc.vertebral_config.regions.map((r) => r.code))
return doc.annotations.flatMap((annotation, index) =>
isObservable(annotation) &&
annotation.vertebral_region_code !== null &&
!codes.has(annotation.vertebral_region_code)
? [
error(
'annotation.region.missing',
`annotations[${index}].vertebral_region_code`,
`Vertebral region "${annotation.vertebral_region_code}" ` +
'is not configured',
),
]
: [],
)
}
/** Allowed in a draft, but a click on it would offer nothing to record. */
const checkAnnotationsHaveFindings: Rule = (doc) =>
doc.annotations.flatMap((annotation, index) =>
isObservable(annotation) && annotation.finding_zone_id === null
? [
warning(
'annotation.no_findings',
`annotations[${index}].finding_zone_id`,
`Annotation "${annotation.id}" is linked to no finding zone`,
),
]
: [],
)
const checkRegionCodesUnique: Rule = (doc) =>
duplicateIssues(
doc.vertebral_config.regions.map((region) => region.code),
'region.code.duplicate',
(index) => `vertebral_config.regions[${index}].code`,
)
const checkCategoryIdsUnique: Rule = (doc) =>
duplicateIssues(
doc.categories.map((category) => category.id),
'category.id.duplicate',
(index) => `categories[${index}].id`,
)
const checkFindingZoneIdsUnique: Rule = (doc) =>
duplicateIssues(
doc.finding_zones.map((zone) => zone.id),
'finding_zone.id.duplicate',
(index) => `finding_zones[${index}].id`,
)
/**
* Findings are addressed by (zone, path[]) as Finding.path does today, so
* ids only need to be unique among siblings, at every depth.
*/
function siblingIssues(
nodes: readonly FindingLevelItem[],
path: string,
): SheetIssue[] {
const own = duplicateIssues(
nodes.map((node) => node.id),
'finding.id.duplicate',
(index) => `${path}[${index}].id`,
)
const nested = nodes.flatMap((node, index) =>
siblingIssues(node.children, `${path}[${index}].children`),
)
return [...own, ...nested]
}
const checkFindingSiblings: Rule = (doc) =>
doc.finding_zones.flatMap((zone, index) =>
siblingIssues(zone.categories, `finding_zones[${index}].categories`),
)
/** Allowed in a draft, but nothing on the drawing can reach this zone. */
const checkFindingZonesReferenced: Rule = (doc) => {
const referenced = new Set(
doc.annotations.filter(isObservable).map((a) => a.finding_zone_id),
)
return doc.finding_zones.flatMap((zone, index) =>
referenced.has(zone.id)
? []
: [
warning(
'finding_zone.unreferenced',
`finding_zones[${index}]`,
`No annotation points to finding zone "${zone.id}"`,
),
],
)
}
const checkReferenceIdsUnique: Rule = (doc) =>
duplicateIssues(
doc.references.map((reference) => reference.id),
'reference.id.duplicate',
(index) => `references[${index}].id`,
)
/** A citation must point at a declared reference, at every depth. */
function citationIssues(
nodes: readonly FindingLevelItem[],
path: string,
known: ReadonlySet<string>,
): SheetIssue[] {
return nodes.flatMap((node, index) => {
const own = node.reference_ids.flatMap((id, refIndex) =>
known.has(id)
? []
: [
error(
'finding.reference.missing',
`${path}[${index}].reference_ids[${refIndex}]`,
`Reference "${id}" is not declared in references`,
),
],
)
const nested = citationIssues(
node.children,
`${path}[${index}].children`,
known,
)
return [...own, ...nested]
})
}
const checkFindingReferences: Rule = (doc) => {
const known = new Set(doc.references.map((reference) => reference.id))
return doc.finding_zones.flatMap((zone, index) =>
citationIssues(
zone.categories,
`finding_zones[${index}].categories`,
known,
),
)
}
/** The usual count must sit inside the documented variation. */
function countRangeIssue(region: VertebralRegion, index: number): SheetIssue[] {
const range = region.count_range
if (range === null) return []
if (range.min <= region.count && region.count <= range.max) return []
return [
error(
'region.count_range.invalid',
`vertebral_config.regions[${index}].count_range`,
`Region "${region.code}": count ${region.count} outside ` +
`${range.min}–${range.max}`,
),
]
}
const checkRegionCountRanges: Rule = (doc) =>
doc.vertebral_config.regions.flatMap(countRangeIssue)
const RULES: readonly Rule[] = [
checkMainViewCount,
checkViewIdsUnique,
checkViewParentsExist,
checkViewParentCycles,
checkViewsReachable,
checkViewAssets,
checkAnnotationIdsUnique,
checkAnnotationViews,
checkAnnotationCategories,
checkTriggerTargets,
checkAnnotationFindingZones,
checkAnnotationRegions,
checkAnnotationsHaveFindings,
checkRegionCodesUnique,
checkCategoryIdsUnique,
checkFindingZoneIdsUnique,
checkFindingSiblings,
checkFindingZonesReferenced,
checkReferenceIdsUnique,
checkFindingReferences,
checkRegionCountRanges,
]
/** Lists every integrity issue of a shape-valid document. */
export function validateSheetDocument(
doc: AnatomicalSheetDocument,
): SheetIssue[] {
return RULES.flatMap((rule) => rule(doc))
}
/** Warnings never block publication; errors always do. */
export function isPublishable(issues: readonly SheetIssue[]): boolean {
return !issues.some((issue) => issue.severity === 'error')
}
export class SheetValidationError extends Error {
readonly issues: SheetIssue[]
constructor(issues: SheetIssue[]) {
const errors = issues.filter((issue) => issue.severity === 'error')
super(
`Sheet document is not publishable: ${errors.length} error(s), ` +
`first: ${errors[0]?.code ?? 'none'}`,
)
this.name = 'SheetValidationError'
this.issues = issues
}
}
/** TypeScript-side publication gate, mirrored by SQL at publish time. */
export function assertPublishable(doc: AnatomicalSheetDocument): void {
const issues = validateSheetDocument(doc)
if (!isPublishable(issues)) throw new SheetValidationError(issues)
}
@@ -0,0 +1,59 @@
import { z } from 'zod'
/**
* The visual identity a PDF archive embeds so a re-export needs no network
* and no `public/` folder (STEP6 §3.4): logos as PNG base64 or SVG text,
* credits with the URL and the text printed when the logo fails. Caps are
* STEP6 §15 (branding row).
*/
const KIB = 1024
const BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/
/**
* `http(s)://` then printable ASCII without `"`, `'`, `(`, `)`, `<`, `>`
* or `\`: the URL is written into PDF link actions and must never be able
* to close a string literal or carry a control character. Expressed as the
* allowed ranges of printable ASCII (0x21-0x7e) minus those seven.
*/
const HTTP_URL_PATTERN = /^https?:\/\/[!#-&*-;=?-[\]-~]+$/
const HttpUrlSchema = z
.string()
.max(2048)
.url()
.regex(HTTP_URL_PATTERN, 'http(s) URL expected')
export const ImageAssetSchema = z.discriminatedUnion('kind', [
z
.object({
kind: z.literal('png'),
base64: z
.string()
.max(512 * KIB)
.regex(BASE64_PATTERN),
})
.strict(),
z.object({ kind: z.literal('svg'), svg: z.string().max(256 * KIB) }).strict(),
])
export type ImageAsset = z.infer<typeof ImageAssetSchema>
export const CreditSchema = z
.object({
logo: ImageAssetSchema.nullable(),
url: HttpUrlSchema,
fallbackText: z.string().max(128),
})
.strict()
export type Credit = z.infer<typeof CreditSchema>
export const BrandingSchema = z
.object({
siteUrl: HttpUrlSchema,
headerLogo: ImageAssetSchema.nullable(),
footerLogo: ImageAssetSchema.nullable(),
poweredBy: CreditSchema.nullable(),
partner: CreditSchema.nullable(),
})
.strict()
export type Branding = z.infer<typeof BrandingSchema>
@@ -0,0 +1,172 @@
import { z } from 'zod'
import { readReportDocument } from '../report/migrate'
import type { ReportMigrationMap } from '../report/migration-map'
import { REPORT_VERSION, ReportSchema, type Report } from '../report/v3'
import { BrandingSchema, type Branding } from './branding'
import { PdfLabelSetSchema, type PdfLabelSet } from './labels'
import {
SheetSnapshotSchema,
SnapshotError,
assertSnapshot,
type SheetSnapshot,
type SnapshotRejection,
} from './snapshot'
/**
* Attachment of a Step 6 PDF: the report (v3, unchanged) wrapped with the
* sheet snapshot, the branding and the PDF labels it was printed with
* (STEP6 §2.3). Reading is layered (§4, §14 "Read"): the report is located
* and parsed first so it is never lost because of its wrapper; the wrapper
* is then validated or dropped with a reason.
*/
export const ENVELOPE_FORMAT = 'faunosteo-report-archive'
export const ENVELOPE_VERSION = 1
export interface ReportArchiveEnvelope {
format: typeof ENVELOPE_FORMAT
envelopeVersion: typeof ENVELOPE_VERSION
/** ISO timestamp of the export. */
exportedAt: string
locale: 'fr' | 'en'
/** As exported, never rebased. */
report: Report
sheetSnapshot: SheetSnapshot
branding: Branding
labels: PdfLabelSet
}
/** Metadata is not strict: an additive v1 field never breaks an older reader. */
const EnvelopeMetadataSchema = z.object({
format: z.literal(ENVELOPE_FORMAT),
envelopeVersion: z.literal(ENVELOPE_VERSION),
exportedAt: z.string(),
locale: z.enum(['fr', 'en']),
})
/** Everything but the report and the snapshot, which the reader checks itself. */
const EnvelopeWrapperSchema = EnvelopeMetadataSchema.extend({
branding: BrandingSchema,
labels: PdfLabelSetSchema,
})
export const ReportArchiveEnvelopeSchema: z.ZodType<
ReportArchiveEnvelope,
z.ZodTypeDef,
unknown
> = EnvelopeWrapperSchema.extend({
report: ReportSchema,
sheetSnapshot: SheetSnapshotSchema,
})
export type ArchiveOrigin = 'envelope_v1' | 'bare_v3' | 'v2'
export interface ArchiveReadOutcome {
report: Report
origin: ArchiveOrigin
migrated: boolean
/** From the v2 migration; 0 for a v3 report. */
unresolvedZones: number
unresolvedFindings: number
/** The validated envelope, when accepted. */
archive: ReportArchiveEnvelope | null
/** Envelope present but its snapshot dropped. */
snapshotRejected?: SnapshotRejection
}
type Wrapped =
| { archive: ReportArchiveEnvelope }
| { snapshotRejected: SnapshotRejection }
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
/** An envelope of any version is recognised by a numeric envelopeVersion. */
function envelopeVersionOf(data: unknown): number | null {
if (!isRecord(data)) return null
const version = data.envelopeVersion
return typeof version === 'number' ? version : null
}
function reportVersionOf(data: unknown): number | null {
if (!isRecord(data)) return null
return typeof data.version === 'number' ? data.version : null
}
function snapshotMatches(snapshot: SheetSnapshot, report: Report): boolean {
return (
snapshot.ref.sheetId === report.sheet.sheetId &&
snapshot.ref.documentSha256 === report.sheet.documentSha256
)
}
/** Step 3 for a v1 envelope: wrapper schema → snapshot gate → sheet invariant. */
function readEnvelopeV1(
data: Record<string, unknown>,
report: Report,
): Wrapped {
const wrapper = EnvelopeWrapperSchema.safeParse(data)
if (!wrapper.success) return { snapshotRejected: 'schema' }
let snapshot: SheetSnapshot
try {
snapshot = assertSnapshot(data.sheetSnapshot)
} catch (error) {
if (error instanceof SnapshotError) {
return { snapshotRejected: error.reason }
}
throw error
}
if (!snapshotMatches(snapshot, report)) {
return { snapshotRejected: 'sheet_mismatch' }
}
return {
archive: {
format: wrapper.data.format,
envelopeVersion: wrapper.data.envelopeVersion,
exportedAt: wrapper.data.exportedAt,
locale: wrapper.data.locale,
report,
sheetSnapshot: snapshot,
branding: wrapper.data.branding,
labels: wrapper.data.labels,
},
}
}
/**
* Reads the JSON of a PDF attachment of any supported shape: bare Report v2
* or v3, or an archive envelope. The report is parsed first and always
* returned (`readReportDocument` throws UnsupportedReportVersionError for an
* unknown report version); the envelope is accepted whole or dropped with
* `snapshotRejected`.
*/
export function readArchiveDocument(
data: unknown,
map: ReportMigrationMap,
): ArchiveReadOutcome {
const envelopeVersion = envelopeVersionOf(data)
const reportData =
envelopeVersion !== null ? (data as Record<string, unknown>).report : data
const outcome = readReportDocument(reportData, map)
const migrated = reportVersionOf(reportData) !== REPORT_VERSION
const base: ArchiveReadOutcome = {
report: outcome.report,
origin: migrated ? 'v2' : 'bare_v3',
migrated,
unresolvedZones: outcome.unresolvedZones,
unresolvedFindings: outcome.unresolvedFindings,
archive: null,
}
if (envelopeVersion === null) return base
if (envelopeVersion !== ENVELOPE_VERSION) {
return { ...base, snapshotRejected: 'unsupported_envelope' }
}
const wrapped = readEnvelopeV1(
data as Record<string, unknown>,
outcome.report,
)
return 'archive' in wrapped
? { ...base, origin: 'envelope_v1', archive: wrapped.archive }
: { ...base, origin: 'envelope_v1', ...wrapped }
}
@@ -0,0 +1,4 @@
export * from './snapshot'
export * from './branding'
export * from './labels'
export * from './envelope'
@@ -0,0 +1,57 @@
import { z } from 'zod'
/**
* The static strings the PDF engine prints (section headings, metadata,
* severities, sides, footer credits), in both locales, frozen into the
* archive so a re-export renders the wording of the day. Exactly the dict
* keys apps/app/src/pdf read when Step 6 started.
*/
export const PDF_LABEL_KEYS = [
'pdf.empty',
'pdf.eyebrow.observation',
'pdf.eyebrow.synthesis',
'pdf.owner_prefix',
'pdf.section.comment',
'pdf.section.conclusion',
'pdf.section.findings_prefix',
'pdf.section.free_findings',
'pdf.section.next_appointment',
'pdf.section.recommendations',
'pdf.section.severity',
'pdf.section.zones',
'pdf.siret_prefix',
'pdf.subject',
'pdf.title.conclusion',
'pdf.title.suffix.bilan',
'pdf.view.detail_prefix',
'pdf.view.general',
'severity.mild',
'severity.moderate',
'severity.severe',
'lateral.left',
'lateral.right',
'footer.powered_by',
'footer.in_partnership',
] as const
export type PdfLabelKey = (typeof PDF_LABEL_KEYS)[number]
export type PdfLabels = Record<PdfLabelKey, string>
export interface PdfLabelSet {
fr: PdfLabels
en: PdfLabels
}
const labelShape = Object.fromEntries(
PDF_LABEL_KEYS.map((key) => [key, z.string().max(256)]),
) as Record<PdfLabelKey, z.ZodString>
export const PdfLabelsSchema: z.ZodType<PdfLabels> = z
.object(labelShape)
.strict()
/** Strict: every key present in both locales, no extra key. */
export const PdfLabelSetSchema: z.ZodType<PdfLabelSet> = z
.object({ fr: PdfLabelsSchema, en: PdfLabelsSchema })
.strict()
@@ -0,0 +1,425 @@
import { z } from 'zod'
import {
AnatomicalSheetDocumentSchema,
type AnatomicalSheetDocument,
type FindingCategory,
type FindingNode,
type FindingZone,
type SheetView,
} from '../anatomical-sheet/schema'
import { validateSheetDocument } from '../anatomical-sheet/validate'
import type { SheetIndexSource } from '../anatomical-sheet/sheet-index'
import { SheetRefSchema, type Report, type SheetRef } from '../report/v3'
/**
* The sheet a report archive carries so an old bilan re-renders without the
* current catalog (STEP6 §2.2). The snapshot keeps the shape the renderer and
* the sheet index consume: a valid, lean `AnatomicalSheetDocument` (every
* view, annotation, category and region; finding trees pruned to the paths
* the report uses; bibliography emptied) plus the SVG text of every asset a
* view reaches. `assertSnapshot` is the single gate an imported snapshot
* passes (STEP6 §15 caps, integrity, reachable assets).
*/
const SHA256_PATTERN = /^[0-9a-f]{64}$/
const MIB = 1024 * 1024
/** Hard limits on an imported snapshot; every excess is a `caps` rejection. */
export const SNAPSHOT_CAPS = {
views: 64,
annotations: 1024,
findingNodes: 8192,
findingDepth: 8,
labelChars: 512,
assets: 4,
assetBytes: 2 * MIB,
assetsTotalBytes: 6 * MIB,
} as const
export type SheetSnapshotRef = SheetRef & {
schemaVersion: number
speciesId: string
}
export interface SheetSnapshotAsset {
svgAssetId: string
/** Content address from the seed manifest; a provenance pointer, not a tamper check. */
sha256: string | null
svg: string
}
export interface SheetSnapshot {
status: 'draft' | 'published'
ref: SheetSnapshotRef
/** Lean, valid document (schema v2, strict). */
document: AnatomicalSheetDocument
assets: SheetSnapshotAsset[]
}
export const SheetSnapshotRefSchema: z.ZodType<SheetSnapshotRef> =
SheetRefSchema.extend({
schemaVersion: z.number().int().positive(),
speciesId: z.string().min(1),
}).strict()
const SheetSnapshotAssetSchema = z
.object({
svgAssetId: z.string().uuid(),
sha256: z.string().regex(SHA256_PATTERN).nullable(),
svg: z.string().max(SNAPSHOT_CAPS.assetBytes),
})
.strict()
/** Shape tier only: caps beyond the schema and integrity live in assertSnapshot. */
export const SheetSnapshotSchema: z.ZodType<
SheetSnapshot,
z.ZodTypeDef,
unknown
> = z
.object({
status: z.enum(['draft', 'published']),
ref: SheetSnapshotRefSchema,
document: AnatomicalSheetDocumentSchema,
assets: z.array(SheetSnapshotAssetSchema).max(SNAPSHOT_CAPS.assets),
})
.strict()
/** What a loaded sheet provides to build a snapshot from. */
export interface SnapshotSource {
status: 'draft' | 'published'
ref: SheetRef
speciesId: string
schemaVersion: number
document: AnatomicalSheetDocument
/** SVG text by `svg_asset_id`. */
assets: Readonly<Record<string, string>>
/** sha256 by `svg_asset_id` (seed manifest); absent → null in the snapshot. */
assetHashes?: Readonly<Record<string, string>>
}
export type SnapshotRejection =
| 'unsupported_envelope'
| 'schema'
| 'caps'
| 'integrity'
| 'sheet_mismatch'
/** Thrown by assertSnapshot; `reason` is what the import reports. */
export class SnapshotError extends Error {
constructor(
public readonly reason: SnapshotRejection,
detail: string,
) {
super(`snapshot rejected (${reason}): ${detail}`)
this.name = 'SnapshotError'
}
}
/** Own-key lookup: ids come from documents (`__proto__` is not an entry). */
function own<T>(
record: Readonly<Record<string, T>>,
key: string,
): T | undefined {
return Object.hasOwn(record, key) ? record[key] : undefined
}
/** The asset a view draws: its own, else the first one up its parent chain. */
function assetOfView(
view: SheetView,
views: ReadonlyMap<string, SheetView>,
): string | null {
const visited = new Set<string>()
let current: SheetView | undefined = view
while (current && !visited.has(current.id)) {
if (current.svg_asset_id !== null) return current.svg_asset_id
visited.add(current.id)
current =
current.kind === 'detail' ? views.get(current.parent_view_id) : undefined
}
return null
}
/** Asset ids reachable from the views, in view order, each once. */
function reachableAssetIds(document: AnatomicalSheetDocument): string[] {
const views = new Map(document.views.map((v) => [v.id, v]))
const ids: string[] = []
for (const view of document.views) {
const id = assetOfView(view, views)
if (id !== null && !ids.includes(id)) ids.push(id)
}
return ids
}
// ---------------------------------------------------------------------------
// Build
/** Finding paths of the report grouped by zone, resolved and unresolved alike. */
function pathsByZone(report: Report): Map<string, string[][]> {
const byZone = new Map<string, string[][]>()
for (const observation of report.observations) {
for (const finding of observation.findings) {
const paths = byZone.get(finding.findingZoneId) ?? []
paths.push(finding.path)
byZone.set(finding.findingZoneId, paths)
}
}
return byZone
}
/** Keeps, in document order, the nodes at `depth` of some path and their used descendants. */
function pruneNodes(
nodes: readonly FindingNode[],
paths: readonly string[][],
depth: number,
): FindingNode[] {
return nodes
.filter((node) => paths.some((path) => path[depth] === node.id))
.map((node) => ({
id: node.id,
name: { ...node.name },
description: {},
requires_vet_referral: node.requires_vet_referral,
reference_ids: [],
review_status: node.review_status,
children: pruneNodes(
node.children,
paths.filter((path) => path[depth] === node.id),
depth + 1,
),
}))
}
function pruneCategories(
categories: readonly FindingCategory[],
paths: readonly string[][],
): FindingCategory[] {
return categories
.filter((category) => paths.some((path) => path[0] === category.id))
.map((category) => ({
id: category.id,
kind: category.kind,
name: { ...category.name },
description: {},
reference_ids: [],
review_status: category.review_status,
children: pruneNodes(
category.children,
paths.filter((path) => path[0] === category.id),
1,
),
}))
}
function pruneZone(zone: FindingZone, paths: readonly string[][]): FindingZone {
return {
id: zone.id,
name: { ...zone.name },
categories: pruneCategories(zone.categories, paths),
}
}
function leanDocument(
document: AnatomicalSheetDocument,
report: Report,
): AnatomicalSheetDocument {
const used = pathsByZone(report)
return {
schema_version: document.schema_version,
species_id: document.species_id,
name: structuredClone(document.name),
description: structuredClone(document.description),
scope_disclaimer: structuredClone(document.scope_disclaimer),
attribution: structuredClone(document.attribution),
vertebral_config: structuredClone(document.vertebral_config),
references: [],
categories: structuredClone(document.categories),
views: structuredClone(document.views),
annotations: structuredClone(document.annotations),
finding_zones: document.finding_zones.map((zone) =>
pruneZone(zone, used.get(zone.id) ?? []),
),
}
}
function snapshotAssets(sheet: SnapshotSource): SheetSnapshotAsset[] {
const assets: SheetSnapshotAsset[] = []
for (const svgAssetId of reachableAssetIds(sheet.document)) {
const svg = own(sheet.assets, svgAssetId)
if (svg === undefined) continue
const sha256 = sheet.assetHashes
? (own(sheet.assetHashes, svgAssetId) ?? null)
: null
assets.push({ svgAssetId, sha256, svg })
}
return assets
}
/**
* The snapshot of `sheet` a given report needs: pure, deterministic
* (document order everywhere), inputs untouched. Finding trees keep only the
* categories and nodes on a path some finding of the report names, as far as
* those nodes exist; a missing asset is left out and caught by assertSnapshot.
*/
export function buildSheetSnapshot(
sheet: SnapshotSource,
report: Report,
): SheetSnapshot {
return {
status: sheet.status,
ref: {
sheetId: sheet.ref.sheetId,
versionId: sheet.ref.versionId,
documentSha256: sheet.ref.documentSha256,
schemaVersion: sheet.schemaVersion,
speciesId: sheet.speciesId,
},
document: leanDocument(sheet.document, report),
assets: snapshotAssets(sheet),
}
}
// ---------------------------------------------------------------------------
// Assert
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function childrenOf(node: unknown): unknown[] {
if (!isRecord(node)) return []
const children = node.children
return Array.isArray(children) ? children : []
}
/**
* Depth of the finding trees, checked on the raw input before Zod recurses
* into it (an attacker-sized tree must not drive the parser). Iterative:
* an explicit stack of (node, depth) pairs, categories at depth 1.
*/
function assertFindingDepth(input: unknown): void {
if (!isRecord(input) || !isRecord(input.document)) return
const zones = input.document.finding_zones
if (!Array.isArray(zones)) return
const stack: Array<[unknown, number]> = []
for (const zone of zones) {
if (!isRecord(zone) || !Array.isArray(zone.categories)) continue
for (const category of zone.categories) stack.push([category, 1])
}
while (stack.length > 0) {
const [node, depth] = stack.pop()!
if (depth > SNAPSHOT_CAPS.findingDepth) {
throw new SnapshotError(
'caps',
`finding depth over ${SNAPSHOT_CAPS.findingDepth}`,
)
}
for (const child of childrenOf(node)) stack.push([child, depth + 1])
}
}
function countFindingNodes(document: AnatomicalSheetDocument): number {
let count = 0
const stack: Array<FindingCategory | FindingNode> =
document.finding_zones.flatMap((zone) => zone.categories)
while (stack.length > 0) {
count += 1
stack.push(...stack.pop()!.children)
}
return count
}
/**
* Longest `name` label (`fr` or `en`) anywhere in the document: sheet, views,
* annotations, categories, regions, finding zones and nodes. Free texts
* (`description`, `scope_disclaimer`) are not labels and carry no cap here.
*/
function longestName(document: AnatomicalSheetDocument): number {
let longest = 0
const stack: unknown[] = [document]
while (stack.length > 0) {
const value = stack.pop()
if (Array.isArray(value)) stack.push(...value)
if (!isRecord(value)) continue
const name = value.name
if (isRecord(name)) {
for (const key of ['fr', 'en']) {
const text = name[key]
if (typeof text === 'string') longest = Math.max(longest, text.length)
}
}
stack.push(...Object.values(value))
}
return longest
}
function utf8Length(text: string): number {
return new TextEncoder().encode(text).byteLength
}
function assertCaps(snapshot: SheetSnapshot): void {
const over = (what: string) => new SnapshotError('caps', `${what} over cap`)
const { document, assets } = snapshot
if (document.views.length > SNAPSHOT_CAPS.views) throw over('views')
if (document.annotations.length > SNAPSHOT_CAPS.annotations) {
throw over('annotations')
}
if (countFindingNodes(document) > SNAPSHOT_CAPS.findingNodes) {
throw over('finding nodes')
}
if (longestName(document) > SNAPSHOT_CAPS.labelChars) throw over('label')
if (assets.length > SNAPSHOT_CAPS.assets) throw over('assets')
const sizes = assets.map((asset) => utf8Length(asset.svg))
if (sizes.some((size) => size > SNAPSHOT_CAPS.assetBytes)) throw over('asset')
const total = sizes.reduce((sum, size) => sum + size, 0)
if (total > SNAPSHOT_CAPS.assetsTotalBytes) throw over('assets total')
}
function assertIntegrity(snapshot: SheetSnapshot): void {
const errors = validateSheetDocument(snapshot.document).filter(
(issue) => issue.severity === 'error',
)
if (errors.length > 0) {
throw new SnapshotError('integrity', errors[0]!.code)
}
const present = new Set(snapshot.assets.map((asset) => asset.svgAssetId))
const views = new Map(snapshot.document.views.map((v) => [v.id, v]))
for (const view of snapshot.document.views) {
const assetId = assetOfView(view, views)
if (assetId === null || !present.has(assetId)) {
throw new SnapshotError('integrity', `view "${view.id}" reaches no asset`)
}
}
}
/**
* The single gate of an imported snapshot, in this order: finding depth on
* the raw input → shape (`schema`) → caps (§15) → sheet integrity rules and
* every view reaching an asset carried by the snapshot (`integrity`).
* Returns the parsed snapshot; throws SnapshotError with the reason.
*/
export function assertSnapshot(snapshot: unknown): SheetSnapshot {
assertFindingDepth(snapshot)
const parsed = SheetSnapshotSchema.safeParse(snapshot)
if (!parsed.success) {
throw new SnapshotError(
'schema',
parsed.error.issues[0]?.message ?? 'invalid',
)
}
assertCaps(parsed.data)
assertIntegrity(parsed.data)
return parsed.data
}
/** Adapter: a snapshot as the sheet index reads it (assets array → record). */
export function snapshotIndexSource(
snapshot: SheetSnapshot,
): SheetIndexSource & { ref: SheetSnapshotRef } {
return {
ref: snapshot.ref,
document: snapshot.document,
assets: Object.fromEntries(
snapshot.assets.map((asset) => [asset.svgAssetId, asset.svg]),
),
}
}
@@ -0,0 +1,3 @@
export * from './anatomical-sheet'
export * from './report'
export * from './archive'
@@ -0,0 +1,37 @@
import { z } from 'zod'
/**
* Identity snapshots carried by every report version: who wrote it, on
* which animal, for which owner. Copied into the report at creation so a
* report stays readable when the underlying records change (BDR-010).
*/
export const PractitionerSchema = z.object({
name: z.string().min(1),
cabinet: z.string().optional(),
contact: z.string().optional(),
/** SIRET, 14-digit French business identifier (not validated). */
siret: z.string().optional(),
})
export type Practitioner = z.infer<typeof PractitionerSchema>
export const AnimalSchema = z.object({
/** Species of the animal; the sheet the report references matches it. */
speciesId: z.string().min(1),
name: z.string().min(1),
breed: z.string().optional(),
age: z.string().optional(),
})
export type Animal = z.infer<typeof AnimalSchema>
export const OwnerSchema = z.object({ name: z.string().min(1) })
export type Owner = z.infer<typeof OwnerSchema>
export const NextAppointmentSchema = z.discriminatedUnion('kind', [
z.object({ kind: z.literal('date'), date: z.string() }),
z.object({ kind: z.literal('period'), text: z.string() }),
])
export type NextAppointment = z.infer<typeof NextAppointmentSchema>
export const LateralSideSchema = z.enum(['left', 'right'])
export type LateralSide = z.infer<typeof LateralSideSchema>
@@ -0,0 +1,32 @@
export * from './identity'
export * from './v3'
export {
FindingV2Schema,
ObservationV2Schema,
ObservationZoneV2Schema,
ReportV2Schema,
SeverityV2Schema,
VertebraV2Schema,
VertebralRegionV2Schema,
type FindingV2,
type ObservationV2,
type ObservationZoneV2,
type ReportV2,
type SeverityV2,
} from './v2'
export {
ReportMigrationMapSchema,
findingPathKey,
type ReportMigrationMap,
} from './migration-map'
export {
migrateReportV2ToV3,
readReportDocument,
UnsupportedReportVersionError,
type MigrationOutcome,
} from './migrate'
export {
rebaseReportOnSheet,
type RebaseIndex,
type RebaseOutcome,
} from './rebase'
@@ -0,0 +1,167 @@
import { findingPathKey, type ReportMigrationMap } from './migration-map'
import {
ReportV2Schema,
type FindingV2,
type ObservationV2,
type ObservationZoneV2,
type ReportV2,
type SeverityV2,
} from './v2'
import {
REPORT_VERSION,
ReportSchema,
type Finding,
type Observation,
type Report,
type ReportZone,
type Severity,
} from './v3'
/**
* Lifts a Report v2 (PDF attachment or sessionStorage draft of the deployed
* application) to v3 against the migration map of the reference sheet.
* Never throws on content: a zone or finding the map cannot place is kept
* verbatim with its snapshots and flagged `unresolved`, so the practitioner's
* data survives any catalog change and stays identifiable.
*/
/** Own-key lookup: ids come from untrusted documents (`__proto__` is not an entry). */
function own<T>(record: Record<string, T>, key: string): T | undefined {
return Object.hasOwn(record, key) ? record[key] : undefined
}
const SEVERITY: Record<SeverityV2, Severity> = {
légère: 'mild',
modérée: 'moderate',
sévère: 'severe',
}
export interface MigrationOutcome {
report: Report
/** Zones whose legacy id has no annotation in the map. */
unresolvedZones: number
/** Findings whose legacy path no longer exists in the sheet. */
unresolvedFindings: number
}
function migrateZone(
zone: ObservationZoneV2,
map: ReportMigrationMap,
): ReportZone {
const entry = own(map.annotations, zone.boneId)
const viewId = zone.detailSourceId
? (own(map.views, zone.detailSourceId) ?? zone.detailSourceId)
: map.main_view_id
const out: ReportZone = { annotationId: entry?.id ?? zone.boneId, viewId }
if (zone.side) out.side = zone.side
if (zone.vertebrae) out.vertebrae = zone.vertebrae.map((v) => ({ ...v }))
if (entry) {
out.labelFrSnapshot = entry.name.fr
out.labelEnSnapshot = entry.name.en
} else {
out.unresolved = true
}
return out
}
function migrateFinding(finding: FindingV2, map: ReportMigrationMap): Finding {
const mapped = own(
map.finding_paths,
findingPathKey(finding.zoneId, finding.path),
)
const out: Finding = {
findingZoneId: finding.zoneId,
path: [...finding.path],
labelFrSnapshot: finding.labelFrSnapshot,
labelEnSnapshot: finding.labelEnSnapshot,
}
if (finding.requiresVetReferral) out.requiresVetReferral = true
if (finding.side) out.side = finding.side
if (typeof mapped === 'string') {
const [zoneId, ...path] = mapped.split('/')
out.findingZoneId = zoneId!
out.path = path
} else {
// null = removed by curation; undefined = never part of the legacy catalog.
out.unresolved = true
}
return out
}
function migrateObservation(
obs: ObservationV2,
map: ReportMigrationMap,
): Observation {
const out: Observation = {
id: obs.id,
zones: obs.zones.map((z) => migrateZone(z, map)),
findings: obs.findings.map((f) => migrateFinding(f, map)),
freeTextFindings: [...obs.freeTextFindings],
comment: obs.comment,
}
if (obs.severity) out.severity = SEVERITY[obs.severity]
return out
}
export function migrateReportV2ToV3(
report: ReportV2,
map: ReportMigrationMap,
): MigrationOutcome {
const observations = report.observations.map((o) =>
migrateObservation(o, map),
)
const migrated: Report = {
version: REPORT_VERSION,
id: report.id,
createdAt: report.createdAt,
date: report.date,
practitioner: report.practitioner,
animal: report.animal,
owner: report.owner,
sheet: { ...map.sheet },
observations,
conclusion: report.conclusion,
recommendations: report.recommendations,
localAnnotations: [],
}
if (report.nextAppointment) migrated.nextAppointment = report.nextAppointment
const zones = observations.flatMap((o) => o.zones)
const findings = observations.flatMap((o) => o.findings)
return {
report: ReportSchema.parse(migrated),
unresolvedZones: zones.filter((z) => z.unresolved).length,
unresolvedFindings: findings.filter((f) => f.unresolved).length,
}
}
/** Thrown for a report whose version this code cannot read. */
export class UnsupportedReportVersionError extends Error {
constructor(public readonly foundVersion: number | null) {
super(`unsupported report version: ${foundVersion ?? 'unknown'}`)
this.name = 'UnsupportedReportVersionError'
}
}
function versionOf(data: unknown): number | null {
if (data === null || typeof data !== 'object') return null
const v = (data as { version?: unknown }).version
return typeof v === 'number' ? v : null
}
/**
* Reads a report document of any supported version (2 or 3) and returns it
* as v3. Zod errors propagate: a document of a known version that does not
* parse is corrupt, not old.
*/
export function readReportDocument(
data: unknown,
map: ReportMigrationMap,
): MigrationOutcome {
const version = versionOf(data)
if (version === REPORT_VERSION) {
const report = ReportSchema.parse(data)
return { report, unresolvedZones: 0, unresolvedFindings: 0 }
}
if (version === 2) return migrateReportV2ToV3(ReportV2Schema.parse(data), map)
throw new UnsupportedReportVersionError(version)
}
@@ -0,0 +1,40 @@
import { z } from 'zod'
import { SheetRefSchema } from './v3'
/**
* Correspondence between the legacy identifiers a Report v2 carries and the
* canonical sheet a Report v3 references. Generated by the curation pipeline
* (`draft/report-migration-map.json`), never written by hand: annotations
* come from the legacy id map, finding paths from the applier's rename and
* removal records. A `null` finding path means "removed from the sheet":
* the migration keeps the finding with its snapshots and flags it.
*/
const LocalizedNameSchema = z.object({ fr: z.string(), en: z.string() })
export const ReportMigrationMapSchema = z.object({
schema_version: z.literal(1),
sheet: SheetRefSchema,
/** Id of the view a v2 zone without `detailSourceId` belongs to. */
main_view_id: z.string().min(1),
/** Legacy detail popup key → view id. */
views: z.record(z.string(), z.string().min(1)),
/** Legacy `data-anno-id` → annotation id and the legacy labels. */
annotations: z.record(
z.string(),
z.object({ id: z.string().min(1), name: LocalizedNameSchema }),
),
/**
* `<zoneId>/<path segments joined by '/'>` of every legacy finding node →
* the same key in the sheet, or null when the node was removed.
*/
finding_paths: z.record(z.string(), z.string().nullable()),
})
export type ReportMigrationMap = z.infer<typeof ReportMigrationMapSchema>
export function findingPathKey(
zoneId: string,
path: readonly string[],
): string {
return `${zoneId}/${path.join('/')}`
}
@@ -0,0 +1,137 @@
import type {
SheetIndex,
SheetIndexSource,
} from '../anatomical-sheet/sheet-index'
import type { Annotation, LocalizedText } from '../anatomical-sheet/schema'
import type { SheetSnapshot } from '../archive/snapshot'
import {
ReportSchema,
type Finding,
type Observation,
type Report,
type ReportZone,
type SheetRef,
} from './v3'
/**
* Moves an imported report onto the sheet the application has loaded
* (STEP6 §3.5). A report written on another revision of the sheet keeps
* every datum: a zone or finding the loaded sheet no longer holds is flagged
* `unresolved`, its labels taken from the archived snapshot when the report
* carries none, and the report now references the loaded sheet. Nothing
* happens when the report already sits on the loaded sheet.
*/
/** An index whose source names its sheet (a loaded sheet or a snapshot). */
export type RebaseIndex = SheetIndex<SheetIndexSource & { ref: SheetRef }>
export interface RebaseOutcome {
report: Report
/** Zones and findings newly flagged by this rebase. */
unresolvedZones: number
unresolvedFindings: number
rebased: boolean
}
interface Counters {
zones: number
findings: number
}
/** The name the archived snapshot gives an annotation (a trigger: its view's). */
function archivedName(
archived: SheetSnapshot | null,
annotationId: string,
): LocalizedText | undefined {
if (!archived) return undefined
const annotation: Annotation | undefined = archived.document.annotations.find(
(a) => a.id === annotationId,
)
if (!annotation) return undefined
if (annotation.kind !== 'detail_trigger') return annotation.name
const view = archived.document.views.find(
(v) => v.id === annotation.opens_view_id,
)
return annotation.name ?? view?.name
}
function flagZone(
zone: ReportZone,
archived: SheetSnapshot | null,
): ReportZone {
const out: ReportZone = { ...zone, unresolved: true }
const name = archivedName(archived, zone.annotationId)
if (name) {
out.labelFrSnapshot ??= name.fr
out.labelEnSnapshot ??= name.en
}
return out
}
function rebaseZone(
zone: ReportZone,
index: RebaseIndex,
archived: SheetSnapshot | null,
counters: Counters,
): ReportZone {
if (zone.unresolved) return { ...zone }
const known =
index.annotation(zone.annotationId) !== undefined &&
index.view(zone.viewId) !== undefined
if (known) return { ...zone }
counters.zones += 1
return flagZone(zone, archived)
}
function rebaseFinding(
finding: Finding,
index: RebaseIndex,
counters: Counters,
): Finding {
if (finding.unresolved) return { ...finding }
if (index.nodeAt(finding.findingZoneId, finding.path)) return { ...finding }
counters.findings += 1
return { ...finding, unresolved: true }
}
function rebaseObservation(
observation: Observation,
index: RebaseIndex,
archived: SheetSnapshot | null,
counters: Counters,
): Observation {
return {
...observation,
zones: observation.zones.map((z) =>
rebaseZone(z, index, archived, counters),
),
findings: observation.findings.map((f) =>
rebaseFinding(f, index, counters),
),
}
}
export function rebaseReportOnSheet(
report: Report,
index: RebaseIndex,
archived: SheetSnapshot | null,
): RebaseOutcome {
if (report.sheet.documentSha256 === index.sheet.ref.documentSha256) {
return { report, unresolvedZones: 0, unresolvedFindings: 0, rebased: false }
}
const counters: Counters = { zones: 0, findings: 0 }
const { sheetId, versionId, documentSha256 } = index.sheet.ref
const rebased: Report = {
...report,
sheet: { sheetId, versionId, documentSha256 },
observations: report.observations.map((o) =>
rebaseObservation(o, index, archived, counters),
),
}
return {
report: ReportSchema.parse(rebased),
unresolvedZones: counters.zones,
unresolvedFindings: counters.findings,
rebased: true,
}
}
@@ -0,0 +1,72 @@
import { z } from 'zod'
import {
AnimalSchema,
LateralSideSchema,
NextAppointmentSchema,
OwnerSchema,
PractitionerSchema,
} from './identity'
/**
* Report document version 2, exactly as the deployed application wrote it
* (PDF attachments of the practitioner's archive, sessionStorage drafts).
* Kept as an INPUT format only: nothing writes v2 any more, `migrate.ts`
* lifts it to v3. Field comments describe the legacy meaning.
*/
export const SeverityV2Schema = z.enum(['légère', 'modérée', 'sévère'])
export type SeverityV2 = z.infer<typeof SeverityV2Schema>
export const VertebralRegionV2Schema = z.enum(['C', 'T', 'L', 'S', 'Cd'])
export const VertebraV2Schema = z.object({
region: VertebralRegionV2Schema,
index: z.number().int().positive(),
})
export const ObservationZoneV2Schema = z.object({
/** The legacy SVG `data-anno-id` (e.g. `point-mpbwtst0`). */
boneId: z.string().min(1),
/** Legacy detail popup key (`head`) when the zone came from that view. */
detailSourceId: z.string().optional(),
vertebrae: z.array(VertebraV2Schema).optional(),
side: LateralSideSchema.optional(),
})
export type ObservationZoneV2 = z.infer<typeof ObservationZoneV2Schema>
export const FindingV2Schema = z.object({
/** Legacy catalog zone key (equal to the canonical finding zone id). */
zoneId: z.string().min(1),
/** Node ids from the zone's categories down to the leaf. */
path: z.array(z.string().min(1)).min(1),
labelFrSnapshot: z.string().min(1),
labelEnSnapshot: z.string().min(1),
requiresVetReferral: z.boolean().optional(),
side: LateralSideSchema.optional(),
})
export type FindingV2 = z.infer<typeof FindingV2Schema>
export const ObservationV2Schema = z.object({
id: z.string().min(1),
zones: z.array(ObservationZoneV2Schema),
findings: z.array(FindingV2Schema),
freeTextFindings: z.array(z.string()),
severity: SeverityV2Schema.optional(),
comment: z.string(),
})
export type ObservationV2 = z.infer<typeof ObservationV2Schema>
export const ReportV2Schema = z.object({
version: z.literal(2),
id: z.string().min(1),
createdAt: z.string(),
date: z.string(),
practitioner: PractitionerSchema,
animal: AnimalSchema,
owner: OwnerSchema,
observations: z.array(ObservationV2Schema),
conclusion: z.string(),
recommendations: z.string(),
nextAppointment: NextAppointmentSchema.optional(),
})
export type ReportV2 = z.infer<typeof ReportV2Schema>
@@ -0,0 +1,97 @@
import { z } from 'zod'
import {
AnimalSchema,
LateralSideSchema,
NextAppointmentSchema,
OwnerSchema,
PractitionerSchema,
} from './identity'
/**
* Report document version 3: a report written on the canonical anatomical
* sheet. Zones name an annotation of a view of an exact sheet, findings a
* node path of a finding zone, both by stable ids; every label the report
* needs to stay readable without the sheet is snapshotted. Breaking change
* → version 4; additive optional fields keep the version.
*/
export const REPORT_VERSION = 3
export const SeveritySchema = z.enum(['mild', 'moderate', 'severe'])
export type Severity = z.infer<typeof SeveritySchema>
/** Region codes are the sheet's `vertebral_config` codes, checked at runtime. */
export const VertebraSchema = z.object({
region: z.string().min(1),
index: z.number().int().positive(),
})
export type Vertebra = z.infer<typeof VertebraSchema>
/** The sheet document a report was built on, by content. */
export const SheetRefSchema = z.object({
sheetId: z.string().min(1),
/** Database version id once the sheet lives in the database; null for a bundled draft. */
versionId: z.string().min(1).nullable(),
/** sha256 of the document file the report was written against. */
documentSha256: z.string().regex(/^[0-9a-f]{64}$/),
})
export type SheetRef = z.infer<typeof SheetRefSchema>
export const ReportZoneSchema = z.object({
annotationId: z.string().min(1),
viewId: z.string().min(1),
side: LateralSideSchema.optional(),
vertebrae: z.array(VertebraSchema).optional(),
/** Annotation name at selection time (or legacy name at migration). */
labelFrSnapshot: z.string().optional(),
labelEnSnapshot: z.string().optional(),
/** Set by the migration when the legacy id has no canonical annotation. */
unresolved: z.literal(true).optional(),
})
export type ReportZone = z.infer<typeof ReportZoneSchema>
export const FindingSchema = z.object({
findingZoneId: z.string().min(1),
/** Node ids from the zone's categories down to the leaf. */
path: z.array(z.string().min(1)).min(1),
labelFrSnapshot: z.string().min(1),
labelEnSnapshot: z.string().min(1),
requiresVetReferral: z.boolean().optional(),
side: LateralSideSchema.optional(),
/** Set by the migration when the path no longer exists in the sheet; data kept. */
unresolved: z.literal(true).optional(),
})
export type Finding = z.infer<typeof FindingSchema>
export const ObservationSchema = z.object({
id: z.string().min(1),
zones: z.array(ReportZoneSchema),
findings: z.array(FindingSchema),
freeTextFindings: z.array(z.string()),
severity: SeveritySchema.optional(),
comment: z.string(),
})
export type Observation = z.infer<typeof ObservationSchema>
export const ReportSchema = z.object({
version: z.literal(REPORT_VERSION),
id: z.string().min(1),
/** ISO timestamp of report creation. */
createdAt: z.string(),
/** ISO date of the clinical encounter. */
date: z.string(),
practitioner: PractitionerSchema,
animal: AnimalSchema,
owner: OwnerSchema,
sheet: SheetRefSchema,
observations: z.array(ObservationSchema),
conclusion: z.string(),
recommendations: z.string(),
nextAppointment: NextAppointmentSchema.optional(),
/** Reserved for report-only points (OPEN_QUESTIONS Q6); empty until defined. */
localAnnotations: z.array(z.unknown()).max(0).default([]),
})
export type Report = z.infer<typeof ReportSchema>
export type ReportInput = z.input<typeof ReportSchema>
export type { LateralSide, NextAppointment } from './identity'
+21
View File
@@ -0,0 +1,21 @@
/**
* The N-1 reader (RUST_ARCHITECTURE_REVIEW III.3 rule 7, VI.3): the Zod schemas and readers
* the last TypeScript build shipped, copied verbatim from `packages/domain/src` at develop
* 1a7ee7d (the R2 starting point) into `./domain`. Never edited: a Rust-written report, draft,
* snapshot or envelope that these readers refuse would break a rollback to that build.
* Permanent, it outlives `packages/domain` (deleted at R5).
*/
export {
ReportSchema,
ReportArchiveEnvelopeSchema,
SheetSnapshotSchema,
AnatomicalSheetDocumentSchema,
BrandingSchema,
PdfLabelSetSchema,
readArchiveDocument,
readReportDocument,
assertSnapshot,
type Report,
type ReportArchiveEnvelope,
type ReportMigrationMap,
} from './domain'
@@ -6,7 +6,7 @@
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { ReportZoneSchema, SheetRefSchema } from '@faunosteo/domain'
import { ReportZoneSchema, SheetRefSchema } from './n-1/domain'
import type { ReportZone, SheetRef } from '../types/index'
import { callCore, loadCore, type CoreModule } from '../src/index'
+7 -3
View File
@@ -23,6 +23,9 @@ importers:
'@faunosteo/anatomy':
specifier: workspace:*
version: link:../../packages/anatomy
'@faunosteo/core-wasm':
specifier: workspace:*
version: link:../../packages/core-wasm
'@faunosteo/domain':
specifier: workspace:*
version: link:../../packages/domain
@@ -147,10 +150,11 @@ importers:
version: 3.2.7(@types/node@20.19.41)(happy-dom@20.10.6)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.23.15)
packages/core-wasm:
dependencies:
zod:
specifier: ^3.24.1
version: 3.25.76
devDependencies:
'@faunosteo/domain':
specifier: workspace:*
version: link:../domain
'@types/node':
specifier: ^20.19.41
version: 20.19.41