effect 4.0.6 → 4.1.0

package/src/rpc/RpcServer.ts

@@ -89,6 +89,15 @@ export interface RpcServer<A extends Rpc.Any> {
  * the request fails with that cause. `onFromServer` is assumed to have already
  * answered the client and reported it, so nothing else is sent or reported.
  *
+ * A request with `isNotification` set runs like any other, but no `Exit`,
+ * `Chunk` or `Defect` is sent for it. Its failures are still reported.
+ *
+ * A request with `discard` set is acknowledged with a successful `Exit` once
+ * its handler starts, after the concurrency permit is taken and the
+ * middleware has run. Nothing else is sent for it after that, and its
+ * failures are only reported. A failure before the acknowledgement is sent as
+ * a failed `Exit` for that request.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -255,16 +264,23 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
     if (client.fibers.has(request.id)) {
       return Effect.interrupt
     }
+    const isNotification = request.isNotification === true
+    const isDiscard = !isNotification && request.discard === true
+    let acknowledged = false
+    // a notification, or a discarded call once it has been acknowledged, gets
+    // no reply of any kind
+    const respond = (exit: Exit.Exit<any, any>): Effect.Effect<void> =>
+      isNotification || acknowledged ? Effect.void : options.onFromServer({
+        _tag: "Exit",
+        clientId: client.id,
+        requestId: request.id,
+        exit
+      })
     const rpc = group.requests.get(request.tag) as any as Rpc.AnyWithProps
     const entry = Context.getOrUndefinedUnsafe(services, rpc?.key) as Rpc.Handler<Rpcs["_tag"]>
     if (!rpc || !entry) {
       const write = Effect.catchDefect(
-        options.onFromServer({
-          _tag: "Exit",
-          clientId: client.id,
-          requestId: request.id,
-          exit: Exit.die(`Unknown request tag: ${request.tag}`)
-        }),
+        respond(Exit.die(`Unknown request tag: ${request.tag}`)),
         (defect) => sendDefect(client, defect)
       )
       if (!client.ended || client.fibers.size > 0) return write
@@ -278,7 +294,18 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
       headers: request.headers,
       payload: request.payload
     }
-    const result = entry.handler(request.payload, metadata)
+    let handlerResult: ReturnType<typeof entry.handler>
+    // a handler that throws while being constructed never starts, so it is
+    // neither streamed nor acknowledged
+    let constructionFailed = false
+    try {
+      handlerResult = entry.handler(request.payload, metadata)
+    } catch (defect) {
+      handlerResult = Effect.die(defect)
+      constructionFailed = true
+    }
+    // a const, so that the narrowing below can be aliased
+    const result = handlerResult
 
     // if the handler requested forking, then we skip the concurrency control
     const isWrapper = Rpc.isWrapper(result)
@@ -288,11 +315,23 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
     const streamOrEffect = isWrapper ? result.value : result
     // set when a chunk could not be written; the writer has already responded
     let writeFailure: Cause.Cause<never> | undefined
-    const handler = isStream
+    let handler = isStream && !constructionFailed
       ? (streamEffect(client, request, streamOrEffect, (cause) => {
         writeFailure = cause
       }) as Effect.Effect<{} | Deferred.Deferred<any, any>>)
       : (streamOrEffect as Effect.Effect<{} | Deferred.Deferred<any, any>>)
+    if (isDiscard && !constructionFailed) {
+      // the acknowledgement runs inside the middleware, so it is only sent
+      // once the permit is held and the middleware has started the handler
+      handler = Effect.andThen(
+        Effect.suspend(() => {
+          const ack = respond(Exit.void)
+          acknowledged = true
+          return ack
+        }),
+        handler
+      )
+    }
 
     const withMiddleware = rpc.middlewares.size === 0
       ? handler
@@ -314,29 +353,22 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
           deferred = exit.value
           write = Effect.void
         } else {
-          write = options.onFromServer({
-            _tag: "Exit",
-            clientId: client.id,
-            requestId: request.id,
-            exit: exit as any
-          })
+          write = respond(exit)
         }
       } else if (writeFailure) {
         // onFromServer has already answered the client and reported the failure
         return Scope.closeUnsafe(scope, exit) ?? Effect.void
       } else if (
         !disableFatalDefects &&
+        // a notification or a discarded call only ever fails itself
+        !isNotification &&
+        !isDiscard &&
         Cause.hasDies(exit.cause) &&
         !Cause.hasInterrupts(exit.cause)
       ) {
         write = sendDefect(client, Cause.squash(exit.cause))
       } else {
-        write = options.onFromServer({
-          _tag: "Exit",
-          clientId: client.id,
-          requestId: request.id,
-          exit: exit as any
-        })
+        write = respond(exit)
       }
       const close = Scope.closeUnsafe(scope, exit)
       if (exit._tag === "Failure") {
@@ -391,29 +423,24 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
     )
     fiber.addObserver(function onExit(exit: Exit.Exit<any, any>): void {
       if (deferred) {
-        const fiber = trackFiber(runFork(Effect.onExit(Deferred.await(deferred), (exit) =>
-          options.onFromServer({
-            _tag: "Exit",
-            clientId: client.id,
-            requestId: request.id,
-            exit: exit as any
-          }))))
+        const fiber = trackFiber(
+          runFork(
+            Effect.onExit(Deferred.await(deferred), (exit) => {
+              // a failure with no reply to carry it is only reported
+              if (exit._tag === "Failure" && (isNotification || acknowledged)) {
+                reportCauseUnsafe(Fiber.getCurrent()!, exit.cause)
+              }
+              return respond(exit)
+            })
+          )
+        )
         client.fibers.set(request.id, fiber)
         deferred = undefined
         fiber.addObserver(onExit)
         return
       }
-      if (!responded && exit._tag === "Failure") {
-        trackFiber(
-          runFork(
-            options.onFromServer({
-              _tag: "Exit",
-              clientId: client.id,
-              requestId: request.id,
-              exit: Exit.interrupt()
-            })
-          )
-        )
+      if (!responded && !isNotification && !acknowledged && exit._tag === "Failure") {
+        trackFiber(runFork(respond(Exit.interrupt())))
       }
       client.fibers.delete(request.id)
       client.latches?.delete(request.id)
@@ -432,8 +459,11 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
       | Effect.Effect<Queue.Dequeue<any, any>, any, Scope.Scope>,
     onWriteFailure: (cause: Cause.Cause<never>) => void
   ) => {
+    // the chunks of a notification or a discarded call have no reader, so they
+    // are neither sent nor acknowledged
+    const silent = request.isNotification === true || request.discard === true
     const writeChunk = (values: NonEmptyReadonlyArray<any>) =>
-      Effect.onError(
+      silent ? Effect.void : Effect.onError(
         options.onFromServer({ _tag: "Chunk", clientId: client.id, requestId: request.id, values }),
         (cause) => {
           if (!Cause.hasInterruptsOnly(cause)) onWriteFailure(cause)
@@ -441,7 +471,7 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any>(
         }
       )
     let latch: Latch.Latch | undefined
-    if (supportsAck) {
+    if (supportsAck && !silent) {
       client.latches ??= new Map()
       latch = client.latches.get(request.id)
       if (!latch) {
@@ -598,6 +628,23 @@ const applyMiddleware = <A, E, R>(
  * requests, invoking handlers, encoding responses, and managing in-flight
  * request lifetime.
  *
+ * **Details**
+ *
+ * The server consumes `Protocol.disconnects` to interrupt a disconnected
+ * client's requests, so use the `onDisconnect` option to observe disconnects
+ * instead of taking from that queue.
+ *
+ * `onDisconnect` is called for each disconnect reported by the `Protocol`,
+ * after the server has requested interruption of that client's in-flight
+ * requests. It does not wait for those requests to finish. It is not called
+ * when a client ends its input normally, or for clients still connected when
+ * the server stops.
+ *
+ * Each callback runs in its own fiber, so a slow callback does not delay
+ * cleanup for other clients, and callbacks may run concurrently. Pending
+ * callbacks are interrupted when the server stops. Failures are ignored and
+ * logged at `References.UnhandledLogLevel`.
+ *
  * @stability unstable
  * @category running
  * @since 4.0.0
@@ -611,6 +658,7 @@ export const make: <Rpcs extends Rpc.Any>(
       readonly spanAttributes?: Record<string, unknown> | undefined
       readonly concurrency?: number | "unbounded" | undefined
       readonly disableFatalDefects?: boolean | undefined
+      readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
     }
     | undefined
 ) => Effect.Effect<
@@ -628,6 +676,7 @@ export const make: <Rpcs extends Rpc.Any>(
     readonly spanAttributes?: Record<string, unknown> | undefined
     readonly concurrency?: number | "unbounded" | undefined
     readonly disableFatalDefects?: boolean | undefined
+    readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
   }
 ) {
   const {
@@ -687,13 +736,24 @@ export const make: <Rpcs extends Rpc.Any>(
   }).pipe(Scope.provide(scope))
 
   // handle disconnects
+  const onDisconnect = options?.onDisconnect
+  const handleDisconnect = onDisconnect
+    ? (clientId: number) =>
+      Effect.andThen(
+        server.disconnect(clientId),
+        Effect.ignoreCause(Effect.suspend(() => onDisconnect(clientId)), {
+          log: "Unhandled",
+          message: "RpcServer onDisconnect hook failed"
+        }).pipe(Effect.forkIn(scope))
+      )
+    : server.disconnect
   yield* Effect.forkChild(
     Effect.whileLoop({
       while: constTrue,
       body: constant(
         Effect.flatMap(Queue.take(disconnects), (clientId) => {
           clients.delete(clientId)
-          return server.disconnect(clientId)
+          return handleDisconnect(clientId)
         })
       ),
       step: constVoid
@@ -726,6 +786,25 @@ export const make: <Rpcs extends Rpc.Any>(
     return schemas
   }
 
+  // The only successful Exit sent for a discarded call is its acknowledgement,
+  // which carries no value, so its Exits are encoded with a void success.
+  const discardSchemasCache = new WeakMap<any, Schemas>()
+  const getDiscardSchemas = (rpc: Rpc.AnyWithProps, schemas: Schemas) => {
+    let discardSchemas = discardSchemasCache.get(rpc)
+    if (!discardSchemas) {
+      const exitSchema = Rpc.exitSchema(rpc as any)
+      discardSchemas = {
+        ...schemas,
+        encodeExit: Schema.encodeUnknownEffect(
+          codecFor(Schema.Exit(Schema.Void, exitSchema.error, exitSchema.defect)),
+          Context.get(rpc.annotations, Rpc.ParseOptions)
+        ) as any
+      }
+      discardSchemasCache.set(rpc, discardSchemas)
+    }
+    return discardSchemas
+  }
+
   type Client = {
     readonly id: number
     readonly schemas: Map<RequestId, Schemas>
@@ -809,6 +888,13 @@ export const make: <Rpcs extends Rpc.Any>(
         })
     )
 
+  // a notification has no reply to carry the error, so it is only logged
+  const dropNotification = (reason: string) =>
+    Effect.annotateLogs(Effect.logDebug(`Dropped RPC notification: ${reason}`), {
+      module: "RpcServer",
+      method: "dropNotification"
+    })
+
   const writeDecodedRequest = (
     client: Client,
     requestId: RequestId,
@@ -816,15 +902,18 @@ export const make: <Rpcs extends Rpc.Any>(
     request: RequestEncoded,
     payload: unknown
   ) => {
-    client.schemas.set(
-      requestId,
-      supportsTransferables
-        ? {
-          ...schemas,
-          collector: Transferable.makeCollectorUnsafe()
-        }
-        : schemas
-    )
+    // nothing is encoded for a notification, and only a reply would remove its schemas
+    if (request.isNotification !== true) {
+      client.schemas.set(
+        requestId,
+        supportsTransferables
+          ? {
+            ...schemas,
+            collector: Transferable.makeCollectorUnsafe()
+          }
+          : schemas
+      )
+    }
     // the envelope is owned by this protocol loop, so it is decoded in place
     // instead of copied for every request
     const decoded = request as Types.Mutable<RequestEncoded>
@@ -834,6 +923,8 @@ export const make: <Rpcs extends Rpc.Any>(
     return server.write(client.id, decoded as any)
   }
 
+  let notificationCount = 0
+
   // main server loop
   return yield* run((clientId, request) => {
     let client = clients.get(clientId)
@@ -848,35 +939,51 @@ export const make: <Rpcs extends Rpc.Any>(
     switch (request._tag) {
       case "Request": {
         const tag = Object.hasOwn(request, "tag") ? (request.tag as string) : ""
+        const isNotification = request.isNotification === true
         let requestId: RequestId
-        switch (typeof request.id) {
-          case "number":
-          case "string": {
-            requestId = RequestId(request.id)
-            break
-          }
-          default: {
-            return sendDefect(client, `Invalid request id: ${request.id}`)
+        if (isNotification) {
+          // JSON-RPC notifications share an empty id, and no reply ever names one
+          requestId = RequestId(`@effect/rpc/notification/${notificationCount++}`)
+        } else {
+          switch (typeof request.id) {
+            case "number":
+            case "string": {
+              requestId = RequestId(request.id)
+              break
+            }
+            default: {
+              return sendDefect(client, `Invalid request id: ${request.id}`)
+            }
           }
         }
         const rpc = group.requests.get(tag)
         if (!rpc) {
-          return sendRequestDefect(client, requestId, encodeUnknownRequestExit, `Unknown request tag: ${tag}`)
+          const reason = `Unknown request tag: ${tag}`
+          return isNotification
+            ? dropNotification(reason)
+            : sendRequestDefect(client, requestId, encodeUnknownRequestExit, reason)
         }
         const schemas = getSchemas(rpc as any)
+        const replySchemas = !isNotification && request.discard === true
+          ? getDiscardSchemas(rpc as any, schemas)
+          : schemas
         const decoded = schemas.decode(request.payload)
         // The schema decoders evaluate eagerly, so a decode that needs no
         // services is already a resolved success and can skip the effect
         // wrappers.
         if (Exit.isExit(decoded) && Exit.isSuccess(decoded)) {
-          return writeDecodedRequest(client, requestId, schemas, request, decoded.value)
+          return writeDecodedRequest(client, requestId, replySchemas, request, decoded.value)
         }
         return Effect.matchEffect(
           Effect.provideContext(decoded, schemas.context),
           {
-            onFailure: (error) =>
-              sendRequestDefect(client, requestId, schemas.encodeExit, SchemaIssue.defaultFormatter(error.issue)),
-            onSuccess: (payload) => writeDecodedRequest(client, requestId, schemas, request, payload)
+            onFailure: (error) => {
+              const reason = SchemaIssue.defaultFormatter(error.issue)
+              return isNotification
+                ? dropNotification(reason)
+                : sendRequestDefect(client, requestId, replySchemas.encodeExit, reason)
+            },
+            onSuccess: (payload) => writeDecodedRequest(client, requestId, replySchemas, request, payload)
           }
         )
       }
@@ -924,6 +1031,7 @@ export const layer = <Rpcs extends Rpc.Any>(
     readonly spanAttributes?: Record<string, unknown> | undefined
     readonly concurrency?: number | "unbounded" | undefined
     readonly disableFatalDefects?: boolean | undefined
+    readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
   }
 ): Layer.Layer<
   never,
@@ -955,6 +1063,7 @@ export const layerHttp = <Rpcs extends Rpc.Any>(options: {
   readonly spanAttributes?: Record<string, unknown> | undefined
   readonly concurrency?: number | "unbounded" | undefined
   readonly disableFatalDefects?: boolean | undefined
+  readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
   readonly streamBufferSize?: number | "unbounded" | undefined
 }): Layer.Layer<
   never,
@@ -1358,6 +1467,7 @@ export const toHttpEffect: <Rpcs extends Rpc.Any>(
     readonly spanPrefix?: string | undefined
     readonly spanAttributes?: Record<string, unknown> | undefined
     readonly disableFatalDefects?: boolean | undefined
+    readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
     readonly streamBufferSize?: number | "unbounded" | undefined
   } | undefined
 ) => Effect.Effect<
@@ -1375,6 +1485,7 @@ export const toHttpEffect: <Rpcs extends Rpc.Any>(
     readonly spanPrefix?: string | undefined
     readonly spanAttributes?: Record<string, unknown> | undefined
     readonly disableFatalDefects?: boolean | undefined
+    readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
     readonly streamBufferSize?: number | "unbounded" | undefined
   }
 ) {
@@ -1402,6 +1513,7 @@ export const toHttpEffectWebsocket: <Rpcs extends Rpc.Any>(
     readonly spanPrefix?: string | undefined
     readonly spanAttributes?: Record<string, unknown> | undefined
     readonly disableFatalDefects?: boolean | undefined
+    readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
   } | undefined
 ) => Effect.Effect<
   Effect.Effect<HttpServerResponse.HttpServerResponse, never, Scope.Scope | HttpServerRequest.HttpServerRequest>,
@@ -1418,6 +1530,7 @@ export const toHttpEffectWebsocket: <Rpcs extends Rpc.Any>(
     readonly spanPrefix?: string | undefined
     readonly spanAttributes?: Record<string, unknown> | undefined
     readonly disableFatalDefects?: boolean | undefined
+    readonly onDisconnect?: ((clientId: number) => Effect.Effect<void>) | undefined
   }
 ) {
   const { httpEffect, protocol } = yield* makeProtocolWithHttpEffectWebsocket

package/src/rpc/RpcTest.ts

@@ -29,6 +29,7 @@ export const makeClient: <Rpcs extends Rpc.Any, const Flatten extends boolean =
   group: RpcGroup.RpcGroup<Rpcs>,
   options?: {
     readonly flatten?: Flatten | undefined
+    readonly disableFatalDefects?: boolean | undefined
   }
 ) => Effect.Effect<
   Flatten extends true ? RpcClient.RpcClient.Flat<Rpcs> : RpcClient.RpcClient<Rpcs>,
@@ -38,11 +39,13 @@ export const makeClient: <Rpcs extends Rpc.Any, const Flatten extends boolean =
   group: RpcGroup.RpcGroup<Rpcs>,
   options?: {
     readonly flatten?: Flatten | undefined
+    readonly disableFatalDefects?: boolean | undefined
   }
 ) {
   // oxlint-disable-next-line prefer-const
   let client!: Effect.Success<ReturnType<typeof RpcClient.makeNoSerialization<Rpcs, never, Flatten>>>
   const server = yield* RpcServer.makeNoSerialization(group, {
+    disableFatalDefects: options?.disableFatalDefects,
     onFromServer(response) {
       return client.write(response)
     }

package/src/schema/Model.ts

@@ -13,6 +13,7 @@
  * @since 4.0.0
  */
 import type { Brand } from "../Brand.ts"
+import * as SecureRandom from "../crypto/SecureRandom.ts"
 import * as DateTime from "../DateTime.ts"
 import * as Effect from "../Effect.ts"
 import * as Uuid from "../internal/uuid.ts"
@@ -808,7 +809,11 @@ export const Uint8Array: Schema.instanceOf<Uint8Array<ArrayBuffer>> = Schema.Uin
 export const UuidV4BytesWithGenerate = <B extends string>(
   schema: Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>
 ): Schema.withConstructorDefault<Schema.brand<Schema.instanceOf<Uint8Array<ArrayBuffer>>, B>> =>
-  schema.pipe(Schema.withConstructorDefault(Effect.sync(() => Uuid.v4Bytes())))
+  schema.pipe(
+    Schema.withConstructorDefault(
+      Effect.sync(() => Uuid.v4Bytes(SecureRandom.randomBytesUnsafe(16) as Uint8Array<ArrayBuffer>))
+    )
+  )
 
 /**
  * A field that represents a binary UUID v4 that is generated on inserts.
@@ -854,7 +859,7 @@ export interface UuidV4Insert<B extends string> extends
 export const UuidV4WithGenerate = <B extends string>(
   schema: Schema.brand<Schema.String, B>
 ): Schema.withConstructorDefault<Schema.brand<Schema.String, B>> =>
-  schema.pipe(Schema.withConstructorDefault(Effect.sync(Uuid.v4String)))
+  schema.pipe(Schema.withConstructorDefault(Effect.sync(() => Uuid.v4String(SecureRandom.randomBytesUnsafe(16)))))
 
 /**
  * A field that represents a string UUID v4 that is generated on inserts.
@@ -893,6 +898,20 @@ export interface UuidV7Insert<B extends string> extends
 /**
  * Adds a constructor default that generates a string UUID v7.
  *
+ * **Details**
+ *
+ * The UUID takes its timestamp from the `Clock`, and shares its ordering with
+ * `SecureRandom.uuidV7Unsafe` and every other `Model.UuidV7WithGenerate` in the
+ * JS realm, so below the maximum timestamp each UUID sorts after the previous
+ * one.
+ *
+ * **Gotchas**
+ *
+ * The shared ordering never moves the timestamp back, so a `Clock` behind the
+ * realm's latest timestamp, such as a `TestClock` after `Date.now()`-based
+ * UUIDs were generated, produces UUIDs with that latest timestamp rather than
+ * the `Clock` time.
+ *
  * @stability unstable
  * @category schemas
  * @since 4.0.0
@@ -902,7 +921,11 @@ export const UuidV7WithGenerate = <B extends string>(
 ): Schema.withConstructorDefault<Schema.brand<Schema.String, B>> =>
   schema.pipe(
     Schema.withConstructorDefault(
-      Effect.clockWith((clock) => Effect.succeed(Uuid.v7String(clock.currentTimeMillisUnsafe())))
+      Effect.clockWith((clock) =>
+        Effect.succeed(
+          Uuid.stringify(Uuid.v7Monotonic(clock.currentTimeMillisUnsafe(), SecureRandom.randomBytesUnsafe(16)))
+        )
+      )
     )
   )
 

package/src/sql/Migrator.ts

@@ -12,11 +12,9 @@
 import * as Arr from "../Array.ts"
 import * as Data from "../Data.ts"
 import * as Effect from "../Effect.ts"
-import { FileSystem } from "../FileSystem.ts"
 import { pipe } from "../Function.ts"
 import * as Option from "../Option.ts"
 import * as Order from "../Order.ts"
-import { Path } from "../Path.ts"
 import * as Client from "./SqlClient.ts"
 import type { SqlError } from "./SqlError.ts"
 
@@ -98,7 +96,8 @@ export class MigrationError extends Data.TaggedError("MigrationError")<{
 /**
  * Creates a migrator that ensures the migrations table exists, runs pending
  * migrations in a transaction, and optionally dumps the schema after successful
- * migrations.
+ * migrations. ClickHouse runs without a transaction and records each migration
+ * only after it succeeds.
  *
  * @stability unstable
  * @category constructors
@@ -173,11 +172,11 @@ ORDER BY migration_id`,
     })
 
     const insertMigrations = (
-      rows: ReadonlyArray<[id: number, name: string]>
+      rows: Arr.NonEmptyReadonlyArray<[id: number, name: string]>
     ) =>
       sql`INSERT INTO ${sql(table)} ${
         sql.insert(
-          rows.map(([migration_id, name]) => ({ migration_id, name }))
+          Arr.map(rows, ([migration_id, name]) => ({ migration_id, name }))
         )
       }`.withoutTransform
 
@@ -240,6 +239,12 @@ ORDER BY migration_id`,
 
     // === run
 
+    // BEGIN is still experimental on clickhouse
+    const transactional = sql.onDialectOrElse({
+      clickhouse: () => false,
+      orElse: () => true
+    })
+
     const run = Effect.gen(function*() {
       yield* sql.onDialectOrElse({
         pg: () => sql`LOCK TABLE ${sql(table)} IN ACCESS EXCLUSIVE MODE`,
@@ -279,9 +284,10 @@ ORDER BY migration_id`,
         ])
       }
 
-      if (required.length > 0) {
+      // rows recorded up front are only rolled back inside a transaction
+      if (transactional && Arr.isArrayNonEmpty(required)) {
         yield* pipe(
-          insertMigrations(required.map(([id, name]) => [id, name])),
+          insertMigrations(Arr.map(required, ([id, name]) => [id, name])),
           Effect.mapError((error): MigrationError | SqlError =>
             isConstraintConflict(error)
               ? new MigrationError({
@@ -298,6 +304,7 @@ ORDER BY migration_id`,
         ([id, name, effect]) =>
           Effect.logDebug(`Running migration`).pipe(
             Effect.flatMap(() => runMigration(id, name, effect)),
+            Effect.andThen(transactional ? Effect.void : insertMigrations([[id, name]])),
             Effect.annotateLogs("migration_id", String(id)),
             Effect.annotateLogs("migration_name", name),
             Effect.withSpan(`Migrator ${id}_${name}`)
@@ -325,11 +332,7 @@ ORDER BY migration_id`,
     yield* ensureMigrationsTable
 
     const completed = yield* pipe(
-      sql.onDialectOrElse({
-        // BEGIN is still experimental on clickhouse
-        clickhouse: () => run,
-        orElse: () => sql.withTransaction(run)
-      }),
+      transactional ? sql.withTransaction(run) : run,
       Effect.catchTag("MigrationError", (_) =>
         _.kind === "Locked"
           ? Effect.as(Effect.logDebug(_.message), [])
@@ -431,60 +434,3 @@ export const fromRecord = (migrations: Record<string, Effect.Effect<void, unknow
     Arr.sort(migrationOrder),
     Effect.succeed
   )
-
-/**
- * Creates a migration loader that reads a directory with `FileSystem`, imports
- * files named `<id>_<name>.js`, `<id>_<name>.ts`,
- * `<id>_<name>.mjs`, or `<id>_<name>.mts`, and sorts migrations by id.
- *
- * **Details**
- *
- * Requires a `Path` service appropriate for the migration directory's path
- * syntax. On Windows, prefer a platform-aware implementation such as
- * `NodePath.layer`; the core `Path.layer` uses POSIX semantics and does not
- * preserve Windows drive-letter paths.
- *
- * @stability unstable
- * @category loaders
- * @since 4.0.0
- */
-export const fromFileSystem: (directory: string) => Loader<FileSystem | Path> = Effect.fnUntraced(function*(directory) {
-  const Fs = yield* FileSystem
-  const path = yield* Path
-  const files = yield* Effect.mapError(
-    Fs.readDirectory(directory),
-    (cause) =>
-      new MigrationError({
-        kind: "Failed",
-        cause,
-        message: "Failed to read migrations directory"
-      })
-  )
-  return files
-    .map((file) => Option.fromNullishOr(file.match(/^(?:.*\/)?(\d+)_([^.]+)\.(js|ts|mjs|mts)$/)))
-    .flatMap(
-      Option.match({
-        onNone: () => [],
-        onSome: ([basename, id, name]): ReadonlyArray<ResolvedMigration> =>
-          [
-            [
-              Number(id),
-              name,
-              // `import` needs a file URL: on Windows an absolute path such as
-              // `D:\migrations\1_init.ts` is rejected by the ESM loader. `orDie` keeps the
-              // failure a defect so `loadMigration` reports it as an import error.
-              Effect.flatMap(Effect.orDie(path.toFileUrl(path.join(directory, basename))), (url) =>
-                Effect.promise(
-                  () =>
-                    import(
-                      /* @vite-ignore */
-                      /* webpackIgnore: true */
-                      url.href
-                    )
-                ))
-            ]
-          ] as const
-      })
-    )
-    .sort(([a], [b]) => a - b);
-})