@wildo-ai/saas-models 1.1.2 → 1.1.3

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

@@ -33,7 +33,21 @@ export var BillingSubscription_Operations;
 // ── Request DTOs ─────────────────────────────────────────────────────
 /** Request DTO for CANCEL operation — shared between resource config and custom impl */
 export const BillingSubscription_CancelRequestDto = z.object({
-    cancelImmediately: z.boolean().default(false),
+    /**
+     * OPTIONAL, with no default — and the absence of a default is the point (#408, 2026-09-08).
+     *
+     * It carried `.default(false)` until then, which materialized `false` at parse and made "the
+     * caller expressed no preference" a state the handler could never observe. That erased the only
+     * input `ProductBehaviorPolicy.cancellation.defaultBehavior` exists to answer, so an authored
+     * product default was unimplementable rather than merely unimplemented — a field one layer up
+     * had already decided for it.
+     *
+     * The resolution order is now: the caller's explicit choice, then the plan product's
+     * `defaultBehavior`, then period-end as the framework floor. Omitting it still ends in period-end
+     * for a product that authors no policy, so nothing changes for an existing caller — what changes
+     * is that a product declaring IMMEDIATE now gets it.
+     */
+    cancelImmediately: z.boolean().optional(),
     reason: z.string().max(500).optional(),
 });
 /** Request DTO for CHANGE_PLAN operation — shared between resource config and custom impl */

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

@@ -1 +1 @@
-{"version":3,"file":"subscription.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/subscription.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Subscription 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 *   ...billingSubscriptionsPolymorphicFactories\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 3\n */\n\nimport { z } from 'zod';\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { billingSubscriptionsPolymorphicDeclaration } from './subscription.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum BillingSubscription_Operations {\n  /** Cancel the subscription (at period end or immediately) */\n  CANCEL = 'cancel',\n  /** Resume a cancelled subscription before period end */\n  RESUME = 'resume',\n  /** Change to a different plan (upgrade/downgrade) */\n  CHANGE_PLAN = 'change_plan',\n  /** Add an addon product to the subscription */\n  ADD_ADDON = 'add_addon',\n  /** Remove an addon product from the subscription */\n  REMOVE_ADDON = 'remove_addon',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\n/** Request DTO for CANCEL operation — shared between resource config and custom impl */\nexport const BillingSubscription_CancelRequestDto = z.object({\n  cancelImmediately: z.boolean().default(false),\n  reason: z.string().max(500).optional(),\n});\n\n/** Request DTO for CHANGE_PLAN operation — shared between resource config and custom impl */\nexport const BillingSubscription_ChangePlanRequestDto = z.object({\n  newProductKey: z.string().min(1),\n  newPriceId: z.string().min(1),\n});\n\n/** Request DTO for ADD_ADDON operation — shared between resource config and custom impl */\nexport const BillingSubscription_AddAddonRequestDto = z.object({\n  addonProductKey: z.string().min(1),\n  priceId: z.string().min(1),\n});\n\n/** Request DTO for REMOVE_ADDON operation — shared between resource config and custom impl */\nexport const BillingSubscription_RemoveAddonRequestDto = z.object({\n  addonProductKey: z.string().min(1),\n});\n\n// =============================================================================\n// POLYMORPHIC FACTORY — 2 variants (org, user)\n// =============================================================================\n\n/**\n * Polymorphic factory map for subscriptions.\n * Spread into `coreShared_ResourcesConfigurations_FactoryMap`:\n *   ...billingSubscriptionsPolymorphicFactories\n *\n * Produces entries for:\n *   - organizationSubscriptions\n *   - userSubscriptions\n */\nexport const billingSubscriptionsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  billingSubscriptionsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    // System-context LIST opt-in (fail-closed default is FORBIDDEN). Subject erasure enumerates the\n    // erased person's live subscriptions so it can cancel them at the provider immediately — an\n    // erased subject must stop being billed. There is no request context on that path (the subject\n    // is being erased), so it reads through `SystemAccessBackendService.listAsSystem`, which refuses\n    // any resource that has not opted in here. LIST's default variant is API_CALL and therefore\n    // resolves through `getServiceOperationPathDefault`; a REPOSITORY_ONLY-only LIST would satisfy\n    // this grant and still fail to resolve at erasure time.\n    systemAccessPolicy: {\n      // Subject-export disclosure. The subject's own subscriptions. 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      exportSubject: ResourceSystemAccessMode.ALLOWED,\n      list: ResourceSystemAccessMode.ALLOWED,\n    },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.\n *\n * `RETAIN_ONLY` is a positive ASSERTION that this resource holds no personal data of its own. The row is\n * subscription terms — plan and price references, status and period boundaries — amounts and contract terms about the ACCOUNT. They\n * describe nobody once the linked USER row is scrubbed, and they must survive erasure for the tax/audit\n * obligation this family exists to serve, so they can be neither scrubbed nor honestly declared as\n * personal data the row holds. The person is the scope foreign key, which the never-scrub floor protects.\n *\n * The assertion is CHECKED in both directions: the factory refuses `RETAIN_ONLY` if any field declares an\n * impersonalize treatment, and (since 2026-08-31) if any non-floor field declares `.dataCategories()`.\n     */\n    retentionPolicy: {\n      mode: ErasureRetentionMode.RETAIN_ONLY,\n    },\n\n    /**\n     * Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n *  record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n *  session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n     */\n    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n    customOperation: BillingSubscription_Operations,\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n      CoreResourceOperation.UPDATE_MANY,\n    ],\n    operationsConfiguration: {\n      /*\n       * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n       * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n       * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n       * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n       * verb the impersonalize writer uses to stamp the retention markers.\n       */\n      [CoreResourceOperation.UPDATE_MANY]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n        }],\n      },\n\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          // API_CALL: subscriptions are a user-facing collection (Settings Hub → Billing →\n          // Subscriptions, and the resource presets' LIST/READ views). REPOSITORY_ONLY would\n          // strip the op from the frontend registry and register no HTTP route. Writes\n          // (checkout + webhook sync) are INTERNAL_CALL (service-pipeline) / custom API_CALL ops.\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.MEDIUM,\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.MEDIUM,\n        }],\n      },\n      [BillingSubscription_Operations.CANCEL]: {\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.CRITICAL,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_CancelRequestDto,\n        }],\n      },\n      [BillingSubscription_Operations.RESUME]: {\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.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          // RESUME clears a pending cancellation at the provider and mirrors the result — it\n          // takes no caller input. Its implementation already ignores the payload, but the\n          // dispatcher MERGES a prefix's return onto the caller payload rather than replacing\n          // it, so an unnarrowed contract is still writable. Omitting `requestDto` would\n          // auto-derive the FULL subscription update DTO (`status`, `items`, `discount`,\n          // `currentPeriodEnd`, `cancelledAt`, …), letting a subscriber rewrite their own\n          // billing state through \"resume\".\n          requestDto: z.object({}),\n        }],\n      },\n      [BillingSubscription_Operations.CHANGE_PLAN]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_ChangePlanRequestDto,\n        }],\n      },\n      [BillingSubscription_Operations.ADD_ADDON]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_AddAddonRequestDto,\n        }],\n      },\n      [BillingSubscription_Operations.REMOVE_ADDON]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_RemoveAddonRequestDto,\n        }],\n      },\n    },\n  },\n);\n"]}
+{"version":3,"file":"subscription.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/subscription.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Subscription 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 *   ...billingSubscriptionsPolymorphicFactories\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 3\n */\n\nimport { z } from 'zod';\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { billingSubscriptionsPolymorphicDeclaration } from './subscription.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum BillingSubscription_Operations {\n  /** Cancel the subscription (at period end or immediately) */\n  CANCEL = 'cancel',\n  /** Resume a cancelled subscription before period end */\n  RESUME = 'resume',\n  /** Change to a different plan (upgrade/downgrade) */\n  CHANGE_PLAN = 'change_plan',\n  /** Add an addon product to the subscription */\n  ADD_ADDON = 'add_addon',\n  /** Remove an addon product from the subscription */\n  REMOVE_ADDON = 'remove_addon',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\n/** Request DTO for CANCEL operation — shared between resource config and custom impl */\nexport const BillingSubscription_CancelRequestDto = z.object({\n  /**\n   * OPTIONAL, with no default — and the absence of a default is the point (#408, 2026-09-08).\n   *\n   * It carried `.default(false)` until then, which materialized `false` at parse and made \"the\n   * caller expressed no preference\" a state the handler could never observe. That erased the only\n   * input `ProductBehaviorPolicy.cancellation.defaultBehavior` exists to answer, so an authored\n   * product default was unimplementable rather than merely unimplemented — a field one layer up\n   * had already decided for it.\n   *\n   * The resolution order is now: the caller's explicit choice, then the plan product's\n   * `defaultBehavior`, then period-end as the framework floor. Omitting it still ends in period-end\n   * for a product that authors no policy, so nothing changes for an existing caller — what changes\n   * is that a product declaring IMMEDIATE now gets it.\n   */\n  cancelImmediately: z.boolean().optional(),\n  reason: z.string().max(500).optional(),\n});\n\n/** Request DTO for CHANGE_PLAN operation — shared between resource config and custom impl */\nexport const BillingSubscription_ChangePlanRequestDto = z.object({\n  newProductKey: z.string().min(1),\n  newPriceId: z.string().min(1),\n});\n\n/** Request DTO for ADD_ADDON operation — shared between resource config and custom impl */\nexport const BillingSubscription_AddAddonRequestDto = z.object({\n  addonProductKey: z.string().min(1),\n  priceId: z.string().min(1),\n});\n\n/** Request DTO for REMOVE_ADDON operation — shared between resource config and custom impl */\nexport const BillingSubscription_RemoveAddonRequestDto = z.object({\n  addonProductKey: z.string().min(1),\n});\n\n// =============================================================================\n// POLYMORPHIC FACTORY — 2 variants (org, user)\n// =============================================================================\n\n/**\n * Polymorphic factory map for subscriptions.\n * Spread into `coreShared_ResourcesConfigurations_FactoryMap`:\n *   ...billingSubscriptionsPolymorphicFactories\n *\n * Produces entries for:\n *   - organizationSubscriptions\n *   - userSubscriptions\n */\nexport const billingSubscriptionsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  billingSubscriptionsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    // System-context LIST opt-in (fail-closed default is FORBIDDEN). Subject erasure enumerates the\n    // erased person's live subscriptions so it can cancel them at the provider immediately — an\n    // erased subject must stop being billed. There is no request context on that path (the subject\n    // is being erased), so it reads through `SystemAccessBackendService.listAsSystem`, which refuses\n    // any resource that has not opted in here. LIST's default variant is API_CALL and therefore\n    // resolves through `getServiceOperationPathDefault`; a REPOSITORY_ONLY-only LIST would satisfy\n    // this grant and still fail to resolve at erasure time.\n    systemAccessPolicy: {\n      // Subject-export disclosure. The subject's own subscriptions. 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      exportSubject: ResourceSystemAccessMode.ALLOWED,\n      list: ResourceSystemAccessMode.ALLOWED,\n    },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.\n *\n * `RETAIN_ONLY` is a positive ASSERTION that this resource holds no personal data of its own. The row is\n * subscription terms — plan and price references, status and period boundaries — amounts and contract terms about the ACCOUNT. They\n * describe nobody once the linked USER row is scrubbed, and they must survive erasure for the tax/audit\n * obligation this family exists to serve, so they can be neither scrubbed nor honestly declared as\n * personal data the row holds. The person is the scope foreign key, which the never-scrub floor protects.\n *\n * The assertion is CHECKED in both directions: the factory refuses `RETAIN_ONLY` if any field declares an\n * impersonalize treatment, and (since 2026-08-31) if any non-floor field declares `.dataCategories()`.\n     */\n    retentionPolicy: {\n      mode: ErasureRetentionMode.RETAIN_ONLY,\n    },\n\n    /**\n     * Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n *  record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n *  session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n     */\n    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n    customOperation: BillingSubscription_Operations,\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n      CoreResourceOperation.UPDATE_MANY,\n    ],\n    operationsConfiguration: {\n      /*\n       * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n       * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n       * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n       * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n       * verb the impersonalize writer uses to stamp the retention markers.\n       */\n      [CoreResourceOperation.UPDATE_MANY]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n        }],\n      },\n\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          // API_CALL: subscriptions are a user-facing collection (Settings Hub → Billing →\n          // Subscriptions, and the resource presets' LIST/READ views). REPOSITORY_ONLY would\n          // strip the op from the frontend registry and register no HTTP route. Writes\n          // (checkout + webhook sync) are INTERNAL_CALL (service-pipeline) / custom API_CALL ops.\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.MEDIUM,\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.MEDIUM,\n        }],\n      },\n      [BillingSubscription_Operations.CANCEL]: {\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.CRITICAL,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_CancelRequestDto,\n        }],\n      },\n      [BillingSubscription_Operations.RESUME]: {\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.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          // RESUME clears a pending cancellation at the provider and mirrors the result — it\n          // takes no caller input. Its implementation already ignores the payload, but the\n          // dispatcher MERGES a prefix's return onto the caller payload rather than replacing\n          // it, so an unnarrowed contract is still writable. Omitting `requestDto` would\n          // auto-derive the FULL subscription update DTO (`status`, `items`, `discount`,\n          // `currentPeriodEnd`, `cancelledAt`, …), letting a subscriber rewrite their own\n          // billing state through \"resume\".\n          requestDto: z.object({}),\n        }],\n      },\n      [BillingSubscription_Operations.CHANGE_PLAN]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_ChangePlanRequestDto,\n        }],\n      },\n      [BillingSubscription_Operations.ADD_ADDON]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_AddAddonRequestDto,\n        }],\n      },\n      [BillingSubscription_Operations.REMOVE_ADDON]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingSubscription_RemoveAddonRequestDto,\n        }],\n      },\n    },\n  },\n);\n"]}

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

@@ -16,7 +16,7 @@
  * @see billing-and-features-system.md §6.6 (Usage Records)
  */
 import { z } from 'zod';
-import { UsageSourceType } from './billing-enums.shared.schemas';
+import { UsageRecordFlushState, UsageRecordUnreportableReason, 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>>>;
@@ -29,8 +29,10 @@ export declare const UsageRecordSchema: z.ZodObject<{
         operationIdentifier: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-    reportedToProvider: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    flushState: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof UsageRecordFlushState>>>>>;
     reportedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
+    unreportableReason: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<typeof UsageRecordUnreportableReason>>>>;
+    unreportableAt: 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>;
@@ -47,8 +49,10 @@ export declare const usageRecordsPolymorphicDeclaration: import("..").Polymorphi
         operationIdentifier: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-    reportedToProvider: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    flushState: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof UsageRecordFlushState>>>>>;
     reportedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
+    unreportableReason: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<typeof UsageRecordUnreportableReason>>>>;
+    unreportableAt: 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>>;

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;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;iBAmD5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI5D,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;kBAQ7C,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;AAGxB,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEvH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;iBAsE5B,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

@@ -18,7 +18,7 @@
 import { z } from 'zod';
 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';
+import { UsageRecordFlushState, UsageRecordUnreportableReason, 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(),
@@ -42,9 +42,28 @@ export const UsageRecordSchema = z.object({
         operationIdentifier: z.string().optional(),
         description: z.string().optional(),
     }).optional().isNotEditable(),
-    /** Whether this has been reported to the billing provider */
-    reportedToProvider: z.boolean().default(false).isDBIndexed().isNotEditable(),
+    /**
+     * Where this row stands with respect to the provider flush.
+     *
+     * The flush selects exactly `PENDING`, so this ONE indexed field decides whether a row is still
+     * work. It replaced a `reportedToProvider` boolean on 2026-09-09 (#512): a boolean has no way to
+     * say "this can never be reported", so rows whose billing account had been deleted were
+     * re-selected by every run forever. See {@link UsageRecordFlushState} for why all three states are
+     * semantically distinct and why the shortcut of marking them reported was refused.
+     */
+    flushState: z.enum(UsageRecordFlushState).default(UsageRecordFlushState.PENDING).isDBIndexed().isNotEditable().systemEnum('UsageRecordFlushState'),
+    /** When the PROVIDER acknowledged the quantity. Set only alongside `flushState: reported`. */
     reportedAt: z.date().optional().isNotEditable(),
+    /**
+     * Why this row can never be reported. Set only alongside `flushState: unreportable`.
+     *
+     * Separate from `reportedAt` on purpose: that timestamp records an acknowledgement by the
+     * provider, this pair records a determination made locally, and merging them would put two
+     * different events under one name.
+     */
+    unreportableReason: z.enum(UsageRecordUnreportableReason).optional().isNotEditable().systemEnum('UsageRecordUnreportableReason'),
+    /** When the flush determined this row unreportable. Set only alongside `unreportableReason`. */
+    unreportableAt: z.date().optional().isNotEditable(),
     /**
      * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).
      *

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;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,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,mGAAmG;IACnG,oGAAoG;IACpG,qGAAqG;IACrG,sGAAsG;IACtG,0BAA0B;IAC1B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAE5E,qBAAqB;IACrB,+FAA+F;IAC/F,gGAAgG;IAChG,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;;;;;;;;;;;;;;;;;;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 { 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  // No `.dataCategories()`: this is an amount/term about the ACCOUNT, not a description of a person.\n  // The person is the scope foreign key, which the never-scrub floor preserves in every mode, and the\n  // value must survive erasure for the tax/audit obligation this family exists to serve — so it can be\n  // neither scrubbed nor honestly declared as personal data the row holds. See `retentionPolicy` on the\n  // resource config (#138).\n  productKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable(),\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(),\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"]}
+{"version":3,"file":"usage-record.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/usage-record.shared.schemas.ts"],"names":[],"mappings":"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","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 { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\nimport { UsageRecordFlushState, UsageRecordUnreportableReason, 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  // No `.dataCategories()`: this is an amount/term about the ACCOUNT, not a description of a person.\n  // The person is the scope foreign key, which the never-scrub floor preserves in every mode, and the\n  // value must survive erasure for the tax/audit obligation this family exists to serve — so it can be\n  // neither scrubbed nor honestly declared as personal data the row holds. See `retentionPolicy` on the\n  // resource config (#138).\n  productKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable(),\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(),\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  /**\n   * Where this row stands with respect to the provider flush.\n   *\n   * The flush selects exactly `PENDING`, so this ONE indexed field decides whether a row is still\n   * work. It replaced a `reportedToProvider` boolean on 2026-09-09 (#512): a boolean has no way to\n   * say \"this can never be reported\", so rows whose billing account had been deleted were\n   * re-selected by every run forever. See {@link UsageRecordFlushState} for why all three states are\n   * semantically distinct and why the shortcut of marking them reported was refused.\n   */\n  flushState: z.enum(UsageRecordFlushState).default(UsageRecordFlushState.PENDING).isDBIndexed().isNotEditable().systemEnum('UsageRecordFlushState'),\n  /** When the PROVIDER acknowledged the quantity. Set only alongside `flushState: reported`. */\n  reportedAt: z.date().optional().isNotEditable(),\n  /**\n   * Why this row can never be reported. Set only alongside `flushState: unreportable`.\n   *\n   * Separate from `reportedAt` on purpose: that timestamp records an acknowledgement by the\n   * provider, this pair records a determination made locally, and merging them would put two\n   * different events under one name.\n   */\n  unreportableReason: z.enum(UsageRecordUnreportableReason).optional().isNotEditable().systemEnum('UsageRecordUnreportableReason'),\n  /** When the flush determined this row unreportable. Set only alongside `unreportableReason`. */\n  unreportableAt: 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/companion/provider-discovery.shared.schemas.d.ts

@@ -70,8 +70,38 @@ export declare const ProviderSecretContractShapeSchema: z.ZodArray<z.ZodObject<{
     description: z.ZodString;
 }, z.core.$strict>>;
 export type ProviderSecretContractShape = z.infer<typeof ProviderSecretContractShapeSchema>;
+/**
+ * A contribution is a wire record produced by one package version and read by
+ * another (the CLI, the companion, a generated artifact), so it is a LOOSE
+ * object: an additive field from a newer producer rides through an older
+ * consumer instead of hard-failing the parse (#328 — it used to be strict,
+ * which made every additive field a five-surface change and every old/new
+ * mix a boot failure). Required fields stay required; only UNKNOWN keys are
+ * tolerated, and they are kept rather than stripped so a re-emitting
+ * consumer does not silently drop what it did not understand.
+ */
 export declare const ProviderCompanionContributionSchema: z.ZodObject<{
     ref: z.ZodString;
+    /**
+     * The provider's identity (package, tier, vendor, origin) as declared on
+     * its module metadata, so tooling can display tiers and group vendors
+     * without loading the runtime module. Optional on the wire for one
+     * reason only: contributions emitted before #328 carry none, and a
+     * discovery walk must still read them.
+     */
+    identity: z.ZodOptional<z.ZodObject<{
+        origin: z.ZodObject<{
+            kind: z.ZodEnum<typeof import("..").ProviderOriginKind>;
+            catalogue: z.ZodOptional<z.ZodObject<{
+                source: z.ZodEnum<typeof import("..").ProviderCatalogueSource>;
+                sourceRef: z.ZodString;
+                sourceVersion: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        packageName: z.ZodString;
+        tier: z.ZodEnum<typeof import("..").ProviderTier>;
+        vendor: z.ZodString;
+    }, z.core.$strip>>;
     /**
      * Stable package import path that makes the provider implementation reachable
      * from the contributing package at runtime. This validates owner-package
@@ -110,6 +140,17 @@ export declare const ProviderCompanionContributionSchema: z.ZodObject<{
     frontendEntry: z.ZodOptional<z.ZodObject<{
         metadata: z.ZodObject<{
             ref: z.ZodString;
+            packageName: z.ZodString;
+            tier: z.ZodEnum<typeof import("..").ProviderTier>;
+            vendor: z.ZodString;
+            origin: z.ZodObject<{
+                kind: z.ZodEnum<typeof import("..").ProviderOriginKind>;
+                catalogue: z.ZodOptional<z.ZodObject<{
+                    source: z.ZodEnum<typeof import("..").ProviderCatalogueSource>;
+                    sourceRef: z.ZodString;
+                    sourceVersion: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
             displayNameLabelKey: z.ZodOptional<z.ZodString>;
             displayName: z.ZodOptional<z.ZodString>;
             iconRef: z.ZodOptional<z.ZodString>;
@@ -117,13 +158,39 @@ export declare const ProviderCompanionContributionSchema: z.ZodObject<{
         providerCapabilities: z.ZodArray<z.ZodString>;
         protocols: z.ZodArray<z.ZodString>;
         publicConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>;
+        csp: z.ZodOptional<z.ZodObject<{
+            scriptOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            connectOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            frameOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            imgOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            styleOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            fontOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            derivedOrigins: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                publicConfigKey: z.ZodString;
+                bucket: z.ZodEnum<typeof import("..").ProviderFrontendCspOriginBucket>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        sdk: z.ZodOptional<z.ZodObject<{
+            packageName: z.ZodString;
+            versionRange: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        scripts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            src: z.ZodString;
+            integrity: z.ZodOptional<z.ZodString>;
+            crossOrigin: z.ZodOptional<z.ZodEnum<typeof import("..").ProviderFrontendScriptCrossOrigin>>;
+            async: z.ZodOptional<z.ZodBoolean>;
+            defer: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>>;
+        components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            selectionDelivery: z.ZodOptional<z.ZodEnum<typeof import("..").ProviderFrontendSelectionDelivery>>;
+        }, z.core.$strict>>>;
+    }, z.core.$loose>>;
     /**
      * Optional app module owner when the provider implementation belongs to one
      * concrete module instead of the whole package/runtime.
      */
     sourceModuleId: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
+}, z.core.$loose>;
 export type ProviderCompanionContribution = z.infer<typeof ProviderCompanionContributionSchema>;
 export interface RuntimeOwnerCompanionExports {
     providerContributions?: ProviderCompanionContribution[];

package/dist/esm/companion/provider-discovery.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-discovery.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/companion/provider-discovery.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0DAA0D,CAAC;AAG5F;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0CAA0C;;;kBAGrD,CAAC;AACH,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC;AAE9G,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;4BAgB/C,CAAC;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,sCAAsC;;;;;kBAKjD,CAAC;AACH,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AAEtG;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC;;;;;mBA+B5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F,eAAO,MAAM,mCAAmC;;IAE9C;;;;OAIG;;;;;;;;;;;;;;;;;;;;;;;;;IAOH;;;;;OAKG;;;;;;;;;;;;IAEH;;;OAGG;;kBAEH,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG,MAAM,WAAW,4BAA4B;IAC3C,qBAAqB,CAAC,EAAE,6BAA6B,EAAE,CAAC;CACzD"}
+{"version":3,"file":"provider-discovery.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/companion/provider-discovery.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0DAA0D,CAAC;AAI5F;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0CAA0C;;;kBAGrD,CAAC;AACH,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0CAA0C,CAAC,CAAC;AAE9G,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;4BAgB/C,CAAC;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,sCAAsC;;;;;kBAKjD,CAAC;AACH,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sCAAsC,CAAC,CAAC;AAEtG;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC;;;;;mBA+B5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;;;;;;;;GASG;AACH,eAAO,MAAM,mCAAmC;;IAE9C;;;;;;OAMG;;;;;;;;;;;;;;IAEH;;;;OAIG;;;;;;;;;;;;;;;;;;;;;;;;;IAOH;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEH;;;OAGG;;iBAEH,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG,MAAM,WAAW,4BAA4B;IAC3C,qBAAqB,CAAC,EAAE,6BAA6B,EAAE,CAAC;CACzD"}

package/dist/esm/companion/provider-discovery.shared.schemas.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { AppFrontendType } from '../config/app-frontend-type.shared.schemas.js';
 import { EngineCapability } from '../external-providers/engine-capabilities.shared.schemas.js';
 import { FrontendProviderEntrySchema } from '../external-providers/frontend-bootstrap.shared.schemas.js';
+import { ProviderIdentitySchema } from '../external-providers/provider-metadata.shared.schemas.js';
 /**
  * Companion-safe provider implementation declaration.
  *
@@ -93,8 +94,26 @@ export const ProviderSecretContractShapeSchema = z.array(ProviderSecretContractS
         }
     }
 });
-export const ProviderCompanionContributionSchema = z.strictObject({
+/**
+ * A contribution is a wire record produced by one package version and read by
+ * another (the CLI, the companion, a generated artifact), so it is a LOOSE
+ * object: an additive field from a newer producer rides through an older
+ * consumer instead of hard-failing the parse (#328 — it used to be strict,
+ * which made every additive field a five-surface change and every old/new
+ * mix a boot failure). Required fields stay required; only UNKNOWN keys are
+ * tolerated, and they are kept rather than stripped so a re-emitting
+ * consumer does not silently drop what it did not understand.
+ */
+export const ProviderCompanionContributionSchema = z.looseObject({
     ref: z.string().min(1),
+    /**
+     * The provider's identity (package, tier, vendor, origin) as declared on
+     * its module metadata, so tooling can display tiers and group vendors
+     * without loading the runtime module. Optional on the wire for one
+     * reason only: contributions emitted before #328 carry none, and a
+     * discovery walk must still read them.
+     */
+    identity: ProviderIdentitySchema.optional(),
     /**
      * Stable package import path that makes the provider implementation reachable
      * from the contributing package at runtime. This validates owner-package

package/dist/esm/companion/provider-discovery.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-discovery.shared.schemas.js","sourceRoot":"","sources":["../../../../src/companion/provider-discovery.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { AppFrontendType } from '../config/app-frontend-type.shared.schemas';\nimport { EngineCapability } from '../external-providers/engine-capabilities.shared.schemas';\nimport { FrontendProviderEntrySchema } from '../external-providers/frontend-bootstrap.shared.schemas';\n\n/**\n * Companion-safe provider implementation declaration.\n *\n * App/runtime-owner packages expose these entries through their `./companion`\n * default export so tooling can discover which provider refs are actually\n * reachable from which runtime owners before materializing generated artifacts.\n */\n\n/**\n * Discriminator branch for `frontendService` runtime targets.\n *\n * Targets a frontend service by its `AppFrontendType` (the closed kind set\n * — SAAS_APP, STATIC_WEBSITE, TECH_DOC) rather than by an app-defined\n * `serviceKey` string. Engine-shipped packages (`external-connectors-public`,\n * etc.) have no way to know app-defined service keys, so the discovery\n * contract is keyed on the type. Apps with multiple frontend services of\n * the same type currently broadcast the contribution to all of them; if\n * per-service-key targeting becomes a need, add a second variant.\n */\nexport const ProviderFrontendServiceRuntimeTargetSchema = z.strictObject({\n  kind: z.literal('frontendService'),\n  serviceType: z.enum(AppFrontendType),\n});\nexport type ProviderFrontendServiceRuntimeTarget = z.infer<typeof ProviderFrontendServiceRuntimeTargetSchema>;\n\nexport const ProviderCompanionRuntimeTargetSchema = z.discriminatedUnion('kind', [\n  z.strictObject({\n    kind: z.literal('backend'),\n  }),\n  z.strictObject({\n    kind: z.literal('companion'),\n  }),\n  ProviderFrontendServiceRuntimeTargetSchema,\n  z.strictObject({\n    kind: z.literal('minion'),\n    minionKey: z.string().min(1),\n  }),\n  z.strictObject({\n    kind: z.literal('worker'),\n    workerKey: z.string().min(1),\n  }),\n]);\nexport type ProviderCompanionRuntimeTarget = z.infer<typeof ProviderCompanionRuntimeTargetSchema>;\n\n/**\n * Values-free projection of one backend provider secret requirement.\n *\n * The stable provider-owned `slug` is preserved separately from the concrete\n * environment-variable name so a rename on either axis changes the lockfile\n * integrity digest. Secret values never cross this companion-safe boundary.\n */\nexport const ProviderSecretContractShapeEntrySchema = z.strictObject({\n  slug: z.string().min(1),\n  envVarName: z.string().min(1),\n  required: z.boolean(),\n  description: z.string().min(1),\n});\nexport type ProviderSecretContractShapeEntry = z.infer<typeof ProviderSecretContractShapeEntrySchema>;\n\n/**\n * Deterministic, values-free secret-contract shape used by provider discovery\n * and lockfile integrity checks.\n *\n * Every contribution must declare this field. `[]` means the provider is\n * authoritatively known to require no secrets; omission is rejected rather\n * than being silently interpreted as an empty contract. Entries must be\n * sorted by `slug`, and both slugs and environment-variable names are unique,\n * so independently contributed facets cannot produce order-dependent digests.\n */\nexport const ProviderSecretContractShapeSchema = z.array(ProviderSecretContractShapeEntrySchema).superRefine((entries, context) => {\n  const seenSlugs = new Set<string>();\n  const seenEnvVarNames = new Set<string>();\n\n  for (const [index, entry] of entries.entries()) {\n    if (seenSlugs.has(entry.slug)) {\n      context.addIssue({\n        code: 'custom',\n        path: [index, 'slug'],\n        message: `Duplicate provider secret-contract slug \"${entry.slug}\".`,\n      });\n    }\n    seenSlugs.add(entry.slug);\n\n    if (seenEnvVarNames.has(entry.envVarName)) {\n      context.addIssue({\n        code: 'custom',\n        path: [index, 'envVarName'],\n        message: `Duplicate provider secret-contract envVarName \"${entry.envVarName}\".`,\n      });\n    }\n    seenEnvVarNames.add(entry.envVarName);\n\n    if (index > 0 && entries[index - 1].slug.localeCompare(entry.slug) >= 0) {\n      context.addIssue({\n        code: 'custom',\n        path: [index, 'slug'],\n        message: 'Provider secret-contract entries must be sorted by slug.',\n      });\n    }\n  }\n});\nexport type ProviderSecretContractShape = z.infer<typeof ProviderSecretContractShapeSchema>;\n\nexport const ProviderCompanionContributionSchema = z.strictObject({\n  ref: z.string().min(1),\n  /**\n   * Stable package import path that makes the provider implementation reachable\n   * from the contributing package at runtime. This validates owner-package\n   * reachability without coupling discovery to source-file paths.\n   */\n  runtimeImportPath: z.string().min(1),\n  runtimeTargets: z.array(ProviderCompanionRuntimeTargetSchema).min(1),\n  engineCapabilities: z.array(z.enum(EngineCapability)).default([]),\n  providerCapabilities: z.array(z.string().min(1)).default([]),\n  protocols: z.array(z.string().min(1)).default([]),\n  secretsContractShape: ProviderSecretContractShapeSchema,\n  /**\n   * Optional frontend-safe provider payload for `frontendService` runtime\n   * targets. Tooling materializes this into generated runtime artifacts so the\n   * backend bootstrap endpoint can serve app-owned public providers without\n   * importing frontend packages at runtime.\n   */\n  frontendEntry: FrontendProviderEntrySchema.optional(),\n  /**\n   * Optional app module owner when the provider implementation belongs to one\n   * concrete module instead of the whole package/runtime.\n   */\n  sourceModuleId: z.string().min(1).optional(),\n});\nexport type ProviderCompanionContribution = z.infer<typeof ProviderCompanionContributionSchema>;\n\nexport interface RuntimeOwnerCompanionExports {\n  providerContributions?: ProviderCompanionContribution[];\n}\n"]}
+{"version":3,"file":"provider-discovery.shared.schemas.js","sourceRoot":"","sources":["../../../../src/companion/provider-discovery.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { AppFrontendType } from '../config/app-frontend-type.shared.schemas';\nimport { EngineCapability } from '../external-providers/engine-capabilities.shared.schemas';\nimport { FrontendProviderEntrySchema } from '../external-providers/frontend-bootstrap.shared.schemas';\nimport { ProviderIdentitySchema } from '../external-providers/provider-metadata.shared.schemas';\n\n/**\n * Companion-safe provider implementation declaration.\n *\n * App/runtime-owner packages expose these entries through their `./companion`\n * default export so tooling can discover which provider refs are actually\n * reachable from which runtime owners before materializing generated artifacts.\n */\n\n/**\n * Discriminator branch for `frontendService` runtime targets.\n *\n * Targets a frontend service by its `AppFrontendType` (the closed kind set\n * — SAAS_APP, STATIC_WEBSITE, TECH_DOC) rather than by an app-defined\n * `serviceKey` string. Engine-shipped packages (`external-connectors-public`,\n * etc.) have no way to know app-defined service keys, so the discovery\n * contract is keyed on the type. Apps with multiple frontend services of\n * the same type currently broadcast the contribution to all of them; if\n * per-service-key targeting becomes a need, add a second variant.\n */\nexport const ProviderFrontendServiceRuntimeTargetSchema = z.strictObject({\n  kind: z.literal('frontendService'),\n  serviceType: z.enum(AppFrontendType),\n});\nexport type ProviderFrontendServiceRuntimeTarget = z.infer<typeof ProviderFrontendServiceRuntimeTargetSchema>;\n\nexport const ProviderCompanionRuntimeTargetSchema = z.discriminatedUnion('kind', [\n  z.strictObject({\n    kind: z.literal('backend'),\n  }),\n  z.strictObject({\n    kind: z.literal('companion'),\n  }),\n  ProviderFrontendServiceRuntimeTargetSchema,\n  z.strictObject({\n    kind: z.literal('minion'),\n    minionKey: z.string().min(1),\n  }),\n  z.strictObject({\n    kind: z.literal('worker'),\n    workerKey: z.string().min(1),\n  }),\n]);\nexport type ProviderCompanionRuntimeTarget = z.infer<typeof ProviderCompanionRuntimeTargetSchema>;\n\n/**\n * Values-free projection of one backend provider secret requirement.\n *\n * The stable provider-owned `slug` is preserved separately from the concrete\n * environment-variable name so a rename on either axis changes the lockfile\n * integrity digest. Secret values never cross this companion-safe boundary.\n */\nexport const ProviderSecretContractShapeEntrySchema = z.strictObject({\n  slug: z.string().min(1),\n  envVarName: z.string().min(1),\n  required: z.boolean(),\n  description: z.string().min(1),\n});\nexport type ProviderSecretContractShapeEntry = z.infer<typeof ProviderSecretContractShapeEntrySchema>;\n\n/**\n * Deterministic, values-free secret-contract shape used by provider discovery\n * and lockfile integrity checks.\n *\n * Every contribution must declare this field. `[]` means the provider is\n * authoritatively known to require no secrets; omission is rejected rather\n * than being silently interpreted as an empty contract. Entries must be\n * sorted by `slug`, and both slugs and environment-variable names are unique,\n * so independently contributed facets cannot produce order-dependent digests.\n */\nexport const ProviderSecretContractShapeSchema = z.array(ProviderSecretContractShapeEntrySchema).superRefine((entries, context) => {\n  const seenSlugs = new Set<string>();\n  const seenEnvVarNames = new Set<string>();\n\n  for (const [index, entry] of entries.entries()) {\n    if (seenSlugs.has(entry.slug)) {\n      context.addIssue({\n        code: 'custom',\n        path: [index, 'slug'],\n        message: `Duplicate provider secret-contract slug \"${entry.slug}\".`,\n      });\n    }\n    seenSlugs.add(entry.slug);\n\n    if (seenEnvVarNames.has(entry.envVarName)) {\n      context.addIssue({\n        code: 'custom',\n        path: [index, 'envVarName'],\n        message: `Duplicate provider secret-contract envVarName \"${entry.envVarName}\".`,\n      });\n    }\n    seenEnvVarNames.add(entry.envVarName);\n\n    if (index > 0 && entries[index - 1].slug.localeCompare(entry.slug) >= 0) {\n      context.addIssue({\n        code: 'custom',\n        path: [index, 'slug'],\n        message: 'Provider secret-contract entries must be sorted by slug.',\n      });\n    }\n  }\n});\nexport type ProviderSecretContractShape = z.infer<typeof ProviderSecretContractShapeSchema>;\n\n/**\n * A contribution is a wire record produced by one package version and read by\n * another (the CLI, the companion, a generated artifact), so it is a LOOSE\n * object: an additive field from a newer producer rides through an older\n * consumer instead of hard-failing the parse (#328 — it used to be strict,\n * which made every additive field a five-surface change and every old/new\n * mix a boot failure). Required fields stay required; only UNKNOWN keys are\n * tolerated, and they are kept rather than stripped so a re-emitting\n * consumer does not silently drop what it did not understand.\n */\nexport const ProviderCompanionContributionSchema = z.looseObject({\n  ref: z.string().min(1),\n  /**\n   * The provider's identity (package, tier, vendor, origin) as declared on\n   * its module metadata, so tooling can display tiers and group vendors\n   * without loading the runtime module. Optional on the wire for one\n   * reason only: contributions emitted before #328 carry none, and a\n   * discovery walk must still read them.\n   */\n  identity: ProviderIdentitySchema.optional(),\n  /**\n   * Stable package import path that makes the provider implementation reachable\n   * from the contributing package at runtime. This validates owner-package\n   * reachability without coupling discovery to source-file paths.\n   */\n  runtimeImportPath: z.string().min(1),\n  runtimeTargets: z.array(ProviderCompanionRuntimeTargetSchema).min(1),\n  engineCapabilities: z.array(z.enum(EngineCapability)).default([]),\n  providerCapabilities: z.array(z.string().min(1)).default([]),\n  protocols: z.array(z.string().min(1)).default([]),\n  secretsContractShape: ProviderSecretContractShapeSchema,\n  /**\n   * Optional frontend-safe provider payload for `frontendService` runtime\n   * targets. Tooling materializes this into generated runtime artifacts so the\n   * backend bootstrap endpoint can serve app-owned public providers without\n   * importing frontend packages at runtime.\n   */\n  frontendEntry: FrontendProviderEntrySchema.optional(),\n  /**\n   * Optional app module owner when the provider implementation belongs to one\n   * concrete module instead of the whole package/runtime.\n   */\n  sourceModuleId: z.string().min(1).optional(),\n});\nexport type ProviderCompanionContribution = z.infer<typeof ProviderCompanionContributionSchema>;\n\nexport interface RuntimeOwnerCompanionExports {\n  providerContributions?: ProviderCompanionContribution[];\n}\n"]}

package/dist/esm/compliance/audit-trails/application-audit-logs.shared.resources-config.schemas.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { AuditEventCategory, AuditEventSeverity } from './auditable-events.shared.schema';
+import { CoreResourceOperation } from '../../resources/resources.shared.core.definitions';
+import { ResourceOperationRiskLevel, ResourceRelationship } from '../../resources/resources.shared.schemas';
+/**
+ * The APPLICATION-scoped door onto the audit trail.
+ *
+ * ## Why this exists at all
+ *
+ * `AUDIT_LOGS` is organization-scoped and its only route is
+ * `/organizations/{organizationId}/audit-logs`, so it returns exactly the rows carrying that
+ * tenant. A large share of security events carry NO organization by design — `logUserLogin` takes
+ * `organizationId` as optional because no organization is selected at login, and the same is true
+ * of session eviction, token refresh and application-wide authentication-policy changes. Measured
+ * on a dogfood application (#317): **94 of 127 rows had no organization**, and were reachable
+ * through no API. An operator could see 26% of the trail and could not attest the rest, while a
+ * reader querying the only available surface saw `user_login: 0` for a control that had emitted 21.
+ *
+ * ## Why a SEPARATE resource type rather than a second route
+ *
+ * `generateParentCombinations` composes every URL as
+ * `[...primaryScope, ...mandatoryContext, ...optionalCombo]`, so a routed application edge on
+ * `AUDIT_LOGS` would appear in EVERY combination and rewrite the organization route to
+ * `/applications/{applicationId}/organizations/{organizationId}/audit-logs` — breaking all eight of
+ * its documented paths and their consumers. Making the organization edge optional does not help:
+ * the empty combination is skipped whenever any parent exists, so no bare route is emitted either.
+ * A sibling type carrying ONE application parent takes the route it needs and leaves the existing
+ * door byte-identical. The pattern is the engine's own: notification badges are dual-scope with a
+ * type per scope, `APPLICATION_API_KEYS` shows the application routing shape, and `USER_SELF`
+ * shows a distinct type addressing another's rows.
+ *
+ * ## Two doors, ONE record set — the security contract
+ *
+ * Both types resolve to the `auditLogs` collection through
+ * `RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES`. That makes the isolation properties a
+ * per-DOOR obligation rather than a property of the rows:
+ *
+ * - the organization door keeps its tenant filter and its organization roles, unchanged;
+ * - this door is `APP_ADMIN_SUPER_ADMIN`-ONLY on every operation. An organization role must never
+ *   reach it — the rows behind it span every tenant;
+ * - a read here that touches a tenant-attributed row is a CROSS-TENANT read and OWES an audit
+ *   emission. **It is wired**, by the two halves below acting together, and neither is optional:
+ *   each read variant declares `admitsCrossTenantPlatformAdministration`, and
+ *   `ServicesRegistryHandler.recordCrossTenantReadAccess` observes every enrolled read and emits
+ *   `CROSS_TENANT_ADMINISTRATIVE_ACCESS` once per TENANT the returned rows belong to. The
+ *   declaration is what enrols the read: `authorizeOrganizations` — where that event is otherwise
+ *   emitted — runs only for ORGANIZATIONS-scoped resources and decides on ONE fetched row, so it
+ *   never sees this door at all. Grouping per tenant is what makes the crossing visible to the
+ *   REACHED tenant, in its own organization-scoped viewer, rather than only to the operator.
+ *   `.claude/rules/administrative-continuity-floors.md` requires every crossing to be named in the
+ *   trail, and the trail is the worst possible surface on which to make an operator read invisible.
+ *   See `security/authorizations/cross-tenant-read-observation.backend.ts` for why an UNDECLARED
+ *   door is deliberately not observed instead of being observed with a false `admissionDeclared`.
+ *
+ * ## Deliberately mirrored from the organization resource
+ *
+ * `isSystemResource`, `systemAccessPolicy.exportSubject: FORBIDDEN` and the ABSENCE of a
+ * `retentionPolicy` are copied ON PURPOSE. They are properties of the ROWS, and the rows are the
+ * same ones — a second door that disagreed about whether the audit trail is subject-exportable, or
+ * about how long it is kept, would be a policy fork over one record set. See the organization
+ * config for the reasoning behind each; do not change one without the other.
+ *
+ * ## Deliberately NOT mirrored
+ *
+ * There is no CREATE. The organization resource carries a `REPOSITORY_ONLY` CREATE because that is
+ * how audit rows are written; writing is not a scope question and must keep exactly one door.
+ */
+export declare const applicationAuditLogsResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("../..").ResourceConfiguration<undefined, CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.SEARCH, z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    eventId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    userId: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    organizationId: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    applicationId: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    correlationId: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    frontendServiceName: z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    clientInstanceId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
+    riskLevel: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof ResourceOperationRiskLevel>>;
+    eventType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    eventData: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    eventCategory: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof AuditEventCategory>>;
+    severity: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof AuditEventSeverity>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
+    updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=application-audit-logs.shared.resources-config.schemas.d.ts.map

package/dist/esm/compliance/audit-trails/application-audit-logs.shared.resources-config.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-audit-logs.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/audit-trails/application-audit-logs.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAA6B,MAAM,kCAAkC,CAAC;AAErH,OAAO,EAAE,qBAAqB,EAAwD,MAAM,mDAAmD,CAAC;AAChJ,OAAO,EAAE,0BAA0B,EAAgC,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAI1I;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,eAAO,MAAM,+DAA+D,GAC1E,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;kBA8F9C,CAAC"}