@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/features/application-features.shared.resources-config.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-features.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/features/application-features.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Application Features Shared Resource Configuration\n *\n * Application-scope entitlement ledger. This mirrors organization/user feature\n * ledgers so exact-scope gates such as `M2M_WEBHOOK_DELIVERY` can be enabled\n * for `WEBHOOK_APPLICATION` without leaking app enablement to every org.\n */\n\nimport { z } from 'zod';\nimport { CoreFeature } from '../organizations/organization-features.shared.schemas';\nimport { ScopeFeaturesWithOverridesSchema } from './scope-features.shared.schemas';\n\nimport { CoreResourceOperation } from '../resources/resources.shared.core.definitions';\nimport { ResourceOperationRiskLevel, ResourceRelationship } from '../resources/resources.shared.schemas';\nimport { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport { ResourceOperationVariantType } from '../resources/resources.shared.schemas';\nimport { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory';\nimport { CORE_APP_ROLES } from '../security/authorizations/roles.shared.schemas';\n\nexport enum ApplicationFeatures_Operations {\n  ENABLE_FEATURE = 'enable_feature',\n  DISABLE_FEATURE = 'disable_feature',\n  RESET_FEATURES = 'reset_features',\n}\n\nexport const ApplicationFeaturesEnableFeatureRequestDtoSchema = z.object({\n  featureId: z.enum(CoreFeature),\n  reason: z.string().max(500).optional(),\n});\n\nexport const ApplicationFeaturesDisableFeatureRequestDtoSchema = z.object({\n  featureId: z.enum(CoreFeature),\n  reason: z.string().min(1).max(500),\n});\n\nexport const ApplicationFeaturesResetFeaturesRequestDtoSchema = z.object({\n  reason: z.string().min(1).max(500),\n});\n\ntype ApplicationFeaturesCoreOperations =\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.UPDATE\n  | CoreResourceOperation.DELETE;\n\nexport const applicationFeaturesResourceConfiguration_InitializationFactory = (resourcesRelationships: ResourceRelationship[]) => createResourceConfiguration_Initialization<\n  typeof ApplicationFeatures_Operations,\n  ApplicationFeaturesCoreOperations,\n  typeof ScopeFeaturesWithOverridesSchema\n>({\n  mainSchema: ScopeFeaturesWithOverridesSchema,\n  resourceIdentifier: CoreResourceType.APPLICATION_FEATURES,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION_FEATURES],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n\n  coreOperations: [\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.READ,\n    CoreResourceOperation.SEARCH,\n    CoreResourceOperation.UPDATE,\n    // DELETE is REPOSITORY_ONLY (no HTTP route): powers the composition onParentDelete\n    // cascade so the row is physically removed when its application is deleted. Without\n    // it the cascade throws ErrorType.CONFIGURATION on any app that has a features row.\n    CoreResourceOperation.DELETE,\n  ],\n\n  customOperation: ApplicationFeatures_Operations,\n\n  operationsConfiguration: {\n    [CoreResourceOperation.CREATE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        },\n      ],\n    },\n\n    [CoreResourceOperation.READ]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        isSearchable: false,\n        searchableFields: [],\n        searchableOptions: { caseSensitive: false, fullMatchOnly: false },\n        filterFields: {},\n        sortFields: [],\n        maxPaginatedResultPerPageLimit: 50,\n      }],\n    },\n\n    [CoreResourceOperation.UPDATE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.HIGH,\n          requestDto: ScopeFeaturesWithOverridesSchema.partial(),\n        },\n      ],\n    },\n\n    // Internal-only (REPOSITORY_ONLY): powers the composition onParentDelete cascade,\n    // not a public API surface — the ledger is reset, never DELETEd, over HTTP.\n    [CoreResourceOperation.DELETE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.HIGH,\n        },\n      ],\n    },\n\n    [ApplicationFeatures_Operations.ENABLE_FEATURE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE_MANY,\n          requestDto: ApplicationFeaturesEnableFeatureRequestDtoSchema,\n        },\n      ],\n    },\n\n    [ApplicationFeatures_Operations.DISABLE_FEATURE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE_MANY,\n          requestDto: ApplicationFeaturesDisableFeatureRequestDtoSchema,\n        },\n      ],\n    },\n\n    [ApplicationFeatures_Operations.RESET_FEATURES]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n          resourceOperationLike: CoreResourceOperation.UPDATE_MANY,\n          requestDto: ApplicationFeaturesResetFeaturesRequestDtoSchema,\n        },\n      ],\n    },\n  },\n});\n"]}

package/dist/esm/features/core-feature-definitions.shared.d.ts

@@ -7,10 +7,25 @@
  * Note: PRIORITY_SUPPORT, CUSTOM_INTEGRATIONS, ADVANCED_PERMISSIONS from the old CoreOrganizationFeature
  * enum were dropped:
  * - PRIORITY_SUPPORT → modeled as a custom app feature (not engine-level)
- * - CUSTOM_INTEGRATIONS → covered by EngineCapability bindings (external connectors)
+ * - CUSTOM_INTEGRATIONS → modeled by provider declarations, not entitlement features
  * - ADVANCED_PERMISSIONS → handled by RBAC system, not feature gating
  */
-import type { FeatureDefinition } from './feature-definition.shared.schemas.js';
+import type { FeatureDefinition } from './feature-definition.shared.schemas';
+/**
+ * LIMIT-feature identifier for the inbound Agent2Agent (A2A) LLM **token budget**: how many LLM
+ * tokens a tenant's A2A agent turns may consume per billing period. Grant it from a billing plan
+ * (a `LimitGrant` on the product) and the A2A transport enforces it fail-closed, denying further
+ * turns with HTTP 402 once exhausted.
+ *
+ * The single named source for this identifier — the backend budget service resolves the allowance
+ * by this exact key, so definition and enforcement cannot drift.
+ *
+ * Measured in TOKENS, not currency: the framework's canonical provider-usage pricing registry is
+ * deliberately not consulted by this A2A entitlement gate. The gate caps the transport's directly
+ * metered token consumption; monetary reservation and settlement belong to the separate Work Cycle
+ * budget authority.
+ */
+export declare const A2A_TOKEN_BUDGET_FEATURE_ID = "a2a.llm.tokensPerPeriod";
 /**
  * Core feature definitions: every CoreFeature value + core LIMIT features.
  * Merged with custom app feature definitions at startup.

package/dist/esm/features/core-feature-definitions.shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-feature-definitions.shared.d.ts","sourceRoot":"","sources":["../../../src/features/core-feature-definitions.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAiB,EA+CvD,CAAC"}
+{"version":3,"file":"core-feature-definitions.shared.d.ts","sourceRoot":"","sources":["../../../../src/features/core-feature-definitions.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAiB,EAwHvD,CAAC"}

package/dist/esm/features/core-feature-definitions.shared.js

@@ -7,13 +7,28 @@
  * Note: PRIORITY_SUPPORT, CUSTOM_INTEGRATIONS, ADVANCED_PERMISSIONS from the old CoreOrganizationFeature
  * enum were dropped:
  * - PRIORITY_SUPPORT → modeled as a custom app feature (not engine-level)
- * - CUSTOM_INTEGRATIONS → covered by EngineCapability bindings (external connectors)
+ * - CUSTOM_INTEGRATIONS → modeled by provider declarations, not entitlement features
  * - ADVANCED_PERMISSIONS → handled by RBAC system, not feature gating
  */
 import { CoreFeature } from '../organizations/organization-features.shared.schemas.js';
 import { CoreResourceType } from '../resources/resources.shared.core.definitions.js';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
-import { FeatureValueType } from './feature-definition.shared.schemas.js';
+import { FEATURES_UNLIMITED, FeatureLimitSemantic, FeatureValueType } from './feature-definition.shared.schemas.js';
+/**
+ * LIMIT-feature identifier for the inbound Agent2Agent (A2A) LLM **token budget**: how many LLM
+ * tokens a tenant's A2A agent turns may consume per billing period. Grant it from a billing plan
+ * (a `LimitGrant` on the product) and the A2A transport enforces it fail-closed, denying further
+ * turns with HTTP 402 once exhausted.
+ *
+ * The single named source for this identifier — the backend budget service resolves the allowance
+ * by this exact key, so definition and enforcement cannot drift.
+ *
+ * Measured in TOKENS, not currency: the framework's canonical provider-usage pricing registry is
+ * deliberately not consulted by this A2A entitlement gate. The gate caps the transport's directly
+ * metered token consumption; monetary reservation and settlement belong to the separate Work Cycle
+ * budget authority.
+ */
+export const A2A_TOKEN_BUDGET_FEATURE_ID = 'a2a.llm.tokensPerPeriod';
 /**
  * Core feature definitions: every CoreFeature value + core LIMIT features.
  * Merged with custom app feature definitions at startup.
@@ -48,6 +63,42 @@ export const CORE_FEATURE_DEFINITIONS = [
         dependencies: [],
         defaultValue: false,
     },
+    {
+        // Outbound delivery of audit-trail events to a tenant-owned SIEM /
+        // compliance store. Depends on `AUDIT_LOGS` for the read-side surface,
+        // but the gate is independent so admins can enable read-only auditing
+        // without paying for outbound delivery.
+        identifier: CoreFeature.SECURITY_EVENT_EXPORT,
+        valueType: FeatureValueType.BOOLEAN,
+        applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],
+        dependencies: [],
+        defaultValue: false,
+    },
+    {
+        // SCIM-driven user/group provisioning. Typically procured alongside
+        // `SINGLE_SIGN_ON` but each feature is an independent gate so an org
+        // can run SSO without provisioning (or vice versa).
+        identifier: CoreFeature.DIRECTORY_PROVISIONING,
+        valueType: FeatureValueType.BOOLEAN,
+        applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],
+        dependencies: [],
+        defaultValue: false,
+    },
+    {
+        // M2M_WEBHOOK_DELIVERY is scope-bound: enabling it at the app level
+        // does NOT auto-enable it for every organization. Each scope (app or
+        // organization) opts in independently. See `FeatureDefinitionSchema.scopeBoundary`
+        // and `FeatureResolutionBackendService.isFeatureEnabledAtScope`.
+        identifier: CoreFeature.M2M_WEBHOOK_DELIVERY,
+        valueType: FeatureValueType.BOOLEAN,
+        applicableScopes: [
+            ResourcePrimaryScope.APPLICATION,
+            ResourcePrimaryScope.ORGANIZATIONS,
+        ],
+        dependencies: [],
+        defaultValue: false,
+        scopeBoundary: true,
+    },
     // ─── LIMIT features with counting configs (auto-checked by gate) ───
     {
         identifier: 'MAX_MEMBERS',
@@ -65,5 +116,42 @@ export const CORE_FEATURE_DEFINITIONS = [
         defaultValue: 2,
         counting: { resourceType: CoreResourceType.ORG_API_KEYS },
     },
+    {
+        // Inbound A2A LLM token budget — see {@link A2A_TOKEN_BUDGET_FEATURE_ID}.
+        //
+        // Applies to all THREE A2A owner scopes: a user-delegated turn is owned by the delegating
+        // user, a machine turn by its organization or application.
+        //
+        // NO `counting` config, deliberately: consumption here is a SUM OF TOKENS, not a count of
+        // resource rows, so the gate's row-counting strategy cannot measure it. The A2A budget service
+        // owns measurement (accumulating into the `a2aTokenBudgetState` singleton) and resolves this
+        // limit directly — which is exactly the "limit checking done in custom service code" case the
+        // `counting` field documents as its absent-branch.
+        //
+        // ⚠️ `limitSemantic: CEILING` is LOAD-BEARING — without it this feature is inert. Under the
+        // default FLOOR semantic the merge is most-permissive-wins, so the `FEATURES_UNLIMITED` default
+        // below would absorb every finite plan grant (`max(-1, 10_000) = -1`) and no cap could ever
+        // engage. CEILING inverts it: `-1` means "no ceiling" and YIELDS to the plan's finite grant.
+        //
+        // With CEILING, `defaultValue: FEATURES_UNLIMITED` is both correct and required: this
+        // definition is registered for EVERY application, so a finite default would silently cap every
+        // tenant that never opted into A2A budgeting (and `0` would deny every A2A turn everywhere).
+        // Budgeting stays opt-in — a real cap arrives only from a plan's `LimitGrant`.
+        identifier: A2A_TOKEN_BUDGET_FEATURE_ID,
+        valueType: FeatureValueType.LIMIT,
+        limitSemantic: FeatureLimitSemantic.CEILING,
+        // All three A2A owner scopes are declared because all three can OWN a turn. ⚠️ But only
+        // ORGANIZATIONS and USER_SELF have a BILLING rail (`BILLING_SCOPE_TO_VARIANTS` has no
+        // application variant), so an APPLICATION-scope cap cannot arrive from a plan `LimitGrant` —
+        // it must come from a features profile or a manual `limitOverrides`. Declaring the scope is
+        // still correct: without it an app-machine principal could never be capped by ANY mechanism.
+        applicableScopes: [
+            ResourcePrimaryScope.USER_SELF,
+            ResourcePrimaryScope.ORGANIZATIONS,
+            ResourcePrimaryScope.APPLICATION,
+        ],
+        dependencies: [],
+        defaultValue: FEATURES_UNLIMITED,
+    },
 ];
-//# sourceMappingURL=core-feature-definitions.shared.js.map
+//# sourceMappingURL=core-feature-definitions.shared.js.map

package/dist/esm/features/core-feature-definitions.shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-feature-definitions.shared.js","sourceRoot":"","sources":["../../../src/features/core-feature-definitions.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,uDAAuD,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAGvE;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IAC3D,4CAA4C;IAC5C;QACE,UAAU,EAAE,WAAW,CAAC,eAAe;QACvC,SAAS,EAAE,gBAAgB,CAAC,OAAO;QACnC,gBAAgB,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC;QACtD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,KAAK;KACpB;IACD;QACE,UAAU,EAAE,WAAW,CAAC,kBAAkB;QAC1C,SAAS,EAAE,gBAAgB,CAAC,OAAO;QACnC,gBAAgB,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC;QACtD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,KAAK;KACpB;IACD;QACE,UAAU,EAAE,WAAW,CAAC,cAAc;QACtC,SAAS,EAAE,gBAAgB,CAAC,OAAO;QACnC,gBAAgB,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC;QACtD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,KAAK;KACpB;IACD;QACE,UAAU,EAAE,WAAW,CAAC,UAAU;QAClC,SAAS,EAAE,gBAAgB,CAAC,OAAO;QACnC,gBAAgB,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC;QACtD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,KAAK;KACpB;IACD,sEAAsE;IACtE;QACE,UAAU,EAAE,aAAa;QACzB,SAAS,EAAE,gBAAgB,CAAC,KAAK;QACjC,gBAAgB,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC;QACtD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,CAAC;QACf,QAAQ,EAAE,EAAE,YAAY,EAAE,gBAAgB,CAAC,oBAAoB,EAAE;KAClE;IACD;QACE,UAAU,EAAE,cAAc;QAC1B,SAAS,EAAE,gBAAgB,CAAC,KAAK;QACjC,gBAAgB,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC;QACtD,YAAY,EAAE,EAAE;QAChB,YAAY,EAAE,CAAC;QACf,QAAQ,EAAE,EAAE,YAAY,EAAE,gBAAgB,CAAC,YAAY,EAAE;KAC1D;CACF,CAAC"}
+{"version":3,"file":"core-feature-definitions.shared.js","sourceRoot":"","sources":["../../../../src/features/core-feature-definitions.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Framework Core Feature Definitions\n *\n * These are business features managed by the engine (not tied to external providers).\n * Enabled by config profiles, billing products, or manual admin overrides.\n *\n * Note: PRIORITY_SUPPORT, CUSTOM_INTEGRATIONS, ADVANCED_PERMISSIONS from the old CoreOrganizationFeature\n * enum were dropped:\n * - PRIORITY_SUPPORT → modeled as a custom app feature (not engine-level)\n * - CUSTOM_INTEGRATIONS → modeled by provider declarations, not entitlement features\n * - ADVANCED_PERMISSIONS → handled by RBAC system, not feature gating\n */\n\nimport { CoreFeature } from '../organizations/organization-features.shared.schemas';\nimport { CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport { FEATURES_UNLIMITED, FeatureLimitSemantic, FeatureValueType } from './feature-definition.shared.schemas';\nimport type { FeatureDefinition } from './feature-definition.shared.schemas';\n\n/**\n * LIMIT-feature identifier for the inbound Agent2Agent (A2A) LLM **token budget**: how many LLM\n * tokens a tenant's A2A agent turns may consume per billing period. Grant it from a billing plan\n * (a `LimitGrant` on the product) and the A2A transport enforces it fail-closed, denying further\n * turns with HTTP 402 once exhausted.\n *\n * The single named source for this identifier — the backend budget service resolves the allowance\n * by this exact key, so definition and enforcement cannot drift.\n *\n * Measured in TOKENS, not currency: the framework's canonical provider-usage pricing registry is\n * deliberately not consulted by this A2A entitlement gate. The gate caps the transport's directly\n * metered token consumption; monetary reservation and settlement belong to the separate Work Cycle\n * budget authority.\n */\nexport const A2A_TOKEN_BUDGET_FEATURE_ID = 'a2a.llm.tokensPerPeriod';\n\n/**\n * Core feature definitions: every CoreFeature value + core LIMIT features.\n * Merged with custom app feature definitions at startup.\n */\nexport const CORE_FEATURE_DEFINITIONS: FeatureDefinition[] = [\n  // ─── BOOLEAN features (on/off toggles) ───\n  {\n    identifier: CoreFeature.CUSTOM_BRANDING,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: false,\n  },\n  {\n    identifier: CoreFeature.ADVANCED_ANALYTICS,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: false,\n  },\n  {\n    identifier: CoreFeature.SINGLE_SIGN_ON,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: false,\n  },\n  {\n    identifier: CoreFeature.AUDIT_LOGS,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: false,\n  },\n  {\n    // Outbound delivery of audit-trail events to a tenant-owned SIEM /\n    // compliance store. Depends on `AUDIT_LOGS` for the read-side surface,\n    // but the gate is independent so admins can enable read-only auditing\n    // without paying for outbound delivery.\n    identifier: CoreFeature.SECURITY_EVENT_EXPORT,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: false,\n  },\n  {\n    // SCIM-driven user/group provisioning. Typically procured alongside\n    // `SINGLE_SIGN_ON` but each feature is an independent gate so an org\n    // can run SSO without provisioning (or vice versa).\n    identifier: CoreFeature.DIRECTORY_PROVISIONING,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: false,\n  },\n  {\n    // M2M_WEBHOOK_DELIVERY is scope-bound: enabling it at the app level\n    // does NOT auto-enable it for every organization. Each scope (app or\n    // organization) opts in independently. See `FeatureDefinitionSchema.scopeBoundary`\n    // and `FeatureResolutionBackendService.isFeatureEnabledAtScope`.\n    identifier: CoreFeature.M2M_WEBHOOK_DELIVERY,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: [\n      ResourcePrimaryScope.APPLICATION,\n      ResourcePrimaryScope.ORGANIZATIONS,\n    ],\n    dependencies: [],\n    defaultValue: false,\n    scopeBoundary: true,\n  },\n  // ─── LIMIT features with counting configs (auto-checked by gate) ───\n  {\n    identifier: 'MAX_MEMBERS',\n    valueType: FeatureValueType.LIMIT,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: 5,\n    counting: { resourceType: CoreResourceType.ORGANIZATION_MEMBERS },\n  },\n  {\n    identifier: 'MAX_API_KEYS',\n    valueType: FeatureValueType.LIMIT,\n    applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],\n    dependencies: [],\n    defaultValue: 2,\n    counting: { resourceType: CoreResourceType.ORG_API_KEYS },\n  },\n  {\n    // Inbound A2A LLM token budget — see {@link A2A_TOKEN_BUDGET_FEATURE_ID}.\n    //\n    // Applies to all THREE A2A owner scopes: a user-delegated turn is owned by the delegating\n    // user, a machine turn by its organization or application.\n    //\n    // NO `counting` config, deliberately: consumption here is a SUM OF TOKENS, not a count of\n    // resource rows, so the gate's row-counting strategy cannot measure it. The A2A budget service\n    // owns measurement (accumulating into the `a2aTokenBudgetState` singleton) and resolves this\n    // limit directly — which is exactly the \"limit checking done in custom service code\" case the\n    // `counting` field documents as its absent-branch.\n    //\n    // ⚠️ `limitSemantic: CEILING` is LOAD-BEARING — without it this feature is inert. Under the\n    // default FLOOR semantic the merge is most-permissive-wins, so the `FEATURES_UNLIMITED` default\n    // below would absorb every finite plan grant (`max(-1, 10_000) = -1`) and no cap could ever\n    // engage. CEILING inverts it: `-1` means \"no ceiling\" and YIELDS to the plan's finite grant.\n    //\n    // With CEILING, `defaultValue: FEATURES_UNLIMITED` is both correct and required: this\n    // definition is registered for EVERY application, so a finite default would silently cap every\n    // tenant that never opted into A2A budgeting (and `0` would deny every A2A turn everywhere).\n    // Budgeting stays opt-in — a real cap arrives only from a plan's `LimitGrant`.\n    identifier: A2A_TOKEN_BUDGET_FEATURE_ID,\n    valueType: FeatureValueType.LIMIT,\n    limitSemantic: FeatureLimitSemantic.CEILING,\n    // All three A2A owner scopes are declared because all three can OWN a turn. ⚠️ But only\n    // ORGANIZATIONS and USER_SELF have a BILLING rail (`BILLING_SCOPE_TO_VARIANTS` has no\n    // application variant), so an APPLICATION-scope cap cannot arrive from a plan `LimitGrant` —\n    // it must come from a features profile or a manual `limitOverrides`. Declaring the scope is\n    // still correct: without it an app-machine principal could never be capped by ANY mechanism.\n    applicableScopes: [\n      ResourcePrimaryScope.USER_SELF,\n      ResourcePrimaryScope.ORGANIZATIONS,\n      ResourcePrimaryScope.APPLICATION,\n    ],\n    dependencies: [],\n    defaultValue: FEATURES_UNLIMITED,\n  },\n];\n"]}

package/dist/esm/features/feature-builders.shared.d.ts

@@ -5,8 +5,8 @@
  * These handle boilerplate: scope normalization, default values, counting config generation.
  * Custom app developers should use these instead of raw FeatureDefinition objects.
  */
-import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
-import { type FeatureDefinition, type FeatureUnavailabilityOverride, type LimitCountingConfig } from './feature-definition.shared.schemas.js';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
+import { FeatureLimitSemantic, type FeatureDefinition, type FeatureUnavailabilityOverride, type LimitCountingConfig } from './feature-definition.shared.schemas';
 /**
  * Internal marker symbol for limit features that should auto-register
  * a limitCheck on the counted resource's CREATE operation.
@@ -78,6 +78,17 @@ export declare function defineFeature(identifier: string, options: {
 export declare function defineLimitFeature(identifier: string, options: {
     scope: ResourcePrimaryScope | ResourcePrimaryScope[];
     default: number;
+    /**
+     * How this limit COMPOSES when several sources supply a value (see {@link FeatureLimitSemantic}).
+     * Omit for the default `FLOOR` — an entitlement the tenant is ALLOWED, where most-permissive
+     * wins and add-ons stack upward (`MAX_MEMBERS`, `MAX_API_KEYS`).
+     *
+     * Pass `CEILING` for a consumption CAP the tenant may not exceed: most-RESTRICTIVE wins, and
+     * `FEATURES_UNLIMITED` means "no ceiling" so it yields to any finite grant. Without it a cap is
+     * inexpressible — under FLOOR an unlimited default absorbs every finite plan grant, so the cap
+     * silently never engages.
+     */
+    limitSemantic?: FeatureLimitSemantic;
     /** Resource to count. Auto-registers a limitCheck on CREATE for this resource. */
     countResource?: string;
     /** Advanced: filter + aggregation for counting (overrides simple resource count) */

package/dist/esm/features/feature-builders.shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-builders.shared.d.ts","sourceRoot":"","sources":["../../../src/features/feature-builders.shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACzB,MAAM,qCAAqC,CAAC;AAM7C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,eAA0C,CAAC;AAEjF;;;GAGG;AACH,MAAM,MAAM,iCAAiC,GAAG,iBAAiB,GAAG;IAClE,CAAC,yBAAyB,CAAC,CAAC,EAAE;QAC5B,oFAAoF;QACpF,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAcF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;IACrD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,6BAA6B,CAAC;CAChD,GACA,iBAAiB,CASnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,6BAA6B,CAAC;CAChD,GACA,iCAAiC,CAwBnC"}
+{"version":3,"file":"feature-builders.shared.d.ts","sourceRoot":"","sources":["../../../../src/features/feature-builders.shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAGL,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACzB,MAAM,qCAAqC,CAAC;AAM7C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,eAA0C,CAAC;AAEjF;;;GAGG;AACH,MAAM,MAAM,iCAAiC,GAAG,iBAAiB,GAAG;IAClE,CAAC,yBAAyB,CAAC,CAAC,EAAE;QAC5B,oFAAoF;QACpF,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAcF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;IACrD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,6BAA6B,CAAC;CAChD,GACA,iBAAiB,CASnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,6BAA6B,CAAC;CAChD,GACA,iCAAiC,CA0BnC"}

package/dist/esm/features/feature-builders.shared.js

@@ -93,6 +93,8 @@ export function defineLimitFeature(identifier, options) {
         applicableScopes: normalizeScopes(options.scope),
         defaultValue: options.default,
         dependencies: options.dependencies ?? [],
+        // Omitted ⇒ absent on the definition ⇒ read as FLOOR, so every existing caller is unchanged.
+        ...(options.limitSemantic ? { limitSemantic: options.limitSemantic } : {}),
         counting,
         unavailability: options.unavailability,
     };
@@ -104,4 +106,4 @@ export function defineLimitFeature(identifier, options) {
     }
     return definition;
 }
-//# sourceMappingURL=feature-builders.shared.js.map
+//# sourceMappingURL=feature-builders.shared.js.map

package/dist/esm/features/feature-builders.shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-builders.shared.js","sourceRoot":"","sources":["../../../src/features/feature-builders.shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,gBAAgB,GAKjB,MAAM,qCAAqC,CAAC;AAE7C,wDAAwD;AACxD,iCAAiC;AACjC,wDAAwD;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAajF,wDAAwD;AACxD,sBAAsB;AACtB,wDAAwD;AAExD,SAAS,eAAe,CAAC,KAAoD;IAC3E,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,wDAAwD;AACxD,4CAA4C;AAC5C,wDAAwD;AAExD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,OAKC;IAED,OAAO;QACL,UAAU;QACV,SAAS,EAAE,gBAAgB,CAAC,OAAO;QACnC,gBAAgB,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC;QAChD,YAAY,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;QAC7C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;QACxC,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,+CAA+C;AAC/C,wDAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,OAWC;IAED,8FAA8F;IAC9F,MAAM,QAAQ,GACZ,OAAO,CAAC,QAAQ;QAChB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEhF,MAAM,UAAU,GAAsC;QACpD,UAAU;QACV,SAAS,EAAE,gBAAgB,CAAC,KAAK;QACjC,gBAAgB,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC;QAChD,YAAY,EAAE,OAAO,CAAC,OAAO;QAC7B,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;QACxC,QAAQ;QACR,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC;IAEF,kFAAkF;IAClF,IAAI,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACvD,UAAU,CAAC,yBAAyB,CAAC,GAAG;YACtC,aAAa,EAAE,OAAO,CAAC,aAAa;SACrC,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"feature-builders.shared.js","sourceRoot":"","sources":["../../../../src/features/feature-builders.shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,gBAAgB,GAMjB,MAAM,qCAAqC,CAAC;AAE7C,wDAAwD;AACxD,iCAAiC;AACjC,wDAAwD;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAajF,wDAAwD;AACxD,sBAAsB;AACtB,wDAAwD;AAExD,SAAS,eAAe,CAAC,KAAoD;IAC3E,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,wDAAwD;AACxD,4CAA4C;AAC5C,wDAAwD;AAExD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,OAKC;IAED,OAAO;QACL,UAAU;QACV,SAAS,EAAE,gBAAgB,CAAC,OAAO;QACnC,gBAAgB,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC;QAChD,YAAY,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;QAC7C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;QACxC,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,+CAA+C;AAC/C,wDAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,OAsBC;IAED,8FAA8F;IAC9F,MAAM,QAAQ,GACZ,OAAO,CAAC,QAAQ;QAChB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEhF,MAAM,UAAU,GAAsC;QACpD,UAAU;QACV,SAAS,EAAE,gBAAgB,CAAC,KAAK;QACjC,gBAAgB,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC;QAChD,YAAY,EAAE,OAAO,CAAC,OAAO;QAC7B,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;QACxC,6FAA6F;QAC7F,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,QAAQ;QACR,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC;IAEF,kFAAkF;IAClF,IAAI,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;QACvD,UAAU,CAAC,yBAAyB,CAAC,GAAG;YACtC,aAAa,EAAE,OAAO,CAAC,aAAa;SACrC,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC","sourcesContent":["/**\n * Feature Builder Utilities\n *\n * DX-oriented builder functions for defining features.\n * These handle boilerplate: scope normalization, default values, counting config generation.\n * Custom app developers should use these instead of raw FeatureDefinition objects.\n */\n\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  FeatureValueType,\n  FEATURES_UNLIMITED,\n  FeatureLimitSemantic,\n  type FeatureDefinition,\n  type FeatureUnavailabilityOverride,\n  type LimitCountingConfig,\n} from './feature-definition.shared.schemas';\n\n// =====================================================\n// Internal: Auto-register marker\n// =====================================================\n\n/**\n * Internal marker symbol for limit features that should auto-register\n * a limitCheck on the counted resource's CREATE operation.\n * Used by FeatureDefinitionRegistryBackendService at startup.\n */\nexport const AUTO_REGISTER_LIMIT_CHECK = Symbol.for('AUTO_REGISTER_LIMIT_CHECK');\n\n/**\n * Extended FeatureDefinition with auto-register metadata.\n * This is the internal type returned by defineLimitFeature when countResource is provided.\n */\nexport type FeatureDefinitionWithAutoRegister = FeatureDefinition & {\n  [AUTO_REGISTER_LIMIT_CHECK]?: {\n    /** Resource type whose CREATE operation should get a limitCheck for this feature */\n    countResource: string;\n  };\n};\n\n// =====================================================\n// Scope Normalization\n// =====================================================\n\nfunction normalizeScopes(scope: ResourcePrimaryScope | ResourcePrimaryScope[]): ResourcePrimaryScope[] {\n  return Array.isArray(scope) ? scope : [scope];\n}\n\n// =====================================================\n// defineFeature() — Boolean Feature Builder\n// =====================================================\n\n/**\n * Simple boolean feature builder.\n *\n * @example\n * defineFeature('AI_ASSISTANT', { scope: ResourcePrimaryScope.ORGANIZATIONS })\n *\n * @example\n * defineFeature('PREMIUM_THEMES', {\n *   scope: ResourcePrimaryScope.USER_SELF,\n *   unavailability: {\n *     behavior: FeatureUnavailabilityBehavior.UPGRADE_PROMPT,\n *   },\n * })\n */\nexport function defineFeature(\n  identifier: string,\n  options: {\n    scope: ResourcePrimaryScope | ResourcePrimaryScope[];\n    defaultEnabled?: boolean;\n    dependencies?: string[];\n    unavailability?: FeatureUnavailabilityOverride;\n  }\n): FeatureDefinition {\n  return {\n    identifier,\n    valueType: FeatureValueType.BOOLEAN,\n    applicableScopes: normalizeScopes(options.scope),\n    defaultValue: options.defaultEnabled ?? false,\n    dependencies: options.dependencies ?? [],\n    unavailability: options.unavailability,\n  };\n}\n\n// =====================================================\n// defineLimitFeature() — Limit Feature Builder\n// =====================================================\n\n/**\n * Limit feature builder with auto-wiring support.\n *\n * Key DX improvement: when `countResource` is provided, the engine\n * auto-registers a `limitChecks` entry on the CREATE operation of the\n * referenced resource at startup (via FeatureDefinitionRegistryBackendService).\n *\n * This means: to add \"max 10 projects per org\", write ONE call and the\n * gate is automatically enforced. No need to manually add limitChecks on\n * the resource's operation variant.\n *\n * @example\n * defineLimitFeature('MAX_PROJECTS', {\n *   scope: ResourcePrimaryScope.ORGANIZATIONS,\n *   default: 5,\n *   countResource: CustomShared_ResourceType.PROJECTS,\n * })\n * // Equivalent to manually defining:\n * //   { identifier: 'MAX_PROJECTS', valueType: LIMIT, applicableScopes: [ORGANIZATIONS],\n * //     defaultValue: 5, counting: { resourceType: 'PROJECTS' } }\n * //   + adding limitChecks: [{ featureId: 'MAX_PROJECTS' }] on PROJECTS.CREATE variant\n *\n * @example\n * defineLimitFeature('MAX_STORAGE_GB', {\n *   scope: ResourcePrimaryScope.ORGANIZATIONS,\n *   default: 10,\n *   counting: {\n *     resourceType: 'FILES',\n *     aggregate: { field: 'sizeBytes', operation: AggregationOperation.SUM },\n *   },\n * })\n */\nexport function defineLimitFeature(\n  identifier: string,\n  options: {\n    scope: ResourcePrimaryScope | ResourcePrimaryScope[];\n    default: number;\n    /**\n     * How this limit COMPOSES when several sources supply a value (see {@link FeatureLimitSemantic}).\n     * Omit for the default `FLOOR` — an entitlement the tenant is ALLOWED, where most-permissive\n     * wins and add-ons stack upward (`MAX_MEMBERS`, `MAX_API_KEYS`).\n     *\n     * Pass `CEILING` for a consumption CAP the tenant may not exceed: most-RESTRICTIVE wins, and\n     * `FEATURES_UNLIMITED` means \"no ceiling\" so it yields to any finite grant. Without it a cap is\n     * inexpressible — under FLOOR an unlimited default absorbs every finite plan grant, so the cap\n     * silently never engages.\n     */\n    limitSemantic?: FeatureLimitSemantic;\n    /** Resource to count. Auto-registers a limitCheck on CREATE for this resource. */\n    countResource?: string;\n    /** Advanced: filter + aggregation for counting (overrides simple resource count) */\n    counting?: LimitCountingConfig;\n    /** If true, skip auto-registration of limitChecks on the resource's CREATE operation */\n    skipAutoRegister?: boolean;\n    dependencies?: string[];\n    unavailability?: FeatureUnavailabilityOverride;\n  }\n): FeatureDefinitionWithAutoRegister {\n  // Build counting config: explicit counting takes precedence, then countResource, then nothing\n  const counting: LimitCountingConfig | undefined =\n    options.counting ??\n    (options.countResource ? { resourceType: options.countResource } : undefined);\n\n  const definition: FeatureDefinitionWithAutoRegister = {\n    identifier,\n    valueType: FeatureValueType.LIMIT,\n    applicableScopes: normalizeScopes(options.scope),\n    defaultValue: options.default,\n    dependencies: options.dependencies ?? [],\n    // Omitted ⇒ absent on the definition ⇒ read as FLOOR, so every existing caller is unchanged.\n    ...(options.limitSemantic ? { limitSemantic: options.limitSemantic } : {}),\n    counting,\n    unavailability: options.unavailability,\n  };\n\n  // Add auto-register marker for limit features with countResource (unless skipped)\n  if (options.countResource && !options.skipAutoRegister) {\n    definition[AUTO_REGISTER_LIMIT_CHECK] = {\n      countResource: options.countResource,\n    };\n  }\n\n  return definition;\n}\n"]}

package/dist/esm/features/feature-definition.shared.schemas.d.ts

@@ -9,7 +9,7 @@
  * This is the DEFINITION layer — not the storage layer (that's ScopeFeaturesSchema in T1.3).
  */
 import { z } from 'zod';
-import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
 export declare enum FeatureValueType {
     /** On/off toggle: checked via features.includes(id) */
     BOOLEAN = "boolean",
@@ -68,8 +68,8 @@ export declare const LimitCountingConfigSchema: z.ZodObject<{
     aggregate: z.ZodOptional<z.ZodObject<{
         field: z.ZodString;
         operation: z.ZodEnum<typeof AggregationOperation>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type LimitCountingConfig = z.infer<typeof LimitCountingConfigSchema>;
 /**
  * Rate limiting configuration for features (data model prepared, implementation deferred).
@@ -100,7 +100,7 @@ export declare const RateLimitConfigSchema: z.ZodOptional<z.ZodObject<{
         per_api_key: "per_api_key";
         per_scope_entity: "per_scope_entity";
     }>>;
-}, z.core.$strip, core.$ZodObjectExtra>>;
+}, z.core.$strip>>;
 export type RateLimitConfig = z.infer<typeof RateLimitConfigSchema>;
 /**
  * Per-feature unavailability behavior override.
@@ -112,22 +112,65 @@ export declare const FeatureUnavailabilityOverrideSchema: z.ZodObject<{
     byRole: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<typeof FeatureUnavailabilityBehavior>>>;
     suggestedProductRef: z.ZodOptional<z.ZodString>;
     customComponentRef: z.ZodOptional<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type FeatureUnavailabilityOverride = z.infer<typeof FeatureUnavailabilityOverrideSchema>;
+/**
+ * @wildo_source:part:start saas.models.feature-limit-semantic facet:layer:shared facet:family:features
+ *
+ * How a LIMIT feature's value composes when several sources supply one (plan grants, add-ons,
+ * profile defaults, the definition default, and the parent scopes in a resolution chain).
+ *
+ * The two are genuine opposites, and picking the wrong one silently inverts enforcement — hence an
+ * explicit vocabulary rather than an implicit convention. Pass it via `defineLimitFeature`'s
+ * `limitSemantic` option. Import path: `@wildo-ai/saas-models`.
+ *
+ * @example
+ * // An entitlement the plan RAISES (default — omit the option entirely):
+ * defineLimitFeature('MAX_PROJECTS', { scope: ResourcePrimaryScope.ORGANIZATIONS, default: 5 });
+ *
+ * // A consumption CAP the plan TIGHTENS — note the unlimited default:
+ * defineLimitFeature('MONTHLY_TOKEN_CAP', {
+ *   scope: ResourcePrimaryScope.ORGANIZATIONS,
+ *   default: FEATURES_UNLIMITED,
+ *   limitSemantic: FeatureLimitSemantic.CEILING,
+ * });
+ */
+export declare enum FeatureLimitSemantic {
+    /**
+     * **Entitlement floor** (the default, and how every pre-existing LIMIT feature behaves): the
+     * limit is something the tenant is ALLOWED, so more is better and the MOST-PERMISSIVE value wins
+     * — `max(a, b)`, with `FEATURES_UNLIMITED` beating everything. Add-ons stack upward on top of a
+     * plan. Example: `MAX_MEMBERS` — a plan grants 5, an add-on raises it to 20.
+     */
+    FLOOR = "floor",
+    /**
+     * **Consumption ceiling**: the limit is a CAP the tenant may not exceed, so less is safer and the
+     * MOST-RESTRICTIVE value wins — `min(a, b)`, and `FEATURES_UNLIMITED` means "imposes no ceiling"
+     * so it LOSES to any finite value.
+     *
+     * That inversion is what makes a cap expressible at all. Under FLOOR semantics a definition
+     * default of `FEATURES_UNLIMITED` would absorb every finite plan grant (`max(-1, 10_000) = -1`),
+     * so the cap could never engage; under CEILING the same default correctly means "no cap until a
+     * plan sets one", and the plan's finite grant wins. Example: the A2A LLM token budget.
+     */
+    CEILING = "ceiling"
+}
+/** @wildo_source:part:end saas.models.feature-limit-semantic */
 export declare const FeatureDefinitionSchema: z.ZodObject<{
     identifier: z.ZodString;
     valueType: z.ZodEnum<typeof FeatureValueType>;
     applicableScopes: z.ZodArray<z.ZodEnum<typeof ResourcePrimaryScope>>;
     defaultValue: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>;
     dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    limitSemantic: z.ZodOptional<z.ZodEnum<typeof FeatureLimitSemantic>>;
     counting: z.ZodOptional<z.ZodObject<{
         resourceType: z.ZodString;
         filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         aggregate: z.ZodOptional<z.ZodObject<{
             field: z.ZodString;
             operation: z.ZodEnum<typeof AggregationOperation>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     rateLimit: z.ZodOptional<z.ZodObject<{
         maxPerWindow: z.ZodNumber;
         window: z.ZodEnum<typeof RateWindowUnit>;
@@ -138,14 +181,15 @@ export declare const FeatureDefinitionSchema: z.ZodObject<{
             per_api_key: "per_api_key";
             per_scope_entity: "per_scope_entity";
         }>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     unavailability: z.ZodOptional<z.ZodObject<{
         behavior: z.ZodOptional<z.ZodEnum<typeof FeatureUnavailabilityBehavior>>;
         byRole: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<typeof FeatureUnavailabilityBehavior>>>;
         suggestedProductRef: z.ZodOptional<z.ZodString>;
         customComponentRef: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+    scopeBoundary: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 export type FeatureDefinition = z.infer<typeof FeatureDefinitionSchema>;
 /**
  * Sentinel value for "unlimited" in limit-type features.
@@ -178,10 +222,10 @@ export declare const RequiredFeaturesConfigSchema: z.ZodUnion<readonly [z.ZodArr
             aggregate: z.ZodOptional<z.ZodObject<{
                 field: z.ZodString;
                 operation: z.ZodEnum<typeof AggregationOperation>;
-            }, z.core.$strip, core.$ZodObjectExtra>>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
-}, z.core.$strip, core.$ZodObjectExtra>]>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>]>;
 /**
  * Central feature configuration — ONE object per app, shared between frontend and backend.
  * Defines ALL feature definitions + the global unavailability policy.
@@ -197,14 +241,15 @@ export declare const FeatureConfigurationSchema: z.ZodObject<{
         applicableScopes: z.ZodArray<z.ZodEnum<typeof ResourcePrimaryScope>>;
         defaultValue: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber]>;
         dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        limitSemantic: z.ZodOptional<z.ZodEnum<typeof FeatureLimitSemantic>>;
         counting: z.ZodOptional<z.ZodObject<{
             resourceType: z.ZodString;
             filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             aggregate: z.ZodOptional<z.ZodObject<{
                 field: z.ZodString;
                 operation: z.ZodEnum<typeof AggregationOperation>;
-            }, z.core.$strip, core.$ZodObjectExtra>>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         rateLimit: z.ZodOptional<z.ZodObject<{
             maxPerWindow: z.ZodNumber;
             window: z.ZodEnum<typeof RateWindowUnit>;
@@ -215,25 +260,26 @@ export declare const FeatureConfigurationSchema: z.ZodObject<{
                 per_api_key: "per_api_key";
                 per_scope_entity: "per_scope_entity";
             }>>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         unavailability: z.ZodOptional<z.ZodObject<{
             behavior: z.ZodOptional<z.ZodEnum<typeof FeatureUnavailabilityBehavior>>;
             byRole: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<typeof FeatureUnavailabilityBehavior>>>;
             suggestedProductRef: z.ZodOptional<z.ZodString>;
             customComponentRef: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
+        scopeBoundary: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        features: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("../index.js").CoreFeature>, z.ZodEnum<typeof import("../index.js").EngineCapability>, z.ZodString]>>>>;
-        limits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
+        features: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodEnum<typeof import("..").CoreFeature>, z.ZodString]>>>>>;
+        limits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>>>;
+    }, z.core.$strip>>>;
     defaultProfile: z.ZodOptional<z.ZodString>;
     unavailabilityPolicy: z.ZodDefault<z.ZodObject<{
         defaultBehavior: z.ZodDefault<z.ZodEnum<typeof FeatureUnavailabilityBehavior>>;
         whenBillingDisabled: z.ZodDefault<z.ZodEnum<typeof FeatureUnavailabilityBehavior>>;
         roleDefaults: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<typeof FeatureUnavailabilityBehavior>>>;
         reasonDefaults: z.ZodDefault<z.ZodRecord<z.ZodEnum<typeof FeatureUnavailabilityReason>, z.ZodEnum<typeof FeatureUnavailabilityBehavior>>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export type FeatureConfiguration = z.infer<typeof FeatureConfigurationSchema>;
 //# sourceMappingURL=feature-definition.shared.schemas.d.ts.map

package/dist/esm/features/feature-definition.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-definition.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/features/feature-definition.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAO7E,oBAAY,gBAAgB;IAC1B,uDAAuD;IACvD,OAAO,YAAY;IACnB,6DAA6D;IAC7D,KAAK,UAAU;CAChB;AAMD;;;;GAIG;AACH,oBAAY,6BAA6B;IACvC,sCAAsC;IACtC,IAAI,SAAS;IACb,sCAAsC;IACtC,OAAO,YAAY;IACnB,8CAA8C;IAC9C,cAAc,mBAAmB;IACjC,iDAAiD;IACjD,YAAY,iBAAiB;IAC7B,wDAAwD;IACxD,aAAa,kBAAkB;IAC/B,gEAAgE;IAChE,oBAAoB,yBAAyB;IAC7C,wHAAwH;IACxH,MAAM,WAAW;CAClB;AAMD;;;GAGG;AACH,oBAAY,2BAA2B;IACrC,oDAAoD;IACpD,mBAAmB,wBAAwB;IAC3C,mDAAmD;IACnD,cAAc,mBAAmB;IACjC,qDAAqD;IACrD,cAAc,mBAAmB;CAClC;AAMD;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,GAAG,QAAQ;CACZ;AAMD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;uCAgBpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAM5E;;;;;;;;;;;;;GAaG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED,eAAO,MAAM,qBAAqB;;;;;;;;;;wCASrB,CAAC;AACd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE;;;;GAIG;AACH,eAAO,MAAM,mCAAmC;;;;;uCAS9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAMhG,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAqClC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAMrC;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;yCAWvC,CAAC;AAMH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCA0DrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}
+{"version":3,"file":"feature-definition.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/features/feature-definition.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAO7E,oBAAY,gBAAgB;IAC1B,uDAAuD;IACvD,OAAO,YAAY;IACnB,6DAA6D;IAC7D,KAAK,UAAU;CAChB;AAMD;;;;GAIG;AACH,oBAAY,6BAA6B;IACvC,sCAAsC;IACtC,IAAI,SAAS;IACb,sCAAsC;IACtC,OAAO,YAAY;IACnB,8CAA8C;IAC9C,cAAc,mBAAmB;IACjC,iDAAiD;IACjD,YAAY,iBAAiB;IAC7B,wDAAwD;IACxD,aAAa,kBAAkB;IAC/B,gEAAgE;IAChE,oBAAoB,yBAAyB;IAC7C,wHAAwH;IACxH,MAAM,WAAW;CAClB;AAMD;;;GAGG;AACH,oBAAY,2BAA2B;IACrC,oDAAoD;IACpD,mBAAmB,wBAAwB;IAC3C,mDAAmD;IACnD,cAAc,mBAAmB;IACjC,qDAAqD;IACrD,cAAc,mBAAmB;CAClC;AAMD;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,GAAG,QAAQ;CACZ;AAMD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;iBAgBpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAM5E;;;;;;;;;;;;;GAaG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED,eAAO,MAAM,qBAAqB;;;;;;;;;;kBASrB,CAAC;AACd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE;;;;GAIG;AACH,eAAO,MAAM,mCAAmC;;;;;iBAS9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAMhG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oBAAY,oBAAoB;IAC9B;;;;;OAKG;IACH,KAAK,UAAU;IACf;;;;;;;;;OASG;IACH,OAAO,YAAY;CACpB;AACD,gEAAgE;AAMhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4ElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAMrC;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;mBAWvC,CAAC;AAMH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0DrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/esm/features/feature-definition.shared.schemas.js

@@ -149,6 +149,52 @@ export const FeatureUnavailabilityOverrideSchema = z.object({
     customComponentRef: z.string().optional(),
 });
 // =====================================================
+// Limit Semantics
+// =====================================================
+/**
+ * @wildo_source:part:start saas.models.feature-limit-semantic facet:layer:shared facet:family:features
+ *
+ * How a LIMIT feature's value composes when several sources supply one (plan grants, add-ons,
+ * profile defaults, the definition default, and the parent scopes in a resolution chain).
+ *
+ * The two are genuine opposites, and picking the wrong one silently inverts enforcement — hence an
+ * explicit vocabulary rather than an implicit convention. Pass it via `defineLimitFeature`'s
+ * `limitSemantic` option. Import path: `@wildo-ai/saas-models`.
+ *
+ * @example
+ * // An entitlement the plan RAISES (default — omit the option entirely):
+ * defineLimitFeature('MAX_PROJECTS', { scope: ResourcePrimaryScope.ORGANIZATIONS, default: 5 });
+ *
+ * // A consumption CAP the plan TIGHTENS — note the unlimited default:
+ * defineLimitFeature('MONTHLY_TOKEN_CAP', {
+ *   scope: ResourcePrimaryScope.ORGANIZATIONS,
+ *   default: FEATURES_UNLIMITED,
+ *   limitSemantic: FeatureLimitSemantic.CEILING,
+ * });
+ */
+export var FeatureLimitSemantic;
+(function (FeatureLimitSemantic) {
+    /**
+     * **Entitlement floor** (the default, and how every pre-existing LIMIT feature behaves): the
+     * limit is something the tenant is ALLOWED, so more is better and the MOST-PERMISSIVE value wins
+     * — `max(a, b)`, with `FEATURES_UNLIMITED` beating everything. Add-ons stack upward on top of a
+     * plan. Example: `MAX_MEMBERS` — a plan grants 5, an add-on raises it to 20.
+     */
+    FeatureLimitSemantic["FLOOR"] = "floor";
+    /**
+     * **Consumption ceiling**: the limit is a CAP the tenant may not exceed, so less is safer and the
+     * MOST-RESTRICTIVE value wins — `min(a, b)`, and `FEATURES_UNLIMITED` means "imposes no ceiling"
+     * so it LOSES to any finite value.
+     *
+     * That inversion is what makes a cap expressible at all. Under FLOOR semantics a definition
+     * default of `FEATURES_UNLIMITED` would absorb every finite plan grant (`max(-1, 10_000) = -1`),
+     * so the cap could never engage; under CEILING the same default correctly means "no cap until a
+     * plan sets one", and the plan's finite grant wins. Example: the A2A LLM token budget.
+     */
+    FeatureLimitSemantic["CEILING"] = "ceiling";
+})(FeatureLimitSemantic || (FeatureLimitSemantic = {}));
+/** @wildo_source:part:end saas.models.feature-limit-semantic */
+// =====================================================
 // Feature Definition
 // =====================================================
 export const FeatureDefinitionSchema = z.object({
@@ -162,6 +208,20 @@ export const FeatureDefinitionSchema = z.object({
     defaultValue: z.union([z.boolean(), z.number()]),
     /** Feature dependencies: these feature identifiers must also be enabled for this feature to be active */
     dependencies: z.array(z.string()).default([]),
+    /**
+     * For LIMIT features: how this limit COMPOSES when several sources supply a value
+     * (see {@link FeatureLimitSemantic}). ABSENT means `FLOOR` — an entitlement the tenant is
+     * allowed, most-permissive wins — which is how every limit behaved before this field existed, so
+     * omitting it preserves existing behaviour exactly. Set `CEILING` for a consumption cap, where
+     * the most-RESTRICTIVE value wins and `FEATURES_UNLIMITED` means "no ceiling".
+     * Ignored for BOOLEAN features.
+     *
+     * Declared `.optional()` rather than `.default(FLOOR)` deliberately: a Zod default is REQUIRED on
+     * the inferred output type, which would force every existing definition literal (and every app's)
+     * to spell out a field that is only meaningful for caps. Both consumers apply the `FLOOR`
+     * fallback when reading, so absence and an explicit `FLOOR` behave identically.
+     */
+    limitSemantic: z.enum(FeatureLimitSemantic).optional(),
     /**
      * For LIMIT features: how to measure current usage (the "counting" strategy).
      * When present: the gate can auto-check limits using this config.
@@ -181,6 +241,29 @@ export const FeatureDefinitionSchema = z.object({
      * When absent: global defaults apply (role > reason > app default).
      */
     unavailability: FeatureUnavailabilityOverrideSchema.optional(),
+    /**
+     * If true, this feature does NOT participate in the cross-scope chain-union
+     * performed by `FeatureResolutionBackendService.resolve()`.
+     *
+     * Default behavior (`scopeBoundary === false / undefined`): a feature
+     * enabled at the APPLICATION layer cascades down to every org/user
+     * request — the resolver merges features from every scope in the chain
+     * (`mergeScopeFeatures`). This is appropriate for capability-style
+     * gates ("audit logs available app-wide").
+     *
+     * `scopeBoundary === true`: the feature is only "on" when the EXACT
+     * scope it is queried against has it enabled. Callers MUST use
+     * `featureResolution.isFeatureEnabledAtScope(featureId, scopeType, entityId)`
+     * — the unscoped `isFeatureEnabled(featureId, ec)` throws for these
+     * features (developer guidance: chain-union semantics would silently
+     * defeat per-scope opt-in, which is the whole point of marking a
+     * feature scope-bound).
+     *
+     * Use this for opt-in policies that MUST stay per-org / per-app
+     * even when a parent scope has the same flag enabled (e.g.
+     * `M2M_WEBHOOK_DELIVERY` — admins decide per organization).
+     */
+    scopeBoundary: z.boolean().optional(),
 });
 // =====================================================
 // FEATURES_UNLIMITED Constant
@@ -277,4 +360,4 @@ export const FeatureConfigurationSchema = z.object({
     // requires a value that matches the schema's output type (all fields required).
     // The inner .default() on each field still applies when parsing partial input.
 });
-//# sourceMappingURL=feature-definition.shared.schemas.js.map
+//# sourceMappingURL=feature-definition.shared.schemas.js.map