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

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

@@ -1,138 +1,191 @@
-import { Session } from "../../sdk"
-import { log_header, wait, async_test } from "@tellescope/testing"
+require('source-map-support').install();
+
 import { Enduser } from "@tellescope/types-client"
-import { setup_tests } from "../setup"
-
-const host = process.env.API_URL || "http://localhost:8080"
-
-// Covers the event-wide "Appointment No-Showed" trigger path (handle_no_showed_event), which had
-// no dedicated test. Mirrors appointment_completed_trigger.test.ts.
-export const appointment_no_showed_trigger_tests = async ({ sdk } : { sdk: Session, sdkNonAdmin: Session }) => {
-  log_header("Automation Trigger Tests (Appointment No-Showed)")
-
-  const t1 = await sdk.api.automation_triggers.createOne({
-    event: { type: 'Appointment No-Showed', info: {} },
-    action: { type: 'Add Tags', info: { tags: ['No-Show - Any'] } },
-    status: 'Active',
-    title: "No-Show - Any",
-  })
-  const t2 = await sdk.api.automation_triggers.createOne({
-    event: { type: 'Appointment No-Showed', info: { titles: ['Test Appointment'] } },
-    action: { type: 'Add Tags', info: { tags: ['No-Show - By Title'] } },
-    status: 'Active',
-    title: "No-Show - By Title",
-  })
-  const template = await sdk.api.calendar_event_templates.createOne({
-    title: 'No-Show Template',
-    durationInMinutes: 30,
-  })
-  const t3 = await sdk.api.automation_triggers.createOne({
-    event: { type: 'Appointment No-Showed', info: { templateIds: [template.id] } },
-    action: { type: 'Add Tags', info: { tags: ['No-Show - By Template'] } },
-    status: 'Active',
-    title: "No-Show - By Template",
-  })
-
-  // Separate endusers to avoid per-trigger throttling (1 min per trigger per enduser)
-  const enduser1 = await sdk.api.endusers.createOne({})
-  const enduser2 = await sdk.api.endusers.createOne({})
-  const enduser3 = await sdk.api.endusers.createOne({})
-
-  // Note: the "Appointment No-Showed" trigger fires only on UPDATE (handle_no_showed_event);
-  // there is no create-time no-show path, so every case creates a normal event then updates it.
-
-  // Test 1: Update to no-showed by title (should trigger Any + By Title)
-  const event1 = await sdk.api.calendar_events.createOne({
-    title: 'Test Appointment',
-    durationInMinutes: 30,
-    startTimeInMS: Date.now(),
-    attendees: [{ type: 'enduser', id: enduser1.id }],
-  })
-  await wait(undefined, 500)
-  await async_test(
-    "No initial triggers before no-show",
-    () => sdk.api.endusers.getOne(enduser1.id),
-    { onResult: (e: Enduser) => !e.tags?.length }
-  )
-  await sdk.api.calendar_events.updateOne(event1.id, { noShowedAt: new Date() })
-  await wait(undefined, 500)
-  await async_test(
-    "Update to no-showed triggers automation (Any + By Title)",
-    () => sdk.api.endusers.getOne(enduser1.id),
-    { onResult: (e: Enduser) =>
-        e.tags?.length === 2
-     && e.tags.includes('No-Show - Any')
-     && e.tags.includes('No-Show - By Title')
-    }
-  )
-
-  // Test 2: Template-based no-show (should trigger Any + By Template)
-  const event2 = await sdk.api.calendar_events.createOne({
-    title: 'Template Test',
-    durationInMinutes: 30,
-    startTimeInMS: Date.now(),
-    attendees: [{ type: 'enduser', id: enduser2.id }],
-    templateId: template.id,
-  })
-  await wait(undefined, 500)
-  await sdk.api.calendar_events.updateOne(event2.id, { noShowedAt: new Date() })
-  await wait(undefined, 500)
-  await async_test(
-    "Template-based no-showed appointment triggers automation (Any + By Template)",
-    () => sdk.api.endusers.getOne(enduser2.id),
-    { onResult: (e: Enduser) =>
-        e.tags?.length === 2
-     && e.tags.includes('No-Show - Any')
-     && e.tags.includes('No-Show - By Template')
-    }
-  )
-
-  // Test 3: Non-matching title only fires the "Any" trigger
-  const event3 = await sdk.api.calendar_events.createOne({
-    title: 'Other Title',
-    durationInMinutes: 30,
-    startTimeInMS: Date.now(),
-    attendees: [{ type: 'enduser', id: enduser3.id }],
-  })
-  await wait(undefined, 500)
-  await sdk.api.calendar_events.updateOne(event3.id, { noShowedAt: new Date() })
-  await wait(undefined, 500)
-  await async_test(
-    "No-show with non-matching title fires only the Any trigger",
-    () => sdk.api.endusers.getOne(enduser3.id),
-    { onResult: (e: Enduser) =>
-        e.tags?.length === 1
-     && e.tags.includes('No-Show - Any')
+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)
+
+/**
+ * Covers the event-wide "Appointment No-Showed" trigger path (handle_no_showed_event).
+ * Mirrors appointment_completed_trigger.test.ts.
+ *
+ * Provisions its own throwaway tenant: the three triggers below are org-wide automation state, so on
+ * the shared fixture they classify every other concurrently running suite's calendar events (and the
+ * tag assertions here count tags added by anyone else's triggers).
+ *
+ * Triggers fire asynchronously. Each case polls for the unfiltered trigger's `No-Show - Any` tag as
+ * its synchronization barrier rather than sleeping a fixed 500ms — with eight suites against one
+ * local API, a fixed wait races trigger processing.
+ *
+ * Separate endusers per case: triggers are throttled to one fire per trigger per enduser per minute.
+ */
+
+/** Polls until `done`, returning the last value seen (so a timeout records a FAIL with evidence
+ *  rather than throwing, which would abort the whole batch). */
+const poll_for = async <T,>(get: () => Promise<T>, done: (v: T) => boolean, attempts = 40): 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 appointment_no_showed_trigger_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: `Appointment No-Showed trigger ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const { sdk } = tenant
+
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Appointment No-Showed', info: {} },
+      action: { type: 'Add Tags', info: { tags: ['No-Show - Any'] } },
+      status: 'Active',
+      title: "No-Show - Any",
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Appointment No-Showed', info: { titles: ['Test Appointment'] } },
+      action: { type: 'Add Tags', info: { tags: ['No-Show - By Title'] } },
+      status: 'Active',
+      title: "No-Show - By Title",
+    })
+    const template = await sdk.api.calendar_event_templates.createOne({
+      title: 'No-Show Template',
+      durationInMinutes: 30,
+    })
+    await sdk.api.automation_triggers.createOne({
+      event: { type: 'Appointment No-Showed', info: { templateIds: [template.id] } },
+      action: { type: 'Add Tags', info: { tags: ['No-Show - By Template'] } },
+      status: 'Active',
+      title: "No-Show - By Template",
+    })
+
+    // Separate endusers to avoid per-trigger throttling (1 min per trigger per enduser)
+    const enduser1 = await sdk.api.endusers.createOne({})
+    const enduser2 = await sdk.api.endusers.createOne({})
+    const enduser3 = await sdk.api.endusers.createOne({})
+
+    const tags_after_no_show = (enduserId: string, done: (e: Enduser) => boolean) => poll_for(
+      () => sdk.api.endusers.getOne(enduserId),
+      done,
+    )
+
+    /** Re-reads until two consecutive samples carry the same tags, so a tag still in flight is not
+     *  mistaken for "no tag was added". */
+    const settled_tags = async (enduserId: string) => {
+      let previous = await sdk.api.endusers.getOne(enduserId)
+      for (let i = 0; i < 8; i++) {
+        await new Promise(resolve => setTimeout(resolve, 250))
+        const current = await sdk.api.endusers.getOne(enduserId)
+        if (JSON.stringify(current.tags ?? []) === JSON.stringify(previous.tags ?? [])) return current
+        previous = current
+      }
+      return previous
     }
-  )
-
-  // Cleanup
-  await Promise.all([
-    sdk.api.automation_triggers.deleteOne(t1.id),
-    sdk.api.automation_triggers.deleteOne(t2.id),
-    sdk.api.automation_triggers.deleteOne(t3.id),
-    sdk.api.calendar_event_templates.deleteOne(template.id),
-    sdk.api.endusers.deleteOne(enduser1.id),
-    sdk.api.endusers.deleteOne(enduser2.id),
-    sdk.api.endusers.deleteOne(enduser3.id),
-    sdk.api.calendar_events.deleteOne(event1.id),
-    sdk.api.calendar_events.deleteOne(event2.id),
-    sdk.api.calendar_events.deleteOne(event3.id),
-  ])
+
+    // Note: the "Appointment No-Showed" trigger fires only on UPDATE (handle_no_showed_event);
+    // there is no create-time no-show path, so every case creates a normal event then updates it.
+
+    // Test 1: Update to no-showed by title (should trigger Any + By Title)
+    const event1 = await sdk.api.calendar_events.createOne({
+      title: 'Test Appointment',
+      durationInMinutes: 30,
+      startTimeInMS: Date.now(),
+      attendees: [{ type: 'enduser', id: enduser1.id }],
+    })
+    await sdk.api.calendar_events.updateOne(event1.id, { noShowedAt: new Date() })
+    const e1 = await tags_after_no_show(
+      enduser1.id,
+      e => !!e.tags?.includes('No-Show - Any') && !!e.tags?.includes('No-Show - By Title'),
+    )
+    record(
+      'Update to no-showed triggers automation (Any + By Title)',
+      e1.tags?.length === 2
+      && e1.tags.includes('No-Show - Any')
+      && e1.tags.includes('No-Show - By Title'),
+      `tags=${JSON.stringify(e1.tags)}`,
+    )
+
+    // Test 2: Template-based no-show (should trigger Any + By Template)
+    const event2 = await sdk.api.calendar_events.createOne({
+      title: 'Template Test',
+      durationInMinutes: 30,
+      startTimeInMS: Date.now(),
+      attendees: [{ type: 'enduser', id: enduser2.id }],
+      templateId: template.id,
+    })
+    await sdk.api.calendar_events.updateOne(event2.id, { noShowedAt: new Date() })
+    const e2 = await tags_after_no_show(
+      enduser2.id,
+      e => !!e.tags?.includes('No-Show - Any') && !!e.tags?.includes('No-Show - By Template'),
+    )
+    record(
+      'Template-based no-showed appointment triggers automation (Any + By Template)',
+      e2.tags?.length === 2
+      && e2.tags.includes('No-Show - Any')
+      && e2.tags.includes('No-Show - By Template'),
+      `tags=${JSON.stringify(e2.tags)}`,
+    )
+
+    // Test 3: Non-matching title only fires the "Any" trigger
+    const event3 = await sdk.api.calendar_events.createOne({
+      title: 'Other Title',
+      durationInMinutes: 30,
+      startTimeInMS: Date.now(),
+      attendees: [{ type: 'enduser', id: enduser3.id }],
+    })
+    await sdk.api.calendar_events.updateOne(event3.id, { noShowedAt: new Date() })
+    // The unfiltered trigger's tag is the barrier here: without it, "only one tag" would pass
+    // merely by reading before any trigger had run. Matched triggers are then applied one after
+    // another (handle_actions_for_triggers_inner loops sequentially), so a regressed title filter
+    // would add its tag a few ms later — settle until two consecutive reads agree before asserting
+    // that only one tag landed.
+    await tags_after_no_show(enduser3.id, e => !!e.tags?.includes('No-Show - Any'))
+    const e3 = await settled_tags(enduser3.id)
+    record(
+      'No-show with non-matching title fires only the Any trigger',
+      e3.tags?.length === 1
+      && e3.tags.includes('No-Show - Any'),
+      `tags=${JSON.stringify(e3.tags)}`,
+    )
+  } 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. */
+export const appointment_no_showed_trigger_tests = async () => {
+  assert_checks('Appointment No-Showed trigger', await appointment_no_showed_trigger_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = {
+  name: 'Appointment No-Showed trigger',
+  run: appointment_no_showed_trigger_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 appointment_no_showed_trigger_tests({ sdk, sdkNonAdmin })
-  }
-
-  runTests()
+  appointment_no_showed_trigger_tests()
     .then(() => {
       console.log("✅ Appointment No-Showed trigger tests completed successfully")
       process.exit(0)

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

@@ -0,0 +1,286 @@
+require('source-map-support').install();
+
+import { DateTime } from "luxon"
+import {
+  assert_checks,
+  Check,
+  setup_isolated_tenant,
+  IsolatedSuite,
+} from "../setup_isolated"
+
+const host = process.env.API_URL || 'http://localhost:8080' as const
+
+const RAND = () => Math.random().toString(36).slice(2, 10)
+
+const TIMEZONE = 'America/New_York' as const
+const INTERVAL_IN_MINUTES = 15
+const DURATION_IN_MINUTES = 60
+const BLOCK_START_IN_MINUTES = 9 * 60   // 9:00am
+const BLOCK_END_IN_MINUTES = 17 * 60    // 5:00pm
+
+/** 9:00am ... 4:00pm inclusive, stepping 15 minutes: the last start that still fits a 60 minute slot */
+const EXPECTED_SLOT_COUNT = ((BLOCK_END_IN_MINUTES - DURATION_IN_MINUTES) - BLOCK_START_IN_MINUTES) / INTERVAL_IN_MINUTES + 1
+
+// indexes into that grid, so the assertions never depend on wall-clock dates or on DST
+const TEN = 4                    // 10:00am — well clear of the appointment, for the ignored-event control
+const ELEVEN = 8                 // 11:00am — the last 60-minute slot a 9:00am-12:00pm block can offer
+const NOON = 12
+const QUARTER_TO_ONE = 15        // 12:45pm — ends at 1:45pm, 15 minutes clear of a 2:00pm appointment
+const ONE = 16                   // 1:00pm  — ends exactly at 2:00pm
+const QUARTER_PAST_ONE = 17      // 1:15pm  — the first start the un-buffered appointment blocks
+const TWO = 20                   // 2:00pm  — the booked appointment, 2:00-3:00pm
+const QUARTER_TO_THREE = 23      // 2:45pm  — the last start the un-buffered appointment blocks
+const THREE = 24                 // 3:00pm  — starts exactly when the appointment ends
+const QUARTER_PAST_THREE = 25    // 3:15pm  — 15 minutes clear of the appointment
+
+const same = (a: number[], b: number[]) => a.length === b.length && a.every((v, i) => v === b[i])
+const preview = (times: number[], all: number[]) => (
+  `[${times.map(t => `${all.indexOf(t)}`).join(',')}] (${times.length} slots)`
+)
+
+/**
+ * `WeeklyAvailability.bufferStartMinutes` — the availability block's "Pre-Event Buffer (Minutes)" —
+ * used to mean only "no bookings within this many minutes of right now". It never padded the
+ * appointments already on the calendar, so a 60 minute appointment at 2:00pm still advertised 3:00pm
+ * as bookable. It now also widens every blocking event's busy window on BOTH edges, so the gap does
+ * not depend on which side was booked first, while keeping its lead-time meaning.
+ *
+ * Covered here: the gap after an appointment, the gap before one, that a blank/0 buffer still offers
+ * back-to-back slots, that two overlapping availability blocks with nothing booked do not thin each
+ * other out (the padding deliberately does not apply to slots already emitted by another block), that
+ * a slot's buffer may still run past the block's own end, and that the lead-time behaviour survives.
+ *
+ * RED (pre-fix): B1-B4 fail — 3:00pm and 1:00pm are still offered with a 15 minute buffer set.
+ * GREEN: every control (N*, Z1, O1, L1) passes before and after.
+ */
+export const availability_block_buffer_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: `availability block buffer ${RAND()}`,
+      users: [{ isAdmin: true }],
+      apiKeys: 0,
+    })
+    const sdk = tenant.sdk
+    const userId = sdk.userInfo.id
+
+    // two days out in the host's own timezone, so "now" is never inside the window (which would make
+    // the lead-time buffer interfere) and the occurrence is always inside the query range below
+    const dayOfWeekStartingSundayIndexedByZero = (DateTime.now().setZone(TIMEZONE).weekday + 2) % 7
+    const BLOCK = {
+      dayOfWeekStartingSundayIndexedByZero,
+      startTimeInMinutes: BLOCK_START_IN_MINUTES,
+      endTimeInMinutes: BLOCK_END_IN_MINUTES,
+      intervalInMinutes: INTERVAL_IN_MINUTES,
+    }
+
+    const set_availability = (weeklyAvailabilities: object[]) => sdk.api.users.updateOne(
+      userId,
+      { timezone: TIMEZONE, weeklyAvailabilities } as any,
+      { replaceObjectFields: true },
+    )
+
+    const template = await sdk.api.calendar_event_templates.createOne({
+      title: `availability buffer ${RAND()}`,
+      durationInMinutes: DURATION_IN_MINUTES,
+      confirmationEmailDisabled: true,
+      confirmationSMSDisabled: true,
+    } as any)
+
+    /** the sorted, de-duplicated start times currently offered for the test user */
+    const slots = async (): Promise<number[]> => {
+      const { availabilityBlocks } = await sdk.api.calendar_events.get_appointment_availability({
+        calendarEventTemplateId: template.id,
+        userId,
+        from: new Date(Date.now() + 1000),
+        // only 6 days, so exactly ONE occurrence of the weekly block is in range
+        to: new Date(Date.now() + 6 * 24 * 60 * 60 * 1000),
+      })
+      const startTimes: number[] = availabilityBlocks.map((b: { startTimeInMS: number }) => b.startTimeInMS)
+      return startTimes.filter((t, i) => startTimes.indexOf(t) === i).sort((a, b) => a - b)
+    }
+
+    /* ================= baseline: one empty block, no buffer ================= */
+
+    await set_availability([{ ...BLOCK }])
+    const grid = await slots()
+
+    record(
+      'setup: an empty 9:00am-5:00pm block offers a complete 15-minute grid of 60-minute slots',
+      grid.length === EXPECTED_SLOT_COUNT
+        && grid.every((t, i) => i === 0 || t - grid[i - 1] === INTERVAL_IN_MINUTES * 60 * 1000),
+      `${grid.length} slots (want ${EXPECTED_SLOT_COUNT}),`
+        + ` first=${new Date(grid[0]).toISOString()} last=${new Date(grid[grid.length - 1]).toISOString()}`,
+    )
+    if (grid.length !== EXPECTED_SLOT_COUNT) {
+      return checks // every assertion below indexes into this grid
+    }
+
+    /* ================= N: no buffer — back-to-back is still offered ================= */
+
+    const appointment = await sdk.api.calendar_events.createOne({
+      title: `buffer test appointment ${RAND()}`,
+      startTimeInMS: grid[TWO],
+      durationInMinutes: DURATION_IN_MINUTES,
+      attendees: [{ id: userId, type: 'user' }],
+    } as any)
+
+    const noBuffer = await slots()
+    record(
+      'N1: a 2:00-3:00pm appointment removes exactly the slots that overlap it (1:15pm through 2:45pm)',
+      same(noBuffer, grid.filter((_, i) => i < QUARTER_PAST_ONE || i > QUARTER_TO_THREE)),
+      `offered=${preview(noBuffer, grid)} want every index except ${QUARTER_PAST_ONE}..${QUARTER_TO_THREE}`,
+    )
+    record(
+      'N2: with no buffer, the slot starting exactly when the appointment ends is still offered',
+      noBuffer.includes(grid[THREE]),
+      `3:00pm present=${noBuffer.includes(grid[THREE])}`,
+    )
+    record(
+      'N3: with no buffer, the slot ending exactly when the appointment starts is still offered',
+      noBuffer.includes(grid[ONE]),
+      `1:00pm present=${noBuffer.includes(grid[ONE])}`,
+    )
+
+    /* ================= B: the fix — the block's buffer pads BOTH edges ================= */
+
+    await set_availability([{ ...BLOCK, bufferStartMinutes: INTERVAL_IN_MINUTES }])
+    const buffered = await slots()
+
+    record(
+      'B1: gap after — 3:00pm, back-to-back with the appointment, is no longer offered',
+      !buffered.includes(grid[THREE]),
+      `offered=${preview(buffered, grid)}`,
+    )
+    record(
+      'B2: gap after — 3:15pm is the first slot offered after the appointment',
+      buffered.find(t => t > grid[QUARTER_TO_THREE]) === grid[QUARTER_PAST_THREE],
+      `first after the appointment=${String(buffered.find(t => t > grid[QUARTER_TO_THREE]))} want ${grid[QUARTER_PAST_THREE]}`,
+    )
+    record(
+      'B3: gap before — 1:00pm, which would end exactly at 2:00pm, is no longer offered',
+      !buffered.includes(grid[ONE]),
+      `1:00pm present=${buffered.includes(grid[ONE])}`,
+    )
+    record(
+      'B4: gap before — 12:45pm, a full buffer clear of the appointment, is still offered',
+      buffered.includes(grid[QUARTER_TO_ONE]),
+      `12:45pm present=${buffered.includes(grid[QUARTER_TO_ONE])}`,
+    )
+    record(
+      'B5: the buffer widens that to exactly 1:00pm through 3:00pm, and nothing else',
+      same(buffered, grid.filter((_, i) => i < ONE || i > THREE)),
+      `offered=${preview(buffered, grid)} want every index except ${ONE}..${THREE}`,
+    )
+    record(
+      'B6: the block edge is unchanged — 4:00pm is still the last slot, its buffer may run past 5:00pm',
+      buffered[buffered.length - 1] === grid[grid.length - 1],
+      `last=${String(buffered[buffered.length - 1])} want ${grid[grid.length - 1]}`,
+    )
+
+    const ignoredEvent = await sdk.api.calendar_events.createOne({
+      title: `buffer test non-blocking event ${RAND()}`,
+      startTimeInMS: grid[TEN],
+      durationInMinutes: DURATION_IN_MINUTES,
+      attendees: [{ id: userId, type: 'user' }],
+      dontBlockAvailability: true,
+    } as any)
+    const withIgnoredEvent = await slots()
+    record(
+      'B7: a dontBlockAvailability event is still ignored entirely — the buffer does not resurrect it',
+      same(withIgnoredEvent, buffered),
+      `offered=${preview(withIgnoredEvent, grid)} want the same ${buffered.length} slots as without it`,
+    )
+
+    /* ================= Z: 0 and blank behave identically ================= */
+
+    await set_availability([{ ...BLOCK, bufferStartMinutes: 0 }])
+    const zeroBuffer = await slots()
+    record(
+      'Z1: bufferStartMinutes 0 is identical to leaving it blank',
+      same(zeroBuffer, noBuffer),
+      `zero=${preview(zeroBuffer, grid)} blank=${preview(noBuffer, grid)}`,
+    )
+
+    /* ================= O: overlapping blocks must not thin each other out ================= */
+
+    await Promise.all([
+      sdk.api.calendar_events.deleteOne(appointment.id),
+      sdk.api.calendar_events.deleteOne(ignoredEvent.id),
+    ])
+    await set_availability([
+      { ...BLOCK, bufferStartMinutes: INTERVAL_IN_MINUTES },
+      { ...BLOCK, startTimeInMinutes: 13 * 60, bufferStartMinutes: INTERVAL_IN_MINUTES },
+    ])
+    const overlapping = await slots()
+    record(
+      'O1: two overlapping buffered blocks with nothing booked still offer the complete grid',
+      same(overlapping, grid),
+      `offered=${preview(overlapping, grid)} want the full ${grid.length}-slot grid`,
+    )
+
+    // O1 alone cannot fail: the nested block's candidates all coincide with slots the wider block
+    // already emitted, so the de-duplication suppresses them whether or not the buffer is applied to
+    // the availability list. Two ADJACENT blocks are the discriminating case — padding the emitted
+    // slots would stretch the 11:00am-12:00pm candidate to 10:45am-12:15pm and swallow 12:00pm, the
+    // first slot the second block offers.
+    await set_availability([
+      { ...BLOCK, endTimeInMinutes: 12 * 60, bufferStartMinutes: INTERVAL_IN_MINUTES },
+      { ...BLOCK, startTimeInMinutes: 12 * 60, bufferStartMinutes: INTERVAL_IN_MINUTES },
+    ])
+    const adjacent = await slots()
+    record(
+      'O2: back-to-back buffered blocks with nothing booked do not eat each other\'s boundary slot',
+      same(adjacent, grid.filter((_, i) => i <= ELEVEN || i >= NOON)),
+      `offered=${preview(adjacent, grid)} want 9:00-11:00am and 12:00-4:00pm`
+        + ` (indexes 0..${ELEVEN} and ${NOON}..${grid.length - 1}), 12:00pm present=${adjacent.includes(grid[NOON])}`,
+    )
+
+    /* ================= L: the lead-time meaning is kept, not replaced ================= */
+
+    // a buffer reaching from right now to the noon slot on the test day
+    const leadTimeInMinutes = Math.ceil((grid[NOON] - Date.now()) / (60 * 1000))
+    await set_availability([{ ...BLOCK, bufferStartMinutes: leadTimeInMinutes }])
+    const leadTime = await slots()
+    record(
+      'L1: bufferStartMinutes still blocks everything within that many minutes of now',
+      leadTime.length > 0
+        && leadTime[0] >= grid[NOON] && leadTime[0] <= grid[NOON + 1]
+        && leadTime[leadTime.length - 1] === grid[grid.length - 1],
+      `buffer=${leadTimeInMinutes}min offered=${preview(leadTime, grid)}`
+        + ` (want nothing before index ${NOON}, and the afternoon intact)`,
+    )
+  } finally {
+    // Teardown before anything asserts — assert calls process.exit, which skips pending finallys and
+    // would strand the provisioned tenant permanently.
+    if (tenant) { try { await tenant.teardown() } catch (e) { console.error('teardown failed', e) } }
+  }
+
+  return checks
+}
+
+/** Asserting wrapper, for standalone runs and for sequential use in the suite. */
+export const availability_block_buffer_tests = async () => {
+  assert_checks('availability block pre-event buffer', await availability_block_buffer_checks())
+}
+
+/** Enrolls this suite in the auto-discovered parallel pool — see run_discovered_isolated_suites. */
+export const ISOLATED_SUITE: IsolatedSuite = { name: 'availability block pre-event buffer', run: availability_block_buffer_checks }
+
+// Allow running this test file independently
+if (require.main === module) {
+  console.log(`🌐 Using API URL: ${host}`)
+  availability_block_buffer_tests()
+    .then(() => {
+      console.log("✅ availability block pre-event buffer test suite completed successfully")
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.error("❌ availability block pre-event buffer test suite failed:", error)
+      process.exit(1)
+    })
+}