@cullet/erp-core 1.1.0 → 1.3.0

package/dist/temporal-use-case.cjs

@@ -0,0 +1,191 @@
+const require_unexpected_error = require("./unexpected-error.cjs");
+const require_not_found_error = require("./not-found-error.cjs");
+const require_validation_code = require("./validation-code.cjs");
+const require_validation_field = require("./validation-field.cjs");
+const require_validation_exception = require("./validation-exception.cjs");
+const require_immutable = require("./immutable.cjs");
+const require_use_case = require("./use-case.cjs");
+const require_temporal_guards = require("./temporal-guards.cjs");
+//#region src/core/application/commands/requested-by.ts
+const REQUESTED_BY_FIELD = require_validation_field.ValidationField.of("requestedBy");
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+var RequestedBy = class RequestedBy {
+	constructor(kind, raw) {
+		this.kind = kind;
+		this.raw = raw;
+		Object.freeze(this);
+	}
+	/** Builds from a human user ID (must be a UUID). */
+	static fromUser(userId) {
+		if (!UUID_PATTERN.test(userId)) throw new require_validation_exception.InvalidValueException(REQUESTED_BY_FIELD, require_validation_code.ValidationCode.INVALID_FORMAT, `requestedBy: user identity must be a UUID, got "${userId}"`);
+		return new RequestedBy("user", userId);
+	}
+	/**
+	* Builds from a system identity.
+	* Only accepts the format "system:<job>", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.
+	*/
+	static fromSystem(systemIdentity) {
+		if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) throw new require_validation_exception.InvalidValueException(REQUESTED_BY_FIELD, require_validation_code.ValidationCode.INVALID_FORMAT, `requestedBy: system identity must match "system:<job>" (e.g. "system:late-fee-job"), got "${systemIdentity}"`);
+		return new RequestedBy("system", systemIdentity);
+	}
+	/**
+	* Infers the kind from the raw value.
+	* Use when the origin (user vs system) is not known at the call-site.
+	*/
+	static parse(raw) {
+		if (UUID_PATTERN.test(raw)) return new RequestedBy("user", raw);
+		if (SYSTEM_IDENTITY_PATTERN.test(raw)) return new RequestedBy("system", raw);
+		throw new require_validation_exception.InvalidValueException(REQUESTED_BY_FIELD, require_validation_code.ValidationCode.INVALID_FORMAT, `requestedBy must be a UUID (user) or "system:<job>" (system), got "${raw}"`);
+	}
+	get isUser() {
+		return this.kind === "user";
+	}
+	get isSystem() {
+		return this.kind === "system";
+	}
+	toString() {
+		return this.raw;
+	}
+};
+//#endregion
+//#region src/core/application/commands/command.ts
+/**
+* Base for use cases that **mutate state** (writes), following CQS.
+*
+* - `Input extends CommandInput` ensures every mutation records who triggered it.
+* - `Output extends Result<unknown, unknown>` ensures business errors are
+*   explicit values, never thrown exceptions.
+*
+* 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);
+//#endregion
+//#region src/core/application/policy-error-mapper.ts
+function mapPolicyEvaluationError(err) {
+	switch (err.kind) {
+		case "INVALID_CONTEXT": return new require_not_found_error.BusinessRuleViolationError(`policy.${err.stage.toLowerCase()}`, err.message, {
+			policyKey: err.policyKey,
+			stage: err.stage
+		}, { cause: err.cause });
+		case "INVALID_POLICY_KEY": return new require_not_found_error.BusinessRuleViolationError("policy.invalid_key", err.message, { rawPolicyKey: err.rawPolicyKey }, { cause: err.cause });
+		case "POLICY_NOT_FOUND": return new require_not_found_error.NotFoundError("Policy", { policyKey: err.policyKey }, { cause: err.cause });
+		case "POLICY_DEFINITION_NOT_FOUND": return new require_not_found_error.NotFoundError("PolicyDefinition", {
+			policyKey: err.policyKey,
+			contextVersion: err.contextVersion,
+			asOf: err.asOf.toISOString()
+		}, { cause: err.cause });
+		case "POLICY_VARIANT_NOT_FOUND": return new require_not_found_error.NotFoundError("PolicyVariant", {
+			policyKey: err.policyKey,
+			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
+		} });
+	}
+}
+//#endregion
+//#region src/core/application/queries/query.ts
+/**
+* Base for use cases that **only read state**, with no side effects, following CQS.
+*
+* - `Data extends QueryOutput` prevents a query from declaring a `void` or
+*   `undefined` success payload, while still allowing primitive projections
+*   and `null` when that makes sense for the read. Failures stay explicit in
+*   `Result<T, E>`.
+* - Override `cacheStrategy()` to declare how infrastructure should cache the
+*   result. By default, no cache is applied.
+*
+* 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 {
+	cacheStrategy() {
+		return { kind: "NO_CACHE" };
+	}
+};
+Query = require_immutable.__decorate([require_immutable.version("1.0")], Query);
+//#endregion
+//#region src/core/application/temporal/temporal-context.ts
+function assertTemporalContext(temporalContext, fieldName = "temporalContext") {
+	require_temporal_guards.assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);
+	require_temporal_guards.assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);
+}
+function createTemporalContext(input = {}) {
+	const requestedAt = input.requestedAt ?? /* @__PURE__ */ new Date();
+	const asOf = input.asOf ?? requestedAt;
+	assertTemporalContext({
+		asOf,
+		requestedAt
+	});
+	return require_immutable.makeImmutable({
+		asOf,
+		requestedAt
+	});
+}
+//#endregion
+//#region src/core/application/temporal/temporal-use-case.ts
+var TemporalUseCase = class extends require_use_case.UseCase {
+	resolveTemporalContext(input) {
+		return createTemporalContext(input.temporalContext);
+	}
+	buildPolicySeed(seed, temporalContext) {
+		return Object.freeze({
+			...seed,
+			fields: {
+				...seed.fields,
+				now: new Date(temporalContext.requestedAt.getTime())
+			}
+		});
+	}
+};
+//#endregion
+Object.defineProperty(exports, "Command", {
+	enumerable: true,
+	get: function() {
+		return Command;
+	}
+});
+Object.defineProperty(exports, "Query", {
+	enumerable: true,
+	get: function() {
+		return Query;
+	}
+});
+Object.defineProperty(exports, "RequestedBy", {
+	enumerable: true,
+	get: function() {
+		return RequestedBy;
+	}
+});
+Object.defineProperty(exports, "TemporalUseCase", {
+	enumerable: true,
+	get: function() {
+		return TemporalUseCase;
+	}
+});
+Object.defineProperty(exports, "assertTemporalContext", {
+	enumerable: true,
+	get: function() {
+		return assertTemporalContext;
+	}
+});
+Object.defineProperty(exports, "createTemporalContext", {
+	enumerable: true,
+	get: function() {
+		return createTemporalContext;
+	}
+});
+Object.defineProperty(exports, "mapPolicyEvaluationError", {
+	enumerable: true,
+	get: function() {
+		return mapPolicyEvaluationError;
+	}
+});
+
+//# sourceMappingURL=temporal-use-case.cjs.map

package/dist/temporal-use-case.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-use-case.cjs","names":["ValidationField","InvalidValueException","ValidationCode","UseCase","version","BusinessRuleViolationError","NotFoundError","UnexpectedError","UseCase","version","makeImmutable","UseCase"],"sources":["../src/core/application/commands/requested-by.ts","../src/core/application/commands/command.ts","../src/core/application/policy-error-mapper.ts","../src/core/application/queries/query.ts","../src/core/application/temporal/temporal-context.ts","../src/core/application/temporal/temporal-use-case.ts"],"sourcesContent":["import { ValidationCode } from \"../../exceptions/validation-code.js\";\nimport { InvalidValueException } from \"../../exceptions/validation-exception.js\";\nimport { ValidationField } from \"../../exceptions/validation-field.js\";\n\n// Identifies who triggered a Command.\n// Two valid formats:\n//   - Human user: UUID v4 (e.g.: \"550e8400-e29b-41d4-a716-446655440000\")\n//   - System identity: \"system:<job>\" where <job> is [a-z][a-z0-9]*(-[a-z0-9]+)*\n//     (e.g.: \"system:late-fee-job\", \"system:email-sender\")\n//\n// The split between `fromUser` / `fromSystem` / `parse` exists to make intent\n// explicit at the call-site: whoever builds the value knows where it came from.\n\ntype RequestedByKind = \"user\" | \"system\";\n\nconst REQUESTED_BY_FIELD = ValidationField.of(\"requestedBy\");\n\nconst UUID_PATTERN =\n    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n// system:<job> where <job> starts with a lowercase letter and may have hyphens between segments\nconst SYSTEM_IDENTITY_PATTERN = /^system:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\nclass RequestedBy {\n    readonly kind: RequestedByKind;\n    readonly raw: string;\n\n    private constructor(kind: RequestedByKind, raw: string) {\n        this.kind = kind;\n        this.raw = raw;\n        Object.freeze(this);\n    }\n\n    /** Builds from a human user ID (must be a UUID). */\n    static fromUser(userId: string): RequestedBy {\n        if (!UUID_PATTERN.test(userId)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: user identity must be a UUID, got \"${userId}\"`,\n            );\n        }\n\n        return new RequestedBy(\"user\", userId);\n    }\n\n    /**\n     * Builds from a system identity.\n     * Only accepts the format \"system:<job>\", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.\n     */\n    static fromSystem(systemIdentity: string): RequestedBy {\n        if (!SYSTEM_IDENTITY_PATTERN.test(systemIdentity)) {\n            throw new InvalidValueException(\n                REQUESTED_BY_FIELD,\n                ValidationCode.INVALID_FORMAT,\n                `requestedBy: system identity must match \"system:<job>\" (e.g. \"system:late-fee-job\"), got \"${systemIdentity}\"`,\n            );\n        }\n\n        return new RequestedBy(\"system\", systemIdentity);\n    }\n\n    /**\n     * Infers the kind from the raw value.\n     * Use when the origin (user vs system) is not known at the call-site.\n     */\n    static parse(raw: string): RequestedBy {\n        if (UUID_PATTERN.test(raw)) {\n            return new RequestedBy(\"user\", raw);\n        }\n\n        if (SYSTEM_IDENTITY_PATTERN.test(raw)) {\n            return new RequestedBy(\"system\", raw);\n        }\n\n        throw new InvalidValueException(\n            REQUESTED_BY_FIELD,\n            ValidationCode.INVALID_FORMAT,\n            `requestedBy must be a UUID (user) or \"system:<job>\" (system), got \"${raw}\"`,\n        );\n    }\n\n    get isUser(): boolean {\n        return this.kind === \"user\";\n    }\n\n    get isSystem(): boolean {\n        return this.kind === \"system\";\n    }\n\n    toString(): string {\n        return this.raw;\n    }\n}\n\nexport type { RequestedByKind };\nexport { RequestedBy };\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { Result } from \"../../result/result.js\";\n\nimport { RequestedBy } from \"./requested-by.js\";\n\ninterface CommandInput {\n    readonly requestedBy: RequestedBy;\n}\n\n/**\n * Base for use cases that **mutate state** (writes), following CQS.\n *\n * - `Input extends CommandInput` ensures every mutation records who triggered it.\n * - `Output extends Result<unknown, unknown>` ensures business errors are\n *   explicit values, never thrown exceptions.\n *\n * The Command/Query distinction is semantic: the type declares the intent\n * before any implementation exists, guiding code review and API contracts.\n */\n@version(\"1.0\")\nabstract class Command<\n    Input extends CommandInput,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> extends UseCase<Input, Output> {}\n\nexport type { CommandInput };\nexport { Command };\n","import {\n    type AppError,\n    BusinessRuleViolationError,\n    NotFoundError,\n    UnexpectedError,\n} from \"../errors/index.js\";\nimport type { PolicyEvaluationError } from \"../policies/index.js\";\n\nexport function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError {\n    switch (err.kind) {\n        case \"INVALID_CONTEXT\":\n            return new BusinessRuleViolationError(\n                `policy.${err.stage.toLowerCase()}`,\n                err.message,\n                { policyKey: err.policyKey, stage: err.stage },\n                { cause: err.cause },\n            );\n        case \"INVALID_POLICY_KEY\":\n            return new BusinessRuleViolationError(\n                \"policy.invalid_key\",\n                err.message,\n                { rawPolicyKey: err.rawPolicyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_NOT_FOUND\":\n            return new NotFoundError(\n                \"Policy\",\n                { policyKey: err.policyKey },\n                { cause: err.cause },\n            );\n        case \"POLICY_DEFINITION_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyDefinition\",\n                {\n                    policyKey: err.policyKey,\n                    contextVersion: err.contextVersion,\n                    asOf: err.asOf.toISOString(),\n                },\n                { cause: err.cause },\n            );\n        case \"POLICY_VARIANT_NOT_FOUND\":\n            return new NotFoundError(\n                \"PolicyVariant\",\n                {\n                    policyKey: err.policyKey,\n                    policyKind: err.policyKind,\n                    payloadSchemaVersion: err.payloadSchemaVersion,\n                },\n                { cause: err.cause },\n            );\n        case \"ENGINE_FAILURE\":\n            return new UnexpectedError(err.message, err.cause, {\n                metadata: {\n                    policyKey: err.policyKey,\n                    engine: err.engine,\n                    engineVersion: err.engineVersion,\n                },\n            });\n    }\n}\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { AppError } from \"../../errors/index.js\";\nimport type { Result } from \"../../result/result.js\";\n\n/**\n * Paginated result of a list query.\n * Use as `Output` when the query returns a collection with pagination metadata.\n */\ninterface Page<T> {\n    readonly items: readonly T[];\n    readonly total: number;\n    readonly page: number;\n    readonly pageSize: number;\n}\n\n/**\n * Cache strategy declared by the query type.\n * Infrastructure reads this value to decide whether and how to cache the result.\n */\ntype CacheStrategy =\n    | { readonly kind: \"NO_CACHE\" }\n    | { readonly kind: \"TIME_TO_LIVE\"; readonly ttlMs: number }\n    | { readonly kind: \"STALE_WHILE_REVALIDATE\"; readonly ttlMs: number };\n\ntype QueryOutput = object | string | number | boolean | bigint | symbol | null;\n\n/**\n * Base for use cases that **only read state**, with no side effects, following CQS.\n *\n * - `Data extends QueryOutput` prevents a query from declaring a `void` or\n *   `undefined` success payload, while still allowing primitive projections\n *   and `null` when that makes sense for the read. Failures stay explicit in\n *   `Result<T, E>`.\n * - Override `cacheStrategy()` to declare how infrastructure should cache the\n *   result. By default, no cache is applied.\n *\n * A Query must never mutate persisted data — its execution must be idempotent\n * and safe to call multiple times with the same input.\n */\n@version(\"1.0\")\nabstract class Query<\n    Input = void,\n    Data extends QueryOutput = never,\n    Failure = AppError,\n> extends UseCase<Input, Result<Data, Failure>> {\n    protected cacheStrategy(): CacheStrategy {\n        return { kind: \"NO_CACHE\" };\n    }\n}\n\nexport type { CacheStrategy, Page, QueryOutput };\nexport { Query };\n","import { makeImmutable } from \"../../shared/immutable.js\";\nimport { assertValidDate } from \"../../shared/temporal-guards.js\";\n\ninterface TemporalContext {\n    readonly asOf: Date;\n    readonly requestedAt: Date;\n}\n\ninterface CreateTemporalContextInput {\n    readonly asOf?: Date;\n    readonly requestedAt?: Date;\n}\n\nfunction assertTemporalContext(\n    temporalContext: TemporalContext,\n    fieldName: string = \"temporalContext\",\n): void {\n    assertValidDate(`${fieldName}.asOf`, temporalContext.asOf);\n    assertValidDate(`${fieldName}.requestedAt`, temporalContext.requestedAt);\n}\n\nfunction createTemporalContext(\n    input: CreateTemporalContextInput = {},\n): TemporalContext {\n    const requestedAt = input.requestedAt ?? new Date();\n    const asOf = input.asOf ?? requestedAt;\n\n    assertTemporalContext({ asOf, requestedAt });\n\n    return makeImmutable({\n        asOf,\n        requestedAt,\n    });\n}\n\nexport {\n    assertTemporalContext,\n    createTemporalContext,\n    type CreateTemporalContextInput,\n    type TemporalContext,\n};\n","import { UseCase } from \"../use-case.js\";\nimport type { ContextSeed } from \"../../policies/index.js\";\nimport type { Result } from \"../../result/result.js\";\n\nimport {\n    createTemporalContext,\n    type TemporalContext,\n} from \"./temporal-context.js\";\n\ninterface TemporalUseCaseInput {\n    readonly temporalContext?: TemporalContext;\n}\n\n/**\n * A {@link ContextSeed} after temporal enrichment by\n * {@link TemporalUseCase.buildPolicySeed}: structurally identical to `TSeed`,\n * except `fields.now` is now guaranteed present as a `Date` (injected from the\n * resolved {@link TemporalContext}). Downstream policies can therefore read\n * `seed.fields.now` without a presence/type guard.\n */\ntype TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<\n    TSeed,\n    \"fields\"\n> & {\n    readonly fields: TSeed[\"fields\"] & { readonly now: Date };\n};\n\nabstract class TemporalUseCase<\n    Input extends object,\n    Output extends Result<unknown, unknown>,\n> extends UseCase<Input & TemporalUseCaseInput, Output> {\n    protected resolveTemporalContext(\n        input: Input & TemporalUseCaseInput,\n    ): TemporalContext {\n        return createTemporalContext(input.temporalContext);\n    }\n\n    protected buildPolicySeed<TSeed extends ContextSeed>(\n        seed: TSeed,\n        temporalContext: TemporalContext,\n    ): TemporalizedContextSeed<TSeed> {\n        return Object.freeze({\n            ...seed,\n            fields: {\n                ...seed.fields,\n                now: new Date(temporalContext.requestedAt.getTime()),\n            },\n        }) as TemporalizedContextSeed<TSeed>;\n    }\n}\n\nexport type { TemporalizedContextSeed, TemporalUseCaseInput };\nexport { TemporalUseCase };\n"],"mappings":"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"}

package/dist/temporal-use-case.d.cts

@@ -0,0 +1,304 @@
+import { n as ContractVersion } from "./version.cjs";
+import { a as Result } from "./outcome.cjs";
+import { t as AppError } from "./app-error.cjs";
+import { b as ContextSeed, r as PolicyEvaluationResult, s as PolicyEvaluationError, t as EvaluateInput } from "./policy-service.cjs";
+import { t as DeepReadonly } from "./immutable.cjs";
+
+//#region src/core/application/ports/logger.port.d.ts
+type LogPayload = Record<string, unknown>;
+interface LoggerPort {
+  debug(message: string, payload?: LogPayload): void;
+  info(message: string, payload?: LogPayload): void;
+  warn(message: string, payload?: LogPayload): void;
+  error(message: string, payload?: LogPayload): void;
+}
+//#endregion
+//#region src/core/application/ports/metrics.port.d.ts
+type MetricLabels = Readonly<Record<string, string | number | boolean>>;
+interface MetricsPort {
+  counter(name: string, value: number, labels?: MetricLabels): void;
+  gauge(name: string, value: number, labels?: MetricLabels): void;
+  histogram(name: string, value: number, labels?: MetricLabels): void;
+}
+//#endregion
+//#region src/core/application/ports/tracer.port.d.ts
+type TraceAttributeValue = string | number | boolean;
+interface TraceSpan {
+  setAttribute(key: string, value: TraceAttributeValue): void;
+  recordException(error: unknown): void;
+  end(): void;
+}
+interface TracerPort {
+  startSpan(name: string, attributes?: Record<string, TraceAttributeValue>): TraceSpan;
+}
+//#endregion
+//#region src/core/application/use-case.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Observability adapters a use case may opt into.
+ *
+ * All fields are optional: a use case that provides none keeps the plain
+ * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}
+ * instruments every execution around `execute()` — opening a span, recording
+ * duration, counting outcomes, and logging business/unexpected failures.
+ */
+interface UseCaseObservability {
+  readonly logger?: LoggerPort;
+  readonly metrics?: MetricsPort;
+  readonly tracer?: TracerPort;
+}
+declare abstract class UseCase<Input = void, Output extends Result<unknown, unknown> = Result<void, never>> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  get contractVersion(): ContractVersion;
+  /**
+   * 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.
+   */
+  run(input: Input): Promise<Output>;
+  /**
+   * 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.
+   */
+  protected observability(): UseCaseObservability;
+  /**
+   * 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.
+   */
+  protected get useCaseName(): string;
+  protected abstract execute(input: Input): MaybePromise<Output>;
+  private runInstrumented;
+}
+//#endregion
+//#region src/core/application/commands/requested-by.d.ts
+type RequestedByKind = "user" | "system";
+declare class RequestedBy {
+  readonly kind: RequestedByKind;
+  readonly raw: string;
+  private constructor();
+  /** Builds from a human user ID (must be a UUID). */
+  static fromUser(userId: string): RequestedBy;
+  /**
+   * Builds from a system identity.
+   * Only accepts the format "system:<job>", where <job> matches [a-z][a-z0-9]*(-[a-z0-9]+)*.
+   */
+  static fromSystem(systemIdentity: string): RequestedBy;
+  /**
+   * Infers the kind from the raw value.
+   * Use when the origin (user vs system) is not known at the call-site.
+   */
+  static parse(raw: string): RequestedBy;
+  get isUser(): boolean;
+  get isSystem(): boolean;
+  toString(): string;
+}
+//#endregion
+//#region src/core/application/commands/command.d.ts
+interface CommandInput {
+  readonly requestedBy: RequestedBy;
+}
+/**
+ * Base for use cases that **mutate state** (writes), following CQS.
+ *
+ * - `Input extends CommandInput` ensures every mutation records who triggered it.
+ * - `Output extends Result<unknown, unknown>` ensures business errors are
+ *   explicit values, never thrown exceptions.
+ *
+ * The Command/Query distinction is semantic: the type declares the intent
+ * before any implementation exists, guiding code review and API contracts.
+ */
+declare abstract class Command<Input extends CommandInput, Output extends Result<unknown, unknown> = Result<void, never>> extends UseCase<Input, Output> {}
+//#endregion
+//#region src/core/application/ports/policy-port.d.ts
+type PolicyEvaluationInput = EvaluateInput;
+type PolicyEvaluationOutput = PolicyEvaluationResult;
+/**
+ * Failure surfaced by {@link PolicyPort.evaluate}.
+ *
+ * This is the *post-mapping* boundary: the structured `PolicyEvaluationError`
+ * union produced inside the policies module is expected to have already been
+ * translated into an {@link AppError} (e.g. via `mapPolicyEvaluationError`)
+ * before it reaches a use case. Named distinctly from the policies-layer
+ * `PolicyEvaluationError` to avoid a collision on the public surface.
+ */
+type PolicyPortError = AppError;
+interface PolicyPort {
+  evaluate(input: PolicyEvaluationInput): Promise<Result<PolicyEvaluationOutput, PolicyPortError>>;
+}
+//#endregion
+//#region src/core/application/ports/repository.port.d.ts
+/**
+ * Persistence port for an aggregate in the imperative style: absence is
+ * modelled as `null`, and failures (missing row on delete, optimistic
+ * concurrency conflicts, infrastructure errors) surface as thrown exceptions.
+ *
+ * Prefer {@link ResultRepository} when you want those persistence outcomes to
+ * be explicit, recoverable values rather than exceptions.
+ */
+interface Repository<TEntity, TId> {
+  findById(id: TId): Promise<TEntity | null>;
+  save(entity: TEntity): Promise<void>;
+  delete(id: TId): Promise<void>;
+}
+/**
+ * `Result`-returning counterpart of {@link Repository}, aligned with the
+ * "errors as values" philosophy used by `Command` / `UseCase`.
+ *
+ * Where {@link Repository} returns `Promise<void>` from `save`/`delete` and
+ * relies on thrown exceptions, this variant lets a repository *signal*
+ * recoverable persistence outcomes without breaking control flow — for
+ * example a `NotFoundError` when updating/deleting a missing aggregate, or a
+ * `ConflictError` on an optimistic-concurrency version mismatch. A successful
+ * write resolves to `Result.ok(undefined)`.
+ *
+ * `findById` keeps `null` as the "not present" answer to a lookup (not an
+ * error) while still wrapping the call in a `Result` so genuine failures
+ * (e.g. a connectivity error) stay in band.
+ *
+ * `TError` defaults to {@link AppError} to match the rest of the application
+ * boundary (see `PolicyPortError`); narrow it per repository when the failure
+ * set is known, e.g. `ResultRepository<Order, OrderId, NotFoundError | ConflictError>`.
+ */
+interface ResultRepository<TEntity, TId, TError = AppError> {
+  findById(id: TId): Promise<Result<TEntity | null, TError>>;
+  save(entity: TEntity): Promise<Result<void, TError>>;
+  delete(id: TId): Promise<Result<void, TError>>;
+}
+//#endregion
+//#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.
+ */
+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;
+}
+//#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.
+ */
+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;
+}
+//#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.
+ */
+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;
+}
+//#endregion
+//#region src/core/application/ports/temporal-repository.port.d.ts
+type TemporalHistory<TEntity> = readonly TemporalSnapshot<TEntity>[];
+interface TemporalRepository<TEntity, TId> extends Repository<TEntity, TId> {
+  findAsOf(id: TId, asOf: Date): Promise<TEntity | null>;
+  findAtTransaction(id: TId, txTime: Date): Promise<TEntity | null>;
+  findHistory(id: TId): Promise<TemporalHistory<TEntity>>;
+  save(entity: TEntity, validFrom?: Date): Promise<void>;
+}
+//#endregion
+//#region src/core/application/policy-error-mapper.d.ts
+declare function mapPolicyEvaluationError(err: PolicyEvaluationError): AppError;
+//#endregion
+//#region src/core/application/queries/query.d.ts
+/**
+ * Paginated result of a list query.
+ * Use as `Output` when the query returns a collection with pagination metadata.
+ */
+interface Page<T> {
+  readonly items: readonly T[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+}
+/**
+ * Cache strategy declared by the query type.
+ * Infrastructure reads this value to decide whether and how to cache the result.
+ */
+type CacheStrategy = {
+  readonly kind: "NO_CACHE";
+} | {
+  readonly kind: "TIME_TO_LIVE";
+  readonly ttlMs: number;
+} | {
+  readonly kind: "STALE_WHILE_REVALIDATE";
+  readonly ttlMs: number;
+};
+type QueryOutput = object | string | number | boolean | bigint | symbol | null;
+/**
+ * Base for use cases that **only read state**, with no side effects, following CQS.
+ *
+ * - `Data extends QueryOutput` prevents a query from declaring a `void` or
+ *   `undefined` success payload, while still allowing primitive projections
+ *   and `null` when that makes sense for the read. Failures stay explicit in
+ *   `Result<T, E>`.
+ * - Override `cacheStrategy()` to declare how infrastructure should cache the
+ *   result. By default, no cache is applied.
+ *
+ * A Query must never mutate persisted data — its execution must be idempotent
+ * and safe to call multiple times with the same input.
+ */
+declare abstract class Query<Input = void, Data extends QueryOutput = never, Failure = AppError> extends UseCase<Input, Result<Data, Failure>> {
+  protected cacheStrategy(): CacheStrategy;
+}
+//#endregion
+//#region src/core/application/temporal/temporal-context.d.ts
+interface TemporalContext {
+  readonly asOf: Date;
+  readonly requestedAt: Date;
+}
+interface CreateTemporalContextInput {
+  readonly asOf?: Date;
+  readonly requestedAt?: Date;
+}
+declare function assertTemporalContext(temporalContext: TemporalContext, fieldName?: string): void;
+declare function createTemporalContext(input?: CreateTemporalContextInput): TemporalContext;
+//#endregion
+//#region src/core/application/temporal/temporal-use-case.d.ts
+interface TemporalUseCaseInput {
+  readonly temporalContext?: TemporalContext;
+}
+/**
+ * A {@link ContextSeed} after temporal enrichment by
+ * {@link TemporalUseCase.buildPolicySeed}: structurally identical to `TSeed`,
+ * except `fields.now` is now guaranteed present as a `Date` (injected from the
+ * resolved {@link TemporalContext}). Downstream policies can therefore read
+ * `seed.fields.now` without a presence/type guard.
+ */
+type TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<TSeed, "fields"> & {
+  readonly fields: TSeed["fields"] & {
+    readonly now: Date;
+  };
+};
+declare abstract class TemporalUseCase<Input extends object, Output extends Result<unknown, unknown>> extends UseCase<Input & TemporalUseCaseInput, Output> {
+  protected resolveTemporalContext(input: Input & TemporalUseCaseInput): TemporalContext;
+  protected buildPolicySeed<TSeed extends ContextSeed>(seed: TSeed, temporalContext: TemporalContext): TemporalizedContextSeed<TSeed>;
+}
+//#endregion
+export { MetricLabels as A, RequestedByKind as C, TraceAttributeValue as D, UseCaseObservability as E, LogPayload as M, LoggerPort as N, TraceSpan as O, RequestedBy as S, UseCase as T, PolicyEvaluationOutput as _, TemporalContext as a, Command as b, CacheStrategy as c, mapPolicyEvaluationError as d, TemporalHistory as f, PolicyEvaluationInput as g, ResultRepository as h, CreateTemporalContextInput as i, MetricsPort as j, TracerPort as k, Page as l, Repository as m, TemporalUseCaseInput as n, assertTemporalContext as o, TemporalRepository as p, TemporalizedContextSeed as r, createTemporalContext as s, TemporalUseCase as t, Query as u, PolicyPort as v, MaybePromise as w, CommandInput as x, PolicyPortError as y };
+//# sourceMappingURL=temporal-use-case.d.cts.map

package/dist/temporal-use-case.d.ts

@@ -1,10 +1,9 @@
-import { I as Result } from "./gate-types.js";
+import { n as ContractVersion } from "./version.js";
+import { a as Result } from "./outcome.js";
 import { t as AppError } from "./app-error.js";
 import { b as ContextSeed, r as PolicyEvaluationResult, s as PolicyEvaluationError, t as EvaluateInput } from "./policy-service.js";
+import { t as DeepReadonly } from "./immutable.js";
 
-//#region src/core/versioning/version.d.ts
-type ContractVersion = `${number}.${number}`;
-//#endregion
 //#region src/core/application/ports/logger.port.d.ts
 type LogPayload = Record<string, unknown>;
 interface LoggerPort {
@@ -200,10 +199,6 @@ interface ValidTime {
   readonly to?: Date;
 }
 //#endregion
-//#region src/core/shared/immutable.d.ts
-type PrimitiveValue = bigint | boolean | null | number | string | symbol | undefined;
-type DeepReadonly<T> = T extends PrimitiveValue | Date ? T : T extends readonly (infer TItem)[] ? readonly DeepReadonly<TItem>[] : { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> };
-//#endregion
 //#region src/core/domain/temporal/temporal-snapshot.d.ts
 /**
  * Pairs a domain datum with its time dimensions (Business and Transaction).
@@ -305,5 +300,5 @@ declare abstract class TemporalUseCase<Input extends object, Output extends Resu
   protected buildPolicySeed<TSeed extends ContextSeed>(seed: TSeed, temporalContext: TemporalContext): TemporalizedContextSeed<TSeed>;
 }
 //#endregion
-export { TracerPort as A, RequestedBy as C, UseCaseObservability as D, UseCase as E, ContractVersion as F, MetricsPort as M, LogPayload as N, TraceAttributeValue as O, LoggerPort as P, CommandInput as S, MaybePromise as T, PolicyEvaluationInput as _, TemporalContext as a, PolicyPortError as b, CacheStrategy as c, mapPolicyEvaluationError as d, TemporalHistory as f, ResultRepository as g, Repository as h, CreateTemporalContextInput as i, MetricLabels as j, TraceSpan as k, Page as l, DeepReadonly as m, TemporalUseCaseInput as n, assertTemporalContext as o, TemporalRepository as p, TemporalizedContextSeed as r, createTemporalContext as s, TemporalUseCase as t, Query as u, PolicyEvaluationOutput as v, RequestedByKind as w, Command as x, PolicyPort as y };
+export { MetricLabels as A, RequestedByKind as C, TraceAttributeValue as D, UseCaseObservability as E, LogPayload as M, LoggerPort as N, TraceSpan as O, RequestedBy as S, UseCase as T, PolicyEvaluationOutput as _, TemporalContext as a, Command as b, CacheStrategy as c, mapPolicyEvaluationError as d, TemporalHistory as f, PolicyEvaluationInput as g, ResultRepository as h, CreateTemporalContextInput as i, MetricsPort as j, TracerPort as k, Page as l, Repository as m, TemporalUseCaseInput as n, assertTemporalContext as o, TemporalRepository as p, TemporalizedContextSeed as r, createTemporalContext as s, TemporalUseCase as t, Query as u, PolicyPort as v, MaybePromise as w, CommandInput as x, PolicyPortError as y };
 //# sourceMappingURL=temporal-use-case.d.ts.map