@duffcloudservices/telemetry 0.2.1 → 0.3.0

package/src/lazySdk.test.ts

@@ -0,0 +1,698 @@
+/**
+ * C-601 — the LAZY App Insights SDK path.
+ *
+ * ## What this file exists to prevent
+ *
+ * Measured on the bryans-handyman-solutions pilot (2026-08-11): the sites reach the
+ * App Insights web SDK through a hand-rolled dynamic `import()`, which their
+ * bundler emits as a separate ~192KB raw / ~78KB gzip chunk, off the critical path
+ * behind a `requestIdleCallback`. Adopting `@duffcloudservices/telemetry@0.2.1` as
+ * published FOLDED that SDK into the site's entry chunk — +192,265B raw (+90.4%),
+ * +77,095B gzip (+101.2%) — of which the package's own code was only ~4.8KB. Total
+ * transferred JS barely moved; the SDK simply relocated onto the critical path and
+ * the sites' deliberate deferral was defeated.
+ *
+ * The cause was one line: a static, value-level
+ * `import { ApplicationInsights } from '@microsoft/applicationinsights-web'` in
+ * `composable.ts`. A single character (`import type`) reintroduces it, in a diff
+ * that looks like a tidy-up, and nothing in a unit test would notice — the package
+ * would keep working perfectly while every adopting site's LCP regressed.
+ *
+ * So laziness is pinned three ways here, at three different altitudes:
+ *
+ * 1. **Source** — no source file may statically bind the SDK.
+ * 2. **Emit** — the JavaScript TypeScript actually produces must contain no static
+ *    import of the SDK, and must contain the dynamic one (a positive control: it
+ *    proves the assertion is looking at a real artifact).
+ * 3. **Runtime** — importing the package must not evaluate the SDK module at all;
+ *    only `initialize()` may.
+ *
+ * The rest of the file pins the behaviour laziness buys and the behaviour it must
+ * not cost: buffered ordering across the load window, one init under concurrent
+ * callers, faithful page timing, and no unbounded buffer on a load that never lands.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import ts from 'typescript'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const SDK_SPECIFIER = '@microsoft/applicationinsights-web'
+const SRC_DIR = join(__dirname)
+
+// ---------------------------------------------------------------------------
+// The controllable SDK module.
+//
+// `sdkLoadGate` lets a test hold the dynamic import OPEN for as long as it likes,
+// which is the only way the pre-init window is observable at all — without it the
+// import resolves a microtask later and there is nothing to measure.
+// ---------------------------------------------------------------------------
+
+/** Flipped the instant the SDK module is evaluated. The eval-time guard reads it. */
+let sdkModuleEvaluated = false
+let sdkLoadGate: Promise<void> = Promise.resolve()
+let releaseSdkLoad: () => void = () => {}
+let sdkLoadShouldFail = false
+
+/** Every SDK call, in the order the SDK received it — the ordering assertions read this. */
+const sdkCallLog: string[] = []
+const constructedConfigs: unknown[] = []
+
+const loadAppInsightsMock = vi.fn()
+const trackEventMock = vi.fn((e: { name: string }) => {
+  sdkCallLog.push(`trackEvent:${e.name}`)
+})
+const trackPageViewMock = vi.fn((p: { name?: string }) => {
+  sdkCallLog.push(`trackPageView:${p?.name ?? ''}`)
+})
+const trackExceptionMock = vi.fn((e: { exception: Error }) => {
+  sdkCallLog.push(`trackException:${e.exception.message}`)
+})
+const trackMetricMock = vi.fn((m: { name: string }) => {
+  sdkCallLog.push(`trackMetric:${m.name}`)
+})
+const trackDependencyDataMock = vi.fn((d: { name: string }) => {
+  sdkCallLog.push(`trackDependency:${d.name}`)
+})
+const startTrackPageMock = vi.fn()
+const stopTrackPageMock = vi.fn()
+
+/**
+ * Register the mocked SDK module — `doMock`, deliberately, NOT the hoisted `vi.mock`.
+ *
+ * A hoisted `vi.mock` factory is invoked ONCE for the whole file and its result is
+ * cached across `vi.resetModules()` (`composable.test.ts` documents relying on
+ * exactly that). That caching silently destroys every test in this file that needs
+ * an observable load window: the gate would be awaited only by the first test to
+ * import the SDK, and from then on the "lazy" import would resolve instantly. The
+ * specs still passed individually and lied in a suite — buffering, ordering, the
+ * buffer bound and the failed-load path all measured a load window that no longer
+ * existed. `doMock` re-runs the factory after each `resetModules`, so every test
+ * gets a real, independently controllable load.
+ */
+function installSdkMock(): void {
+  vi.doMock(SDK_SPECIFIER, async () => {
+    sdkModuleEvaluated = true
+    await sdkLoadGate
+    if (sdkLoadShouldFail) {
+      throw new Error('SDK chunk failed to load')
+    }
+    return {
+      ApplicationInsights: vi.fn().mockImplementation((arg: { config: unknown }) => {
+        constructedConfigs.push(arg.config)
+        return {
+          loadAppInsights: loadAppInsightsMock,
+          addTelemetryInitializer: vi.fn(),
+          trackEvent: trackEventMock,
+          trackPageView: trackPageViewMock,
+          trackException: trackExceptionMock,
+          trackMetric: trackMetricMock,
+          trackDependencyData: trackDependencyDataMock,
+          startTrackPage: startTrackPageMock,
+          stopTrackPage: stopTrackPageMock,
+          flush: vi.fn(),
+        }
+      }),
+    }
+  })
+}
+
+const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+vi.spyOn(console, 'log').mockImplementation(() => {})
+
+const CONNECTION_STRING =
+  'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://example.in.applicationinsights.azure.com/'
+
+/** Hold the SDK import open until the test says otherwise. */
+function holdSdkLoad(): void {
+  sdkLoadGate = new Promise<void>((resolve) => {
+    releaseSdkLoad = resolve
+  })
+}
+
+/** Yield to the macrotask queue so the dynamic import gets a chance to start. */
+function tick(ms = 0): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+beforeEach(() => {
+  sdkModuleEvaluated = false
+  sdkLoadShouldFail = false
+  sdkLoadGate = Promise.resolve()
+  releaseSdkLoad = () => {}
+  sdkCallLog.length = 0
+  constructedConfigs.length = 0
+  loadAppInsightsMock.mockClear()
+  trackEventMock.mockClear()
+  trackPageViewMock.mockClear()
+  trackExceptionMock.mockClear()
+  trackMetricMock.mockClear()
+  trackDependencyDataMock.mockClear()
+  startTrackPageMock.mockClear()
+  stopTrackPageMock.mockClear()
+  warnSpy.mockClear()
+  errorSpy.mockClear()
+  // Recreate the composable's module-level singleton state for each test, then
+  // re-register the SDK mock so its factory (and therefore the load gate) is fresh.
+  vi.resetModules()
+  installSdkMock()
+})
+
+// ===========================================================================
+// 1 + 2. The SDK must not be reachable statically — in source, or in the emit.
+// ===========================================================================
+
+describe('no static SDK import (the C-601 regression guard)', () => {
+  const sourceFiles = readdirSync(SRC_DIR)
+    .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+    .sort()
+
+  /**
+   * Static bindings of the SDK: `import … from 'SDK'`, `export … from 'SDK'`,
+   * a bare side-effect `import 'SDK'`, or `require('SDK')`.
+   *
+   * `import type` / `export type` are allowed — TypeScript erases them, so they
+   * cost zero runtime bytes, and the composable needs the `ApplicationInsights`
+   * type to describe its own singleton.
+   *
+   * Deliberately strict about WHERE `type` may appear: only the top-level
+   * `import type` / `export type` form passes. Inline `import { type X } from 'SDK'`
+   * is flagged even though today's tsconfig would elide it, because whether it is
+   * elided depends on compiler settings (`verbatimModuleSyntax`,
+   * `importsNotUsedAsValues`) that a future config change could flip underneath us.
+   * The cost of the strictness is one keyword; the cost of being wrong is +192KB on
+   * every adopting site's entry chunk.
+   */
+  const escaped = SDK_SPECIFIER.replace(/[/\\^$*+?.()|[\]{}]/g, '\\$&')
+  const staticBinding = new RegExp(
+    String.raw`(?:^|[\s;])(import|export)\s+(type\s+)?[^;]*?\bfrom\s*['"]${escaped}['"]`,
+    'g',
+  )
+  const bareImport = new RegExp(String.raw`(?:^|[\s;])import\s*['"]${escaped}['"]`, 'g')
+  const requireCall = new RegExp(
+    String.raw`\brequire\s*\(\s*['"]${escaped}['"]\s*\)`,
+    'g',
+  )
+
+  /**
+   * Drop comments before scanning.
+   *
+   * Not cosmetic — this bit for real. `staticBinding` deliberately spans newlines so
+   * a multi-line `import {\n  ApplicationInsights,\n} from 'SDK'` cannot hide from
+   * it, which also means the prose in `composable.ts`'s own header comment (which
+   * says the word "import" a few lines above the real `import type` line) matched as
+   * a violation. A guard that reds on its own explanatory comment gets deleted, not
+   * fixed.
+   */
+  function stripComments(source: string): string {
+    return source
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:])\/\/[^\n]*/gm, '$1')
+  }
+
+  function staticSdkBindingsIn(rawSource: string): string[] {
+    const source = stripComments(rawSource)
+    const violations: string[] = []
+    for (const match of source.matchAll(staticBinding)) {
+      const isTypeOnly = match[2] !== undefined
+      if (!isTypeOnly) violations.push(match[0].trim())
+    }
+    for (const match of source.matchAll(bareImport)) violations.push(match[0].trim())
+    for (const match of source.matchAll(requireCall)) violations.push(match[0].trim())
+    return violations
+  }
+
+  it('scans a non-trivial set of source files (guards the guard)', () => {
+    // A glob that silently matches nothing would make every assertion below vacuous.
+    expect(sourceFiles).toContain('composable.ts')
+    expect(sourceFiles).toContain('index.ts')
+    expect(sourceFiles.length).toBeGreaterThanOrEqual(5)
+  })
+
+  it('detects a static SDK import when one is present (kill-test)', () => {
+    // The positive control. If this matcher cannot see a real static import, the
+    // per-file assertion below proves nothing at all.
+    expect(
+      staticSdkBindingsIn(`import { ApplicationInsights } from '${SDK_SPECIFIER}'\n`),
+    ).toHaveLength(1)
+    expect(staticSdkBindingsIn(`import '${SDK_SPECIFIER}'\n`)).toHaveLength(1)
+    expect(
+      staticSdkBindingsIn(`export { ApplicationInsights } from '${SDK_SPECIFIER}'\n`),
+    ).toHaveLength(1)
+    expect(
+      staticSdkBindingsIn(`const m = require('${SDK_SPECIFIER}')\n`),
+    ).toHaveLength(1)
+    // A multi-line value import is the realistic shape of the regression — a
+    // formatter reflows the line the moment a second named export is added.
+    expect(
+      staticSdkBindingsIn(
+        `import {\n  ApplicationInsights,\n  type IConfig,\n} from '${SDK_SPECIFIER}'\n`,
+      ),
+    ).toHaveLength(1)
+
+    // …and must NOT flag the forms that cost no runtime bytes.
+    expect(
+      staticSdkBindingsIn(`import type { ApplicationInsights } from '${SDK_SPECIFIER}'\n`),
+    ).toHaveLength(0)
+    expect(
+      staticSdkBindingsIn(`const m = await import('${SDK_SPECIFIER}')\n`),
+    ).toHaveLength(0)
+    // Prose about importing is not an import.
+    expect(
+      staticSdkBindingsIn(
+        `// A static import of the SDK here would fold it into the entry chunk.\n` +
+          `import type { ApplicationInsights } from '${SDK_SPECIFIER}'\n`,
+      ),
+    ).toHaveLength(0)
+  })
+
+  it.each(readdirSync(SRC_DIR).filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts')))(
+    'src/%s binds the SDK only as a type',
+    (file) => {
+      const source = readFileSync(join(SRC_DIR, file), 'utf8')
+      expect(staticSdkBindingsIn(source)).toEqual([])
+    },
+  )
+
+  it('emits no static SDK import, and does emit the dynamic one', () => {
+    // One altitude down from the source scan: this is the JavaScript the bundler
+    // consumes. `import type` is gone; `import()` survives and becomes the async
+    // chunk boundary.
+    const source = readFileSync(join(SRC_DIR, 'composable.ts'), 'utf8')
+    const emitted = ts.transpileModule(source, {
+      compilerOptions: {
+        module: ts.ModuleKind.ESNext,
+        target: ts.ScriptTarget.ES2022,
+      },
+    }).outputText
+
+    expect(emitted).not.toMatch(new RegExp(String.raw`\bfrom\s*['"]${escaped}['"]`))
+    // Positive control: the dynamic import must be there, or the assertion above
+    // would also pass on a file that simply never mentions the SDK.
+    expect(emitted).toMatch(new RegExp(String.raw`import\(\s*['"]${escaped}['"]`))
+  })
+})
+
+// ===========================================================================
+// 3. Runtime: importing the package must not evaluate the SDK.
+// ===========================================================================
+
+describe('module-eval-time laziness', () => {
+  it('importing the composable does not evaluate the SDK module', async () => {
+    await import('./composable')
+    expect(sdkModuleEvaluated).toBe(false)
+  })
+
+  it('importing the package entry point does not evaluate the SDK module', async () => {
+    // The entry point re-exports the composable, so this is the shape a consumer
+    // actually gets — and the one whose entry chunk the SDK was landing on.
+    await import('./index')
+    expect(sdkModuleEvaluated).toBe(false)
+  })
+
+  it('only initialize() reaches the SDK (positive control)', async () => {
+    // Without this the test above passes on a broken build too — e.g. if the mock
+    // were never wired up, `sdkModuleEvaluated` would be false forever.
+    const { useTelemetry } = await import('./composable')
+    expect(sdkModuleEvaluated).toBe(false)
+
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+    t.initialize()
+    await t.whenReady()
+
+    expect(sdkModuleEvaluated).toBe(true)
+    expect(constructedConfigs).toHaveLength(1)
+  })
+
+  it('a disabled site never loads the SDK chunk at all', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry()
+
+    expect(t.initialize()).toBe(false)
+    await tick()
+
+    expect(sdkModuleEvaluated).toBe(false)
+    expect(constructedConfigs).toHaveLength(0)
+  })
+})
+
+// ===========================================================================
+// The load window: buffering and ordering.
+// ===========================================================================
+
+describe('calls made while the SDK chunk is in flight', () => {
+  it('buffers an event fired before the lazy import resolves, then sends it', async () => {
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: false,
+    })
+
+    expect(t.initialize()).toBe(true)
+    await tick()
+
+    // The window is genuinely open: the SDK module is entered and blocked.
+    expect(sdkModuleEvaluated).toBe(true)
+    expect(t.isInitialized.value).toBe(false)
+
+    t.trackEvent({ name: 'early_event' })
+    // Nothing can have been sent — there is no SDK yet.
+    expect(trackEventMock).not.toHaveBeenCalled()
+    // …and it must not have been written off as "not initialized" either.
+    expect(
+      warnSpy.mock.calls.some((c) => String(c[0]).includes('not initialized')),
+    ).toBe(false)
+
+    releaseSdkLoad()
+    await t.whenReady()
+
+    expect(t.isInitialized.value).toBe(true)
+    expect(trackEventMock).toHaveBeenCalledTimes(1)
+    expect(trackEventMock.mock.calls[0][0].name).toBe('early_event')
+  })
+
+  it('stamps buffered events with their CALL time, not the drain time', async () => {
+    // The whole value of a buffer is that the event still describes the moment it
+    // happened. A payload built at drain time would report the page the visitor had
+    // navigated to by then, and a timestamp minutes late on a slow connection.
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+
+    t.initialize()
+    await tick()
+    t.trackEvent({ name: 'early_event', properties: { page_at_call: '/landing' } })
+    const afterCall = new Date().toISOString()
+
+    await tick(25)
+    releaseSdkLoad()
+    await t.whenReady()
+
+    const properties = trackEventMock.mock.calls[0][0].properties as Record<string, string>
+    expect(properties.page_at_call).toBe('/landing')
+    expect(properties.timestamp <= afterCall).toBe(true)
+  })
+
+  it('replays buffered calls in the order they were made', async () => {
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: false,
+    })
+
+    t.initialize()
+    await tick()
+
+    t.trackEvent({ name: 'first' })
+    t.trackPageView({ name: 'Landing' })
+    t.trackException({ exception: new Error('boom') })
+    t.trackMetric({ name: 'lcp', average: 1200 })
+    t.trackDependency({ name: 'api', data: '/api/x', duration: 12, success: true })
+    t.trackEvent({ name: 'last' })
+
+    expect(sdkCallLog).toEqual([])
+
+    releaseSdkLoad()
+    await t.whenReady()
+
+    expect(sdkCallLog).toEqual([
+      'trackEvent:first',
+      'trackPageView:Landing',
+      'trackException:boom',
+      'trackMetric:lcp',
+      'trackDependency:api',
+      'trackEvent:last',
+    ])
+  })
+
+  it('keeps the C-288 double-count guard armed DURING the load', async () => {
+    // The guard answers a config question, so it must not depend on load state.
+    // If it were checked after the buffer, a site with auto-route tracking on would
+    // queue manual page views during the load and replay them into exactly the
+    // duplicate the guard exists to prevent.
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: true,
+    })
+
+    t.initialize()
+    await tick()
+    t.trackPageView({ name: 'Landing' })
+
+    releaseSdkLoad()
+    await t.whenReady()
+
+    expect(trackPageViewMock).not.toHaveBeenCalled()
+    expect(
+      warnSpy.mock.calls.some((c) => String(c[0]).includes('double-counting')),
+    ).toBe(true)
+  })
+
+  it('reports a page-timing pair that straddles the load with its REAL duration', async () => {
+    // The SDK's own start/stop timer cannot be replayed — restarted at drain time it
+    // would report a ~0ms page load. So the pair is timed here and replayed as the
+    // equivalent trackPageView, using the SDK's own encoding for a timed page view
+    // (`properties.duration` as a string, which `sendPageViewInternal` reads to
+    // back-date `startTime`).
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: false,
+    })
+
+    t.initialize()
+    await tick()
+
+    t.startTrackPage('/contact')
+    await tick(20)
+    t.stopTrackPage('/contact', 'https://example.com/contact', { routeName: 'contact' })
+
+    releaseSdkLoad()
+    await t.whenReady()
+
+    // The SDK's own timer was never started, so neither half may reach it.
+    expect(startTrackPageMock).not.toHaveBeenCalled()
+    expect(stopTrackPageMock).not.toHaveBeenCalled()
+
+    expect(trackPageViewMock).toHaveBeenCalledTimes(1)
+    const call = trackPageViewMock.mock.calls[0][0] as {
+      name?: string
+      uri?: string
+      properties: Record<string, string>
+    }
+    expect(call.name).toBe('/contact')
+    expect(call.uri).toBe('https://example.com/contact')
+    expect(call.properties.routeName).toBe('contact')
+    // Real elapsed time, not a fabricated zero.
+    expect(Number(call.properties.duration)).toBeGreaterThanOrEqual(10)
+  })
+
+  it('drops a pre-init stopTrackPage with no matching start rather than inventing a timing', async () => {
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({
+      connectionString: CONNECTION_STRING,
+      enableAutoRouteTracking: false,
+    })
+
+    t.initialize()
+    await tick()
+    t.stopTrackPage('/orphan', 'https://example.com/orphan')
+
+    releaseSdkLoad()
+    await t.whenReady()
+
+    expect(trackPageViewMock).not.toHaveBeenCalled()
+    expect(stopTrackPageMock).not.toHaveBeenCalled()
+  })
+
+  it('sends straight through once the SDK has landed', async () => {
+    // The buffer must be a load-window mechanism only — a permanent queue would add
+    // latency to every event for the rest of the session.
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+
+    t.initialize()
+    await t.whenReady()
+
+    t.trackEvent({ name: 'after_load' })
+    expect(trackEventMock).toHaveBeenCalledTimes(1)
+  })
+})
+
+// ===========================================================================
+// Single init under concurrent callers.
+// ===========================================================================
+
+describe('single init under concurrent callers', () => {
+  it('two initialize() callers share one import and one SDK instance', async () => {
+    // Two SDK instances on one connection string double every beacon. The sites
+    // guard this with an `initializationPromise` (kduff-homes useTelemetry.ts);
+    // this is the packaged equivalent.
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const a = useTelemetry({ connectionString: CONNECTION_STRING })
+    const b = useTelemetry({ connectionString: CONNECTION_STRING })
+
+    expect(a.initialize()).toBe(true)
+    expect(b.initialize()).toBe(true)
+    await tick()
+
+    // Both callers are waiting on the SAME in-flight load, not two of them.
+    expect(a.whenReady()).toBe(b.whenReady())
+
+    releaseSdkLoad()
+    await Promise.all([a.whenReady(), b.whenReady()])
+
+    expect(constructedConfigs).toHaveLength(1)
+    expect(loadAppInsightsMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('a repeat initialize() after the load lands is still a no-op', async () => {
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+
+    t.initialize()
+    await t.whenReady()
+    expect(t.initialize()).toBe(true)
+    await t.whenReady()
+
+    expect(constructedConfigs).toHaveLength(1)
+    expect(loadAppInsightsMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('ten concurrent callers still produce exactly one SDK instance', async () => {
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const instances = Array.from({ length: 10 }, () =>
+      useTelemetry({ connectionString: CONNECTION_STRING }),
+    )
+
+    for (const t of instances) expect(t.initialize()).toBe(true)
+    await tick()
+    releaseSdkLoad()
+    await Promise.all(instances.map((t) => t.whenReady()))
+
+    expect(constructedConfigs).toHaveLength(1)
+  })
+})
+
+// ===========================================================================
+// The buffer must not become a leak or a lie.
+// ===========================================================================
+
+describe('buffer bounds and failure handling', () => {
+  it('never buffers when no load is in flight, so an unconfigured site cannot leak', async () => {
+    // A site with no connection string never drains anything. Buffering its calls
+    // would grow an array for the whole session on a long-lived SPA — and would
+    // then dump stale events into any SDK that later arrived.
+    const { useTelemetry } = await import('./composable')
+    const disabled = useTelemetry()
+
+    expect(disabled.initialize()).toBe(false)
+    for (let i = 0; i < 200; i += 1) disabled.trackEvent({ name: `dropped_${i}` })
+
+    expect(
+      warnSpy.mock.calls.some((c) => String(c[0]).includes('not initialized')),
+    ).toBe(true)
+
+    // Now bring a configured instance up. Nothing from before may appear.
+    const enabled = useTelemetry({ connectionString: CONNECTION_STRING })
+    enabled.initialize()
+    await enabled.whenReady()
+
+    expect(trackEventMock).not.toHaveBeenCalled()
+  })
+
+  it('bounds the buffer and says so, instead of growing without limit', async () => {
+    holdSdkLoad()
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+
+    t.initialize()
+    await tick()
+    for (let i = 0; i < 150; i += 1) t.trackEvent({ name: `event_${i}` })
+
+    releaseSdkLoad()
+    await t.whenReady()
+
+    expect(trackEventMock).toHaveBeenCalledTimes(100)
+    expect(trackEventMock.mock.calls[0][0].name).toBe('event_0')
+    expect(trackEventMock.mock.calls[99][0].name).toBe('event_99')
+    expect(
+      warnSpy.mock.calls.filter((c) => String(c[0]).includes('pre-init buffer full')),
+    ).toHaveLength(1)
+  })
+
+  it('discards the buffer and stops buffering when the SDK chunk fails to load', async () => {
+    holdSdkLoad()
+    sdkLoadShouldFail = true
+    const { useTelemetry } = await import('./composable')
+    const t = useTelemetry({ connectionString: CONNECTION_STRING })
+
+    expect(t.initialize()).toBe(true)
+    await tick()
+    t.trackEvent({ name: 'lost_to_a_failed_chunk' })
+
+    releaseSdkLoad()
+    expect(await t.whenReady()).toBe(false)
+
+    expect(t.isInitialized.value).toBe(false)
+    // The message is asserted as "present and non-empty" rather than by text:
+    // vitest substitutes its own message when a module-mock factory throws, so
+    // pinning the string would test vitest, not the composable. What matters is that
+    // the rejection is CAPTURED into the reactive error instead of escaping as an
+    // unhandled rejection.
+    expect(t.initializationError.value).toBeTruthy()
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Failed to initialize Application Insights:',
+      expect.any(Error),
+    )
+
+    // And subsequent calls must go back to warn-and-drop rather than buffering for
+    // a drain that is never coming.
+    t.trackEvent({ name: 'after_failure' })
+    expect(
+      warnSpy.mock.calls.some((c) => String(c[0]).includes('not initialized')),
+    ).toBe(true)
+    expect(trackEventMock).not.toHaveBeenCalled()
+  })
+
+  it('whenReady() is false before initialize() is ever called', async () => {
+    const { useTelemetry } = await import('./composable')
+    expect(await useTelemetry({ connectionString: CONNECTION_STRING }).whenReady()).toBe(
+      false,
+    )
+    expect(sdkModuleEvaluated).toBe(false)
+  })
+
+  it('declines the SDK entirely during a synthetic capture pass (C-614 still holds)', async () => {
+    // The C-614 gate has to keep working on the lazy path: a capture pass must load
+    // no SDK chunk at all, not merely fail to send.
+    const original = window.location
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      value: { hostname: 'duffcloudservices.com', pathname: '/', search: '?dcs-hide-ribbon=' },
+    })
+
+    try {
+      const { useTelemetry } = await import('./composable')
+      const t = useTelemetry({ connectionString: CONNECTION_STRING })
+
+      expect(t.initialize()).toBe(false)
+      await tick()
+
+      expect(sdkModuleEvaluated).toBe(false)
+      expect(constructedConfigs).toHaveLength(0)
+      expect(await t.whenReady()).toBe(false)
+    } finally {
+      Object.defineProperty(window, 'location', { configurable: true, value: original })
+    }
+  })
+})