@cullet/erp-core 1.4.0 → 2.0.0

package/dist/ruleset-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ruleset-registry.js","names":[],"sources":["../src/core/domain/rulesets/ruleset-registry.ts"],"sourcesContent":["import { DomainException } from \"../../exceptions/domain-exception.js\";\nimport {\n    type Ruleset,\n    type RulesetRegistry as RulesetRegistryContract,\n} from \"./ruleset.contracts.js\";\n\nclass RulesetRegistryError extends DomainException {}\n\nfunction parseVersion(id: string): [number, number] {\n    const atIdx = id.lastIndexOf(\"@\");\n    const versionStr = id.slice(atIdx + 1);\n    const [major, minor] = versionStr.split(\".\").map(Number);\n    return [major, minor];\n}\n\nclass RulesetRegistry implements RulesetRegistryContract {\n    private readonly _store = new Map<string, Ruleset>();\n    private _sealed = false;\n\n    register(ruleset: Ruleset): void {\n        if (this._sealed) {\n            throw new RulesetRegistryError(\n                \"Registry is sealed. No new rulesets can be registered.\",\n            );\n        }\n        if (this._store.has(ruleset.id)) {\n            throw new RulesetRegistryError(\n                `Ruleset with id \"${ruleset.id}\" is already registered.`,\n            );\n        }\n        this._store.set(ruleset.id, ruleset);\n    }\n\n    seal(): void {\n        this._sealed = true;\n    }\n\n    get<T extends Ruleset>(id: string): T {\n        const ruleset = this._store.get(id);\n        if (!ruleset) {\n            const available = Array.from(this._store.keys()).join(\", \");\n            throw new RulesetRegistryError(\n                `Ruleset \"${id}\" not found. Available: [${available}]`,\n            );\n        }\n        return ruleset as T;\n    }\n\n    getCurrent<T extends Ruleset>(prefix: string): T {\n        const matchingEntries = Array.from(this._store.entries()).filter(\n            ([key]) => key.startsWith(prefix + \"@\"),\n        );\n\n        if (matchingEntries.length === 0) {\n            throw new RulesetRegistryError(\n                `No rulesets found with prefix \"${prefix}\".`,\n            );\n        }\n\n        const sorted = matchingEntries.sort(([a], [b]) => {\n            const [aMajor, aMinor] = parseVersion(a);\n            const [bMajor, bMinor] = parseVersion(b);\n            if (aMajor !== bMajor) return aMajor - bMajor;\n            return aMinor - bMinor;\n        });\n\n        return sorted[sorted.length - 1][1] as T;\n    }\n}\n\nexport { RulesetRegistry };\n"],"mappings":";;AAMA,IAAM,uBAAN,cAAmC,gBAAgB,CAAC;AAEpD,SAAS,aAAa,IAA8B;CAChD,MAAM,QAAQ,GAAG,YAAY,GAAG;CAEhC,MAAM,CAAC,OAAO,SADK,GAAG,MAAM,QAAQ,CACJ,EAAE,MAAM,GAAG,EAAE,IAAI,MAAM;CACvD,OAAO,CAAC,OAAO,KAAK;AACxB;AAEA,IAAM,kBAAN,MAAyD;;gCAC3B,IAAI,IAAqB;iBACjC;;CAElB,SAAS,SAAwB;EAC7B,IAAI,KAAK,SACL,MAAM,IAAI,qBACN,wDACJ;EAEJ,IAAI,KAAK,OAAO,IAAI,QAAQ,EAAE,GAC1B,MAAM,IAAI,qBACN,oBAAoB,QAAQ,GAAG,yBACnC;EAEJ,KAAK,OAAO,IAAI,QAAQ,IAAI,OAAO;CACvC;CAEA,OAAa;EACT,KAAK,UAAU;CACnB;CAEA,IAAuB,IAAe;EAClC,MAAM,UAAU,KAAK,OAAO,IAAI,EAAE;EAClC,IAAI,CAAC,SAED,MAAM,IAAI,qBACN,YAAY,GAAG,2BAFD,MAAM,KAAK,KAAK,OAAO,KAAK,CAAC,EAAE,KAAK,IAEA,EAAE,EACxD;EAEJ,OAAO;CACX;CAEA,WAA8B,QAAmB;EAC7C,MAAM,kBAAkB,MAAM,KAAK,KAAK,OAAO,QAAQ,CAAC,EAAE,QACrD,CAAC,SAAS,IAAI,WAAW,SAAS,GAAG,CAC1C;EAEA,IAAI,gBAAgB,WAAW,GAC3B,MAAM,IAAI,qBACN,kCAAkC,OAAO,GAC7C;EAGJ,MAAM,SAAS,gBAAgB,MAAM,CAAC,IAAI,CAAC,OAAO;GAC9C,MAAM,CAAC,QAAQ,UAAU,aAAa,CAAC;GACvC,MAAM,CAAC,QAAQ,UAAU,aAAa,CAAC;GACvC,IAAI,WAAW,QAAQ,OAAO,SAAS;GACvC,OAAO,SAAS;EACpB,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,GAAG;CACrC;AACJ"}
+{"version":3,"file":"ruleset-registry.js","names":[],"sources":["../src/core/domain/rulesets/ruleset-registry.ts"],"sourcesContent":["import { DomainException } from \"../../exceptions/domain-exception.js\";\nimport {\n    type Ruleset,\n    type RulesetRegistry as RulesetRegistryContract,\n} from \"./ruleset.contracts.js\";\n\nclass RulesetRegistryError extends DomainException {}\n\n/**\n * Runtime guard for the `RulesetId` shape (`name@major.minor`). The template\n * type only protects TypeScript callers — a JS consumer (or a cast) could\n * register `\"foo\"` or `\"foo@1.5.2\"`, and either would silently corrupt\n * {@link RulesetRegistry.getCurrent}'s version ordering via `NaN`/ignored\n * segments. Same idea as `CONTRACT_VERSION_PATTERN` in `versioning/version.ts`.\n */\nconst RULESET_ID_PATTERN = /^.+@\\d+\\.\\d+$/;\n\nfunction parseVersion(id: string): [number, number] {\n    const atIdx = id.lastIndexOf(\"@\");\n    const versionStr = id.slice(atIdx + 1);\n    const [major, minor] = versionStr.split(\".\").map(Number);\n    return [major, minor];\n}\n\nclass RulesetRegistry implements RulesetRegistryContract {\n    private readonly _store = new Map<string, Ruleset>();\n    private _sealed = false;\n\n    register(ruleset: Ruleset): void {\n        if (this._sealed) {\n            throw new RulesetRegistryError(\n                \"Registry is sealed. No new rulesets can be registered.\",\n            );\n        }\n        if (!RULESET_ID_PATTERN.test(ruleset.id)) {\n            throw new RulesetRegistryError(\n                `Invalid ruleset id \"${ruleset.id}\". Expected \"<name>@<major>.<minor>\", e.g. \"order-creation@1.0\".`,\n            );\n        }\n        if (this._store.has(ruleset.id)) {\n            throw new RulesetRegistryError(\n                `Ruleset with id \"${ruleset.id}\" is already registered.`,\n            );\n        }\n        this._store.set(ruleset.id, ruleset);\n    }\n\n    seal(): void {\n        this._sealed = true;\n    }\n\n    /**\n     * Looks up a ruleset by exact id. The `T` parameter is a caller-asserted\n     * cast, not a runtime check: asking for the wrong `T` compiles and returns\n     * the object mistyped — the standard registry trade-off. Keep the id and\n     * the expected type paired at the call site.\n     */\n    get<T extends Ruleset>(id: string): T {\n        const ruleset = this._store.get(id);\n        if (!ruleset) {\n            const available = Array.from(this._store.keys()).join(\", \");\n            throw new RulesetRegistryError(\n                `Ruleset \"${id}\" not found. Available: [${available}]`,\n            );\n        }\n        return ruleset as T;\n    }\n\n    /**\n     * Returns the highest `major.minor` version registered under `prefix`.\n     * The same caller-asserted `T` cast as {@link get} applies.\n     */\n    getCurrent<T extends Ruleset>(prefix: string): T {\n        const matchingEntries = Array.from(this._store.entries()).filter(\n            ([key]) => key.startsWith(prefix + \"@\"),\n        );\n\n        if (matchingEntries.length === 0) {\n            throw new RulesetRegistryError(\n                `No rulesets found with prefix \"${prefix}\".`,\n            );\n        }\n\n        const sorted = matchingEntries.sort(([a], [b]) => {\n            const [aMajor, aMinor] = parseVersion(a);\n            const [bMajor, bMinor] = parseVersion(b);\n            if (aMajor !== bMajor) return aMajor - bMajor;\n            return aMinor - bMinor;\n        });\n\n        return sorted[sorted.length - 1][1] as T;\n    }\n}\n\nexport { RulesetRegistry };\n"],"mappings":";;AAMA,IAAM,uBAAN,cAAmC,gBAAgB,CAAC;;;;;;;;AASpD,MAAM,qBAAqB;AAE3B,SAAS,aAAa,IAA8B;CAChD,MAAM,QAAQ,GAAG,YAAY,GAAG;CAEhC,MAAM,CAAC,OAAO,SADK,GAAG,MAAM,QAAQ,CACJ,EAAE,MAAM,GAAG,EAAE,IAAI,MAAM;CACvD,OAAO,CAAC,OAAO,KAAK;AACxB;AAEA,IAAM,kBAAN,MAAyD;;gCAC3B,IAAI,IAAqB;iBACjC;;CAElB,SAAS,SAAwB;EAC7B,IAAI,KAAK,SACL,MAAM,IAAI,qBACN,wDACJ;EAEJ,IAAI,CAAC,mBAAmB,KAAK,QAAQ,EAAE,GACnC,MAAM,IAAI,qBACN,uBAAuB,QAAQ,GAAG,iEACtC;EAEJ,IAAI,KAAK,OAAO,IAAI,QAAQ,EAAE,GAC1B,MAAM,IAAI,qBACN,oBAAoB,QAAQ,GAAG,yBACnC;EAEJ,KAAK,OAAO,IAAI,QAAQ,IAAI,OAAO;CACvC;CAEA,OAAa;EACT,KAAK,UAAU;CACnB;;;;;;;CAQA,IAAuB,IAAe;EAClC,MAAM,UAAU,KAAK,OAAO,IAAI,EAAE;EAClC,IAAI,CAAC,SAED,MAAM,IAAI,qBACN,YAAY,GAAG,2BAFD,MAAM,KAAK,KAAK,OAAO,KAAK,CAAC,EAAE,KAAK,IAEA,EAAE,EACxD;EAEJ,OAAO;CACX;;;;;CAMA,WAA8B,QAAmB;EAC7C,MAAM,kBAAkB,MAAM,KAAK,KAAK,OAAO,QAAQ,CAAC,EAAE,QACrD,CAAC,SAAS,IAAI,WAAW,SAAS,GAAG,CAC1C;EAEA,IAAI,gBAAgB,WAAW,GAC3B,MAAM,IAAI,qBACN,kCAAkC,OAAO,GAC7C;EAGJ,MAAM,SAAS,gBAAgB,MAAM,CAAC,IAAI,CAAC,OAAO;GAC9C,MAAM,CAAC,QAAQ,UAAU,aAAa,CAAC;GACvC,MAAM,CAAC,QAAQ,UAAU,aAAa,CAAC;GACvC,IAAI,WAAW,QAAQ,OAAO,SAAS;GACvC,OAAO,SAAS;EACpB,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,GAAG;CACrC;AACJ"}

package/dist/stable-stringify.cjs

@@ -0,0 +1,87 @@
+const require_temporal_guards = require("./temporal-guards.cjs");
+//#region src/core/shared/stable-stringify.ts
+const CIRCULAR_STRUCTURE_MESSAGE = "Cannot stably stringify a circular structure";
+function sortKeysDeep(value, seen) {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+		seen.add(value);
+		const mapped = value.map((item) => sortKeysDeep(item, seen));
+		seen.delete(value);
+		return mapped;
+	}
+	if (value instanceof Date) return value;
+	if (value && typeof value === "object") {
+		if (seen.has(value)) throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+		seen.add(value);
+		const record = value;
+		const ordered = Object.create(null);
+		for (const key of Object.keys(record).sort()) ordered[key] = sortKeysDeep(record[key], seen);
+		seen.delete(value);
+		return ordered;
+	}
+	return value;
+}
+/**
+* Deterministic JSON string with object keys sorted recursively, so key order
+* does not affect the output.
+*
+* Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
+* functions and symbols are dropped, non-finite numbers become `null`, `bigint`
+* throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
+* collapse to the same string — this is fine for the structural-equality use it
+* serves (comparing two value objects), but **not** for hashing. For a
+* collision-resistant canonical form use {@link canonicalStringify}, which
+* rejects those lossy values up front.
+*
+* @throws {TypeError} On circular references (mirroring `JSON.stringify`).
+*/
+function stableStringify(value) {
+	return JSON.stringify(sortKeysDeep(value, /* @__PURE__ */ new WeakSet()));
+}
+function assertHashable(value, path, seen) {
+	if (value === null) return;
+	const type = typeof value;
+	if (type === "undefined") throw new TypeError(`canonicalStringify does not accept undefined values (at ${path})`);
+	if (type === "number" && !Number.isFinite(value)) throw new TypeError(`canonicalStringify does not accept non-finite numbers (at ${path}, value: ${String(value)})`);
+	if (type === "bigint" || type === "function" || type === "symbol") throw new TypeError(`canonicalStringify does not accept ${type} values (at ${path})`);
+	if (type !== "object") return;
+	if (value instanceof Date) {
+		if (!require_temporal_guards.isValidDate(value)) throw new TypeError(`canonicalStringify does not accept Invalid Date (at ${path})`);
+		return;
+	}
+	if (seen.has(value)) throw new TypeError(`canonicalStringify does not accept circular references (at ${path})`);
+	seen.add(value);
+	if (Array.isArray(value)) value.forEach((item, index) => {
+		assertHashable(item, `${path}[${index}]`, seen);
+	});
+	else for (const [key, nested] of Object.entries(value)) assertHashable(nested, `${path}.${key}`, seen);
+	seen.delete(value);
+}
+/**
+* Strict counterpart to {@link stableStringify}: same deterministic output, but
+* throws on any value `JSON.stringify` would drop or coerce (`undefined`,
+* non-finite numbers, `bigint`, functions, symbols, `Invalid Date`) and on
+* circular references. Use this whenever the string feeds a hash or integrity
+* check, so distinct payloads cannot collide.
+*
+* @throws {TypeError} On lossy values or circular references.
+*/
+function canonicalStringify(value) {
+	assertHashable(value, "$", /* @__PURE__ */ new WeakSet());
+	return stableStringify(value);
+}
+//#endregion
+Object.defineProperty(exports, "canonicalStringify", {
+	enumerable: true,
+	get: function() {
+		return canonicalStringify;
+	}
+});
+Object.defineProperty(exports, "stableStringify", {
+	enumerable: true,
+	get: function() {
+		return stableStringify;
+	}
+});
+
+//# sourceMappingURL=stable-stringify.cjs.map

package/dist/stable-stringify.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-stringify.cjs","names":["isValidDate"],"sources":["../src/core/shared/stable-stringify.ts"],"sourcesContent":["import { isValidDate } from \"./temporal-guards.js\";\n\nconst CIRCULAR_STRUCTURE_MESSAGE =\n    \"Cannot stably stringify a circular structure\";\n\n// `seen` holds the current traversal branch so true cycles are rejected while\n// repeated (acyclic) references are still serialized — matching JSON.stringify.\nfunction sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {\n    if (Array.isArray(value)) {\n        if (seen.has(value)) {\n            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);\n        }\n        seen.add(value);\n        const mapped = value.map((item) => sortKeysDeep(item, seen));\n        seen.delete(value);\n        return mapped;\n    }\n\n    if (value instanceof Date) {\n        return value;\n    }\n\n    if (value && typeof value === \"object\") {\n        if (seen.has(value)) {\n            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);\n        }\n        seen.add(value);\n        const record = value as Record<string, unknown>;\n        const ordered = Object.create(null) as Record<string, unknown>;\n\n        for (const key of Object.keys(record).sort()) {\n            ordered[key] = sortKeysDeep(record[key], seen);\n        }\n        seen.delete(value);\n\n        return ordered;\n    }\n\n    return value;\n}\n\n/**\n * Deterministic JSON string with object keys sorted recursively, so key order\n * does not affect the output.\n *\n * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,\n * functions and symbols are dropped, non-finite numbers become `null`, `bigint`\n * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore\n * collapse to the same string — this is fine for the structural-equality use it\n * serves (comparing two value objects), but **not** for hashing. For a\n * collision-resistant canonical form use {@link canonicalStringify}, which\n * rejects those lossy values up front.\n *\n * @throws {TypeError} On circular references (mirroring `JSON.stringify`).\n */\nfunction stableStringify(value: unknown): string {\n    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));\n}\n\n// Rejects every value `JSON.stringify` would silently drop or coerce, so\n// semantically different payloads can never collapse to the same canonical\n// string. Owned here (rather than in policies) so `payloadHash` and\n// `PolicyHashing` share one strict definition instead of each re-implementing\n// the deep guard.\nfunction assertHashable(\n    value: unknown,\n    path: string,\n    seen: WeakSet<object>,\n): void {\n    if (value === null) {\n        return;\n    }\n\n    const type = typeof value;\n\n    if (type === \"undefined\") {\n        throw new TypeError(\n            `canonicalStringify does not accept undefined values (at ${path})`,\n        );\n    }\n\n    if (type === \"number\" && !Number.isFinite(value)) {\n        throw new TypeError(\n            `canonicalStringify does not accept non-finite numbers (at ${path}, value: ${String(value)})`,\n        );\n    }\n\n    if (type === \"bigint\" || type === \"function\" || type === \"symbol\") {\n        throw new TypeError(\n            `canonicalStringify does not accept ${type} values (at ${path})`,\n        );\n    }\n\n    if (type !== \"object\") {\n        return;\n    }\n\n    if (value instanceof Date) {\n        if (!isValidDate(value)) {\n            throw new TypeError(\n                `canonicalStringify does not accept Invalid Date (at ${path})`,\n            );\n        }\n        return;\n    }\n\n    if (seen.has(value as object)) {\n        throw new TypeError(\n            `canonicalStringify does not accept circular references (at ${path})`,\n        );\n    }\n    seen.add(value as object);\n\n    if (Array.isArray(value)) {\n        value.forEach((item, index) => {\n            assertHashable(item, `${path}[${index}]`, seen);\n        });\n    } else {\n        for (const [key, nested] of Object.entries(\n            value as Record<string, unknown>,\n        )) {\n            assertHashable(nested, `${path}.${key}`, seen);\n        }\n    }\n\n    seen.delete(value as object);\n}\n\n/**\n * Strict counterpart to {@link stableStringify}: same deterministic output, but\n * throws on any value `JSON.stringify` would drop or coerce (`undefined`,\n * non-finite numbers, `bigint`, functions, symbols, `Invalid Date`) and on\n * circular references. Use this whenever the string feeds a hash or integrity\n * check, so distinct payloads cannot collide.\n *\n * @throws {TypeError} On lossy values or circular references.\n */\nfunction canonicalStringify(value: unknown): string {\n    assertHashable(value, \"$\", new WeakSet<object>());\n\n    return stableStringify(value);\n}\n\nexport { assertHashable, canonicalStringify, stableStringify };\n"],"mappings":";;AAEA,MAAM,6BACF;AAIJ,SAAS,aAAa,OAAgB,MAAgC;CAClE,IAAI,MAAM,QAAQ,KAAK,GAAG;EACtB,IAAI,KAAK,IAAI,KAAK,GACd,MAAM,IAAI,UAAU,0BAA0B;EAElD,KAAK,IAAI,KAAK;EACd,MAAM,SAAS,MAAM,KAAK,SAAS,aAAa,MAAM,IAAI,CAAC;EAC3D,KAAK,OAAO,KAAK;EACjB,OAAO;CACX;CAEA,IAAI,iBAAiB,MACjB,OAAO;CAGX,IAAI,SAAS,OAAO,UAAU,UAAU;EACpC,IAAI,KAAK,IAAI,KAAK,GACd,MAAM,IAAI,UAAU,0BAA0B;EAElD,KAAK,IAAI,KAAK;EACd,MAAM,SAAS;EACf,MAAM,UAAU,OAAO,OAAO,IAAI;EAElC,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,EAAE,KAAK,GACvC,QAAQ,OAAO,aAAa,OAAO,MAAM,IAAI;EAEjD,KAAK,OAAO,KAAK;EAEjB,OAAO;CACX;CAEA,OAAO;AACX;;;;;;;;;;;;;;;AAgBA,SAAS,gBAAgB,OAAwB;CAC7C,OAAO,KAAK,UAAU,aAAa,uBAAO,IAAI,QAAgB,CAAC,CAAC;AACpE;AAOA,SAAS,eACL,OACA,MACA,MACI;CACJ,IAAI,UAAU,MACV;CAGJ,MAAM,OAAO,OAAO;CAEpB,IAAI,SAAS,aACT,MAAM,IAAI,UACN,2DAA2D,KAAK,EACpE;CAGJ,IAAI,SAAS,YAAY,CAAC,OAAO,SAAS,KAAK,GAC3C,MAAM,IAAI,UACN,6DAA6D,KAAK,WAAW,OAAO,KAAK,EAAE,EAC/F;CAGJ,IAAI,SAAS,YAAY,SAAS,cAAc,SAAS,UACrD,MAAM,IAAI,UACN,sCAAsC,KAAK,cAAc,KAAK,EAClE;CAGJ,IAAI,SAAS,UACT;CAGJ,IAAI,iBAAiB,MAAM;EACvB,IAAI,CAACA,wBAAAA,YAAY,KAAK,GAClB,MAAM,IAAI,UACN,uDAAuD,KAAK,EAChE;EAEJ;CACJ;CAEA,IAAI,KAAK,IAAI,KAAe,GACxB,MAAM,IAAI,UACN,8DAA8D,KAAK,EACvE;CAEJ,KAAK,IAAI,KAAe;CAExB,IAAI,MAAM,QAAQ,KAAK,GACnB,MAAM,SAAS,MAAM,UAAU;EAC3B,eAAe,MAAM,GAAG,KAAK,GAAG,MAAM,IAAI,IAAI;CAClD,CAAC;MAED,KAAK,MAAM,CAAC,KAAK,WAAW,OAAO,QAC/B,KACJ,GACI,eAAe,QAAQ,GAAG,KAAK,GAAG,OAAO,IAAI;CAIrD,KAAK,OAAO,KAAe;AAC/B;;;;;;;;;;AAWA,SAAS,mBAAmB,OAAwB;CAChD,eAAe,OAAO,qBAAK,IAAI,QAAgB,CAAC;CAEhD,OAAO,gBAAgB,KAAK;AAChC"}

package/dist/stable-stringify.js

@@ -0,0 +1,76 @@
+import { r as isValidDate } from "./temporal-guards.js";
+//#region src/core/shared/stable-stringify.ts
+const CIRCULAR_STRUCTURE_MESSAGE = "Cannot stably stringify a circular structure";
+function sortKeysDeep(value, seen) {
+	if (Array.isArray(value)) {
+		if (seen.has(value)) throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+		seen.add(value);
+		const mapped = value.map((item) => sortKeysDeep(item, seen));
+		seen.delete(value);
+		return mapped;
+	}
+	if (value instanceof Date) return value;
+	if (value && typeof value === "object") {
+		if (seen.has(value)) throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);
+		seen.add(value);
+		const record = value;
+		const ordered = Object.create(null);
+		for (const key of Object.keys(record).sort()) ordered[key] = sortKeysDeep(record[key], seen);
+		seen.delete(value);
+		return ordered;
+	}
+	return value;
+}
+/**
+* Deterministic JSON string with object keys sorted recursively, so key order
+* does not affect the output.
+*
+* Follows `JSON.stringify` semantics for the values it serializes: `undefined`,
+* functions and symbols are dropped, non-finite numbers become `null`, `bigint`
+* throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore
+* collapse to the same string — this is fine for the structural-equality use it
+* serves (comparing two value objects), but **not** for hashing. For a
+* collision-resistant canonical form use {@link canonicalStringify}, which
+* rejects those lossy values up front.
+*
+* @throws {TypeError} On circular references (mirroring `JSON.stringify`).
+*/
+function stableStringify(value) {
+	return JSON.stringify(sortKeysDeep(value, /* @__PURE__ */ new WeakSet()));
+}
+function assertHashable(value, path, seen) {
+	if (value === null) return;
+	const type = typeof value;
+	if (type === "undefined") throw new TypeError(`canonicalStringify does not accept undefined values (at ${path})`);
+	if (type === "number" && !Number.isFinite(value)) throw new TypeError(`canonicalStringify does not accept non-finite numbers (at ${path}, value: ${String(value)})`);
+	if (type === "bigint" || type === "function" || type === "symbol") throw new TypeError(`canonicalStringify does not accept ${type} values (at ${path})`);
+	if (type !== "object") return;
+	if (value instanceof Date) {
+		if (!isValidDate(value)) throw new TypeError(`canonicalStringify does not accept Invalid Date (at ${path})`);
+		return;
+	}
+	if (seen.has(value)) throw new TypeError(`canonicalStringify does not accept circular references (at ${path})`);
+	seen.add(value);
+	if (Array.isArray(value)) value.forEach((item, index) => {
+		assertHashable(item, `${path}[${index}]`, seen);
+	});
+	else for (const [key, nested] of Object.entries(value)) assertHashable(nested, `${path}.${key}`, seen);
+	seen.delete(value);
+}
+/**
+* Strict counterpart to {@link stableStringify}: same deterministic output, but
+* throws on any value `JSON.stringify` would drop or coerce (`undefined`,
+* non-finite numbers, `bigint`, functions, symbols, `Invalid Date`) and on
+* circular references. Use this whenever the string feeds a hash or integrity
+* check, so distinct payloads cannot collide.
+*
+* @throws {TypeError} On lossy values or circular references.
+*/
+function canonicalStringify(value) {
+	assertHashable(value, "$", /* @__PURE__ */ new WeakSet());
+	return stableStringify(value);
+}
+//#endregion
+export { stableStringify as n, canonicalStringify as t };
+
+//# sourceMappingURL=stable-stringify.js.map

package/dist/stable-stringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-stringify.js","names":[],"sources":["../src/core/shared/stable-stringify.ts"],"sourcesContent":["import { isValidDate } from \"./temporal-guards.js\";\n\nconst CIRCULAR_STRUCTURE_MESSAGE =\n    \"Cannot stably stringify a circular structure\";\n\n// `seen` holds the current traversal branch so true cycles are rejected while\n// repeated (acyclic) references are still serialized — matching JSON.stringify.\nfunction sortKeysDeep(value: unknown, seen: WeakSet<object>): unknown {\n    if (Array.isArray(value)) {\n        if (seen.has(value)) {\n            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);\n        }\n        seen.add(value);\n        const mapped = value.map((item) => sortKeysDeep(item, seen));\n        seen.delete(value);\n        return mapped;\n    }\n\n    if (value instanceof Date) {\n        return value;\n    }\n\n    if (value && typeof value === \"object\") {\n        if (seen.has(value)) {\n            throw new TypeError(CIRCULAR_STRUCTURE_MESSAGE);\n        }\n        seen.add(value);\n        const record = value as Record<string, unknown>;\n        const ordered = Object.create(null) as Record<string, unknown>;\n\n        for (const key of Object.keys(record).sort()) {\n            ordered[key] = sortKeysDeep(record[key], seen);\n        }\n        seen.delete(value);\n\n        return ordered;\n    }\n\n    return value;\n}\n\n/**\n * Deterministic JSON string with object keys sorted recursively, so key order\n * does not affect the output.\n *\n * Follows `JSON.stringify` semantics for the values it serializes: `undefined`,\n * functions and symbols are dropped, non-finite numbers become `null`, `bigint`\n * throws, and `Map`/`Set` serialize as `{}`. Distinct payloads can therefore\n * collapse to the same string — this is fine for the structural-equality use it\n * serves (comparing two value objects), but **not** for hashing. For a\n * collision-resistant canonical form use {@link canonicalStringify}, which\n * rejects those lossy values up front.\n *\n * @throws {TypeError} On circular references (mirroring `JSON.stringify`).\n */\nfunction stableStringify(value: unknown): string {\n    return JSON.stringify(sortKeysDeep(value, new WeakSet<object>()));\n}\n\n// Rejects every value `JSON.stringify` would silently drop or coerce, so\n// semantically different payloads can never collapse to the same canonical\n// string. Owned here (rather than in policies) so `payloadHash` and\n// `PolicyHashing` share one strict definition instead of each re-implementing\n// the deep guard.\nfunction assertHashable(\n    value: unknown,\n    path: string,\n    seen: WeakSet<object>,\n): void {\n    if (value === null) {\n        return;\n    }\n\n    const type = typeof value;\n\n    if (type === \"undefined\") {\n        throw new TypeError(\n            `canonicalStringify does not accept undefined values (at ${path})`,\n        );\n    }\n\n    if (type === \"number\" && !Number.isFinite(value)) {\n        throw new TypeError(\n            `canonicalStringify does not accept non-finite numbers (at ${path}, value: ${String(value)})`,\n        );\n    }\n\n    if (type === \"bigint\" || type === \"function\" || type === \"symbol\") {\n        throw new TypeError(\n            `canonicalStringify does not accept ${type} values (at ${path})`,\n        );\n    }\n\n    if (type !== \"object\") {\n        return;\n    }\n\n    if (value instanceof Date) {\n        if (!isValidDate(value)) {\n            throw new TypeError(\n                `canonicalStringify does not accept Invalid Date (at ${path})`,\n            );\n        }\n        return;\n    }\n\n    if (seen.has(value as object)) {\n        throw new TypeError(\n            `canonicalStringify does not accept circular references (at ${path})`,\n        );\n    }\n    seen.add(value as object);\n\n    if (Array.isArray(value)) {\n        value.forEach((item, index) => {\n            assertHashable(item, `${path}[${index}]`, seen);\n        });\n    } else {\n        for (const [key, nested] of Object.entries(\n            value as Record<string, unknown>,\n        )) {\n            assertHashable(nested, `${path}.${key}`, seen);\n        }\n    }\n\n    seen.delete(value as object);\n}\n\n/**\n * Strict counterpart to {@link stableStringify}: same deterministic output, but\n * throws on any value `JSON.stringify` would drop or coerce (`undefined`,\n * non-finite numbers, `bigint`, functions, symbols, `Invalid Date`) and on\n * circular references. Use this whenever the string feeds a hash or integrity\n * check, so distinct payloads cannot collide.\n *\n * @throws {TypeError} On lossy values or circular references.\n */\nfunction canonicalStringify(value: unknown): string {\n    assertHashable(value, \"$\", new WeakSet<object>());\n\n    return stableStringify(value);\n}\n\nexport { assertHashable, canonicalStringify, stableStringify };\n"],"mappings":";;AAEA,MAAM,6BACF;AAIJ,SAAS,aAAa,OAAgB,MAAgC;CAClE,IAAI,MAAM,QAAQ,KAAK,GAAG;EACtB,IAAI,KAAK,IAAI,KAAK,GACd,MAAM,IAAI,UAAU,0BAA0B;EAElD,KAAK,IAAI,KAAK;EACd,MAAM,SAAS,MAAM,KAAK,SAAS,aAAa,MAAM,IAAI,CAAC;EAC3D,KAAK,OAAO,KAAK;EACjB,OAAO;CACX;CAEA,IAAI,iBAAiB,MACjB,OAAO;CAGX,IAAI,SAAS,OAAO,UAAU,UAAU;EACpC,IAAI,KAAK,IAAI,KAAK,GACd,MAAM,IAAI,UAAU,0BAA0B;EAElD,KAAK,IAAI,KAAK;EACd,MAAM,SAAS;EACf,MAAM,UAAU,OAAO,OAAO,IAAI;EAElC,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,EAAE,KAAK,GACvC,QAAQ,OAAO,aAAa,OAAO,MAAM,IAAI;EAEjD,KAAK,OAAO,KAAK;EAEjB,OAAO;CACX;CAEA,OAAO;AACX;;;;;;;;;;;;;;;AAgBA,SAAS,gBAAgB,OAAwB;CAC7C,OAAO,KAAK,UAAU,aAAa,uBAAO,IAAI,QAAgB,CAAC,CAAC;AACpE;AAOA,SAAS,eACL,OACA,MACA,MACI;CACJ,IAAI,UAAU,MACV;CAGJ,MAAM,OAAO,OAAO;CAEpB,IAAI,SAAS,aACT,MAAM,IAAI,UACN,2DAA2D,KAAK,EACpE;CAGJ,IAAI,SAAS,YAAY,CAAC,OAAO,SAAS,KAAK,GAC3C,MAAM,IAAI,UACN,6DAA6D,KAAK,WAAW,OAAO,KAAK,EAAE,EAC/F;CAGJ,IAAI,SAAS,YAAY,SAAS,cAAc,SAAS,UACrD,MAAM,IAAI,UACN,sCAAsC,KAAK,cAAc,KAAK,EAClE;CAGJ,IAAI,SAAS,UACT;CAGJ,IAAI,iBAAiB,MAAM;EACvB,IAAI,CAAC,YAAY,KAAK,GAClB,MAAM,IAAI,UACN,uDAAuD,KAAK,EAChE;EAEJ;CACJ;CAEA,IAAI,KAAK,IAAI,KAAe,GACxB,MAAM,IAAI,UACN,8DAA8D,KAAK,EACvE;CAEJ,KAAK,IAAI,KAAe;CAExB,IAAI,MAAM,QAAQ,KAAK,GACnB,MAAM,SAAS,MAAM,UAAU;EAC3B,eAAe,MAAM,GAAG,KAAK,GAAG,MAAM,IAAI,IAAI;CAClD,CAAC;MAED,KAAK,MAAM,CAAC,KAAK,WAAW,OAAO,QAC/B,KACJ,GACI,eAAe,QAAQ,GAAG,KAAK,GAAG,OAAO,IAAI;CAIrD,KAAK,OAAO,KAAe;AAC/B;;;;;;;;;;AAWA,SAAS,mBAAmB,OAAwB;CAChD,eAAe,OAAO,qBAAK,IAAI,QAAgB,CAAC;CAEhD,OAAO,gBAAgB,KAAK;AAChC"}

package/dist/temporal-snapshot.d.cts

@@ -0,0 +1,87 @@
+import { t as DeepReadonly } from "./immutable.cjs";
+
+//#region src/core/domain/temporal/transaction-time.d.ts
+
+/**
+ * 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. */
+  readonly recordedAt: Date;
+  /** When this information was superseded or invalidated by a newer version. */
+  readonly supersededAt?: Date;
+}
+type CreateTransactionTimeInput = TransactionTime;
+declare function assertTransactionTime(txTime: TransactionTime, fieldName?: string): void;
+declare function createTransactionTime(input: CreateTransactionTimeInput): TransactionTime;
+//#endregion
+//#region src/core/domain/temporal/valid-time.d.ts
+/**
+ * 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). */
+  readonly from: Date;
+  /** End of the validity window (exclusive). When absent, the information is still in effect. */
+  readonly to?: Date;
+}
+type CreateValidTimeInput = ValidTime;
+declare function assertValidTime(validTime: ValidTime, fieldName?: string): void;
+declare function createValidTime(input: CreateValidTimeInput): ValidTime;
+//#endregion
+//#region src/core/domain/temporal/temporal-snapshot.d.ts
+/**
+ * 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. */
+  readonly data: DeepReadonly<T>;
+  /** Period during which this datum was valid in the real world. */
+  readonly validTime: ValidTime;
+  /** Period during which this record was the state known to the system. */
+  readonly txTime: TransactionTime;
+}
+interface CreateTemporalSnapshotInput<T> {
+  readonly data: T;
+  readonly validTime: CreateValidTimeInput;
+  readonly txTime: CreateTransactionTimeInput;
+}
+declare function createTemporalSnapshot<T>(input: CreateTemporalSnapshotInput<T>): TemporalSnapshot<T>;
+//#endregion
+export { ValidTime as a, CreateTransactionTimeInput as c, createTransactionTime as d, CreateValidTimeInput as i, TransactionTime as l, TemporalSnapshot as n, assertValidTime as o, createTemporalSnapshot as r, createValidTime as s, CreateTemporalSnapshotInput as t, assertTransactionTime as u };
+//# sourceMappingURL=temporal-snapshot.d.cts.map

package/dist/temporal-snapshot.d.ts

@@ -0,0 +1,87 @@
+import { t as DeepReadonly } from "./immutable.js";
+
+//#region src/core/domain/temporal/transaction-time.d.ts
+
+/**
+ * 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. */
+  readonly recordedAt: Date;
+  /** When this information was superseded or invalidated by a newer version. */
+  readonly supersededAt?: Date;
+}
+type CreateTransactionTimeInput = TransactionTime;
+declare function assertTransactionTime(txTime: TransactionTime, fieldName?: string): void;
+declare function createTransactionTime(input: CreateTransactionTimeInput): TransactionTime;
+//#endregion
+//#region src/core/domain/temporal/valid-time.d.ts
+/**
+ * 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). */
+  readonly from: Date;
+  /** End of the validity window (exclusive). When absent, the information is still in effect. */
+  readonly to?: Date;
+}
+type CreateValidTimeInput = ValidTime;
+declare function assertValidTime(validTime: ValidTime, fieldName?: string): void;
+declare function createValidTime(input: CreateValidTimeInput): ValidTime;
+//#endregion
+//#region src/core/domain/temporal/temporal-snapshot.d.ts
+/**
+ * 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. */
+  readonly data: DeepReadonly<T>;
+  /** Period during which this datum was valid in the real world. */
+  readonly validTime: ValidTime;
+  /** Period during which this record was the state known to the system. */
+  readonly txTime: TransactionTime;
+}
+interface CreateTemporalSnapshotInput<T> {
+  readonly data: T;
+  readonly validTime: CreateValidTimeInput;
+  readonly txTime: CreateTransactionTimeInput;
+}
+declare function createTemporalSnapshot<T>(input: CreateTemporalSnapshotInput<T>): TemporalSnapshot<T>;
+//#endregion
+export { ValidTime as a, CreateTransactionTimeInput as c, createTransactionTime as d, CreateValidTimeInput as i, TransactionTime as l, TemporalSnapshot as n, assertValidTime as o, createTemporalSnapshot as r, createValidTime as s, CreateTemporalSnapshotInput as t, assertTransactionTime as u };
+//# sourceMappingURL=temporal-snapshot.d.ts.map

package/dist/temporal-use-case.cjs

@@ -1,8 +1,128 @@
+const require_app_error = require("./app-error.cjs");
 const require_not_found_error = require("./not-found-error.cjs");
+const require_temporal_guards = require("./temporal-guards.cjs");
 const require_unexpected_error = require("./unexpected-error.cjs");
 const require_immutable = require("./immutable.cjs");
-const require_use_case = require("./use-case.cjs");
-const require_temporal_guards = require("./temporal-guards.cjs");
+const require_decorate = require("./decorate.cjs");
+//#region src/core/application/use-case.ts
+const EXECUTION_COUNTER = "use_case.executions";
+const DURATION_HISTOGRAM = "use_case.duration_ms";
+let UseCase = class UseCase {
+	get contractVersion() {
+		return this.constructor.CONTRACT_VERSION;
+	}
+	/**
+	* Runs the use case.
+	*
+	* `run()` is the single seam every use case crosses, so it is where
+	* cross-cutting instrumentation lives. When {@link observability} exposes
+	* any adapter, the call to `execute()` is wrapped with tracing, metrics and
+	* failure logging; otherwise it delegates directly with no overhead.
+	*
+	* Observability is strictly side-effecting: a misbehaving adapter never
+	* changes the business result nor masks a thrown error — its own failures
+	* are swallowed.
+	*/
+	async run(input) {
+		const observability = this.observability();
+		if (!observability.logger && !observability.metrics && !observability.tracer) return await this.execute(input);
+		return await this.runInstrumented(input, observability);
+	}
+	/**
+	* Adapters used to instrument {@link run}. Override to opt a use case into
+	* tracing/metrics/logging. Returns an empty object by default, which keeps
+	* the plain delegating behavior.
+	*/
+	observability() {
+		return {};
+	}
+	/**
+	* Stable identity used for span names and metric labels. Defaults to the
+	* runtime class name; override when bundling/minification would otherwise
+	* erase a meaningful name.
+	*/
+	get useCaseName() {
+		return this.constructor.name;
+	}
+	/**
+	* 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.
+	*/
+	spanAttributes(_input) {
+		return {};
+	}
+	async runInstrumented(input, observability) {
+		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,
+			...attributes
+		}));
+		const startedAt = performance.now();
+		let outcome = "exception";
+		try {
+			const output = await this.execute(input);
+			outcome = output.isOk() ? "ok" : "error";
+			if (outcome === "error") {
+				const code = businessErrorCode(output);
+				safely(() => logger?.warn(`${name} returned a business error`, {
+					useCase: name,
+					...code ? { code } : {}
+				}));
+			}
+			safely(() => span?.setAttribute("use_case.outcome", outcome));
+			safely(() => metrics?.counter(EXECUTION_COUNTER, 1, {
+				useCase: name,
+				outcome,
+				...attributes
+			}));
+			return output;
+		} catch (error) {
+			safely(() => logger?.error(`${name} threw an unexpected error`, { useCase: name }));
+			safely(() => span?.setAttribute("use_case.outcome", "exception"));
+			safely(() => span?.recordException(error));
+			safely(() => metrics?.counter(EXECUTION_COUNTER, 1, {
+				useCase: name,
+				outcome: "exception",
+				...attributes
+			}));
+			throw error;
+		} finally {
+			safely(() => metrics?.histogram(DURATION_HISTOGRAM, performance.now() - startedAt, {
+				useCase: name,
+				outcome,
+				...attributes
+			}));
+			safely(() => span?.end());
+		}
+	}
+};
+UseCase = require_decorate.__decorate([require_immutable.version("1.0")], UseCase);
+/**
+* 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) {
+	const error = output.errorOrNull();
+	return error instanceof require_app_error.AppError ? error.code : void 0;
+}
+/**
+* Invokes an observability side effect, isolating any adapter failure so it
+* cannot alter the use case outcome.
+*/
+function safely(effect) {
+	try {
+		return effect();
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/core/application/commands/command.ts
 /**
 * Base for use cases that **mutate state** (writes), following CQS.
@@ -14,8 +134,18 @@ const require_temporal_guards = require("./temporal-guards.cjs");
 * The Command/Query distinction is semantic: the type declares the intent
 * before any implementation exists, guiding code review and API contracts.
 */
-let Command = class Command extends require_use_case.UseCase {};
-Command = require_immutable.__decorate([require_immutable.version("1.0")], Command);
+let Command = class Command extends UseCase {
+	/**
+	* Surfaces the actor's *kind* (`"user"` / `"system"`) on the span and
+	* metrics so a write can be sliced by origin. Only the low-cardinality
+	* `kind` is emitted — never the raw id, which would blow up label
+	* cardinality and could leak a user identifier into metrics.
+	*/
+	spanAttributes(input) {
+		return { "requested_by.kind": input.requestedBy.kind };
+	}
+};
+Command = require_decorate.__decorate([require_immutable.version("1.0")], Command);
 //#endregion
 //#region src/core/application/policy-error-mapper.ts
 function mapPolicyEvaluationError(err) {
@@ -36,11 +166,14 @@ function mapPolicyEvaluationError(err) {
 			policyKind: err.policyKind,
 			payloadSchemaVersion: err.payloadSchemaVersion
 		}, { cause: err.cause });
-		case "ENGINE_FAILURE": return new require_unexpected_error.UnexpectedError(err.message, err.cause, { metadata: {
-			policyKey: err.policyKey,
-			engine: err.engine,
-			engineVersion: err.engineVersion
-		} });
+		case "ENGINE_FAILURE": return new require_unexpected_error.UnexpectedError(err.message, err.cause, {
+			publicMessage: "Policy evaluation failed unexpectedly.",
+			metadata: {
+				policyKey: err.policyKey,
+				engine: err.engine,
+				engineVersion: err.engineVersion
+			}
+		});
 	}
 }
 //#endregion
@@ -58,12 +191,17 @@ function mapPolicyEvaluationError(err) {
 * A Query must never mutate persisted data — its execution must be idempotent
 * and safe to call multiple times with the same input.
 */
-let Query = class Query extends require_use_case.UseCase {
+let Query = class Query extends UseCase {
+	/**
+	* Declares how infrastructure should cache this query's result. Public so
+	* a caching adapter can actually read it off the instance; overrides must
+	* stay public.
+	*/
 	cacheStrategy() {
 		return { kind: "NO_CACHE" };
 	}
 };
-Query = require_immutable.__decorate([require_immutable.version("1.0")], Query);
+Query = require_decorate.__decorate([require_immutable.version("1.0")], Query);
 //#endregion
 //#region src/core/application/temporal/temporal-context.ts
 function assertTemporalContext(temporalContext, fieldName = "temporalContext") {
@@ -84,20 +222,34 @@ function createTemporalContext(input = {}) {
 }
 //#endregion
 //#region src/core/application/temporal/temporal-use-case.ts
-var TemporalUseCase = class extends require_use_case.UseCase {
+let TemporalUseCase = class TemporalUseCase extends UseCase {
 	resolveTemporalContext(input) {
 		return createTemporalContext(input.temporalContext);
 	}
+	/**
+	* Enriches a policy `ContextSeed` with `fields.now`, taken from the
+	* context's `requestedAt` (wall-clock time of the request).
+	*
+	* NOTE: this injects **only** `now` (from `requestedAt`) — it does *not*
+	* propagate `temporalContext.asOf`. Policy evaluation derives its own
+	* `asOf` from whichever seed field the policy's `asOfSource` points at
+	* (via `fields.now` by default). So a retroactive use case (an `asOf` in
+	* the past) will still evaluate policies at the *current* time unless the
+	* author maps `temporalContext.asOf` onto that seed field explicitly. Do
+	* that mapping in the use case when back-dated evaluation is intended.
+	*/
 	buildPolicySeed(seed, temporalContext) {
+		const fields = Object.freeze({
+			...seed.fields,
+			now: new Date(temporalContext.requestedAt.getTime())
+		});
 		return Object.freeze({
 			...seed,
-			fields: {
-				...seed.fields,
-				now: new Date(temporalContext.requestedAt.getTime())
-			}
+			fields
 		});
 	}
 };
+TemporalUseCase = require_decorate.__decorate([require_immutable.version("1.0")], TemporalUseCase);
 //#endregion
 Object.defineProperty(exports, "Command", {
 	enumerable: true,
@@ -117,6 +269,12 @@ Object.defineProperty(exports, "TemporalUseCase", {
 		return TemporalUseCase;
 	}
 });
+Object.defineProperty(exports, "UseCase", {
+	enumerable: true,
+	get: function() {
+		return UseCase;
+	}
+});
 Object.defineProperty(exports, "assertTemporalContext", {
 	enumerable: true,
 	get: function() {