velocious 1.0.563 → 1.0.564

package/src/sync/local-mutation-log.js

@@ -1,19 +1,8 @@
-// @ts-check
-
-const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
-const PENDING_STATUS_VALUES = /** @type {LocalMutationStatus[]} */ (["pending", "applied-locally", "peer-applied"])
-const PENDING_STATUSES = new Set(PENDING_STATUS_VALUES)
-const MUTATION_STATUSES = new Set([...PENDING_STATUSES, "conflict", "rejected", "synced"])
-const TERMINAL_STATUSES = new Set(["rejected", "synced"])
-/** @type {Map<string, Promise<unknown>>} */
-const STORAGE_KEY_LOCKS = new Map()
-
 /**
  * Local mutation log record query options.
  * @typedef {object} LocalMutationLogRecordsOptions
  * @property {LocalMutationStatus[]} [statuses] - Optional status filter.
  */
-
 /**
  * Local mutation log row-oriented storage adapter.
  *
@@ -28,19 +17,16 @@ const STORAGE_KEY_LOCKS = new Map()
  * @property {(storageKey: string, options?: LocalMutationLogRecordsOptions) => Promise<LocalMutationLogRecord[]> | LocalMutationLogRecord[]} records - Reads log records.
  * @property {(storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void} updateRecord - Replaces one log record.
  */
-
 /**
  * Local sync mutation dependency metadata.
  * @typedef {object} LocalMutationDependency
  * @property {string} clientMutationId - Client mutation id this mutation depends on.
  * @property {string} model - Dependent model/resource name.
  */
-
 /**
  * Local mutation log status.
  * @typedef {"pending" | "applied-locally" | "peer-applied" | "conflict" | "rejected" | "synced"} LocalMutationStatus
  * */
-
 /**
  * Local mutation log record.
  * @typedef {object} LocalMutationLogRecord
@@ -53,6 +39,15 @@ const STORAGE_KEY_LOCKS = new Map()
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} [syncResult] - Backend replay/result metadata.
  * @property {string} updatedAt - ISO timestamp when the record was last changed.
  */
+// @ts-check
+
+const DEFAULT_STORAGE_KEY = "velocious.sync.localMutationLog"
+const PENDING_STATUS_VALUES = /** @type {LocalMutationStatus[]} */ (["pending", "applied-locally", "peer-applied"])
+const PENDING_STATUSES = new Set(PENDING_STATUS_VALUES)
+const MUTATION_STATUSES = new Set([...PENDING_STATUSES, "conflict", "rejected", "synced"])
+const TERMINAL_STATUSES = new Set(["rejected", "synced"])
+/** @type {Map<string, Promise<unknown>>} */
+const STORAGE_KEY_LOCKS = new Map()
 
 /** Client-side append-only sync mutation log with pluggable persistent storage. */
 export default class LocalMutationLog {

package/src/sync/offline-grant.js

@@ -1,8 +1,3 @@
-// @ts-check
-
-const OFFLINE_GRANT_SIGNATURE_ALGORITHM = "HS256"
-const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
-
 /**
  * Signed offline grant envelope.
  * @typedef {object} SignedOfflineGrant
@@ -11,7 +6,6 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {string} keyId - Signing key id.
  * @property {string} signature - Hex HMAC signature with a hmac-sha256 prefix.
  */
-
 /**
  * Backend-issued offline grant payload.
  * @typedef {object} OfflineGrant
@@ -23,7 +17,6 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {Record<string, import("../configuration-types.js").FrontendModelSyncJsonValue>} scopes - Materialized grant scopes.
  * @property {string} userId - Actor user id allowed to use the grant.
  */
-
 /**
  * Offline grant signing key.
  * @typedef {object} OfflineGrantSigningKey
@@ -31,6 +24,10 @@ const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
  * @property {string} id - Public key id included in signed grant envelopes.
  * @property {string} secret - Private HMAC secret. Never expose this to clients.
  */
+// @ts-check
+
+const OFFLINE_GRANT_SIGNATURE_ALGORITHM = "HS256"
+const OFFLINE_GRANT_SIGNATURE_PREFIX = "hmac-sha256-"
 
 /**
  * Creates a signed offline grant envelope.

package/src/sync/peer-mutation-bundle.js

@@ -2,9 +2,6 @@
 
 import {createSignedMutation, mutationIdempotencyKey, verifySignedMutation} from "./device-identity.js"
 
-const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
-const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
-
 /**
  * Peer mutation bundle exported by a device for offline/P2P transfer.
  * @typedef {object} PeerMutationBundle
@@ -12,7 +9,6 @@ const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
  * @property {"velocious.sync.peer-mutation-bundle.v1"} format - Bundle format identifier.
  * @property {PeerMutationBundleEntry[]} mutations - Signed mutations in local sequence order.
  */
-
 /**
  * One peer mutation bundle entry.
  * @typedef {object} PeerMutationBundleEntry
@@ -20,6 +16,8 @@ const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
  * @property {number} [localSequence] - Exporting device's local mutation sequence.
  * @property {import("./device-identity.js").SignedSyncMutation} signedMutation - Device-signed mutation envelope.
  */
+const PEER_MUTATION_BUNDLE_FORMAT = "velocious.sync.peer-mutation-bundle.v1"
+const EXPORTABLE_STATUSES = new Set(["pending", "applied-locally", "conflict"])
 
 /**
  * Exports local non-terminal mutations as a signed peer-transfer bundle.

package/src/sync/server-change-feed.js

@@ -4,6 +4,38 @@ import {randomUUID} from "crypto"
 import TableData from "../database/table-data/index.js"
 import stableJsonStringify from "./stable-json.js"
 
+/**
+ * @typedef {object} ServerChangeFeedEntry
+ * @property {string | null} actorDeviceId - Signed mutation actor device id when available.
+ * @property {string | null} actorUserId - Signed mutation actor user id when available.
+ * @property {Record<string, ?> | null} attributes - Serialized mutation attributes.
+ * @property {string} createdAt - Server change creation timestamp.
+ * @property {string} id - Server change id.
+ * @property {string | null} idempotencyKey - Mutation idempotency key when available.
+ * @property {string} model - Frontend model name.
+ * @property {string} operation - Mutation operation.
+ * @property {Record<string, ?> | null} payload - Serialized mutation payload.
+ * @property {string | null} recordId - Changed record id when known.
+ * @property {Record<string, ?> | null} response - Command response payload.
+ * @property {Record<string, ?> | null} scope - Offline grant scope.
+ * @property {number} serverSequence - Monotonic server sequence.
+ */
+/**
+ * @typedef {object} ServerChangeFeedRow
+ * @property {string | null} actor_device_id - Actor device id.
+ * @property {string | null} actor_user_id - Actor user id.
+ * @property {string | null} attributes_json - Attributes JSON.
+ * @property {Date | string} created_at - Creation time.
+ * @property {string} id - Entry id.
+ * @property {string | null} idempotency_key - Mutation idempotency key.
+ * @property {string} model - Frontend model name.
+ * @property {string} operation - Mutation operation.
+ * @property {string | null} payload_json - Mutation payload JSON.
+ * @property {string | null} record_id - Record id.
+ * @property {string | null} response_json - Response JSON.
+ * @property {string | null} scope_json - Scope JSON.
+ * @property {number | string} server_sequence - Server sequence.
+ */
 const DEFAULT_RETENTION_SIZE = 10000
 const DEFAULT_PAGE_SIZE = 100
 const MAX_PAGE_SIZE = 1000
@@ -464,37 +496,3 @@ function scopesEqual(changeScope, requestedScope) {
 
   return stableJsonStringify(changeScope || null) === stableJsonStringify(requestedScope)
 }
-
-/**
- * @typedef {object} ServerChangeFeedEntry
- * @property {string | null} actorDeviceId - Signed mutation actor device id when available.
- * @property {string | null} actorUserId - Signed mutation actor user id when available.
- * @property {Record<string, ?> | null} attributes - Serialized mutation attributes.
- * @property {string} createdAt - Server change creation timestamp.
- * @property {string} id - Server change id.
- * @property {string | null} idempotencyKey - Mutation idempotency key when available.
- * @property {string} model - Frontend model name.
- * @property {string} operation - Mutation operation.
- * @property {Record<string, ?> | null} payload - Serialized mutation payload.
- * @property {string | null} recordId - Changed record id when known.
- * @property {Record<string, ?> | null} response - Command response payload.
- * @property {Record<string, ?> | null} scope - Offline grant scope.
- * @property {number} serverSequence - Monotonic server sequence.
- */
-
-/**
- * @typedef {object} ServerChangeFeedRow
- * @property {string | null} actor_device_id - Actor device id.
- * @property {string | null} actor_user_id - Actor user id.
- * @property {string | null} attributes_json - Attributes JSON.
- * @property {Date | string} created_at - Creation time.
- * @property {string} id - Entry id.
- * @property {string | null} idempotency_key - Mutation idempotency key.
- * @property {string} model - Frontend model name.
- * @property {string} operation - Mutation operation.
- * @property {string | null} payload_json - Mutation payload JSON.
- * @property {string | null} record_id - Record id.
- * @property {string | null} response_json - Response JSON.
- * @property {string | null} scope_json - Scope JSON.
- * @property {number | string} server_sequence - Server sequence.
- */

package/src/sync/sync-api-client.js

@@ -4,8 +4,6 @@ import {optionalBoolean, optionalInteger} from "typanic"
 
 import recordChanges from "../database/record-changes.js"
 
-const syncTaskPromises = new Map()
-
 /** @typedef {import("./sync-api-client-types.js").SyncChangeApplyResult} SyncChangeApplyResult */
 /** @typedef {import("./sync-api-client-types.js").SyncChangeEnvelope} SyncChangeEnvelope */
 /** @typedef {import("./sync-api-client-types.js").SyncChangesRequest} SyncChangesRequest */
@@ -15,6 +13,7 @@ const syncTaskPromises = new Map()
 /** @typedef {import("./sync-api-client-types.js").SyncReplayItem} SyncReplayItem */
 /** @typedef {import("./sync-api-client-types.js").SyncReplayResponse} SyncReplayResponse */
 /** @typedef {import("./sync-api-client-types.js").SyncResourceConfig} SyncResourceConfig */
+const syncTaskPromises = new Map()
 
 /**
  * Generic client-side helper for replaying pending sync envelopes through the

package/src/sync/sync-envelope-replay-service.js

@@ -7,6 +7,23 @@ import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
 import {ValidationError} from "../database/record/index.js"
 import VelociousError from "../velocious-error.js"
 
+/**
+ * Resolved routed-resource registration for one replay resource type.
+ * @typedef {object} SyncReplayResourceRegistration
+ * @property {string} modelName - Effective frontend model name.
+ * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Routed resource class.
+ * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} resourceConfiguration - Normalized resource configuration when registry-resolved.
+ */
+/**
+ * @typedef {object} SyncReplayMutation
+ * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
+ * @property {Record<string, ?>} data - Parsed mutation payload.
+ * @property {?} id - Client sync row id for per-sync responses.
+ * @property {string} resourceId - Resource id as a string.
+ * @property {string} resourceType - Resource/model name.
+ * @property {string} serializedData - JSON serialized mutation payload.
+ * @property {string} syncType - Sync operation type.
+ */
 /**
  * One declarative broadcast fanned out after a mutation applies.
  * @typedef {object} SyncReplayBroadcast
@@ -778,22 +795,3 @@ export default class SyncEnvelopeReplayService {
     await deliverDeclaredBroadcasts({args, broadcaster: this.broadcaster, broadcasts: this.broadcasts})
   }
 }
-
-/**
- * Resolved routed-resource registration for one replay resource type.
- * @typedef {object} SyncReplayResourceRegistration
- * @property {string} modelName - Effective frontend model name.
- * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Routed resource class.
- * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} resourceConfiguration - Normalized resource configuration when registry-resolved.
- */
-
-/**
- * @typedef {object} SyncReplayMutation
- * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
- * @property {Record<string, ?>} data - Parsed mutation payload.
- * @property {?} id - Client sync row id for per-sync responses.
- * @property {string} resourceId - Resource id as a string.
- * @property {string} resourceType - Resource/model name.
- * @property {string} serializedData - JSON serialized mutation payload.
- * @property {string} syncType - Sync operation type.
- */

package/src/sync/sync-resource-base.js

@@ -7,8 +7,6 @@ import SyncEnvelopeReplayService from "./sync-envelope-replay-service.js"
 import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
 import VelociousError from "../velocious-error.js"
 
-const QUICK_SEARCH_COLUMN = "quickSearch"
-
 /**
  * Optional client-declared sync scope carried on a changes request.
  * @typedef {object} SerializedChangesScope
@@ -16,6 +14,7 @@ const QUICK_SEARCH_COLUMN = "quickSearch"
  * @property {string | null} resourceType - Client resource/model name the scope was declared for, or null for the all-types (user) scope: one scope covering every resource type this resource authorizes for the caller, so a sync authorizes once however many types it serves.
  * @property {string[] | null} resourceTypes - For the all-types scope, the resource types the client can apply. A cheap delivery/type filter only - it narrows, never widens, what the app's authorization already allows. Null for a type-declared scope.
  */
+const QUICK_SEARCH_COLUMN = "quickSearch"
 
 /**
  * Base resource for Velocious sync endpoints.

package/src/sync/sync-scope-store.js

@@ -6,6 +6,15 @@ import UUID from "pure-uuid"
 import {scopeKey} from "./query-scope.js"
 import stableJsonStringify from "./stable-json.js"
 
+/**
+ * @typedef {object} SyncScopeRow
+ * @property {Record<string, ?>} conditions - Scope attribute conditions.
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
+ * @property {string} id - Scope row id.
+ * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
+ * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
+ * @property {string} state - Scope state ("active" or "removed").
+ */
 const TABLE_NAME = "velocious_sync_scopes"
 const SCOPE_DIGEST_PREFIX = "velocious-sync-scope:"
 
@@ -19,16 +28,6 @@ function scopeDigestForScope(scope) {
   return new UUID(5, "ns:URL", `${SCOPE_DIGEST_PREFIX}${scopeKey(scope)}`).format()
 }
 
-/**
- * @typedef {object} SyncScopeRow
- * @property {Record<string, ?>} conditions - Scope attribute conditions.
- * @property {string | null} cursorPayload - Persisted cursor JSON payload.
- * @property {string} id - Scope row id.
- * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
- * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
- * @property {string} state - Scope state ("active" or "removed").
- */
-
 /**
  * Framework-owned local persistence for declared sync scopes and their cursors.
  *

package/src/testing/test-filter-parser.js

@@ -1,3 +1,13 @@
+/**
+ * ParseFiltersResult type.
+ * @typedef {object} ParseFiltersResult
+ * @property {string[]} includeTags - Tags to include.
+ * @property {string[]} excludeTags - Tags to exclude.
+ * @property {string[]} examplePatterns - Example name patterns.
+ * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
+ * @property {number | undefined} groups - Total number of groups for test splitting.
+ * @property {number | undefined} groupNumber - Which group to run (1-indexed).
+ */
 // @ts-check
 
 const INCLUDE_TAG_FLAGS = new Set(["--tag", "--include-tag", "-t"])
@@ -50,17 +60,6 @@ export function normalizeExamplePatterns(patterns) {
   return normalized
 }
 
-/**
- * ParseFiltersResult type.
- * @typedef {object} ParseFiltersResult
- * @property {string[]} includeTags - Tags to include.
- * @property {string[]} excludeTags - Tags to exclude.
- * @property {string[]} examplePatterns - Example name patterns.
- * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
- * @property {number | undefined} groups - Total number of groups for test splitting.
- * @property {number | undefined} groupNumber - Which group to run (1-indexed).
- */
-
 /**
  * Runs the parseFilters helper.
  * @param {string[]} processArgs - Process args.

package/src/testing/test-runner.js

@@ -13,6 +13,87 @@ import {testConfig, testEvents, tests} from "./test.js"
 import {pathToFileURL} from "url"
 import {clearDeliveries} from "../mailer.js"
 
+/**
+ * ConsoleMethodName type.
+ * @typedef {"log" | "info" | "warn" | "error" | "debug"} ConsoleMethodName */
+/**
+ * AttemptConsoleOutput type.
+ * @typedef {object} AttemptConsoleOutput
+ * @property {number} attemptNumber - Attempt number.
+ * @property {string} output - Captured console output.
+ */
+/**
+ * TestArgs type.
+ * @typedef {object} TestArgs
+ * @property {Application} [application] - Application instance for integration tests.
+ * @property {RequestClient} [client] - HTTP client for request tests.
+ * @property {object} [databaseCleaning] - Database cleanup options for tests.
+ * @property {boolean} [databaseCleaning.transaction] - Use transactions to rollback between tests.
+ * @property {boolean} [databaseCleaning.truncate] - Truncate tables between tests.
+ * @property {boolean} [databaseCleaning.truncateBefore] - Truncate tables before each test, in addition to the default cleanup.
+ * @property {boolean} [focus] - Whether this test is focused.
+ * @property {() => (void|Promise<void>)} [function] - Test callback function.
+ * @property {number} [retry] - Number of retries when a test fails.
+ * @property {string[] | string} [tags] - Tags for filtering.
+ * @property {number} [timeoutSeconds] - Timeout in seconds for the test.
+ * @property {string} [type] - Test type identifier.
+ */
+/**
+ * TestData type.
+ * @typedef {object} TestData
+ * @property {TestArgs} args - Arguments passed to the test.
+ * @property {string} [filePath] - Source file path.
+ * @property {number} [line] - Source line number.
+ * @property {function(TestArgs) : (void|Promise<void>)} function - Test callback to execute.
+ */
+/**
+ * FailedTestDetail type.
+ * @typedef {object} FailedTestDetail
+ * @property {string} fullDescription - Full test description.
+ * @property {string} [filePath] - Source file path.
+ * @property {number} [line] - Source line number.
+ * @property {?} error - Failure error.
+ * @property {string} [consoleOutput] - Captured console output while test ran.
+ * @property {string} [consoleLogPath] - Saved console log path.
+ */
+/**
+ * ActiveAfterAllScopeEntry type.
+ * @typedef {object} ActiveAfterAllScopeEntry
+ * @property {TestsArgument} tests - Scope test tree.
+ * @property {boolean} afterAllsRun - Whether cleanup hooks have run.
+ */
+/**
+ * Defines this typedef.
+ * @typedef {function({configuration: import("../configuration.js").default, testArgs: TestArgs, testData: TestData}) : (void|Promise<void>)} AfterBeforeEachCallbackType
+ */
+/**
+ * AfterBeforeEachCallbackObjectType type.
+ * @typedef {object} AfterBeforeEachCallbackObjectType
+ * @property {AfterBeforeEachCallbackType} callback - Hook callback to execute.
+ */
+/**
+ * Defines this typedef.
+ * @typedef {function({configuration: import("../configuration.js").default}) : (void|Promise<void>)} BeforeAfterAllCallbackType
+ */
+/**
+ * BeforeAfterAllCallbackObjectType type.
+ * @typedef {object} BeforeAfterAllCallbackObjectType
+ * @property {BeforeAfterAllCallbackType} callback - Hook callback to execute.
+ */
+/**
+ * TestsArgument type.
+ * @typedef {object} TestsArgument
+ * @property {Record<string, TestData>} args - Arguments keyed by test description.
+ * @property {boolean} [anyTestsFocussed] - Whether any tests in the tree are focused.
+ * @property {AfterBeforeEachCallbackObjectType[]} afterEaches - After-each hooks for this scope.
+ * @property {BeforeAfterAllCallbackObjectType[]} afterAlls - After-all hooks for this scope.
+ * @property {BeforeAfterAllCallbackObjectType[]} beforeAlls - Before-all hooks for this scope.
+ * @property {AfterBeforeEachCallbackObjectType[]} beforeEaches - Before-each hooks for this scope.
+ * @property {string} [filePath] - Source file path.
+ * @property {number} [line] - Source line number.
+ * @property {Record<string, TestData>} tests - A unique identifier for the node.
+ * @property {Record<string, TestsArgument>} subs - Optional child nodes. Each item is another `Node`, allowing recursion.
+ */
 /**
  * Marks the error thrown by {@link runWithTimeout} so the caller can tell a
  * lifecycle timeout (the promise is still running detached) apart from an
@@ -85,22 +166,11 @@ function awaitSettledOrGrace(lifecycle, graceMs) {
   })
 }
 
-/**
- * ConsoleMethodName type.
- * @typedef {"log" | "info" | "warn" | "error" | "debug"} ConsoleMethodName */
-
 /**
  * Captured console methods.
  * @type {ConsoleMethodName[]} */
 const CAPTURED_CONSOLE_METHODS = ["log", "info", "warn", "error", "debug"]
 
-/**
- * AttemptConsoleOutput type.
- * @typedef {object} AttemptConsoleOutput
- * @property {number} attemptNumber - Attempt number.
- * @property {string} output - Captured console output.
- */
-
 /**
  * Runs to file slug.
  * @param {string} value - Value to sanitize.
@@ -114,87 +184,6 @@ function toFileSlug(value) {
     .slice(0, 80) || "failed-test"
 }
 
-/**
- * TestArgs type.
- * @typedef {object} TestArgs
- * @property {Application} [application] - Application instance for integration tests.
- * @property {RequestClient} [client] - HTTP client for request tests.
- * @property {object} [databaseCleaning] - Database cleanup options for tests.
- * @property {boolean} [databaseCleaning.transaction] - Use transactions to rollback between tests.
- * @property {boolean} [databaseCleaning.truncate] - Truncate tables between tests.
- * @property {boolean} [databaseCleaning.truncateBefore] - Truncate tables before each test, in addition to the default cleanup.
- * @property {boolean} [focus] - Whether this test is focused.
- * @property {() => (void|Promise<void>)} [function] - Test callback function.
- * @property {number} [retry] - Number of retries when a test fails.
- * @property {string[] | string} [tags] - Tags for filtering.
- * @property {number} [timeoutSeconds] - Timeout in seconds for the test.
- * @property {string} [type] - Test type identifier.
- */
-
-/**
- * TestData type.
- * @typedef {object} TestData
- * @property {TestArgs} args - Arguments passed to the test.
- * @property {string} [filePath] - Source file path.
- * @property {number} [line] - Source line number.
- * @property {function(TestArgs) : (void|Promise<void>)} function - Test callback to execute.
- */
-
-/**
- * FailedTestDetail type.
- * @typedef {object} FailedTestDetail
- * @property {string} fullDescription - Full test description.
- * @property {string} [filePath] - Source file path.
- * @property {number} [line] - Source line number.
- * @property {?} error - Failure error.
- * @property {string} [consoleOutput] - Captured console output while test ran.
- * @property {string} [consoleLogPath] - Saved console log path.
- */
-
-/**
- * ActiveAfterAllScopeEntry type.
- * @typedef {object} ActiveAfterAllScopeEntry
- * @property {TestsArgument} tests - Scope test tree.
- * @property {boolean} afterAllsRun - Whether cleanup hooks have run.
- */
-
-/**
- * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default, testArgs: TestArgs, testData: TestData}) : (void|Promise<void>)} AfterBeforeEachCallbackType
- */
-
-/**
- * AfterBeforeEachCallbackObjectType type.
- * @typedef {object} AfterBeforeEachCallbackObjectType
- * @property {AfterBeforeEachCallbackType} callback - Hook callback to execute.
- */
-
-/**
- * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default}) : (void|Promise<void>)} BeforeAfterAllCallbackType
- */
-
-/**
- * BeforeAfterAllCallbackObjectType type.
- * @typedef {object} BeforeAfterAllCallbackObjectType
- * @property {BeforeAfterAllCallbackType} callback - Hook callback to execute.
- */
-
-/**
- * TestsArgument type.
- * @typedef {object} TestsArgument
- * @property {Record<string, TestData>} args - Arguments keyed by test description.
- * @property {boolean} [anyTestsFocussed] - Whether any tests in the tree are focused.
- * @property {AfterBeforeEachCallbackObjectType[]} afterEaches - After-each hooks for this scope.
- * @property {BeforeAfterAllCallbackObjectType[]} afterAlls - After-all hooks for this scope.
- * @property {BeforeAfterAllCallbackObjectType[]} beforeAlls - Before-all hooks for this scope.
- * @property {AfterBeforeEachCallbackObjectType[]} beforeEaches - Before-each hooks for this scope.
- * @property {string} [filePath] - Source file path.
- * @property {number} [line] - Source line number.
- * @property {Record<string, TestData>} tests - A unique identifier for the node.
- * @property {Record<string, TestsArgument>} subs - Optional child nodes. Each item is another `Node`, allowing recursion.
- */
-
 export default class TestRunner {
   /**
    * Narrows the runtime value to the documented type.
@@ -539,17 +528,18 @@ export default class TestRunner {
   }
 
   /**
-   * Pins each per-test connection as its pool's in-process test shared connection so
-   * HTTP request handlers dispatched during the test (which run in the main thread but
-   * in a fresh async context without the connection pin) resolve to the SAME connection
-   * — and therefore the same open transaction — as the test body. Pools that predate the
-   * shared-connection hook are skipped. Pair with {@link clearTestSharedConnections} in a
-   * finally.
-   * @returns {void}
+   * Registers each non-tenant per-test connection as a dynamic candidate for in-process
+   * request sharing. The pool evaluates transaction state when each request is dispatched,
+   * so a transaction started or ended during a hook callback takes effect immediately.
+   * Inactive and tenant-only connections remain independently pooled. Pair with
+   * {@link clearTestSharedConnections} in a finally.
+   * @returns {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} - Lifecycle-owned registrations.
    */
   activateTestSharedConnections() {
     const configuration = this.getConfiguration()
     const currentConnections = configuration.getCurrentConnections()
+    /** @type {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} */
+    const registrations = []
 
     for (const identifier of Object.keys(currentConnections)) {
       const pool = configuration.getDatabasePool(identifier)
@@ -561,16 +551,33 @@ export default class TestRunner {
       if (pool.getConfiguration().tenantOnly) {
         continue
       }
-      pool.setTestSharedConnection(currentConnections[identifier])
+
+      const connection = currentConnections[identifier]
+
+      const registration = pool.setTestSharedConnectionProvider(() => {
+        return connection.insideTransaction() ? connection : undefined
+      })
+
+      if (registration) registrations.push({pool, registration})
     }
+
+    return registrations
   }
 
   /**
    * Clears the in-process test shared connection on every configured pool. Idempotent and
    * safe to call when none was set.
+   * @param {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} [registrations] - Lifecycle-owned registrations to clear conditionally.
    * @returns {void}
    */
-  clearTestSharedConnections() {
+  clearTestSharedConnections(registrations) {
+    if (registrations) {
+      for (const {pool, registration} of registrations) {
+        pool.clearTestSharedConnection(registration)
+      }
+      return
+    }
+
     const configuration = this.getConfiguration()
 
     for (const identifier of configuration.getDatabaseIdentifiers()) {
@@ -976,6 +983,8 @@ export default class TestRunner {
            * still wait for it to settle after runWithTimeout has abandoned it.
            * @type {Promise<?> | undefined} */
           let testLifecycle
+          /** @type {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} */
+          let testSharedConnectionRegistrations = []
           /**
            * Shared mutable flag so the catch block can suppress the
            * `_successfulTests` increment inside the still-detached lifecycle:
@@ -1002,12 +1011,11 @@ export default class TestRunner {
               // stale async-context pin and force every later test onto a fresh checkout,
               // breaking isolation).
               await this.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, async () => {
-                // Only request-type tests dispatch through the in-process HTTP handler,
-                // so only they need the pinned connection shared with it. Sharing it for
-                // every test would let unrelated specs observe a test shared connection on
-                // pools they inspect directly. Cleared after afterEach either way.
+                // Register dynamic candidates before application hooks so transaction
+                // state changes made during a hook are visible to a request dispatched
+                // by that same callback.
                 if (testArgs.type == "request") {
-                  this.activateTestSharedConnections()
+                  testSharedConnectionRegistrations = this.activateTestSharedConnections()
                 }
 
                 try {
@@ -1035,7 +1043,7 @@ export default class TestRunner {
                     }
                   }
                 } finally {
-                  this.clearTestSharedConnections()
+                  this.clearTestSharedConnections(testSharedConnectionRegistrations)
                 }
               })
             })
@@ -1077,7 +1085,7 @@ export default class TestRunner {
               // ensureConnections before activateTestSharedConnections() replaces
               // it. Clear it here so the next test checks out a fresh connection.
               // Idempotent when the lifecycle did settle and already cleared.
-              this.clearTestSharedConnections()
+              this.clearTestSharedConnections(testSharedConnectionRegistrations)
             }
 
             willRetry = retriesUsed < retryCount