@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/flows-actors/model-call-attributions.shared.schemas.js

@@ -0,0 +1,165 @@
+/**
+ * # Model-call attributions: which tenant and which case a model call served, and what it cost (#1598)
+ *
+ * One row per (provider call × unit of work). Most calls produce exactly one row (share `WHOLE_CALL`); an
+ * embedding call that served several source rows of one tenant produces one row per source, each carrying
+ * its `APPORTIONED_BY_INPUT_LENGTH` share. A call made outside any work frame produces one `UNATTRIBUTED`
+ * row, so "every call is accounted for" stays a countable statement.
+ *
+ * ## Why a separate table, and not an `organizationId` on `providerCallRecords`
+ *
+ * `providerCallRecords` is operator EVIDENCE about what the application sent to which vendor; it names no
+ * customer on purpose. An organization id there would turn every evidence row into a statement about a
+ * customer, with the erasure and retention obligations that follow. The attribution is a separate fact with
+ * its own owner (the tenant it names) and its own teardown: these rows are deleted with the tenant.
+ *
+ * ## A closed projection, like the evidence row
+ *
+ * {@link projectModelCallAttribution} is the only producer, and it names every field it copies. No prompt,
+ * no output, no error message, no `userId` and nothing from the trace's free-form `attributes` can reach
+ * the table: the row holds identifiers and counts. That is also why it is `exportSubject: FORBIDDEN` with no
+ * relationship to USERS: it is "a financial row that POINTS at a case", not data about a person. A case row's
+ * erasure does not touch it; its `caseRef` then points at an impersonalized or absent row.
+ *
+ * ## Cost, exact and unrounded
+ *
+ * When a registered authority priced the call, the row stores the WHOLE call's exact cost as
+ * `callCostMinorNumerator / callCostUnitsDenominator` minor units. A reader applies the row's share and
+ * rounds once per reported total (`ExactMinorCostTotal`). A provider-reported cost (an ACP coding agent's
+ * `cost`) is kept apart, verbatim, and never mixed into the computed one.
+ *
+ * ## Retention
+ *
+ * Bound to the application's `OPERATIONAL_LOGS` period from creation (#1613). The durable record behind an
+ * invoice is the per-period aggregate (`modelCostPeriodAggregates`), not these rows.
+ */
+import { z } from 'zod';
+// Side-effect import: this module calls `.systemEnum()` at load (#966).
+import '@wildo-ai/zod-decorators';
+import { AgentCallTraceKind } from './agent-traceability.shared.schemas.js';
+import { WorkUnitRefSchema } from '../resources/work-unit.shared.schemas.js';
+import { ExecutionRefSchema, ModelCallAttributionShare, ModelCallAttributionSource, ModelCallPricingStatus, ReasoningUsageReporting, } from './work-attribution.shared.schemas.js';
+export const ModelCallAttributionSchema = z.object({
+    /** Document id. `.isPrimaryKey()` is what makes the PostgreSQL planner emit the PRIMARY KEY constraint. */
+    _id: z.string().isPrimaryKey().isSummaryField(),
+    /** The application record the call was made by (the APPLICATION scope's key), stamped by the recorder. */
+    applicationId: z.string().isDBIndexed(),
+    /** The provider-call record this row attributes. Several rows may name one record (apportioned shares). */
+    providerCallRecordId: z.string().min(1).isDBIndexed(),
+    /** Copied from the call so a summary never needs a join: the agent, or the service's label for an embedding or extraction. */
+    agentRef: z.string().min(1).isDBIndexed().isSummaryField(),
+    kind: z.enum(AgentCallTraceKind).systemEnum('AgentCallTraceKind').default(AgentCallTraceKind.GENERATION),
+    provider: z.string().min(1).isDBIndexed().optional(),
+    model: z.string().min(1).isDBIndexed().optional(),
+    /** When the call was initiated. The instant a summary window and a cost period are cut on. */
+    calledAt: z.date().isDBIndexed().isSummaryField(),
+    /** The request or job correlation id the call ran under, when there was one. A join key, never authority. */
+    correlationId: z.string().min(1).max(128).optional(),
+    /**
+     * The tenant the call served. Derived by the engine from an authenticated owner field or the case row's
+     * own scope; never from a caller or a model. Absent on an `UNATTRIBUTED` row and on work an application
+     * does for itself.
+     */
+    organizationId: z.string().isDBIndexed().optional(),
+    /** The case the call served: a row of a resource declared `workUnit: true`. */
+    caseRef: WorkUnitRefSchema.optional(),
+    /** The run the call was made in. */
+    executionRef: ExecutionRefSchema.optional(),
+    /** The actor task within that run, when there is one. */
+    taskRef: z.string().min(1).max(200).optional(),
+    /** How this row learned its attribution: explicitly from the call site, from the ambient work frame, or not at all. */
+    attributionSource: z.enum(ModelCallAttributionSource).systemEnum('ModelCallAttributionSource').isDBIndexed(),
+    /** Which part of the call this row accounts for. */
+    share: z.enum(ModelCallAttributionShare).systemEnum('ModelCallAttributionShare'),
+    /** This row's share of the call: `shareNumerator / shareDenominator` (1/1 for a whole call). */
+    shareNumerator: z.number().int().min(0),
+    shareDenominator: z.number().int().min(1),
+    /** The WHOLE call's token counts (a share applies to cost, and a reader applies it to tokens when it needs to). */
+    promptTokens: z.number().int().min(0),
+    completionTokens: z.number().int().min(0),
+    totalTokens: z.number().int().min(0),
+    noCacheTokens: z.number().int().min(0).optional(),
+    cacheReadTokens: z.number().int().min(0).optional(),
+    cacheWriteTokens: z.number().int().min(0).optional(),
+    textTokens: z.number().int().min(0).optional(),
+    /** Part of `completionTokens`. Absent when the provider did not report the split; see `reasoningUsage`. */
+    reasoningTokens: z.number().int().min(0).optional(),
+    /** Whether the provider reported the reasoning split. `UNREPORTED` is never read as zero reasoning. */
+    reasoningUsage: z.enum(ReasoningUsageReporting).systemEnum('ReasoningUsageReporting'),
+    /** Whether a registered pricing authority priced the call. */
+    pricingStatus: z.enum(ModelCallPricingStatus).systemEnum('ModelCallPricingStatus').isDBIndexed(),
+    /** The price used, identified as `pricingAuthorityRef@pricingAuthorityVersion`. Present exactly when `PRICED`. */
+    pricingAuthorityRef: z.string().min(1).optional(),
+    pricingAuthorityVersion: z.number().int().min(1).optional(),
+    currency: z.string().regex(/^[A-Z]{3}$/).optional(),
+    /** The whole call's exact cost numerator in minor units, a decimal integer string. Present exactly when `PRICED`. */
+    callCostMinorNumerator: z.string().regex(/^\d+$/).optional(),
+    /** The whole call's exact cost denominator. Present exactly when `PRICED`. */
+    callCostUnitsDenominator: z.number().int().min(1).optional(),
+    /** A cost the provider reported itself (an ACP coding agent's `cost`), verbatim in its own unit; never mixed into the computed cost. */
+    reportedCostAmount: z.number().min(0).optional(),
+    reportedCurrency: z.string().min(1).max(12).optional(),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+});
+/**
+ * The ONLY way an attribution row is built: a closed projection of the provider-call record already
+ * written for the call, the resolved attribution, and the computed cost.
+ *
+ * It reads the RECORD (already a closed projection of the trace) rather than the trace, so the two tables
+ * cannot disagree about a call's provider, model or tokens, and nothing the record deliberately dropped
+ * (prompt, output, error message) can come back here. The reported provider cost is the one value read
+ * from the trace, and only its numeric amount and currency code.
+ */
+export function projectModelCallAttribution(input) {
+    const { record, target, cost } = input;
+    const promptTokens = record.promptTokens ?? 0;
+    const completionTokens = record.completionTokens ?? 0;
+    return {
+        applicationId: record.applicationId,
+        providerCallRecordId: input.providerCallRecordId,
+        agentRef: record.agentRef,
+        kind: record.kind,
+        ...(record.provider ? { provider: record.provider } : {}),
+        ...(record.model ? { model: record.model } : {}),
+        calledAt: record.calledAt,
+        ...(input.correlationId ? { correlationId: input.correlationId } : {}),
+        ...(target.attribution.organizationId ? { organizationId: target.attribution.organizationId } : {}),
+        ...(target.attribution.caseRef ? { caseRef: { resourceType: target.attribution.caseRef.resourceType, resourceId: target.attribution.caseRef.resourceId } } : {}),
+        ...(target.attribution.executionRef ? { executionRef: { kind: target.attribution.executionRef.kind, id: target.attribution.executionRef.id } } : {}),
+        ...(target.attribution.taskRef ? { taskRef: target.attribution.taskRef } : {}),
+        attributionSource: target.source,
+        share: target.share,
+        shareNumerator: target.shareNumerator,
+        shareDenominator: target.shareDenominator,
+        promptTokens,
+        completionTokens,
+        totalTokens: record.totalTokens ?? promptTokens + completionTokens,
+        ...(record.noCacheTokens !== undefined ? { noCacheTokens: record.noCacheTokens } : {}),
+        ...(record.cacheReadTokens !== undefined ? { cacheReadTokens: record.cacheReadTokens } : {}),
+        ...(record.cacheWriteTokens !== undefined ? { cacheWriteTokens: record.cacheWriteTokens } : {}),
+        ...(record.textTokens !== undefined ? { textTokens: record.textTokens } : {}),
+        ...(record.reasoningTokens !== undefined ? { reasoningTokens: record.reasoningTokens } : {}),
+        reasoningUsage: input.reasoningUsage,
+        ...(cost
+            ? {
+                pricingStatus: ModelCallPricingStatus.PRICED,
+                pricingAuthorityRef: cost.pricingAuthorityRef,
+                pricingAuthorityVersion: cost.pricingAuthorityVersion,
+                currency: cost.currency,
+                callCostMinorNumerator: cost.callCostMinorNumerator,
+                callCostUnitsDenominator: cost.callCostUnitsDenominator,
+            }
+            : { pricingStatus: ModelCallPricingStatus.UNPRICED }),
+        ...(input.reportedCost && Number.isFinite(input.reportedCost.amount) && input.reportedCost.amount >= 0
+            ? { reportedCostAmount: input.reportedCost.amount, reportedCurrency: input.reportedCost.currency.slice(0, 12) }
+            : {}),
+    };
+}
+/** Read an ACP-style provider-reported cost off a trace's usage, when there is one. Numeric fields only. */
+export function readReportedProviderCost(trace) {
+    const cost = trace.context?.usage?.cost;
+    return cost && typeof cost.amount === 'number' && typeof cost.currency === 'string' && cost.currency.length > 0
+        ? { amount: cost.amount, currency: cost.currency }
+        : undefined;
+}
+//# sourceMappingURL=model-call-attributions.shared.schemas.js.map

package/dist/esm/flows-actors/model-call-attributions.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-call-attributions.shared.schemas.js","sourceRoot":"","sources":["../../../src/flows-actors/model-call-attributions.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * # Model-call attributions: which tenant and which case a model call served, and what it cost (#1598)\n *\n * One row per (provider call × unit of work). Most calls produce exactly one row (share `WHOLE_CALL`); an\n * embedding call that served several source rows of one tenant produces one row per source, each carrying\n * its `APPORTIONED_BY_INPUT_LENGTH` share. A call made outside any work frame produces one `UNATTRIBUTED`\n * row, so \"every call is accounted for\" stays a countable statement.\n *\n * ## Why a separate table, and not an `organizationId` on `providerCallRecords`\n *\n * `providerCallRecords` is operator EVIDENCE about what the application sent to which vendor; it names no\n * customer on purpose. An organization id there would turn every evidence row into a statement about a\n * customer, with the erasure and retention obligations that follow. The attribution is a separate fact with\n * its own owner (the tenant it names) and its own teardown: these rows are deleted with the tenant.\n *\n * ## A closed projection, like the evidence row\n *\n * {@link projectModelCallAttribution} is the only producer, and it names every field it copies. No prompt,\n * no output, no error message, no `userId` and nothing from the trace's free-form `attributes` can reach\n * the table: the row holds identifiers and counts. That is also why it is `exportSubject: FORBIDDEN` with no\n * relationship to USERS: it is \"a financial row that POINTS at a case\", not data about a person. A case row's\n * erasure does not touch it; its `caseRef` then points at an impersonalized or absent row.\n *\n * ## Cost, exact and unrounded\n *\n * When a registered authority priced the call, the row stores the WHOLE call's exact cost as\n * `callCostMinorNumerator / callCostUnitsDenominator` minor units. A reader applies the row's share and\n * rounds once per reported total (`ExactMinorCostTotal`). A provider-reported cost (an ACP coding agent's\n * `cost`) is kept apart, verbatim, and never mixed into the computed one.\n *\n * ## Retention\n *\n * Bound to the application's `OPERATIONAL_LOGS` period from creation (#1613). The durable record behind an\n * invoice is the per-period aggregate (`modelCostPeriodAggregates`), not these rows.\n */\nimport { z } from 'zod';\n// Side-effect import: this module calls `.systemEnum()` at load (#966).\nimport '@wildo-ai/zod-decorators';\n\nimport { AgentCallTraceKind, type AgentCallTrace } from './agent-traceability.shared.schemas';\nimport { WorkUnitRefSchema } from '../resources/work-unit.shared.schemas';\nimport {\n  ExecutionRefSchema,\n  ModelCallAttributionShare,\n  ModelCallAttributionSource,\n  ModelCallPricingStatus,\n  ReasoningUsageReporting,\n  type ModelCallAttributionInput,\n} from './work-attribution.shared.schemas';\nimport type { ProviderCallRecord } from './provider-call-records.shared.schemas';\nimport type { ProviderUsageCostResult } from '../external-providers/provider-usage-pricing.shared.schemas';\n\nexport const ModelCallAttributionSchema = z.object({\n  /** Document id. `.isPrimaryKey()` is what makes the PostgreSQL planner emit the PRIMARY KEY constraint. */\n  _id: z.string().isPrimaryKey().isSummaryField(),\n  /** The application record the call was made by (the APPLICATION scope's key), stamped by the recorder. */\n  applicationId: z.string().isDBIndexed(),\n\n  /** The provider-call record this row attributes. Several rows may name one record (apportioned shares). */\n  providerCallRecordId: z.string().min(1).isDBIndexed(),\n  /** Copied from the call so a summary never needs a join: the agent, or the service's label for an embedding or extraction. */\n  agentRef: z.string().min(1).isDBIndexed().isSummaryField(),\n  kind: z.enum(AgentCallTraceKind).systemEnum('AgentCallTraceKind').default(AgentCallTraceKind.GENERATION),\n  provider: z.string().min(1).isDBIndexed().optional(),\n  model: z.string().min(1).isDBIndexed().optional(),\n  /** When the call was initiated. The instant a summary window and a cost period are cut on. */\n  calledAt: z.date().isDBIndexed().isSummaryField(),\n  /** The request or job correlation id the call ran under, when there was one. A join key, never authority. */\n  correlationId: z.string().min(1).max(128).optional(),\n\n  /**\n   * The tenant the call served. Derived by the engine from an authenticated owner field or the case row's\n   * own scope; never from a caller or a model. Absent on an `UNATTRIBUTED` row and on work an application\n   * does for itself.\n   */\n  organizationId: z.string().isDBIndexed().optional(),\n  /** The case the call served: a row of a resource declared `workUnit: true`. */\n  caseRef: WorkUnitRefSchema.optional(),\n  /** The run the call was made in. */\n  executionRef: ExecutionRefSchema.optional(),\n  /** The actor task within that run, when there is one. */\n  taskRef: z.string().min(1).max(200).optional(),\n  /** How this row learned its attribution: explicitly from the call site, from the ambient work frame, or not at all. */\n  attributionSource: z.enum(ModelCallAttributionSource).systemEnum('ModelCallAttributionSource').isDBIndexed(),\n\n  /** Which part of the call this row accounts for. */\n  share: z.enum(ModelCallAttributionShare).systemEnum('ModelCallAttributionShare'),\n  /** This row's share of the call: `shareNumerator / shareDenominator` (1/1 for a whole call). */\n  shareNumerator: z.number().int().min(0),\n  shareDenominator: z.number().int().min(1),\n\n  /** The WHOLE call's token counts (a share applies to cost, and a reader applies it to tokens when it needs to). */\n  promptTokens: z.number().int().min(0),\n  completionTokens: z.number().int().min(0),\n  totalTokens: z.number().int().min(0),\n  noCacheTokens: z.number().int().min(0).optional(),\n  cacheReadTokens: z.number().int().min(0).optional(),\n  cacheWriteTokens: z.number().int().min(0).optional(),\n  textTokens: z.number().int().min(0).optional(),\n  /** Part of `completionTokens`. Absent when the provider did not report the split; see `reasoningUsage`. */\n  reasoningTokens: z.number().int().min(0).optional(),\n  /** Whether the provider reported the reasoning split. `UNREPORTED` is never read as zero reasoning. */\n  reasoningUsage: z.enum(ReasoningUsageReporting).systemEnum('ReasoningUsageReporting'),\n\n  /** Whether a registered pricing authority priced the call. */\n  pricingStatus: z.enum(ModelCallPricingStatus).systemEnum('ModelCallPricingStatus').isDBIndexed(),\n  /** The price used, identified as `pricingAuthorityRef@pricingAuthorityVersion`. Present exactly when `PRICED`. */\n  pricingAuthorityRef: z.string().min(1).optional(),\n  pricingAuthorityVersion: z.number().int().min(1).optional(),\n  currency: z.string().regex(/^[A-Z]{3}$/).optional(),\n  /** The whole call's exact cost numerator in minor units, a decimal integer string. Present exactly when `PRICED`. */\n  callCostMinorNumerator: z.string().regex(/^\\d+$/).optional(),\n  /** The whole call's exact cost denominator. Present exactly when `PRICED`. */\n  callCostUnitsDenominator: z.number().int().min(1).optional(),\n  /** A cost the provider reported itself (an ACP coding agent's `cost`), verbatim in its own unit; never mixed into the computed cost. */\n  reportedCostAmount: z.number().min(0).optional(),\n  reportedCurrency: z.string().min(1).max(12).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n});\nexport type ModelCallAttribution = z.infer<typeof ModelCallAttributionSchema>;\n\n/** One unit of work a provider call served, with its share of the call. */\nexport interface ModelCallAttributionTarget {\n  readonly attribution: ModelCallAttributionInput;\n  readonly source: ModelCallAttributionSource;\n  readonly share: ModelCallAttributionShare;\n  readonly shareNumerator: number;\n  readonly shareDenominator: number;\n}\n\n/**\n * The ONLY way an attribution row is built: a closed projection of the provider-call record already\n * written for the call, the resolved attribution, and the computed cost.\n *\n * It reads the RECORD (already a closed projection of the trace) rather than the trace, so the two tables\n * cannot disagree about a call's provider, model or tokens, and nothing the record deliberately dropped\n * (prompt, output, error message) can come back here. The reported provider cost is the one value read\n * from the trace, and only its numeric amount and currency code.\n */\nexport function projectModelCallAttribution(input: {\n  readonly providerCallRecordId: string;\n  readonly record: Omit<ProviderCallRecord, '_id' | 'createdAt'>;\n  readonly target: ModelCallAttributionTarget;\n  readonly cost: ProviderUsageCostResult | undefined;\n  readonly reasoningUsage: ReasoningUsageReporting;\n  readonly correlationId?: string;\n  readonly reportedCost?: { readonly amount: number; readonly currency: string };\n}): Omit<ModelCallAttribution, '_id' | 'createdAt'> {\n  const { record, target, cost } = input;\n  const promptTokens = record.promptTokens ?? 0;\n  const completionTokens = record.completionTokens ?? 0;\n  return {\n    applicationId: record.applicationId,\n    providerCallRecordId: input.providerCallRecordId,\n    agentRef: record.agentRef,\n    kind: record.kind,\n    ...(record.provider ? { provider: record.provider } : {}),\n    ...(record.model ? { model: record.model } : {}),\n    calledAt: record.calledAt,\n    ...(input.correlationId ? { correlationId: input.correlationId } : {}),\n    ...(target.attribution.organizationId ? { organizationId: target.attribution.organizationId } : {}),\n    ...(target.attribution.caseRef ? { caseRef: { resourceType: target.attribution.caseRef.resourceType, resourceId: target.attribution.caseRef.resourceId } } : {}),\n    ...(target.attribution.executionRef ? { executionRef: { kind: target.attribution.executionRef.kind, id: target.attribution.executionRef.id } } : {}),\n    ...(target.attribution.taskRef ? { taskRef: target.attribution.taskRef } : {}),\n    attributionSource: target.source,\n    share: target.share,\n    shareNumerator: target.shareNumerator,\n    shareDenominator: target.shareDenominator,\n    promptTokens,\n    completionTokens,\n    totalTokens: record.totalTokens ?? promptTokens + completionTokens,\n    ...(record.noCacheTokens !== undefined ? { noCacheTokens: record.noCacheTokens } : {}),\n    ...(record.cacheReadTokens !== undefined ? { cacheReadTokens: record.cacheReadTokens } : {}),\n    ...(record.cacheWriteTokens !== undefined ? { cacheWriteTokens: record.cacheWriteTokens } : {}),\n    ...(record.textTokens !== undefined ? { textTokens: record.textTokens } : {}),\n    ...(record.reasoningTokens !== undefined ? { reasoningTokens: record.reasoningTokens } : {}),\n    reasoningUsage: input.reasoningUsage,\n    ...(cost\n      ? {\n          pricingStatus: ModelCallPricingStatus.PRICED,\n          pricingAuthorityRef: cost.pricingAuthorityRef,\n          pricingAuthorityVersion: cost.pricingAuthorityVersion,\n          currency: cost.currency,\n          callCostMinorNumerator: cost.callCostMinorNumerator,\n          callCostUnitsDenominator: cost.callCostUnitsDenominator,\n        }\n      : { pricingStatus: ModelCallPricingStatus.UNPRICED }),\n    ...(input.reportedCost && Number.isFinite(input.reportedCost.amount) && input.reportedCost.amount >= 0\n      ? { reportedCostAmount: input.reportedCost.amount, reportedCurrency: input.reportedCost.currency.slice(0, 12) }\n      : {}),\n  };\n}\n\n/** Read an ACP-style provider-reported cost off a trace's usage, when there is one. Numeric fields only. */\nexport function readReportedProviderCost(trace: AgentCallTrace): { amount: number; currency: string } | undefined {\n  const cost = (trace.context?.usage as { cost?: { amount?: unknown; currency?: unknown } } | undefined)?.cost;\n  return cost && typeof cost.amount === 'number' && typeof cost.currency === 'string' && cost.currency.length > 0\n    ? { amount: cost.amount, currency: cost.currency }\n    : undefined;\n}\n"]}

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.resources-config.schemas.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Model-cost period aggregates: resource configuration (#1598).
+ *
+ * Written only by the engine (the period close and the tenant-deletion close), through the repository. The
+ * application's billing flow reaches it at APPLICATION-admin level (super-administrator or billing manager) through
+ * three doors: LIST and READ, to find the month it is about to invoice (filter on `organizationId`, `periodStart`,
+ * `currency`), and `link_invoice`, to record that an invoice bills it. That is the ordinary shape of a billable ledger
+ * (list the entries, then attach the invoice to one); the cost summary stays the analytical surface and returns
+ * totals, not the rows an invoice is attached to (#1598 review F4).
+ *
+ * `DELETE_MANY` is route-less and serves the retention-class sweep (`BUSINESS_RECORDS` from the end of the
+ * calendar year the period falls in) and the tenant-deletion close, which deletes the tenant's UNLINKED
+ * aggregates. The `organizations → modelCostPeriodAggregates` edge disables the cascade, so an invoiced
+ * aggregate outlives its tenant for the statutory period.
+ */
+import { z } from 'zod';
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+import { type ResourceRelationship } from '../resources/resources.shared.schemas';
+import { ModelCostPeriodAggregates_Operations } from './model-cost-period-aggregates.shared.schemas';
+export declare const modelCostPeriodAggregatesResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("..").ResourceConfiguration<typeof ModelCostPeriodAggregates_Operations, CoreResourceOperation.READ | CoreResourceOperation.UPDATE_MANY | CoreResourceOperation.DELETE_MANY | CoreResourceOperation.CREATE | CoreResourceOperation.LIST, z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    periodKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    periodStart: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDate>>;
+    periodEnd: z.ZodDate;
+    currency: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    attributedCallCount: z.ZodNumber;
+    unpricedCallCount: z.ZodNumber;
+    promptTokens: z.ZodNumber;
+    completionTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    reasoningTokens: z.ZodNumber;
+    costMinor: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
+    pricingAuthorities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        pricingAuthorityRef: z.ZodString;
+        pricingAuthorityVersion: z.ZodNumber;
+    }, z.core.$strict>>>;
+    closedAt: z.ZodDate;
+    organizationInvoiceRefId: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=model-cost-period-aggregates.shared.resources-config.schemas.d.ts.map

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.resources-config.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cost-period-aggregates.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/flows-actors/model-cost-period-aggregates.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,qBAAqB,EAAwD,MAAM,gDAAgD,CAAC;AAC7I,OAAO,EAA4D,KAAK,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAE5I,OAAO,EAGL,oCAAoC,EACrC,MAAM,+CAA+C,CAAC;AAevD,eAAO,MAAM,oEAAoE,GAC/E,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;kBAkG9C,CAAC"}

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.resources-config.schemas.js

@@ -0,0 +1,127 @@
+/**
+ * Model-cost period aggregates: resource configuration (#1598).
+ *
+ * Written only by the engine (the period close and the tenant-deletion close), through the repository. The
+ * application's billing flow reaches it at APPLICATION-admin level (super-administrator or billing manager) through
+ * three doors: LIST and READ, to find the month it is about to invoice (filter on `organizationId`, `periodStart`,
+ * `currency`), and `link_invoice`, to record that an invoice bills it. That is the ordinary shape of a billable ledger
+ * (list the entries, then attach the invoice to one); the cost summary stays the analytical surface and returns
+ * totals, not the rows an invoice is attached to (#1598 review F4).
+ *
+ * `DELETE_MANY` is route-less and serves the retention-class sweep (`BUSINESS_RECORDS` from the end of the
+ * calendar year the period falls in) and the tenant-deletion close, which deletes the tenant's UNLINKED
+ * aggregates. The `organizations → modelCostPeriodAggregates` edge disables the cascade, so an invoiced
+ * aggregate outlives its tenant for the statutory period.
+ */
+import { z } from 'zod';
+import { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory.js';
+import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
+import { DataRetentionClass, RetentionStartPoint } from '../compliance/privacy/retention-schedule.shared.schemas.js';
+import { ErasureRetentionMode, ResourceDataSubjectKind, StatutoryRetentionGround } from '../compliance/privacy/impersonalization.shared.schemas.js';
+import { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions.js';
+import { ResourceOperationRiskLevel, ResourceOperationVariantType } from '../resources/resources.shared.schemas.js';
+import { CORE_APP_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+import { ModelCostLinkInvoiceRequestSchema, ModelCostPeriodAggregateSchema, ModelCostPeriodAggregates_Operations, } from './model-cost-period-aggregates.shared.schemas.js';
+/**
+ * Who works with the aggregates: the application's own billing people. Not an organization role — the aggregate is
+ * the operator's record of what a client's cases cost it, and the client never reads it.
+ */
+const MODEL_COST_BILLING_ROLES = [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN, CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER];
+/** What the billing flow filters the aggregates by. Without a declaration LIST ignores every filter and answers all. */
+const MODEL_COST_AGGREGATE_FILTER_FIELDS = {
+    organizationId: z.string(),
+    currency: z.string(),
+    periodKey: z.string(),
+};
+export const modelCostPeriodAggregatesResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
+    mainSchema: ModelCostPeriodAggregateSchema,
+    resourceIdentifier: CoreResourceType.MODEL_COST_PERIOD_AGGREGATES,
+    resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.MODEL_COST_PERIOD_AGGREGATES],
+    resourceRelationships: resourcesRelationships,
+    isSystemResource: true,
+    /*
+     * No personal data (an organization id, instants, counts, money), and no relationship to USERS. FORBIDDEN so
+     * the decision not to disclose the firm's internal margin data is visible.
+     */
+    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.FORBIDDEN },
+    /*
+     * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — the statutory bookkeeping period, counted from the end
+     * of the calendar year the row was written in (HGB §257(4), AO §147(3), Code de commerce L123-22).
+     */
+    retentionBinding: {
+        retentionClass: DataRetentionClass.BUSINESS_RECORDS,
+        startPoint: RetentionStartPoint.END_OF_CALENDAR_YEAR,
+    },
+    /*
+     * BUSINESS_RECORDS is a statutory minimum, so the engine requires the statute to be named (#1635). RETAIN_ONLY:
+     * the rows carry no personal data to impersonalize, and no data subject — they describe an organization's spend.
+     */
+    retentionPolicy: {
+        mode: ErasureRetentionMode.RETAIN_ONLY,
+        statutoryRetention: {
+            ground: StatutoryRetentionGround.LEGAL_OBLIGATION,
+            rationale: 'Booking vouchers backing an invoice: HGB §257(1) no. 4 and AO §147(1) no. 4 (eight years from the end of the calendar year, §257(4)-(5) / §147(3)-(4)); Code de commerce L123-22 (ten years for accounting documents).',
+        },
+    },
+    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },
+    coreOperations: [
+        CoreResourceOperation.CREATE,
+        CoreResourceOperation.READ,
+        CoreResourceOperation.LIST,
+        // Required by the retention policy (the erasure writer's `updateManyAsSystem`); route-less. RETAIN_ONLY
+        // scrubs nothing here, so in practice it only flips the retained marker.
+        CoreResourceOperation.UPDATE_MANY,
+        CoreResourceOperation.DELETE_MANY,
+    ],
+    operationsConfiguration: {
+        [CoreResourceOperation.CREATE]: {
+            variants: [{ variantType: ResourceOperationVariantType.REPOSITORY_ONLY, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW }],
+        },
+        [CoreResourceOperation.READ]: {
+            variants: [
+                { variantType: ResourceOperationVariantType.REPOSITORY_ONLY, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },
+                // The retention policy's see-through reads resolve through the SERVICE transport; route-less.
+                { variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },
+                // The billing flow's door onto one aggregate. The INTERNAL_CALL variant above stays the service default.
+                { variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [...MODEL_COST_BILLING_ROLES], riskLevel: ResourceOperationRiskLevel.LOW },
+            ],
+        },
+        [CoreResourceOperation.LIST]: {
+            variants: [
+                { variantType: ResourceOperationVariantType.REPOSITORY_ONLY, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },
+                // The retention policy's see-through reads resolve through the SERVICE transport; route-less.
+                { variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },
+                // The billing flow's door onto the aggregates it invoices, found by organization, month and currency —
+                // `periodKey` (`{organizationId}:{YYYY-MM}:{currency}`) names exactly one.
+                {
+                    variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [...MODEL_COST_BILLING_ROLES], riskLevel: ResourceOperationRiskLevel.LOW,
+                    filterFields: MODEL_COST_AGGREGATE_FILTER_FIELDS,
+                },
+            ],
+        },
+        [CoreResourceOperation.UPDATE_MANY]: {
+            variants: [{ variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.CRITICAL }],
+        },
+        [CoreResourceOperation.DELETE_MANY]: {
+            variants: [{ variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.HIGH }],
+        },
+        /**
+         * Record that an invoice bills this aggregate. Set once: a second link to the SAME invoice is a no-op, to a
+         * different one is refused (the paired implementation). The link is what keeps the row past its tenant's
+         * deletion, so it is audited (`MODEL_COST_AGGREGATE_INVOICE_LINKED`).
+         *
+         * assurance-control: WILDO.PRIVACY.ERASURE_PROPAGATION — only an aggregate an invoice bills survives its tenant.
+         */
+        [ModelCostPeriodAggregates_Operations.LINK_INVOICE]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [...MODEL_COST_BILLING_ROLES],
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: ModelCostLinkInvoiceRequestSchema,
+                }],
+        },
+    },
+});
+//# sourceMappingURL=model-cost-period-aggregates.shared.resources-config.schemas.js.map

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.resources-config.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cost-period-aggregates.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../src/flows-actors/model-cost-period-aggregates.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Model-cost period aggregates: resource configuration (#1598).\n *\n * Written only by the engine (the period close and the tenant-deletion close), through the repository. The\n * application's billing flow reaches it at APPLICATION-admin level (super-administrator or billing manager) through\n * three doors: LIST and READ, to find the month it is about to invoice (filter on `organizationId`, `periodStart`,\n * `currency`), and `link_invoice`, to record that an invoice bills it. That is the ordinary shape of a billable ledger\n * (list the entries, then attach the invoice to one); the cost summary stays the analytical surface and returns\n * totals, not the rows an invoice is attached to (#1598 review F4).\n *\n * `DELETE_MANY` is route-less and serves the retention-class sweep (`BUSINESS_RECORDS` from the end of the\n * calendar year the period falls in) and the tenant-deletion close, which deletes the tenant's UNLINKED\n * aggregates. The `organizations → modelCostPeriodAggregates` edge disables the cascade, so an invoiced\n * aggregate outlives its tenant for the statutory period.\n */\nimport { z } from 'zod';\nimport { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataRetentionClass, RetentionStartPoint } from '../compliance/privacy/retention-schedule.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind, StatutoryRetentionGround } from '../compliance/privacy/impersonalization.shared.schemas';\nimport { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport { ResourceOperationRiskLevel, ResourceOperationVariantType, type ResourceRelationship } from '../resources/resources.shared.schemas';\nimport { CORE_APP_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport {\n  ModelCostLinkInvoiceRequestSchema,\n  ModelCostPeriodAggregateSchema,\n  ModelCostPeriodAggregates_Operations,\n} from './model-cost-period-aggregates.shared.schemas';\n\n/**\n * Who works with the aggregates: the application's own billing people. Not an organization role — the aggregate is\n * the operator's record of what a client's cases cost it, and the client never reads it.\n */\nconst MODEL_COST_BILLING_ROLES = [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN, CORE_APP_ROLES.APP_ADMIN_BILLING_MANAGER] as const;\n\n/** What the billing flow filters the aggregates by. Without a declaration LIST ignores every filter and answers all. */\nconst MODEL_COST_AGGREGATE_FILTER_FIELDS = {\n  organizationId: z.string(),\n  currency: z.string(),\n  periodKey: z.string(),\n};\n\nexport const modelCostPeriodAggregatesResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[],\n) => createResourceConfiguration_Initialization<typeof ModelCostPeriodAggregates_Operations,\n  CoreResourceOperation.CREATE | CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.UPDATE_MANY | CoreResourceOperation.DELETE_MANY,\n  typeof ModelCostPeriodAggregateSchema\n>({\n  mainSchema: ModelCostPeriodAggregateSchema,\n  resourceIdentifier: CoreResourceType.MODEL_COST_PERIOD_AGGREGATES,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.MODEL_COST_PERIOD_AGGREGATES],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n\n  /*\n   * No personal data (an organization id, instants, counts, money), and no relationship to USERS. FORBIDDEN so\n   * the decision not to disclose the firm's internal margin data is visible.\n   */\n  systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.FORBIDDEN },\n\n  /*\n   * assurance-control: WILDO.PRIVACY.STORAGE_LIMITATION — the statutory bookkeeping period, counted from the end\n   * of the calendar year the row was written in (HGB §257(4), AO §147(3), Code de commerce L123-22).\n   */\n  retentionBinding: {\n    retentionClass: DataRetentionClass.BUSINESS_RECORDS,\n    startPoint: RetentionStartPoint.END_OF_CALENDAR_YEAR,\n  },\n  /*\n   * BUSINESS_RECORDS is a statutory minimum, so the engine requires the statute to be named (#1635). RETAIN_ONLY:\n   * the rows carry no personal data to impersonalize, and no data subject — they describe an organization's spend.\n   */\n  retentionPolicy: {\n    mode: ErasureRetentionMode.RETAIN_ONLY,\n    statutoryRetention: {\n      ground: StatutoryRetentionGround.LEGAL_OBLIGATION,\n      rationale: 'Booking vouchers backing an invoice: HGB §257(1) no. 4 and AO §147(1) no. 4 (eight years from the end of the calendar year, §257(4)-(5) / §147(3)-(4)); Code de commerce L123-22 (ten years for accounting documents).',\n    },\n  },\n  dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n\n  coreOperations: [\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    // Required by the retention policy (the erasure writer's `updateManyAsSystem`); route-less. RETAIN_ONLY\n    // scrubs nothing here, so in practice it only flips the retained marker.\n    CoreResourceOperation.UPDATE_MANY,\n    CoreResourceOperation.DELETE_MANY,\n  ],\n  operationsConfiguration: {\n    [CoreResourceOperation.CREATE]: {\n      variants: [{ variantType: ResourceOperationVariantType.REPOSITORY_ONLY, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW }],\n    },\n    [CoreResourceOperation.READ]: {\n      variants: [\n        { variantType: ResourceOperationVariantType.REPOSITORY_ONLY, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },\n        // The retention policy's see-through reads resolve through the SERVICE transport; route-less.\n        { variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },\n        // The billing flow's door onto one aggregate. The INTERNAL_CALL variant above stays the service default.\n        { variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [...MODEL_COST_BILLING_ROLES], riskLevel: ResourceOperationRiskLevel.LOW },\n      ],\n    },\n    [CoreResourceOperation.LIST]: {\n      variants: [\n        { variantType: ResourceOperationVariantType.REPOSITORY_ONLY, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },\n        // The retention policy's see-through reads resolve through the SERVICE transport; route-less.\n        { variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.LOW },\n        // The billing flow's door onto the aggregates it invoices, found by organization, month and currency —\n        // `periodKey` (`{organizationId}:{YYYY-MM}:{currency}`) names exactly one.\n        {\n          variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [...MODEL_COST_BILLING_ROLES], riskLevel: ResourceOperationRiskLevel.LOW,\n          filterFields: MODEL_COST_AGGREGATE_FILTER_FIELDS,\n        },\n      ],\n    },\n    [CoreResourceOperation.UPDATE_MANY]: {\n      variants: [{ variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.CRITICAL }],\n    },\n    [CoreResourceOperation.DELETE_MANY]: {\n      variants: [{ variantType: ResourceOperationVariantType.INTERNAL_CALL, isDefault: true, roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], riskLevel: ResourceOperationRiskLevel.HIGH }],\n    },\n\n    /**\n     * Record that an invoice bills this aggregate. Set once: a second link to the SAME invoice is a no-op, to a\n     * different one is refused (the paired implementation). The link is what keeps the row past its tenant's\n     * deletion, so it is audited (`MODEL_COST_AGGREGATE_INVOICE_LINKED`).\n     *\n     * assurance-control: WILDO.PRIVACY.ERASURE_PROPAGATION — only an aggregate an invoice bills survives its tenant.\n     */\n    [ModelCostPeriodAggregates_Operations.LINK_INVOICE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [...MODEL_COST_BILLING_ROLES],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        resourceOperationLike: CoreResourceOperation.UPDATE,\n        requestDto: ModelCostLinkInvoiceRequestSchema,\n      }],\n    },\n  },\n});\n"]}

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.schemas.d.ts

@@ -0,0 +1,83 @@
+/**
+ * # Model-cost period aggregates: one tenant's model cost for one calendar month, in one currency (#1598)
+ *
+ * The durable, invoice-backing record of model spend. Detail rows (`modelCallAttributions`) are operational
+ * logs, kept for `OPERATIONAL_LOGS` and deleted with the tenant; an aggregate is a BUSINESS record: it is what
+ * an invoice cites, so it is kept for the statutory bookkeeping period (`BUSINESS_RECORDS`, counted from the
+ * end of the calendar year: booking vouchers 8 years in Germany, HGB §257(4) and AO §147(3); accounting
+ * documents 10 years in France, Code de commerce L123-22).
+ *
+ * ## Key and write moments
+ *
+ * One row per (`organizationId`, `periodStart`, `currency`), unique, written idempotently: a closed period is
+ * final, so a second close of the same key leaves the row as it is. It is written
+ *
+ * - by the period-close batch, once the month (UTC) has ended plus the declared grace for late rows; and
+ * - for the OPEN period at tenant deletion, before the detail rows are deleted with the tenant.
+ *
+ * Calls no registered authority priced are totalled under the ISO 4217 code `XXX` ("no currency"), so an
+ * unpriced month is recorded rather than silently absent, and `unpricedCallCount` says how many calls it holds.
+ *
+ * ## The invoice link, and what tenant deletion keeps
+ *
+ * `organizationInvoiceRefId` is set by `linkInvoice`, which the application's billing flow calls when that
+ * invoice bills the cost. Relinking to a different invoice is refused. Presence of the link is the flag.
+ * On tenant deletion an aggregate WITH a link is kept (its legal basis is the statutory retention, GDPR Art.
+ * 17(3)(b)); one without is deleted, because nothing justifies keeping it. Automatic linkage by period overlap
+ * was rejected: every subscribed organization has an invoice every period, so every aggregate would be kept
+ * whether or not the cost was billed.
+ *
+ * Holds no personal data: an organization id, instants, counts and money totals.
+ */
+import { z } from 'zod';
+import '@wildo-ai/zod-decorators';
+/** ISO 4217 "no currency": the currency slot of the calls no registered authority priced. */
+export declare const MODEL_COST_UNPRICED_CURRENCY = "XXX";
+export declare enum ModelCostPeriodAggregates_Operations {
+    /** Record that an invoice bills this aggregate's cost, which keeps it past its tenant's deletion. */
+    LINK_INVOICE = "link_invoice"
+}
+/** One pricing authority a period's calls were priced by. */
+export declare const ModelCostPricingAuthorityUseSchema: z.ZodObject<{
+    pricingAuthorityRef: z.ZodString;
+    pricingAuthorityVersion: z.ZodNumber;
+}, z.core.$strict>;
+export type ModelCostPricingAuthorityUse = z.infer<typeof ModelCostPricingAuthorityUseSchema>;
+export declare const ModelCostPeriodAggregateSchema: z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    periodKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    periodStart: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDate>>;
+    periodEnd: z.ZodDate;
+    currency: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    attributedCallCount: z.ZodNumber;
+    unpricedCallCount: z.ZodNumber;
+    promptTokens: z.ZodNumber;
+    completionTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    reasoningTokens: z.ZodNumber;
+    costMinor: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
+    pricingAuthorities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        pricingAuthorityRef: z.ZodString;
+        pricingAuthorityVersion: z.ZodNumber;
+    }, z.core.$strict>>>;
+    closedAt: z.ZodDate;
+    organizationInvoiceRefId: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+}, z.core.$strip>;
+export type ModelCostPeriodAggregate = z.infer<typeof ModelCostPeriodAggregateSchema>;
+export declare const ModelCostLinkInvoiceRequestSchema: z.ZodObject<{
+    organizationInvoiceRefId: z.ZodString;
+}, z.core.$strip>;
+export type ModelCostLinkInvoiceRequest = z.infer<typeof ModelCostLinkInvoiceRequestSchema>;
+/** The calendar month (UTC) an instant falls in: `[start, end)`. */
+export declare function modelCostPeriodOf(instant: Date): {
+    periodStart: Date;
+    periodEnd: Date;
+};
+/** The aggregate's unique natural key: one row per organization, calendar month (UTC) and currency. */
+export declare function modelCostPeriodKey(organizationId: string, periodStart: Date, currency: string): string;
+//# sourceMappingURL=model-cost-period-aggregates.shared.schemas.d.ts.map

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cost-period-aggregates.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/flows-actors/model-cost-period-aggregates.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,0BAA0B,CAAC;AAElC,6FAA6F;AAC7F,eAAO,MAAM,4BAA4B,QAAQ,CAAC;AAElD,oBAAY,oCAAoC;IAC9C,qGAAqG;IACrG,YAAY,iBAAiB;CAC9B;AAED,6DAA6D;AAC7D,eAAO,MAAM,kCAAkC;;;kBAG7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;iBAoCzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,eAAO,MAAM,iCAAiC;;iBAE5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,GAAG;IAAE,WAAW,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,CAIvF;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtG"}

package/dist/esm/flows-actors/model-cost-period-aggregates.shared.schemas.js

@@ -0,0 +1,97 @@
+/**
+ * # Model-cost period aggregates: one tenant's model cost for one calendar month, in one currency (#1598)
+ *
+ * The durable, invoice-backing record of model spend. Detail rows (`modelCallAttributions`) are operational
+ * logs, kept for `OPERATIONAL_LOGS` and deleted with the tenant; an aggregate is a BUSINESS record: it is what
+ * an invoice cites, so it is kept for the statutory bookkeeping period (`BUSINESS_RECORDS`, counted from the
+ * end of the calendar year: booking vouchers 8 years in Germany, HGB §257(4) and AO §147(3); accounting
+ * documents 10 years in France, Code de commerce L123-22).
+ *
+ * ## Key and write moments
+ *
+ * One row per (`organizationId`, `periodStart`, `currency`), unique, written idempotently: a closed period is
+ * final, so a second close of the same key leaves the row as it is. It is written
+ *
+ * - by the period-close batch, once the month (UTC) has ended plus the declared grace for late rows; and
+ * - for the OPEN period at tenant deletion, before the detail rows are deleted with the tenant.
+ *
+ * Calls no registered authority priced are totalled under the ISO 4217 code `XXX` ("no currency"), so an
+ * unpriced month is recorded rather than silently absent, and `unpricedCallCount` says how many calls it holds.
+ *
+ * ## The invoice link, and what tenant deletion keeps
+ *
+ * `organizationInvoiceRefId` is set by `linkInvoice`, which the application's billing flow calls when that
+ * invoice bills the cost. Relinking to a different invoice is refused. Presence of the link is the flag.
+ * On tenant deletion an aggregate WITH a link is kept (its legal basis is the statutory retention, GDPR Art.
+ * 17(3)(b)); one without is deleted, because nothing justifies keeping it. Automatic linkage by period overlap
+ * was rejected: every subscribed organization has an invoice every period, so every aggregate would be kept
+ * whether or not the cost was billed.
+ *
+ * Holds no personal data: an organization id, instants, counts and money totals.
+ */
+import { z } from 'zod';
+import '@wildo-ai/zod-decorators';
+/** ISO 4217 "no currency": the currency slot of the calls no registered authority priced. */
+export const MODEL_COST_UNPRICED_CURRENCY = 'XXX';
+export var ModelCostPeriodAggregates_Operations;
+(function (ModelCostPeriodAggregates_Operations) {
+    /** Record that an invoice bills this aggregate's cost, which keeps it past its tenant's deletion. */
+    ModelCostPeriodAggregates_Operations["LINK_INVOICE"] = "link_invoice";
+})(ModelCostPeriodAggregates_Operations || (ModelCostPeriodAggregates_Operations = {}));
+/** One pricing authority a period's calls were priced by. */
+export const ModelCostPricingAuthorityUseSchema = z.strictObject({
+    pricingAuthorityRef: z.string().min(1).describe('The pricing authority some of the period\'s model calls were priced by.'),
+    pricingAuthorityVersion: z.number().int().min(1).describe('The version of that pricing authority that was in effect for those calls.'),
+});
+export const ModelCostPeriodAggregateSchema = z.object({
+    _id: z.string().isPrimaryKey().isSummaryField(),
+    applicationId: z.string().isDBIndexed(),
+    /**
+     * `<organizationId>:<YYYY-MM>:<currency>` — the aggregate's natural key, unique, so a second close of the
+     * same period and currency can never write a second row ({@link modelCostPeriodKey} is the only producer).
+     */
+    periodKey: z.string().min(1).isUnique({ scope: 'global', sparse: false }).excludeFromUpdate(),
+    /** The tenant. Required: an aggregate is per organization; unattributed calls are not aggregated. */
+    organizationId: z.string().min(1).isDBIndexed().isSummaryField(),
+    /** First instant of the calendar month (UTC), inclusive. */
+    periodStart: z.date().isDBIndexed().isSummaryField(),
+    /** First instant of the next month (UTC), exclusive. */
+    periodEnd: z.date(),
+    /** ISO 4217 code of every total on the row, or `XXX` for the calls no authority priced. */
+    currency: z.string().regex(/^[A-Z]{3}$/).isSummaryField(),
+    /** Distinct provider calls attributed to the tenant in the period, in this currency slot. */
+    attributedCallCount: z.number().int().min(0),
+    /** Of those, the calls no registered authority priced (all of them in the `XXX` slot, none elsewhere). */
+    unpricedCallCount: z.number().int().min(0),
+    /** Token sums per dimension, each row's share applied exactly and rounded up once. */
+    promptTokens: z.number().int().min(0),
+    completionTokens: z.number().int().min(0),
+    totalTokens: z.number().int().min(0),
+    cacheReadTokens: z.number().int().min(0),
+    cacheWriteTokens: z.number().int().min(0),
+    reasoningTokens: z.number().int().min(0),
+    /** The exact sum of the period's call costs in minor units, rounded up ONCE (`CEILING_AGGREGATE_TO_MINOR_UNIT`). 0 in the `XXX` slot. */
+    costMinor: z.number().int().min(0).isSummaryField(),
+    /** The pricing authorities the period's calls were priced by. */
+    pricingAuthorities: z.array(ModelCostPricingAuthorityUseSchema).default([]),
+    /** When the aggregate was written. A closed period is final. */
+    closedAt: z.date(),
+    /** The invoice that bills this cost. Set once by `linkInvoice`; its presence keeps the row past tenant deletion. */
+    organizationInvoiceRefId: z.string().min(1).isDBIndexed().optional(),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+});
+export const ModelCostLinkInvoiceRequestSchema = z.object({
+    organizationInvoiceRefId: z.string().min(1).max(200).describe('Id of the organization invoice reference that bills this period\'s model cost. The invoice must belong to the same organization.'),
+});
+/** The calendar month (UTC) an instant falls in: `[start, end)`. */
+export function modelCostPeriodOf(instant) {
+    const periodStart = new Date(Date.UTC(instant.getUTCFullYear(), instant.getUTCMonth(), 1));
+    const periodEnd = new Date(Date.UTC(instant.getUTCFullYear(), instant.getUTCMonth() + 1, 1));
+    return { periodStart, periodEnd };
+}
+/** The aggregate's unique natural key: one row per organization, calendar month (UTC) and currency. */
+export function modelCostPeriodKey(organizationId, periodStart, currency) {
+    const month = `${periodStart.getUTCFullYear()}-${String(periodStart.getUTCMonth() + 1).padStart(2, '0')}`;
+    return `${organizationId}:${month}:${currency}`;
+}
+//# sourceMappingURL=model-cost-period-aggregates.shared.schemas.js.map