velocious 1.0.666 → 1.0.668

package/build/testing/test-profiler.js

@@ -1,918 +1,61 @@
 // @ts-check
 
-import { createHash } from "node:crypto"
-import path from "node:path"
-import { registerTestProfileContextReader } from "./test-profile-context.js"
-import { validateTestActivityName } from "./test-profile-activity.js"
-import { compareTimingManifestPaths } from "./timing-manifest.js"
-
-/** @typedef {"passed" | "failed" | "interrupted" | "timed-out"} TestProfileAttemptStatus */
-/** @typedef {{user: number, system: number}} ProcessCpuUsage */
-/** @typedef {{queryCount: number, failedQueryCount: number, totalMs: number, maxMs: number}} ProfileDatabaseAggregate */
-/** @typedef {{count: number, failedCount: number, totalMs: number, maxMs: number}} ProfileActionAggregate */
-/** @typedef {{identifier: string, connectionCreation: ProfileActionAggregate, checkoutWait: {count: number, totalMs: number, maxMs: number}, checkoutTimeoutCount: number, idleReap: ProfileActionAggregate & {disposalCount: number}, peakLiveConnections: number}} ProfilePoolAggregate */
-
-/**
- * @typedef {object} TestProfileAsyncContext
- * @property {TestProfiler} profiler - Owning profiler.
- * @property {TestProfileAttemptRecord | undefined} attempt - Active test attempt.
- * @property {boolean} active - Whether attribution is still open.
- * @property {Set<TestProfileAsyncContext> | undefined} [attemptContexts] - Contexts sharing one attempt lifetime.
- * @property {string | undefined} filePath - Project-relative owning test file.
- * @property {TestProfileSpan | undefined} [span] - Innermost active profile span.
- * @property {number} [spanStartedAt] - Span monotonic start time.
- * @property {ProcessCpuUsage} [spanCpuStartedAt] - Span CPU start time.
- */
-
-/**
- * @typedef {object} TestProfileSpan
- * @property {string} phase - Profile phase.
- * @property {number} executionOrder - Monotonic span start order.
- * @property {number} durationMs - Real duration.
- * @property {{user: number, system: number, total: number}} cpuMs - Process CPU duration.
- * @property {string} [activity] - Validated custom activity name.
- * @property {number} [declarationIndex] - Hook index within its declaration scope.
- * @property {string} [declarationScopeId] - Opaque declaration scope identifier.
- * @property {string} [file] - Project-relative source path.
- * @property {ProfileDatabaseAggregate} [database] - Span database aggregate.
- * @property {ProfilePoolAggregate[]} [pools] - Span pool aggregates.
- */
-
-/**
- * @typedef {object} TestProfileAttemptRecord
- * @property {number} number - One-indexed attempt number.
- * @property {TestProfileAttemptStatus | "running"} status - Attempt result.
- * @property {number} durationMs - Real duration.
- * @property {{user: number, system: number, total: number}} cpuMs - Process CPU duration.
- * @property {TestProfileSpan[]} spans - Attempt-owned spans.
- */
-
-/**
- * @typedef {object} TestProfileAttemptHandle
- * @property {TestProfileAsyncContext} context - Async attribution context.
- * @property {TestProfileAttemptRecord} attempt - Output attempt record.
- * @property {number} startedAt - Real start time.
- * @property {ProcessCpuUsage} cpuStartedAt - CPU start time.
- */
-
-/**
- * @typedef {object} InternalPhaseAggregate
- * @property {number} count - Invocation count.
- * @property {number} totalMs - Total real duration.
- * @property {number} maxMs - Maximum real duration.
- * @property {number} cpuUserMs - Total user CPU time.
- * @property {number} cpuSystemMs - Total system CPU time.
- */
-
-/**
- * @typedef {object} InternalFileAggregate
- * @property {string} path - Project-relative path.
- * @property {number} importMs - Import duration.
- * @property {number} hooksMs - Hook duration.
- * @property {number} testsMs - Test body duration.
- * @property {number} attemptsMs - Complete test-attempt duration.
- * @property {number} totalMs - Total file weight duration.
- */
-
-/**
- * @typedef {object} InternalTestRecord
- * @property {string} id - Opaque stable test identifier.
- * @property {string} file - Project-relative source path.
- * @property {number | undefined} line - Declaration line.
- * @property {TestProfileAttemptRecord[]} attempts - Attempt records.
- */
-
-const BUILT_IN_PHASES = [
-  "discovery",
-  "imports",
-  "testing config/global setup",
-  "beforeAll",
-  "beforeEach",
-  "test body",
-  "afterEach",
-  "afterAll"
-]
-const MAX_CUSTOM_ACTIVITY_NAMES = 20
-const SAFE_SQL_OPERATIONS = new Set([
-  "ALTER",
-  "ANALYZE",
-  "BEGIN",
-  "CALL",
-  "COMMIT",
-  "COPY",
-  "CREATE",
-  "DELETE",
-  "DESCRIBE",
-  "DROP",
-  "EXEC",
-  "EXECUTE",
-  "EXPLAIN",
-  "GRANT",
-  "INSERT",
-  "MERGE",
-  "PRAGMA",
-  "RELEASE",
-  "REPLACE",
-  "REVOKE",
-  "ROLLBACK",
-  "SAVEPOINT",
-  "SELECT",
-  "SET",
-  "SHOW",
-  "TRUNCATE",
-  "UPDATE",
-  "VACUUM",
-  "VALUES",
-  "WITH"
-])
-
-/**
- * Rounds and bounds duration values for public output.
- * @param {number} durationMs - Raw duration.
- * @returns {number} - Safe duration.
- */
-export function roundProfileDuration(durationMs) {
-  if (!Number.isFinite(durationMs) || durationMs < 0) return 0
-
-  return Math.round(durationMs * 1000) / 1000
-}
-
-/**
- * Collects opt-in test-run timing without retaining application payloads.
- */
-export default class TestProfiler {
-  /**
-   * Creates an opt-in test profile collector.
-   * @param {object} args - Profiler options.
-   * @param {import("../configuration.js").default} args.configuration - Test configuration.
-   * @param {string} args.projectDirectory - Project root used for portable paths.
-   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.selection] - Sanitized selection metadata.
-   */
-  constructor({configuration, projectDirectory, selection = {}}) {
-    this._configuration = configuration
-    this._projectDirectory = path.resolve(projectDirectory)
-    this._selection = selection
-    this._startedAt = this.now()
-    this._cpuStartedAt = process.cpuUsage()
-    this._executionOrder = 0
-    this._unattributedLateEventCount = 0
-    /** @type {Map<string, InternalPhaseAggregate>} */
-    this._phases = new Map()
-    /** @type {Map<string, InternalFileAggregate>} */
-    this._files = new Map()
-    /** @type {InternalTestRecord[]} */
-    this._tests = []
-    /** @type {Map<string, InternalTestRecord>} */
-    this._testsById = new Map()
-    /** @type {Set<TestProfileAttemptHandle>} */
-    this._activeAttempts = new Set()
-    /** @type {Set<TestProfileAsyncContext>} */
-    this._activeSpanContexts = new Set()
-    /** @type {TestProfileSpan[]} */
-    this._spans = []
-    /** @type {Array<{id: string, parentId: string | undefined, file: string, line: number | undefined}>} */
-    this._scopes = []
-    /** @type {WeakMap<import("./test-runner.js").TestsArgument | import("@velocious/testing/runner").SuiteDeclaration, string>} */
-    this._scopeIds = new WeakMap()
-    /** @type {Set<string>} */
-    this._customActivityNames = new Set()
-    this._database = this.emptyDatabaseAggregate()
-    /** @type {Map<string, {hash: string, operation: string, count: number, failedCount: number, totalMs: number, maxMs: number}>} */
-    this._queryFingerprints = new Map()
-    this._transactions = {
-      start: this.phaseAggregateShape(),
-      commit: this.phaseAggregateShape(),
-      rollback: this.phaseAggregateShape()
-    }
-    /** @type {Map<string, ProfilePoolAggregate>} */
-    this._pools = new Map()
-    this._finishedProfile = undefined
-
-    registerTestProfileContextReader(configuration, () => {
-      return configuration.getEnvironmentHandler().getCurrentTestProfileContext()
-    })
-
-    for (const phase of BUILT_IN_PHASES) this.phaseAggregate(phase)
-  }
-
-  /**
-   * Returns the profiler's monotonic clock.
-   * @returns {number} - Monotonic milliseconds.
-   */
-  now() {
-    return globalThis.performance.now()
-  }
-
-  /**
-   * Converts a source path to a project-relative path or an opaque hash.
-   * @param {string | undefined} filePath - Source path.
-   * @returns {string} - Safe source identifier.
-   */
-  safeSourcePath(filePath) {
-    if (!filePath) return "sha256:unknown"
-
-    const absolutePath = path.resolve(filePath)
-    const relativePath = path.relative(this._projectDirectory, absolutePath)
-
-    if (relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
-      return relativePath.replaceAll(path.sep, "/")
-    }
-
-    if (!relativePath) return path.basename(absolutePath)
-
-    return this.hash(`external-source:${absolutePath}`)
-  }
-
-  /**
-   * Returns a bounded opaque SHA-256 identifier.
-   * @param {string} value - Value to hash.
-   * @returns {string} - Opaque hash.
-   */
-  hash(value) {
-    return `sha256:${createHash("sha256").update(value).digest("hex").slice(0, 24)}`
-  }
-
-  /**
-   * Adds aggregate-only selection metadata as discovery progresses.
-   * @param {Record<string, ReturnType<typeof JSON.parse>>} selection - Safe selection metadata.
-   * @returns {void}
-   */
-  setSelection(selection) {
-    Object.assign(this._selection, selection)
-  }
-
-  /**
-   * Registers and returns a deterministic scope identifier.
-   * @param {import("./test-runner.js").TestsArgument | import("@velocious/testing/runner").SuiteDeclaration} scope - Scope object.
-   * @param {object} args - Scope metadata.
-   * @param {string[]} args.descriptions - Scope description path.
-   * @param {string | undefined} args.filePath - Scope source path.
-   * @param {number | undefined} [args.line] - Scope source line.
-   * @param {string | undefined} [args.parentId] - Parent scope identifier.
-   * @returns {string} - Opaque scope identifier.
-   */
-  scopeId(scope, {descriptions, filePath, line, parentId}) {
-    const existing = this._scopeIds.get(scope)
-    if (existing) return existing
-
-    const safeFilePath = this.safeSourcePath(filePath)
-    const id = this.hash(`scope:${safeFilePath}:${line ?? 0}:${descriptions.join("\u0000")}`)
-
-    this._scopeIds.set(scope, id)
-    this._scopes.push({id, parentId, file: safeFilePath, line})
-    return id
-  }
-
-  /**
-   * Starts an attempt and its async attribution context.
-   * @param {object} args - Attempt metadata.
-   * @param {string[]} args.descriptions - Parent descriptions.
-   * @param {number} args.attemptNumber - Attempt number.
-   * @param {import("./test-runner.js").TestData} args.testData - Test declaration.
-   * @param {string} args.testDescription - Test description.
-   * @returns {TestProfileAttemptHandle} - Active attempt handle.
-   */
-  startAttempt({descriptions, attemptNumber, testData, testDescription}) {
-    const file = this.safeSourcePath(testData.ownerFilePath ?? testData.filePath)
-    const id = this.hash(`test:${file}:${testData.line ?? 0}:${[...descriptions, testDescription].join("\u0000")}`)
-    let testRecord = this._testsById.get(id)
-
-    if (!testRecord) {
-      testRecord = {id, file, line: testData.line, attempts: []}
-      this._testsById.set(id, testRecord)
-      this._tests.push(testRecord)
-    }
-
-    /** @type {TestProfileAttemptRecord} */
-    const attempt = {
-      number: attemptNumber,
-      status: "running",
-      durationMs: 0,
-      cpuMs: {user: 0, system: 0, total: 0},
-      spans: []
-    }
-    /** @type {Set<TestProfileAsyncContext>} */
-    const attemptContexts = new Set()
-    const context = {profiler: this, attempt, active: true, attemptContexts, filePath: file, span: undefined}
-
-    attemptContexts.add(context)
-
-    const handle = {context, attempt, startedAt: this.now(), cpuStartedAt: process.cpuUsage()}
-
-    testRecord.attempts.push(attempt)
-    this._activeAttempts.add(handle)
-
-    return handle
-  }
-
-  /**
-   * Runs work inside an attempt's async context.
-   * @template T
-   * @param {TestProfileAttemptHandle} handle - Attempt handle.
-   * @param {() => Promise<T>} callback - Attempt lifecycle.
-   * @returns {Promise<T>} - Callback result.
-   */
-  async runAttempt(handle, callback) {
-    return await this._configuration
-      .getEnvironmentHandler()
-      .runWithTestProfileContext(handle.context, callback)
-  }
-
-  /**
-   * Completes an attempt and prevents descendant late work from retaining attribution.
-   * @param {TestProfileAttemptHandle} handle - Attempt handle.
-   * @param {TestProfileAttemptStatus} status - Attempt result.
-   * @returns {void}
-   */
-  finishAttempt(handle, status) {
-    if (handle.attempt.status !== "running") return
-
-    for (const context of handle.context.attemptContexts || []) {
-      if (context.span) this.finishSpanContext(context)
-      context.active = false
-    }
-
-    handle.attempt.status = status
-    handle.attempt.durationMs = roundProfileDuration(this.now() - handle.startedAt)
-    handle.attempt.cpuMs = this.cpuDuration(handle.cpuStartedAt)
-    this.addFileAttemptDuration(handle.context.filePath, handle.attempt.durationMs)
-    this._activeAttempts.delete(handle)
-  }
-
-  /**
-   * Closes every active attempt and nested span at the current interruption boundary.
-   * @returns {void}
-   */
-  interrupt() {
-    for (const handle of [...this._activeAttempts]) {
-      this.finishAttempt(handle, "interrupted")
-    }
-
-    for (const context of [...this._activeSpanContexts]) {
-      this.finishSpanContext(context)
-    }
-  }
+import {
+  TestProfiler as PackageTestProfiler,
+  roundProfileDuration
+} from "@velocious/testing/node"
 
-  /**
-   * Runs a runner-owned phase span.
-   * @template T
-   * @param {object} args - Span metadata.
-   * @param {string} args.phase - Phase name.
-   * @param {string} [args.activity] - Custom activity label.
-   * @param {number} [args.declarationIndex] - Hook declaration index.
-   * @param {string} [args.declarationScopeId] - Hook declaration scope.
-   * @param {string} [args.filePath] - Source or owning test file.
-   * @param {() => (T | Promise<T>)} callback - Timed work.
-   * @returns {Promise<T>} - Callback result.
-   */
-  async runSpan({phase, activity, declarationIndex, declarationScopeId, filePath}, callback) {
-    const currentContext = this._configuration.getEnvironmentHandler().getCurrentTestProfileContext()
-
-    if (currentContext && !this.contextIsActive(currentContext)) {
-      this._unattributedLateEventCount++
-      return await callback()
-    }
-
-    const safeFilePath = currentContext?.filePath ?? (filePath ? this.safeSourcePath(filePath) : undefined)
-    const startedAt = this.now()
-    const cpuStartedAt = process.cpuUsage()
-    /** @type {TestProfileSpan} */
-    const span = {
-      phase,
-      executionOrder: ++this._executionOrder,
-      durationMs: 0,
-      cpuMs: {user: 0, system: 0, total: 0}
-    }
-
-    if (activity) span.activity = activity
-    if (declarationIndex !== undefined) span.declarationIndex = declarationIndex
-    if (declarationScopeId) span.declarationScopeId = declarationScopeId
-    if (safeFilePath) span.file = safeFilePath
-
-    if (currentContext?.attempt) {
-      currentContext.attempt.spans.push(span)
-    } else {
-      this._spans.push(span)
-    }
-
-    const spanContext = {
-      profiler: this,
-      attempt: currentContext?.attempt,
-      active: true,
-      attemptContexts: currentContext?.attemptContexts,
-      filePath: safeFilePath,
-      span,
-      spanStartedAt: startedAt,
-      spanCpuStartedAt: cpuStartedAt
-    }
-
-    spanContext.attemptContexts?.add(spanContext)
-    this._activeSpanContexts.add(spanContext)
-
-    try {
-      return await this._configuration
-        .getEnvironmentHandler()
-        .runWithTestProfileContext(spanContext, callback)
-    } finally {
-      if (spanContext.active) {
-        this.finishSpanContext(spanContext)
-      } else if (spanContext.attempt) {
-        this._unattributedLateEventCount++
-      }
-    }
-  }
+import restArgsError from "../utils/rest-args-error.js"
+import { registerTestProfileContextReader } from "./test-profile-context.js"
 
-  /**
-   * Finalizes an open span, including partial work closed by a timeout.
-   * @param {TestProfileAsyncContext} context - Span context.
-   * @returns {void}
-   */
-  finishSpanContext(context) {
-    if (!context.active || !context.span || context.spanStartedAt === undefined || !context.spanCpuStartedAt) return
+/** @typedef {import("@velocious/testing/node").TestProfileAsyncContext} TestProfileAsyncContext */
+/** @typedef {import("@velocious/testing/node").TestProfileAttemptHandle} TestProfileAttemptHandle */
+/** @typedef {import("@velocious/testing/node").TestProfileAttemptStatus} TestProfileAttemptStatus */
 
-    context.active = false
-    context.span.durationMs = roundProfileDuration(this.now() - context.spanStartedAt)
-    context.span.cpuMs = this.cpuDuration(context.spanCpuStartedAt)
-    this.addPhaseDuration(context.span.phase, context.span.durationMs, context.span.cpuMs)
-    this.addFileDuration(context.filePath, context.span.phase, context.span.durationMs, Boolean(context.attempt))
-    this._activeSpanContexts.delete(context)
-  }
+export { roundProfileDuration }
 
+/** Connects the package profiler to Velocious's environment-owned async context. */
+class VelociousProfileContextAdapter {
   /**
-   * Checks both a nested span boundary and its owning attempt boundary.
-   * @param {TestProfileAsyncContext} context - Candidate profile context.
-   * @returns {boolean} - Whether events may still be attributed.
+   * Creates the environment context adapter.
+   * @param {import("../environment-handlers/base.js").default} environmentHandler - Active environment handler.
    */
-  contextIsActive(context) {
-    return context.active && (!context.attempt || context.attempt.status === "running")
+  constructor(environmentHandler) {
+    this.environmentHandler = environmentHandler
   }
 
   /**
-   * Runs a validated application-defined activity.
-   * @template T
-   * @param {TestProfileAsyncContext} context - Captured async context.
-   * @param {string} name - Validated activity name.
-   * @param {() => (T | Promise<T>)} callback - Activity callback.
-   * @returns {Promise<T>} - Callback result.
+   * Gets the active framework profile context.
+   * @returns {TestProfileAsyncContext | undefined} - Current profile attribution.
    */
-  async profileActivity(context, name, callback) {
-    if (!this.contextIsActive(context)) {
-      this._unattributedLateEventCount++
-      return await callback()
-    }
-
-    const validatedName = validateTestActivityName(name)
-    let outputName = validatedName
-
-    if (!this._customActivityNames.has(validatedName)) {
-      if (this._customActivityNames.size >= MAX_CUSTOM_ACTIVITY_NAMES) {
-        outputName = "other"
-      } else {
-        this._customActivityNames.add(validatedName)
-      }
-    }
-
-    return await this.runSpan({phase: "custom", activity: outputName}, callback)
-  }
+  current() { return this.environmentHandler.getCurrentTestProfileContext() }
 
   /**
-   * Measures a command-level phase outside an attempt.
+   * Runs work with framework profile attribution.
    * @template T
-   * @param {string} phase - Phase name.
-   * @param {() => (T | Promise<T>)} callback - Timed work.
-   * @param {{filePath?: string}} [metadata] - Optional source ownership.
-   * @returns {Promise<T>} - Callback result.
-   */
-  async measurePhase(phase, callback, metadata = {}) {
-    return await this.runSpan({phase, filePath: metadata.filePath}, callback)
-  }
-
-  /**
-   * Records one successful or failed physical database query attempt.
-   * @param {TestProfileAsyncContext} context - Context captured when the query began.
-   * @param {{durationMs: number, failed: boolean, sqlFingerprint: string, sqlOperation: string}} args - Query aggregate values.
-   * @returns {void}
+   * @param {TestProfileAsyncContext} context - Profile attribution to install.
+   * @param {() => T} callback - Work to run.
+   * @returns {T} - Callback result.
    */
-  recordDatabaseQuery(context, {durationMs, failed, sqlFingerprint, sqlOperation}) {
-    if (!this.contextIsActive(context)) {
-      this._unattributedLateEventCount++
-      return
-    }
-
-    const safeDurationMs = roundProfileDuration(durationMs)
-
-    this.addDatabaseQueryAggregate(this._database, {durationMs: safeDurationMs, failed})
-    if (context.span) {
-      context.span.database ||= this.emptyDatabaseAggregate()
-      this.addDatabaseQueryAggregate(context.span.database, {durationMs: safeDurationMs, failed})
-    }
-
-    const safeOperation = SAFE_SQL_OPERATIONS.has(sqlOperation) ? sqlOperation : "UNKNOWN"
-    const fingerprintKey = `${safeOperation}:${sqlFingerprint}`
-    let fingerprint = this._queryFingerprints.get(fingerprintKey)
-
-    if (!fingerprint && this._queryFingerprints.size < 50) {
-      fingerprint = {
-        hash: sqlFingerprint,
-        operation: safeOperation,
-        count: 0,
-        failedCount: 0,
-        totalMs: 0,
-        maxMs: 0
-      }
-      this._queryFingerprints.set(fingerprintKey, fingerprint)
-    }
-
-    if (fingerprint) {
-      fingerprint.count++
-      if (failed) fingerprint.failedCount++
-      fingerprint.totalMs += safeDurationMs
-      fingerprint.maxMs = Math.max(fingerprint.maxMs, safeDurationMs)
-    }
-  }
-
-  /**
-   * Records a physical transaction action.
-   * @param {TestProfileAsyncContext} context - Context captured when the action began.
-   * @param {{action: "start" | "commit" | "rollback", durationMs: number, failed: boolean}} args - Transaction aggregate values.
-   * @returns {void}
-   */
-  recordDatabaseTransaction(context, {action, durationMs, failed}) {
-    if (!this.contextIsActive(context)) {
-      this._unattributedLateEventCount++
-      return
-    }
-
-    const aggregate = this._transactions[action]
-    const safeDurationMs = roundProfileDuration(durationMs)
-
-    aggregate.count++
-    if (failed) aggregate.failedCount++
-    aggregate.totalMs += safeDurationMs
-    aggregate.maxMs = Math.max(aggregate.maxMs, safeDurationMs)
-  }
-
-  /**
-   * Records one low-cardinality pool lifecycle delta.
-   * @param {TestProfileAsyncContext} context - Context captured when the operation began.
-   * @param {string} identifier - Logical pool identifier.
-   * @param {"connectionCreation" | "checkoutWait" | "checkoutTimeout" | "idleReap" | "idleReapDisposal" | "peakLiveConnections"} metric - Metric name.
-   * @param {{durationMs?: number, failed?: boolean, value?: number}} [values] - Aggregate values.
-   * @returns {void}
-   */
-  recordPoolMetric(context, identifier, metric, values = {}) {
-    if (!this.contextIsActive(context)) {
-      this._unattributedLateEventCount++
-      return
-    }
-
-    const aggregate = this.poolAggregate(this._pools, identifier)
-
-    this.addPoolMetric(aggregate, metric, values)
-
-    if (context.span) {
-      context.span.pools ||= []
-      const spanPools = new Map(context.span.pools.map((pool) => [pool.identifier, pool]))
-      const spanAggregate = this.poolAggregate(spanPools, identifier)
-
-      if (!context.span.pools.includes(spanAggregate)) context.span.pools.push(spanAggregate)
-      this.addPoolMetric(spanAggregate, metric, values)
-    }
-  }
-
-  /**
-   * Builds the final privacy-safe profile document.
-   * @param {object} args - Run result.
-   * @param {{discovered: number, executed: number, failed: number, passed: number}} args.counts - Run counts.
-   * @param {boolean} args.focused - Whether focused tests were selected.
-   * @param {string} args.status - Run status.
-   * @returns {ReturnType<typeof JSON.parse>} - Rich profile document.
-   */
-  finish({counts, focused, status}) {
-    if (this._finishedProfile) return this._finishedProfile
-
-    const totalDurationMs = roundProfileDuration(this.now() - this._startedAt)
-    const totalCpuMs = this.cpuDuration(this._cpuStartedAt)
-    const exclusivePhaseNames = BUILT_IN_PHASES
-    const measuredDurationMs = exclusivePhaseNames.reduce((sum, phase) => sum + this.phaseAggregate(phase).totalMs, 0)
-    const measuredCpuUserMs = exclusivePhaseNames.reduce((sum, phase) => sum + this.phaseAggregate(phase).cpuUserMs, 0)
-    const measuredCpuSystemMs = exclusivePhaseNames.reduce((sum, phase) => sum + this.phaseAggregate(phase).cpuSystemMs, 0)
-
-    this._phases.set("runner overhead", {
-      count: 1,
-      totalMs: Math.max(0, totalDurationMs - measuredDurationMs),
-      maxMs: Math.max(0, totalDurationMs - measuredDurationMs),
-      cpuUserMs: Math.max(0, totalCpuMs.user - measuredCpuUserMs),
-      cpuSystemMs: Math.max(0, totalCpuMs.system - measuredCpuSystemMs)
-    })
-    this._phases.set("total", {
-      count: 1,
-      totalMs: totalDurationMs,
-      maxMs: totalDurationMs,
-      cpuUserMs: totalCpuMs.user,
-      cpuSystemMs: totalCpuMs.system
-    })
-
-    const phases = Object.fromEntries([...this._phases.entries()].map(([phase, aggregate]) => [
-      phase,
-      this.publicAggregate(aggregate)
-    ]))
-    const files = [...this._files.values()]
-      .map((file) => ({
-        path: file.path,
-        importMs: roundProfileDuration(file.importMs),
-        hooksMs: roundProfileDuration(file.hooksMs),
-        testsMs: roundProfileDuration(file.testsMs),
-        attemptsMs: roundProfileDuration(file.attemptsMs),
-        totalMs: roundProfileDuration(file.totalMs)
-      }))
-      .sort((fileA, fileB) => compareTimingManifestPaths(fileA.path, fileB.path))
-    const timingManifest = Object.fromEntries(files.map((file) => [file.path, file.totalMs]))
-    const attempts = this._tests.reduce((sum, test) => sum + test.attempts.length, 0)
-
-    this._finishedProfile = {
-      schema: "velocious.test-profile",
-      schemaVersion: 1,
-      status,
-      selection: {...this._selection, focused},
-      counts: {...counts, attempts},
-      durationMs: totalDurationMs,
-      cpuMs: totalCpuMs,
-      phases,
-      files,
-      scopes: [...this._scopes].sort((scopeA, scopeB) => scopeA.id.localeCompare(scopeB.id)),
-      tests: this._tests.map((test) => ({
-        id: test.id,
-        file: test.file,
-        line: test.line,
-        durationMs: roundProfileDuration(test.attempts.reduce((sum, attempt) => sum + attempt.durationMs, 0)),
-        attempts: test.attempts
-      })),
-      spans: this._spans,
-      database: {
-        queryCount: this._database.queryCount,
-        failedQueryCount: this._database.failedQueryCount,
-        totalMs: roundProfileDuration(this._database.totalMs),
-        maxMs: roundProfileDuration(this._database.maxMs),
-        fingerprints: [...this._queryFingerprints.values()]
-          .map((fingerprint) => ({
-            ...fingerprint,
-            totalMs: roundProfileDuration(fingerprint.totalMs),
-            maxMs: roundProfileDuration(fingerprint.maxMs)
-          }))
-          .sort((fingerprintA, fingerprintB) => {
-            return fingerprintA.operation.localeCompare(fingerprintB.operation) || fingerprintA.hash.localeCompare(fingerprintB.hash)
-          }),
-        transactions: {
-          start: this.publicActionAggregate(this._transactions.start),
-          commit: this.publicActionAggregate(this._transactions.commit),
-          rollback: this.publicActionAggregate(this._transactions.rollback)
-        }
-      },
-      pools: [...this._pools.values()]
-        .map((pool) => this.publicPoolAggregate(pool))
-        .sort((poolA, poolB) => poolA.identifier.localeCompare(poolB.identifier)),
-      unattributedLateEventCount: this._unattributedLateEventCount,
-      timingManifest
-    }
-
-    return this._finishedProfile
-  }
-
-  /**
-   * Returns an internal phase aggregate.
-   * @param {string} phase - Phase name.
-   * @returns {InternalPhaseAggregate} - Aggregate.
-   */
-  phaseAggregate(phase) {
-    let aggregate = this._phases.get(phase)
-
-    if (!aggregate) {
-      aggregate = {count: 0, totalMs: 0, maxMs: 0, cpuUserMs: 0, cpuSystemMs: 0}
-      this._phases.set(phase, aggregate)
-    }
-
-    return aggregate
-  }
-
-  /**
-   * Adds a completed span to its aggregate phase.
-   * @param {string} phase - Phase name.
-   * @param {number} durationMs - Real duration.
-   * @param {{user: number, system: number, total: number}} cpuMs - CPU duration.
-   * @returns {void}
-   */
-  addPhaseDuration(phase, durationMs, cpuMs) {
-    const aggregate = this.phaseAggregate(phase)
-
-    aggregate.count++
-    aggregate.totalMs += durationMs
-    aggregate.maxMs = Math.max(aggregate.maxMs, durationMs)
-    aggregate.cpuUserMs += cpuMs.user
-    aggregate.cpuSystemMs += cpuMs.system
-  }
-
-  /**
-   * Adds an exclusive file-owned phase to timing-manifest weight.
-   * @param {string | undefined} filePath - Safe project-relative path.
-   * @param {string} phase - Phase name.
-   * @param {number} durationMs - Real duration.
-   * @param {boolean} [insideAttempt] - Whether the phase is already covered by complete attempt time.
-   * @returns {void}
-   */
-  addFileDuration(filePath, phase, durationMs, insideAttempt = false) {
-    if (!filePath) return
-    if (!["imports", "beforeAll", "beforeEach", "test body", "afterEach", "afterAll"].includes(phase)) return
-
-    let file = this._files.get(filePath)
-
-    if (!file) {
-      file = {path: filePath, importMs: 0, hooksMs: 0, testsMs: 0, attemptsMs: 0, totalMs: 0}
-      this._files.set(filePath, file)
-    }
-
-    if (phase === "imports") file.importMs += durationMs
-    if (phase === "test body") file.testsMs += durationMs
-    if (["beforeAll", "beforeEach", "afterEach", "afterAll"].includes(phase)) file.hooksMs += durationMs
-    if (!insideAttempt) file.totalMs += durationMs
-  }
-
-  /**
-   * Adds the complete cost of an attempt to its owning file weight.
-   * @param {string | undefined} filePath - Safe project-relative path.
-   * @param {number} durationMs - Attempt duration.
-   * @returns {void}
-   */
-  addFileAttemptDuration(filePath, durationMs) {
-    if (!filePath) return
-
-    let file = this._files.get(filePath)
-
-    if (!file) {
-      file = {path: filePath, importMs: 0, hooksMs: 0, testsMs: 0, attemptsMs: 0, totalMs: 0}
-      this._files.set(filePath, file)
-    }
-
-    file.attemptsMs += durationMs
-    file.totalMs += durationMs
-  }
-
-  /**
-   * Calculates process CPU time since a start sample.
-   * @param {ProcessCpuUsage} start - CPU start sample.
-   * @returns {{user: number, system: number, total: number}} - Millisecond CPU duration.
-   */
-  cpuDuration(start) {
-    const cpu = process.cpuUsage(start)
-    const user = roundProfileDuration(cpu.user / 1000)
-    const system = roundProfileDuration(cpu.system / 1000)
-
-    return {user, system, total: roundProfileDuration(user + system)}
-  }
-
-  /**
-   * Converts an internal aggregate to public rounded values.
-   * @param {InternalPhaseAggregate} [aggregate] - Internal aggregate.
-   * @returns {{count: number, totalMs: number, maxMs: number, cpuMs: {user: number, system: number, total: number}}} - Public aggregate.
-   */
-  publicAggregate(aggregate = {count: 0, totalMs: 0, maxMs: 0, cpuUserMs: 0, cpuSystemMs: 0}) {
-    const user = roundProfileDuration(aggregate.cpuUserMs)
-    const system = roundProfileDuration(aggregate.cpuSystemMs)
-
-    return {
-      count: aggregate.count,
-      totalMs: roundProfileDuration(aggregate.totalMs),
-      maxMs: roundProfileDuration(aggregate.maxMs),
-      cpuMs: {user, system, total: roundProfileDuration(user + system)}
-    }
-  }
-
-  /**
-   * Returns an empty query aggregate.
-   * @returns {ProfileDatabaseAggregate} - Empty aggregate.
-   */
-  emptyDatabaseAggregate() {
-    return {queryCount: 0, failedQueryCount: 0, totalMs: 0, maxMs: 0}
-  }
-
-  /**
-   * Adds a query attempt to a database aggregate.
-   * @param {ProfileDatabaseAggregate} aggregate - Aggregate to update.
-   * @param {{durationMs: number, failed: boolean}} args - Attempt values.
-   * @returns {void}
-   */
-  addDatabaseQueryAggregate(aggregate, {durationMs, failed}) {
-    aggregate.queryCount++
-    if (failed) aggregate.failedQueryCount++
-    aggregate.totalMs += durationMs
-    aggregate.maxMs = Math.max(aggregate.maxMs, durationMs)
-  }
-
-  /**
-   * Returns an empty action aggregate.
-   * @returns {ProfileActionAggregate} - Empty aggregate.
-   */
-  phaseAggregateShape() {
-    return {count: 0, failedCount: 0, totalMs: 0, maxMs: 0}
-  }
-
-  /**
-   * Rounds a transaction or pool action aggregate.
-   * @param {ProfileActionAggregate} aggregate - Internal aggregate.
-   * @returns {ProfileActionAggregate} - Public aggregate.
-   */
-  publicActionAggregate(aggregate) {
-    return {
-      count: aggregate.count,
-      failedCount: aggregate.failedCount,
-      totalMs: roundProfileDuration(aggregate.totalMs),
-      maxMs: roundProfileDuration(aggregate.maxMs)
-    }
-  }
-
-  /**
-   * Returns an empty pool aggregate.
-   * @param {string} [identifier] - Logical pool identifier.
-   * @returns {ProfilePoolAggregate} - Empty aggregate.
-   */
-  emptyPoolAggregate(identifier = "") {
-    return {
-      identifier,
-      connectionCreation: this.phaseAggregateShape(),
-      checkoutWait: {count: 0, totalMs: 0, maxMs: 0},
-      checkoutTimeoutCount: 0,
-      idleReap: {...this.phaseAggregateShape(), disposalCount: 0},
-      peakLiveConnections: 0
-    }
-  }
-
-  /**
-   * Gets or creates a pool aggregate in a map.
-   * @param {Map<string, ProfilePoolAggregate>} pools - Pool map.
-   * @param {string} identifier - Logical pool identifier.
-   * @returns {ProfilePoolAggregate} - Pool aggregate.
-   */
-  poolAggregate(pools, identifier) {
-    let aggregate = pools.get(identifier)
-
-    if (!aggregate) {
-      aggregate = this.emptyPoolAggregate(identifier)
-      pools.set(identifier, aggregate)
-    }
-
-    return aggregate
+  run(context, callback) {
+    return this.environmentHandler.runWithTestProfileContext(context, callback)
   }
+}
 
+/** Velocious compatibility facade around the package-owned profiler. */
+export default class TestProfiler extends PackageTestProfiler {
   /**
-   * Applies one pool metric delta.
-   * @param {ProfilePoolAggregate} aggregate - Pool aggregate.
-   * @param {"connectionCreation" | "checkoutWait" | "checkoutTimeout" | "idleReap" | "idleReapDisposal" | "peakLiveConnections"} metric - Metric name.
-   * @param {{durationMs?: number, failed?: boolean, value?: number}} values - Metric values.
-   * @returns {void}
+   * Creates the package profiler with Velocious environment context.
+   * @param {object} args - Profiler options.
+   * @param {import("../configuration.js").default} args.configuration - Test configuration.
+   * @param {string} args.projectDirectory - Project root used for portable paths.
+   * @param {Partial<import("@velocious/testing/node").TestProfileSelection>} [args.selection] - Selection metadata.
    */
-  addPoolMetric(aggregate, metric, values) {
-    const durationMs = roundProfileDuration(values.durationMs ?? 0)
-
-    if (metric === "connectionCreation" || metric === "idleReap") {
-      const actionAggregate = metric === "connectionCreation" ? aggregate.connectionCreation : aggregate.idleReap
-
-      actionAggregate.count++
-      if (values.failed) actionAggregate.failedCount++
-      actionAggregate.totalMs += durationMs
-      actionAggregate.maxMs = Math.max(actionAggregate.maxMs, durationMs)
-    } else if (metric === "checkoutWait") {
-      aggregate.checkoutWait.count++
-      aggregate.checkoutWait.totalMs += durationMs
-      aggregate.checkoutWait.maxMs = Math.max(aggregate.checkoutWait.maxMs, durationMs)
-    } else if (metric === "checkoutTimeout") {
-      aggregate.checkoutTimeoutCount++
-    } else if (metric === "idleReapDisposal") {
-      aggregate.idleReap.disposalCount++
-    } else if (metric === "peakLiveConnections") {
-      aggregate.peakLiveConnections = Math.max(aggregate.peakLiveConnections, values.value ?? 0)
-    }
-  }
+  constructor({configuration, projectDirectory, selection, ...restArgs}) {
+    restArgsError(restArgs)
+    const contextAdapter = new VelociousProfileContextAdapter(configuration.getEnvironmentHandler())
 
-  /**
-   * Rounds a pool aggregate for output.
-   * @param {ProfilePoolAggregate} aggregate - Internal aggregate.
-   * @returns {ProfilePoolAggregate} - Public aggregate.
-   */
-  publicPoolAggregate(aggregate) {
-    return {
-      identifier: aggregate.identifier,
-      connectionCreation: this.publicActionAggregate(aggregate.connectionCreation),
-      checkoutWait: {
-        count: aggregate.checkoutWait.count,
-        totalMs: roundProfileDuration(aggregate.checkoutWait.totalMs),
-        maxMs: roundProfileDuration(aggregate.checkoutWait.maxMs)
-      },
-      checkoutTimeoutCount: aggregate.checkoutTimeoutCount,
-      idleReap: {
-        ...this.publicActionAggregate(aggregate.idleReap),
-        disposalCount: aggregate.idleReap.disposalCount
-      },
-      peakLiveConnections: aggregate.peakLiveConnections
-    }
+    super({contextAdapter, projectDirectory, selection})
+    registerTestProfileContextReader(configuration, () => contextAdapter.current())
   }
 }