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

package/dist/Uuid5.js

@@ -1,28 +1,105 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import { dual } from "effect/Function";
 import * as Schema from "effect/Schema";
 import { sha1 } from "./_sha.js";
 import { uuidStringify } from "./_uuid-stringify.js";
+/**
+ * Effect Schema and branded string type for RFC UUID version 5 values.
+ * @remarks
+ * ## Why
+ * The schema verifies UUID version and variant at transport boundaries before restoring the compile-time brand.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Uuid5 } from "@typed/id/Uuid5"
+ * import { Schema } from "effect"
+ * const id = Schema.decodeUnknownSync(Uuid5)("21f7f8de-8051-5b89-8680-0195ef798b6a")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export const Uuid5 = Schema.String.pipe(Schema.check(Schema.isUUID(5)), Schema.brand("@typed/id/UUID5"));
+/**
+ * Tests whether a string is an RFC UUID version 5 value.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUuid5 } from "@typed/id/Uuid5"
+ * isUuid5("21f7f8de-8051-5b89-8680-0195ef798b6a")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isUuid5 = Schema.is(Uuid5);
 const textEncoder = new TextEncoder();
 // Pre-defined namespaces from RFC 4122
-export const Uuid5Namespace = {
-    DNS: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-    URL: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-    OID: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x12, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-    X500: new Uint8Array([
-        0x6b, 0xa7, 0xb8, 0x14, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-    ]),
-};
+const DNS = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+const URL = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+const OID = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x12, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+const X500 = new Uint8Array([
+    0x6b, 0xa7, 0xb8, 0x14, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
+]);
+/**
+ * Standard RFC UUID version 5 namespaces, returned as fresh mutable copies.
+ * @remarks
+ * ## Why
+ * Copy-on-access protects canonical constants while allowing callers to own and safely modify their selected namespace bytes.
+ * ## Ownership and lifetime
+ * The module owns canonical bytes for its lifetime; every property access transfers a fresh 16-byte copy to the caller.
+ * @example
+ * ```ts
+ * import { Uuid5Namespace } from "@typed/id/Uuid5"
+ * const namespace = Uuid5Namespace.DNS
+ * ```
+ * @category Namespaces
+ * @since 1.0.0
+ */
+export const Uuid5Namespace = Object.freeze({
+    get DNS() {
+        return DNS.slice(0);
+    },
+    get URL() {
+        return URL.slice(0);
+    },
+    get OID() {
+        return OID.slice(0);
+    },
+    get X500() {
+        return X500.slice(0);
+    },
+});
+/**
+ * Derives a deterministic UUID version 5 from a UTF-8 name and 16-byte namespace.
+ * @remarks
+ * ## Why
+ * Determinism is exact for the same name bytes and namespace. Invalid namespace length fails in the typed channel with `IllegalArgumentError`; missing Web Crypto or a rejected SHA-1 digest is an Effect defect, not a typed error.
+ * ## Ownership and lifetime
+ * Each Effect acquires no persistent resources, reads but does not retain the namespace, and uses Web Crypto `subtle.digest` for the invocation.
+ * @example
+ * ```ts
+ * import { uuid5, Uuid5Namespace } from "@typed/id/Uuid5"
+ * const id = uuid5("example.com", Uuid5Namespace.DNS)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const uuid5 = dual(2, function uuid5(name, namespace) {
     return Effect.gen(function* () {
+        if (namespace.length !== 16) {
+            return yield* new Cause.IllegalArgumentError(`UUIDv5 namespace must contain exactly 16 bytes, received ${namespace.length}`);
+        }
         // Convert name to UTF-8 bytes
         const nameBytes = textEncoder.encode(name);
         // Concatenate namespace and name
@@ -38,10 +115,70 @@ export const uuid5 = dual(2, function uuid5(name, namespace) {
         // Set version (5) and variant bits
         result[6] = (result[6] & 0x0f) | 0x50; // version 5
         result[8] = (result[8] & 0x3f) | 0x80; // variant 1
-        return Uuid5.makeUnsafe(uuidStringify(result));
+        return Uuid5.make(uuidStringify(result));
     });
 });
+/**
+ * Derives deterministic UUID version 5 values in the standard DNS namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for DNS identities.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { dnsUuid5 } from "@typed/id/Uuid5"
+ * const id = dnsUuid5("example.com")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const dnsUuid5 = uuid5(Uuid5Namespace.DNS);
+/**
+ * Derives deterministic UUID version 5 values in the standard URL namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for URL identities.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { urlUuid5 } from "@typed/id/Uuid5"
+ * const id = urlUuid5("https://example.com")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const urlUuid5 = uuid5(Uuid5Namespace.URL);
+/**
+ * Derives deterministic UUID version 5 values in the standard OID namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for object identifiers.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { oidUuid5 } from "@typed/id/Uuid5"
+ * const id = oidUuid5("1.3.6.1.4.1")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const oidUuid5 = uuid5(Uuid5Namespace.OID);
+/**
+ * Derives deterministic UUID version 5 values in the standard X.500 namespace.
+ * @remarks
+ * ## Why
+ * The pre-bound helper prevents accidental namespace selection drift for X.500 identities.
+ * ## Ownership and lifetime
+ * This function acquires no persistent resources and uses a captured namespace copy for module lifetime.
+ * @example
+ * ```ts
+ * import { x500Uuid5 } from "@typed/id/Uuid5"
+ * const id = x500Uuid5("CN=example")
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const x500Uuid5 = uuid5(Uuid5Namespace.X500);

package/dist/Uuid7.d.ts

@@ -1,44 +1,150 @@
+import * as Cause from "effect/Cause";
 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 { DateTimes } from "./DateTimes.js";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for RFC UUID version 7 values.
+ * @remarks
+ * ## Why
+ * The schema verifies version and variant at transport boundaries; generated ordering is local to one Uuid7State, not a distributed total order.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Uuid7 } from "@typed/id/Uuid7"
+ * import { Schema } from "effect"
+ * const id = Schema.decodeUnknownSync(Uuid7)("01890f2e-7d6c-7cc0-98c4-dc0c0c07398f")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export declare const Uuid7: Schema.brand<Schema.String, "@typed/id/UUID7">;
 export type Uuid7 = typeof Uuid7.Type;
+/**
+ * Tests whether a string is an RFC UUID version 7 value.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUuid7 } from "@typed/id/Uuid7"
+ * const valid = isUuid7("01890f2e-7d6c-7cc0-98c4-dc0c0c07398f")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export declare const isUuid7: (value: string) => value is Uuid7;
+/**
+ * The validated time, sequence, and entropy used to format one UUID version 7.
+ * @remarks
+ * ## Why
+ * An explicit seed documents the exact inputs to version and variant bit layout and makes generator state testable.
+ * ## Ownership and lifetime
+ * This data acquires no resources; the producing service owns sequence state and transfers a fresh random byte array.
+ * @example
+ * ```ts
+ * import type { Uuid7Seed } from "@typed/id/Uuid7"
+ * const seed: Uuid7Seed = { timestamp: 0, seq: 0, randomBytes: new Uint8Array(16) as Uuid7Seed["randomBytes"] }
+ * ```
+ * @category Models
+ * @since 1.0.0
+ */
 export type Uuid7Seed = {
+    /** Validated millisecond timestamp encoded into the UUID. @since 1.0.0 */
     readonly timestamp: number;
+    /** Unsigned 32-bit sequence integer in the range [0, 0xffffffff]. @since 1.0.0 */
     readonly seq: number;
+    /** Fresh entropy buffer whose final bytes complete the UUID payload. @since 1.0.0 */
     readonly randomBytes: Uint8Array & {
         length: 16;
     };
 };
-declare const Uuid7State_base: ServiceMap.ServiceClass<Uuid7State, "@typed/id/Uuid7State", Effect.Effect<{
-    timestamp: number;
-    seq: number;
-    randomBytes: Uint8Array<ArrayBufferLike> & {
-        length: 16;
-    };
-}, never, never>> & {
-    readonly make: Effect.Effect<Effect.Effect<{
+declare const Uuid7State_base: Context.ServiceClass<Uuid7State, "@typed/id/Uuid7State", {
+    next: Effect.Effect<{
         timestamp: number;
         seq: number;
         randomBytes: Uint8Array<ArrayBufferLike> & {
-            length: 16;
+            readonly length: 16;
         };
-    }, never, never>, never, DateTimes | RandomValues>;
+    }, Cause.IllegalArgumentError, never>;
+}> & {
+    readonly make: Effect.Effect<{
+        next: Effect.Effect<{
+            timestamp: number;
+            seq: number;
+            randomBytes: Uint8Array<ArrayBufferLike> & {
+                readonly length: 16;
+            };
+        }, Cause.IllegalArgumentError, never>;
+    }, never, DateTimes | RandomValues>;
 };
+/**
+ * Process-local Effect service that produces monotonic UUID version 7 seeds.
+ * @remarks
+ * ## Why
+ * Clock rollback and 32-bit sequence rollover are handled inside an explicit service, guaranteeing monotonicity only for one shared service instance.
+ * ## Ownership and lifetime
+ * Each Layer instance owns mutable timestamp and sequence state. A new process, worker, deployment, or Layer resets it; exact hydration identity must be serialized.
+ * @example
+ * ```ts
+ * import { uuid7, Uuid7State } from "@typed/id/Uuid7"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(uuid7, Uuid7State.Default)
+ * ```
+ * @category Services
+ * @since 1.0.0
+ */
 export declare class Uuid7State extends Uuid7State_base {
+    /**
+     * Reads the next validated seed from the current Uuid7State.
+     * @remarks
+     * ## Why
+     * The accessor exposes ordered state through Effect's service channel and reports timestamp exhaustion as `IllegalArgumentError`.
+     * ## Ownership and lifetime
+     * The Effect uses the state owned by its provided Layer and acquires no separate persistent resource.
+     * @category Services
+     * @since 1.0.0
+     */
     static readonly next: Effect.Effect<{
         timestamp: number;
         seq: number;
         randomBytes: Uint8Array<ArrayBufferLike> & {
-            length: 16;
+            readonly length: 16;
         };
-    }, never, Uuid7State>;
-    static readonly Default: Layer.Layer<DateTimes | RandomValues | Uuid7State, never, never>;
+    }, Cause.IllegalArgumentError, Uuid7State>;
+    /**
+     * Provides Uuid7State from system time and Web Crypto entropy.
+     * @remarks
+     * ## Why
+     * The production default is explicit while remaining replaceable by deterministic service layers.
+     * ## Ownership and lifetime
+     * Layer acquisition creates one mutable sequence state owned by the surrounding Layer Scope.
+     * @category Layers
+     * @since 1.0.0
+     */
+    static readonly Default: Layer.Layer<Uuid7State, never, never>;
 }
-export declare const uuid7: Effect.Effect<Uuid7, never, Uuid7State>;
+/**
+ * Generates one UUID version 7 from the current Uuid7State.
+ * @remarks
+ * ## Why
+ * Effectful generation makes the state boundary explicit and preserves `IllegalArgumentError` for invalid or exhausted timestamp space.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resource and uses state owned by the provided Uuid7State Layer.
+ * @example
+ * ```ts
+ * import { uuid7, Uuid7State } from "@typed/id/Uuid7"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(uuid7, Uuid7State.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
+export declare const uuid7: Effect.Effect<Uuid7, Cause.IllegalArgumentError, Uuid7State>;
 export {};
 //# sourceMappingURL=Uuid7.d.ts.map

package/dist/Uuid7.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Uuid7.d.ts","sourceRoot":"","sources":["../src/Uuid7.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,KAAK,gDAGjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC,eAAO,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,KAAwB,CAAC;AAE3E,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC;CACnD,CAAC;;;;;gBAD6C,EAAE;;;;;;;oBAAF,EAAE;;;;AAGjD,qBAAa,UAAW,SAAQ,eAkC9B;IACA,MAAM,CAAC,QAAQ,CAAC,IAAI;;;;oBAtCyB,EAAE;;0BAsCc;IAE7D,MAAM,CAAC,QAAQ,CAAC,OAAO,mEAErB;CACH;AAED,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAGzD,CAAC"}
+{"version":3,"file":"Uuid7.d.ts","sourceRoot":"","sources":["../src/Uuid7.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,gDAGjB,CAAC;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,KAAwB,CAAC;AAE3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC;CACnD,CAAC;;;;;;;;;;;;;;;;;;;;AAIF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAW,SAAQ,eA8D9B;IACA;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI;;;;;;+CAGjB;IAEH;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,wCAErB;CACH;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,oBAAoB,EAAE,UAAU,CAG9E,CAAC"}

package/dist/Uuid7.js

@@ -1,13 +1,62 @@
+import * as Cause from "effect/Cause";
 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 { uuidStringify } from "./_uuid-stringify.js";
 import { DateTimes } from "./DateTimes.js";
 import { RandomValues } from "./RandomValues.js";
+/**
+ * Effect Schema and branded string type for RFC UUID version 7 values.
+ * @remarks
+ * ## Why
+ * The schema verifies version and variant at transport boundaries; generated ordering is local to one Uuid7State, not a distributed total order.
+ * ## Ownership and lifetime
+ * This module-level schema value acquires no resources and is shared; no runtime freezing guarantee is implied.
+ * @example
+ * ```ts
+ * import { Uuid7 } from "@typed/id/Uuid7"
+ * import { Schema } from "effect"
+ * const id = Schema.decodeUnknownSync(Uuid7)("01890f2e-7d6c-7cc0-98c4-dc0c0c07398f")
+ * ```
+ * @category Schemas
+ * @since 1.0.0
+ */
 export const Uuid7 = Schema.String.pipe(Schema.check(Schema.isUUID(7)), Schema.brand("@typed/id/UUID7"));
+/**
+ * Tests whether a string is an RFC UUID version 7 value.
+ * @remarks
+ * ## Why
+ * Runtime refinement restores trust after serialization has erased the TypeScript brand.
+ * ## Ownership and lifetime
+ * This pure predicate acquires no resources and retains no input.
+ * @example
+ * ```ts
+ * import { isUuid7 } from "@typed/id/Uuid7"
+ * const valid = isUuid7("01890f2e-7d6c-7cc0-98c4-dc0c0c07398f")
+ * ```
+ * @category Refinements
+ * @since 1.0.0
+ */
 export const isUuid7 = Schema.is(Uuid7);
-export class Uuid7State extends ServiceMap.Service()("@typed/id/Uuid7State", {
+const maximumTimestamp = 2 ** 48 - 1;
+/**
+ * Process-local Effect service that produces monotonic UUID version 7 seeds.
+ * @remarks
+ * ## Why
+ * Clock rollback and 32-bit sequence rollover are handled inside an explicit service, guaranteeing monotonicity only for one shared service instance.
+ * ## Ownership and lifetime
+ * Each Layer instance owns mutable timestamp and sequence state. A new process, worker, deployment, or Layer resets it; exact hydration identity must be serialized.
+ * @example
+ * ```ts
+ * import { uuid7, Uuid7State } from "@typed/id/Uuid7"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(uuid7, Uuid7State.Default)
+ * ```
+ * @category Services
+ * @since 1.0.0
+ */
+export class Uuid7State extends Context.Service()("@typed/id/Uuid7State", {
     make: Effect.gen(function* () {
         const { now } = yield* DateTimes;
         const getRandomValues = yield* RandomValues;
@@ -16,33 +65,92 @@ export class Uuid7State extends ServiceMap.Service()("@typed/id/Uuid7State", {
             seq: 0,
         };
         function updateV7State(now, randomBytes) {
+            let msecs;
+            let seq;
             if (now > state.msecs) {
                 // Time has moved on! Pick a new random sequence number
-                state.seq =
-                    (randomBytes[6] << 23) | (randomBytes[7] << 16) | (randomBytes[8] << 8) | randomBytes[9];
-                state.msecs = now;
+                seq =
+                    ((randomBytes[6] << 24) |
+                        (randomBytes[7] << 16) |
+                        (randomBytes[8] << 8) |
+                        randomBytes[9]) >>>
+                        0;
+                msecs = now;
             }
             else {
                 // Bump sequence counter w/ 32-bit rollover
-                state.seq = (state.seq + 1) | 0;
+                seq = (state.seq + 1) >>> 0;
+                msecs = state.msecs;
                 // In case of rollover, bump timestamp to preserve monotonicity. This is
                 // allowed by the RFC and should self-correct as the system clock catches
                 // up. See https://www.rfc-editor.org/rfc/rfc9562.html#section-6.2-9.4
-                if (state.seq === 0) {
-                    state.msecs++;
+                if (seq === 0) {
+                    msecs++;
                 }
             }
+            state.msecs = msecs;
+            state.seq = seq;
         }
-        return Effect.gen(function* () {
-            const randomBytes = yield* getRandomValues(16);
-            updateV7State(yield* now, randomBytes);
-            return { timestamp: state.msecs, seq: state.seq, randomBytes };
-        });
+        return {
+            next: Effect.gen(function* () {
+                const timestamp = yield* now;
+                if (!Number.isSafeInteger(timestamp) || timestamp < 0 || timestamp > maximumTimestamp) {
+                    return yield* new Cause.IllegalArgumentError(`UUIDv7 timestamp must be a safe integer between 0 and ${maximumTimestamp}, received ${timestamp}`);
+                }
+                if (timestamp <= state.msecs &&
+                    state.msecs === maximumTimestamp &&
+                    state.seq === 0xffffffff) {
+                    return yield* new Cause.IllegalArgumentError("UUIDv7 sequence rollover exceeds its 48-bit timestamp field");
+                }
+                const randomBytes = yield* getRandomValues(16);
+                updateV7State(timestamp, randomBytes);
+                return { timestamp: state.msecs, seq: state.seq, randomBytes };
+            }),
+        };
     }),
 }) {
-    static next = Effect.flatten(Uuid7State.asEffect());
-    static Default = Layer.effect(Uuid7State, Uuid7State.make).pipe(Layer.provideMerge([DateTimes.Default, RandomValues.Default]));
+    /**
+     * Reads the next validated seed from the current Uuid7State.
+     * @remarks
+     * ## Why
+     * The accessor exposes ordered state through Effect's service channel and reports timestamp exhaustion as `IllegalArgumentError`.
+     * ## Ownership and lifetime
+     * The Effect uses the state owned by its provided Layer and acquires no separate persistent resource.
+     * @category Services
+     * @since 1.0.0
+     */
+    static next = Effect.gen(function* () {
+        const { next } = yield* Uuid7State;
+        return yield* next;
+    });
+    /**
+     * Provides Uuid7State from system time and Web Crypto entropy.
+     * @remarks
+     * ## Why
+     * The production default is explicit while remaining replaceable by deterministic service layers.
+     * ## Ownership and lifetime
+     * Layer acquisition creates one mutable sequence state owned by the surrounding Layer Scope.
+     * @category Layers
+     * @since 1.0.0
+     */
+    static Default = Layer.effect(Uuid7State, Uuid7State.make).pipe(Layer.provide([DateTimes.Default, RandomValues.Default]));
 }
+/**
+ * Generates one UUID version 7 from the current Uuid7State.
+ * @remarks
+ * ## Why
+ * Effectful generation makes the state boundary explicit and preserves `IllegalArgumentError` for invalid or exhausted timestamp space.
+ * ## Ownership and lifetime
+ * The Effect acquires no persistent resource and uses state owned by the provided Uuid7State Layer.
+ * @example
+ * ```ts
+ * import { uuid7, Uuid7State } from "@typed/id/Uuid7"
+ * import { Effect } from "effect"
+ * const id = Effect.provide(uuid7, Uuid7State.Default)
+ * ```
+ * @category Generators
+ * @since 1.0.0
+ */
 export const uuid7 = Effect.map(Uuid7State.next, uuid7FromSeed);
 function uuid7FromSeed({ randomBytes, seq, timestamp }) {
     const result = new Uint8Array(16);
@@ -69,5 +177,5 @@ function uuid7FromSeed({ randomBytes, seq, timestamp }) {
     result[13] = randomBytes[13];
     result[14] = randomBytes[14];
     result[15] = randomBytes[15];
-    return Uuid7.makeUnsafe(uuidStringify(result));
+    return Uuid7.make(uuidStringify(result));
 }

package/dist/__tests__/helpers.d.ts

@@ -0,0 +1,7 @@
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import { RandomValues } from "../RandomValues.js";
+export declare const expectIllegalArgument: (exit: Exit.Exit<unknown, unknown>) => void;
+export declare const seededRandomValues: (seed: string | number) => Layer.Layer<RandomValues>;
+export declare const zeroRandomValues: Layer.Layer<RandomValues>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/__tests__/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/__tests__/helpers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAGtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,eAAO,MAAM,qBAAqB,SAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,SAStE,CAAC;AAEF,eAAO,MAAM,kBAAkB,SAAU,MAAM,GAAG,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,YAAY,CAIhF,CAAC;AAEJ,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,CAOtD,CAAC"}

package/dist/__tests__/helpers.js

@@ -0,0 +1,19 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
+import { expect } from "vitest";
+import { RandomValues } from "../RandomValues.js";
+export const expectIllegalArgument = (exit) => {
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+        const failure = Cause.findErrorOption(exit.cause);
+        expect(failure._tag).toBe("Some");
+        if (failure._tag === "Some") {
+            expect(Cause.isIllegalArgumentError(failure.value)).toBe(true);
+        }
+    }
+};
+export const seededRandomValues = (seed) => Layer.effect(RandomValues, RandomValues.pipe(Effect.provide(RandomValues.Random), Random.withSeed(seed)));
+export const zeroRandomValues = Layer.succeed(RandomValues, RandomValues.of(Effect.fn((length) => Effect.succeed(new Uint8Array(length)))));

package/dist/__tests__/public-contract.type-test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=public-contract.type-test.d.ts.map

package/dist/__tests__/public-contract.type-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-contract.type-test.d.ts","sourceRoot":"","sources":["../../src/__tests__/public-contract.type-test.ts"],"names":[],"mappings":""}

package/dist/__tests__/public-contract.type-test.js

@@ -0,0 +1,3 @@
+import { Ids } from "../Ids.js";
+const curriedUuid5 = Ids.uuid5(namespace);
+const directUuid5 = Ids.uuid5(name, namespace);

package/dist/_sha.d.ts

@@ -1,4 +1,36 @@
 import * as Effect from "effect/Effect";
+/**
+ * Digests bytes with Web Crypto SHA-1 and returns a fresh Uint8Array.
+ * @remarks
+ * ## Why
+ * This published low-level helper exposes the exact hash required by UUID version 5; SHA-1 here is identity derivation, not password or signature security. Missing Web Crypto and rejected `subtle.digest` promises are Effect defects because the typed error channel is `never`.
+ * ## Ownership and lifetime
+ * Each Effect owns one asynchronous Web Crypto request and transfers a fresh result buffer; it retains no input after completion.
+ * @example
+ * ```ts
+ * import { sha1 } from "@typed/id/_sha"
+ * import { Effect } from "effect"
+ * const digest = Effect.runPromise(sha1(new TextEncoder().encode("name")))
+ * ```
+ * @category Hashing
+ * @since 1.0.0
+ */
 export declare const sha1: (data: BufferSource) => Effect.Effect<Uint8Array<ArrayBuffer>, never, never>;
+/**
+ * Digests bytes with Web Crypto SHA-512 and returns a fresh Uint8Array.
+ * @remarks
+ * ## Why
+ * This published low-level helper exposes the exact domain-separated hash used by CUID formatting without hiding platform requirements. Missing Web Crypto and rejected `subtle.digest` promises are Effect defects because the typed error channel is `never`.
+ * ## Ownership and lifetime
+ * Each Effect owns one asynchronous Web Crypto request and transfers a fresh result buffer; it retains no input after completion.
+ * @example
+ * ```ts
+ * import { sha512 } from "@typed/id/_sha"
+ * import { Effect } from "effect"
+ * const digest = Effect.runPromise(sha512(new TextEncoder().encode("seed")))
+ * ```
+ * @category Hashing
+ * @since 1.0.0
+ */
 export declare const sha512: (data: BufferSource) => Effect.Effect<Uint8Array<ArrayBuffer>, never, never>;
 //# sourceMappingURL=_sha.d.ts.map

package/dist/_sha.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_sha.d.ts","sourceRoot":"","sources":["../src/_sha.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,eAAO,MAAM,IAAI,GAAI,MAAM,YAAY,yDAGpC,CAAC;AAEJ,eAAO,MAAM,MAAM,GAAI,MAAM,YAAY,yDAGtC,CAAC"}
+{"version":3,"file":"_sha.d.ts","sourceRoot":"","sources":["../src/_sha.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,SAAU,YAAY,yDAGpC,CAAC;AAEJ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,SAAU,YAAY,yDAGtC,CAAC"}

package/dist/_sha.js

@@ -1,3 +1,35 @@
 import * as Effect from "effect/Effect";
+/**
+ * Digests bytes with Web Crypto SHA-1 and returns a fresh Uint8Array.
+ * @remarks
+ * ## Why
+ * This published low-level helper exposes the exact hash required by UUID version 5; SHA-1 here is identity derivation, not password or signature security. Missing Web Crypto and rejected `subtle.digest` promises are Effect defects because the typed error channel is `never`.
+ * ## Ownership and lifetime
+ * Each Effect owns one asynchronous Web Crypto request and transfers a fresh result buffer; it retains no input after completion.
+ * @example
+ * ```ts
+ * import { sha1 } from "@typed/id/_sha"
+ * import { Effect } from "effect"
+ * const digest = Effect.runPromise(sha1(new TextEncoder().encode("name")))
+ * ```
+ * @category Hashing
+ * @since 1.0.0
+ */
 export const sha1 = (data) => Effect.promise(() => crypto.subtle.digest("SHA-1", data).then((buffer) => new Uint8Array(buffer)));
+/**
+ * Digests bytes with Web Crypto SHA-512 and returns a fresh Uint8Array.
+ * @remarks
+ * ## Why
+ * This published low-level helper exposes the exact domain-separated hash used by CUID formatting without hiding platform requirements. Missing Web Crypto and rejected `subtle.digest` promises are Effect defects because the typed error channel is `never`.
+ * ## Ownership and lifetime
+ * Each Effect owns one asynchronous Web Crypto request and transfers a fresh result buffer; it retains no input after completion.
+ * @example
+ * ```ts
+ * import { sha512 } from "@typed/id/_sha"
+ * import { Effect } from "effect"
+ * const digest = Effect.runPromise(sha512(new TextEncoder().encode("seed")))
+ * ```
+ * @category Hashing
+ * @since 1.0.0
+ */
 export const sha512 = (data) => Effect.promise(() => crypto.subtle.digest("SHA-512", data).then((buffer) => new Uint8Array(buffer)));