@typed/id 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/Cuid.js

@@ -1,7 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import { sha512 } from "./_sha.js";
 import { DateTimes } from "./DateTimes.js";
 import { RandomValues } from "./RandomValues.js";
@@ -9,10 +9,57 @@ import { RandomValues } from "./RandomValues.js";
 const DEFAULT_LENGTH = 24;
 const BIG_LENGTH = 32;
 const INITIAL_COUNT_MAX = 476782367;
-// Schema
-export const Cuid = Schema.String.pipe(Schema.check(Schema.isPattern(/^[a-z][0-9a-z]+$/)), Schema.brand("@typed/id/CUID"));
+/**
+ * Effect Schema and branded string type for 24-character CUID values.
+ * @remarks
+ * ## Why
+ * The schema validates transport or persisted strings before restoring the compile-time brand; generating a new client ID is not hydration identity.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Cuid } from "@typed/id/Cuid"
+ * const id = Cuid.make("a00000000000000000000000")
+ * ```
+ * See [Effect Schema](https://effect.website/docs/schema/introduction/).
+ * @category Schemas
+ * @since 1.0.0
+ */
+export const Cuid = Schema.String.pipe(Schema.check(Schema.isPattern(/^[a-z][0-9a-z]{23}$/)), Schema.brand("@typed/id/CUID"));
+/**
+ * Tests whether a string is a valid branded CUID.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after JSON, structured clone, or other transport has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isCuid } from "@typed/id/Cuid"
+ * isCuid("a00000000000000000000000")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isCuid = Schema.is(Cuid);
-export class CuidState extends ServiceMap.Service()("@typed/id/CuidState", {
+/**
+ * Process-local Effect service that supplies sequential CUID seeds.
+ * @remarks
+ * ## Why
+ * Counter state and caller-provided `envData` live in an explicit service so tests and applications choose the sharing boundary instead of relying on hidden globals.
+ * ## Ownership and lifetime
+ * Each Layer instance owns its mutable counter and captured fingerprint. A new process, worker, or Layer resets that sequence; exact SSR identity must be serialized and reused.
+ * @example
+ * ```ts
+ * import { cuid, CuidState } from "@typed/id/Cuid"
+ * import { Effect } from "effect"
+ * const program = Effect.provide(cuid, CuidState.Default)
+ * ```
+ * See [Effect services](https://effect.website/docs/requirements-management/services/) and [Layers](https://effect.website/docs/requirements-management/layers/).
+ * @category Services
+ * @since 1.0.0
+ */
+export class CuidState extends Context.Service()("@typed/id/CuidState", {
     make: (envData) => Effect.gen(function* () {
         const { now } = yield* DateTimes;
         const getRandomValues = yield* RandomValues;
@@ -21,38 +68,72 @@ export class CuidState extends ServiceMap.Service()("@typed/id/CuidState", {
             (initialBytes[1] << 16) |
             (initialBytes[2] << 8) |
             initialBytes[3]) % INITIAL_COUNT_MAX;
-        // Create fingerprint from environment data
+        // Derive a stable discriminator from caller-provided environment data
         const fingerprint = (yield* hash(envData)).substring(0, BIG_LENGTH);
         let counter = initialValue;
-        return Effect.gen(function* () {
-            const timestamp = yield* now;
-            const random = yield* getRandomValues(32);
-            return {
-                timestamp,
-                counter: counter++,
-                random,
-                fingerprint,
-            };
-        });
+        return {
+            next: Effect.gen(function* () {
+                const timestamp = yield* now;
+                const random = yield* getRandomValues(32);
+                return {
+                    timestamp,
+                    counter: counter++,
+                    random,
+                    fingerprint,
+                };
+            }),
+        };
     }),
 }) {
-    static next = Effect.flatten(CuidState.asEffect());
-    static Default = Layer.effect(CuidState, CuidState.make("node")).pipe(Layer.provideMerge([DateTimes.Default, RandomValues.Default]));
+    /**
+     * Reads one seed from the current CuidState service.
+     * @remarks
+     * ## Why
+     * The accessor exposes stateful sequencing through Effect's service channel rather than a module-global counter.
+     * ## Ownership and lifetime
+     * The Effect requires `CuidState`; its Layer owns the counter for the Layer lifetime.
+     * @category Services
+     * @since 1.0.0
+     */
+    static next = Effect.gen(function* () {
+        const { next } = yield* CuidState;
+        return yield* next;
+    });
+    /**
+     * Provides a default CuidState backed by system time and Web Crypto entropy.
+     * @remarks
+     * ## Why
+     * The explicit Layer gives production code a standard service while keeping test and environment-specific alternatives replaceable.
+     * ## Ownership and lifetime
+     * Layer acquisition creates one counter state; the surrounding Layer Scope owns it. Web Crypto must be available in the runtime.
+     * @category Layers
+     * @since 1.0.0
+     */
+    static Default = Layer.effect(CuidState, CuidState.make("node")).pipe(Layer.provide([DateTimes.Default, RandomValues.Default]));
 }
+/**
+ * Generates one CUID from the current CuidState service.
+ * @remarks
+ * ## Why
+ * Generation is an Effect so sequencing and entropy dependencies remain explicit and replaceable; `envData` is only a caller discriminator, not a machine fingerprint guarantee. Missing Web Crypto or rejected SHA-512 work is a defect because the typed error channel is `never`.
+ * ## Ownership and lifetime
+ * The Effect acquires no resources itself and uses the CuidState owned by its provided Layer.
+ * @example
+ * ```ts
+ * import { cuid, CuidState } from "@typed/id/Cuid"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(cuid, CuidState.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const cuid = Effect.flatMap(CuidState.next, cuidFromSeed);
 // Utilities
-const ALPHABET = Array.from({ length: 26 }, (_, i) => String.fromCharCode(i + 97));
+const LETTER_ALPHABET = "abcdefghijklmnopqrstuvwxyz";
+const BODY_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+const LETTER_DOMAIN = "@typed/id/cuid/letter";
+const BODY_DOMAIN = "@typed/id/cuid/body";
 const encoder = new TextEncoder();
-function createEntropy(length, random) {
-    let entropy = "";
-    let offset = 0;
-    while (entropy.length < length) {
-        const value = random[offset];
-        entropy += Math.floor(value % 36).toString(36);
-        offset = (offset + 1) % random.length;
-    }
-    return entropy;
-}
 function hash(input) {
     return Effect.map(sha512(encoder.encode(input)), (buffer) => {
         const view = new Uint8Array(buffer);
@@ -64,20 +145,33 @@ function hash(input) {
         return value.toString(36).slice(1);
     });
 }
+function sample(domain, alphabet, length, canonicalInput) {
+    return Effect.gen(function* () {
+        const limit = Math.floor(256 / alphabet.length) * alphabet.length;
+        let value = "";
+        for (let block = 0; value.length < length; block++) {
+            const prefix = encoder.encode(`${domain}\0${block.toString(10)}\0`);
+            const input = new Uint8Array(prefix.length + canonicalInput.length);
+            input.set(prefix);
+            input.set(canonicalInput, prefix.length);
+            const digest = new Uint8Array(yield* sha512(input));
+            for (const byte of digest) {
+                if (byte >= limit)
+                    continue;
+                value += alphabet[byte % alphabet.length];
+                if (value.length === length)
+                    break;
+            }
+        }
+        return value;
+    });
+}
 function cuidFromSeed({ counter, fingerprint, random, timestamp }) {
     return Effect.gen(function* () {
-        // First letter is always a random lowercase letter from the seed
-        const firstLetter = ALPHABET[random[0] % ALPHABET.length];
-        // Convert components to base36
-        const time = timestamp.toString(36);
-        const count = counter.toString(36);
-        // Create entropy from remaining random bytes
-        const salt = createEntropy(4, random.slice(1));
-        // Hash all components together
-        const hashInput = `${time}${salt}${count}${fingerprint}`;
-        const hashed = yield* hash(hashInput);
-        // Construct the final CUID
-        const id = `${firstLetter}${hashed.substring(0, DEFAULT_LENGTH - 1)}`;
-        return Cuid.makeUnsafe(id);
+        const randomHex = Array.from(random, (byte) => byte.toString(16).padStart(2, "0")).join("");
+        const canonicalInput = encoder.encode([timestamp.toString(36), counter.toString(36), fingerprint, randomHex].join("\0"));
+        const firstLetter = yield* sample(LETTER_DOMAIN, LETTER_ALPHABET, 1, canonicalInput);
+        const body = yield* sample(BODY_DOMAIN, BODY_ALPHABET, DEFAULT_LENGTH - 1, canonicalInput);
+        return Cuid.make(firstLetter + body);
     });
 }

package/dist/DateTimes.d.ts

@@ -1,7 +1,8 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as ServiceMap from "effect/ServiceMap";
-declare const DateTimes_base: ServiceMap.ServiceClass<DateTimes, "@typed/id/DateTimes", {
+import * as Context from "effect/Context";
+declare const DateTimes_base: Context.ServiceClass<DateTimes, "@typed/id/DateTimes", {
     now: Effect.Effect<number, never, never>;
     date: Effect.Effect<Date, never, never>;
 }> & {
@@ -10,11 +11,73 @@ declare const DateTimes_base: ServiceMap.ServiceClass<DateTimes, "@typed/id/Date
         date: Effect.Effect<Date, never, never>;
     }, never, never>;
 };
+/**
+ * Effect service for current epoch milliseconds and Date values.
+ * @remarks
+ * ## Why
+ * Making time a service keeps time-based ID generators deterministic under tests and explicit under server or browser runtimes.
+ * ## Ownership and lifetime
+ * A DateTimes Layer owns its time source for the Layer lifetime; individual reads acquire no resources.
+ * @example
+ * ```ts
+ * import { DateTimes } from "@typed/id/DateTimes"
+ * import { Effect } from "effect"
+ * const now = Effect.provide(DateTimes.now, DateTimes.Default)
+ * ```
+ * See [Effect Clock](https://effect.website/docs/testing/testclock/).
+ * @category Services
+ * @since 1.0.0
+ */
 export declare class DateTimes extends DateTimes_base {
+    /**
+     * Reads epoch milliseconds from the current DateTimes service.
+     * @remarks
+     * ## Why
+     * A service-backed read avoids hard-wiring `Date.now` into generators and tests.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses the DateTimes service for one invocation.
+     * @category Services
+     * @since 1.0.0
+     */
     static readonly now: Effect.Effect<number, never, DateTimes>;
+    /**
+     * Reads a Date from the current DateTimes service.
+     * @remarks
+     * ## Why
+     * The Date view stays aligned with the same replaceable time source as epoch-millisecond reads.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses the DateTimes service for one invocation.
+     * @category Services
+     * @since 1.0.0
+     */
     static readonly date: Effect.Effect<Date, never, DateTimes>;
+    /**
+     * Provides DateTimes using the runtime wall clock.
+     * @remarks
+     * ## Why
+     * The production default is explicit and replaceable rather than hidden in each generator.
+     * ## Ownership and lifetime
+     * The surrounding Layer Scope owns the service; reads allocate only their returned Date values.
+     * @category Layers
+     * @since 1.0.0
+     */
     static readonly Default: Layer.Layer<DateTimes, never, never>;
-    static readonly Fixed: (baseDate: number | string | Date) => Layer.Layer<DateTimes, never, never>;
+    /**
+     * Provides DateTimes anchored to a base date and advanced by Effect Clock.
+     * @remarks
+     * ## Why
+     * Clock-relative time supports deterministic tests while still allowing controlled advancement; invalid bases fail with `IllegalArgumentError`.
+     * ## Ownership and lifetime
+     * Layer acquisition captures the base and current Clock reading; the surrounding Layer Scope owns that state.
+     * @example
+     * ```ts
+     * import { DateTimes } from "@typed/id/DateTimes"
+     * const fixed = DateTimes.Fixed("2026-01-01T00:00:00Z")
+     * ```
+     * @category Layers
+     * @since 1.0.0
+     */
+    static readonly Fixed: (baseDate: number | string | Date) => Layer.Layer<DateTimes, Cause.IllegalArgumentError, never>;
 }
 export {};
 //# sourceMappingURL=DateTimes.d.ts.map

package/dist/DateTimes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DateTimes.d.ts","sourceRoot":"","sources":["../src/DateTimes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;;;;;;;;;;AAEhD,qBAAa,SAAU,SAAQ,cAK7B;IACA,MAAM,CAAC,QAAQ,CAAC,GAAG,0CAA0D;IAC7E,MAAM,CAAC,QAAQ,CAAC,IAAI,wCAA4D;IAEhF,MAAM,CAAC,QAAQ,CAAC,OAAO,uCAA2C;IAElE,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAI,UAAU,MAAM,GAAG,MAAM,GAAG,IAAI,0CAkBrD;CACL"}
+{"version":3,"file":"DateTimes.d.ts","sourceRoot":"","sources":["../src/DateTimes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;;;;;;;;;;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,SAAQ,cAK7B;IACA;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,0CAA+C;IAClE;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,wCAAiD;IAErE;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,uCAA2C;IAElE;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,aAAc,MAAM,GAAG,MAAM,GAAG,IAAI,+DAsBrD;CACL"}

package/dist/DateTimes.js

@@ -1,20 +1,87 @@
 import * as Clock from "effect/Clock";
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as ServiceMap from "effect/ServiceMap";
-export class DateTimes extends ServiceMap.Service()("@typed/id/DateTimes", {
+import * as Context from "effect/Context";
+/**
+ * Effect service for current epoch milliseconds and Date values.
+ * @remarks
+ * ## Why
+ * Making time a service keeps time-based ID generators deterministic under tests and explicit under server or browser runtimes.
+ * ## Ownership and lifetime
+ * A DateTimes Layer owns its time source for the Layer lifetime; individual reads acquire no resources.
+ * @example
+ * ```ts
+ * import { DateTimes } from "@typed/id/DateTimes"
+ * import { Effect } from "effect"
+ * const now = Effect.provide(DateTimes.now, DateTimes.Default)
+ * ```
+ * See [Effect Clock](https://effect.website/docs/testing/testclock/).
+ * @category Services
+ * @since 1.0.0
+ */
+export class DateTimes extends Context.Service()("@typed/id/DateTimes", {
     make: Effect.succeed({
         now: Effect.sync(() => Date.now()),
         date: Effect.sync(() => new Date()),
     }),
 }) {
-    static now = Effect.flatMap(DateTimes.asEffect(), ({ now }) => now);
-    static date = Effect.flatMap(DateTimes.asEffect(), ({ date }) => date);
+    /**
+     * Reads epoch milliseconds from the current DateTimes service.
+     * @remarks
+     * ## Why
+     * A service-backed read avoids hard-wiring `Date.now` into generators and tests.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses the DateTimes service for one invocation.
+     * @category Services
+     * @since 1.0.0
+     */
+    static now = Effect.flatMap(DateTimes, ({ now }) => now);
+    /**
+     * Reads a Date from the current DateTimes service.
+     * @remarks
+     * ## Why
+     * The Date view stays aligned with the same replaceable time source as epoch-millisecond reads.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses the DateTimes service for one invocation.
+     * @category Services
+     * @since 1.0.0
+     */
+    static date = Effect.flatMap(DateTimes, ({ date }) => date);
+    /**
+     * Provides DateTimes using the runtime wall clock.
+     * @remarks
+     * ## Why
+     * The production default is explicit and replaceable rather than hidden in each generator.
+     * ## Ownership and lifetime
+     * The surrounding Layer Scope owns the service; reads allocate only their returned Date values.
+     * @category Layers
+     * @since 1.0.0
+     */
     static Default = Layer.effect(DateTimes, DateTimes.make);
+    /**
+     * Provides DateTimes anchored to a base date and advanced by Effect Clock.
+     * @remarks
+     * ## Why
+     * Clock-relative time supports deterministic tests while still allowing controlled advancement; invalid bases fail with `IllegalArgumentError`.
+     * ## Ownership and lifetime
+     * Layer acquisition captures the base and current Clock reading; the surrounding Layer Scope owns that state.
+     * @example
+     * ```ts
+     * import { DateTimes } from "@typed/id/DateTimes"
+     * const fixed = DateTimes.Fixed("2026-01-01T00:00:00Z")
+     * ```
+     * @category Layers
+     * @since 1.0.0
+     */
     static Fixed = (baseDate) => Layer.effect(DateTimes, Effect.gen(function* () {
         const clock = yield* Clock.Clock;
         const base = new Date(baseDate);
-        const baseN = BigInt(base.getTime());
+        const baseMillis = base.getTime();
+        if (!Number.isFinite(baseMillis)) {
+            return yield* new Cause.IllegalArgumentError(`Invalid base date: ${String(baseDate)}`);
+        }
+        const baseN = BigInt(baseMillis);
         const startMillis = yield* clock.currentTimeMillis;
         const now = clock.currentTimeMillis.pipe(Effect.map((millis) => 
         // Use BigInt to avoid floating point precision issues which can break deterministic testing

package/dist/Ids.d.ts

@@ -1,6 +1,7 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as ServiceMap from "effect/ServiceMap";
+import * as Context from "effect/Context";
 import type { Cuid } from "./Cuid.js";
 import { CuidState } from "./Cuid.js";
 import { DateTimes } from "./DateTimes.js";
@@ -13,59 +14,201 @@ import { type Uuid5, Uuid5Namespace } from "./Uuid5.js";
 import type { Uuid7 } from "./Uuid7.js";
 import { Uuid7State } from "./Uuid7.js";
 import { TestClock } from "effect/testing";
-declare const Ids_base: ServiceMap.ServiceClass<Ids, "@typed/id/Ids", {
+declare const Ids_base: Context.ServiceClass<Ids, "@typed/id/Ids", {
     cuid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/CUID">, never, never>;
-    ksuid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/KSUID">, never, never>;
+    ksuid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/KSUID">, Cause.IllegalArgumentError, never>;
     nanoId: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/NanoId">, never, never>;
-    ulid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/ULID">, never, never>;
+    ulid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/ULID">, Cause.IllegalArgumentError, never>;
     uuid4: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/UUID4">, never, never>;
     uuid5: {
-        (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5>;
-        (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5>;
-        readonly dns: (name: string) => Effect.Effect<Uuid5>;
-        readonly url: (name: string) => Effect.Effect<Uuid5>;
-        readonly oid: (name: string) => Effect.Effect<Uuid5>;
-        readonly x500: (name: string) => Effect.Effect<Uuid5>;
+        (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+        (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+        readonly dns: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+        readonly url: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+        readonly oid: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+        readonly x500: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
     };
-    uuid7: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/UUID7">, never, never>;
+    uuid7: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/UUID7">, Cause.IllegalArgumentError, never>;
 }> & {
     readonly make: Effect.Effect<{
         cuid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/CUID">, never, never>;
-        ksuid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/KSUID">, never, never>;
+        ksuid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/KSUID">, Cause.IllegalArgumentError, never>;
         nanoId: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/NanoId">, never, never>;
-        ulid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/ULID">, never, never>;
+        ulid: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/ULID">, Cause.IllegalArgumentError, never>;
         uuid4: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/UUID4">, never, never>;
         uuid5: {
-            (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5>;
-            (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5>;
-            readonly dns: (name: string) => Effect.Effect<Uuid5>;
-            readonly url: (name: string) => Effect.Effect<Uuid5>;
-            readonly oid: (name: string) => Effect.Effect<Uuid5>;
-            readonly x500: (name: string) => Effect.Effect<Uuid5>;
+            (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+            (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+            readonly dns: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+            readonly url: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+            readonly oid: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
+            readonly x500: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError>;
         };
-        uuid7: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/UUID7">, never, never>;
+        uuid7: Effect.Effect<string & import("effect/Brand").Brand<"@typed/id/UUID7">, Cause.IllegalArgumentError, never>;
     }, never, CuidState | DateTimes | RandomValues | Uuid7State>;
 };
+/**
+ * Unified Effect service for every Typed ID generator.
+ * @remarks
+ * ## Why
+ * One facade captures time, entropy, and state services once, so application code composes generators through a single explicit dependency without hiding their behavior.
+ * ## Ownership and lifetime
+ * Each Ids Layer owns its captured services plus lazy CUID and UUIDv7 state. Recreating the Layer resets process-local sequences; serialize server IDs when identity must survive hydration.
+ * @example
+ * ```ts
+ * import { Ids } from "@typed/id/Ids"
+ * import { Effect } from "effect"
+ * const program = Effect.gen(function* () { return yield* Ids.uuid7 }).pipe(Effect.provide(Ids.Default))
+ * ```
+ * See [Effect services](https://effect.website/docs/requirements-management/services/) and [Layers](https://effect.website/docs/requirements-management/layers/).
+ * @category Services
+ * @since 1.0.0
+ */
 export declare class Ids extends Ids_base {
+    /**
+     * Generates a CUID using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade shares the Ids-owned CuidState instead of allocating a new sequence for every call.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses state owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
     static readonly cuid: Effect.Effect<Cuid, never, Ids>;
-    static readonly ksuid: Effect.Effect<Ksuid, never, Ids>;
+    /**
+     * Generates a KSUID using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade reuses captured time and entropy while retaining `IllegalArgumentError` for invalid KSUID timestamps.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses services owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static readonly ksuid: Effect.Effect<Ksuid, Cause.IllegalArgumentError, Ids>;
+    /**
+     * Generates a NanoId using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade makes the selected entropy implementation available through one application dependency.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses entropy owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
     static readonly nanoId: Effect.Effect<NanoId, never, Ids>;
-    static readonly ulid: Effect.Effect<Ulid, never, Ids>;
+    /**
+     * Generates a ULID using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade reuses captured time and entropy while retaining `IllegalArgumentError` for invalid 48-bit timestamps.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses services owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static readonly ulid: Effect.Effect<Ulid, Cause.IllegalArgumentError, Ids>;
+    /**
+     * Generates a random UUID version 4 using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade keeps entropy selection replaceable while preserving UUID version and variant semantics.
+     * ## Ownership and lifetime
+     * This Effect acquires no persistent resource and uses entropy owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
     static readonly uuid4: Effect.Effect<Uuid4, never, Ids>;
+    /**
+     * Derives deterministic UUID version 5 values through the current Ids service, with DNS, URL, OID, and X.500 helpers.
+     * @remarks
+     * ## Why
+     * The facade supports data-first and namespace-first calls while keeping namespace choice and `IllegalArgumentError` explicit.
+     * ## Ownership and lifetime
+     * Each Effect acquires no persistent resources and reads the Ids service for one invocation; helper namespaces are stable captured copies.
+     * @example
+     * ```ts
+     * import { Ids } from "@typed/id/Ids"
+     * import { Effect } from "effect"
+     * const program = Ids.uuid5.dns("example.com").pipe(Effect.provide(Ids.Default))
+     * ```
+     * @category Generators
+     * @since 1.0.0
+     */
     static readonly uuid5: {
-        (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5, never, Ids>;
-        (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5, never, Ids>;
-        readonly dns: (name: string) => Effect.Effect<Uuid5, never, Ids>;
-        readonly url: (name: string) => Effect.Effect<Uuid5, never, Ids>;
-        readonly oid: (name: string) => Effect.Effect<Uuid5, never, Ids>;
-        readonly x500: (name: string) => Effect.Effect<Uuid5, never, Ids>;
+        /** Binds a namespace first, then derives UUIDv5 values for names. @since 1.0.0 */
+        (namespace: Uuid5Namespace): (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError, Ids>;
+        /** Derives a UUIDv5 from a name and namespace through the current Ids service. @since 1.0.0 */
+        (name: string, namespace: Uuid5Namespace): Effect.Effect<Uuid5, Cause.IllegalArgumentError, Ids>;
+        /** Derives a UUIDv5 in the standard DNS namespace. @since 1.0.0 */
+        readonly dns: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError, Ids>;
+        /** Derives a UUIDv5 in the standard URL namespace. @since 1.0.0 */
+        readonly url: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError, Ids>;
+        /** Derives a UUIDv5 in the standard OID namespace. @since 1.0.0 */
+        readonly oid: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError, Ids>;
+        /** Derives a UUIDv5 in the standard X.500 namespace. @since 1.0.0 */
+        readonly x500: (name: string) => Effect.Effect<Uuid5, Cause.IllegalArgumentError, Ids>;
     };
-    static readonly uuid7: Effect.Effect<Uuid7, never, Ids>;
+    /**
+     * Generates a UUID version 7 using the current Ids service.
+     * @remarks
+     * ## Why
+     * The facade shares one lazy Uuid7State per Ids Layer, preserving local monotonicity and typed timestamp errors.
+     * ## Ownership and lifetime
+     * This Effect acquires no resources and uses sequence state owned by the provided Ids Layer.
+     * @category Generators
+     * @since 1.0.0
+     */
+    static readonly uuid7: Effect.Effect<Uuid7, Cause.IllegalArgumentError, Ids>;
+    /**
+     * Provides production Ids, DateTimes, and RandomValues services.
+     * @remarks
+     * ## Why
+     * The standard Layer uses system time and Web Crypto while lazily creating sequence state only when CUID or UUIDv7 is first requested.
+     * ## Ownership and lifetime
+     * The surrounding Layer Scope owns captured services and lazy sequence state; Web Crypto must exist in the runtime.
+     * @category Layers
+     * @since 1.0.0
+     */
     static readonly Default: Layer.Layer<Ids | DateTimes | RandomValues, never, never>;
-    static readonly Test: (options?: TestOptions) => Layer.Layer<Ids | DateTimes | RandomValues | TestClock.TestClock>;
+    /**
+     * Provides deterministic Ids, time, entropy, and TestClock services.
+     * @remarks
+     * ## Why
+     * Reproducible generators make exact sequences testable; the deterministic entropy is for tests and simulations, not security.
+     * ## Ownership and lifetime
+     * Each Layer construction owns an independent clock, random sequence, and lazy CUID/UUIDv7 state for its Scope.
+     * @example
+     * ```ts
+     * import { Ids } from "@typed/id/Ids"
+     * import { Effect } from "effect"
+     * const deterministic = Ids.uuid7.pipe(Effect.provide(Ids.Test({ currentTime: 0 })))
+     * ```
+     * @category Testing
+     * @since 1.0.0
+     */
+    static readonly Test: (options?: TestOptions) => Layer.Layer<Ids | DateTimes | RandomValues | TestClock.TestClock, Cause.IllegalArgumentError>;
 }
+/**
+ * Configuration for the deterministic Ids test Layer.
+ * @remarks
+ * ## Why
+ * Explicit initial time and CUID environment data let tests reproduce generator sequences without ambient process state.
+ * ## Ownership and lifetime
+ * This plain configuration acquires no resources and is read only by Layer acquisition; TypeScript `readonly` does not freeze it at runtime.
+ * @example
+ * ```ts
+ * import type { TestOptions } from "@typed/id/Ids"
+ * const options: TestOptions = { currentTime: "2026-01-01T00:00:00Z", envData: "test-worker" }
+ * ```
+ * @category Testing
+ * @since 1.0.0
+ */
 export type TestOptions = {
+    /** Base time passed to `DateTimes.Fixed`; invalid dates fail Layer acquisition. @since 1.0.0 */
     readonly currentTime?: number | string | Date;
+    /** CUID caller discriminator used when the test CuidState is created. @since 1.0.0 */
     readonly envData?: string;
 };
 export {};