@zudojs/constants 1.0.1 → 1.1.1

package/README.md

@@ -2,6 +2,12 @@
 
 Shared constants, enums, branded types, and type-safe literals for the Zudojs framework.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-constants](https://zudojs.oyinlola.site/docs/packages-constants) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-constants.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -31,7 +37,11 @@ formatDuration(150_000); // "2m 30s"
 All constant objects are `Object.freeze`d `as const` maps, and every map has a
 matching literal-union type (`HttpStatusCode`, `HttpMethod`, `Environment`,
 `LifecycleState`, `SchemaIssueCode`, ...). Sets such as `HTTP_METHODS` and
-`SCHEMA_FORBIDDEN_KEYS` are immutable at runtime: `add`/`delete`/`clear` throw.
+`SCHEMA_FORBIDDEN_KEYS` are immutable at runtime: `add`/`delete`/`clear` throw,
+and their values live in a private store, so `Set.prototype.clear.call(set)`
+cannot empty them either. They implement `ReadonlySet` but are not `Set`
+instances (`instanceof Set` is `false`); copy with `new Set(value)` when a
+mutable set is needed.
 
 ## Modules
 
@@ -81,7 +91,11 @@ formatDuration(4_500_000); // "1h 15m"
 - Branded types (`UserId`, `EventId`, `Timestamp`, `Url`, `EmailAddress`, ...)
   with `createX` factories — the validating ones (`createTimestamp`,
   `createUrl`, `createEmailAddress`, `createHexString`, `createBase64String`,
-  `createJsonString`) throw `InvalidConstantError` on bad input
+  `createJsonString`, `createTenantId`) throw `InvalidConstantError` on bad
+  input. `createTimestamp` rejects impossible dates such as `2024-02-30`;
+  `createTenantId` NFKC-normalizes, trims and lowercases, then enforces
+  `TENANT_ID_PATTERN` (`[a-z0-9][a-z0-9_-]*`) and `MAX_TENANT_ID_LENGTH` (64),
+  the same rule as `@zudojs/tenancy`
 - `Limits`, `Defaults`, `Sentinel` and sentinels `NONE`, `UNINITIALIZED`, `EMPTY`
 - Lifecycle state machine: `LifecycleState`, `LifecyclePhase`, `LIFECYCLE_VALID_TRANSITIONS`, timeouts/retries
 - Schema constants: `SchemaIssueCode`, `SCHEMA_FORBIDDEN_KEYS` (immutable at runtime), `SCHEMA_STRING_FORMATS`
@@ -92,6 +106,9 @@ formatDuration(4_500_000); // "1h 15m"
 - `ValidationPattern` — the single source of truth for regexes (EMAIL, UUID,
   UUID_V4, IPV4, IPV6, ISO_DATE_TIME, URL, SEMVER, PHONE, FILE_NAME, ...).
   `SCHEMA_STRING_FORMATS` re-exports these rather than redefining them.
+  `EMAIL` accepts exactly what `isEmail` in `@zudojs/types` accepts
+  (structural, at most 254 characters, no `..`; `o'brien@example.com` and
+  `user@host.123` pass).
 - `ValidationLength`, `ValidationRange`
 
 ```typescript
@@ -116,6 +133,9 @@ ValidationLength.EMAIL; // 254
 - Injectable `Clock` / `Random` interfaces with `systemClock` / `systemRandom`
   (fully `node:crypto`-backed, safe for tokens and salts) and deterministic
   `createMockClock()` / `createMockRandom(seed)` for tests
+- `Random` is branded: `createMockRandom` returns a `MockRandom`
+  (`deterministic: true`), which the compiler refuses wherever a `Random` is
+  required, so a predictable generator cannot mint tokens by accident
 - `MockClock` adds `advance(ms)` and `set(timestampOrDate)`
 
 ```typescript
@@ -138,5 +158,6 @@ systemRandom.randomString(32); // CSPRNG-backed
 
 ### Errors
 
-- `InvalidConstantError`, `ConstantContextError` (built on `@zudojs/errors`;
-  error codes themselves live in `@zudojs/errors`)
+- `InvalidConstantError`, `ConstantContextError`, re-exported from
+  `@zudojs/errors` (which owns them), so `instanceof` matches either import
+  path

package/dist/common/common.constant.d.ts

@@ -4,7 +4,7 @@
  *
  * @module common/common
  */
-import { type UserId, type EventId, type RequestId, type CorrelationId, type SessionId, type TenantId, type MessageId, type MessageCausationId, type TokenId, type Timestamp, type Url, type EmailAddress, type HexString, type Base64String, type JsonString } from "./common.type.js";
+import { type UserId, type EventId, type RequestId, type CorrelationId, type SessionId, type MessageId, type MessageCausationId, type TokenId, type Url, type HexString, type Base64String, type JsonString } from "./common.type.js";
 /** Sentinel value indicating absence of a value. */
 export declare const NONE: "NONE";
 /** Sentinel value indicating an uninitialized state. */
@@ -109,10 +109,6 @@ export declare function createCorrelationId(id: string): CorrelationId;
  * Create a branded SessionId from a raw string.
  */
 export declare function createSessionId(id: string): SessionId;
-/**
- * Create a branded TenantId from a raw string.
- */
-export declare function createTenantId(id: string): TenantId;
 /**
  * Create a branded MessageId from a raw string.
  */
@@ -125,25 +121,12 @@ export declare function createMessageCausationId(id: string): MessageCausationId
  * Create a branded TokenId from a raw string.
  */
 export declare function createTokenId(id: string): TokenId;
-/**
- * Create a branded Timestamp from an ISO 8601 string.
- *
- * @throws {InvalidConstantError} if the input is not a valid ISO 8601
- * date-time string (e.g. `2024-01-01T00:00:00.000Z`).
- */
-export declare function createTimestamp(iso: string): Timestamp;
 /**
  * Create a branded Url from a raw string.
  *
  * @throws {InvalidConstantError} if the input is not a parseable URL.
  */
 export declare function createUrl(url: string): Url;
-/**
- * Create a branded EmailAddress from a raw string.
- *
- * @throws {InvalidConstantError} if the input is not a valid email address.
- */
-export declare function createEmailAddress(email: string): EmailAddress;
 /**
  * Create a branded HexString from a raw string.
  *

package/dist/common/common.constant.js

@@ -6,7 +6,6 @@
  */
 import {} from "./common.type.js";
 import { ContentTypes, Charset } from "../http/httpContentType.type.js";
-import { ValidationPattern } from "../validation/validation.pattern.type.js";
 import { InvalidConstantError } from "../constantsErrors/constantsError.base.js";
 /** Sentinel value indicating absence of a value. */
 export const NONE = "NONE";
@@ -122,12 +121,6 @@ export function createCorrelationId(id) {
 export function createSessionId(id) {
     return id;
 }
-/**
- * Create a branded TenantId from a raw string.
- */
-export function createTenantId(id) {
-    return id;
-}
 /**
  * Create a branded MessageId from a raw string.
  */
@@ -146,19 +139,6 @@ export function createMessageCausationId(id) {
 export function createTokenId(id) {
     return id;
 }
-/**
- * Create a branded Timestamp from an ISO 8601 string.
- *
- * @throws {InvalidConstantError} if the input is not a valid ISO 8601
- * date-time string (e.g. `2024-01-01T00:00:00.000Z`).
- */
-export function createTimestamp(iso) {
-    if (!ValidationPattern.ISO_DATE_TIME.test(iso) ||
-        Number.isNaN(Date.parse(iso))) {
-        throw new InvalidConstantError(`Invalid ISO 8601 timestamp: ${JSON.stringify(iso)}`);
-    }
-    return iso;
-}
 /**
  * Create a branded Url from a raw string.
  *
@@ -170,17 +150,6 @@ export function createUrl(url) {
     }
     return url;
 }
-/**
- * Create a branded EmailAddress from a raw string.
- *
- * @throws {InvalidConstantError} if the input is not a valid email address.
- */
-export function createEmailAddress(email) {
-    if (email.length > 254 || !ValidationPattern.EMAIL.test(email)) {
-        throw new InvalidConstantError(`Invalid email address: ${JSON.stringify(email)}`);
-    }
-    return email;
-}
 /**
  * Create a branded HexString from a raw string.
  *

package/dist/common/common.factory.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Validating branded-type factories: tenant ids, timestamps and email
+ * addresses. Each rejects input that the brand promises is impossible.
+ *
+ * @module common/factory
+ */
+import type { EmailAddress, TenantId, Timestamp } from "./common.type.js";
+/**
+ * Characters a tenant id may contain, after normalization.
+ *
+ * A tenant id is concatenated into cache keys, log lines, schema names and
+ * file paths, so anything that could act as a separator or a path segment is
+ * rejected here rather than escaped at every use site. Matches the rule in
+ * `@zudojs/tenancy`.
+ */
+export declare const TENANT_ID_PATTERN: RegExp;
+/** Maximum accepted tenant id length. */
+export declare const MAX_TENANT_ID_LENGTH = 64;
+/**
+ * Create a validated, normalized TenantId.
+ *
+ * Input is NFKC-normalized, trimmed and lowercased, then checked against
+ * {@link TENANT_ID_PATTERN} and {@link MAX_TENANT_ID_LENGTH}, so two
+ * spellings of one tenant cannot become two tenants and no id can carry a
+ * separator or path segment.
+ *
+ * @throws {InvalidConstantError} when the value is not a valid tenant id.
+ */
+export declare function createTenantId(id: string): TenantId;
+/**
+ * Create a branded Timestamp from an ISO 8601 string.
+ *
+ * @throws {InvalidConstantError} if the input is not a valid ISO 8601
+ * date-time string (e.g. `2024-01-01T00:00:00.000Z`) naming a real calendar
+ * date and time.
+ */
+export declare function createTimestamp(iso: string): Timestamp;
+/**
+ * Create a branded EmailAddress from a raw string.
+ *
+ * Accepts exactly what `ValidationPattern.EMAIL` accepts, which is the same
+ * set as `isEmail` in `@zudojs/types`, bounded at 254 characters.
+ *
+ * @throws {InvalidConstantError} if the input is not a valid email address.
+ */
+export declare function createEmailAddress(email: string): EmailAddress;
+//# sourceMappingURL=common.factory.d.ts.map

package/dist/common/common.factory.js

@@ -0,0 +1,96 @@
+/**
+ * Validating branded-type factories: tenant ids, timestamps and email
+ * addresses. Each rejects input that the brand promises is impossible.
+ *
+ * @module common/factory
+ */
+import { ValidationPattern } from "../validation/validation.pattern.type.js";
+import { ValidationLength } from "../validation/validation.constant.js";
+import { InvalidConstantError } from "../constantsErrors/constantsError.base.js";
+/**
+ * Characters a tenant id may contain, after normalization.
+ *
+ * A tenant id is concatenated into cache keys, log lines, schema names and
+ * file paths, so anything that could act as a separator or a path segment is
+ * rejected here rather than escaped at every use site. Matches the rule in
+ * `@zudojs/tenancy`.
+ */
+export const TENANT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/u;
+/** Maximum accepted tenant id length. */
+export const MAX_TENANT_ID_LENGTH = 64;
+/**
+ * Create a validated, normalized TenantId.
+ *
+ * Input is NFKC-normalized, trimmed and lowercased, then checked against
+ * {@link TENANT_ID_PATTERN} and {@link MAX_TENANT_ID_LENGTH}, so two
+ * spellings of one tenant cannot become two tenants and no id can carry a
+ * separator or path segment.
+ *
+ * @throws {InvalidConstantError} when the value is not a valid tenant id.
+ */
+export function createTenantId(id) {
+    const normalized = typeof id === "string" ? id.normalize("NFKC").trim().toLowerCase() : "";
+    if (normalized.length === 0 ||
+        normalized.length > MAX_TENANT_ID_LENGTH ||
+        !TENANT_ID_PATTERN.test(normalized)) {
+        throw new InvalidConstantError(`Invalid tenant id: ${JSON.stringify(id)}`);
+    }
+    return normalized;
+}
+const ISO_PARTS = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))?$/;
+/**
+ * Whether an ISO 8601 date-time names an instant that exists.
+ *
+ * `Date.parse` rolls day overflow into the next month (`2024-02-30` becomes
+ * March 1), so the calendar date is round-tripped through `Date.UTC` and the
+ * time and offset fields are range-checked explicitly.
+ */
+function isRealIsoDateTime(iso) {
+    const match = ISO_PARTS.exec(iso);
+    if (match === null)
+        return false;
+    const [year, month, day, hour, minute, second, offH, offM] = match
+        .slice(1)
+        .map((part) => (part === undefined ? 0 : Number(part)));
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day &&
+        hour <= 23 &&
+        minute <= 59 &&
+        second <= 59 &&
+        offH <= 23 &&
+        offM <= 59);
+}
+/**
+ * Create a branded Timestamp from an ISO 8601 string.
+ *
+ * @throws {InvalidConstantError} if the input is not a valid ISO 8601
+ * date-time string (e.g. `2024-01-01T00:00:00.000Z`) naming a real calendar
+ * date and time.
+ */
+export function createTimestamp(iso) {
+    if (typeof iso !== "string" ||
+        !ValidationPattern.ISO_DATE_TIME.test(iso) ||
+        !isRealIsoDateTime(iso)) {
+        throw new InvalidConstantError(`Invalid ISO 8601 timestamp: ${JSON.stringify(iso)}`);
+    }
+    return iso;
+}
+/**
+ * Create a branded EmailAddress from a raw string.
+ *
+ * Accepts exactly what `ValidationPattern.EMAIL` accepts, which is the same
+ * set as `isEmail` in `@zudojs/types`, bounded at 254 characters.
+ *
+ * @throws {InvalidConstantError} if the input is not a valid email address.
+ */
+export function createEmailAddress(email) {
+    if (typeof email !== "string" ||
+        email.length > ValidationLength.EMAIL ||
+        !ValidationPattern.EMAIL.test(email)) {
+        throw new InvalidConstantError(`Invalid email address: ${JSON.stringify(email)}`);
+    }
+    return email;
+}
+//# sourceMappingURL=common.factory.js.map

package/dist/common/common.serialization.d.ts

@@ -40,6 +40,12 @@ export declare const SerializationLimits: Readonly<{
     readonly MAX_TRANSFORMERS: 256;
     /** Maximum length of a type tag string. */
     readonly MAX_TYPE_TAG_LENGTH: 128;
+    /**
+     * Maximum number of decimal digits accepted when decoding or coercing a
+     * BigInt from text. `BigInt()` parsing is quadratic in the digit count, so
+     * an unbounded string is a CPU denial-of-service vector.
+     */
+    readonly MAX_BIGINT_DIGITS: 4096;
 }>;
 /** Type-tag sentinel keys for JSON representation. */
 export declare const SerializationTags: Readonly<{

package/dist/common/common.serialization.js

@@ -42,6 +42,12 @@ export const SerializationLimits = Object.freeze({
     MAX_TRANSFORMERS: 256,
     /** Maximum length of a type tag string. */
     MAX_TYPE_TAG_LENGTH: 128,
+    /**
+     * Maximum number of decimal digits accepted when decoding or coercing a
+     * BigInt from text. `BigInt()` parsing is quadratic in the digit count, so
+     * an unbounded string is a CPU denial-of-service vector.
+     */
+    MAX_BIGINT_DIGITS: 4096,
 });
 /** Type-tag sentinel keys for JSON representation. */
 export const SerializationTags = Object.freeze({

package/dist/common/index.d.ts

@@ -4,7 +4,8 @@
  * @module common
  */
 export { type Brand, type EntityId, type UserId, type EventId, type RequestId, type CorrelationId, type SessionId, type TenantId, type MessageId, type MessageCausationId, type TokenId, type Timestamp, type Url, type EmailAddress, type HexString, type Base64String, type JsonString, } from "./common.type.js";
-export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createTenantId, createMessageId, createMessageCausationId, createTokenId, createTimestamp, createUrl, createEmailAddress, createHexString, createBase64String, createJsonString, } from "./common.constant.js";
+export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createMessageId, createMessageCausationId, createTokenId, createUrl, createHexString, createBase64String, createJsonString, } from "./common.constant.js";
+export { createTenantId, createTimestamp, createEmailAddress, TENANT_ID_PATTERN, MAX_TENANT_ID_LENGTH, } from "./common.factory.js";
 export { SerializationFormat, SerializationContentType, SerializationLimits, SerializationTags, SERIALIZATION_SCHEMA_VERSION, } from "./common.serialization.js";
 export { SchemaIssueCode, SCHEMA_DEFAULT_MAX_DEPTH, SCHEMA_DEFAULT_MAX_STRING_LENGTH, SCHEMA_DEFAULT_MAX_ARRAY_LENGTH, SCHEMA_DEFAULT_MAX_OBJECT_KEYS, SCHEMA_FORBIDDEN_KEYS, SCHEMA_STRING_FORMATS, } from "./common.schema.js";
 export { LifecycleState, LifecyclePhase, LIFECYCLE_VALID_TRANSITIONS, LIFECYCLE_DEFAULT_TIMEOUT, LIFECYCLE_DEFAULT_START_TIMEOUT, LIFECYCLE_DEFAULT_STOP_TIMEOUT, LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT, LIFECYCLE_DEFAULT_CONCURRENCY, LIFECYCLE_DEFAULT_RETRY_ATTEMPTS, LIFECYCLE_DEFAULT_RETRY_DELAY, LIFECYCLE_DEFAULT_RETRY_MAX_DELAY, } from "./common.lifecycle.js";

package/dist/common/index.js

@@ -4,7 +4,8 @@
  * @module common
  */
 export {} from "./common.type.js";
-export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createTenantId, createMessageId, createMessageCausationId, createTokenId, createTimestamp, createUrl, createEmailAddress, createHexString, createBase64String, createJsonString, } from "./common.constant.js";
+export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createMessageId, createMessageCausationId, createTokenId, createUrl, createHexString, createBase64String, createJsonString, } from "./common.constant.js";
+export { createTenantId, createTimestamp, createEmailAddress, TENANT_ID_PATTERN, MAX_TENANT_ID_LENGTH, } from "./common.factory.js";
 export { SerializationFormat, SerializationContentType, SerializationLimits, SerializationTags, SERIALIZATION_SCHEMA_VERSION, } from "./common.serialization.js";
 export { SchemaIssueCode, SCHEMA_DEFAULT_MAX_DEPTH, SCHEMA_DEFAULT_MAX_STRING_LENGTH, SCHEMA_DEFAULT_MAX_ARRAY_LENGTH, SCHEMA_DEFAULT_MAX_OBJECT_KEYS, SCHEMA_FORBIDDEN_KEYS, SCHEMA_STRING_FORMATS, } from "./common.schema.js";
 export { LifecycleState, LifecyclePhase, LIFECYCLE_VALID_TRANSITIONS, LIFECYCLE_DEFAULT_TIMEOUT, LIFECYCLE_DEFAULT_START_TIMEOUT, LIFECYCLE_DEFAULT_STOP_TIMEOUT, LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT, LIFECYCLE_DEFAULT_CONCURRENCY, LIFECYCLE_DEFAULT_RETRY_ATTEMPTS, LIFECYCLE_DEFAULT_RETRY_DELAY, LIFECYCLE_DEFAULT_RETRY_MAX_DELAY, } from "./common.lifecycle.js";

package/dist/constantsErrors/constantsError.base.d.ts

@@ -1,24 +1,10 @@
 /**
- * Error classes specific to the constants package.
+ * Error classes used by the constants package.
+ *
+ * Owned by `@zudojs/errors` and re-exported here, so `instanceof` checks
+ * against either import path match the same errors.
  *
  * @module constantsErrors
  */
-import { BaseError, ErrorCode, type ErrorMetadata } from "@zudojs/errors";
-/**
- * Error thrown when an invalid constant value is used.
- */
-export declare class InvalidConstantError extends BaseError {
-    constructor(message: string, options?: {
-        readonly code?: ErrorCode;
-        readonly metadata?: ErrorMetadata;
-    });
-}
-/**
- * Error thrown when a constant is used outside its valid context.
- */
-export declare class ConstantContextError extends BaseError {
-    constructor(message: string, options?: {
-        readonly metadata?: ErrorMetadata;
-    });
-}
+export { InvalidConstantError, ConstantContextError } from "@zudojs/errors";
 //# sourceMappingURL=constantsError.base.d.ts.map

package/dist/constantsErrors/constantsError.base.js

@@ -1,33 +1,10 @@
 /**
- * Error classes specific to the constants package.
+ * Error classes used by the constants package.
+ *
+ * Owned by `@zudojs/errors` and re-exported here, so `instanceof` checks
+ * against either import path match the same errors.
  *
  * @module constantsErrors
  */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
-/**
- * Error thrown when an invalid constant value is used.
- */
-export class InvalidConstantError extends BaseError {
-    constructor(message, options) {
-        super(message, {
-            code: options?.code ?? ErrorCode.CONFIGURATION_INVALID,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.ERROR,
-            metadata: options?.metadata,
-        });
-    }
-}
-/**
- * Error thrown when a constant is used outside its valid context.
- */
-export class ConstantContextError extends BaseError {
-    constructor(message, options) {
-        super(message, {
-            code: ErrorCode.INVALID_INPUT,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.ERROR,
-            metadata: options?.metadata,
-        });
-    }
-}
+export { InvalidConstantError, ConstantContextError } from "@zudojs/errors";
 //# sourceMappingURL=constantsError.base.js.map

package/dist/internal/immutableSet.d.ts

@@ -3,24 +3,42 @@
  *
  * `Object.freeze` does not protect the internal slots of a `Set`, so a
  * "frozen" Set still allows `.add()`, `.delete()`, and `.clear()` at runtime.
- * This subclass hard-disables all mutators, making it safe to expose
- * security-sensitive sets (e.g. forbidden schema keys) as `ReadonlySet`.
+ * Subclassing `Set` and overriding the mutators is not enough either:
+ * `Set.prototype.clear.call(instance)` reaches the internal slot directly.
+ * This class therefore holds its values in a private `Set` that no outside
+ * code can reference, and exposes only the `ReadonlySet` surface.
  *
  * @module internal/immutableSet
  */
 /**
- * A `Set` whose mutating methods (`add`, `delete`, `clear`) always throw.
+ * A read-only set whose mutating methods (`add`, `delete`, `clear`) always
+ * throw, and whose backing storage is unreachable from outside the instance.
  *
- * Values are inserted via `super.add` during construction only; afterwards
- * the collection is permanently immutable.
+ * It is not a `Set` subclass, so `instanceof Set` is `false`; iterate it or
+ * copy it with `new Set(value)` when a mutable `Set` is needed.
  */
-export declare class ImmutableSet<T> extends Set<T> {
+export declare class ImmutableSet<T> implements ReadonlySet<T> {
+    #private;
     constructor(values?: Iterable<T>);
+    /** Number of values in the set. */
+    get size(): number;
+    /** Whether `value` is in the set. */
+    has(value: T): boolean;
+    /** Calls `callbackfn` once per value, in insertion order. */
+    forEach(callbackfn: (value: T, value2: T, set: ReadonlySet<T>) => void, thisArg?: unknown): void;
+    /** Iterates `[value, value]` pairs, mirroring `Set.prototype.entries`. */
+    entries(): SetIterator<[T, T]>;
+    /** Iterates the values. */
+    keys(): SetIterator<T>;
+    /** Iterates the values. */
+    values(): SetIterator<T>;
+    /** Iterates the values. */
+    [Symbol.iterator](): SetIterator<T>;
     /** @throws {TypeError} always — this set is immutable. */
-    add(_value: T): this;
+    add(_value: T): never;
     /** @throws {TypeError} always — this set is immutable. */
-    delete(_value: T): boolean;
+    delete(_value: T): never;
     /** @throws {TypeError} always — this set is immutable. */
-    clear(): void;
+    clear(): never;
 }
 //# sourceMappingURL=immutableSet.d.ts.map

package/dist/internal/immutableSet.js

@@ -3,27 +3,57 @@
  *
  * `Object.freeze` does not protect the internal slots of a `Set`, so a
  * "frozen" Set still allows `.add()`, `.delete()`, and `.clear()` at runtime.
- * This subclass hard-disables all mutators, making it safe to expose
- * security-sensitive sets (e.g. forbidden schema keys) as `ReadonlySet`.
+ * Subclassing `Set` and overriding the mutators is not enough either:
+ * `Set.prototype.clear.call(instance)` reaches the internal slot directly.
+ * This class therefore holds its values in a private `Set` that no outside
+ * code can reference, and exposes only the `ReadonlySet` surface.
  *
  * @module internal/immutableSet
  */
+const setHas = Set.prototype.has;
 /**
- * A `Set` whose mutating methods (`add`, `delete`, `clear`) always throw.
+ * A read-only set whose mutating methods (`add`, `delete`, `clear`) always
+ * throw, and whose backing storage is unreachable from outside the instance.
  *
- * Values are inserted via `super.add` during construction only; afterwards
- * the collection is permanently immutable.
+ * It is not a `Set` subclass, so `instanceof Set` is `false`; iterate it or
+ * copy it with `new Set(value)` when a mutable `Set` is needed.
  */
-export class ImmutableSet extends Set {
+export class ImmutableSet {
+    #values;
     constructor(values) {
-        super();
-        if (values !== undefined) {
-            for (const value of values) {
-                super.add(value);
-            }
-        }
+        this.#values = new Set(values);
         Object.freeze(this);
     }
+    /** Number of values in the set. */
+    get size() {
+        return this.#values.size;
+    }
+    /** Whether `value` is in the set. */
+    has(value) {
+        return setHas.call(this.#values, value);
+    }
+    /** Calls `callbackfn` once per value, in insertion order. */
+    forEach(callbackfn, thisArg) {
+        for (const value of this.#values) {
+            callbackfn.call(thisArg, value, value, this);
+        }
+    }
+    /** Iterates `[value, value]` pairs, mirroring `Set.prototype.entries`. */
+    entries() {
+        return this.#values.entries();
+    }
+    /** Iterates the values. */
+    keys() {
+        return this.#values.keys();
+    }
+    /** Iterates the values. */
+    values() {
+        return this.#values.values();
+    }
+    /** Iterates the values. */
+    [Symbol.iterator]() {
+        return this.#values.values();
+    }
     /** @throws {TypeError} always — this set is immutable. */
     add(_value) {
         throw new TypeError("Cannot add to an immutable Set");
@@ -37,4 +67,5 @@ export class ImmutableSet extends Set {
         throw new TypeError("Cannot clear an immutable Set");
     }
 }
+Object.freeze(ImmutableSet.prototype);
 //# sourceMappingURL=immutableSet.js.map

package/dist/runtime/index.d.ts

@@ -6,5 +6,5 @@
 export { systemClock, createMockClock } from "./clock.js";
 export type { Clock, MockClock } from "./clock.js";
 export { systemRandom, createMockRandom } from "./random.js";
-export type { Random } from "./random.js";
+export type { Random, RandomSource, MockRandom } from "./random.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/random.d.ts

@@ -4,9 +4,15 @@
  * @module runtime/random
  */
 /**
- * Provides deterministic randomness for testing.
+ * Brand marking an implementation as cryptographically secure.
+ *
+ * Without it any object with the four method names would satisfy
+ * {@link Random}, including the seeded {@link createMockRandom} generator,
+ * so a predictable test double could be injected where tokens are minted.
  */
-export interface Random {
+declare const SecureRandomBrand: unique symbol;
+/** The randomness operations shared by {@link Random} and {@link MockRandom}. */
+export interface RandomSource {
     /**
      * Returns a random float between 0 (inclusive) and 1 (exclusive).
      */
@@ -24,6 +30,29 @@ export interface Random {
      */
     randomBytes(length: number): Uint8Array;
 }
+/**
+ * Cryptographically secure randomness, safe for tokens, session ids and
+ * salts. Branded: only {@link systemRandom} (or an implementation cast
+ * deliberately) satisfies it, and {@link MockRandom} never does.
+ *
+ * The richer, separately-branded `Random` in `@zudojs/types` is the
+ * long-term owner of this contract.
+ */
+export interface Random extends RandomSource {
+    /** @internal Marks the implementation as unpredictable. */
+    readonly [SecureRandomBrand]: true;
+}
+/**
+ * A seeded, fully predictable generator for tests.
+ *
+ * Structurally distinct from {@link Random} (it lacks the security brand and
+ * carries `deterministic: true`), so the compiler rejects it wherever a
+ * secure generator is required.
+ */
+export interface MockRandom extends RandomSource {
+    /** Marks this as a deterministic generator, not a secure one. */
+    readonly deterministic: true;
+}
 /**
  * Default random backed by `node:crypto` (CSPRNG).
  *
@@ -40,5 +69,6 @@ export declare const systemRandom: Random;
  * with `Math.imul` for exact 32-bit arithmetic. Outputs are always in
  * `[0, 1)`. Not cryptographically secure — tests only.
  */
-export declare function createMockRandom(seed?: number): Random;
+export declare function createMockRandom(seed?: number): MockRandom;
+export {};
 //# sourceMappingURL=random.d.ts.map

package/dist/runtime/random.js

@@ -50,6 +50,7 @@ export function createMockRandom(seed = 1) {
         return state / 0x100000000;
     }
     return {
+        deterministic: true,
         random: next,
         randomInt: (min, max) => Math.floor(next() * (max - min + 1)) + min,
         randomString: (length) => {

package/dist/validation/validation.pattern.type.d.ts

@@ -12,11 +12,15 @@
  */
 export declare const ValidationPattern: Readonly<{
     /**
-     * Simplified email pattern (pragmatic subset of RFC 5322).
+     * Structural email pattern — the monorepo's one acceptance set.
      *
-     * The domain part rejects consecutive dots, leading/trailing dots, and
-     * labels that start or end with a hyphen. Combine with
-     * `ValidationLength.EMAIL` (254) for a length bound.
+     * Accepts exactly what `isEmail` in `@zudojs/types` accepts: at most 254
+     * characters (RFC 5321), no `..` anywhere, a local part free of
+     * whitespace, `@`, `,`, `;`, `<`, `>`, `"`, `[`, `]` and `\\`, and a
+     * domain of two or more hyphen-safe labels. Deliberately structural, not a
+     * full RFC 5322 parser: `o'brien@example.com` and `user@host.123` pass,
+     * deliverability is a verification step's job. The length bound is a
+     * lookahead, so it runs before the label pattern can backtrack.
      */
     readonly EMAIL: RegExp;
     /** UUID — any version/variant nibble (use UUID_V4 for strict v4). */

package/dist/validation/validation.pattern.type.js

@@ -12,13 +12,17 @@
  */
 export const ValidationPattern = Object.freeze({
     /**
-     * Simplified email pattern (pragmatic subset of RFC 5322).
+     * Structural email pattern — the monorepo's one acceptance set.
      *
-     * The domain part rejects consecutive dots, leading/trailing dots, and
-     * labels that start or end with a hyphen. Combine with
-     * `ValidationLength.EMAIL` (254) for a length bound.
+     * Accepts exactly what `isEmail` in `@zudojs/types` accepts: at most 254
+     * characters (RFC 5321), no `..` anywhere, a local part free of
+     * whitespace, `@`, `,`, `;`, `<`, `>`, `"`, `[`, `]` and `\\`, and a
+     * domain of two or more hyphen-safe labels. Deliberately structural, not a
+     * full RFC 5322 parser: `o'brien@example.com` and `user@host.123` pass,
+     * deliverability is a verification step's job. The length bound is a
+     * lookahead, so it runs before the label pattern can backtrack.
      */
-    EMAIL: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/,
+    EMAIL: /^(?=[\s\S]{1,254}$)(?![\s\S]*\.\.)[^\s@,;<>"[\]\\]+@[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i,
     /** UUID — any version/variant nibble (use UUID_V4 for strict v4). */
     UUID: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
     /** UUID v4 (strict: version nibble 4, RFC 4122 variant). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/constants",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Shared constants, enums, and type-safe literals for the Zudojs framework.",
   "license": "MIT",
   "author": {
@@ -26,7 +26,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.2.0"
   },
   "engines": {
     "node": ">=24.0.0"