@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/billing/subscription.shared.schemas.js

@@ -14,7 +14,8 @@
  * @see billing-and-features-system.md §6.3 (Subscription & Subscription Items)
  */
 import { z } from 'zod';
-import { declarePolymorphicSchemas } from '../resources/utils/resource-polymorphism.schemas.js';
+import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
+import { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas.js';
 import { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas.js';
 import { SubscriptionStatus } from './billing-enums.shared.schemas.js';
 // ── Subscription Item ──────────────────────────────────────────────
@@ -42,9 +43,19 @@ export const BillingSubscriptionBaseSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
     /** References the parent billing account (polymorphic FK — renamed per variant) */
     billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),
-    status: z.enum(SubscriptionStatus).isDBIndexed().isSummaryField().systemEnum('SubscriptionStatus'),
+    // `.isAuditEvidence()` — subscription status is the ENTITLEMENT gate: the feature resolver
+    // derives a scope's capabilities from it, so a transition to/from ACTIVE silently widens or
+    // narrows what the tenant may do. Recording the before/after states makes an entitlement
+    // dispute answerable from the trail instead of from the payment provider's own records.
+    // Marked on the STATUS only — the provider identifiers on this schema are `.isBackendOnly()`
+    // and the money/customer fields are not authorization evidence, so neither is marked.
+    // assurance-control: WILDO.ACCESS.PRIVILEGE_EVIDENCE — a subscription status transition widens or
+    // narrows tenant capability, so the before/after states are entitlement evidence.
+    status: z.enum(SubscriptionStatus).isDBIndexed().isSummaryField().systemEnum('SubscriptionStatus').isAuditEvidence(),
     /** Subscription items (what products/prices are included) */
-    items: z.array(SubscriptionItemSchema).min(1),
+    // FINANCIAL — see the note on `billing-account.shared.schemas.ts`. What the account holder pays
+    // for, at what quantity; the lifecycle `status` beside it is a state machine, not a datum.
+    items: z.array(SubscriptionItemSchema).min(1).dataCategories(PersonalDataCategory.FINANCIAL),
     /** Period */
     currentPeriodStart: z.date().isDBIndexed().isNotEditable(),
     currentPeriodEnd: z.date().isDBIndexed().isSummaryField().isNotEditable(),
@@ -67,6 +78,25 @@ export const BillingSubscriptionBaseSchema = z.object({
     }).optional().isNotEditable(),
     /** Provider sync (payment methods are managed entirely by provider) */
     providerSubscriptionId: z.string().optional().isBackendOnly(),
+    /**
+     * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).
+     *
+     * ⚠️ **AUTHORING RULE — never store personal data here.** This row is RETAINED when its subject is
+     * erased: the billing-retention decision keeps the financial record for tax/audit obligations, and
+     * subject erasure scrubs the linked USER rather than these rows, because a billing row holds no
+     * personal data of its own — the person is a foreign key. An open bag is the one place that
+     * assumption can be broken by an app author, and nothing would catch it: the erasure scrub is
+     * field-directed (`.impersonalizeWith()`), and it cannot reach inside an arbitrary record whose
+     * keys it does not know.
+     *
+     * Concretely: no names, emails, phone numbers, addresses, free-text notes about a person, or
+     * anything else that identifies one. Personal data written here SURVIVES an erasure — a compliance
+     * breach that the retained label makes look intentional.
+     *
+     * Enforcement is deliberately NOT built (Q3, 2026-07-31): scrubbing these rows would require
+     * hide/freeze to become separable from scrub — a real capability change with no current consumer.
+     * Revisit only if an app is found using the bag this way.
+     */
     metadata: z.record(z.string(), z.string()).optional(),
     createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
@@ -87,6 +117,8 @@ export const billingSubscriptionsPolymorphicDeclaration = declarePolymorphicSche
     baseFieldIdentifier: 'subscriptionId',
     baseEnumKey: 'SUBSCRIPTIONS',
     baseSchema: BillingSubscriptionBaseSchema,
-    variants: BILLING_SCOPE_VARIANTS,
+    // Many subscriptions per scope (LIST/CREATE/UPDATE) — opt out of the
+    // polymorphism engine's singleton-per-scope business-key auto-default.
+    variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),
 });
-//# sourceMappingURL=subscription.shared.schemas.js.map
+//# sourceMappingURL=subscription.shared.schemas.js.map

package/dist/esm/billing/subscription.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscription.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/subscription.shared.schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subscription.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/subscription.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Subscription & Subscription Item Schemas (Shared) — Polymorphic\n *\n * Subscriptions are scope-expanded alongside BillingAccounts. Each subscription\n * variant gets the scope identity FK injected (organizationId / userId)\n * and keeps `billingAccountId` as the FK to its parent billing account variant.\n *\n * The polymorphic expansion produces 2 concrete resources:\n *   - organizationSubscriptions  (with organizationId + organizationBillingAccountId)\n *   - userSubscriptions          (with userId + userBillingAccountId)\n *\n *\n * @see polymorphic-scope-approach-A-expansion.md\n * @see billing-and-features-system.md §6.3 (Subscription & Subscription Items)\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\nimport { SubscriptionStatus } from './billing-enums.shared.schemas';\n\n// ── Subscription Item ──────────────────────────────────────────────\n\n/**\n * A line item within a subscription (one product/price pair).\n */\nexport const SubscriptionItemSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey(),\n  /** Reference to the product */\n  productId: z.string().min(1).isForeignKey().isSummaryField({ populate: true }),\n  /** Reference to the specific price */\n  priceId: z.string().min(1).isForeignKey().isSummaryField({ populate: true }),\n  /** Quantity (e.g., number of seats) */\n  quantity: z.number().min(1).default(1).isSummaryField(),\n  /** Provider sync */\n  providerSubscriptionItemId: z.string().optional().isBackendOnly(),\n});\nexport type SubscriptionItem = z.infer<typeof SubscriptionItemSchema>;\n\n// ── Subscription Base Schema ───────────────────────────────────────\n\n/**\n * Subscription base schema — NO identity scope fields.\n * The polymorphic declaration injects the parent scope FK automatically per variant.\n * `billingAccountId` is kept as the FK to the parent billing account variant.\n */\nexport const BillingSubscriptionBaseSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  /** References the parent billing account (polymorphic FK — renamed per variant) */\n  billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),\n\n  // `.isAuditEvidence()` — subscription status is the ENTITLEMENT gate: the feature resolver\n  // derives a scope's capabilities from it, so a transition to/from ACTIVE silently widens or\n  // narrows what the tenant may do. Recording the before/after states makes an entitlement\n  // dispute answerable from the trail instead of from the payment provider's own records.\n  // Marked on the STATUS only — the provider identifiers on this schema are `.isBackendOnly()`\n  // and the money/customer fields are not authorization evidence, so neither is marked.\n  // assurance-control: WILDO.ACCESS.PRIVILEGE_EVIDENCE — a subscription status transition widens or\n  // narrows tenant capability, so the before/after states are entitlement evidence.\n  status: z.enum(SubscriptionStatus).isDBIndexed().isSummaryField().systemEnum('SubscriptionStatus').isAuditEvidence(),\n\n  /** Subscription items (what products/prices are included) */\n  // FINANCIAL — see the note on `billing-account.shared.schemas.ts`. What the account holder pays\n  // for, at what quantity; the lifecycle `status` beside it is a state machine, not a datum.\n  items: z.array(SubscriptionItemSchema).min(1).dataCategories(PersonalDataCategory.FINANCIAL),\n\n  /** Period */\n  currentPeriodStart: z.date().isDBIndexed().isNotEditable(),\n  currentPeriodEnd: z.date().isDBIndexed().isSummaryField().isNotEditable(),\n\n  /** Trial */\n  trialStart: z.date().optional().isNotEditable(),\n  trialEnd: z.date().optional().isSummaryField().isNotEditable(),\n\n  /** Cancellation */\n  cancelAtPeriodEnd: z.boolean().default(false).isSummaryField(),\n  cancelledAt: z.date().optional().isNotEditable(),\n  cancellationReason: z.string().optional(),\n\n  /** Active discount from a coupon/promotion applied to this subscription (populated from provider) */\n  discount: z.object({\n    providerCouponId: z.string().optional(),\n    percentOff: z.number().optional(),\n    amountOff: z.number().optional(),\n    currency: z.string().optional(),\n    duration: z.string().optional(),\n    durationInMonths: z.number().optional(),\n    end: z.date().optional(),\n  }).optional().isNotEditable(),\n\n  /** Provider sync (payment methods are managed entirely by provider) */\n  providerSubscriptionId: z.string().optional().isBackendOnly(),\n\n  /**\n   * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).\n   *\n   * ⚠️ **AUTHORING RULE — never store personal data here.** This row is RETAINED when its subject is\n   * erased: the billing-retention decision keeps the financial record for tax/audit obligations, and\n   * subject erasure scrubs the linked USER rather than these rows, because a billing row holds no\n   * personal data of its own — the person is a foreign key. An open bag is the one place that\n   * assumption can be broken by an app author, and nothing would catch it: the erasure scrub is\n   * field-directed (`.impersonalizeWith()`), and it cannot reach inside an arbitrary record whose\n   * keys it does not know.\n   *\n   * Concretely: no names, emails, phone numbers, addresses, free-text notes about a person, or\n   * anything else that identifies one. Personal data written here SURVIVES an erasure — a compliance\n   * breach that the retained label makes look intentional.\n   *\n   * Enforcement is deliberately NOT built (Q3, 2026-07-31): scrubbing these rows would require\n   * hide/freeze to become separable from scrub — a real capability change with no current consumer.\n   * Revisit only if an app is found using the bag this way.\n   */\n  metadata: z.record(z.string(), z.string()).optional(),\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type BillingSubscriptionBase = z.infer<typeof BillingSubscriptionBaseSchema>;\n\n// ── Polymorphic Declaration ────────────────────────────────────────\n\n/**\n * Polymorphic declaration for Subscriptions.\n * Produces 2 variants:\n *   - organizations  → organizationSubscriptions  (organizationId injected)\n *   - users          → userSubscriptions          (userId injected)\n *\n *\n * Each variant gets `billingAccountId` renamed to the scoped FK\n * (e.g., `organizationBillingAccountId`) via polymorphic FK transformation.\n */\nexport const billingSubscriptionsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'subscriptions',\n  baseFieldIdentifier: 'subscriptionId',\n  baseEnumKey: 'SUBSCRIPTIONS',\n  baseSchema: BillingSubscriptionBaseSchema,\n  // Many subscriptions per scope (LIST/CREATE/UPDATE) — opt out of the\n  // polymorphism engine's singleton-per-scope business-key auto-default.\n  variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n\n"]}

package/dist/esm/billing/usage-record.shared.resources-config.schemas.d.ts

@@ -5,6 +5,6 @@
  * Spread into the registry factory map:
  *   ...usageRecordsPolymorphicFactories
  */
-import { CoreResourceOperation } from '../resources/resources.shared.core.definitions.js';
-export declare const usageRecordsPolymorphicFactories: Record<string, import("../index.js").ResourceConfiguration_InitializationFactory<undefined, CoreResourceOperation.READ | CoreResourceOperation.UPDATE | CoreResourceOperation.CREATE | CoreResourceOperation.LIST, any>>;
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+export declare const usageRecordsPolymorphicFactories: Record<string, import("..").ResourceConfiguration_InitializationFactory<undefined, CoreResourceOperation.READ | CoreResourceOperation.UPDATE | CoreResourceOperation.CREATE | CoreResourceOperation.LIST, any>>;
 //# sourceMappingURL=usage-record.shared.resources-config.schemas.d.ts.map

package/dist/esm/billing/usage-record.shared.resources-config.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-record.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/usage-record.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AASzG,eAAO,MAAM,gCAAgC,iNAyD5C,CAAC"}
+{"version":3,"file":"usage-record.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/usage-record.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAWzG,eAAO,MAAM,gCAAgC,iNAiE5C,CAAC"}

package/dist/esm/billing/usage-record.shared.resources-config.schemas.js

@@ -8,10 +8,15 @@
 import { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions.js';
 import { ResourceOperationRiskLevel, ResourceOperationVariantType, } from '../resources/resources.shared.schemas.js';
 import { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory.js';
-import { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
 import { usageRecordsPolymorphicDeclaration } from './usage-record.shared.schemas.js';
+import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
+import { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas.js';
 export const usageRecordsPolymorphicFactories = createPolymorphicResourceConfigurations(usageRecordsPolymorphicDeclaration, {
     isSystemResource: true,
+    /** Subject-export disclosure. The subject's own usage records. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */
+    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
+    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },
     coreOperations: [
         CoreResourceOperation.READ,
         CoreResourceOperation.LIST,
@@ -21,48 +26,52 @@ export const usageRecordsPolymorphicFactories = createPolymorphicResourceConfigu
     operationsConfiguration: {
         [CoreResourceOperation.READ]: {
             variants: [{
-                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    // API_CALL: usage records are a user-facing collection (Settings Hub → Billing →
+                    // Usage, and the resource presets' LIST/READ views). REPOSITORY_ONLY would strip
+                    // the op from the frontend registry and register no HTTP route. Writes are
+                    // INTERNAL_CALL (service-pipeline; metered internally / by webhooks, not by users).
+                    variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
         },
         [CoreResourceOperation.LIST]: {
             variants: [{
-                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
         },
         [CoreResourceOperation.CREATE]: {
             variants: [{
-                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
         },
         [CoreResourceOperation.UPDATE]: {
             variants: [{
-                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
         },
     },
 });
-//# sourceMappingURL=usage-record.shared.resources-config.schemas.js.map
+//# sourceMappingURL=usage-record.shared.resources-config.schemas.js.map

package/dist/esm/billing/usage-record.shared.resources-config.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage-record.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../src/billing/usage-record.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AACzG,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,uCAAuC,EAAE,MAAM,kDAAkD,CAAC;AAC3G,OAAO,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjF,OAAO,EAAE,kCAAkC,EAAE,MAAM,+BAA+B,CAAC;AAEnF,MAAM,CAAC,MAAM,gCAAgC,GAAG,uCAAuC,CACrF,kCAAkC,EAClC;IACE,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE;QACd,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;KAC7B;IACD,uBAAuB,EAAE;QACvB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;wBAC5D,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE;qBAC7B;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;wBAC5D,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE;qBAC7B;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;wBAC5D,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE;qBAC7B;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;wBAC5D,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE;qBAC7B;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;KACF;CACF,CACF,CAAC"}
+{"version":3,"file":"usage-record.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/usage-record.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Usage Record Resource Configuration — Polymorphic\n *\n * Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n *   ...usageRecordsPolymorphicFactories\n */\n\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { usageRecordsPolymorphicDeclaration } from './usage-record.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\n\nexport const usageRecordsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  usageRecordsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    /** Subject-export disclosure. The subject's own usage records. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */\n    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n    ],\n    operationsConfiguration: {\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          // API_CALL: usage records are a user-facing collection (Settings Hub → Billing →\n          // Usage, and the resource presets' LIST/READ views). REPOSITORY_ONLY would strip\n          // the op from the frontend registry and register no HTTP route. Writes are\n          // INTERNAL_CALL (service-pipeline; metered internally / by webhooks, not by users).\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.LIST]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.CREATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.UPDATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n    },\n  },\n);\n"]}

package/dist/esm/billing/usage-record.shared.schemas.d.ts

@@ -1,8 +1,11 @@
 /**
  * Usage Record Schema (Shared) — Polymorphic
  *
- * Tracks metered usage for METERED products. Records are aggregated
- * and flushed to the billing provider periodically (per ProductBehaviorPolicy.metering).
+ * Tracks metered usage for METERED products. The current metering service groups
+ * unreported rows by billing account and product when its scheduled flush runs.
+ * `ProductBehaviorPolicy.metering` is an authored policy surface, but the current
+ * flush scheduler does not consume its interval, window or retry members; do not
+ * present those values as an effective reporting schedule until that runtime join exists.
  *
  * POLYMORPHIC EXPANSION: Like subscriptions, usage records are scope-expanded.
  * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:
@@ -13,40 +16,40 @@
  * @see billing-and-features-system.md §6.6 (Usage Records)
  */
 import { z } from 'zod';
-import { UsageSourceType } from './billing-enums.shared.schemas.js';
+import { UsageSourceType } from './billing-enums.shared.schemas';
 export declare const UsageRecordSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
     billingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-    productKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-    quantity: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
+    productKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
+    quantity: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>>;
     timestamp: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDate>>>;
     source: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
         type: z.ZodEnum<typeof UsageSourceType>;
         resourceType: z.ZodOptional<z.ZodString>;
         operationIdentifier: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     reportedToProvider: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
     reportedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type UsageRecord = z.infer<typeof UsageRecordSchema>;
-export declare const usageRecordsPolymorphicDeclaration: import("../index.js").PolymorphicSchemaDeclaration<z.ZodObject<{
+export declare const usageRecordsPolymorphicDeclaration: import("..").PolymorphicSchemaDeclaration<z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
     billingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-    productKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
-    quantity: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
+    productKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
+    quantity: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>>;
     timestamp: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDate>>>;
     source: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
         type: z.ZodEnum<typeof UsageSourceType>;
         resourceType: z.ZodOptional<z.ZodString>;
         operationIdentifier: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     reportedToProvider: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
     reportedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
-}, z.core.$strip, core.$ZodObjectExtra>>;
+}, z.core.$strip>>;
 //# sourceMappingURL=usage-record.shared.schemas.d.ts.map

package/dist/esm/billing/usage-record.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-record.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/usage-record.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;uCAyB5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI5D,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;wCAM7C,CAAC"}
+{"version":3,"file":"usage-record.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/usage-record.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;iBA8C5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI5D,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;kBAQ7C,CAAC"}

package/dist/esm/billing/usage-record.shared.schemas.js

@@ -1,8 +1,11 @@
 /**
  * Usage Record Schema (Shared) — Polymorphic
  *
- * Tracks metered usage for METERED products. Records are aggregated
- * and flushed to the billing provider periodically (per ProductBehaviorPolicy.metering).
+ * Tracks metered usage for METERED products. The current metering service groups
+ * unreported rows by billing account and product when its scheduled flush runs.
+ * `ProductBehaviorPolicy.metering` is an authored policy surface, but the current
+ * flush scheduler does not consume its interval, window or retry members; do not
+ * present those values as an effective reporting schedule until that runtime join exists.
  *
  * POLYMORPHIC EXPANSION: Like subscriptions, usage records are scope-expanded.
  * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:
@@ -13,16 +16,19 @@
  * @see billing-and-features-system.md §6.6 (Usage Records)
  */
 import { z } from 'zod';
-import { declarePolymorphicSchemas } from '../resources/utils/resource-polymorphism.schemas.js';
+import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
+import { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas.js';
 import { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas.js';
 import { UsageSourceType } from './billing-enums.shared.schemas.js';
 export const UsageRecordSchema = z.object({
     _id: z.string().min(1).isPrimaryKey(),
     billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),
     /** Product key for grouping/lookup (matches ProductDefinition.key) */
-    productKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable(),
+    productKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable().dataCategories(PersonalDataCategory.USAGE),
     /** Usage quantity */
-    quantity: z.number().min(0).isSummaryField(),
+    // USAGE, not FINANCIAL. A metered quantity is what the person DID in the product; the money it
+    // becomes lives on the invoice. Two different sentences in a notice, and they read differently.
+    quantity: z.number().min(0).isSummaryField().dataCategories(PersonalDataCategory.USAGE),
     /** When the usage occurred */
     timestamp: z.date().isDBIndexed().isSummaryField().isNotEditable(),
     /** What generated this usage */
@@ -35,6 +41,25 @@ export const UsageRecordSchema = z.object({
     /** Whether this has been reported to the billing provider */
     reportedToProvider: z.boolean().default(false).isDBIndexed().isNotEditable(),
     reportedAt: z.date().optional().isNotEditable(),
+    /**
+     * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).
+     *
+     * ⚠️ **AUTHORING RULE — never store personal data here.** This row is RETAINED when its subject is
+     * erased: the billing-retention decision keeps the financial record for tax/audit obligations, and
+     * subject erasure scrubs the linked USER rather than these rows, because a billing row holds no
+     * personal data of its own — the person is a foreign key. An open bag is the one place that
+     * assumption can be broken by an app author, and nothing would catch it: the erasure scrub is
+     * field-directed (`.impersonalizeWith()`), and it cannot reach inside an arbitrary record whose
+     * keys it does not know.
+     *
+     * Concretely: no names, emails, phone numbers, addresses, free-text notes about a person, or
+     * anything else that identifies one. Personal data written here SURVIVES an erasure — a compliance
+     * breach that the retained label makes look intentional.
+     *
+     * Enforcement is deliberately NOT built (Q3, 2026-07-31): scrubbing these rows would require
+     * hide/freeze to become separable from scrub — a real capability change with no current consumer.
+     * Revisit only if an app is found using the bag this way.
+     */
     metadata: z.record(z.string(), z.string()).optional(),
     createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
 });
@@ -44,6 +69,8 @@ export const usageRecordsPolymorphicDeclaration = declarePolymorphicSchemas({
     baseFieldIdentifier: 'usageRecordId',
     baseEnumKey: 'USAGE_RECORDS',
     baseSchema: UsageRecordSchema,
-    variants: BILLING_SCOPE_VARIANTS,
+    // Many metered usage rows per scope — opt out of the polymorphism engine's
+    // singleton-per-scope business-key auto-default.
+    variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),
 });
-//# sourceMappingURL=usage-record.shared.schemas.js.map
+//# sourceMappingURL=usage-record.shared.schemas.js.map

package/dist/esm/billing/usage-record.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage-record.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/usage-record.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,MAAM,kDAAkD,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE;IACrC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IACnI,sEAAsE;IACtE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAE5E,qBAAqB;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE;IAC5C,8BAA8B;IAC9B,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAElE,gCAAgC;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;QAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACnC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACnC,CAAC,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAE7B,6DAA6D;IAC7D,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,aAAa,EAAE;IAC5E,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAE/C,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,CAAC;IAC1E,gBAAgB,EAAE,cAAc;IAChC,mBAAmB,EAAE,eAAe;IACpC,WAAW,EAAE,eAAe;IAC5B,UAAU,EAAE,iBAAiB;IAC7B,QAAQ,EAAE,sBAAsB;CACjC,CAAC,CAAC"}
+{"version":3,"file":"usage-record.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/usage-record.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAC;AACnG,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,kDAAkD,CAAC;AAC/H,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE;IACrC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IACnI,sEAAsE;IACtE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,KAAK,CAAC;IAEvH,qBAAqB;IACrB,+FAA+F;IAC/F,gGAAgG;IAChG,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,KAAK,CAAC;IACvF,8BAA8B;IAC9B,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAElE,gCAAgC;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;QAC7B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACnC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACnC,CAAC,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAE7B,6DAA6D;IAC7D,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,aAAa,EAAE;IAC5E,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAE/C;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,CAAC;IAC1E,gBAAgB,EAAE,cAAc;IAChC,mBAAmB,EAAE,eAAe;IACpC,WAAW,EAAE,eAAe;IAC5B,UAAU,EAAE,iBAAiB;IAC7B,2EAA2E;IAC3E,iDAAiD;IACjD,QAAQ,EAAE,sBAAsB,CAAC,GAAG,CAAC,gCAAgC,CAAC;CACvE,CAAC,CAAC","sourcesContent":["/**\n * Usage Record Schema (Shared) — Polymorphic\n *\n * Tracks metered usage for METERED products. The current metering service groups\n * unreported rows by billing account and product when its scheduled flush runs.\n * `ProductBehaviorPolicy.metering` is an authored policy surface, but the current\n * flush scheduler does not consume its interval, window or retry members; do not\n * present those values as an effective reporting schedule until that runtime join exists.\n *\n * POLYMORPHIC EXPANSION: Like subscriptions, usage records are scope-expanded.\n * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:\n *   - organizationUsageRecords  (with organizationId + organizationBillingAccountId)\n *   - userUsageRecords          (with userId + userBillingAccountId)\n *\n *\n * @see billing-and-features-system.md §6.6 (Usage Records)\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\nimport { UsageSourceType } from './billing-enums.shared.schemas';\n\nexport const UsageRecordSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey(),\n  billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),\n  /** Product key for grouping/lookup (matches ProductDefinition.key) */\n  productKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable().dataCategories(PersonalDataCategory.USAGE),\n\n  /** Usage quantity */\n  // USAGE, not FINANCIAL. A metered quantity is what the person DID in the product; the money it\n  // becomes lives on the invoice. Two different sentences in a notice, and they read differently.\n  quantity: z.number().min(0).isSummaryField().dataCategories(PersonalDataCategory.USAGE),\n  /** When the usage occurred */\n  timestamp: z.date().isDBIndexed().isSummaryField().isNotEditable(),\n\n  /** What generated this usage */\n  source: z.object({\n    type: z.enum(UsageSourceType),\n    resourceType: z.string().optional(),\n    operationIdentifier: z.string().optional(),\n    description: z.string().optional(),\n  }).optional().isNotEditable(),\n\n  /** Whether this has been reported to the billing provider */\n  reportedToProvider: z.boolean().default(false).isDBIndexed().isNotEditable(),\n  reportedAt: z.date().optional().isNotEditable(),\n\n  /**\n   * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).\n   *\n   * ⚠️ **AUTHORING RULE — never store personal data here.** This row is RETAINED when its subject is\n   * erased: the billing-retention decision keeps the financial record for tax/audit obligations, and\n   * subject erasure scrubs the linked USER rather than these rows, because a billing row holds no\n   * personal data of its own — the person is a foreign key. An open bag is the one place that\n   * assumption can be broken by an app author, and nothing would catch it: the erasure scrub is\n   * field-directed (`.impersonalizeWith()`), and it cannot reach inside an arbitrary record whose\n   * keys it does not know.\n   *\n   * Concretely: no names, emails, phone numbers, addresses, free-text notes about a person, or\n   * anything else that identifies one. Personal data written here SURVIVES an erasure — a compliance\n   * breach that the retained label makes look intentional.\n   *\n   * Enforcement is deliberately NOT built (Q3, 2026-07-31): scrubbing these rows would require\n   * hide/freeze to become separable from scrub — a real capability change with no current consumer.\n   * Revisit only if an app is found using the bag this way.\n   */\n  metadata: z.record(z.string(), z.string()).optional(),\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type UsageRecord = z.infer<typeof UsageRecordSchema>;\n\n// ── Polymorphic Declaration ────────────────────────────────────────\n\nexport const usageRecordsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'usageRecords',\n  baseFieldIdentifier: 'usageRecordId',\n  baseEnumKey: 'USAGE_RECORDS',\n  baseSchema: UsageRecordSchema,\n  // Many metered usage rows per scope — opt out of the polymorphism engine's\n  // singleton-per-scope business-key auto-default.\n  variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n"]}

package/dist/esm/charts/aggregation-query.shared.schemas.d.ts

@@ -6,7 +6,7 @@
  * use AggregationQuerySchema directly.
  * ────────────────────────────────────────────────────────────── */
 import { z } from 'zod';
-import { AggregateFunction, TimeGranularity, SortDirection, ComparisonOperator, JoinType, ContextFilterSource, WindowFunctionType, DimensionSortBy } from './aggregation.shared.definitions.js';
+import { AggregateFunction, TimeGranularity, SortDirection, ComparisonOperator, JoinType, ContextFilterSource, WindowFunctionType, DimensionSortBy } from './aggregation.shared.definitions';
 export declare const MeasureSchema: z.ZodObject<{
     ref: z.ZodString;
     field: z.ZodString;
@@ -16,7 +16,7 @@ export declare const MeasureSchema: z.ZodObject<{
     separator: z.ZodOptional<z.ZodString>;
     arrayLimit: z.ZodOptional<z.ZodNumber>;
     filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type Measure = z.infer<typeof MeasureSchema>;
 export declare const DimensionSchema: z.ZodObject<{
     ref: z.ZodString;
@@ -27,27 +27,27 @@ export declare const DimensionSchema: z.ZodObject<{
     dateRange: z.ZodOptional<z.ZodObject<{
         from: z.ZodOptional<z.ZodString>;
         to: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     bin: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         step: z.ZodNumber;
-    }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         boundaries: z.ZodArray<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>]>>;
+    }, z.core.$strip>]>>;
     sort: z.ZodOptional<z.ZodObject<{
         direction: z.ZodDefault<z.ZodEnum<typeof SortDirection>>;
         by: z.ZodDefault<z.ZodEnum<typeof DimensionSortBy>>;
         measureRef: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     topN: z.ZodOptional<z.ZodNumber>;
     groupOther: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type Dimension = z.infer<typeof DimensionSchema>;
 export declare const ComputedMeasureSchema: z.ZodObject<{
     ref: z.ZodString;
     label: z.ZodOptional<z.ZodString>;
     expression: z.ZodString;
     dependsOn: z.ZodArray<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ComputedMeasure = z.infer<typeof ComputedMeasureSchema>;
 export declare const WindowFunctionSchema: z.ZodObject<{
     ref: z.ZodString;
@@ -57,7 +57,7 @@ export declare const WindowFunctionSchema: z.ZodObject<{
     windowSize: z.ZodOptional<z.ZodNumber>;
     partitionBy: z.ZodOptional<z.ZodString>;
     orderBy: z.ZodOptional<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type WindowFunction = z.infer<typeof WindowFunctionSchema>;
 export declare const ResourceJoinSchema: z.ZodObject<{
     resourceType: z.ZodString;
@@ -65,20 +65,20 @@ export declare const ResourceJoinSchema: z.ZodObject<{
     alias: z.ZodString;
     selectFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
     joinType: z.ZodDefault<z.ZodEnum<typeof JoinType>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ResourceJoin = z.infer<typeof ResourceJoinSchema>;
 export declare const HavingClauseSchema: z.ZodObject<{
     measureRef: z.ZodString;
     operator: z.ZodEnum<typeof ComparisonOperator>;
     value: z.ZodNumber;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type HavingClause = z.infer<typeof HavingClauseSchema>;
 export declare const ContextFilterSchema: z.ZodObject<{
     field: z.ZodString;
     operator: z.ZodDefault<z.ZodEnum<typeof ComparisonOperator>>;
     source: z.ZodEnum<typeof ContextFilterSource>;
     sourceField: z.ZodOptional<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ContextFilter = z.infer<typeof ContextFilterSchema>;
 /**
  * `refreshInterval` used to sit on `AggregationQuery`, but polling semantics are
@@ -93,7 +93,7 @@ export declare const AggregationQuerySchema: z.ZodPipe<z.ZodUnknown, z.ZodObject
         operator: z.ZodDefault<z.ZodEnum<typeof ComparisonOperator>>;
         source: z.ZodEnum<typeof ContextFilterSource>;
         sourceField: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     dimensions: z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
         field: z.ZodString;
@@ -103,20 +103,20 @@ export declare const AggregationQuerySchema: z.ZodPipe<z.ZodUnknown, z.ZodObject
         dateRange: z.ZodOptional<z.ZodObject<{
             from: z.ZodOptional<z.ZodString>;
             to: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         bin: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             step: z.ZodNumber;
-        }, z.core.$strip, core.$ZodObjectExtra>, z.ZodObject<{
+        }, z.core.$strip>, z.ZodObject<{
             boundaries: z.ZodArray<z.ZodNumber>;
-        }, z.core.$strip, core.$ZodObjectExtra>]>>;
+        }, z.core.$strip>]>>;
         sort: z.ZodOptional<z.ZodObject<{
             direction: z.ZodDefault<z.ZodEnum<typeof SortDirection>>;
             by: z.ZodDefault<z.ZodEnum<typeof DimensionSortBy>>;
             measureRef: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         topN: z.ZodOptional<z.ZodNumber>;
         groupOther: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     measures: z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
         field: z.ZodString;
@@ -126,13 +126,13 @@ export declare const AggregationQuerySchema: z.ZodPipe<z.ZodUnknown, z.ZodObject
         separator: z.ZodOptional<z.ZodString>;
         arrayLimit: z.ZodOptional<z.ZodNumber>;
         filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     computedMeasures: z.ZodOptional<z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
         expression: z.ZodString;
         dependsOn: z.ZodArray<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     windowFunctions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
@@ -141,45 +141,45 @@ export declare const AggregationQuerySchema: z.ZodPipe<z.ZodUnknown, z.ZodObject
         windowSize: z.ZodOptional<z.ZodNumber>;
         partitionBy: z.ZodOptional<z.ZodString>;
         orderBy: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     joins: z.ZodOptional<z.ZodArray<z.ZodObject<{
         resourceType: z.ZodString;
         foreignKeyField: z.ZodString;
         alias: z.ZodString;
         selectFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
         joinType: z.ZodDefault<z.ZodEnum<typeof JoinType>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     having: z.ZodOptional<z.ZodArray<z.ZodObject<{
         measureRef: z.ZodString;
         operator: z.ZodEnum<typeof ComparisonOperator>;
         value: z.ZodNumber;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     limit: z.ZodOptional<z.ZodNumber>;
     orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
         direction: z.ZodDefault<z.ZodEnum<typeof SortDirection>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+    }, z.core.$strip>>>;
     timeoutMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     timezone: z.ZodOptional<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>>;
+}, z.core.$strip>>;
 export type AggregationQuery = z.infer<typeof AggregationQuerySchema>;
 export declare const AggregationQueryResponseRowSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export type AggregationQueryResponseRow = z.infer<typeof AggregationQueryResponseRowSchema>;
 export declare const AggregationQueryMetaSchema: z.ZodObject<{
-    executionTimeMs: z.ZodNumber;
-    totalRows: z.ZodNumber;
-    truncated: z.ZodBoolean;
-    resolvedTimezone: z.ZodString;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    executionTimeMs: z.ZodOptional<z.ZodNumber>;
+    totalRows: z.ZodOptional<z.ZodNumber>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    resolvedTimezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export type AggregationQueryMeta = z.infer<typeof AggregationQueryMetaSchema>;
 export declare const AggregationQueryResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     queryMeta: z.ZodObject<{
-        executionTimeMs: z.ZodNumber;
-        totalRows: z.ZodNumber;
-        truncated: z.ZodBoolean;
-        resolvedTimezone: z.ZodString;
-    }, z.core.$strip, core.$ZodObjectExtra>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+        executionTimeMs: z.ZodOptional<z.ZodNumber>;
+        totalRows: z.ZodOptional<z.ZodNumber>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        resolvedTimezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export type AggregationQueryResponse = z.infer<typeof AggregationQueryResponseSchema>;
 //# sourceMappingURL=aggregation-query.shared.schemas.d.ts.map

package/dist/esm/charts/aggregation-query.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregation-query.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/charts/aggregation-query.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;oEAMoE;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAI1C,eAAO,MAAM,aAAa;;;;;;;;;uCAqBxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAIpD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;uCAwC1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD,eAAO,MAAM,qBAAqB;;;;;uCAkBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE,eAAO,MAAM,oBAAoB;;;;;;;;uCAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,eAAO,MAAM,kBAAkB;;;;;;uCAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,eAAO,MAAM,kBAAkB;;;;uCAO7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,eAAO,MAAM,mBAAmB;;;;;uCAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA0ChE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wCAaE,CAAC;AACtC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,iCAAiC,wCAAoC,CAAC;AACnF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F,eAAO,MAAM,0BAA0B;;;;;uCASrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,8BAA8B;;;;;;;;uCAKzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC"}
+{"version":3,"file":"aggregation-query.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/charts/aggregation-query.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;oEAMoE;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAI1C,eAAO,MAAM,aAAa;;;;;;;;;iBAqBxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAIpD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;iBAwC1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD,eAAO,MAAM,qBAAqB;;;;;iBAkBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE,eAAO,MAAM,oBAAoB;;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,eAAO,MAAM,kBAAkB;;;;;;iBAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,eAAO,MAAM,kBAAkB;;;;iBAO7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,eAAO,MAAM,mBAAmB;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA0ChE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaE,CAAC;AACtC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,iCAAiC,wCAAoC,CAAC;AACnF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F,eAAO,MAAM,0BAA0B;;;;;iBASrC,CAAC;AAKH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,8BAA8B;;;;;;;;iBAKzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC"}