effect 4.1.1 → 4.1.2

package/src/encoding/SchemaBinary.ts

@@ -972,6 +972,139 @@ export function fieldId(id: number) {
 
 const FIELD_ID_ANNOTATION_KEY = "~effect/encoding/SchemaBinary/fieldId"
 
+// Marks the check that opts a number or bigint into a fixed-width encoding.
+// It lives on a check, not the AST, so later annotations and checks keep it.
+const FIXED_WIDTH_ANNOTATION_KEY = "~effect/encoding/SchemaBinary/fixedWidth"
+
+type FixedWidthKind = "i32" | "u32" | "i64" | "u64"
+
+const BIGINT_I64_MIN = BigInt("-9223372036854775808")
+const BIGINT_I64_MAX = BigInt("9223372036854775807")
+const BIGINT_U64_MAX = BigInt("18446744073709551615")
+
+/**
+ * A 32-bit signed integer written as four little-endian bytes.
+ *
+ * **When to use**
+ *
+ * Use when values regularly need more than four bytes as a varint, such as
+ * hashes or full-range ids. Small values are cheaper as `Schema.Int`.
+ *
+ * **Details**
+ *
+ * Rejects non-integers and values outside -2147483648 through 2147483647
+ * instead of truncating them. `-0` is written as `0`.
+ *
+ * **Gotchas**
+ *
+ * Switching a field between this, {@link uint32}, `Schema.Number` or
+ * `Schema.Int` changes its encoding, so it is not a compatible evolution. In
+ * default mode the other reader can decode a different value without an error,
+ * for example after a signedness swap or inside an array of structs.
+ * Fingerprint mode rejects the layout mismatch.
+ *
+ * **Example** (Declaring fixed-width integer fields)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { SchemaBinary } from "effect/encoding"
+ *
+ * const Packet = Schema.Struct({
+ *   version: SchemaBinary.uint32,
+ *   offset: SchemaBinary.int32,
+ *   sequence: SchemaBinary.uint64,
+ *   timestamp: SchemaBinary.int64
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const int32: Schema.Number = Schema.Number.check(
+  Schema.isInt32({ [FIXED_WIDTH_ANNOTATION_KEY]: "i32" })
+)
+
+/**
+ * A 32-bit unsigned integer written as four little-endian bytes.
+ *
+ * **Details**
+ *
+ * Rejects non-integers and values outside 0 through 4294967295 instead of
+ * wrapping them. See {@link int32} for when a fixed width pays off.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const uint32: Schema.Number = Schema.Number.check(
+  Schema.isUint32({ [FIXED_WIDTH_ANNOTATION_KEY]: "u32" })
+)
+
+/**
+ * A 64-bit signed integer, as a `bigint`, written as eight little-endian bytes.
+ *
+ * **Details**
+ *
+ * Rejects values outside -2^63 through 2^63 - 1 instead of wrapping them. As a
+ * struct field it costs one length byte more than the payload, because the
+ * eight-byte field kind belongs to floating-point numbers.
+ *
+ * **Gotchas**
+ *
+ * Switching a field between this, {@link uint64} or `Schema.BigInt` is not a
+ * compatible evolution. All three are length-prefixed struct fields, and eight
+ * bytes can be valid for each, so a default-mode reader may decode the other
+ * form as a different value without an error. Fingerprint mode rejects the
+ * layout mismatch.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const int64: Schema.BigInt = Schema.BigInt.check(
+  Schema.isBetweenBigInt({ minimum: BIGINT_I64_MIN, maximum: BIGINT_I64_MAX }, {
+    expected: "a 64-bit integer",
+    [FIXED_WIDTH_ANNOTATION_KEY]: "i64"
+  })
+)
+
+/**
+ * A 64-bit unsigned integer, as a `bigint`, written as eight little-endian
+ * bytes.
+ *
+ * **Details**
+ *
+ * Rejects values outside 0 through 2^64 - 1 instead of wrapping them. See
+ * {@link int64} for the struct field cost.
+ *
+ * **Gotchas**
+ *
+ * Switching a field between this, {@link int64} or `Schema.BigInt` can decode
+ * as a different value without an error in default mode; see {@link int64}.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const uint64: Schema.BigInt = Schema.BigInt.check(
+  Schema.isBetweenBigInt({ minimum: BigInt(0), maximum: BIGINT_U64_MAX }, {
+    expected: "a 64-bit unsigned integer",
+    [FIXED_WIDTH_ANNOTATION_KEY]: "u64"
+  })
+)
+
+// The fixed width the schema opted into, from any of its checks.
+function fixedWidthKind(ast: SchemaAST.AST): FixedWidthKind | undefined {
+  const checks = ast.checks
+  if (checks === undefined) return undefined
+  for (const check of checks) {
+    const kind = check.annotations?.[FIXED_WIDTH_ANNOTATION_KEY]
+    if (kind !== undefined) return kind as FixedWidthKind
+  }
+  return undefined
+}
+
 // Bit 0 selects fingerprint mode; all other flag bits are reserved.
 const ENVELOPE = 0x20 // version nibble 2, flags 0
 const ENVELOPE_FINGERPRINT = 0x21 // version nibble 2, flag bit 0
@@ -1370,6 +1503,11 @@ class Writer {
     this.view.setBigInt64(this.start + this.len, n, true)
     this.len += 8
   }
+  u64(n: bigint) {
+    this.ensure(8)
+    this.view.setBigUint64(this.start + this.len, n, true)
+    this.len += 8
+  }
   u32le(n: number) {
     this.ensure(4)
     this.view.setUint32(this.start + this.len, n >>> 0, true)
@@ -1801,6 +1939,12 @@ class Reader {
     this.pos += 8
     return value
   }
+  u64(): bigint {
+    if (this.pos + 8 > this.end) invalid("complete value", undefined, this.options)
+    const value = (this.view ?? this.dataView()).getBigUint64(this.pos, true)
+    this.pos += 8
+    return value
+  }
   u32le(): number {
     if (this.pos + 4 > this.end) invalid("complete value", undefined, this.options)
     const value = (this.view ?? this.dataView()).getUint32(this.pos, true)
@@ -1825,6 +1969,7 @@ type LeafKind =
   | "symbol"
   | "bytes"
   | "bigint"
+  | FixedWidthKind
   | "json"
   | "duration"
   | "bigDecimal"
@@ -2007,7 +2152,12 @@ function packedSize(layout: Layout): number | undefined {
       return packedSize(layout.leaf)
     case "bool":
       return 1
+    case "i32":
+    case "u32":
+      return 4
     case "int64":
+    case "i64":
+    case "u64":
       return 8
     default:
       return undefined
@@ -2318,10 +2468,15 @@ function compileLayout(root: SchemaAST.AST): CompiledLayout {
       case "Undefined":
       case "Void":
         return leaf("undefined")
-      case "Number":
+      case "Number": {
+        const fixed = fixedWidthKind(ast)
+        if (fixed === "i32" || fixed === "u32") return leaf(fixed)
         return leaf(provesInteger(ast) ? "int" : "number")
-      case "BigInt":
-        return leaf("bigint")
+      }
+      case "BigInt": {
+        const fixed = fixedWidthKind(ast)
+        return leaf(fixed === "i64" || fixed === "u64" ? fixed : "bigint")
+      }
       case "Literal":
         return literalLayout(leaf(literalKind(ast.literal)), [ast.literal])
       case "Unknown":
@@ -2685,7 +2840,7 @@ function isExact(root: SchemaAST.AST): boolean {
   const walked = new Map<SchemaAST.AST, boolean>()
   const exact = (ast: SchemaAST.AST): boolean => {
     if (
-      ast.encoding !== undefined || ast.checks !== undefined ||
+      ast.encoding !== undefined || (ast.checks !== undefined && !isFixedWidthOnly(ast)) ||
       (ast as { readonly encodingChecks?: SchemaAST.Checks }).encodingChecks !== undefined
     ) {
       return false
@@ -2746,6 +2901,13 @@ function isExact(root: SchemaAST.AST): boolean {
   return exact(root)
 }
 
+// The binary layer enforces a fixed-width check on its own, so it is exact
+// when no other check rides along.
+function isFixedWidthOnly(ast: SchemaAST.AST): boolean {
+  return (ast._tag === "Number" || ast._tag === "BigInt") && ast.checks?.length === 1 &&
+    fixedWidthKind(ast) !== undefined
+}
+
 // A clean Exit whose success schema is exact: the binary layer fully produces
 // and validates success exits, so only failure exits need the schema pass for
 // their cause's error and defect encodings.
@@ -2784,7 +2946,11 @@ const F = {
   exit: 22,
   cause: 23,
   causeReason: 24,
-  literal: 25
+  literal: 25,
+  i32: 26,
+  u32: 27,
+  i64: 28,
+  u64: 29
 } as const
 
 // Hash the compiled layout graph, including cycle back-edge distances.
@@ -2828,6 +2994,10 @@ function layoutFingerprint(root: Layout): bigint {
       case "symbol":
       case "bytes":
       case "bigint":
+      case "i32":
+      case "u32":
+      case "i64":
+      case "u64":
       case "json":
       case "duration":
       case "bigDecimal":
@@ -2986,12 +3156,16 @@ function matchesLayout(layout: Layout, value: unknown): boolean {
       return value === undefined
     case "number":
     case "int":
+    case "i32":
+    case "u32":
       return typeof value === "number"
     case "string":
       return typeof value === "string"
     case "symbol":
       return typeof value === "symbol"
     case "bigint":
+    case "i64":
+    case "u64":
       return typeof value === "bigint"
     case "bytes":
       return value instanceof Uint8Array
@@ -3287,6 +3461,10 @@ function valueWireCode(layout: Layout, value: unknown, options: SchemaAST.ParseO
     case "int":
       if (!Number.isSafeInteger(value)) encodeFail("an integer", value, options)
       return FIELD_WIRE_VARINT
+    // The payload write validates the value.
+    case "i32":
+    case "u32":
+      return FIELD_WIRE_FIXED32
     default:
       return FIELD_WIRE_SIZED
   }
@@ -3295,8 +3473,8 @@ function valueWireCode(layout: Layout, value: unknown, options: SchemaAST.ParseO
 function encodeWirePayload(ctx: EncodeContext, layout: Layout, value: unknown, wire: number, w: Writer) {
   const kind = wire % FIELD_WIRE_FACTOR
   switch (kind) {
-    // EMPTY and FIXED32 are decoder-side skip support only; `valueWireCode`
-    // never produces them.
+    // EMPTY is decoder-side skip support only; `valueWireCode` never produces
+    // it.
     case FIELD_WIRE_FALSE:
     case FIELD_WIRE_TRUE:
       return
@@ -3306,6 +3484,9 @@ function encodeWirePayload(ctx: EncodeContext, layout: Layout, value: unknown, w
     case FIELD_WIRE_FIXED64:
       w.f64(value as number)
       return
+    case FIELD_WIRE_FIXED32:
+      encodeValue(ctx, layout, value, w)
+      return
     case FIELD_WIRE_DECIMAL: {
       const scale = Math.floor(wire / FIELD_WIRE_FACTOR)
       w.numberVarint(Math.round((value as number) * POW10[scale]))
@@ -4010,6 +4191,29 @@ function encodeValue(ctx: EncodeContext, layout: Layout, value: unknown, w: Writ
       if (typeof value !== "bigint") encodeFail("a bigint", value, ctx.options)
       w.zigzag(value)
       return
+    // `disableChecks` can bypass the range check used to select these layouts.
+    case "i32":
+      if (typeof value !== "number" || (value | 0) !== value) encodeFail("a 32-bit integer", value, ctx.options)
+      w.i32le(value)
+      return
+    case "u32":
+      if (typeof value !== "number" || value >>> 0 !== value) {
+        encodeFail("a 32-bit unsigned integer", value, ctx.options)
+      }
+      w.u32le(value)
+      return
+    case "i64":
+      if (typeof value !== "bigint" || value < BIGINT_I64_MIN || value > BIGINT_I64_MAX) {
+        encodeFail("a 64-bit integer", value, ctx.options)
+      }
+      w.i64(value)
+      return
+    case "u64":
+      if (typeof value !== "bigint" || value < BIGINT_ZERO || value > BIGINT_U64_MAX) {
+        encodeFail("a 64-bit unsigned integer", value, ctx.options)
+      }
+      w.u64(value)
+      return
     case "int64": {
       if (!matchesLayout(layout, value)) {
         encodeFail(layout.flavor === "date" ? "a Date" : "a DateTime.Utc", value, ctx.options)
@@ -4375,6 +4579,9 @@ function fieldWireMask(layout: Layout): number {
       return (1 << FIELD_WIRE_VARINT) | (1 << FIELD_WIRE_FIXED64) | (1 << FIELD_WIRE_DECIMAL)
     case "int":
       return 1 << FIELD_WIRE_VARINT
+    case "i32":
+    case "u32":
+      return 1 << FIELD_WIRE_FIXED32
     default:
       return 1 << FIELD_WIRE_SIZED
   }
@@ -4406,6 +4613,8 @@ function decodeFieldPayload(layout: Layout, wireMask: number, kind: number, r: R
     skipFieldPayload(kind, r)
     return ABSENT
   }
+  // Only the two 32-bit layouts accept this kind, so the payload needs no window.
+  if (kind === FIELD_WIRE_FIXED32) return layout._ === "u32" ? r.u32le() : r.i32le()
   if (kind !== FIELD_WIRE_SIZED) {
     const value = decodeScalarField(kind, r)
     if (layout._ === "literal" && !hasLiteral(layout, value)) {
@@ -4993,6 +5202,18 @@ function decodeValueUnchecked(layout: Layout, r: Reader): unknown {
       return r.takeCopy(r.end - r.pos)
     case "bigint":
       return r.zigzag()
+    case "i32":
+      if (r.remaining !== 4) invalid("a 32-bit integer", undefined, r.options)
+      return r.i32le()
+    case "u32":
+      if (r.remaining !== 4) invalid("a 32-bit unsigned integer", undefined, r.options)
+      return r.u32le()
+    case "i64":
+      if (r.remaining !== 8) invalid("a 64-bit integer", undefined, r.options)
+      return r.i64()
+    case "u64":
+      if (r.remaining !== 8) invalid("a 64-bit unsigned integer", undefined, r.options)
+      return r.u64()
     case "int64": {
       if (r.remaining !== 8) invalid("int64", undefined, r.options)
       const millis = Number(r.i64())

package/src/encoding/index.ts

@@ -41,12 +41,24 @@ export * as Hex from "./Hex.ts"
  */
 export * as Ini from "./Ini.ts"
 
+/**
+ * @stability unstable
+ * @since 4.1.2
+ */
+export * as Json5 from "./Json5.ts"
+
 /**
  * @stability unstable
  * @since 4.0.6
  */
 export * as JsonArray from "./JsonArray.ts"
 
+/**
+ * @stability unstable
+ * @since 4.1.2
+ */
+export * as Jsonc from "./Jsonc.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/eventlog/EventLogServer.ts

@@ -12,6 +12,7 @@
 import type { NonEmptyReadonlyArray } from "../Array.ts"
 import * as Arr from "../Array.ts"
 import * as Cache from "../Cache.ts"
+import * as Clock from "../Clock.ts"
 import * as Context from "../Context.ts"
 import * as Mac from "../crypto/Mac.ts"
 import * as Data from "../Data.ts"
@@ -22,7 +23,6 @@ import * as Exit from "../Exit.ts"
 import * as Hash from "../Hash.ts"
 import * as Uuid from "../internal/uuid.ts"
 import * as Layer from "../Layer.ts"
-import * as Option from "../Option.ts"
 import * as Redacted from "../Redacted.ts"
 import type * as Rpc from "../rpc/Rpc.ts"
 import type * as RpcGroup from "../rpc/RpcGroup.ts"
@@ -119,11 +119,6 @@ export const layerRpcHandlers = (options: {
   Rpc.ToHandler<RpcGroup.Rpcs<typeof EventLogRemoteRpcs>> | EventLogAuthentication
 > =>
   EventLogRemoteRpcs.toLayer(Effect.gen(function*() {
-    const clientChallenges = yield* Cache.make({
-      lookup: (_clientId: number) => Effect.orDie(EventLogSessionAuth.makeSessionAuthChallenge),
-      capacity: Number.MAX_SAFE_INTEGER,
-      timeToLive: EventLogSessionAuth.SessionAuthChallengeTimeToLiveMillis
-    })
     const toFrames = makeFramer()
 
     const persistedSigningPublicKeys = yield* Cache.makeWith(
@@ -148,17 +143,31 @@ export const layerRpcHandlers = (options: {
 
     return EventLogRemoteRpcs.of({
       "EventLog.Hello": Effect.fnUntraced(function*(_, { client }) {
-        const challenge = yield* Cache.get(clientChallenges, client.id)
+        // Kept on the connection, so it is released when the client disconnects
+        // and shared by overlapping Hellos until `Authenticate` consumes it.
+        let pending = getPendingChallenge(client, yield* Clock.currentTimeMillis)
+        if (pending === undefined) {
+          const challenge = yield* Effect.orDie(EventLogSessionAuth.makeSessionAuthChallenge)
+          // Read the clock again, as generating the challenge can suspend. A
+          // concurrent Hello may have stored a challenge in the meantime.
+          const now = yield* Clock.currentTimeMillis
+          pending = getPendingChallenge(client, now) ?? {
+            challenge,
+            expiresAt: now + EventLogSessionAuth.SessionAuthChallengeTimeToLiveMillis
+          }
+          client.annotate(PendingChallenge, pending)
+        }
         return new HelloResponse({
           remoteId: options.remoteId,
-          challenge,
+          challenge: pending.challenge,
           firstSequence: options.firstSequence,
           compaction: options.compaction === true ? true : undefined
         })
       }),
       "EventLog.Authenticate": Effect.fnUntraced(function*(request, { client }) {
-        const challenge = Option.getOrNull(yield* Cache.getOption(clientChallenges, client.id))
-        if (!challenge) {
+        const pending = getPendingChallenge(client, yield* Clock.currentTimeMillis)
+        client.annotate(PendingChallenge, undefined)
+        if (pending === undefined) {
           return yield* new EventLogProtocolError({
             requestTag: "Authenticate",
             publicKey: request.publicKey,
@@ -166,13 +175,12 @@ export const layerRpcHandlers = (options: {
             message: "Session auth challenge has expired"
           })
         }
-        yield* Cache.invalidate(clientChallenges, client.id)
         if (options.authorizeIdentity) {
           yield* options.authorizeIdentity(request.publicKey, request.signingPublicKey)
         }
         const verified = yield* EventLogSessionAuth.verifySessionAuthenticateRequest({
           remoteId: options.remoteId,
-          challenge,
+          challenge: pending.challenge,
           publicKey: request.publicKey,
           signingPublicKey: request.signingPublicKey,
           signature: request.signature,
@@ -409,6 +417,22 @@ class ConnectionWritesState extends Context.Service<ConnectionWritesState, Conne
   "effect/eventlog/EventLogServer/ConnectionWrites"
 ) {}
 
+// The connection's unconsumed `Hello` challenge, cleared by `Authenticate`.
+const PendingChallenge = Context.Reference<
+  | {
+    readonly challenge: Uint8Array<ArrayBuffer>
+    readonly expiresAt: number
+  }
+  | undefined
+>("effect/eventlog/EventLogServer/PendingChallenge", {
+  defaultValue: () => undefined
+})
+
+const getPendingChallenge = (client: Rpc.ServerClient, now: number) => {
+  const pending = Context.get(client.annotations, PendingChallenge)
+  return pending !== undefined && pending.expiresAt > now ? pending : undefined
+}
+
 const getConnectionWrites = (client: Rpc.ServerClient): ConnectionWrites => {
   const existing = Context.getOrUndefined(client.annotations, ConnectionWritesState)
   if (existing !== undefined) return existing

package/src/http/HttpClient.ts

@@ -2666,9 +2666,11 @@ export const tapRequest: {
  * **Details**
  *
  * Response cookies are merged into the ref with `Cookies.mergeIntoArray` for
- * the response URL. Before each request, `Cookies.toRequestCookieHeader` selects
- * the cookies for the request URL and sets them as the `cookie` header. Expiry
- * uses the current `Clock`.
+ * the response URL. When a request is sent, `Cookies.toRequestCookieHeader`
+ * selects the cookies for its final URL, after later transformations such as
+ * `HttpClientRequest.prependUrl`, and sets them as the `cookie` header. With
+ * `followRedirects` applied after `withCookiesRef`, this runs for every hop.
+ * Expiry uses the current `Clock`.
  *
  * @stability unstable
  * @category cookies
@@ -2687,9 +2689,11 @@ export const withCookiesRef: {
    * **Details**
    *
    * Response cookies are merged into the ref with `Cookies.mergeIntoArray` for
-   * the response URL. Before each request, `Cookies.toRequestCookieHeader` selects
-   * the cookies for the request URL and sets them as the `cookie` header. Expiry
-   * uses the current `Clock`.
+   * the response URL. When a request is sent, `Cookies.toRequestCookieHeader`
+   * selects the cookies for its final URL, after later transformations such as
+   * `HttpClientRequest.prependUrl`, and sets them as the `cookie` header. With
+   * `followRedirects` applied after `withCookiesRef`, this runs for every hop.
+   * Expiry uses the current `Clock`.
    *
    * @stability unstable
    * @category cookies
@@ -2708,9 +2712,11 @@ export const withCookiesRef: {
    * **Details**
    *
    * Response cookies are merged into the ref with `Cookies.mergeIntoArray` for
-   * the response URL. Before each request, `Cookies.toRequestCookieHeader` selects
-   * the cookies for the request URL and sets them as the `cookie` header. Expiry
-   * uses the current `Clock`.
+   * the response URL. When a request is sent, `Cookies.toRequestCookieHeader`
+   * selects the cookies for its final URL, after later transformations such as
+   * `HttpClientRequest.prependUrl`, and sets them as the `cookie` header. With
+   * `followRedirects` applied after `withCookiesRef`, this runs for every hop.
+   * Expiry uses the current `Clock`.
    *
    * @stability unstable
    * @category cookies
@@ -2722,21 +2728,27 @@ export const withCookiesRef: {
   <E, R>(
     self: HttpClient.With<E, R>,
     ref: Ref.Ref<ReadonlyArray<Cookies.Cookie>>
-  ): HttpClient.With<E, R> =>
-    makeWith(
+  ): HttpClient.With<E, R> => {
+    const now = () => Fiber.getCurrent()!.getRef(Clock).currentTimeMillisUnsafe()
+    const addCookies = (request: HttpClientRequest.HttpClientRequest) =>
+      Effect.map(Ref.get(ref), (cookies) => {
+        const header = Cookies.toRequestCookieHeader(cookies, request.url, now())
+        if (header === undefined) return request
+        const withCookies = HttpClientRequest.setHeader(request, "cookie", header)
+        // setHeader returns a new request, so carry over the withScope controller
+        const controller = scopedRequests.get(request)
+        if (controller !== undefined) scopedRequests.set(withCookies, controller)
+        return withCookies
+      })
+    return makeWith(
       (request: Effect.Effect<HttpClientRequest.HttpClientRequest, E, R>) =>
-        Effect.tap(self.postprocess(request), (response) => {
-          const now = Fiber.getCurrent()!.getRef(Clock).currentTimeMillisUnsafe()
-          return Ref.update(ref, Cookies.mergeIntoArray(response.url, response.cookies, now))
-        }),
-      (request) =>
-        Effect.flatMap(self.preprocess(request), (request) =>
-          Effect.map(Ref.get(ref), (cookies) => {
-            const now = Fiber.getCurrent()!.getRef(Clock).currentTimeMillisUnsafe()
-            const header = Cookies.toRequestCookieHeader(cookies, request.url, now)
-            return header === undefined ? request : HttpClientRequest.setHeader(request, "cookie", header)
-          }))
+        Effect.tap(
+          self.postprocess(Effect.flatMap(request, addCookies)),
+          (response) => Ref.update(ref, Cookies.mergeIntoArray(response.url, response.cookies, now()))
+        ),
+      self.preprocess
     )
+  }
 )
 
 /**

package/src/internal/dateTime.ts

@@ -1054,6 +1054,29 @@ export const subtract: {
   return add(self, newParts)
 })
 
+const mutateRounding = (
+  self: DateTime.DateTime,
+  part: DateTime.DateTime.UnitSingular,
+  f: (date: Date) => void,
+  disambiguation: DateTime.Disambiguation = "compatible"
+): DateTime.DateTime => {
+  if (
+    self._tag === "Utc" || self.zone._tag === "Offset" ||
+    part === "day" || part === "week" || part === "month" || part === "year"
+  ) {
+    return mutate(self, f, { disambiguation })
+  }
+  // keep the input's offset so rounding stays in the same occurrence of a repeated hour
+  const date = toDate(self)
+  const offset = date.getTime() - Math.trunc(self.epochMilliseconds)
+  f(date)
+  const adjustedMillis = date.getTime()
+  const result = makeZonedProto(adjustedMillis - offset, self.zone)
+  return zonedOffset(result) === offset
+    ? result
+    : makeZonedFromAdjusted(adjustedMillis, self.zone, disambiguation)
+}
+
 const startOfDate = (date: Date, part: DateTime.DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
 }) => {
@@ -1105,7 +1128,7 @@ export const startOf: {
   }): A
 } = dual(isDateTimeArgs, (self: DateTime.DateTime, part: DateTime.DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-}): DateTime.DateTime => mutate(self, (date) => startOfDate(date, part, options)))
+}): DateTime.DateTime => mutateRounding(self, part, (date) => startOfDate(date, part, options)))
 
 const endOfDate = (date: Date, part: DateTime.DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
@@ -1158,7 +1181,7 @@ export const endOf: {
   }): A
 } = dual(isDateTimeArgs, (self: DateTime.DateTime, part: DateTime.DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
-}): DateTime.DateTime => mutate(self, (date) => endOfDate(date, part, options)))
+}): DateTime.DateTime => mutateRounding(self, part, (date) => endOfDate(date, part, options), "later"))
 
 /** @internal */
 export const nearest: {
@@ -1171,7 +1194,7 @@ export const nearest: {
 } = dual(isDateTimeArgs, (self: DateTime.DateTime, part: DateTime.DateTime.UnitSingular, options?: {
   readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
 }): DateTime.DateTime =>
-  mutate(self, (date) => {
+  mutateRounding(self, part, (date) => {
     if (part === "millisecond") return
     const millis = date.getTime()
     const start = new Date(millis)