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

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

@@ -1,94 +1,154 @@
 require('source-map-support').install();
 
-import { Session, EnduserSession } from "../../sdk"
-import {
-  async_test,
-  log_header,
-} from "@tellescope/testing"
+import { EnduserSession } from "../../sdk"
 import { STEDI_TITLE } from "@tellescope/constants"
-import { authenticate_enduser_via_token, setup_tests } from "../setup"
+import {
+  assert_checks,
+  Check,
+  IsolatedSuite,
+  setup_isolated_tenant,
+} from "../setup_isolated"
 
 const host = process.env.API_URL || 'http://localhost:8080' as const
 
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
 // Stedi runs on Tellescope's own platform credentials (zz_secrets) and each eligibility check costs
 // Tellescope $0.10, so an organization must be approved by a Tellescope super admin
 // (Organization.stediAllowed) before any Stedi call is made on its behalf.
 //
 // Every assertion here is a REJECTION assertion, so nothing in this file ever reaches Stedi.
-export const stedi_approval_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Stedi Pre-Approval (stediAllowed) Tests")
-
-  const orgId = sdk.userInfo.businessId
-  const businessId = orgId
-
-  // A. Super-admin write gate.
-  //
-  // `isa` is only minted by GET /switch-tenant, so this plainly-authenticated admin session never
-  // has it — even when TEST_EMAIL happens to be in the API's SUPER_ADMINS allowlist.
-  log_header("A. stediAllowed is writable by super admins only")
-
-  await async_test(
-    "org admin cannot enable stediAllowed for their own organization",
-    () => sdk.api.organizations.updateOne(orgId, { stediAllowed: true }),
-    { shouldError: true, onError: (e: { message: string }) => /not allowed/i.test(e.message) }
-  )
+//
+// Runs on its own provisioned tenant: section B's whole premise is "this organization is NOT
+// Stedi-approved", which on the shared fixture is whatever the last developer left in their local
+// database. A freshly provisioned tenant is never approved (the provisioner cannot write
+// stediAllowed — it is not in its organization allowlist), so the skip branch that used to report
+// green without asserting anything is now a FAILING check instead.
+export const stedi_approval_checks = async (): Promise<Check[]> => {
+  const checks: Check[] = []
+  const record = (label: string, pass: boolean, detail: string) => checks.push({ label, pass, detail })
+
+  /**
+   * The async_test({ shouldError: true, onError }) equivalent, as a soft Check: a call that RESOLVES
+   * is a failure (async_test treats it the same way), and a rejection passes only when onError agrees.
+   */
+  const expect_rejected = async (label: string, fn: () => Promise<any>, onError: (e: any) => boolean) => {
+    let rejection: { e: any }
+    try {
+      const unexpected = await fn()
+      record(
+        label,
+        false,
+        `resolved instead of rejecting; result=${unexpected === undefined ? '(none)' : JSON.stringify(unexpected)}`,
+      )
+      return
+    } catch (e: any) {
+      rejection = { e }
+    }
+
+    // Outside the catch on purpose: a predicate that throws here would otherwise escape the suite
+    // and, per run_isolated_in_parallel, abort every remaining batch instead of failing one check.
+    // The raw value decides the fallback, not JSON.stringify of it — JSON.stringify('') is '""',
+    // which is truthy, so a `|| fallback` on the stringified form can never fire.
+    const { e } = rejection
+    const message = typeof e?.message === 'string' && e.message !== ''
+      ? e.message
+      : (e === undefined || e === null ? String(e) : JSON.stringify(e))
+    record(label, onError(e), `rejected with ${message}`)
+  }
 
-  // Regression test for the truthiness hole in the shared super-admin relationship constraint:
-  // it used to test `options.updates?.stediAllowed` (falsy for `false`), so an org admin could
-  // clear super-admin-owned flags even though they could never set them.
-  await async_test(
-    "org admin cannot disable stediAllowed either (guard is key-presence, not truthiness)",
-    () => sdk.api.organizations.updateOne(orgId, { stediAllowed: false }),
-    { shouldError: true, onError: (e: { message: string }) => /not allowed/i.test(e.message) }
+  const rejectedAsNotAllowed = (e: any) => /not allowed/i.test(typeof e?.message === 'string' ? e.message : '')
+  const rejectedAsNotEnabled = (e: any) => (
+    /not enabled for this organization/i.test(typeof e?.message === 'string' ? e.message : '')
   )
 
-  // Same bug, pre-existing field — proves the fix wasn't scoped to the new flag only.
-  await async_test(
-    "org admin cannot disable bedrockAIAllowed",
-    () => sdk.api.organizations.updateOne(orgId, { bedrockAIAllowed: false }),
-    { shouldError: true, onError: (e: { message: string }) => /not allowed/i.test(e.message) }
-  )
+  let tenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+  let enduserId: string | undefined
 
-  // ...and that it covers the whole gated list, not just the two booleans.
-  await async_test(
-    "org admin cannot disable allowCreateSuborganizations",
-    () => sdk.api.organizations.updateOne(orgId, { allowCreateSuborganizations: false }),
-    { shouldError: true, onError: (e: { message: string }) => /not allowed/i.test(e.message) }
-  )
+  try {
+    tenant = await setup_isolated_tenant({
+      name: `Stedi approval gate ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+    const orgId = tenant.businessId
+
+    // A. Super-admin write gate.
+    //
+    // `isa` is only minted by GET /switch-tenant, so this plainly-authenticated admin session never
+    // has it — and a provisioned tenant's throwaway admin is in no SUPER_ADMINS allowlist either.
+    //
+    // The four updates are deliberately DISTINCT (id, updates) pairs: identical ones throttle at
+    // 3 per 30s and the fourth would be rejected by the throttle rather than by the guard.
+
+    await expect_rejected(
+      "org admin cannot enable stediAllowed for their own organization",
+      () => sdk.api.organizations.updateOne(orgId, { stediAllowed: true }),
+      rejectedAsNotAllowed,
+    )
 
-  // B. An unapproved organization is rejected at every Stedi entry point.
-  log_header("B. Unapproved organizations cannot reach Stedi")
+    // Regression test for the truthiness hole in the shared super-admin relationship constraint:
+    // it used to test `options.updates?.stediAllowed` (falsy for `false`), so an org admin could
+    // clear super-admin-owned flags even though they could never set them.
+    await expect_rejected(
+      "org admin cannot disable stediAllowed either (guard is key-presence, not truthiness)",
+      () => sdk.api.organizations.updateOne(orgId, { stediAllowed: false }),
+      rejectedAsNotAllowed,
+    )
 
-  const organization = await sdk.api.organizations.getOne(orgId)
-  if (organization.stediAllowed) {
-    console.log(
-      "⚠️  SKIPPING section B: the test organization already has stediAllowed=true "
-      + "(hand-toggled in this dev database). Turn it off in the super admin console and re-run — "
-      + "these assertions would otherwise report a false pass."
+    // Same bug, pre-existing field — proves the fix wasn't scoped to the new flag only.
+    await expect_rejected(
+      "org admin cannot disable bedrockAIAllowed",
+      () => sdk.api.organizations.updateOne(orgId, { bedrockAIAllowed: false }),
+      rejectedAsNotAllowed,
     )
-    return
-  }
 
-  const enduser = await sdk.api.endusers.createOne({
-    email: `stedi-approval-${Date.now()}@test.tellescope.com`,
-    fname: 'Stedi',
-    lname: 'Approval',
-  })
+    // ...and that it covers the whole gated list, not just the two booleans.
+    await expect_rejected(
+      "org admin cannot disable allowCreateSuborganizations",
+      () => sdk.api.organizations.updateOne(orgId, { allowCreateSuborganizations: false }),
+      rejectedAsNotAllowed,
+    )
 
-  try {
-    await async_test(
+    // B. An unapproved organization is rejected at every Stedi entry point.
+
+    const organization = await sdk.api.organizations.getOne(orgId)
+    if (organization.stediAllowed) {
+      // Previously a console warning and an early return, which reported green without asserting
+      // anything. On a tenant this suite provisioned seconds ago it is a real defect — the
+      // provisioner has started granting a super-admin-only flag — so it fails loudly and the
+      // section-B checks below are NOT run (they would all pass for the wrong reason).
+      record(
+        'the freshly provisioned organization is not Stedi-approved',
+        false,
+        'stediAllowed=true on a tenant this suite just provisioned, so the five Stedi entry-point '
+        + 'rejections below would report a false pass and were skipped. Nothing in the provisioning '
+        + 'path may set stediAllowed — it is a Tellescope super-admin flag.',
+      )
+      return checks
+    }
+
+    const enduser = await sdk.api.endusers.createOne({
+      email: `stedi-approval-${Date.now()}@test.tellescope.com`,
+      fname: 'Stedi',
+      lname: 'Approval',
+    })
+    enduserId = enduser.id
+
+    await expect_rejected(
       "staff: Stedi payer search (proxy_read) is rejected",
       () => sdk.api.integrations.proxy_read({ integration: STEDI_TITLE, type: 'payers', query: 'aetna' }),
-      { shouldError: true, onError: (e: { message: string }) => /not enabled for this organization/i.test(e.message) }
+      rejectedAsNotEnabled,
     )
 
-    await async_test(
+    await expect_rejected(
       "staff: Stedi payer importer (load_payers) is rejected",
       () => sdk.api.integrations.load_payers({ integration: STEDI_TITLE, query: 'aetna' }),
-      { shouldError: true, onError: (e: { message: string }) => /not enabled for this organization/i.test(e.message) }
+      rejectedAsNotEnabled,
     )
 
-    await async_test(
+    await expect_rejected(
       "staff: Stedi eligibility check is rejected on approval, before the credit checks",
       () => sdk.api.integrations.proxy_read({
         integration: STEDI_TITLE,
@@ -96,66 +156,72 @@ export const stedi_approval_tests = async ({ sdk, sdkNonAdmin } : { sdk: Session
         id: enduser.id,
         query: JSON.stringify({ serviceCode: '30', npi: '1234567890' }),
       }),
-      {
-        shouldError: true,
-        // The absence of /credit/ is the real assertion: it proves the approval gate fires ahead of
-        // the credit gate, so an unapproved org is never told to go buy credits.
-        onError: (e: { message: string }) => (
-          /not enabled for this organization/i.test(e.message) && !/credit/i.test(e.message)
-        ),
-      }
+      // The absence of /credit/ is the real assertion: it proves the approval gate fires ahead of
+      // the credit gate, so an unapproved org is never told to go buy credits.
+      (e: any) => rejectedAsNotEnabled(e) && !/credit/i.test(typeof e?.message === 'string' ? e.message : ''),
     )
 
     // Enduser sessions reach both branches for real: StediEligibilityInput auto-runs the check, and
     // InsuranceInput search-on-types against the payer branch. Approval/billing state must not leak
     // to patients.
-    const enduserSdk = new EnduserSession({ host, businessId })
-    await authenticate_enduser_via_token(sdk, enduserSdk, { id: enduser.id })
+    //
+    // The session is minted from endusers.generate_auth_token rather than imported from setup.ts
+    // (this suite shares nothing with the hand-seeded fixture) and rather than a password login
+    // (/login-enduser throttles 20/min per IP, and the pool runs 8 suites from one IP).
+    const { authToken, enduser: enduserInfo } = await sdk.api.endusers.generate_auth_token({ id: enduser.id })
+    const enduserSdk = new EnduserSession({ host, authToken, enduser: enduserInfo, businessId: tenant.businessId })
 
     // Exact-match on the generic copy: no "Stedi", no "credits", no "contact sales", no mention that
     // approval is the reason. Note this is deliberately the SAME string the enduser-facing credit
     // rejection uses, so it cannot prove which gate fired — the staff assertion above is what pins
     // down the approval-before-credits ordering.
-    const messageIsGenericForEnduser = (e: { message: string }) => (
-      e.message === 'Eligibility check is currently unavailable'
-    )
+    const messageIsGenericForEnduser = (e: any) => e?.message === 'Eligibility check is currently unavailable'
 
-    await async_test(
+    await expect_rejected(
       "enduser: eligibility check rejected with a generic message (no approval/billing leak)",
       () => enduserSdk.api.integrations.proxy_read({
         integration: STEDI_TITLE,
         type: 'stedi-eligibility',
         query: JSON.stringify({ serviceCode: '30', npi: '1234567890' }),
       }),
-      { shouldError: true, onError: messageIsGenericForEnduser }
+      messageIsGenericForEnduser,
     )
 
-    await async_test(
+    await expect_rejected(
       "enduser: payer search rejected with a generic message (no approval/billing leak)",
       () => enduserSdk.api.integrations.proxy_read({
         integration: STEDI_TITLE,
         type: 'payers',
         query: 'aetna',
       }),
-      { shouldError: true, onError: messageIsGenericForEnduser }
+      messageIsGenericForEnduser,
     )
   } finally {
-    await sdk.api.endusers.deleteOne(enduser.id).catch(console.error)
+    if (tenant) {
+      if (enduserId) await tenant.sdk.api.endusers.deleteOne(enduserId).catch(console.error)
+      // Teardown BEFORE anything asserts — assert calls process.exit, which would strand this tenant.
+      try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) }
+    }
   }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs. */
+export const stedi_approval_tests = async () => {
+  assert_checks('Stedi approval gate', await stedi_approval_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Stedi approval gate',
+  run: stedi_approval_checks,
 }
 
 // Allow running this test file independently
 if (require.main === module) {
   console.log(`Using API URL: ${host}`)
-  const sdk = new Session({ host })
-  const sdkNonAdmin = new Session({ host })
-
-  const runTests = async () => {
-    await setup_tests(sdk, sdkNonAdmin)
-    await stedi_approval_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  stedi_approval_tests()
     .then(() => {
       console.log("✅ Stedi pre-approval tests completed successfully")
       process.exit(0)

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

@@ -0,0 +1,314 @@
+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)
+
+/**
+ * Coverage for coupling a ticket's Stage to real archival (CU-86e3hhavw).
+ *
+ * Stage: Archived used to be cosmetic — only the Archive Ticket button set archiveReason + closedAt
+ * + closedBy, and only that real archival stops a Journey advancing to its next step
+ * (handleTicketClosed skips a ticket whose archiveReason is set). Customers staged tickets Archived
+ * and expected them to be archived. The generic update route in api/modules/routing.ts now folds the
+ * archival into `updates` before the `$set`, so the archived state is part of the same write and is
+ * visible to the PATCH response, the webhooks and every v2 side effect.
+ *
+ * A: changing the stage to Archived archives the ticket, and says so in the PATCH response.
+ * B: changing the stage off Archived un-archives it (the Un-Archive button's payload).
+ * C: an already-Completed ticket keeps the closedAt it was actually closed at.
+ * D: repeating the stage change does not rewrite the reason or the timestamp.
+ * E: an explicit archiveReason in the same payload is not overwritten.
+ * F: with organization.settings.tickets.allowArchival off (the default, and so what every existing
+ *    organization sees until it opts in), Stage: Archived behaves exactly as it did before.
+ * G: a queued ticket archives and stays in its queue — parity with the Archive Ticket button.
+ * H: a payload that re-states closedAt (the Edit Ticket form, or any full-record PATCH) is not a
+ *    move off Archived, while the Stage select's stage-only payload still is.
+ */
+
+/** The queue count is maintained by asynchronous side effects, so reads of it poll. */
+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 ticket_stage_archive_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
+  let noArchivalTenant: Awaited<ReturnType<typeof setup_isolated_tenant>> | undefined
+
+  try {
+    ;[tenant, noArchivalTenant] = await Promise.all([
+      setup_isolated_tenant({ name: `StageArchive ${RAND()}`, users: [{ isAdmin: true }], apiKeys: 0 }),
+      setup_isolated_tenant({ name: `StageArchive off ${RAND()}`, users: [{ isAdmin: true }], apiKeys: 0 }),
+    ])
+
+    const { sdk } = tenant
+    const adminId = tenant.users[0].id
+
+    // archival is off by default — this tenant opts in, noArchivalTenant deliberately does not
+    await sdk.api.organizations.updateOne(sdk.userInfo.businessId, {
+      settings: { tickets: { allowArchival: true } },
+    } as any)
+
+    const settings = await sdk.api.organizations.getOne(sdk.userInfo.businessId)
+    record(
+      'setup: allowArchival is enabled for the primary tenant',
+      settings.settings?.tickets?.allowArchival === true,
+      `allowArchival=${JSON.stringify(settings.settings?.tickets?.allowArchival)}`,
+    )
+
+    /* ===== A: Stage -> Archived archives the ticket ===== */
+
+    const ticket = await sdk.api.tickets.createOne({ title: `Stage archive ${RAND()}` })
+    record(
+      'setup: a new ticket is open and unarchived',
+      !ticket.closedAt && !ticket.archiveReason,
+      `closedAt=${JSON.stringify(ticket.closedAt)} archiveReason=${JSON.stringify(ticket.archiveReason)}`,
+    )
+
+    const archivedResponse = await sdk.api.tickets.updateOne(ticket.id, { stage: 'Archived' })
+    record(
+      'A1: the PATCH response already reflects the archival',
+      archivedResponse.archiveReason === 'Stage set to Archived'
+        && !!archivedResponse.closedAt
+        && archivedResponse.closedBy === adminId,
+      `response archiveReason=${JSON.stringify(archivedResponse.archiveReason)}`
+      + ` closedAt=${JSON.stringify(archivedResponse.closedAt)} closedBy=${JSON.stringify(archivedResponse.closedBy)}`
+      + ` — a side effect instead of a folded update would leave these unset here, and would land after`
+      + ` the Journey next-step check`,
+    )
+
+    const archived = await sdk.api.tickets.getOne(ticket.id)
+    record(
+      'A2: the stored ticket is archived: reason, closedAt and closedBy all set',
+      archived.stage === 'Archived'
+        && archived.archiveReason === 'Stage set to Archived'
+        && !!archived.closedAt
+        && archived.closedBy === adminId,
+      `stage=${JSON.stringify(archived.stage)} archiveReason=${JSON.stringify(archived.archiveReason)}`
+      + ` closedAt=${JSON.stringify(archived.closedAt)} closedBy=${JSON.stringify(archived.closedBy)} (want closedBy=${adminId})`,
+    )
+
+    /* ===== B: Stage -> anything else un-archives ===== */
+
+    const unarchived = await sdk.api.tickets.updateOne(ticket.id, { stage: 'In Progress' })
+    record(
+      'B1: moving off Archived clears the reason, closedAt and closedBy',
+      unarchived.stage === 'In Progress'
+        && !unarchived.archiveReason
+        && !unarchived.closedAt
+        && !unarchived.closedBy,
+      `stage=${JSON.stringify(unarchived.stage)} archiveReason=${JSON.stringify(unarchived.archiveReason)}`
+      + ` closedAt=${JSON.stringify(unarchived.closedAt)} closedBy=${JSON.stringify(unarchived.closedBy)}`,
+    )
+
+    const unarchivedStored = await sdk.api.tickets.getOne(ticket.id)
+    record(
+      'B2: the un-archival is stored, not only echoed',
+      !unarchivedStored.archiveReason && !unarchivedStored.closedAt && !unarchivedStored.closedBy,
+      `archiveReason=${JSON.stringify(unarchivedStored.archiveReason)}`
+      + ` closedAt=${JSON.stringify(unarchivedStored.closedAt)} closedBy=${JSON.stringify(unarchivedStored.closedBy)}`
+      + ` — null/undefined would be dropped from the update rather than written`,
+    )
+
+    // a stage change on a ticket that was never archived must not touch anything else
+    const neverArchived = await sdk.api.tickets.createOne({ title: `Stage plain ${RAND()}` })
+    const plainStage = await sdk.api.tickets.updateOne(neverArchived.id, { stage: 'Blocked' })
+    record(
+      'B3: a stage change on an open, never-archived ticket changes only the stage',
+      plainStage.stage === 'Blocked' && !plainStage.closedAt && !plainStage.archiveReason,
+      `stage=${JSON.stringify(plainStage.stage)} closedAt=${JSON.stringify(plainStage.closedAt)}`
+      + ` archiveReason=${JSON.stringify(plainStage.archiveReason)}`,
+    )
+
+    /* ===== C: an already-Completed ticket keeps its closedAt ===== */
+
+    const completedAt = new Date(Date.now() - 1000 * 60 * 60 * 24 * 7) // a week ago
+    const completed = await sdk.api.tickets.createOne({ title: `Stage archive completed ${RAND()}` })
+    await sdk.api.tickets.updateOne(completed.id, { closedAt: completedAt, closedBy: adminId })
+
+    const completedThenArchived = await sdk.api.tickets.updateOne(completed.id, { stage: 'Archived' })
+    const storedClosedAt = new Date(completedThenArchived.closedAt as any).getTime()
+    record(
+      'C1: archiving an already-Completed ticket preserves its original closedAt',
+      completedThenArchived.archiveReason === 'Stage set to Archived'
+        && storedClosedAt === completedAt.getTime(),
+      `closedAt=${JSON.stringify(completedThenArchived.closedAt)} (want ${completedAt.toISOString()});`
+      + ` archiveReason=${JSON.stringify(completedThenArchived.archiveReason)}`
+      + ` — overwriting it would move the Closed date to today`,
+    )
+
+    /* ===== D: repeating the stage change is a no-op ===== */
+
+    const reArchived = await sdk.api.tickets.updateOne(completed.id, { stage: 'Archived' })
+    record(
+      'D1: setting the stage to Archived a second time rewrites neither the reason nor closedAt',
+      reArchived.archiveReason === 'Stage set to Archived'
+        && new Date(reArchived.closedAt as any).getTime() === completedAt.getTime(),
+      `archiveReason=${JSON.stringify(reArchived.archiveReason)} closedAt=${JSON.stringify(reArchived.closedAt)}`
+      + ` (want ${completedAt.toISOString()})`,
+    )
+
+    /* ===== E: an explicit archiveReason in the same payload wins ===== */
+
+    const explicit = await sdk.api.tickets.createOne({ title: `Stage archive explicit ${RAND()}` })
+    const explicitArchived = await sdk.api.tickets.updateOne(explicit.id, {
+      stage: 'Archived', archiveReason: 'Duplicate of another ticket',
+    })
+    record(
+      'E1: an archiveReason supplied with the stage is not replaced by the default',
+      explicitArchived.archiveReason === 'Duplicate of another ticket' && !!explicitArchived.closedAt,
+      `archiveReason=${JSON.stringify(explicitArchived.archiveReason)} closedAt=${JSON.stringify(explicitArchived.closedAt)}`,
+    )
+
+    /* ===== H: a full-record PATCH is not a move off Archived ===== */
+
+    // The Edit Ticket form submits every field of the record it loaded, including `stage` and
+    // `closedAt`, whose inputs are hidden for a closed ticket. On a ticket archived from the Archive
+    // Ticket button — which never writes stage, so the stage is still 'In Progress' or the like —
+    // that payload must not be read as a stage change off Archived. The same goes for any API
+    // consumer that PATCHes a whole ticket record back.
+    const buttonArchived = await sdk.api.tickets.createOne({
+      title: `Stage archive button ${RAND()}`, stage: 'In Progress',
+    })
+    const buttonClosedAt = new Date(Date.now() - 1000 * 60 * 60) // an hour ago
+    await sdk.api.tickets.updateOne(buttonArchived.id, {
+      archiveReason: 'Archived from the button', closedAt: buttonClosedAt, closedBy: adminId,
+    })
+
+    const editedTitle = `Stage archive button edited ${RAND()}`
+    const edited = await sdk.api.tickets.updateOne(buttonArchived.id, {
+      title: editedTitle, stage: 'In Progress', closedAt: buttonClosedAt, // exactly the editor's payload
+    })
+    record(
+      'H1: editing an archived ticket (full record, stage unchanged) does not un-archive it',
+      edited.title === editedTitle
+        && edited.archiveReason === 'Archived from the button'
+        && new Date(edited.closedAt as any).getTime() === buttonClosedAt.getTime()
+        && edited.closedBy === adminId,
+      `title=${JSON.stringify(edited.title)} archiveReason=${JSON.stringify(edited.archiveReason)}`
+      + ` closedAt=${JSON.stringify(edited.closedAt)} (want ${buttonClosedAt.toISOString()}) closedBy=${JSON.stringify(edited.closedBy)}`
+      + ` — a bare stage comparison here would re-open the ticket and wipe its archive reason`,
+    )
+
+    // but the Stage column's select — which sends the stage on its own — still un-archives it
+    const unarchivedFromColumn = await sdk.api.tickets.updateOne(buttonArchived.id, { stage: 'Blocked' })
+    record(
+      'H2: the Stage select still un-archives a button-archived ticket (stage alone, no closedAt)',
+      unarchivedFromColumn.stage === 'Blocked'
+        && !unarchivedFromColumn.archiveReason
+        && !unarchivedFromColumn.closedAt
+        && !unarchivedFromColumn.closedBy,
+      `stage=${JSON.stringify(unarchivedFromColumn.stage)} archiveReason=${JSON.stringify(unarchivedFromColumn.archiveReason)}`
+      + ` closedAt=${JSON.stringify(unarchivedFromColumn.closedAt)} closedBy=${JSON.stringify(unarchivedFromColumn.closedBy)}`,
+    )
+
+    /* ===== G: a queued ticket archives, and stays in its queue ===== */
+
+    // parity with the Archive Ticket button, which also leaves queue membership and the queue count
+    // alone — unlike close_ticket, which refuses outright for a queued ticket
+    const queue = await sdk.api.ticket_queues.createOne({ title: `Stage archive queue ${RAND()}`, userIds: [adminId] })
+    const queued = await sdk.api.tickets.createOne({ title: `Stage archive queued ${RAND()}`, queueId: queue.id })
+
+    // the queue count is maintained by asynchronous side effects
+    const countBefore = await poll_for(
+      () => sdk.api.ticket_queues.getOne(queue.id).then(q => q.count ?? 0),
+      c => c === 1,
+    )
+
+    const queuedArchived = await sdk.api.tickets.updateOne(queued.id, { stage: 'Archived' })
+    // poll for a WRONG value rather than a right one: a decrement landing a moment later must fail
+    // this check, not slip past a single immediate read
+    const countAfter = await poll_for(
+      () => sdk.api.ticket_queues.getOne(queue.id).then(q => q.count ?? 0),
+      c => c !== 1,
+      8, // ~2s of settling
+    )
+    record(
+      'G1: a queued ticket archives, keeping its queue membership and the queue count',
+      queuedArchived.archiveReason === 'Stage set to Archived'
+        && !!queuedArchived.closedAt
+        && queuedArchived.queueId === queue.id
+        && countBefore === 1 && countAfter === 1,
+      `archiveReason=${JSON.stringify(queuedArchived.archiveReason)} closedAt=${JSON.stringify(queuedArchived.closedAt)}`
+      + ` queueId=${JSON.stringify(queuedArchived.queueId)} (want ${queue.id}); count ${countBefore} -> ${countAfter} (want 1 -> 1)`,
+    )
+
+    /* ===== F: with archival disabled, nothing changes ===== */
+
+    const offSdk = noArchivalTenant.sdk
+    const offOrg = await offSdk.api.organizations.getOne(offSdk.userInfo.businessId)
+    record(
+      'F1: a newly provisioned organization has archival off',
+      !offOrg.settings?.tickets?.allowArchival,
+      `allowArchival=${JSON.stringify(offOrg.settings?.tickets?.allowArchival)} — the setting must stay opt-in`,
+    )
+
+    const offTicket = await offSdk.api.tickets.createOne({ title: `Stage archive off ${RAND()}` })
+    const offArchived = await offSdk.api.tickets.updateOne(offTicket.id, { stage: 'Archived' })
+    record(
+      'F2: without allowArchival, Stage: Archived stays cosmetic — the ticket is still open',
+      offArchived.stage === 'Archived' && !offArchived.closedAt && !offArchived.archiveReason && !offArchived.closedBy,
+      `stage=${JSON.stringify(offArchived.stage)} closedAt=${JSON.stringify(offArchived.closedAt)}`
+      + ` archiveReason=${JSON.stringify(offArchived.archiveReason)} closedBy=${JSON.stringify(offArchived.closedBy)}`,
+    )
+
+    // and an archived ticket in such an organization is not re-opened by a stage change either
+    const offArchivedByButton = await offSdk.api.tickets.createOne({ title: `Stage archive off button ${RAND()}` })
+    await offSdk.api.tickets.updateOne(offArchivedByButton.id, {
+      archiveReason: 'Archived by the button', closedAt: new Date(), closedBy: noArchivalTenant.users[0].id,
+    })
+    const offUnarchiveAttempt = await offSdk.api.tickets.updateOne(offArchivedByButton.id, { stage: 'In Progress' })
+    record(
+      'F3: without allowArchival, moving off Archived does not un-archive',
+      offUnarchiveAttempt.stage === 'In Progress'
+        && offUnarchiveAttempt.archiveReason === 'Archived by the button'
+        && !!offUnarchiveAttempt.closedAt,
+      `stage=${JSON.stringify(offUnarchiveAttempt.stage)} archiveReason=${JSON.stringify(offUnarchiveAttempt.archiveReason)}`
+      + ` closedAt=${JSON.stringify(offUnarchiveAttempt.closedAt)}`,
+    )
+  } finally {
+    // Teardown BEFORE anything asserts — assert calls process.exit, which would strand these tenants.
+    for (const t of [tenant, noArchivalTenant]) {
+      if (t) { try { await t.teardown() } catch (e) { console.error('teardown failed', e) } }
+    }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const ticket_stage_archive_tests = async () => {
+  assert_checks('Ticket stage archival', await ticket_stage_archive_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'Ticket stage archival', run: ticket_stage_archive_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  ticket_stage_archive_tests()
+    .then(() => {
+      console.log("✅ Ticket stage archival test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ Ticket stage archival test suite failed:", error)
+      process.exit(1)
+    })
+}