@cullet/erp-core 1.5.0 → 2.0.0

package/src/core/application/use-case.ts

@@ -1,9 +1,10 @@
 import { type ContractVersion, version } from "../versioning/version.js";
+import { AppError } from "../errors/index.js";
 import type { Result } from "../result/result.js";
 
 import type { LoggerPort } from "./ports/logger.port.js";
 import type { MetricsPort } from "./ports/metrics.port.js";
-import type { TracerPort } from "./ports/tracer.port.js";
+import type { TraceAttributeValue, TracerPort } from "./ports/tracer.port.js";
 
 type MaybePromise<T> = T | Promise<T>;
 
@@ -82,25 +83,45 @@ abstract class UseCase<
 
     protected abstract execute(input: Input): MaybePromise<Output>;
 
+    /**
+     * Extra attributes stamped onto the span and every metric emitted for this
+     * execution. Override to attach stable, **low-cardinality** dimensions
+     * (e.g. `Command` adds `requested_by.kind`). Keep values bounded — they
+     * become metric label values, so a user id or free-form string here would
+     * explode the metric's cardinality. Defaults to none.
+     */
+    protected spanAttributes(
+        _input: Input,
+    ): Readonly<Record<string, TraceAttributeValue>> {
+        return {};
+    }
+
     private async runInstrumented(
         input: Input,
         observability: UseCaseObservability,
     ): Promise<Output> {
         const { logger, metrics, tracer } = observability;
         const name = this.useCaseName;
+        const attributes = safely(() => this.spanAttributes(input)) ?? {};
         const span = safely(() =>
-            tracer?.startSpan(name, { "use_case.name": name }),
+            tracer?.startSpan(name, { "use_case.name": name, ...attributes }),
         );
-        const startedAt = Date.now();
+        const startedAt = performance.now();
+        // Declared here (not inside `try`) so the `finally` histogram can label
+        // duration by outcome; defaults to "exception" and is overwritten once
+        // execute() returns without throwing.
+        let outcome: ExecutionOutcome = "exception";
 
         try {
             const output = await this.execute(input);
-            const outcome: ExecutionOutcome = output.isOk() ? "ok" : "error";
+            outcome = output.isOk() ? "ok" : "error";
 
             if (outcome === "error") {
+                const code = businessErrorCode(output);
                 safely(() =>
                     logger?.warn(`${name} returned a business error`, {
                         useCase: name,
+                        ...(code ? { code } : {}),
                     }),
                 );
             }
@@ -109,6 +130,7 @@ abstract class UseCase<
                 metrics?.counter(EXECUTION_COUNTER, 1, {
                     useCase: name,
                     outcome,
+                    ...attributes,
                 }),
             );
 
@@ -125,21 +147,36 @@ abstract class UseCase<
                 metrics?.counter(EXECUTION_COUNTER, 1, {
                     useCase: name,
                     outcome: "exception",
+                    ...attributes,
                 }),
             );
 
             throw error;
         } finally {
             safely(() =>
-                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {
-                    useCase: name,
-                }),
+                metrics?.histogram(
+                    DURATION_HISTOGRAM,
+                    performance.now() - startedAt,
+                    { useCase: name, outcome, ...attributes },
+                ),
             );
             safely(() => span?.end());
         }
     }
 }
 
+/**
+ * Pulls the stable `code` off a business-error `Result` for logging. Returns
+ * `undefined` when the error is not an {@link AppError} — the code is safe to
+ * log (it's the public contract), unlike the message which may carry PII.
+ */
+function businessErrorCode(
+    output: Result<unknown, unknown>,
+): string | undefined {
+    const error = output.errorOrNull();
+    return error instanceof AppError ? error.code : undefined;
+}
+
 /**
  * Invokes an observability side effect, isolating any adapter failure so it
  * cannot alter the use case outcome.

package/src/core/config/core-config.ts

@@ -1,5 +1,7 @@
 import type {
     ConditionEvaluationOptions,
+    ConditionEvaluationReport,
+    ConditionEvaluationReportLevel,
     ConditionEvaluatorReporter,
 } from "../policies/engines/condition-evaluator-reporter.js";
 import type { PolicyEvent, PolicyReporter } from "./policy-reporter.js";
@@ -10,23 +12,32 @@ export interface CoreObservabilityConfig {
 }
 
 export interface CoreConfigOptions {
+    // `observability` is today's only section. Future core config (settings,
+    // feature flags) joins here as sibling keys — that umbrella is why the
+    // reporter is nested under `observability` instead of living at the root.
     readonly observability?: CoreObservabilityConfig;
 }
 
-function reportSafely(
-    policyReporter: PolicyReporter,
-    event: PolicyEvent,
-): void {
+/** Reports an event without letting a throwing reporter abort the caller. */
+function safeReport(policyReporter: PolicyReporter, event: PolicyEvent): void {
     try {
         policyReporter.report(event);
     } catch {
-        // Falhas de telemetria nao podem interromper o fluxo de dominio.
+        // Telemetry failures must never interrupt the domain flow.
     }
 }
 
 /**
- * Centraliza a configuracao pura do core sem depender de implementacoes
- * concretas de logging, tracing ou report.
+ * The core's config namespace. Today it holds a single section —
+ * `observability` — whose whole job is to decide *where policy telemetry goes*
+ * while guaranteeing telemetry is best-effort (a throwing reporter can never
+ * abort a domain flow). App config (env, settings, feature flags) is
+ * deliberately absent for now: when the core needs it, it joins here as a
+ * sibling section rather than a new module — which is why this is `config`,
+ * not `observability`. It holds the active {@link PolicyReporter} (silent by
+ * default, so the core carries no logging dependency), bridges it to the
+ * engines' {@link ConditionEvaluatorReporter}, and offers `reportSafely` as
+ * the single guarded emit path shared with {@link PolicyService}.
  */
 export class CoreConfig {
     readonly #initialReporter: PolicyReporter;
@@ -39,22 +50,30 @@ export class CoreConfig {
         this.#currentReporter = reporter;
     }
 
+    /**
+     * Swaps the active reporter. Pass `observability.reporter` to enable
+     * telemetry, or set it explicitly to `undefined` to go silent again.
+     * Omitting `observability` (or its `reporter` key) is a no-op.
+     */
     configure(options: CoreConfigOptions): this {
-        const reporter = options.observability?.reporter;
-        if (reporter) {
-            this.#currentReporter = reporter;
+        const observability = options.observability;
+        if (observability && "reporter" in observability) {
+            this.#currentReporter =
+                observability.reporter ?? new SilentPolicyReporter();
         }
         return this;
     }
 
-    // Restores the reporter captured at construction time.
+    // Restores the reporter captured at construction time — which is silent
+    // only if this instance was built without one.
     reset(): this {
         this.#currentReporter = this.#initialReporter;
         return this;
     }
 
-    getPolicyReporter(): PolicyReporter {
-        return this.#currentReporter;
+    /** Emits a policy event through the active reporter, best-effort. */
+    reportSafely(event: PolicyEvent): void {
+        safeReport(this.#currentReporter, event);
     }
 
     getConditionEvaluationOptions(
@@ -69,19 +88,21 @@ export class CoreConfig {
     #bridgeToConditionReporter(
         policyReporter: PolicyReporter,
     ): ConditionEvaluatorReporter {
+        // Capture the reporter now so a mid-evaluation reconfigure never splits
+        // a single evaluation's reports across two reporters (intentional).
+        const emit = (
+            level: ConditionEvaluationReportLevel,
+            report: ConditionEvaluationReport,
+        ): void => {
+            safeReport(policyReporter, {
+                kind: "condition-eval",
+                ...report,
+                level,
+            });
+        };
         return {
-            warn(report) {
-                reportSafely(policyReporter, {
-                    kind: "condition-eval",
-                    ...report,
-                } satisfies PolicyEvent);
-            },
-            error(report) {
-                reportSafely(policyReporter, {
-                    kind: "condition-eval",
-                    ...report,
-                } satisfies PolicyEvent);
-            },
+            warn: (report) => emit("warn", report),
+            error: (report) => emit("error", report),
         };
     }
 }

package/src/core/config/index.ts

@@ -11,5 +11,6 @@ export type {
     PolicyResolutionEvent,
     PolicyEvaluationFailedEvent,
     PolicyEvaluationCompletedEvent,
+    AbacDecisionEvent,
 } from "./policy-reporter.js";
 export { SilentPolicyReporter } from "./silent-policy-reporter.js";

package/src/core/config/policy-reporter.ts

@@ -40,14 +40,45 @@ export interface PolicyEvaluationCompletedEvent {
     readonly occurredAt: Date;
 }
 
+/**
+ * A resolved ABAC decision (both PERMIT and DENY). Emitted best-effort by the
+ * `AbacAuthorizer` so a host can build an authorization audit trail without an
+ * adapter of its own; silent by default like every other event. Types are kept
+ * self-contained (no import from `core/abac`) to avoid a config→abac cycle.
+ */
+export interface AbacDecisionEvent {
+    readonly kind: "abac-decision";
+    readonly level: "info";
+    readonly action: string;
+    readonly resource?: { readonly type: string; readonly id?: string };
+    readonly actorId: string;
+    readonly effect: "PERMIT" | "DENY";
+    /** Deciding rule id, or `"<default>"` / `"<default-deny>"` when the set's default decided. */
+    readonly decidingRuleId: string;
+    readonly decidingRuleVersion?: number;
+    readonly algorithm: string;
+    readonly occurredAt: Date;
+}
+
 export type PolicyEvent =
     | ConditionEvalEvent
     | PolicyResolutionEvent
     | PolicyEvaluationFailedEvent
-    | PolicyEvaluationCompletedEvent;
+    | PolicyEvaluationCompletedEvent
+    | AbacDecisionEvent;
 
 // ─── Reporter interface ───────────────────────────────────────────────────────
 
+/**
+ * Sink for policy telemetry. The core never logs on its own — it hands typed
+ * events here and a host implementation decides what to do with them.
+ *
+ * Redaction is the host's responsibility: a `condition-eval` event carries the
+ * evaluated field path and value in `details` (e.g. `student.flags.*`), so in
+ * an ERP those payloads can contain PII. Sanitize before persisting or shipping
+ * events off-box; the core deliberately keeps no redaction seam so it stays
+ * pure and unopinionated about your logging stack.
+ */
 export interface PolicyReporter {
     report(event: PolicyEvent): void;
 }

package/src/core/domain/entity.ts

@@ -3,6 +3,8 @@ import { assertValidAggregateVersion } from "../shared/aggregate-version.js";
 import { assertValidDate, cloneDate } from "../shared/temporal-guards.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
+import { ValueObject } from "./value-object.js";
+
 /**
  * The minimal persisted shape needed to reconstitute an {@link Entity}.
  *
@@ -53,9 +55,16 @@ abstract class Entity<TIdentifier> {
      * Declared `protected` because entities are reconstituted through a
      * subclass factory, never instantiated directly by application code.
      *
-     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+     * @throws {InvariantViolationException} When `id` is absent, or when
+     *   `updatedAt` is earlier than `createdAt`.
      */
     protected constructor(state: EntityState<TIdentifier>) {
+        if (state.id == null) {
+            throw new InvariantViolationException(
+                "id is required: an entity cannot exist without an identity",
+            );
+        }
+
         assertValidDate("createdAt", state.createdAt);
         assertValidDate("updatedAt", state.updatedAt);
         assertValidAggregateVersion(state.aggregateVersion);
@@ -121,18 +130,23 @@ abstract class Entity<TIdentifier> {
      * call this from every state-changing method so the version counter stays
      * an accurate optimistic-lock token.
      *
-     * @param updatedAt - The modification instant; defaults to now. Validated
-     *   and required not to predate `createdAt`, preserving the same invariant
-     *   the constructor enforces.
+     * `updatedAt` is monotonic: each call must be at or after the current
+     * `updatedAt` (equal is fine — two mutations can share a millisecond).
+     * Without this, the version counter would advance while the timestamp
+     * walked backwards, corrupting any audit trail or ordering that reads
+     * `updatedAt`. A caller replaying out-of-order events must sort them first.
+     *
+     * @param updatedAt - The modification instant; defaults to now.
      * @returns The new aggregate version after the increment.
-     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+     * @throws {InvariantViolationException} When `updatedAt` is earlier than
+     *   the current `updatedAt`.
      */
     protected markAsModified(updatedAt: Date = new Date()): number {
         assertValidDate("updatedAt", updatedAt);
 
-        if (updatedAt.getTime() < this._createdAt.getTime()) {
+        if (updatedAt.getTime() < this._updatedAt.getTime()) {
             throw new InvariantViolationException(
-                "updatedAt cannot be earlier than createdAt",
+                "updatedAt cannot move backwards: it must be at or after the current updatedAt",
             );
         }
 
@@ -141,6 +155,35 @@ abstract class Entity<TIdentifier> {
 
         return this._aggregateVersion;
     }
+
+    /**
+     * Identity-based equality — the semantics that define an entity. Two
+     * entities are equal when they are the same concrete class and their ids
+     * match, regardless of any other field.
+     *
+     * The class check keeps a `CustomerId`-bearing entity from equalling an
+     * unrelated entity that happens to reuse the same raw id. Value-object ids
+     * are compared through their own `equals`, so two independently
+     * reconstituted id instances still match; primitive ids use `===`.
+     */
+    public equals(other: Entity<TIdentifier> | null | undefined): boolean {
+        if (other == null) {
+            return false;
+        }
+        if (other === this) {
+            return true;
+        }
+        if (other.constructor !== this.constructor) {
+            return false;
+        }
+
+        const id: unknown = this._id;
+        if (id instanceof ValueObject) {
+            return id.equals(other._id as typeof id);
+        }
+
+        return this._id === other._id;
+    }
 }
 
 export { Entity, type EntityState };

package/src/core/domain/rulesets/entity-ruleset.contracts.ts

@@ -1,5 +1,4 @@
 import { type Ruleset, type RulesetId } from "./ruleset.contracts.js";
-import { DomainException } from "../../exceptions/domain-exception.js";
 
 interface CreationRuleset<TData> extends Ruleset {
     validate(data: TData): void;
@@ -9,7 +8,6 @@ type InvariantRuleset = Ruleset;
 
 export {
     type CreationRuleset,
-    DomainException,
     type InvariantRuleset,
     type Ruleset,
     type RulesetId,

package/src/core/domain/rulesets/ruleset-registry.ts

@@ -6,6 +6,15 @@ import {
 
 class RulesetRegistryError extends DomainException {}
 
+/**
+ * Runtime guard for the `RulesetId` shape (`name@major.minor`). The template
+ * type only protects TypeScript callers — a JS consumer (or a cast) could
+ * register `"foo"` or `"foo@1.5.2"`, and either would silently corrupt
+ * {@link RulesetRegistry.getCurrent}'s version ordering via `NaN`/ignored
+ * segments. Same idea as `CONTRACT_VERSION_PATTERN` in `versioning/version.ts`.
+ */
+const RULESET_ID_PATTERN = /^.+@\d+\.\d+$/;
+
 function parseVersion(id: string): [number, number] {
     const atIdx = id.lastIndexOf("@");
     const versionStr = id.slice(atIdx + 1);
@@ -23,6 +32,11 @@ class RulesetRegistry implements RulesetRegistryContract {
                 "Registry is sealed. No new rulesets can be registered.",
             );
         }
+        if (!RULESET_ID_PATTERN.test(ruleset.id)) {
+            throw new RulesetRegistryError(
+                `Invalid ruleset id "${ruleset.id}". Expected "<name>@<major>.<minor>", e.g. "order-creation@1.0".`,
+            );
+        }
         if (this._store.has(ruleset.id)) {
             throw new RulesetRegistryError(
                 `Ruleset with id "${ruleset.id}" is already registered.`,
@@ -35,6 +49,12 @@ class RulesetRegistry implements RulesetRegistryContract {
         this._sealed = true;
     }
 
+    /**
+     * Looks up a ruleset by exact id. The `T` parameter is a caller-asserted
+     * cast, not a runtime check: asking for the wrong `T` compiles and returns
+     * the object mistyped — the standard registry trade-off. Keep the id and
+     * the expected type paired at the call site.
+     */
     get<T extends Ruleset>(id: string): T {
         const ruleset = this._store.get(id);
         if (!ruleset) {
@@ -46,6 +66,10 @@ class RulesetRegistry implements RulesetRegistryContract {
         return ruleset as T;
     }
 
+    /**
+     * Returns the highest `major.minor` version registered under `prefix`.
+     * The same caller-asserted `T` cast as {@link get} applies.
+     */
     getCurrent<T extends Ruleset>(prefix: string): T {
         const matchingEntries = Array.from(this._store.entries()).filter(
             ([key]) => key.startsWith(prefix + "@"),

package/src/core/domain/rulesets/value-object-ruleset.contracts.ts

@@ -1,13 +1,7 @@
-import { DomainException } from "../../exceptions/domain-exception.js";
 import { type Ruleset, type RulesetId } from "./ruleset.contracts.js";
 
 interface ValueObjectRuleset<T> extends Ruleset {
     validate(value: T): void;
 }
 
-export {
-    DomainException,
-    type Ruleset,
-    type RulesetId,
-    type ValueObjectRuleset,
-};
+export { type Ruleset, type RulesetId, type ValueObjectRuleset };

package/src/core/domain/temporal/half-open-interval.ts

@@ -0,0 +1,34 @@
+import { InvariantViolationException } from "../../exceptions/invariant-violation-exception.js";
+import { assertValidDate } from "../../shared/temporal-guards.js";
+
+/**
+ * Shared core of the bitemporal primitives: a half-open interval
+ * `[start, end)` whose end, when present, must be strictly later than its
+ * start. `ValidTime` and `TransactionTime` are the same shape under different
+ * (deliberate) vocabularies — the invariant lives here once so the two files
+ * cannot drift apart.
+ *
+ * Internal to `domain/temporal`; not exported from the barrel.
+ */
+function assertHalfOpenInterval(
+    startLabel: string,
+    start: Date,
+    endLabel: string,
+    end: Date | undefined,
+): void {
+    assertValidDate(startLabel, start);
+
+    if (end === undefined) {
+        return;
+    }
+
+    assertValidDate(endLabel, end);
+
+    if (end.getTime() <= start.getTime()) {
+        throw new InvariantViolationException(
+            `${endLabel} must be later than ${startLabel}`,
+        );
+    }
+}
+
+export { assertHalfOpenInterval };

package/src/core/domain/temporal/temporal-snapshot.ts

@@ -14,6 +14,14 @@ import {
 /**
  * Pairs a domain datum with its time dimensions (Business and Transaction).
  * It is the representation of an entry in the append-only (historical) table.
+ *
+ * `data` must be plain, structured-cloneable state — the primitive shape of an
+ * aggregate, not the aggregate itself. `createTemporalSnapshot` deep-clones it
+ * via `structuredClone`: functions and symbols inside `data` throw an
+ * `InvariantViolationException`, and class instances (a `ValueObject`, an
+ * `Entity`) are NOT rejected — they are silently flattened to plain objects,
+ * losing their prototype (and with it `equals`/`toPrimitive`). Project rich
+ * objects down first, e.g. with `toPrimitive()`.
  */
 interface TemporalSnapshot<T> {
     /** The data or state captured by the snapshot. */
@@ -33,8 +41,11 @@ interface CreateTemporalSnapshotInput<T> {
 function createTemporalSnapshot<T>(
     input: CreateTemporalSnapshotInput<T>,
 ): TemporalSnapshot<T> {
-    return makeImmutable({
-        data: input.data,
+    // The time dimensions come out of their factories already cloned and
+    // frozen; only `data` still needs the clone+freeze. Freezing the shell by
+    // hand avoids a second structuredClone pass over the whole snapshot.
+    return Object.freeze({
+        data: makeImmutable(input.data),
         validTime: createValidTime(input.validTime),
         txTime: createTransactionTime(input.txTime),
     });

package/src/core/domain/temporal/transaction-time.ts

@@ -1,11 +1,22 @@
-import { InvariantViolationException } from "../../exceptions/invariant-violation-exception.js";
 import { makeImmutable } from "../../shared/immutable.js";
-import { assertValidDate } from "../../shared/temporal-guards.js";
+
+import { assertHalfOpenInterval } from "./half-open-interval.js";
 
 /**
  * Represents transaction time (Transaction Time).
  * Defines when the system learned about or recorded a piece of information.
  * Useful for auditing and reconstructing system state at a specific past moment.
+ *
+ * The window is half-open — `recordedAt` inclusive, `supersededAt` exclusive —
+ * and strictly non-empty: `supersededAt` must be later than `recordedAt`, so a
+ * record superseded in the same instant it was written is not representable.
+ *
+ * One caveat mirrors {@link ValueObject}: `createTransactionTime` clones the
+ * input dates (no aliasing) but the inner `Date`s are NOT frozen —
+ * `Object.freeze` cannot block `setTime`/`setFullYear`, so a caller can still
+ * mutate `recordedAt` in place and corrupt the audit record after creation.
+ * `readonly` only prevents reassignment. Treat the dates as read-only, or keep
+ * instants as ISO/epoch in your own state when that guarantee matters.
  */
 interface TransactionTime {
     /** When the information was first recorded in the system. */
@@ -20,19 +31,12 @@ function assertTransactionTime(
     txTime: TransactionTime,
     fieldName: string = "txTime",
 ): void {
-    assertValidDate(`${fieldName}.recordedAt`, txTime.recordedAt);
-
-    if (txTime.supersededAt === undefined) {
-        return;
-    }
-
-    assertValidDate(`${fieldName}.supersededAt`, txTime.supersededAt);
-
-    if (txTime.supersededAt.getTime() <= txTime.recordedAt.getTime()) {
-        throw new InvariantViolationException(
-            `${fieldName}.supersededAt must be later than ${fieldName}.recordedAt`,
-        );
-    }
+    assertHalfOpenInterval(
+        `${fieldName}.recordedAt`,
+        txTime.recordedAt,
+        `${fieldName}.supersededAt`,
+        txTime.supersededAt,
+    );
 }
 
 function createTransactionTime(

package/src/core/domain/temporal/valid-time.ts

@@ -1,10 +1,22 @@
-import { InvariantViolationException } from "../../exceptions/invariant-violation-exception.js";
 import { makeImmutable } from "../../shared/immutable.js";
-import { assertValidDate } from "../../shared/temporal-guards.js";
+
+import { assertHalfOpenInterval } from "./half-open-interval.js";
 
 /**
  * Represents business time (Valid Time).
  * Defines when a piece of information is considered true or in effect in the real world.
+ *
+ * The window is half-open — `from` inclusive, `to` exclusive — and strictly
+ * non-empty: `to` must be later than `from`, so a zero-duration range `[t, t)`
+ * is deliberately not representable. Model an instantaneous event as an open
+ * range closed by the next fact, not as an empty window.
+ *
+ * One caveat mirrors {@link ValueObject}: `createValidTime` clones the input
+ * dates (no aliasing) but the inner `Date`s are NOT frozen — `Object.freeze`
+ * cannot block `setTime`/`setFullYear`, so a caller can still mutate `from`
+ * in place and corrupt the range after creation. `readonly` only prevents
+ * reassignment. Treat the dates as read-only, or keep instants as ISO/epoch in
+ * your own state when that guarantee matters.
  */
 interface ValidTime {
     /** Start of the validity window (inclusive). */
@@ -19,19 +31,12 @@ function assertValidTime(
     validTime: ValidTime,
     fieldName: string = "validTime",
 ): void {
-    assertValidDate(`${fieldName}.from`, validTime.from);
-
-    if (validTime.to === undefined) {
-        return;
-    }
-
-    assertValidDate(`${fieldName}.to`, validTime.to);
-
-    if (validTime.to.getTime() <= validTime.from.getTime()) {
-        throw new InvariantViolationException(
-            `${fieldName}.to must be later than ${fieldName}.from`,
-        );
-    }
+    assertHalfOpenInterval(
+        `${fieldName}.from`,
+        validTime.from,
+        `${fieldName}.to`,
+        validTime.to,
+    );
 }
 
 function createValidTime(input: CreateValidTimeInput): ValidTime {

package/src/core/domain/uuid-identifier.ts

@@ -38,7 +38,7 @@ abstract class UuidIdentifier<
      * two identifiers with different brands are not interchangeable at the type
      * level despite sharing the same `string` value.
      */
-    protected declare readonly __brand: TBrand;
+    declare protected readonly __brand: TBrand;
 
     protected constructor(value: string) {
         super(value);
@@ -54,8 +54,10 @@ abstract class UuidIdentifier<
     }
 
     /**
-     * Whether `candidate` is a canonical UUID (versions 1–5). The single source
-     * of truth for the format; concrete identifiers call this from `create`.
+     * Whether `candidate` is a canonical UUID (versions 1–8, including the
+     * time-ordered v7; nil and max UUIDs are rejected as sentinels). The single
+     * source of truth for the format — see `shared/uuid.ts`; concrete
+     * identifiers call this from `create`.
      */
     public static isValid(candidate: string): boolean {
         return UUID_PATTERN.test(candidate);