@tellescope/sdk 2.0.0-beta.1 → 2.0.0-beta.3

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

@@ -0,0 +1,701 @@
+require('source-map-support').install();
+
+import { EnduserSession } from "../../enduser"
+import { EnduserProgram } from "@tellescope/types-models"
+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)
+
+/**
+ * Coverage for the `programs` field on Enduser / EnduserObservation / EnduserOrder, and for the
+ * `programs` filter on the Order Status Equals and Vital Update automation triggers.
+ *
+ * `EnduserOrder.programs` and `EnduserObservation.programs` are lists of `{ name }` objects; the
+ * trigger's `info.programs` is a list of names. A trigger matches when the two overlap, and — the part
+ * that matters most — a trigger with NO programs filter must keep matching every record, since that is
+ * every trigger that exists today.
+ *
+ * Both handlers apply the filter in JS after loading candidate triggers:
+ *   - handle_order_status_equals, api/modules/automation_triggers.ts
+ *   - handle_vital_create, api/v1/event_handlers_v2/vitals.ts
+ *
+ * This suite provisions its own throwaway tenant. That is not optional here: `vital_configurations`
+ * are business-wide (handle_vital_create reads them with `enduserId: { $exists: false }` across the
+ * businessId), so running on the shared fixture would classify other concurrently running suites'
+ * readings and theirs would bleed into these checks. It never calls `sdk.reset_db()`, which clears
+ * global throttle namespaces shared with other suites.
+ *
+ * Every check gets its own enduser: triggers are throttled to one fire per trigger per enduser per
+ * minute, so reusing a patient across checks would silently swallow the second fire.
+ *
+ * Triggers fire asynchronously. Each check polls for the unfiltered trigger's tag and uses that as the
+ * synchronization barrier, then asserts on the filtered trigger's tag. Without the barrier a negative
+ * check would pass merely by reading too early.
+ */
+
+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 programs_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: `ProgramFilters ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    /* ===================== Enduser.programs ===================== */
+
+    const programsEnduser = await sdk.api.endusers.createOne({
+      fname: 'Programs',
+      lname: 'Field',
+      email: `programs-field-${RAND()}@tellescope.example`,
+      devices: [{ title: 'Cuff', id: `dev-a-${RAND()}` }, { title: 'Scale', id: `dev-b-${RAND()}` }],
+      programs: [
+        { name: 'CHF', deviceIds: ['dev-a'], status: 'Active' },
+        { name: 'Diabetes' }, // deviceIds and status are optional
+      ],
+    })
+
+    const createdPrograms = (await sdk.api.endusers.getOne(programsEnduser.id)).programs
+    record(
+      'F: Enduser.programs round-trips on create, with and without deviceIds / status',
+      createdPrograms?.length === 2
+      && createdPrograms[0].name === 'CHF'
+      && JSON.stringify(createdPrograms[0].deviceIds) === JSON.stringify(['dev-a'])
+      && createdPrograms[0].status === 'Active'
+      && createdPrograms[1].name === 'Diabetes'
+      && createdPrograms[1].deviceIds === undefined
+      && createdPrograms[1].status === undefined,
+      `programs=${JSON.stringify(createdPrograms)}`,
+    )
+
+    await sdk.api.endusers.updateOne(
+      programsEnduser.id,
+      { programs: [{ name: 'CHF', deviceIds: ['dev-a', 'dev-b'] }] },
+      { replaceObjectFields: true },
+    )
+    const replacedPrograms = (await sdk.api.endusers.getOne(programsEnduser.id)).programs
+    record(
+      'G: updating programs with replaceObjectFields replaces the whole list',
+      replacedPrograms?.length === 1
+      && replacedPrograms[0].name === 'CHF'
+      && JSON.stringify(replacedPrograms[0].deviceIds) === JSON.stringify(['dev-a', 'dev-b']),
+      `programs=${JSON.stringify(replacedPrograms)}`,
+    )
+
+    // name carries a non-optional validator inside the object validator, so it is required per item
+    let missingNameError = ''
+    try {
+      await sdk.api.endusers.updateOne(programsEnduser.id, { programs: [{ deviceIds: ['dev-a'] } as any] })
+    } catch (err: any) { missingNameError = err?.message ?? String(err) }
+    record(
+      'H: a program entry without a name is rejected',
+      missingNameError.includes('name'),
+      `error=${JSON.stringify(missingNameError) || '(none — the write was ACCEPTED)'}`,
+    )
+
+    /* --- programs is staff-only: redacted from enduser sessions, and not enduser-updatable --- */
+
+    const { authToken } = await sdk.api.endusers.generate_auth_token({ id: programsEnduser.id })
+    const enduserSession = new EnduserSession({ host, authToken, businessId: tenant.businessId })
+    await enduserSession.refresh_session()
+
+    const selfRead = await enduserSession.api.endusers.getOne(programsEnduser.id)
+    record(
+      'I: Enduser.programs is redacted from the enduser\'s own read of their record',
+      selfRead.programs === undefined,
+      `enduser-session programs=${JSON.stringify(selfRead.programs)}`,
+    )
+
+    let selfUpdateError = ''
+    try {
+      await enduserSession.api.endusers.updateOne(programsEnduser.id, { programs: [{ name: 'Self Assigned' }] })
+    } catch (err: any) { selfUpdateError = err?.message ?? String(err) }
+    const afterSelfUpdate = (await sdk.api.endusers.getOne(programsEnduser.id)).programs
+    record(
+      'J: an enduser cannot update their own programs',
+      selfUpdateError.includes('cannot be updated by endusers')
+      && afterSelfUpdate?.length === 1 && afterSelfUpdate[0].name === 'CHF',
+      `error=${JSON.stringify(selfUpdateError) || '(none — the write was ACCEPTED)'}`
+      + ` programs=${JSON.stringify(afterSelfUpdate)}`,
+    )
+
+    /* ===================== Order Status Equals ===================== */
+
+    const ORDER_SOURCE = `ProgramFilterSource${RAND()}`
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Order Status Equals', info: { source: ORDER_SOURCE, status: 'shipped', programs: ['CHF'] } },
+      action: { type: 'Add Tags', info: { tags: ['order-chf'] } },
+      status: 'Active',
+      title: `Order programs=[CHF] ${RAND()}`,
+    })
+    // no programs filter — the shape of every trigger that exists today; must match regardless
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Order Status Equals', info: { source: ORDER_SOURCE, status: 'shipped' } },
+      action: { type: 'Add Tags', info: { tags: ['order-any'] } },
+      status: 'Active',
+      title: `Order programs unset ${RAND()}`,
+    })
+
+    const create_order = async (enduserId: string, programs?: { name: string }[]) => (
+      sdk.api.enduser_orders.createOne({
+        enduserId,
+        source: ORDER_SOURCE,
+        externalId: `ext-${RAND()}`,
+        title: 'Program filter order',
+        status: 'shipped',
+        ...(programs ? { programs } : {}),
+      })
+    )
+
+    const tags_after_order = async (programs: { name: string }[] | undefined) => {
+      const enduser = await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'Order' })
+      await create_order(enduser.id, programs)
+      // the unfiltered trigger always fires, so its tag is the barrier that makes an absence meaningful
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes('order-any'),
+      )
+      return after.tags ?? []
+    }
+
+    const orderMatching = await tags_after_order([{ name: 'CHF' }])
+    record(
+      'A: Order Status Equals with programs=[CHF] fires for an order in program CHF',
+      orderMatching.includes('order-chf') && orderMatching.includes('order-any'),
+      `tags=${JSON.stringify(orderMatching)}`,
+    )
+
+    const orderNonMatching = await tags_after_order([{ name: 'Diabetes' }])
+    record(
+      'B: Order Status Equals with programs=[CHF] does NOT fire for an order in program Diabetes',
+      !orderNonMatching.includes('order-chf') && orderNonMatching.includes('order-any'),
+      `tags=${JSON.stringify(orderNonMatching)}`,
+    )
+
+    const orderNoPrograms = await tags_after_order(undefined)
+    record(
+      'C: Order Status Equals with programs=[CHF] does NOT fire for an order with no programs,'
+      + ' while the unfiltered trigger still does (back-compat)',
+      !orderNoPrograms.includes('order-chf') && orderNoPrograms.includes('order-any'),
+      `tags=${JSON.stringify(orderNoPrograms)}`,
+    )
+
+    /* ===================== Vital Update ===================== */
+
+    const configuration = await sdk.api.vital_configurations.createOne({
+      title: `Program filter SBP ${RAND()}`,
+      unit: 'SBP',
+      ranges: [
+        {
+          classification: 'High',
+          comparison: { type: 'Greater Than', value: 200 },
+        },
+      ],
+    })
+
+    await sdk.api.automation_triggers.createOne({
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [configuration.id], classifications: ['High'], programs: ['CHF'] },
+      },
+      action: { type: 'Add Tags', info: { tags: ['vital-chf'] } },
+      status: 'Active',
+      title: `Vital programs=[CHF] ${RAND()}`,
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: {
+        type: 'Vital Update',
+        info: { configurationIds: [configuration.id], classifications: ['High'] },
+      },
+      action: { type: 'Add Tags', info: { tags: ['vital-any'] } },
+      status: 'Active',
+      title: `Vital programs unset ${RAND()}`,
+    })
+
+    const tags_after_reading = async (programs: { name: string }[] | undefined) => {
+      const enduser = await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'Vital' })
+      await sdk.api.enduser_observations.createOne({
+        category: 'vital-signs',
+        status: 'final',
+        enduserId: enduser.id,
+        measurement: { unit: 'SBP', value: 250 }, // High
+        timestamp: new Date(),
+        ...(programs ? { programs } : {}),
+      })
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes('vital-any'),
+      )
+      return after.tags ?? []
+    }
+
+    const vitalMatching = await tags_after_reading([{ name: 'CHF' }])
+    record(
+      'D: Vital Update with programs=[CHF] fires for a reading in program CHF',
+      vitalMatching.includes('vital-chf') && vitalMatching.includes('vital-any'),
+      `tags=${JSON.stringify(vitalMatching)}`,
+    )
+
+    const vitalNonMatching = await tags_after_reading([{ name: 'Diabetes' }])
+    record(
+      'E: Vital Update with programs=[CHF] does NOT fire for a reading in program Diabetes,'
+      + ' while the unfiltered trigger still does (back-compat)',
+      !vitalNonMatching.includes('vital-chf') && vitalNonMatching.includes('vital-any'),
+      `tags=${JSON.stringify(vitalNonMatching)}`,
+    )
+
+    /* =============== Programs as a trigger enduserCondition (conditional logic) =============== */
+
+    // The `Programs` key is evaluated by evaluate_conditional_logic_for_enduser_fields, which is what
+    // handle_actions_for_triggers runs every trigger's enduserCondition through. These two checks are the
+    // end-to-end proof that a condition built in the UI actually gates a real trigger fire.
+    const CONDITION_FIELD = `ProgramConditionKey${RAND()}`
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: CONDITION_FIELD, value: 'go' } },
+      action: { type: 'Add Tags', info: { tags: ['condition-chf'] } },
+      enduserCondition: { $and: [{ condition: { Programs: { $in: 'CHF' } } }] },
+      status: 'Active',
+      title: `Programs condition Is In CHF ${RAND()}`,
+    })
+    // the same event with no enduserCondition — the barrier that makes an absence above meaningful
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: CONDITION_FIELD, value: 'go' } },
+      action: { type: 'Add Tags', info: { tags: ['condition-any'] } },
+      status: 'Active',
+      title: `Programs condition unset ${RAND()}`,
+    })
+
+    // `waitFor` is the tag that makes the read meaningful. For the positive check that is the
+    // conditioned trigger's own tag — the two triggers are dispatched by separate awaited calls, so the
+    // unconditioned trigger's tag can land first and polling on it alone would read too early. For the
+    // negative check, where there is no tag to wait for, the unconditioned trigger is the barrier.
+    const tags_after_create = async (programs: EnduserProgram[] | undefined, waitFor: string) => {
+      const enduser = await sdk.api.endusers.createOne({
+        fname: 'Programs',
+        lname: 'Condition',
+        fields: { [CONDITION_FIELD]: 'go' },
+        ...(programs ? { programs } : {}),
+      })
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes(waitFor),
+      )
+      return after.tags ?? []
+    }
+
+    const conditionMatching = await tags_after_create([{ name: 'CHF', status: 'active' }], 'condition-chf')
+    record(
+      'K: a trigger with a Programs Is In CHF enduserCondition fires for a patient in program CHF',
+      conditionMatching.includes('condition-chf') && conditionMatching.includes('condition-any'),
+      `tags=${JSON.stringify(conditionMatching)}`,
+    )
+
+    const conditionNonMatching = await tags_after_create(undefined, 'condition-any')
+    record(
+      'L: the same trigger does NOT fire for a patient with no programs,'
+      + ' while the unconditioned trigger still does',
+      !conditionNonMatching.includes('condition-chf') && conditionNonMatching.includes('condition-any'),
+      `tags=${JSON.stringify(conditionNonMatching)}`,
+    )
+
+    /* ============ Add / Remove / Update List Item trigger actions ============ */
+
+    // '$exists' is matched by handle_enduser_field_change for ANY truthy value of the field, so this one
+    // trigger is the barrier for every mutation check below, whatever value that check writes. Without a
+    // barrier a "nothing happened" assertion would pass merely by reading before the trigger ran.
+    const MUTATION_FIELD = `ProgramMutation${RAND()}`
+    const PROGRAM = 'CHF'
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: MUTATION_FIELD, value: '$exists' } },
+      action: { type: 'Add Tags', info: { tags: ['mutation-any'] } },
+      status: 'Active',
+      title: `Mutation barrier ${RAND()}`,
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: MUTATION_FIELD, value: 'add' } },
+      action: { type: 'Add List Item', info: { field: 'programs', match: { name: PROGRAM }, values: { status: 'Active' } } },
+      status: 'Active',
+      title: `Add List Item ${RAND()}`,
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: MUTATION_FIELD, value: 'status' } },
+      action: { type: 'Update List Item', info: { field: 'programs', match: { name: PROGRAM }, values: { status: 'Discharged' } } },
+      status: 'Active',
+      title: `Update List Item ${RAND()}`,
+    })
+    await sdk.api.automation_triggers.createOne({
+      // a BLANK value clears that sub-field, rather than being a no-op — the $unset half of the action
+      event: { type: 'Field Equals', info: { field: MUTATION_FIELD, value: 'clear' } },
+      action: { type: 'Update List Item', info: { field: 'programs', match: { name: PROGRAM }, values: { status: '' } } },
+      status: 'Active',
+      title: `Clear List Item status ${RAND()}`,
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: MUTATION_FIELD, value: 'remove' } },
+      action: { type: 'Remove List Item', info: { field: 'programs', match: { name: PROGRAM } } },
+      status: 'Active',
+      title: `Remove List Item ${RAND()}`,
+    })
+
+    /**
+     * The sub-fields a mutation may touch are ENDUSER_LIST_FIELD_CONFIG's, checked when the trigger is
+     * SAVED (an automation_triggers constraint, sharing list_item_mutation_error with the editor).
+     *
+     * Rejecting here rather than at fire time is the point: an accepted-but-ignored key leaves a
+     * trigger that looks configured and silently never does what it says. It is also what keeps a
+     * `$`-prefixed or dotted key out of the Mongo paths the action builds from these keys.
+     */
+    const save_trigger_error = async (action: any): Promise<string> => {
+      try {
+        const created = await sdk.api.automation_triggers.createOne({
+          event: { type: 'Field Equals', info: { field: `Never${RAND()}`, value: 'never' } },
+          action, status: 'Inactive', title: `Rejected ${RAND()}`,
+        })
+        // it saved; leave nothing behind for the later checks to trip over
+        await sdk.api.automation_triggers.deleteOne(created.id)
+        return ''
+      } catch (err: any) { return err?.message ?? String(err) }
+    }
+
+    const unknownMatchKey = await save_trigger_error({
+      type: 'Add List Item', info: { field: 'programs', match: { title: PROGRAM } },
+    })
+    const unknownValueKey = await save_trigger_error({
+      type: 'Update List Item', info: { field: 'programs', match: { name: PROGRAM }, values: { deviceIds: 'x' } },
+    })
+    const operatorKey = await save_trigger_error({
+      type: 'Add List Item', info: { field: 'programs', match: { '$where': PROGRAM } },
+    })
+    const emptyMatch = await save_trigger_error({
+      type: 'Remove List Item', info: { field: 'programs', match: {} },
+    })
+    const emptyUpdate = await save_trigger_error({
+      type: 'Update List Item', info: { field: 'programs', match: { name: PROGRAM }, values: {} },
+    })
+    const unknownField = await save_trigger_error({
+      type: 'Add List Item', info: { field: 'diagnoses', match: { code: 'I50' } },
+    })
+    record(
+      'Y: a list mutation naming a sub-field (or field) outside the registry is rejected ON SAVE,'
+      + ' naming the offending key',
+      // the message, not merely "an error": the point of sharing list_item_mutation_error with the
+      // editor is that both reject the same action with the same wording, and a rejection for some
+      // unrelated reason would pass a non-empty check while proving nothing
+      unknownMatchKey.includes('title') && unknownValueKey.includes('deviceIds')
+      && operatorKey.includes('$where') && unknownField.includes('diagnoses'),
+      `match=${JSON.stringify(unknownMatchKey)} values=${JSON.stringify(unknownValueKey)}`
+      + ` operator=${JSON.stringify(operatorKey)} field=${JSON.stringify(unknownField)}`,
+    )
+    record(
+      'Z: a list mutation that matches nothing, or an Update that sets nothing, is rejected ON SAVE',
+      !!emptyMatch && !!emptyUpdate,
+      `emptyMatch=${JSON.stringify(emptyMatch)} emptyUpdate=${JSON.stringify(emptyUpdate)}`,
+    )
+
+    // every check gets its own patient: triggers are throttled to one fire per trigger per enduser per
+    // minute, so reusing one would silently swallow the second fire
+    const fire_mutation = async (value: string, programs?: EnduserProgram[]) => {
+      const enduser = await sdk.api.endusers.createOne({
+        fname: 'Programs', lname: 'Mutation', ...(programs ? { programs } : {}),
+      })
+      // an UPDATE, not a create: the mutation actions are reached through the update path, and Field
+      // Equals on programs (below) is update-only
+      await sdk.api.endusers.updateOne(enduser.id, { fields: { [MUTATION_FIELD]: value } })
+      return enduser.id
+    }
+
+    const programs_once = async (id: string, done: (p: EnduserProgram[]) => boolean, attempts?: number) => (
+      (await poll_for(() => sdk.api.endusers.getOne(id), e => done(e.programs ?? []), attempts)).programs ?? []
+    )
+
+    /**
+     * For the checks that assert NOTHING changed. The barrier tag proves trigger processing happened for
+     * this patient, but the barrier and the mutation are two triggers dispatched from one loop in
+     * whatever order the trigger page came back in, so the tag alone does not prove the mutation already
+     * ran. The extra settle closes that window; the positive checks need none of this, since they poll
+     * for their own effect.
+     */
+    const settled_enduser = async (id: string) => {
+      await poll_for(() => sdk.api.endusers.getOne(id), e => !!e.tags?.includes('mutation-any'))
+      await new Promise(resolve => setTimeout(resolve, 2000))
+      return sdk.api.endusers.getOne(id)
+    }
+
+    const addedId = await fire_mutation('add')
+    const added = await programs_once(addedId, p => p.length > 0)
+    record(
+      'M: Add List Item adds the configured program, with the status the action carries',
+      added.length === 1 && added[0].name === PROGRAM && added[0].status === 'Active',
+      `programs=${JSON.stringify(added)}`,
+    )
+
+    const duplicateId = await fire_mutation('add', [{ name: PROGRAM, status: 'Discharged' }])
+    const afterDuplicate = (await settled_enduser(duplicateId)).programs ?? []
+    record(
+      'N: Add List Item no-ops when the patient is already in that program, and does NOT reset its status',
+      afterDuplicate.length === 1
+      && afterDuplicate[0].name === PROGRAM && afterDuplicate[0].status === 'Discharged',
+      `programs=${JSON.stringify(afterDuplicate)}`,
+    )
+
+    // two entries with the same name: the drawer forbids that, but the API and integrations do not, and
+    // the action is specified to act on EVERY match rather than the first
+    const updatedId = await fire_mutation('status', [
+      { name: PROGRAM, status: 'Active' }, { name: 'Diabetes', status: 'Active' }, { name: PROGRAM },
+    ])
+    const afterUpdate = await programs_once(
+      updatedId, p => p.filter(x => x.name === PROGRAM && x.status === 'Discharged').length === 2,
+    )
+    record(
+      'O: Update List Item sets the status on EVERY entry with that name, and on no other entry',
+      afterUpdate.length === 3
+      && afterUpdate.filter(p => p.name === PROGRAM && p.status === 'Discharged').length === 2
+      && afterUpdate.find(p => p.name === 'Diabetes')?.status === 'Active',
+      `programs=${JSON.stringify(afterUpdate)}`,
+    )
+
+    // the $unset half: a blank value REMOVES the sub-field from every matching entry. Asserted by key
+    // presence, not by value: a status written as '' or null would satisfy `status === undefined` in
+    // some clients and is not what the action is specified to do.
+    const clearedId = await fire_mutation('clear', [
+      { name: PROGRAM, status: 'Active' }, { name: 'Diabetes', status: 'Active' },
+    ])
+    const afterClear = await programs_once(
+      clearedId, p => p.some(x => x.name === PROGRAM && x.status === undefined),
+    )
+    const clearedEntry = afterClear.find(p => p.name === PROGRAM)
+    record(
+      'AA: Update List Item with a blank value CLEARS that sub-field, leaving no key behind',
+      afterClear.length === 2
+      && !!clearedEntry && !('status' in clearedEntry)
+      && afterClear.find(p => p.name === 'Diabetes')?.status === 'Active',
+      `programs=${JSON.stringify(afterClear)}`
+      + ` keys=${JSON.stringify(Object.keys(clearedEntry ?? {}))}`,
+    )
+
+    const removedId = await fire_mutation('remove', [
+      { name: PROGRAM }, { name: 'Diabetes', status: 'Active' }, { name: PROGRAM, status: 'Active' },
+    ])
+    const afterRemove = await programs_once(removedId, p => !p.some(x => x.name === PROGRAM))
+    record(
+      'P: Remove List Item removes EVERY entry with that name, whatever status they hold, and nothing else',
+      afterRemove.length === 1 && afterRemove[0].name === 'Diabetes' && afterRemove[0].status === 'Active',
+      `programs=${JSON.stringify(afterRemove)}`,
+    )
+
+    const noMatchRemoveId = await fire_mutation('remove', [{ name: 'Diabetes', status: 'Active' }])
+    const noMatchUpdateId = await fire_mutation('status', [{ name: 'Diabetes', status: 'Active' }])
+    const afterNoMatchRemove = (await settled_enduser(noMatchRemoveId)).programs ?? []
+    const afterNoMatchUpdate = (await settled_enduser(noMatchUpdateId)).programs ?? []
+    record(
+      'Q: Remove and Update List Item both no-op when no entry carries that name',
+      JSON.stringify(afterNoMatchRemove) === JSON.stringify([{ name: 'Diabetes', status: 'Active' }])
+      && JSON.stringify(afterNoMatchUpdate) === JSON.stringify([{ name: 'Diabetes', status: 'Active' }]),
+      `afterRemove=${JSON.stringify(afterNoMatchRemove)} afterUpdate=${JSON.stringify(afterNoMatchUpdate)}`,
+    )
+
+    /**
+     * The status already being the target one is a no-op too, detected in the $elemMatch filter.
+     *
+     * Read this as documentation of the invariant, NOT as a regression test: rewriting an identical
+     * status leaves a byte-identical record, so this check passes with the $elemMatch reverted to a
+     * plain name match. What the filter actually prevents is an updatedAt bump, a webhook and a
+     * sync_record push, none of which are observable here — updatedAt cannot be the discriminator
+     * because the barrier Add Tags trigger writes to this same patient. The filter's positive
+     * direction, which is what a malformed $elemMatch would break, is covered by check O.
+     */
+    const alreadyDischargedId = await fire_mutation('status', [{ name: PROGRAM, status: 'Discharged' }])
+    const afterAlreadyDischarged = (await settled_enduser(alreadyDischargedId)).programs ?? []
+    record(
+      'X: Update List Item leaves an entry alone when it already carries the target status',
+      JSON.stringify(afterAlreadyDischarged) === JSON.stringify([{ name: PROGRAM, status: 'Discharged' }]),
+      `programs=${JSON.stringify(afterAlreadyDischarged)}`,
+    )
+
+    /* ============ Fields Changed on programs, and the no-cascade rule ============ */
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Fields Changed', info: { fields: ['programs'] } },
+      action: { type: 'Add Tags', info: { tags: ['programs-fc'] } },
+      status: 'Active',
+      title: `Fields Changed programs ${RAND()}`,
+    })
+
+    const fieldsChangedEnduser = await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'Changed' })
+    await sdk.api.endusers.updateOne(
+      fieldsChangedEnduser.id, { programs: [{ name: PROGRAM }] }, { replaceObjectFields: true },
+    )
+    const fieldsChangedTags = (await poll_for(
+      () => sdk.api.endusers.getOne(fieldsChangedEnduser.id),
+      e => !!e.tags?.includes('programs-fc'),
+    )).tags ?? []
+    record(
+      'R: a Fields Changed trigger on programs fires for a direct staff/API write',
+      fieldsChangedTags.includes('programs-fc'),
+      `tags=${JSON.stringify(fieldsChangedTags)}`,
+    )
+
+    // leaving the LAST program is the case the per-name loop has no name to push for; `programs` must
+    // still reach handle_enduser_field_change or this automation goes quiet exactly when a patient is
+    // removed from their only program
+    const emptiedEnduser = await sdk.api.endusers.createOne({
+      fname: 'Programs', lname: 'Emptied', programs: [{ name: PROGRAM, status: 'Active' }],
+    })
+    await sdk.api.endusers.updateOne(emptiedEnduser.id, { programs: [] }, { replaceObjectFields: true })
+    const emptiedTags = (await poll_for(
+      () => sdk.api.endusers.getOne(emptiedEnduser.id),
+      e => !!e.tags?.includes('programs-fc'),
+    )).tags ?? []
+    record(
+      'W: a Fields Changed trigger on programs still fires when the patient\'s LAST program is removed',
+      emptiedTags.includes('programs-fc'),
+      `tags=${JSON.stringify(emptiedTags)}`
+      + ` programs=${JSON.stringify((await sdk.api.endusers.getOne(emptiedEnduser.id)).programs)}`,
+    )
+
+    // the same trigger must NOT fire for a program written BY a trigger — handleUpdatedRecord is called
+    // with dontUseAutomationTriggers, as Set Fields and Add Tags do
+    const cascadeId = await fire_mutation('add')
+    await programs_once(cascadeId, p => p.some(x => x.name === PROGRAM)) // the trigger's write landed
+    const afterCascade = await settled_enduser(cascadeId)
+    record(
+      'S: a program written by a trigger does NOT re-fire programs automations (no cascade),'
+      + ' while trigger processing demonstrably ran for this patient',
+      !afterCascade.tags?.includes('programs-fc') && !!afterCascade.tags?.includes('mutation-any'),
+      `tags=${JSON.stringify(afterCascade.tags)} programs=${JSON.stringify(afterCascade.programs)}`,
+    )
+
+    /* ============ Field Equals on programs ============ */
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Field Equals', info: { field: 'programs', value: PROGRAM } },
+      action: { type: 'Add Tags', info: { tags: ['programs-fe'] } },
+      status: 'Active',
+      title: `Field Equals programs ${RAND()}`,
+    })
+
+    const fieldEqualsTags = async (programs: EnduserProgram[], waitFor: string) => {
+      const enduser = await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'FieldEquals' })
+      await sdk.api.endusers.updateOne(enduser.id, { programs }, { replaceObjectFields: true })
+      const after = await poll_for(
+        () => sdk.api.endusers.getOne(enduser.id),
+        e => !!e.tags?.includes(waitFor),
+      )
+      return after.tags ?? []
+    }
+
+    const feMatching = await fieldEqualsTags([{ name: PROGRAM, status: 'Active' }], 'programs-fe')
+    record(
+      'T: Field Equals on programs fires for a patient put into a program of that name',
+      feMatching.includes('programs-fe'),
+      `tags=${JSON.stringify(feMatching)}`,
+    )
+
+    // the Fields Changed trigger above fires for ANY programs write, so it is the barrier here
+    const feNonMatching = await fieldEqualsTags([{ name: 'Diabetes' }], 'programs-fc')
+    await new Promise(resolve => setTimeout(resolve, 2000))
+    record(
+      'U: Field Equals on programs does NOT fire for a different program name,'
+      + ' while the Fields Changed trigger on the same write still does',
+      !feNonMatching.includes('programs-fe') && feNonMatching.includes('programs-fc'),
+      `tags=${JSON.stringify(feNonMatching)}`,
+    )
+
+    /* ============ the bulk-dispatched path ============ */
+
+    /**
+     * Bulk-dispatched events cannot run the list mutations inline — the no-ops are detected in each
+     * record's own update filter, which has no bulk equivalent — so bulk_handle_actions_for_triggers
+     * defers all three types to the single-record path through `delayed_events`. A type missing from that
+     * list is silently dropped AFTER its throttle record is written, which is invisible except here.
+     *
+     * createSome, not createOne: handle_orders_create only takes the bulk branch for more than one
+     * created order; a single create goes to handle_order_status_equals, which is the inline path.
+     *
+     * The deferral is drained by the WORKER, which polls on an 8s+ cadence, so this is much slower than
+     * every other check in this suite and needs a worker running at all.
+     */
+    const BULK_SOURCE = `ProgramBulkSource${RAND()}`
+    const BULK_PROGRAM = 'Bulk Program'
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Order Status Equals', info: { source: BULK_SOURCE, status: 'shipped' } },
+      action: { type: 'Add List Item', info: { field: 'programs', match: { name: BULK_PROGRAM } } },
+      status: 'Active',
+      title: `Bulk Add List Item ${RAND()}`,
+    })
+
+    const bulkEndusers = [
+      await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'BulkA' }),
+      await sdk.api.endusers.createOne({ fname: 'Programs', lname: 'BulkB' }),
+    ]
+    await sdk.api.enduser_orders.createSome(bulkEndusers.map(e => ({
+      enduserId: e.id,
+      source: BULK_SOURCE,
+      externalId: `ext-${RAND()}`,
+      title: 'Bulk program order',
+      status: 'shipped',
+    })))
+
+    const bulkPrograms = await Promise.all(bulkEndusers.map(e => (
+      programs_once(e.id, p => p.some(x => x.name === BULK_PROGRAM), 240) // up to 60s; worker-paced
+    )))
+    record(
+      'V: an Add List Item action dispatched in bulk is deferred to the single-record path and applied'
+      + ' to every patient in the batch',
+      bulkPrograms.every(p => p.length === 1 && p[0].name === BULK_PROGRAM),
+      `programs=${JSON.stringify(bulkPrograms)} (needs a worker running to drain delayed_events)`,
+    )
+  } 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 programs_tests = async () => {
+  assert_checks('Programs', await programs_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Programs', run: programs_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  programs_tests()
+    .then(() => {
+      console.log("✅ Programs test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Programs test suite failed:", error)
+      process.exit(1)
+    })
+}