@cullet/erp-core 1.5.0 → 2.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"temporal-use-case.cjs","names":["UseCase","version","BusinessRuleViolationError","NotFoundError","UnexpectedError","UseCase","version","makeImmutable","UseCase"],"sources":["../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 { 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    /**\n     * Declares how infrastructure should cache this query's result. Public so\n     * a caching adapter can actually read it off the instance; overrides must\n     * stay public.\n     */\n    public 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":";;;;;;;;;;;;;;;;AAoBA,IAAA,UAAA,MACe,gBAGLA,iBAAAA,QAAuB,CAAC;wCAJjCC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,OAAA;;;ACZd,SAAgB,yBAAyB,KAAsC;CAC3E,QAAQ,IAAI,MAAZ;EACI,KAAK,mBACD,OAAO,IAAIC,wBAAAA,2BACP,UAAU,IAAI,MAAM,YAAY,KAChC,IAAI,SACJ;GAAE,WAAW,IAAI;GAAW,OAAO,IAAI;EAAM,GAC7C,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,sBACD,OAAO,IAAIA,wBAAAA,2BACP,sBACA,IAAI,SACJ,EAAE,cAAc,IAAI,aAAa,GACjC,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,oBACD,OAAO,IAAIC,wBAAAA,cACP,UACA,EAAE,WAAW,IAAI,UAAU,GAC3B,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,+BACD,OAAO,IAAIA,wBAAAA,cACP,oBACA;GACI,WAAW,IAAI;GACf,gBAAgB,IAAI;GACpB,MAAM,IAAI,KAAK,YAAY;EAC/B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,4BACD,OAAO,IAAIA,wBAAAA,cACP,iBACA;GACI,WAAW,IAAI;GACf,YAAY,IAAI;GAChB,sBAAsB,IAAI;EAC9B,GACA,EAAE,OAAO,IAAI,MAAM,CACvB;EACJ,KAAK,kBACD,OAAO,IAAIC,yBAAAA,gBAAgB,IAAI,SAAS,IAAI,OAAO,EAC/C,UAAU;GACN,WAAW,IAAI;GACf,QAAQ,IAAI;GACZ,eAAe,IAAI;EACvB,EACJ,CAAC;CACT;AACJ;;;;;;;;;;;;;;;;ACnBA,IAAA,QAAA,MACe,cAILC,iBAAAA,QAAsC;;;;;;CAM5C,gBAAsC;EAClC,OAAO,EAAE,MAAM,WAAW;CAC9B;AACJ;sCAdCC,kBAAAA,QAAQ,KAAK,CAAA,GAAA,KAAA;;;AC3Bd,SAAS,sBACL,iBACA,YAAoB,mBAChB;CACJ,wBAAA,gBAAgB,GAAG,UAAU,QAAQ,gBAAgB,IAAI;CACzD,wBAAA,gBAAgB,GAAG,UAAU,eAAe,gBAAgB,WAAW;AAC3E;AAEA,SAAS,sBACL,QAAoC,CAAC,GACtB;CACf,MAAM,cAAc,MAAM,+BAAe,IAAI,KAAK;CAClD,MAAM,OAAO,MAAM,QAAQ;CAE3B,sBAAsB;EAAE;EAAM;CAAY,CAAC;CAE3C,OAAOC,kBAAAA,cAAc;EACjB;EACA;CACJ,CAAC;AACL;;;ACNA,IAAe,kBAAf,cAGUC,iBAAAA,QAA8C;CACpD,uBACI,OACe;EACf,OAAO,sBAAsB,MAAM,eAAe;CACtD;CAEA,gBACI,MACA,iBAC8B;EAC9B,OAAO,OAAO,OAAO;GACjB,GAAG;GACH,QAAQ;IACJ,GAAG,KAAK;IACR,KAAK,IAAI,KAAK,gBAAgB,YAAY,QAAQ,CAAC;GACvD;EACJ,CAAC;CACL;AACJ"}
+{"version":3,"file":"temporal-use-case.cjs","names":["version","AppError","version","BusinessRuleViolationError","NotFoundError","UnexpectedError","version","makeImmutable","version"],"sources":["../src/core/application/use-case.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 { type ContractVersion, version } from \"../versioning/version.js\";\nimport { AppError } from \"../errors/index.js\";\nimport type { Result } from \"../result/result.js\";\n\nimport type { LoggerPort } from \"./ports/logger.port.js\";\nimport type { MetricsPort } from \"./ports/metrics.port.js\";\nimport type { TraceAttributeValue, TracerPort } from \"./ports/tracer.port.js\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * Observability adapters a use case may opt into.\n *\n * All fields are optional: a use case that provides none keeps the plain\n * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}\n * instruments every execution around `execute()` — opening a span, recording\n * duration, counting outcomes, and logging business/unexpected failures.\n */\ninterface UseCaseObservability {\n    readonly logger?: LoggerPort;\n    readonly metrics?: MetricsPort;\n    readonly tracer?: TracerPort;\n}\n\nconst EXECUTION_COUNTER = \"use_case.executions\";\nconst DURATION_HISTOGRAM = \"use_case.duration_ms\";\n\ntype ExecutionOutcome = \"ok\" | \"error\" | \"exception\";\n\n@version(\"1.0\")\nabstract class UseCase<\n    Input = void,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    public get contractVersion(): ContractVersion {\n        return (this.constructor as typeof UseCase).CONTRACT_VERSION;\n    }\n\n    /**\n     * Runs the use case.\n     *\n     * `run()` is the single seam every use case crosses, so it is where\n     * cross-cutting instrumentation lives. When {@link observability} exposes\n     * any adapter, the call to `execute()` is wrapped with tracing, metrics and\n     * failure logging; otherwise it delegates directly with no overhead.\n     *\n     * Observability is strictly side-effecting: a misbehaving adapter never\n     * changes the business result nor masks a thrown error — its own failures\n     * are swallowed.\n     */\n    public async run(input: Input): Promise<Output> {\n        const observability = this.observability();\n        if (\n            !observability.logger &&\n            !observability.metrics &&\n            !observability.tracer\n        ) {\n            return await this.execute(input);\n        }\n\n        return await this.runInstrumented(input, observability);\n    }\n\n    /**\n     * Adapters used to instrument {@link run}. Override to opt a use case into\n     * tracing/metrics/logging. Returns an empty object by default, which keeps\n     * the plain delegating behavior.\n     */\n    protected observability(): UseCaseObservability {\n        return {};\n    }\n\n    /**\n     * Stable identity used for span names and metric labels. Defaults to the\n     * runtime class name; override when bundling/minification would otherwise\n     * erase a meaningful name.\n     */\n    protected get useCaseName(): string {\n        return this.constructor.name;\n    }\n\n    protected abstract execute(input: Input): MaybePromise<Output>;\n\n    /**\n     * Extra attributes stamped onto the span and every metric emitted for this\n     * execution. Override to attach stable, **low-cardinality** dimensions\n     * (e.g. `Command` adds `requested_by.kind`). Keep values bounded — they\n     * become metric label values, so a user id or free-form string here would\n     * explode the metric's cardinality. Defaults to none.\n     */\n    protected spanAttributes(\n        _input: Input,\n    ): Readonly<Record<string, TraceAttributeValue>> {\n        return {};\n    }\n\n    private async runInstrumented(\n        input: Input,\n        observability: UseCaseObservability,\n    ): Promise<Output> {\n        const { logger, metrics, tracer } = observability;\n        const name = this.useCaseName;\n        const attributes = safely(() => this.spanAttributes(input)) ?? {};\n        const span = safely(() =>\n            tracer?.startSpan(name, { \"use_case.name\": name, ...attributes }),\n        );\n        const startedAt = performance.now();\n        // Declared here (not inside `try`) so the `finally` histogram can label\n        // duration by outcome; defaults to \"exception\" and is overwritten once\n        // execute() returns without throwing.\n        let outcome: ExecutionOutcome = \"exception\";\n\n        try {\n            const output = await this.execute(input);\n            outcome = output.isOk() ? \"ok\" : \"error\";\n\n            if (outcome === \"error\") {\n                const code = businessErrorCode(output);\n                safely(() =>\n                    logger?.warn(`${name} returned a business error`, {\n                        useCase: name,\n                        ...(code ? { code } : {}),\n                    }),\n                );\n            }\n            safely(() => span?.setAttribute(\"use_case.outcome\", outcome));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome,\n                    ...attributes,\n                }),\n            );\n\n            return output;\n        } catch (error) {\n            safely(() =>\n                logger?.error(`${name} threw an unexpected error`, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.setAttribute(\"use_case.outcome\", \"exception\"));\n            safely(() => span?.recordException(error));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome: \"exception\",\n                    ...attributes,\n                }),\n            );\n\n            throw error;\n        } finally {\n            safely(() =>\n                metrics?.histogram(\n                    DURATION_HISTOGRAM,\n                    performance.now() - startedAt,\n                    { useCase: name, outcome, ...attributes },\n                ),\n            );\n            safely(() => span?.end());\n        }\n    }\n}\n\n/**\n * Pulls the stable `code` off a business-error `Result` for logging. Returns\n * `undefined` when the error is not an {@link AppError} — the code is safe to\n * log (it's the public contract), unlike the message which may carry PII.\n */\nfunction businessErrorCode(\n    output: Result<unknown, unknown>,\n): string | undefined {\n    const error = output.errorOrNull();\n    return error instanceof AppError ? error.code : undefined;\n}\n\n/**\n * Invokes an observability side effect, isolating any adapter failure so it\n * cannot alter the use case outcome.\n */\nfunction safely<R>(effect: () => R): R | undefined {\n    try {\n        return effect();\n    } catch {\n        return undefined;\n    }\n}\n\nexport { type MaybePromise, UseCase, type UseCaseObservability };\n","import { UseCase } from \"../use-case.js\";\nimport { version } from \"../../versioning/version.js\";\nimport type { TraceAttributeValue } from \"../ports/tracer.port.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    /**\n     * Surfaces the actor's *kind* (`\"user\"` / `\"system\"`) on the span and\n     * metrics so a write can be sliced by origin. Only the low-cardinality\n     * `kind` is emitted — never the raw id, which would blow up label\n     * cardinality and could leak a user identifier into metrics.\n     */\n    protected override spanAttributes(\n        input: Input,\n    ): Readonly<Record<string, TraceAttributeValue>> {\n        return { \"requested_by.kind\": input.requestedBy.kind };\n    }\n}\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            // `engine`/`engineVersion` are internal detail kept in `metadata`\n            // for logs. `publicMessage` gives the HTTP boundary a safe string\n            // to expose so it never has to serialize this metadata to a client\n            // on a 500. (Whether the boundary leaks `metadata` is still its\n            // call — this only hands it the non-leaking alternative.)\n            return new UnexpectedError(err.message, err.cause, {\n                publicMessage: \"Policy evaluation failed unexpectedly.\",\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 (offset-based).\n * Use as `Output` when the query returns a collection with pagination metadata.\n * For cursor/keyset pagination, model your own `Output` type instead.\n */\ninterface Page<T> {\n    readonly items: readonly T[];\n    /** Total rows across all pages, ignoring `page`/`pageSize`. */\n    readonly total: number;\n    /** 1-based page number (the first page is `1`, not `0`). */\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 *\n * These are pure descriptors: the type cannot enforce that a duration is finite\n * and positive, so the caching adapter must validate `ttlMs` /\n * `staleWhileRevalidateMs` (`> 0`, finite) before honoring the strategy.\n */\ntype CacheStrategy =\n    | { readonly kind: \"NO_CACHE\" }\n    | { readonly kind: \"TIME_TO_LIVE\"; readonly ttlMs: number }\n    | {\n          readonly kind: \"STALE_WHILE_REVALIDATE\";\n          /** How long the entry is served fresh. */\n          readonly ttlMs: number;\n          /**\n           * How long *after* `ttlMs` a stale entry may still be served while a\n           * background refresh runs. SWR needs both windows; a single TTL is\n           * ambiguous and each adapter would guess the second one.\n           */\n          readonly staleWhileRevalidateMs: number;\n      };\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    /**\n     * Declares how infrastructure should cache this query's result. Public so\n     * a caching adapter can actually read it off the instance; overrides must\n     * stay public.\n     */\n    public 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 { version } from \"../../versioning/version.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\n/**\n * Marker mixed into a temporal use case's `Input`.\n *\n * The consumer's `Input` must not re-declare `temporalContext` with an\n * incompatible type: `TemporalUseCase` intersects the two, and a clashing\n * declaration collapses the field to `never` (surfacing only as a confusing\n * error at the call site, not here).\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\n@version(\"1.0\")\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    /**\n     * Enriches a policy `ContextSeed` with `fields.now`, taken from the\n     * context's `requestedAt` (wall-clock time of the request).\n     *\n     * NOTE: this injects **only** `now` (from `requestedAt`) — it does *not*\n     * propagate `temporalContext.asOf`. Policy evaluation derives its own\n     * `asOf` from whichever seed field the policy's `asOfSource` points at\n     * (via `fields.now` by default). So a retroactive use case (an `asOf` in\n     * the past) will still evaluate policies at the *current* time unless the\n     * author maps `temporalContext.asOf` onto that seed field explicitly. Do\n     * that mapping in the use case when back-dated evaluation is intended.\n     */\n    protected buildPolicySeed<TSeed extends ContextSeed>(\n        seed: TSeed,\n        temporalContext: TemporalContext,\n    ): TemporalizedContextSeed<TSeed> {\n        // ponytail: shallow-freeze the two objects we create (outer + fields);\n        // nested `fields` values belong to the caller's seed — not ours to\n        // deep-freeze (would freeze shared refs) or structuredClone (would\n        // flatten any class instances the seed carries).\n        const fields = Object.freeze({\n            ...seed.fields,\n            now: new Date(temporalContext.requestedAt.getTime()),\n        });\n        return Object.freeze({\n            ...seed,\n            fields,\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

@@ -1,9 +1,9 @@
 import { t as RequestedBy } from "./requested-by.cjs";
 import { t as AppError } from "./app-error.cjs";
 import { r as Result } from "./result.cjs";
-import { t as DeepReadonly } from "./immutable.cjs";
 import { n as ContractVersion } from "./version.cjs";
 import { b as ContextSeed, r as PolicyEvaluationResult, s as PolicyEvaluationError, t as EvaluateInput } from "./policy-service.cjs";
+import { n as TemporalSnapshot } from "./temporal-snapshot.cjs";
 
 //#region src/core/application/ports/logger.port.d.ts
 type LogPayload = Record<string, unknown>;
@@ -77,6 +77,14 @@ declare abstract class UseCase<Input = void, Output extends Result<unknown, unkn
    */
   protected get useCaseName(): string;
   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>>;
   private runInstrumented;
 }
 //#endregion
@@ -94,7 +102,15 @@ interface CommandInput {
  * 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> {}
+declare abstract class Command<Input extends CommandInput, Output extends Result<unknown, unknown> = Result<void, never>> extends UseCase<Input, Output> {
+  /**
+   * 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.
+   */
+  protected spanAttributes(input: Input): Readonly<Record<string, TraceAttributeValue>>;
+}
 //#endregion
 //#region src/core/application/ports/policy-port.d.ts
 type PolicyEvaluationInput = EvaluateInput;
@@ -152,71 +168,61 @@ interface ResultRepository<TEntity, TId, TError = AppError> {
   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>[];
+/**
+ * Bitemporal persistence port in the imperative (exception-raising) style.
+ *
+ * `delete(id)` is inherited from {@link Repository} and its bitemporal meaning
+ * is intentionally left to the implementation: it may close the current
+ * valid-time interval (a logical end-of-validity that preserves history) or
+ * physically purge the row's whole history. Pick one per adapter and document
+ * it — callers cannot tell which from this type. Prefer closing validity so
+ * `findAsOf`/`findHistory` stay meaningful for past instants.
+ */
 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>;
 }
+/**
+ * `Result`-returning counterpart of {@link TemporalRepository}, aligned with the
+ * "errors as values" philosophy (mirrors the {@link Repository} /
+ * {@link ResultRepository} pair). The `delete` semantics note above applies
+ * unchanged.
+ */
+interface ResultTemporalRepository<TEntity, TId, TError = AppError> extends ResultRepository<TEntity, TId, TError> {
+  findAsOf(id: TId, asOf: Date): Promise<Result<TEntity | null, TError>>;
+  findAtTransaction(id: TId, txTime: Date): Promise<Result<TEntity | null, TError>>;
+  findHistory(id: TId): Promise<Result<TemporalHistory<TEntity>, TError>>;
+  save(entity: TEntity, validFrom?: Date): Promise<Result<void, TError>>;
+}
 //#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.
+ * Paginated result of a list query (offset-based).
  * Use as `Output` when the query returns a collection with pagination metadata.
+ * For cursor/keyset pagination, model your own `Output` type instead.
  */
 interface Page<T> {
   readonly items: readonly T[];
+  /** Total rows across all pages, ignoring `page`/`pageSize`. */
   readonly total: number;
+  /** 1-based page number (the first page is `1`, not `0`). */
   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.
+ *
+ * These are pure descriptors: the type cannot enforce that a duration is finite
+ * and positive, so the caching adapter must validate `ttlMs` /
+ * `staleWhileRevalidateMs` (`> 0`, finite) before honoring the strategy.
  */
 type CacheStrategy = {
   readonly kind: "NO_CACHE";
@@ -225,7 +231,14 @@ type CacheStrategy = {
   readonly ttlMs: number;
 } | {
   readonly kind: "STALE_WHILE_REVALIDATE";
+  /** How long the entry is served fresh. */
   readonly ttlMs: number;
+  /**
+   * How long *after* `ttlMs` a stale entry may still be served while a
+   * background refresh runs. SWR needs both windows; a single TTL is
+   * ambiguous and each adapter would guess the second one.
+   */
+  readonly staleWhileRevalidateMs: number;
 };
 type QueryOutput = object | string | number | boolean | bigint | symbol | null;
 /**
@@ -263,6 +276,14 @@ declare function assertTemporalContext(temporalContext: TemporalContext, fieldNa
 declare function createTemporalContext(input?: CreateTemporalContextInput): TemporalContext;
 //#endregion
 //#region src/core/application/temporal/temporal-use-case.d.ts
+/**
+ * Marker mixed into a temporal use case's `Input`.
+ *
+ * The consumer's `Input` must not re-declare `temporalContext` with an
+ * incompatible type: `TemporalUseCase` intersects the two, and a clashing
+ * declaration collapses the field to `never` (surfacing only as a confusing
+ * error at the call site, not here).
+ */
 interface TemporalUseCaseInput {
   readonly temporalContext?: TemporalContext;
 }
@@ -280,8 +301,20 @@ type TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<TSeed, "fields">
 };
 declare abstract class TemporalUseCase<Input extends object, Output extends Result<unknown, unknown>> extends UseCase<Input & TemporalUseCaseInput, Output> {
   protected resolveTemporalContext(input: Input & TemporalUseCaseInput): 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.
+   */
   protected buildPolicySeed<TSeed extends ContextSeed>(seed: TSeed, temporalContext: TemporalContext): TemporalizedContextSeed<TSeed>;
 }
 //#endregion
-export { LogPayload as A, UseCase as C, TracerPort as D, TraceSpan as E, MetricLabels as O, MaybePromise as S, TraceAttributeValue 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, LoggerPort as j, MetricsPort 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, UseCaseObservability as w, CommandInput as x, PolicyPortError as y };
+export { MetricLabels as A, CommandInput as C, TraceAttributeValue as D, UseCaseObservability as E, LogPayload as M, LoggerPort as N, TraceSpan as O, Command as S, UseCase as T, ResultRepository as _, TemporalContext as a, PolicyPort as b, CacheStrategy as c, QueryOutput as d, mapPolicyEvaluationError as f, Repository as g, TemporalRepository as h, CreateTemporalContextInput as i, MetricsPort as j, TracerPort as k, Page as l, TemporalHistory as m, TemporalUseCaseInput as n, assertTemporalContext as o, ResultTemporalRepository as p, TemporalizedContextSeed as r, createTemporalContext as s, TemporalUseCase as t, Query as u, PolicyEvaluationInput as v, MaybePromise as w, PolicyPortError as x, PolicyEvaluationOutput as y };
 //# sourceMappingURL=temporal-use-case.d.cts.map

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

@@ -1,9 +1,9 @@
 import { t as RequestedBy } from "./requested-by.js";
 import { t as AppError } from "./app-error.js";
 import { r as Result } from "./result.js";
-import { t as DeepReadonly } from "./immutable.js";
 import { n as ContractVersion } from "./version.js";
 import { b as ContextSeed, r as PolicyEvaluationResult, s as PolicyEvaluationError, t as EvaluateInput } from "./policy-service.js";
+import { n as TemporalSnapshot } from "./temporal-snapshot.js";
 
 //#region src/core/application/ports/logger.port.d.ts
 type LogPayload = Record<string, unknown>;
@@ -77,6 +77,14 @@ declare abstract class UseCase<Input = void, Output extends Result<unknown, unkn
    */
   protected get useCaseName(): string;
   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>>;
   private runInstrumented;
 }
 //#endregion
@@ -94,7 +102,15 @@ interface CommandInput {
  * 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> {}
+declare abstract class Command<Input extends CommandInput, Output extends Result<unknown, unknown> = Result<void, never>> extends UseCase<Input, Output> {
+  /**
+   * 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.
+   */
+  protected spanAttributes(input: Input): Readonly<Record<string, TraceAttributeValue>>;
+}
 //#endregion
 //#region src/core/application/ports/policy-port.d.ts
 type PolicyEvaluationInput = EvaluateInput;
@@ -152,71 +168,61 @@ interface ResultRepository<TEntity, TId, TError = AppError> {
   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>[];
+/**
+ * Bitemporal persistence port in the imperative (exception-raising) style.
+ *
+ * `delete(id)` is inherited from {@link Repository} and its bitemporal meaning
+ * is intentionally left to the implementation: it may close the current
+ * valid-time interval (a logical end-of-validity that preserves history) or
+ * physically purge the row's whole history. Pick one per adapter and document
+ * it — callers cannot tell which from this type. Prefer closing validity so
+ * `findAsOf`/`findHistory` stay meaningful for past instants.
+ */
 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>;
 }
+/**
+ * `Result`-returning counterpart of {@link TemporalRepository}, aligned with the
+ * "errors as values" philosophy (mirrors the {@link Repository} /
+ * {@link ResultRepository} pair). The `delete` semantics note above applies
+ * unchanged.
+ */
+interface ResultTemporalRepository<TEntity, TId, TError = AppError> extends ResultRepository<TEntity, TId, TError> {
+  findAsOf(id: TId, asOf: Date): Promise<Result<TEntity | null, TError>>;
+  findAtTransaction(id: TId, txTime: Date): Promise<Result<TEntity | null, TError>>;
+  findHistory(id: TId): Promise<Result<TemporalHistory<TEntity>, TError>>;
+  save(entity: TEntity, validFrom?: Date): Promise<Result<void, TError>>;
+}
 //#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.
+ * Paginated result of a list query (offset-based).
  * Use as `Output` when the query returns a collection with pagination metadata.
+ * For cursor/keyset pagination, model your own `Output` type instead.
  */
 interface Page<T> {
   readonly items: readonly T[];
+  /** Total rows across all pages, ignoring `page`/`pageSize`. */
   readonly total: number;
+  /** 1-based page number (the first page is `1`, not `0`). */
   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.
+ *
+ * These are pure descriptors: the type cannot enforce that a duration is finite
+ * and positive, so the caching adapter must validate `ttlMs` /
+ * `staleWhileRevalidateMs` (`> 0`, finite) before honoring the strategy.
  */
 type CacheStrategy = {
   readonly kind: "NO_CACHE";
@@ -225,7 +231,14 @@ type CacheStrategy = {
   readonly ttlMs: number;
 } | {
   readonly kind: "STALE_WHILE_REVALIDATE";
+  /** How long the entry is served fresh. */
   readonly ttlMs: number;
+  /**
+   * How long *after* `ttlMs` a stale entry may still be served while a
+   * background refresh runs. SWR needs both windows; a single TTL is
+   * ambiguous and each adapter would guess the second one.
+   */
+  readonly staleWhileRevalidateMs: number;
 };
 type QueryOutput = object | string | number | boolean | bigint | symbol | null;
 /**
@@ -263,6 +276,14 @@ declare function assertTemporalContext(temporalContext: TemporalContext, fieldNa
 declare function createTemporalContext(input?: CreateTemporalContextInput): TemporalContext;
 //#endregion
 //#region src/core/application/temporal/temporal-use-case.d.ts
+/**
+ * Marker mixed into a temporal use case's `Input`.
+ *
+ * The consumer's `Input` must not re-declare `temporalContext` with an
+ * incompatible type: `TemporalUseCase` intersects the two, and a clashing
+ * declaration collapses the field to `never` (surfacing only as a confusing
+ * error at the call site, not here).
+ */
 interface TemporalUseCaseInput {
   readonly temporalContext?: TemporalContext;
 }
@@ -280,8 +301,20 @@ type TemporalizedContextSeed<TSeed extends ContextSeed> = Omit<TSeed, "fields">
 };
 declare abstract class TemporalUseCase<Input extends object, Output extends Result<unknown, unknown>> extends UseCase<Input & TemporalUseCaseInput, Output> {
   protected resolveTemporalContext(input: Input & TemporalUseCaseInput): 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.
+   */
   protected buildPolicySeed<TSeed extends ContextSeed>(seed: TSeed, temporalContext: TemporalContext): TemporalizedContextSeed<TSeed>;
 }
 //#endregion
-export { LogPayload as A, UseCase as C, TracerPort as D, TraceSpan as E, MetricLabels as O, MaybePromise as S, TraceAttributeValue 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, LoggerPort as j, MetricsPort 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, UseCaseObservability as w, CommandInput as x, PolicyPortError as y };
+export { MetricLabels as A, CommandInput as C, TraceAttributeValue as D, UseCaseObservability as E, LogPayload as M, LoggerPort as N, TraceSpan as O, Command as S, UseCase as T, ResultRepository as _, TemporalContext as a, PolicyPort as b, CacheStrategy as c, QueryOutput as d, mapPolicyEvaluationError as f, Repository as g, TemporalRepository as h, CreateTemporalContextInput as i, MetricsPort as j, TracerPort as k, Page as l, TemporalHistory as m, TemporalUseCaseInput as n, assertTemporalContext as o, ResultTemporalRepository as p, TemporalizedContextSeed as r, createTemporalContext as s, TemporalUseCase as t, Query as u, PolicyEvaluationInput as v, MaybePromise as w, PolicyPortError as x, PolicyEvaluationOutput as y };
 //# sourceMappingURL=temporal-use-case.d.ts.map