effect-app 4.0.0-beta.33 → 4.0.0-beta.331

package/src/Schema/moreStrings.ts

@@ -1,21 +1,36 @@
-import { pipe } from "effect"
+/**
+ * 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 type { Refinement } from "effect-app/Function"
 import { extendM } from "effect-app/utils"
+import type * as B from "effect/Brand"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
 import * as S from "effect/Schema"
+import * as Getter from "effect/SchemaGetter"
+import * as SchemaIssue from "effect/SchemaIssue"
 import type { Simplify } from "effect/Types"
 import { customRandom, nanoid, urlAlphabet } from "nanoid"
 import validator from "validator"
-import { fromBrand, nominal } from "./brand.js"
-import { withDefaultConstructor, withDefaultMake, type WithDefaults } from "./ext.js"
-import { type B } from "./schema.js"
-import type { NonEmptyString255Brand, NonEmptyStringBrand } from "./strings.js"
+import type * as SchemaAST from "../SchemaAST.ts"
+import { type BrandedSchema, fromBrand, nominal } from "./brand.ts"
+import { withDefaultMake } from "./ext.ts"
+import { type B as SchemaB } from "./schema.ts"
+import type { NonEmptyString255Brand, NonEmptyStringBrand } from "./strings.ts"
 
 const nonEmptyString = S.NonEmptyString
 
 /**
  * A string that is at least 1 character long and a maximum of 50.
  */
-export interface NonEmptyString50Brand extends Simplify<B.Brand<"NonEmptyString50"> & NonEmptyString64Brand> {}
+export interface NonEmptyString50Brand extends Simplify<SchemaB.Brand<"NonEmptyString50"> & NonEmptyString64Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 50.
@@ -25,11 +40,13 @@ export type NonEmptyString50 = string & NonEmptyString50Brand
 /**
  * A string that is at least 1 character long and a maximum of 50.
  */
-export const NonEmptyString50 = nonEmptyString.pipe(
+export interface NonEmptyString50Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString50> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString50
+}
+export const NonEmptyString50: NonEmptyString50Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(50)),
-  fromBrand(nominal<NonEmptyString50>(), {
+  fromBrand<NonEmptyString50>(nominal<NonEmptyString50>(), {
     identifier: "NonEmptyString50",
-    title: "NonEmptyString50",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -38,7 +55,7 @@ export const NonEmptyString50 = nonEmptyString.pipe(
 /**
  * A string that is at least 1 character long and a maximum of 64.
  */
-export interface NonEmptyString64Brand extends Simplify<B.Brand<"NonEmptyString64"> & NonEmptyString80Brand> {}
+export interface NonEmptyString64Brand extends Simplify<SchemaB.Brand<"NonEmptyString64"> & NonEmptyString80Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 64.
@@ -48,11 +65,13 @@ export type NonEmptyString64 = string & NonEmptyString64Brand
 /**
  * A string that is at least 1 character long and a maximum of 64.
  */
-export const NonEmptyString64 = nonEmptyString.pipe(
+export interface NonEmptyString64Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString64> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString64
+}
+export const NonEmptyString64: NonEmptyString64Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(64)),
-  fromBrand(nominal<NonEmptyString64>(), {
+  fromBrand<NonEmptyString64>(nominal<NonEmptyString64>(), {
     identifier: "NonEmptyString64",
-    title: "NonEmptyString64",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -61,7 +80,7 @@ export const NonEmptyString64 = nonEmptyString.pipe(
 /**
  * A string that is at least 1 character long and a maximum of 80.
  */
-export interface NonEmptyString80Brand extends Simplify<B.Brand<"NonEmptyString80"> & NonEmptyString100Brand> {}
+export interface NonEmptyString80Brand extends Simplify<SchemaB.Brand<"NonEmptyString80"> & NonEmptyString100Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 80.
@@ -72,11 +91,13 @@ export type NonEmptyString80 = string & NonEmptyString80Brand
  * A string that is at least 1 character long and a maximum of 80.
  */
 
-export const NonEmptyString80 = nonEmptyString.pipe(
+export interface NonEmptyString80Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString80> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString80
+}
+export const NonEmptyString80: NonEmptyString80Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(80)),
-  fromBrand(nominal<NonEmptyString80>(), {
+  fromBrand<NonEmptyString80>(nominal<NonEmptyString80>(), {
     identifier: "NonEmptyString80",
-    title: "NonEmptyString80",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -85,7 +106,7 @@ export const NonEmptyString80 = nonEmptyString.pipe(
 /**
  * A string that is at least 1 character long and a maximum of 100.
  */
-export interface NonEmptyString100Brand extends Simplify<B.Brand<"NonEmptyString100"> & NonEmptyString255Brand> {}
+export interface NonEmptyString100Brand extends Simplify<SchemaB.Brand<"NonEmptyString100"> & NonEmptyString255Brand> {}
 
 /**
  * A string that is at least 1 character long and a maximum of 100.
@@ -95,11 +116,13 @@ export type NonEmptyString100 = string & NonEmptyString100Brand
 /**
  * A string that is at least 1 character long and a maximum of 100.
  */
-export const NonEmptyString100 = nonEmptyString.pipe(
+export interface NonEmptyString100Schema extends BrandedSchema<S.NonEmptyString, NonEmptyString100> {
+  (i: string, options?: SchemaAST.ParseOptions): NonEmptyString100
+}
+export const NonEmptyString100: NonEmptyString100Schema = nonEmptyString.pipe(
   S.check(S.isMaxLength(100)),
-  fromBrand(nominal<NonEmptyString100>(), {
+  fromBrand<NonEmptyString100>(nominal<NonEmptyString100>(), {
     identifier: "NonEmptyString100",
-    title: "NonEmptyString100",
     jsonSchema: {}
   }),
   withDefaultMake
@@ -108,7 +131,7 @@ export const NonEmptyString100 = nonEmptyString.pipe(
 /**
  * A string that is at least 3 character long and a maximum of 255.
  */
-export interface Min3String255Brand extends Simplify<B.Brand<"Min3String255"> & NonEmptyString255Brand> {}
+export interface Min3String255Brand extends Simplify<SchemaB.Brand<"Min3String255"> & NonEmptyString255Brand> {}
 
 /**
  * A string that is at least 3 character long and a maximum of 255.
@@ -118,58 +141,115 @@ export type Min3String255 = string & Min3String255Brand
 /**
  * A string that is at least 3 character long and a maximum of 255.
  */
-export const Min3String255 = pipe(
+export interface Min3String255Schema extends BrandedSchema<S.String, Min3String255> {
+  (i: string, options?: SchemaAST.ParseOptions): Min3String255
+}
+export const Min3String255: Min3String255Schema = pipe(
   S.String,
   S.check(S.isMinLength(3), S.isMaxLength(255)),
-  fromBrand(nominal<Min3String255>(), { identifier: "Min3String255", title: "Min3String255", jsonSchema: {} }),
+  fromBrand<Min3String255>(nominal<Min3String255>(), {
+    identifier: "Min3String255",
+    jsonSchema: {}
+  }),
   withDefaultMake
 )
 
 /**
  * A string that is at least 6 characters long and a maximum of 50.
  */
-export interface StringIdBrand extends Simplify<B.Brand<"StringId"> & NonEmptyString50Brand> {}
+export interface StringIdBrand extends Simplify<SchemaB.Brand<"StringId"> & NonEmptyString50Brand> {}
 
 /**
  * A string that is at least 6 characters long and a maximum of 50.
  */
 export type StringId = string & StringIdBrand
 
-const makeStringId = (): StringId => nanoid() as unknown as StringId
 const minLength = 6
 const maxLength = 50
-const size = 21
-const length = 10 * size
-const StringIdArb = (): S.LazyArbitrary<StringId> => (fc) =>
-  fc
-    .uint8Array({ minLength: length, maxLength: length })
-    .map((_) => customRandom(urlAlphabet, size, (size) => _.subarray(0, size))() as StringId)
+const nanoidSize = 21
+const nanoidByteLength = 10 * nanoidSize
+
+const StringIdString = pipe(
+  S.String,
+  S.check(S.isMinLength(minLength), S.isMaxLength(maxLength)),
+  fromBrand<StringId>(nominal<StringId>(), {
+    identifier: "StringId",
+    jsonSchema: {}
+  })
+)
+
+const nanoidFromBytes = (bytes: Uint8Array) =>
+  customRandom(urlAlphabet, nanoidSize, (size) => bytes.subarray(0, size))() as StringId
+
+// JSON stays a branded string (toCodec). Generation uses toCodecArbitrary — the native
+// replacement for fast-check `toArbitrary` — same as the old StringIdArb:
+// uint8Array(210).map(bytes => customRandom(urlAlphabet, 21, …)).
+const StringIdSchemaBase = S.declareConstructor<StringId, string>()(
+  [],
+  () => (input, ast, options) =>
+    S.is(StringIdString)(input)
+      ? Effect.succeed(input)
+      : Effect.fail(new SchemaIssue.InvalidType(ast, input, options)),
+  {
+    identifier: "StringId",
+    expected: "StringId",
+    toCodec: () =>
+      S.link<StringId>()(StringIdString, {
+        decode: Getter.passthrough(),
+        encode: Getter.passthrough()
+      }),
+    toCodecArbitrary: () =>
+      S.link<StringId>()(
+        S.Uint8Array.check(S.isMinLength(nanoidByteLength), S.isMaxLength(nanoidByteLength)),
+        {
+          decode: Getter.transform(nanoidFromBytes),
+          encode: Getter.forbiddenEncoding
+        }
+      )
+  }
+)
+const makeStringId = (s?: string): StringId =>
+  s !== undefined ? S.decodeSync(StringIdString)(s) : nanoid() as unknown 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(
-    S.String,
-    S.check(S.isMinLength(minLength), S.isMaxLength(maxLength)),
-    fromBrand(nominal<StringId>(), {
-      identifier: "StringId",
-      title: "StringId",
-      toArbitrary: () => (fc) => StringIdArb()(fc),
-      jsonSchema: {}
-    })
-  ),
+export interface StringIdSchema extends S.declareConstructor<StringId, string, readonly [], StringId> {
+  (i: string, options?: SchemaAST.ParseOptions): StringId
+  /** Generate fresh `nanoid()`-shaped `StringId`. */
+  make(): StringId
+  /** Construct a `StringId` from a known string (validated via decodeSync). */
+  make(input: string, options?: S.MakeOptions): StringId
+  readonly withConstructorDefault: S.withConstructorDefault<
+    S.declareConstructor<StringId, string, readonly [], StringId>
+  >
+}
+export const StringId: StringIdSchema = extendM(
+  StringIdSchemaBase,
   (s) => ({
     make: makeStringId,
-    withDefault: s.pipe(withDefaultConstructor(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)
 
-// const prefixedStringIdUnsafe = (prefix: string) => StringId(prefix + StringId.make())
-
-// const prefixedStringIdUnsafeThunk = (prefix: string) => () => prefixedStringIdUnsafe(prefix)
-
-export function prefixedStringId<Brand extends StringId>() {
+/**
+ * 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,
     name: string,
@@ -177,27 +257,42 @@ export function prefixedStringId<Brand extends StringId>() {
   ) => {
     type FullPrefix = `${Prefix}${Separator}`
     const pref = `${prefix}${separator ?? "-"}` as FullPrefix
-    const arb = (): S.LazyArbitrary<string & Brand> => (fc) =>
-      StringIdArb()(fc).map(
-        (x) => (pref + x.substring(0, 50 - pref.length)) as Brand
-      )
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const s: S.Codec<string & Brand, string> = StringId
-      .pipe(
-        S.refine((x: string): x is string & Brand => x.startsWith(pref), {
-          identifier: name,
-          title: name
-        }),
-        S.annotate({
-          toArbitrary: () => (fc) => arb()(fc)
-        })
-      ) as S.Codec<string & Brand, string>
+    const PrefixedString = StringIdString.pipe(
+      S.refine((x): x is Type => x.startsWith(pref), { identifier: name })
+    )
+    // Pre-rc.114: StringIdArb().map(x => pref + x.substring(0, 50 - pref.length))
+    const s = S.declareConstructor<Type, string>()(
+      [],
+      () => (input, ast, options) =>
+        S.is(PrefixedString)(input)
+          ? Effect.succeed(input)
+          : Effect.fail(new SchemaIssue.InvalidType(ast, input, options)),
+      {
+        identifier: name,
+        expected: name,
+        toCodec: () =>
+          S.link<Type>()(PrefixedString, {
+            decode: Getter.passthrough(),
+            encode: Getter.passthrough()
+          }),
+        toCodecArbitrary: () =>
+          S.link<Type>()(
+            S.Uint8Array.check(S.isMinLength(nanoidByteLength), S.isMaxLength(nanoidByteLength)),
+            {
+              decode: Getter.transform((bytes) =>
+                (pref + nanoidFromBytes(bytes).substring(0, maxLength - pref.length)) as Type
+              ),
+              encode: Getter.forbiddenEncoding
+            }
+          )
+      }
+    )
     const schema = s.pipe(withDefaultMake)
-    const make = () => (pref + StringId.make().substring(0, 50 - pref.length)) as Brand
+    const make = () => (pref + StringId.make().substring(0, 50 - pref.length)) as Type
 
     return extendM(
       schema,
-      (ex): PrefixedStringUtils<Brand, Prefix, Separator> => ({
+      (ex): PrefixedStringUtils<Type, Prefix, Separator> => ({
         make,
         /**
          * Automatically adds the prefix.
@@ -208,35 +303,60 @@ export function prefixedStringId<Brand extends StringId>() {
          */
         prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => ex(str),
         prefix,
-        withDefault: schema.pipe(withDefaultConstructor(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)
+          )
+        )
       })
     )
   }
 }
 
-export const brandedStringId = <
-  Brand extends StringIdBrand
->() =>
+/**
+ * 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 extends string & B.Brand<any>>(): BrandedStringIdSchema<Id> =>
   withDefaultMake(
-    Object.assign(Object.create(StringId), StringId) as S.Codec<string & Brand, string> & {
-      make: () => string & Brand
-      withDefault: S.withConstructorDefault<S.Codec<string & Brand, string> & S.WithoutConstructorDefault>
-    } & WithDefaults<S.Codec<string & Brand, string>>
+    Object.assign(Object.create(StringId), StringId) as BrandedStringIdSchema<Id>
   )
 
 export interface PrefixedStringUtils<
-  Brand extends StringId,
+  Type extends StringId,
   Prefix extends string,
   Separator extends string
 > {
-  readonly make: () => Brand
-  readonly unsafeFrom: (str: string) => Brand
-  prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => Brand
+  readonly make: () => Type
+  readonly unsafeFrom: (str: string) => Type
+  prefixSafe: <REST extends string>(str: `${Prefix}${Separator}${REST}`) => Type
   readonly prefix: Prefix
-  readonly withDefault: S.withConstructorDefault<S.Codec<Brand, 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 BrandedStringIdSchema<Id extends string & B.Brand<any>> extends BrandedSchema<S.String, Id> {
+  (i: string, options?: SchemaAST.ParseOptions): Id
+  /** Generate fresh `nanoid()`-shaped id (inherited from `StringId`). */
+  make(): Id
+  /** Construct an `Id` from a known string (validated via decodeSync). */
+  make(input: string, options?: S.MakeOptions): Id
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.String, Id>>
 }
 
-export interface UrlBrand extends Simplify<B.Brand<"Url"> & NonEmptyStringBrand> {}
+export interface UrlBrand extends Simplify<SchemaB.Brand<"Url"> & NonEmptyStringBrand> {}
 
 export type Url = string & UrlBrand
 
@@ -244,16 +364,27 @@ const isUrl: Refinement<string, Url> = (s: string): s is Url => {
   return validator.default.isURL(s, { require_tld: false })
 }
 
-export const Url = S
+export interface UrlSchema extends S.refine<Url, S.String> {
+  (i: string, options?: SchemaAST.ParseOptions): Url
+}
+export const Url: UrlSchema = S
   .String
   .pipe(
-    S.refine(isUrl, {
-      identifier: "Url",
+    S.annotate({
       title: "Url",
-      jsonSchema: { format: "uri" }
+      format: "uri"
     }),
-    S.annotate({
-      toArbitrary: () => (fc) => fc.webUrl().map((_) => _ as Url)
+    S.refine(isUrl, {
+      identifier: "Url",
+      jsonSchema: { format: "uri" },
+      // Native Arbitrary otherwise emits strings that `isURL({ require_tld: false })`
+      // accepts (`"R"`, `"prototype"`). Restore the old fast-check `fc.webUrl()` shape.
+      arbitraryConstraint: {
+        patterns: [{
+          source: "^https://[a-z]{3,12}\\.(?:com|net|org|de)(?:/[a-z0-9-]{0,16})?$",
+          flags: ""
+        }]
+      }
     }),
     withDefaultMake
   )

package/src/Schema/numbers.ts

@@ -1,76 +1,155 @@
+/**
+ * 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 { extendM } from "effect-app/utils"
+import * as Effect from "effect/Effect"
+import * as Order from "effect/Order"
 import * as S from "effect/Schema"
 import type { Simplify } from "effect/Types"
-import { fromBrand, nominal } from "./brand.js"
-import { withDefaultConstructor, withDefaultMake } from "./ext.js"
-import { type B } from "./schema.js"
+import type * as SchemaAST from "../SchemaAST.ts"
+import { type BrandedSchema, fromBrand, nominal } from "./brand.ts"
+import { withDefaultMake } from "./ext.ts"
+import { type B } from "./schema.ts"
 
 export interface PositiveIntBrand
   extends Simplify<B.Brand<"PositiveInt"> & NonNegativeIntBrand & PositiveNumberBrand>
 {}
-export const PositiveInt = extendM(
+export type PositiveInt = number & PositiveIntBrand
+/** Positive integer. `.withConstructorDefault` => `1` (construction-only). */
+export interface PositiveIntSchema extends BrandedSchema<S.Int, PositiveInt> {
+  (i: number, options?: SchemaAST.ParseOptions): PositiveInt
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Int, PositiveInt>>
+}
+export const PositiveInt: PositiveIntSchema = extendM(
   S.Int.pipe(
     S.check(S.isGreaterThan(0)),
-    fromBrand(nominal<PositiveInt>(), { identifier: "PositiveInt", title: "PositiveInt", jsonSchema: {} }),
+    fromBrand<PositiveInt>(nominal<PositiveInt>(), { identifier: "PositiveInt", jsonSchema: {} }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => 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> {}
-export const NonNegativeInt = extendM(
+export type NonNegativeInt = number & NonNegativeIntBrand
+/** Non-negative integer. `.withConstructorDefault` => `0` (construction-only). */
+export interface NonNegativeIntSchema extends BrandedSchema<S.Int, NonNegativeInt> {
+  (i: number, options?: SchemaAST.ParseOptions): NonNegativeInt
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Int, NonNegativeInt>>
+}
+export const NonNegativeInt: NonNegativeIntSchema = extendM(
   S.Int.pipe(
     S.check(S.isGreaterThanOrEqualTo(0)),
-    fromBrand(nominal<NonNegativeInt>(), {
+    fromBrand<NonNegativeInt>(nominal<NonNegativeInt>(), {
       identifier: "NonNegativeInt",
-      title: "NonNegativeInt",
       jsonSchema: {}
     }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => 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">> {}
-export const Int = extendM(
-  S.Int.pipe(fromBrand(nominal<Int>(), { identifier: "Int", title: "Int", jsonSchema: {} }), withDefaultMake),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => s(0))) })
-)
 export type Int = number & IntBrand
+/** Integer. `.withConstructorDefault` => `0` (construction-only). */
+export interface IntSchema extends BrandedSchema<S.Int, Int> {
+  (i: number, options?: SchemaAST.ParseOptions): Int
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Int, Int>>
+}
+export const Int: IntSchema = extendM(
+  S.Int.pipe(fromBrand<Int>(nominal<Int>(), { identifier: "Int", jsonSchema: {} }), withDefaultMake),
+  (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 interface PositiveNumberBrand extends Simplify<B.Brand<"PositiveNumber"> & NonNegativeNumberBrand> {}
-export const PositiveNumber = extendM(
+export type PositiveNumber = number & PositiveNumberBrand
+/** Positive finite number. `.withConstructorDefault` => `1` (construction-only). */
+// Generation-only: native Arbitrary otherwise samples up to Number.MAX_VALUE, so derived totals
+// (amount x weight, sums) overflow to Infinity. Validation and JSON Schema are unaffected.
+const realisticMaximum = 1_000_000
+
+export interface PositiveNumberSchema extends BrandedSchema<S.Finite, PositiveNumber> {
+  (i: number, options?: SchemaAST.ParseOptions): PositiveNumber
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Finite, PositiveNumber>>
+}
+export const PositiveNumber: PositiveNumberSchema = extendM(
   S.Finite.pipe(
-    S.check(S.isGreaterThan(0)),
-    fromBrand(nominal<PositiveNumber>(), {
+    S.check(S.isGreaterThan(0, {
+      // the full constraint: annotations replace the check default, which carries `order` + `minimum`
+      arbitraryConstraint: { order: Order.Number, minimum: 0, exclusiveMinimum: true, maximum: realisticMaximum }
+    })),
+    fromBrand<PositiveNumber>(nominal<PositiveNumber>(), {
       identifier: "PositiveNumber",
-      title: "PositiveNumber",
       jsonSchema: {}
     }),
     withDefaultMake
   ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => 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">> {}
-export const NonNegativeNumber = extendM(
+export type NonNegativeNumber = number & NonNegativeNumberBrand
+/** Non-negative finite number. `.withConstructorDefault` => `0` (construction-only). */
+export interface NonNegativeNumberSchema extends BrandedSchema<S.Finite, NonNegativeNumber> {
+  (i: number, options?: SchemaAST.ParseOptions): NonNegativeNumber
+  readonly withConstructorDefault: S.withConstructorDefault<BrandedSchema<S.Finite, NonNegativeNumber>>
+}
+export const NonNegativeNumber: NonNegativeNumberSchema = extendM(
   S
     .Finite
     .pipe(
-      S.check(S.isGreaterThanOrEqualTo(0)),
-      fromBrand(nominal<NonNegativeNumber>(), {
+      S.check(S.isGreaterThanOrEqualTo(0, {
+        arbitraryConstraint: { order: Order.Number, minimum: 0, maximum: realisticMaximum }
+      })),
+      fromBrand<NonNegativeNumber>(nominal<NonNegativeNumber>(), {
         identifier: "NonNegativeNumber",
-        title: "NonNegativeNumber",
         jsonSchema: {}
       }),
       withDefaultMake
     ),
-  (s) => ({ withDefault: s.pipe(withDefaultConstructor(() => 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
 
 /** @deprecated Not an actual decimal */
 export const NonNegativeDecimal = NonNegativeNumber