effect-app 4.0.0-beta.211 → 4.0.0-beta.213

package/src/Schema/ext.ts

@@ -1,5 +1,35 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
+/**
+ * # `withConstructorDefault` policy
+ *
+ * The `withConstructorDefault` properties exported throughout this module
+ * (and from `numbers.ts`, `moreStrings.ts`, `ids.ts`) attach a default value
+ * that is **only** applied during construction — i.e. when the field is
+ * omitted from the input to a Schema constructor / `.make(...)` call.
+ *
+ * They are **NOT** applied during `decode` (JSON, database rows, RPC payloads,
+ * etc.). Decoding a payload with a missing field will still fail with a parse
+ * error, exactly as if the default were not present.
+ *
+ * Concretely this means `withConstructorDefault` MUST NOT be relied on as a
+ * just-in-time migration mechanism for database fields. If a stored record is
+ * missing a newly added field, the constructor default will not fill it in on
+ * read — decoding will fail.
+ *
+ * ## Don't reach for `withDecodingDefault*` either
+ *
+ * The sibling `withDecodingDefaultType` (and `withDecodingDefault`) extensions
+ * exist, but they are discouraged for migrating persisted data. A missing
+ * field in a stored record is just as likely to be data corruption as it is
+ * an old-shape document; silently substituting a default hides the problem
+ * and can poison downstream aggregates.
+ *
+ * Prefer an **explicit, preferably versioned** migration of database data
+ * (a schema-version field, a one-shot backfill, or a transform on read that
+ * is gated on an explicit version marker) over shoving missing fields under
+ * the rug with a decode-time default.
+ */
 import { Config, Effect, Function, Option, pipe, type SchemaAST, SchemaIssue, SchemaTransformation } from "effect"
 import * as S from "effect/Schema"
 import { isDateValid } from "effect/Schema"
@@ -75,78 +105,163 @@ export interface DateFromString extends S.decodeTo<S.Date, S.String> {}
  */
 export const DateFromString: DateFromString = DateString.pipe(S.decodeTo(S.Date, SchemaTransformation.dateFromString))
 
-/**
- * Like the default Schema `Date` but from String with `withDefault` => now
- */
+/** Like the default Schema `Date` but from String, with default helpers. */
 export const Date = Object.assign(DateFromString, {
-  withDefault: DateFromString.pipe(S.withConstructorDefault(Effect.sync(() => new global.Date()))),
+  /**
+   * Construction-only default `new Date()`. Applied only when the field is
+   * omitted from `.make(...)` input. NOT applied during decode — cannot be
+   * used to JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: DateFromString.pipe(S.withConstructorDefault(Effect.sync(() => new global.Date()))),
+  /**
+   * Decode-time default `new Date()`. **Discouraged for persisted data:** a
+   * missing field may be data corruption, not an old-shape document; silently
+   * substituting `new Date()` hides the problem. Prefer an explicit,
+   * preferably versioned migration over a decode-time fallback. See
+   * file-level note.
+   */
   withDecodingDefaultType: DateFromString.pipe(S.withDecodingDefaultType(Effect.sync(() => new global.Date())))
 })
 
-/**
- * Like the default Schema `DateValid` but from String with `withDefault` => now
- */
+/** Like the default Schema `DateValid` but from String, with default helpers. */
 export const DateValid = Object.assign(Date.check(isDateValid()), {
-  withDefault: DateFromString.pipe(S.withConstructorDefault(Effect.sync(() => new global.Date()))),
+  /**
+   * Construction-only default `new Date()`. Applied only when the field is
+   * omitted from `.make(...)` input. NOT applied during decode — cannot be
+   * used to JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: DateFromString.pipe(S.withConstructorDefault(Effect.sync(() => new global.Date()))),
+  /**
+   * Decode-time default `new Date()`. **Discouraged for persisted data:** a
+   * missing field may be data corruption, not an old-shape document; silently
+   * substituting `new Date()` hides the problem. Prefer an explicit,
+   * preferably versioned migration over a decode-time fallback. See
+   * file-level note.
+   */
   withDecodingDefaultType: DateFromString.pipe(S.withDecodingDefaultType(Effect.sync(() => new global.Date())))
 })
 
-/**
- * Like the default Schema `Boolean` but with `withDefault` => false
- */
+/** Like the default Schema `Boolean` but with default helpers. */
 export const Boolean = Object.assign(S.Boolean, {
-  withDefault: S.Boolean.pipe(S.withConstructorDefault(Effect.succeed(false))),
+  /**
+   * Construction-only default `false`. Applied only when the field is
+   * omitted from `.make(...)` input. NOT applied during decode — cannot be
+   * used to JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: S.Boolean.pipe(S.withConstructorDefault(Effect.succeed(false))),
+  /**
+   * Decode-time default `false`. **Discouraged for persisted data:** a
+   * missing field may be data corruption, not an old-shape document; silently
+   * substituting `false` hides the problem. Prefer an explicit, preferably
+   * versioned migration over a decode-time fallback. See file-level note.
+   */
   withDecodingDefaultType: S.Boolean.pipe(S.withDecodingDefaultType(Effect.succeed(false)))
 })
 
 /**
- * You probably want to use `Finite` instead of this.
- * Like the default Schema `Number` but with `withDefault` => 0
+ * You probably want to use `Finite` instead of this. Like the default Schema
+ * `Number` but with default helpers.
  */
 export const Number = Object.assign(S.Number, {
-  withDefault: S.Number.pipe(S.withConstructorDefault(Effect.succeed(0))),
+  /**
+   * Construction-only default `0`. Applied only when the field is omitted
+   * from `.make(...)` input. NOT applied during decode — cannot be used to
+   * JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: S.Number.pipe(S.withConstructorDefault(Effect.succeed(0))),
+  /**
+   * Decode-time default `0`. **Discouraged for persisted data:** a missing
+   * field may be data corruption, not an old-shape document; silently
+   * substituting `0` hides the problem. Prefer an explicit, preferably
+   * versioned migration over a decode-time fallback. See file-level note.
+   */
   withDecodingDefaultType: S.Number.pipe(S.withDecodingDefaultType(Effect.succeed(0)))
 })
 
-/**
- * Like the default Schema `Finite` but with `withDefault` => 0
- */
+/** Like the default Schema `Finite` but with default helpers. */
 export const Finite = Object.assign(S.Finite, {
-  withDefault: S.Finite.pipe(S.withConstructorDefault(Effect.succeed(0))),
+  /**
+   * Construction-only default `0`. Applied only when the field is omitted
+   * from `.make(...)` input. NOT applied during decode — cannot be used to
+   * JIT-migrate database fields. See file-level note.
+   */
+  withConstructorDefault: S.Finite.pipe(S.withConstructorDefault(Effect.succeed(0))),
+  /**
+   * Decode-time default `0`. **Discouraged for persisted data:** a missing
+   * field may be data corruption, not an old-shape document; silently
+   * substituting `0` hides the problem. Prefer an explicit, preferably
+   * versioned migration over a decode-time fallback. See file-level note.
+   */
   withDecodingDefaultType: S.Finite.pipe(S.withDecodingDefaultType(Effect.succeed(0)))
 })
 
-/**
- * Like the default Schema `Literals` but with `withDefault` => literals[0]
- */
+/** Like the default Schema `Literals` but with default helpers. Default value is `literals[0]`. */
 export const Literals = <const Literals extends NonEmptyReadonlyArray<AST.LiteralValue>>(literals: Literals) =>
   pipe(
     S.Literals(literals),
     (s) =>
       Object.assign(s, {
+        /** Override the default literal value used by `withConstructorDefault` / `withDecodingDefaultType`. */
         changeDefault: <A extends Literals[number]>(a: A) => {
           return Object.assign(S.Literals(literals), {
             Default: a,
-            withDefault: s.pipe(S.withConstructorDefault(Effect.succeed(a))),
+            /**
+             * Construction-only default. Applied only when the field is
+             * omitted from `.make(...)` input. NOT applied during decode —
+             * cannot be used to JIT-migrate database fields. See file-level
+             * note.
+             */
+            withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.succeed(a))),
+            /**
+             * Decode-time default. **Discouraged for persisted data:** a
+             * missing field may be data corruption, not an old-shape
+             * document; silently substituting hides the problem. Prefer an
+             * explicit, preferably versioned migration over a decode-time
+             * fallback. See file-level note.
+             */
             withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.succeed(a)))
           }) // todo: copy annotations from original?
         },
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- load-bearing: Object.assign widens the field type without it, breaking `expectTypeOf(l.Default).toEqualTypeOf<"a">()` in tests
         Default: literals[0] as Literals[0],
-        withDefault: s.pipe(S.withConstructorDefault(Effect.succeed(literals[0]))),
+        /**
+         * Construction-only default `literals[0]`. Applied only when the
+         * field is omitted from `.make(...)` input. NOT applied during
+         * decode — cannot be used to JIT-migrate database fields. See
+         * file-level note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.succeed(literals[0]))),
+        /**
+         * Decode-time default `literals[0]`. **Discouraged for persisted
+         * data:** a missing field may be data corruption, not an old-shape
+         * document; silently substituting hides the problem. Prefer an
+         * explicit, preferably versioned migration over a decode-time
+         * fallback. See file-level note.
+         */
         withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.succeed(literals[0])))
       })
   )
 
-/**
- * Like the default Schema `Array` but with `withDefault` => []
- */
+/** Like the default Schema `Array` but with default helpers. */
 export function Array<ValueSchema extends S.Top>(value: ValueSchema) {
   return pipe(
     S.Array(value).annotate(concurrencyUnbounded),
     (s) =>
       Object.assign(s, {
-        withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => []))),
+        /**
+         * Construction-only default `[]`. Applied only when the field is
+         * omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => []))),
+        /**
+         * Decode-time default `[]`. **Discouraged for persisted data:** a
+         * missing field may be data corruption, not an old-shape document;
+         * silently substituting `[]` hides the problem. Prefer an explicit,
+         * preferably versioned migration over a decode-time fallback. See
+         * file-level note.
+         */
         withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => [])))
       })
   )
@@ -204,24 +319,35 @@ export const ReadonlyMapFromArray = <KeySchema extends S.Top, ValueSchema extend
   return schema
 }
 
-/**
- * Like the default Schema `ReadonlySet` but from Array with `withDefault` => new Set()
- */
+/** Like the default Schema `ReadonlySet` but from Array, with default helpers. */
 export const ReadonlySet = <ValueSchema extends S.Top>(value: ValueSchema) =>
   pipe(
     ReadonlySetFromArray(value),
     (s) =>
       Object.assign(s, {
-        withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new Set<S.Schema.Type<ValueSchema>>()))),
+        /**
+         * Construction-only default `new Set()`. Applied only when the field
+         * is omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(
+          S.withConstructorDefault(Effect.sync(() => new Set<S.Schema.Type<ValueSchema>>()))
+        ),
+        /**
+         * Decode-time default `new Set()`. **Discouraged for persisted
+         * data:** a missing field may be data corruption, not an old-shape
+         * document; silently substituting an empty set hides the problem.
+         * Prefer an explicit, preferably versioned migration over a
+         * decode-time fallback. See file-level note.
+         */
         withDecodingDefaultType: s.pipe(
           S.withDecodingDefaultType(Effect.sync(() => new Set<S.Schema.Type<ValueSchema>>()))
         )
       })
   )
 
-/**
- * Like the default Schema `ReadonlyMap` but from Array with `withDefault` => new Map()
- */
+/** Like the default Schema `ReadonlyMap` but from Array, with default helpers. */
 export const ReadonlyMap = <KeySchema extends S.Top, ValueSchema extends S.Top>(pair: {
   readonly key: KeySchema
   readonly value: ValueSchema
@@ -230,39 +356,105 @@ export const ReadonlyMap = <KeySchema extends S.Top, ValueSchema extends S.Top>(
     ReadonlyMapFromArray(pair),
     (s) =>
       Object.assign(s, {
-        withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new Map()))),
+        /**
+         * Construction-only default `new Map()`. Applied only when the field
+         * is omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new Map()))),
+        /**
+         * Decode-time default `new Map()`. **Discouraged for persisted
+         * data:** a missing field may be data corruption, not an old-shape
+         * document; silently substituting an empty map hides the problem.
+         * Prefer an explicit, preferably versioned migration over a
+         * decode-time fallback. See file-level note.
+         */
         withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => new Map())))
       })
   )
 
-/**
- * Like the default Schema `NullOr` but with `withDefault` => null
- */
+/** Like the default Schema `NullOr` but with default helpers. */
 export const NullOr = <Schema extends S.Top>(self: Schema) =>
   pipe(
     S.NullOr(self),
     (s) =>
       Object.assign(s, {
-        withDefault: s.pipe(S.withConstructorDefault(Effect.succeed(null))),
+        /**
+         * Construction-only default `null`. Applied only when the field is
+         * omitted from `.make(...)` input. NOT applied during decode —
+         * cannot be used to JIT-migrate database fields. See file-level
+         * note.
+         */
+        withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.succeed(null))),
+        /**
+         * Decode-time default `null`. **Discouraged for persisted data:** a
+         * missing field may be data corruption, not an old-shape document;
+         * silently substituting `null` hides the problem. Prefer an
+         * explicit, preferably versioned migration over a decode-time
+         * fallback. See file-level note.
+         */
         withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.succeed(null)))
       })
   )
 
+/**
+ * Attach a `withConstructorDefault` of `new Date()` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
 export const defaultDate = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
   schema.pipe(S.withConstructorDefault(Effect.sync(() => new global.Date())))
 
+/**
+ * Attach a `withConstructorDefault` of `false` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
 export const defaultBool = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
   schema.pipe(S.withConstructorDefault(Effect.succeed(false)))
 
+/**
+ * Attach a `withConstructorDefault` of `null` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
 export const defaultNullable = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
   schema.pipe(S.withConstructorDefault(Effect.succeed(null)))
 
+/**
+ * Attach a `withConstructorDefault` of `[]` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
 export const defaultArray = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
   schema.pipe(S.withConstructorDefault(Effect.sync(() => [])))
 
+/**
+ * Attach a `withConstructorDefault` of `new Map()` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
 export const defaultMap = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
   schema.pipe(S.withConstructorDefault(Effect.sync(() => new Map())))
 
+/**
+ * Attach a `withConstructorDefault` of `new Set()` to any schema.
+ *
+ * **Construction-only.** Applied only when the field is omitted from
+ * `.make(...)` input. NOT applied during decode — cannot be used to
+ * JIT-migrate database fields. See file-level note.
+ */
 export const defaultSet = <Schema extends S.Top & S.WithoutConstructorDefault>(schema: Schema) =>
   schema.pipe(S.withConstructorDefault(Effect.sync(() => new Set())))
 
@@ -293,10 +485,23 @@ export type WithDefaults<Self extends S.Top> = (
 // export type UnionToIntersection3<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I
 //   : never
 
+/** Union of `DateValid` and `Date`, with default helpers. */
 export const inputDate = extendM(
   S.Union([S.DateValid, Date]),
   (s) => ({
-    withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new globalThis.Date()))),
+    /**
+     * Construction-only default `new Date()`. Applied only when the field is
+     * omitted from `.make(...)` input. NOT applied during decode — cannot be
+     * used to JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => new globalThis.Date()))),
+    /**
+     * Decode-time default `new Date()`. **Discouraged for persisted data:** a
+     * missing field may be data corruption, not an old-shape document;
+     * silently substituting `new Date()` hides the problem. Prefer an
+     * explicit, preferably versioned migration over a decode-time fallback.
+     * See file-level note.
+     */
     withDecodingDefaultType: s.pipe(S.withDecodingDefaultType(Effect.sync(() => new globalThis.Date())))
   })
 )

package/src/Schema/moreStrings.ts

@@ -1,3 +1,13 @@
+/**
+ * Branded string ID schemas with `.withConstructorDefault` extensions.
+ *
+ * Each `.withConstructorDefault` here is **only** applied when the field is
+ * omitted during construction (`.make(...)`). It is **not** applied during
+ * decode and therefore cannot be used to JIT-migrate database fields.
+ *
+ * For persisted data, prefer an explicit, preferably versioned migration
+ * over decode-time fallbacks. See `./ext.ts` for the full policy note.
+ */
 import { Effect, pipe } from "effect"
 import type { Refinement } from "effect-app/Function"
 import { extendM } from "effect-app/utils"
@@ -146,6 +156,9 @@ const StringIdArb = (): S.LazyArbitrary<StringId> => (fc) =>
     .map((_) => customRandom(urlAlphabet, size, (size) => _.subarray(0, size))() as StringId)
 /**
  * A string that is at least 6 characters long and a maximum of 50.
+ *
+ * `.withConstructorDefault` => fresh `nanoid()` (construction-only; not
+ * applied during decode — see file-level note).
  */
 export const StringId = extendM(
   pipe(
@@ -159,7 +172,13 @@ export const StringId = extendM(
   ),
   (s) => ({
     make: makeStringId,
-    withDefault: s.pipe(S.withConstructorDefault(Effect.sync(makeStringId)))
+    /**
+     * Construction-only default: fresh `nanoid()`-shaped `StringId`. Applied
+     * only when the field is omitted from `.make(...)` input. NOT applied
+     * during decode — cannot be used to JIT-migrate database fields. See
+     * file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(makeStringId)))
   })
 )
   .pipe(withDefaultMake)
@@ -168,6 +187,14 @@ export const StringId = extendM(
 
 // const prefixedStringIdUnsafeThunk = (prefix: string) => () => prefixedStringIdUnsafe(prefix)
 
+/**
+ * Build a `StringId` schema whose values are required to start with a fixed
+ * `prefix` (joined with `separator`, default `-`).
+ *
+ * The returned schema exposes `.withConstructorDefault` that mints a fresh
+ * prefixed id. Construction-only — not applied during decode; see file-level
+ * note.
+ */
 export function prefixedStringId<Type extends StringId>() {
   return <Prefix extends string, Separator extends string = "-">(
     prefix: Prefix,
@@ -206,20 +233,40 @@ export function prefixedStringId<Type extends StringId>() {
          */
         prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => ex(str),
         prefix,
-        withDefault: schema.pipe(S.withConstructorDefault<S.Codec<Type, string> & S.WithoutConstructorDefault>(
-          Effect.sync(make)
-        ))
+        /**
+         * Construction-only default: fresh prefixed id. Applied only when
+         * the field is omitted from `.make(...)` input. NOT applied during
+         * decode — cannot be used to JIT-migrate database fields. See
+         * file-level note.
+         */
+        withConstructorDefault: schema.pipe(
+          S.withConstructorDefault<S.Codec<Type, string> & S.WithoutConstructorDefault>(
+            Effect.sync(make)
+          )
+        )
       })
     )
   }
 }
 
+/**
+ * Build a branded `StringId` schema for the given branded `Id` type.
+ *
+ * Exposes `.withConstructorDefault` that mints a fresh `nanoid()`-shaped id.
+ * Construction-only — not applied during decode; see file-level note.
+ */
 export const brandedStringId = <
   Id
 >() =>
   withDefaultMake(
     Object.assign(Object.create(StringId), StringId) as S.Codec<Id, string> & {
-      withDefault: S.withConstructorDefault<S.Codec<Id, string> & S.WithoutConstructorDefault>
+      /**
+       * Construction-only default: fresh `nanoid()`-shaped id. Applied only
+       * when the field is omitted from `.make(...)` input. NOT applied
+       * during decode — cannot be used to JIT-migrate database fields. See
+       * file-level note.
+       */
+      withConstructorDefault: S.withConstructorDefault<S.Codec<Id, string> & S.WithoutConstructorDefault>
       make: () => Id
     } & WithDefaults<S.Codec<Id, string>>
   )
@@ -233,7 +280,12 @@ export interface PrefixedStringUtils<
   readonly unsafeFrom: (str: string) => Type
   prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => Type
   readonly prefix: Prefix
-  readonly withDefault: S.withConstructorDefault<S.Codec<Type, string> & S.WithoutConstructorDefault>
+  /**
+   * Construction-only default: fresh prefixed id. Applied only when the
+   * field is omitted from `.make(...)` input. NOT applied during decode —
+   * cannot be used to JIT-migrate database fields. See file-level note.
+   */
+  readonly withConstructorDefault: S.withConstructorDefault<S.Codec<Type, string> & S.WithoutConstructorDefault>
 }
 
 export interface UrlBrand extends Simplify<B.Brand<"Url"> & NonEmptyStringBrand> {}

package/src/Schema/numbers.ts

@@ -1,3 +1,13 @@
+/**
+ * Numeric brand schemas with `.withConstructorDefault` extensions.
+ *
+ * Each `.withConstructorDefault` here is **only** applied when the field is
+ * omitted during construction (`.make(...)`). It is **not** applied during
+ * decode and therefore cannot be used to JIT-migrate database fields.
+ *
+ * For persisted data, prefer an explicit, preferably versioned migration
+ * over decode-time fallbacks. See `./ext.ts` for the full policy note.
+ */
 import { Effect } from "effect"
 import { extendM } from "effect-app/utils"
 import * as S from "effect/Schema"
@@ -9,17 +19,26 @@ import { type B } from "./schema.js"
 export interface PositiveIntBrand
   extends Simplify<B.Brand<"PositiveInt"> & NonNegativeIntBrand & PositiveNumberBrand>
 {}
+/** Positive integer. `.withConstructorDefault` => `1` (construction-only). */
 export const PositiveInt = extendM(
   S.Int.pipe(
     S.check(S.isGreaterThan(0)),
     fromBrand<PositiveInt>(nominal<PositiveInt>(), { identifier: "PositiveInt", jsonSchema: {} }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(1)))) })
+  (s) => ({
+    /**
+     * Construction-only default `1`. Applied only when the field is omitted
+     * from `.make(...)` input. NOT applied during decode — cannot be used to
+     * JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(1))))
+  })
 )
 export type PositiveInt = number & PositiveIntBrand
 
 export interface NonNegativeIntBrand extends Simplify<B.Brand<"NonNegativeInt"> & IntBrand & NonNegativeNumberBrand> {}
+/** Non-negative integer. `.withConstructorDefault` => `0` (construction-only). */
 export const NonNegativeInt = extendM(
   S.Int.pipe(
     S.check(S.isGreaterThanOrEqualTo(0)),
@@ -29,18 +48,34 @@ export const NonNegativeInt = extendM(
     }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0)))) })
+  (s) => ({
+    /**
+     * Construction-only default `0`. Applied only when the field is omitted
+     * from `.make(...)` input. NOT applied during decode — cannot be used to
+     * JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0))))
+  })
 )
 export type NonNegativeInt = number & NonNegativeIntBrand
 
 export interface IntBrand extends Simplify<B.Brand<"Int">> {}
+/** Integer. `.withConstructorDefault` => `0` (construction-only). */
 export const Int = extendM(
   S.Int.pipe(fromBrand<Int>(nominal<Int>(), { identifier: "Int", jsonSchema: {} }), withDefaultMake),
-  (s) => ({ withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0)))) })
+  (s) => ({
+    /**
+     * Construction-only default `0`. Applied only when the field is omitted
+     * from `.make(...)` input. NOT applied during decode — cannot be used to
+     * JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0))))
+  })
 )
 export type Int = number & IntBrand
 
 export interface PositiveNumberBrand extends Simplify<B.Brand<"PositiveNumber"> & NonNegativeNumberBrand> {}
+/** Positive finite number. `.withConstructorDefault` => `1` (construction-only). */
 export const PositiveNumber = extendM(
   S.Finite.pipe(
     S.check(S.isGreaterThan(0)),
@@ -50,11 +85,19 @@ export const PositiveNumber = extendM(
     }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(1)))) })
+  (s) => ({
+    /**
+     * Construction-only default `1`. Applied only when the field is omitted
+     * from `.make(...)` input. NOT applied during decode — cannot be used to
+     * JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(1))))
+  })
 )
 export type PositiveNumber = number & PositiveNumberBrand
 
 export interface NonNegativeNumberBrand extends Simplify<B.Brand<"NonNegativeNumber">> {}
+/** Non-negative finite number. `.withConstructorDefault` => `0` (construction-only). */
 export const NonNegativeNumber = extendM(
   S
     .Finite
@@ -66,7 +109,14 @@ export const NonNegativeNumber = extendM(
       }),
       withDefaultMake
     ),
-  (s) => ({ withDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0)))) })
+  (s) => ({
+    /**
+     * Construction-only default `0`. Applied only when the field is omitted
+     * from `.make(...)` input. NOT applied during decode — cannot be used to
+     * JIT-migrate database fields. See file-level note.
+     */
+    withConstructorDefault: s.pipe(S.withConstructorDefault(Effect.sync(() => s(0))))
+  })
 )
 export type NonNegativeNumber = number & NonNegativeNumberBrand