@tellescope/sdk 2.0.0-beta.0 → 2.0.0-beta.2

package/src/tests/api_tests/enduser_fields_sync.test.ts

@@ -0,0 +1,154 @@
+require('source-map-support').install();
+
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+/**
+ * Schema round-trip for `Form.syncEnduserFieldsToEHR` and `Form.enduserFieldsSync`, the two fields
+ * behind "Sync Patient Fields to Healthie".
+ *
+ * The names are deliberately EHR-agnostic — each row's `externalId` is the question id in whichever
+ * EHR the form syncs to (`Form.externalId`) — even though only the Healthie push reads them today.
+ *
+ * What this file can and cannot cover: the actual `createFormAnswerGroup` round trip needs live
+ * Healthie credentials that no suite here has, and there is no Healthie mock or fixture layer in the
+ * repository, so the push itself is covered by the resolver's unit tests
+ * (api/modules/forms.test.ts) plus manual QA against Healthie staging. What IS covered here is
+ * everything the API owns: that the fields persist and read back unchanged, that validation rejects
+ * malformed rows, and — the one that guards a real decision in the form-editor modal — that an
+ * update with `replaceObjectFields` actually SHRINKS the list rather than merging into it, which is
+ * what makes deleting a mapping row persist.
+ */
+export const enduser_fields_sync_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  /** records a check that the given write is rejected (any 4xx), not silently accepted */
+  const record_rejected = async (label: string, write: () => Promise<any>) => {
+    try {
+      const accepted = await write()
+      record(label, false, `accepted, expected a validation error — got ${JSON.stringify(accepted?.enduserFieldsSync)}`)
+    } catch (err: any) {
+      const message = err?.message || String(err)
+      record(label, true, `rejected: ${message.slice(0, 200)}`)
+    }
+  }
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({ name: `FieldSync ${RAND()}`, users: [{ isAdmin: true }], apiKeys: 0 })
+    const sdk = tenant.sdk
+
+    const TWO_ROWS = [
+      { field: 'dateOfBirth', externalId: '111111' },
+      { field: 'Referring Provider', externalId: '222222' },
+    ]
+
+    /* ===== 1. Create with both fields set, and read them back ===== */
+    const created = await sdk.api.forms.createOne({
+      title: `Field sync ${RAND()}`,
+      externalId: 'healthie-form-id',
+      syncEnduserFieldsToEHR: true,
+      enduserFieldsSync: TWO_ROWS,
+    })
+    const readBack = await sdk.api.forms.getOne(created.id)
+
+    record('1: create persists syncEnduserFieldsToEHR', readBack.syncEnduserFieldsToEHR === true,
+      `got ${JSON.stringify(readBack.syncEnduserFieldsToEHR)}`)
+    record('1: create persists enduserFieldsSync verbatim',
+      JSON.stringify(readBack.enduserFieldsSync) === JSON.stringify(TWO_ROWS),
+      `got ${JSON.stringify(readBack.enduserFieldsSync)} expected ${JSON.stringify(TWO_ROWS)}`)
+
+    /* ===== 2. replaceObjectFields must SHRINK the list, not merge into it =====
+       This is the guard for the form-editor modal's `replaceObjectFields` change. Without it,
+       deleting a mapping row in the UI would save and then silently come back on reload. */
+    const ONE_ROW = [{ field: 'insurance.memberId', externalId: '333333' }]
+    await sdk.api.forms.updateOne(created.id, { enduserFieldsSync: ONE_ROW }, { replaceObjectFields: true })
+    const shrunk = await sdk.api.forms.getOne(created.id)
+
+    record('2: replaceObjectFields shrinks a two-row list to one row',
+      JSON.stringify(shrunk.enduserFieldsSync) === JSON.stringify(ONE_ROW),
+      `got ${JSON.stringify(shrunk.enduserFieldsSync)} expected ${JSON.stringify(ONE_ROW)}`)
+
+    /* ===== 3. Malformed rows are rejected ===== */
+    await record_rejected('3: a row with a non-string field is rejected', () =>
+      sdk.api.forms.updateOne(created.id, { enduserFieldsSync: [{ field: 1, externalId: '1' }] } as any,
+        { replaceObjectFields: true }))
+
+    await record_rejected('3: a row missing externalId is rejected', () =>
+      sdk.api.forms.updateOne(created.id, { enduserFieldsSync: [{ field: 'fname' }] } as any,
+        { replaceObjectFields: true }))
+
+    await record_rejected('3: an externalId over 100 characters is rejected', () =>
+      sdk.api.forms.updateOne(created.id,
+        { enduserFieldsSync: [{ field: 'fname', externalId: 'x'.repeat(101) }] },
+        { replaceObjectFields: true }))
+
+    // a rejected write must not have partially applied - the one-row list from step 2 stands
+    const afterRejections = await sdk.api.forms.getOne(created.id)
+    record('3: rejected writes leave the stored list untouched',
+      JSON.stringify(afterRejections.enduserFieldsSync) === JSON.stringify(ONE_ROW),
+      `got ${JSON.stringify(afterRejections.enduserFieldsSync)} expected ${JSON.stringify(ONE_ROW)}`)
+
+    /* ===== 4. An empty list is accepted (clearing every row) ===== */
+    try {
+      await sdk.api.forms.updateOne(created.id, { enduserFieldsSync: [] }, { replaceObjectFields: true })
+      const cleared = await sdk.api.forms.getOne(created.id)
+      const rows = cleared.enduserFieldsSync
+      record('4: an empty list is accepted and clears the mapping',
+        Array.isArray(rows) && rows.length === 0,
+        `got ${JSON.stringify(rows)}`)
+    } catch (err: any) {
+      record('4: an empty list is accepted and clears the mapping', false,
+        `rejected: ${(err?.message || String(err)).slice(0, 200)}`)
+    }
+
+    /* ===== 5. Backward compatibility: a form that sets neither field reads back with neither ===== */
+    const plain = await sdk.api.forms.createOne({ title: `No field sync ${RAND()}` })
+    const plainReadBack = await sdk.api.forms.getOne(plain.id)
+
+    record('5: a form created without either field has no syncEnduserFieldsToEHR',
+      plainReadBack.syncEnduserFieldsToEHR === undefined,
+      `got ${JSON.stringify(plainReadBack.syncEnduserFieldsToEHR)}`)
+    record('5: a form created without either field has no enduserFieldsSync',
+      plainReadBack.enduserFieldsSync === undefined,
+      `got ${JSON.stringify(plainReadBack.enduserFieldsSync)}`)
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which skips pending finallys and
+    // would strand the provisioned tenant permanently.
+    if (tenant) { try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) } }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const enduser_fields_sync_tests = async () => {
+  assert_checks('Enduser fields sync schema round-trip', await enduser_fields_sync_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Enduser fields sync schema round-trip', run: enduser_fields_sync_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  enduser_fields_sync_tests()
+    .then(() => {
+      console.log("✅ enduser fields sync test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ enduser fields sync test suite failed:", error)
+      process.exit(1)
+    })
+}

package/src/tests/api_tests/enduser_observations_auto_review.test.ts

@@ -5,6 +5,7 @@ import {
   assert_checks,
   Check,
   setup_isolated_tenant,
+  IsolatedSuite,
 } from "../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
@@ -343,6 +344,9 @@ export const enduser_observations_auto_review_tests = async () => {
   assert_checks('Vital auto-review on create', await enduser_observations_auto_review_checks())
 }
 
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Vital auto-review on create', run: enduser_observations_auto_review_checks }
+
 // Allow running this test file independently
 if (require.main === module) {
   console.log(`🌐 Using API URL: ${host}`)

package/src/tests/api_tests/form_vital_reading.test.ts

@@ -0,0 +1,393 @@
+require('source-map-support').install();
+
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+const FORM_VITAL_READING_SOURCE = 'tellescope-form'
+
+/**
+ * Coverage for the per-question opt-in that turns a numeric form answer into an
+ * `enduser_observations` vital reading on submission — `form_fields.options.vitalUnit`, consumed by
+ * `create_vital_readings_for_form_response` in api/modules/forms.ts.
+ *
+ * The point of the feature is that weight (and the other VITAL_UNITS) collected in a form charts
+ * beside device, portal and manually entered readings. The point of the opt-in being per FIELD is
+ * that nothing changes for an existing org or form until an admin configures a question — which is
+ * why the "no opt-in configured" check below is as load-bearing as the positive ones.
+ *
+ * Provisions its own throwaway tenant: readings are read back by enduser, and `handle_vital_create`
+ * reads business-wide vital_configurations, so a shared tenant would let concurrently running suites
+ * see each other's observations. Never calls `sdk.reset_db()`.
+ *
+ * Readings are created as an asynchronous side effect of the submission (fire-and-forget, so that a
+ * reading can never delay or fail a patient's submit), so every read polls — and every NEGATIVE
+ * check polls too, with a barrier that proves the submission's side effects have run.
+ */
+
+const poll_for = async <T,>(get: () => Promise<T>, done: (v: T) => boolean, attempts=20): Promise<T> => {
+  let value = await get()
+  for (let i = 0; i < attempts && !done(value); i++) {
+    await new Promise(resolve => setTimeout(resolve, 250))
+    value = await get()
+  }
+  return value
+}
+
+export const form_vital_reading_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `FormVitals ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    const observations_for = (enduserId: string) => (
+      sdk.api.enduser_observations.getSome({ filter: { enduserId } })
+    )
+
+    /* ===== A: a configured Number question creates a reading on submission ===== */
+
+    const form = await sdk.api.forms.createOne({ title: `Vitals intake ${RAND()}` })
+    const weightField = await sdk.api.form_fields.createOne({
+      formId: form.id,
+      title: 'Weight (lbs)',
+      type: 'number',
+      options: { vitalUnit: 'LB' },
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    // a second question with NO vitalUnit, to prove the opt-in is per field and not per form
+    const plainField = await sdk.api.form_fields.createOne({
+      formId: form.id,
+      title: 'How many glasses of water?',
+      type: 'number',
+      previousFields: [{ type: 'after', info: { fieldId: weightField.id } }],
+    })
+
+    const enduser = await sdk.api.endusers.createOne({ fname: 'Form', lname: 'Vitals' })
+
+    const prepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: enduser.id,
+    })
+    const submittedAt = new Date()
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: prepared.accessCode,
+      responses: [
+        { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 185 } },
+        { fieldId: plainField.id, fieldTitle: plainField.title, answer: { type: 'number', value: 8 } },
+      ],
+    })
+
+    const readings = await poll_for(() => observations_for(enduser.id), o => o.length >= 1)
+
+    record(
+      'A1: exactly one reading is created — the opt-in is per field, not per form',
+      readings.length === 1,
+      `created ${readings.length}: ${JSON.stringify(readings.map(r => r.measurement))}`
+      + ` — the second Number question has no vitalUnit and must contribute nothing`,
+    )
+
+    const reading = readings[0]
+    record(
+      'A2: the reading carries the answer value in the configured unit',
+      reading?.measurement?.value === 185 && reading?.measurement?.unit === 'LB',
+      `measurement=${JSON.stringify(reading?.measurement)} (want { value: 185, unit: 'LB' })`,
+    )
+    record(
+      'A3: source marks it as form-collected',
+      reading?.source === FORM_VITAL_READING_SOURCE,
+      `source=${JSON.stringify(reading?.source)} (want ${JSON.stringify(FORM_VITAL_READING_SOURCE)})`
+      + ` — the webapp Vitals table renders an unlisted source as "Source: <source>"`,
+    )
+    record(
+      'A4: it is a final vital-signs observation, like any other charted reading',
+      reading?.category === 'vital-signs' && reading?.status === 'final',
+      `category=${JSON.stringify(reading?.category)} status=${JSON.stringify(reading?.status)}`,
+    )
+    record(
+      'A5: timestamp and recordedAt are the submission time',
+      (
+        !!reading?.timestamp && !!reading?.recordedAt
+        && new Date(reading.recordedAt).getTime() === new Date(reading.timestamp).getTime()
+        && Math.abs(new Date(reading.timestamp).getTime() - submittedAt.getTime()) < 1000 * 60 * 5
+      ),
+      `timestamp=${JSON.stringify(reading?.timestamp)} recordedAt=${JSON.stringify(reading?.recordedAt)}`
+      + ` (want both ~= the submission at ${submittedAt.toISOString()})`,
+    )
+    record(
+      'A6: externalId links the reading back to <formResponseId>:<fieldId>',
+      reading?.externalId === `${prepared.response.id}:${weightField.id}`,
+      `externalId=${JSON.stringify(reading?.externalId)}`
+      + ` (want ${JSON.stringify(`${prepared.response.id}:${weightField.id}`)})`,
+    )
+    record(
+      'A7: vital triggers are left enabled for an ordinary enduser',
+      reading?.dontTrigger !== true,
+      `dontTrigger=${JSON.stringify(reading?.dontTrigger)} (want not true, so Vital Update triggers fire)`,
+    )
+
+    /* ===== C: a form with no opted-in question creates nothing ===== */
+
+    const plainForm = await sdk.api.forms.createOne({ title: `No vitals ${RAND()}` })
+    const plainOnlyField = await sdk.api.form_fields.createOne({
+      formId: plainForm.id,
+      title: 'Current weight',
+      type: 'number',
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    const plainEnduser = await sdk.api.endusers.createOne({ fname: 'NoOptIn', lname: 'Patient' })
+    const plainPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: plainForm.id, enduserId: plainEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: plainPrepared.accessCode,
+      responses: [
+        { fieldId: plainOnlyField.id, fieldTitle: plainOnlyField.title, answer: { type: 'number', value: 200 } },
+      ],
+    })
+    // barrier: the submission completed, so its side effects have had their chance
+    await poll_for(
+      () => sdk.api.form_responses.getOne(plainPrepared.response.id),
+      r => !!r.submittedAt,
+    )
+    const plainReadings = await poll_for(() => observations_for(plainEnduser.id), o => o.length > 0, 8)
+    record(
+      'C1: a Number question with no vitalUnit creates no reading',
+      plainReadings.length === 0,
+      `created ${plainReadings.length}: ${JSON.stringify(plainReadings.map(r => r.measurement))}`
+      + ` — this is what keeps every existing org and form unchanged`,
+    )
+
+    /* ===== D: blank and non-numeric answers are skipped, and never fail the submission ===== */
+
+    const skipEnduser = await sdk.api.endusers.createOne({ fname: 'Skipped', lname: 'Answers' })
+    const skipPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: skipEnduser.id,
+    })
+
+    let submitError: any = undefined
+    try {
+      await sdk.api.form_responses.submit_form_response({
+        accessCode: skipPrepared.accessCode,
+        responses: [
+          // a blank answer for the opted-in question
+          { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: '' as any } },
+          { fieldId: plainField.id, fieldTitle: plainField.title, answer: { type: 'number', value: 8 } },
+        ],
+      })
+    } catch (err) { submitError = err }
+
+    record(
+      'D1: a blank answer does not fail the submission',
+      submitError === undefined,
+      `error=${submitError ? (submitError.message || JSON.stringify(submitError)) : 'none'}`
+      + ` — a patient must never see an error because of a vital reading`,
+    )
+    if (submitError === undefined) {
+      await poll_for(
+        () => sdk.api.form_responses.getOne(skipPrepared.response.id),
+        r => !!r.submittedAt,
+      )
+      const skipReadings = await poll_for(() => observations_for(skipEnduser.id), o => o.length > 0, 8)
+      record(
+        'D2: a blank answer creates no reading',
+        skipReadings.length === 0,
+        `created ${skipReadings.length}: ${JSON.stringify(skipReadings.map(r => r.measurement))}`,
+      )
+    }
+
+    // A non-numeric answer never reaches the reading code over HTTP: the submit endpoint validates
+    // a 'number' answer with numberValidator ("Response must be a number") and rejects the whole
+    // submission. Pinned here because QA step 16 is written as if the field type allowed it.
+    // The parseFloat/NaN guard in create_vital_readings_for_form_response is therefore defence in
+    // depth for the non-HTTP path (submit_form_response_internal, whose responses are persisted
+    // incrementally rather than through this validator).
+    const badEnduser = await sdk.api.endusers.createOne({ fname: 'NonNumeric', lname: 'Answer' })
+    const badPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: badEnduser.id,
+    })
+    let badError: any = undefined
+    try {
+      await sdk.api.form_responses.submit_form_response({
+        accessCode: badPrepared.accessCode,
+        responses: [
+          { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 'one hundred' as any } },
+        ],
+      })
+    } catch (err) { badError = err }
+    const badReadings = await poll_for(() => observations_for(badEnduser.id), o => o.length > 0, 8)
+    record(
+      'D3: a non-numeric answer on a Number question is rejected and creates no reading',
+      // assert the rejection too, so this check starts failing if numberValidator ever stops
+      // rejecting and the answer begins reaching create_vital_readings_for_form_response for real
+      !!badError && badReadings.length === 0,
+      `submit ${badError ? `rejected (${badError.message || JSON.stringify(badError)})` : 'ACCEPTED'};`
+      + ` ${badReadings.length} reading(s) — rejection happens in numberValidator, before this feature`,
+    )
+
+    /* ===== E: one unit per question — SBP and DBP are two questions ===== */
+
+    const bpForm = await sdk.api.forms.createOne({ title: `Blood pressure ${RAND()}` })
+    const sbpField = await sdk.api.form_fields.createOne({
+      formId: bpForm.id, title: 'Systolic', type: 'number',
+      options: { vitalUnit: 'SBP' },
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    const dbpField = await sdk.api.form_fields.createOne({
+      formId: bpForm.id, title: 'Diastolic', type: 'number',
+      options: { vitalUnit: 'DBP' },
+      previousFields: [{ type: 'after', info: { fieldId: sbpField.id } }],
+    })
+    const bpEnduser = await sdk.api.endusers.createOne({ fname: 'Blood', lname: 'Pressure' })
+    const bpPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: bpForm.id, enduserId: bpEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: bpPrepared.accessCode,
+      responses: [
+        { fieldId: sbpField.id, fieldTitle: sbpField.title, answer: { type: 'number', value: 128 } },
+        { fieldId: dbpField.id, fieldTitle: dbpField.title, answer: { type: 'number', value: 82 } },
+      ],
+    })
+    const bpReadings = await poll_for(() => observations_for(bpEnduser.id), o => o.length >= 2)
+    const sbp = bpReadings.find(r => r.measurement?.unit === 'SBP')
+    const dbp = bpReadings.find(r => r.measurement?.unit === 'DBP')
+    record(
+      'E1: two opted-in questions produce one reading each, in their own units',
+      bpReadings.length === 2 && sbp?.measurement?.value === 128 && dbp?.measurement?.value === 82,
+      `readings=${JSON.stringify(bpReadings.map(r => r.measurement))} (want SBP 128 and DBP 82)`,
+    )
+
+    /* ===== F: an enduser with vital triggers disabled still gets the reading ===== */
+
+    const quietEnduser = await sdk.api.endusers.createOne({
+      fname: 'Quiet', lname: 'Triggers', vitalTriggersDisabled: true,
+    })
+    const quietPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: quietEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: quietPrepared.accessCode,
+      responses: [
+        { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 210 } },
+      ],
+    })
+    const quietReadings = await poll_for(() => observations_for(quietEnduser.id), o => o.length >= 1)
+    record(
+      'F1: the reading is still created and charted for a triggers-disabled enduser',
+      quietReadings.length === 1 && quietReadings[0]?.measurement?.value === 210,
+      `readings=${JSON.stringify(quietReadings.map(r => r.measurement))} (want one, 210 LB)`,
+    )
+    record(
+      'F2: but it is marked dontTrigger, so no Vital Update automation fires',
+      quietReadings[0]?.dontTrigger === true,
+      `dontTrigger=${JSON.stringify(quietReadings[0]?.dontTrigger)} (want true, as smartmeter.ts does)`,
+    )
+
+    /* ===== G: a partial save creates nothing — final submission only ===== */
+
+    const partialEnduser = await sdk.api.endusers.createOne({ fname: 'Partial', lname: 'Save' })
+    const partialPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: form.id, enduserId: partialEnduser.id,
+    })
+    await sdk.api.form_responses.save_field_response({
+      accessCode: partialPrepared.accessCode,
+      response: { fieldId: weightField.id, fieldTitle: weightField.title, answer: { type: 'number', value: 175 } },
+    })
+    // barrier: the draft answer is persisted, so anything the save path triggers has had its chance
+    await poll_for(
+      () => sdk.api.form_responses.getOne(partialPrepared.response.id),
+      r => !!(r.responses || []).length,
+    )
+    const partialReadings = await poll_for(() => observations_for(partialEnduser.id), o => o.length > 0, 8)
+    record(
+      'G1: a partial save creates no reading before the response is submitted',
+      partialReadings.length === 0,
+      `created ${partialReadings.length}: ${JSON.stringify(partialReadings.map(r => r.measurement))}`
+      + ` — readings are a final-submission side effect only`,
+    )
+
+
+    /* ===== H: clearing the select (vitalUnit '') is the documented off switch ===== */
+
+    // The editor writes '' rather than removing the key, so '' must read as off just like an absent
+    // vitalUnit. This is the path QA step 9 takes to turn a configured question back off.
+    const clearedForm = await sdk.api.forms.createOne({ title: `Cleared unit ${RAND()}` })
+    const clearedField = await sdk.api.form_fields.createOne({
+      formId: clearedForm.id, title: 'Weight (lbs)', type: 'number',
+      options: { vitalUnit: 'LB' },
+      previousFields: [{ type: 'root', info: {} }],
+    })
+    await sdk.api.form_fields.updateOne(clearedField.id, { options: { vitalUnit: '' } })
+    const storedCleared = await sdk.api.form_fields.getOne(clearedField.id)
+    record(
+      "H1: clearing the unit persists as '', it is not dropped back to the old value",
+      storedCleared.options?.vitalUnit === '',
+      `stored vitalUnit=${JSON.stringify(storedCleared.options?.vitalUnit)} (want '')`
+      + ` — stringValidatorOptionalEmptyOkay is what lets the empty round-trip`,
+    )
+
+    const clearedEnduser = await sdk.api.endusers.createOne({ fname: 'Cleared', lname: 'OptIn' })
+    const clearedPrepared = await sdk.api.form_responses.prepare_form_response({
+      formId: clearedForm.id, enduserId: clearedEnduser.id,
+    })
+    await sdk.api.form_responses.submit_form_response({
+      accessCode: clearedPrepared.accessCode,
+      responses: [
+        { fieldId: clearedField.id, fieldTitle: clearedField.title, answer: { type: 'number', value: 199 } },
+      ],
+    })
+    await poll_for(
+      () => sdk.api.form_responses.getOne(clearedPrepared.response.id),
+      r => !!r.submittedAt,
+    )
+    const clearedReadings = await poll_for(() => observations_for(clearedEnduser.id), o => o.length > 0, 8)
+    record(
+      'H2: a question whose unit was cleared creates no reading',
+      clearedReadings.length === 0,
+      `created ${clearedReadings.length}: ${JSON.stringify(clearedReadings.map(r => r.measurement))}`
+      + ` — the field query treats '' as off, same as an absent vitalUnit`,
+    )
+
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+    if (tenant) { try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) } }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const form_vital_reading_tests = async () => {
+  assert_checks('Vitals from form submissions', await form_vital_reading_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Vitals from form submissions', run: form_vital_reading_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  form_vital_reading_tests()
+    .then(() => {
+      console.log("✅ Vitals from form submissions test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Vitals from form submissions test suite failed:", error)
+      process.exit(1)
+    })
+}