@tellescope/sdk 1.256.10 → 1.256.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellescope/sdk",
-  "version": "1.256.10",
+  "version": "1.256.12",
   "description": "Code for interacting with the Tellescope API",
   "main": "./lib/cjs/sdk.js",
   "module": "./lib/esm/sdk.js",
@@ -32,14 +32,14 @@
   },
   "homepage": "https://github.com/tellescope-os/tellescope#readme",
   "dependencies": {
-    "@tellescope/constants": "1.256.10",
-    "@tellescope/schema": "1.256.10",
-    "@tellescope/testing": "1.256.10",
-    "@tellescope/types-client": "1.256.10",
-    "@tellescope/types-models": "1.256.10",
-    "@tellescope/types-utilities": "1.256.10",
-    "@tellescope/utilities": "1.256.10",
-    "@tellescope/validation": "1.256.10",
+    "@tellescope/constants": "1.256.12",
+    "@tellescope/schema": "1.256.12",
+    "@tellescope/testing": "1.256.12",
+    "@tellescope/types-client": "1.256.12",
+    "@tellescope/types-models": "1.256.12",
+    "@tellescope/types-utilities": "1.256.12",
+    "@tellescope/utilities": "1.256.12",
+    "@tellescope/validation": "1.256.12",
     "axios": "0.30.3",
     "dotenv": "14.3.2",
     "form-data": "4.0.4",
@@ -55,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "46f8475fc2faa03773200b0312f34b095a68eaeb"
+  "gitHead": "137bfca8fc8d2229a8eee245265536e507a3afae"
 }

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

@@ -0,0 +1,435 @@
+require('source-map-support').install();
+
+import { Session, EnduserSession } from "../../sdk"
+import {
+  async_test,
+  handleAnyError,
+  log_header,
+  wait,
+} from "@tellescope/testing"
+import { authenticate_enduser_via_token, setup_tests } from "../setup"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+const businessId = '60398b1131a295e64f084ff6'
+
+// Second-tenant session, used to prove the active patient count never crosses tenants.
+// Same key used by the org-isolation tests in tests.ts.
+const OTHER_TENANT_API_KEY = "ba745e25162bb95a795c5fa1af70df188d93c4d3aac9c48b34a5c8c9dd7b80f7"
+
+// Arbitrary valid ObjectId — endusers carrying a customTypeId are excluded from the default count
+const TEST_CUSTOM_TYPE_ID = '60398b0231a295e64f084fd9'
+
+/**
+ * Locks in the behavior of getEngagedEndusers (endusers/engagement), which backs both the billing
+ * /usage endpoint and the super-admin active patient count. Every case creates exactly one
+ * qualifying (or deliberately non-qualifying) engagement record and asserts its effect on the
+ * distinct enduser count.
+ *
+ * All assertions are made inside a time window opened at the top of the test, so unrelated records
+ * left behind by other suites can't move the numbers.
+ */
+export const active_patient_count_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
+  log_header("Active Patient Count Tests")
+
+  const userId = sdk.userInfo.id
+
+  // _id-based range filters use ObjectId.createFromTime, which floors to whole seconds — back off a
+  // couple of seconds so nothing created below can land before the window starts.
+  const windowStart = new Date(Date.now() - 2000)
+
+  const activeCount = (args: Parameters<typeof sdk.api.endusers.get_engagement_statistics>[0] = {}) => (
+    sdk.api.endusers.get_engagement_statistics({ range: { from: windowStart }, ...args })
+    .then(r => r.count)
+  )
+
+  // Scenarios are identified by fields.apcCase rather than fname, because fname is title-cased on
+  // create ('apc-email' is stored as 'Apc-email') while stored fields are kept verbatim.
+  const onlyCase = (apcCase: string) => activeCount({ enduserFields: [{ field: 'fields.apcCase', value: apcCase }] })
+  // every enduser this test creates, and nothing else
+  const onlyThisTest = (args: Parameters<typeof activeCount>[0] = {}) => activeCount({
+    ...args, enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+  })
+
+  // One enduser per scenario, created in a single call to avoid create throttling
+  const [
+    eEmail, eEmailOutbound,
+    eSMS, eSMSOutbound,
+    eCallInbound, eCallLongOutbound, eCallShortOutbound,
+    eChat, eChatNoEnduser,
+    eForm, eFormUnsubmitted, eFormOtherForm,
+    eCalendar, eCalendarUserOnly, eCalendarPastStart,
+    eGroupMMS, eGroupMMSUserSender,
+    eDedupe,
+    eCustomType,
+    eInactive,
+  ] = (await sdk.api.endusers.createSome([
+    { fname: 'apc-email', fields: { apcCase: 'email', apcTag: 'yes', apcGroup: 'A' } },
+    { fname: 'apc-email-outbound', fields: { apcCase: 'email-outbound' } },
+    { fname: 'apc-sms', fields: { apcCase: 'sms', apcTag: 'yes', apcGroup: 'A' } },
+    { fname: 'apc-sms-outbound', fields: { apcCase: 'sms-outbound' } },
+    { fname: 'apc-call-inbound', fields: { apcCase: 'call-inbound', apcGroup: 'B' } },
+    { fname: 'apc-call-long-outbound', fields: { apcCase: 'call-long-outbound', apcGroup: 'B' } },
+    { fname: 'apc-call-short-outbound', fields: { apcCase: 'call-short-outbound' } },
+    { fname: 'apc-chat', fields: { apcCase: 'chat', apcGroup: 'B' } },
+    { fname: 'apc-chat-no-enduserid', fields: { apcCase: 'chat-no-enduserid' } },
+    { fname: 'apc-form', fields: { apcCase: 'form', apcGroup: 'C' } },
+    { fname: 'apc-form-unsubmitted', fields: { apcCase: 'form-unsubmitted' } },
+    { fname: 'apc-form-other-form', fields: { apcCase: 'form-other-form', apcGroup: 'C' } },
+    // deliberately has no apcGroup, so the $exists case below is narrower than the total
+    { fname: 'apc-calendar', fields: { apcCase: 'calendar' } },
+    { fname: 'apc-calendar-user-only', fields: { apcCase: 'calendar-user-only' } },
+    { fname: 'apc-calendar-past-start', fields: { apcCase: 'calendar-past-start' } },
+    { fname: 'apc-group-mms', fields: { apcCase: 'group-mms', apcGroup: 'D' } },
+    { fname: 'apc-group-mms-user-sender', fields: { apcCase: 'group-mms-user-sender' } },
+    { fname: 'apc-dedupe', fields: { apcCase: 'dedupe', apcTag: 'yes', apcGroup: 'D' } },
+    { fname: 'apc-custom-type', customTypeId: TEST_CUSTOM_TYPE_ID, fields: { apcCase: 'custom-type' } },
+    { fname: 'apc-inactive', fields: { apcCase: 'inactive' } },
+  ])).created
+
+  const createdEnduserIds = [
+    eEmail, eEmailOutbound, eSMS, eSMSOutbound, eCallInbound, eCallLongOutbound, eCallShortOutbound,
+    eChat, eChatNoEnduser, eForm, eFormUnsubmitted, eFormOtherForm, eCalendar, eCalendarUserOnly,
+    eCalendarPastStart, eGroupMMS, eGroupMMSUserSender, eDedupe, eCustomType, eInactive,
+  ].map(e => e.id)
+
+  const chatRoomIds: string[] = []
+  const conversationIds: string[] = []
+  const calendarEventIds: string[] = []
+  const formIds: string[] = []
+
+  try {
+    // --- emails ---------------------------------------------------------------------------------
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eEmail.id, subject: 'apc inbound', textContent: 'inbound email',
+    })
+    // outbound with no link opens does not qualify
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: false, userId,
+      enduserId: eEmailOutbound.id, subject: 'apc outbound', textContent: 'outbound email',
+    })
+
+    // --- sms_messages ---------------------------------------------------------------------------
+    await sdk.api.sms_messages.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eSMS.id, message: 'apc inbound sms',
+    })
+    await sdk.api.sms_messages.createOne({
+      logOnly: true, inbound: false, userId,
+      enduserId: eSMSOutbound.id, message: 'apc outbound sms',
+    })
+
+    // --- phone_calls ----------------------------------------------------------------------------
+    // inbound qualifies regardless of duration
+    await sdk.api.phone_calls.createOne({ enduserId: eCallInbound.id, inbound: true, userId })
+    // outbound qualifies only at >= 60 seconds
+    await sdk.api.phone_calls.createOne({
+      enduserId: eCallLongOutbound.id, inbound: false, userId, callDurationInSeconds: 60,
+    })
+    await sdk.api.phone_calls.createOne({
+      enduserId: eCallShortOutbound.id, inbound: false, userId, callDurationInSeconds: 59,
+    })
+
+    // --- chats ----------------------------------------------------------------------------------
+    const chatRoom = await sdk.api.chat_rooms.createOne({ enduserIds: [eChat.id], userIds: [userId] })
+    chatRoomIds.push(chatRoom.id)
+    await sdk.api.chats.createOne({
+      roomId: chatRoom.id, message: 'apc chat', senderId: eChat.id, enduserId: eChat.id,
+    })
+
+    // a chat with no enduserId can't be attributed to a patient
+    const chatRoomNoEnduser = await sdk.api.chat_rooms.createOne({
+      enduserIds: [eChatNoEnduser.id], userIds: [userId],
+    })
+    chatRoomIds.push(chatRoomNoEnduser.id)
+    await sdk.api.chats.createOne({
+      roomId: chatRoomNoEnduser.id, message: 'apc chat without enduserId', senderId: userId,
+    })
+
+    // --- form_responses -------------------------------------------------------------------------
+    const formA = await sdk.api.forms.createOne({ title: 'Active Patient Count Form A' })
+    formIds.push(formA.id)
+    const fieldA = await sdk.api.form_fields.createOne({
+      formId: formA.id, type: 'string', title: 'FieldA', previousFields: [{ type: 'root', info: {} }],
+    })
+
+    const formB = await sdk.api.forms.createOne({ title: 'Active Patient Count Form B' })
+    formIds.push(formB.id)
+    const fieldB = await sdk.api.form_fields.createOne({
+      formId: formB.id, type: 'string', title: 'FieldB', previousFields: [{ type: 'root', info: {} }],
+    })
+
+    const submitForm = async (formId: string, fieldId: string, fieldTitle: string, enduserId: string) => {
+      const { accessCode } = await sdk.api.form_responses.prepare_form_response({ enduserId, formId })
+      await sdk.api.form_responses.submit_form_response({
+        accessCode,
+        responses: [{ fieldId, fieldTitle, answer: { type: 'string', value: 'apc' } }],
+      })
+    }
+
+    await submitForm(formA.id, fieldA.id, 'FieldA', eForm.id)
+    await submitForm(formB.id, fieldB.id, 'FieldB', eFormOtherForm.id)
+
+    // prepared but never submitted — no submittedAt, so it must not qualify
+    await sdk.api.form_responses.prepare_form_response({
+      enduserId: eFormUnsubmitted.id, formId: formA.id,
+    })
+
+    // --- calendar_events ------------------------------------------------------------------------
+    // starts now, not in the future — the bounded-range case below closes the window a couple of
+    // seconds out, and calendar_events are filtered on startTimeInMS
+    const calendarEvent = await sdk.api.calendar_events.createOne({
+      title: 'apc event', durationInMinutes: 30, startTimeInMS: Date.now(),
+      attendees: [{ id: eCalendar.id, type: 'enduser' }],
+    })
+    calendarEventIds.push(calendarEvent.id)
+
+    const calendarEventUserOnly = await sdk.api.calendar_events.createOne({
+      title: 'apc event user only', durationInMinutes: 30, startTimeInMS: Date.now(),
+      attendees: [{ id: userId, type: 'user' }],
+    })
+    calendarEventIds.push(calendarEventUserOnly.id)
+
+    // created now, but starts 30 days ago — calendar_events filter on startTimeInMS, not _id, so
+    // this must fall outside the window even though the record itself is brand new
+    const calendarEventPastStart = await sdk.api.calendar_events.createOne({
+      title: 'apc event past start', durationInMinutes: 30,
+      startTimeInMS: Date.now() - 30 * 24 * 60 * 60 * 1000,
+      attendees: [{ id: eCalendarPastStart.id, type: 'enduser' }],
+    })
+    calendarEventIds.push(calendarEventPastStart.id)
+
+    // --- group_mms_conversations ----------------------------------------------------------------
+    const conversation = await sdk.api.group_mms_conversations.createOne({
+      enduserIds: [eGroupMMS.id, eGroupMMSUserSender.id], userIds: [userId], userStates: [], messages: [],
+    })
+    conversationIds.push(conversation.id)
+
+    await sdk.api.group_mms_conversations.send_message({
+      conversationId: conversation.id, sender: eGroupMMS.id, message: 'apc group mms', logOnly: true,
+    })
+    await wait(undefined, 250)
+    // sent by a user, so it counts for nobody — the other enduser in the conversation included
+    await sdk.api.group_mms_conversations.send_message({
+      conversationId: conversation.id, sender: userId, message: 'apc group mms from user', logOnly: true,
+    })
+    await wait(undefined, 250)
+
+    // --- dedupe: one enduser active across three channels ----------------------------------------
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eDedupe.id, subject: 'apc dedupe', textContent: 'inbound email',
+    })
+    await sdk.api.sms_messages.createOne({
+      logOnly: true, inbound: true, userId, enduserId: eDedupe.id, message: 'apc dedupe sms',
+    })
+    const dedupeRoom = await sdk.api.chat_rooms.createOne({ enduserIds: [eDedupe.id], userIds: [userId] })
+    chatRoomIds.push(dedupeRoom.id)
+    await sdk.api.chats.createOne({
+      roomId: dedupeRoom.id, message: 'apc dedupe chat', senderId: eDedupe.id, enduserId: eDedupe.id,
+    })
+
+    // --- customTypeId: excluded from the default count --------------------------------------------
+    await sdk.api.emails.createOne({
+      logOnly: true, inbound: true, userId,
+      enduserId: eCustomType.id, subject: 'apc custom type', textContent: 'inbound email',
+    })
+
+    await wait(undefined, 1000) // let side effects settle
+
+    // Qualifying endusers: email, sms, inbound call, long outbound call, chat, form A, form B,
+    // calendar, group mms, dedupe = 10. eCustomType is excluded by customTypeId.
+    const EXPECTED_ACTIVE = 10
+
+    await async_test(
+      "Active count includes exactly the qualifying endusers",
+      () => onlyThisTest(),
+      { onResult: r => r === EXPECTED_ACTIVE }
+    )
+
+    // --- dedupe ----------------------------------------------------------------------------------
+    await async_test(
+      "Enduser active on email + sms + chat counts once",
+      () => onlyCase('dedupe'),
+      { onResult: r => r === 1 }
+    )
+
+    // --- per-channel attribution -----------------------------------------------------------------
+    const expectActive = (label: string, apcCase: string, expected: number) => async_test(
+      label,
+      () => onlyCase(apcCase),
+      { onResult: r => r === expected }
+    )
+
+    await expectActive("Inbound email counts", 'email', 1)
+    await expectActive("Outbound email without link opens does not count", 'email-outbound', 0)
+    await expectActive("Inbound SMS counts", 'sms', 1)
+    await expectActive("Outbound SMS does not count", 'sms-outbound', 0)
+    await expectActive("Inbound phone call counts", 'call-inbound', 1)
+    await expectActive("Outbound phone call >= 60s counts", 'call-long-outbound', 1)
+    await expectActive("Outbound phone call < 60s does not count", 'call-short-outbound', 0)
+    await expectActive("Chat with enduserId counts", 'chat', 1)
+    await expectActive("Chat without enduserId does not count", 'chat-no-enduserid', 0)
+    await expectActive("Submitted form response counts", 'form', 1)
+    await expectActive("Unsubmitted form response does not count", 'form-unsubmitted', 0)
+    await expectActive("Calendar event with enduser attendee counts", 'calendar', 1)
+    await expectActive("Calendar event with only user attendees does not count", 'calendar-user-only', 0)
+    await expectActive("Inbound group MMS counts", 'group-mms', 1)
+    await expectActive("Group MMS sent by a user does not count", 'group-mms-user-sender', 0)
+    await expectActive("Enduser with no engagement does not count", 'inactive', 0)
+
+    // --- date field per collection ----------------------------------------------------------------
+    await async_test(
+      "Calendar event is filtered by startTimeInMS, not creation time",
+      () => onlyCase('calendar-past-start'),
+      { onResult: r => r === 0 }
+    )
+
+    // --- range boundaries -------------------------------------------------------------------------
+    const afterAll = new Date(Date.now() + 2000)
+
+    await async_test(
+      "Active count is unchanged with an explicit upper bound after all activity",
+      () => sdk.api.endusers.get_engagement_statistics({
+        range: { from: windowStart, to: afterAll },
+        enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+      }).then(r => r.count),
+      { onResult: r => r === EXPECTED_ACTIVE }
+    )
+    await async_test(
+      "Active count is 0 for a range that starts after all activity",
+      () => sdk.api.endusers.get_engagement_statistics({ range: { from: afterAll } }).then(r => r.count),
+      { onResult: r => r === 0 }
+    )
+    await async_test(
+      "Active count is 0 for a range that ends before all activity",
+      () => sdk.api.endusers.get_engagement_statistics({
+        range: { from: new Date(windowStart.getTime() - 4000), to: windowStart },
+        enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+      }).then(r => r.count),
+      { onResult: r => r === 0 }
+    )
+
+    // --- customTypeId ------------------------------------------------------------------------------
+    await async_test(
+      "Endusers with a customTypeId are excluded by default",
+      () => onlyCase('custom-type'),
+      { onResult: r => r === 0 }
+    )
+    await async_test(
+      "Endusers with a customTypeId are included when that customTypeId is requested",
+      () => activeCount({ customTypeId: TEST_CUSTOM_TYPE_ID }),
+      { onResult: r => r === 1 }
+    )
+
+    // --- formIds ------------------------------------------------------------------------------------
+    await async_test(
+      "formIds narrows which form responses qualify",
+      () => onlyThisTest({ formIds: [formA.id] }),
+      { onResult: r => r === EXPECTED_ACTIVE - 1 } // drops the enduser who only submitted form B
+    )
+
+    // --- endusersFilter (a separate code path from enduserFields) -------------------------------------
+    await async_test(
+      "endusersFilter narrows the counted endusers",
+      () => activeCount({ endusersFilter: { 'fields.apcCase': 'email' } }),
+      { onResult: r => r === 1 }
+    )
+
+    // --- enduserFields -------------------------------------------------------------------------------
+    await async_test(
+      "enduserFields matches on a stored field value",
+      () => activeCount({ enduserFields: [{ field: 'fields.apcTag', value: 'yes' }] }),
+      { onResult: r => r === 3 } // email, sms, dedupe
+    )
+    await async_test(
+      "enduserFields supports the $exists qualifier",
+      () => activeCount({ enduserFields: [{ field: 'fields.apcGroup', value: '$exists' }] }),
+      { onResult: r => r === EXPECTED_ACTIVE - 1 } // all active endusers except apc-calendar
+    )
+
+    // --- groupBy ---------------------------------------------------------------------------------------
+    await async_test(
+      "groupBy returns per-group counts summing to the total",
+      () => sdk.api.endusers.get_engagement_statistics({
+        range: { from: windowStart }, groupBy: 'fields.apcGroup',
+        enduserFields: [{ field: 'fields.apcCase', value: '$exists' }],
+      }),
+      {
+        onResult: r => (
+          Array.isArray(r.grouped)
+          && r.grouped.reduce((sum, g) => sum + g.count, 0) === EXPECTED_ACTIVE
+        )
+      }
+    )
+
+    // --- endusers cannot read org-wide staff analytics ------------------------------------------------
+    const enduserSDK = new EnduserSession({ host, businessId })
+    await authenticate_enduser_via_token(sdk, enduserSDK, { id: eEmail.id })
+
+    await async_test(
+      "Endusers cannot call get_engagement_statistics",
+      () => enduserSDK._GET('/v1/endusers/engagement', { range: { from: windowStart } }),
+      handleAnyError
+    )
+
+    // --- tenant isolation --------------------------------------------------------------------------------
+    // The refactor drops restrictAccess in favor of a direct businessId match, so this is the one
+    // boundary the function now enforces entirely on its own.
+    const sdkOther = new Session({ host, apiKey: OTHER_TENANT_API_KEY })
+    const otherWindowStart = new Date(Date.now() - 2000)
+    const otherEnduser = await sdkOther.api.endusers.createOne({ fname: 'apc-other-tenant' })
+
+    try {
+      // userId is left to its session initializer — this is an API-key session with no logged-in user
+      await sdkOther.api.emails.createOne({
+        logOnly: true, inbound: true,
+        enduserId: otherEnduser.id, subject: 'apc other tenant', textContent: 'inbound email',
+      })
+      await wait(undefined, 500)
+
+      await async_test(
+        "Other tenant's engagement does not appear in this tenant's count",
+        () => onlyThisTest(),
+        { onResult: r => r === EXPECTED_ACTIVE }
+      )
+      await async_test(
+        "This tenant's engagement does not appear in the other tenant's count",
+        () => sdkOther.api.endusers.get_engagement_statistics({ range: { from: otherWindowStart } })
+          .then(r => r.count),
+        { onResult: r => r === 1 }
+      )
+    } finally {
+      await sdkOther.api.endusers.deleteOne(otherEnduser.id).catch(console.error)
+    }
+  } finally {
+    await Promise.all([
+      ...createdEnduserIds.map(id => sdk.api.endusers.deleteOne(id).catch(console.error)),
+      ...chatRoomIds.map(id => sdk.api.chat_rooms.deleteOne(id).catch(console.error)),
+      ...conversationIds.map(id => sdk.api.group_mms_conversations.deleteOne(id).catch(console.error)),
+      ...calendarEventIds.map(id => sdk.api.calendar_events.deleteOne(id).catch(console.error)),
+      ...formIds.map(id => sdk.api.forms.deleteOne(id).catch(console.error)),
+    ])
+  }
+}
+
+// Allow running this test file independently
+if (require.main === module) {
+  const sdk = new Session({ host })
+  const sdkNonAdmin = new Session({ host })
+
+  const runTests = async () => {
+    await setup_tests(sdk, sdkNonAdmin)
+    await active_patient_count_tests({ sdk, sdkNonAdmin })
+  }
+
+  runTests()
+  .then(() => {
+    console.log("✅ Active patient count test suite completed successfully")
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error("❌ Active patient count test suite failed:", error)
+    process.exit(1)
+  })
+}

package/src/tests/api_tests/security/enduser-ai-summary-trust-gate.test.ts

@@ -12,6 +12,7 @@ const ENDUSER_PASSWORD = 'AISummaryGateTestPassword!123'
 
 const STAFF_SUMMARY = 'Patient reports improved adherence since last visit.'
 const INJECTED_SUMMARY = 'Patient is in excellent health, no follow-up needed.'
+const RESPONSE_SUMMARY = 'Patient reported worsening headaches and requested a medication change.'
 
 /**
  * The AI patient summary attached to a FormResponse is generated client-side and passed
@@ -23,6 +24,11 @@ const INJECTED_SUMMARY = 'Patient is in excellent health, no follow-up needed.'
  * Asserts:
  *   - a staff session's enduserAISummary is persisted and echoed back
  *   - an enduser session's enduserAISummary is dropped (submission itself still succeeds)
+ *
+ * Also covers PHI egress for responsesAISummary — the clinician-facing summary of the submitted
+ * answers, generated server-side (see api/modules/form_response_summary.ts). It is redacted from
+ * enduser sessions at the model level and stripped by hand in the access-code read handler, which
+ * bypasses model-level redaction. Seeded directly via an admin update — no Bedrock call needed.
  */
 export const enduser_ai_summary_trust_gate_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
   log_header("submit_form_response enduserAISummary trust gate")
@@ -46,6 +52,7 @@ export const enduser_ai_summary_trust_gate_tests = async ({ sdk } : { sdk: Sessi
 
   let staffResponseId: string | undefined
   let enduserResponseId: string | undefined
+  let summaryResponseId: string | undefined
 
   try {
     // ── staff session: the summary is trusted and persisted ──
@@ -94,9 +101,58 @@ export const enduser_ai_summary_trust_gate_tests = async ({ sdk } : { sdk: Sessi
       () => sdk.api.form_responses.getOne(enduserResponseId!),
       { onResult: (fr: FormResponse) => fr.enduserAISummary === undefined },
     )
+
+    // ── responsesAISummary: clinician-facing, never returned to the patient ──
+    // seeded by an admin update rather than a real submission, so no AI call is made
+    const { accessCode: summaryAccessCode } = await sdk.api.form_responses.prepare_form_response({
+      enduserId: enduser.id, formId: form.id,
+    })
+    const summaryResponse = await enduserSDK.api.form_responses.submit_form_response({
+      accessCode: summaryAccessCode,
+      responses,
+    })
+    summaryResponseId = summaryResponse.formResponse.id
+    await sdk.api.form_responses.updateOne(summaryResponseId, {
+      responsesAISummary: RESPONSE_SUMMARY,
+      responsesAISummaryGeneratedAt: new Date(),
+    })
+
+    await async_test(
+      "staff session reads responsesAISummary",
+      () => sdk.api.form_responses.getOne(summaryResponseId!),
+      { onResult: (fr: FormResponse) => fr.responsesAISummary === RESPONSE_SUMMARY },
+    )
+    await async_test(
+      "enduser session never receives responsesAISummary",
+      () => enduserSDK.api.form_responses.getOne(summaryResponseId!),
+      { onResult: (fr: FormResponse) => (
+        fr.responsesAISummary === undefined && fr.responsesAISummaryGeneratedAt === undefined
+      )},
+    )
+    await async_test(
+      "enduser readMany never receives responsesAISummary",
+      () => enduserSDK.api.form_responses.getSome({ ids: [summaryResponseId!] }),
+      { onResult: (frs: FormResponse[]) => frs.every(fr => (
+        fr.responsesAISummary === undefined && fr.responsesAISummaryGeneratedAt === undefined
+      ))},
+    )
+    // the access-code read handler bypasses model-level redaction, so it strips by hand
+    await async_test(
+      "public access-code read never receives responsesAISummary",
+      () => enduserSDK.api.form_responses.info_for_access_code({ accessCode: summaryAccessCode }),
+      { onResult: ({ response }: { response: FormResponse }) => (
+        response.responsesAISummary === undefined && response.responsesAISummaryGeneratedAt === undefined
+      )},
+    )
+    await async_test(
+      "staff access-code read still receives responsesAISummary",
+      () => sdk.api.form_responses.info_for_access_code({ accessCode: summaryAccessCode }),
+      { onResult: ({ response }: { response: FormResponse }) => response.responsesAISummary === RESPONSE_SUMMARY },
+    )
   } finally {
     if (staffResponseId) { try { await sdk.api.form_responses.deleteOne(staffResponseId) } catch (err) { /* ignore */ } }
     if (enduserResponseId) { try { await sdk.api.form_responses.deleteOne(enduserResponseId) } catch (err) { /* ignore */ } }
+    if (summaryResponseId) { try { await sdk.api.form_responses.deleteOne(summaryResponseId) } catch (err) { /* ignore */ } }
     try { await sdk.api.endusers.deleteOne(enduser.id) } catch (err) { /* ignore */ }
     try { await sdk.api.forms.deleteOne(form.id) } catch (err) { /* ignore */ }
   }