@wildo-ai/saas-models 1.1.1 → 1.1.3

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

@@ -25,6 +25,37 @@ function normalizeScopes(scope) {
 // defineFeature() — Boolean Feature Builder
 // =====================================================
 /**
+ * @wildo_source:part:start saas.models.features.definition-builders facet:layer:shared facet:audience:app-developer
+ *
+ * Declaring what an application can SELL or gate on. Two builders, from `@wildo-ai/saas-models`:
+ * `defineFeature` for a boolean capability, `defineLimitFeature` for a numeric allowance.
+ *
+ * A product in the billing catalogue then grants them through `grantedFeatures` / `grantedLimits`,
+ * and any surface gates on the identifier with `requiredFeatures` — a resource operation, a view, a
+ * chart, a navigation item, a settings section.
+ *
+ * ## Two things that decide whether the gate actually fires
+ *
+ * (`limitSemantic` is the third and is covered by the product-definitions skill's own guidance —
+ * the default `FLOOR` is an entitlement the tenant is ALLOWED, and a consumption CAP needs `CEILING`.)
+ *
+ * - **`countResource` is the one-call form.** It registers a limit check on that resource's CREATE
+ *   automatically, so "at most ten projects per organisation" is one declaration rather than a
+ *   definition plus a hand-written gate. A limit declared WITHOUT counting cannot be checked
+ *   automatically: `checkLimit` REFUSES rather than guessing at a remaining quota, and the caller
+ *   must pass a counting override or measure consumption itself. That is the right answer for a
+ *   quantity that is not a row count — a sum of tokens, for instance.
+ * - **`rateLimit` on a definition is RESERVED and ignored by the gate.** A time-windowed allowance
+ *   like "one hundred calls an hour" is not expressible here at all; abuse throttling is a separate
+ *   mechanism with its own declaration.
+ *
+ * ## Granting a capability does not configure it
+ *
+ * An entitlement says the tenant MAY have the thing. Single sign-on entitles an organisation to
+ * register an identity provider; somebody still has to register one. The same holds for provisioning
+ * tokens, export destinations and webhook endpoints — so a plan that grants one of these still needs
+ * an onboarding step behind it.
+ *
  * Simple boolean feature builder.
  *
  * @example
@@ -106,4 +137,5 @@ export function defineLimitFeature(identifier, options) {
     }
     return definition;
 }
+/** @wildo_source:part:end saas.models.features.definition-builders */
 //# 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,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"]}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;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;AACD,sEAAsE","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 * @wildo_source:part:start saas.models.features.definition-builders facet:layer:shared facet:audience:app-developer\n *\n * Declaring what an application can SELL or gate on. Two builders, from `@wildo-ai/saas-models`:\n * `defineFeature` for a boolean capability, `defineLimitFeature` for a numeric allowance.\n *\n * A product in the billing catalogue then grants them through `grantedFeatures` / `grantedLimits`,\n * and any surface gates on the identifier with `requiredFeatures` — a resource operation, a view, a\n * chart, a navigation item, a settings section.\n *\n * ## Two things that decide whether the gate actually fires\n *\n * (`limitSemantic` is the third and is covered by the product-definitions skill's own guidance —\n * the default `FLOOR` is an entitlement the tenant is ALLOWED, and a consumption CAP needs `CEILING`.)\n *\n * - **`countResource` is the one-call form.** It registers a limit check on that resource's CREATE\n *   automatically, so \"at most ten projects per organisation\" is one declaration rather than a\n *   definition plus a hand-written gate. A limit declared WITHOUT counting cannot be checked\n *   automatically: `checkLimit` REFUSES rather than guessing at a remaining quota, and the caller\n *   must pass a counting override or measure consumption itself. That is the right answer for a\n *   quantity that is not a row count — a sum of tokens, for instance.\n * - **`rateLimit` on a definition is RESERVED and ignored by the gate.** A time-windowed allowance\n *   like \"one hundred calls an hour\" is not expressible here at all; abuse throttling is a separate\n *   mechanism with its own declaration.\n *\n * ## Granting a capability does not configure it\n *\n * An entitlement says the tenant MAY have the thing. Single sign-on entitles an organisation to\n * register an identity provider; somebody still has to register one. The same holds for provisioning\n * tokens, export destinations and webhook endpoints — so a plan that grants one of these still needs\n * an onboarding step behind it.\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/** @wildo_source:part:end saas.models.features.definition-builders */\n"]}

package/dist/esm/features/user-features.shared.resources-config.schemas.d.ts

@@ -7,7 +7,7 @@
  */
 import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
 import { ResourceRelationship } from '../resources/resources.shared.schemas';
-type UserFeaturesCoreOperations = CoreResourceOperation.CREATE | CoreResourceOperation.READ | CoreResourceOperation.SEARCH | CoreResourceOperation.UPDATE | CoreResourceOperation.DELETE;
+type UserFeaturesCoreOperations = CoreResourceOperation.CREATE | CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.UPDATE_MANY | CoreResourceOperation.SEARCH | CoreResourceOperation.UPDATE | CoreResourceOperation.DELETE;
 export declare const userFeaturesResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("..").ResourceConfiguration<Record<string, never>, UserFeaturesCoreOperations, import("zod").ZodObject<{
     features: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodEnum<typeof import("..").CoreFeature>, import("zod").ZodString]>>>>>;
     limits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>>>;

package/dist/esm/features/user-features.shared.resources-config.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-features.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/features/user-features.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAA8B,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAQzG,KAAK,0BAA0B,GAC3B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,uDAAuD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;iCA6FpH,CAAC"}
+{"version":3,"file":"user-features.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/features/user-features.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAA8B,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAQzG,KAAK,0BAA0B,GAC3B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,WAAW,GACjC,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,uDAAuD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;iCA+IpH,CAAC"}

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

@@ -6,6 +6,7 @@
  * Uses ScopeFeaturesWithOverridesSchema as mainSchema (same pattern as org features).
  */
 import { ScopeFeaturesWithOverridesSchema } from './scope-features.shared.schemas.js';
+import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas.js';
 import { CoreResourceOperation } from '../resources/resources.shared.core.definitions.js';
 import { ResourceOperationRiskLevel } from '../resources/resources.shared.schemas.js';
 import { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions.js';
@@ -23,11 +24,31 @@ export const userFeaturesResourceConfiguration_InitializationFactory = (resource
     /** Subject-export disclosure. The subject's own data. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. */
     systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
     portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.DERIVED },
+    /**
+     * Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.
+     *
+     * `RETAIN_ONLY` is a positive assertion, not a default: this resource holds feature toggles, added
+     * and removed feature keys, and numeric limit overrides. Its only link to a person is the scope
+     * foreign key, which the never-scrub floor protects in every mode. Declaring the mode is what lets a
+     * notice say what erasure does to these rows instead of reporting them as undeclared.
+     *
+     * The assertion is CHECKED: the factory refuses `RETAIN_ONLY` if any field declares an impersonalize
+     * treatment, because a treatment that would never run is a config claiming something the runtime
+     * would not honour.
+     */
+    retentionPolicy: {
+        mode: ErasureRetentionMode.RETAIN_ONLY,
+    },
+    /** The subject is the person whose features these are, reached through the scope key. */
+    dataSubjectPolicy: { kind: ResourceDataSubjectKind.SELF_PRINCIPAL },
     coreOperations: [
         CoreResourceOperation.CREATE,
         CoreResourceOperation.READ,
         CoreResourceOperation.SEARCH,
         CoreResourceOperation.UPDATE,
+        // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY (see the variants).
+        CoreResourceOperation.LIST,
+        CoreResourceOperation.UPDATE_MANY,
         // DELETE is REPOSITORY_ONLY (no HTTP route): the scope-features ledger is not
         // API-deletable, but the composition `onParentDelete` cascade must physically
         // delete the row when its owning user is deleted. Without a DELETE op the cascade
@@ -37,6 +58,33 @@ export const userFeaturesResourceConfiguration_InitializationFactory = (resource
     ],
     customOperation: {},
     operationsConfiguration: {
+        /*
+         * Route-less retention plumbing — INTERNAL_CALL registers no route. Not REPOSITORY_ONLY: the
+         * retention primitives resolve through `getServiceOperationPathDefault`, which excludes it, so
+         * that spelling passes the boot guard and fails when an erasure runs. LIST is LOW because a
+         * read-shaped operation may not claim the HIGH/CRITICAL band — that band carries an audit-emission
+         * obligation, checked over the real engine catalogue.
+         */
+        [CoreResourceOperation.LIST]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
+        },
+        [CoreResourceOperation.UPDATE_MANY]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.INTERNAL_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.CRITICAL,
+                },
+            ],
+        },
         [CoreResourceOperation.CREATE]: {
             variants: [
                 {

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

@@ -1 +1 @@
-{"version":3,"file":"user-features.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/features/user-features.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * User Features Shared Resource Configuration\n *\n * Resource configuration for user-level feature management.\n * Controls which features are available to individual users (overrides/additions).\n * Uses ScopeFeaturesWithOverridesSchema as mainSchema (same pattern as org features).\n */\n\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, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\n\ntype UserFeaturesCoreOperations =\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.UPDATE\n  | CoreResourceOperation.DELETE;\n\nexport const userFeaturesResourceConfiguration_InitializationFactory = (resourcesRelationships: ResourceRelationship[]) => createResourceConfiguration_Initialization<\n  Record<string, never>,\n  UserFeaturesCoreOperations,\n  typeof ScopeFeaturesWithOverridesSchema\n>({\n  mainSchema: ScopeFeaturesWithOverridesSchema,\n  resourceIdentifier: CoreResourceType.USER_FEATURES,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USER_FEATURES],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n\n  /** Subject-export disclosure. The subject's own data. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. */\n  systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },\n  portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.DERIVED },\n\n  coreOperations: [\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.READ,\n    CoreResourceOperation.SEARCH,\n    CoreResourceOperation.UPDATE,\n    // DELETE is REPOSITORY_ONLY (no HTTP route): the scope-features ledger is not\n    // API-deletable, but the composition `onParentDelete` cascade must physically\n    // delete the row when its owning user is deleted. Without a DELETE op the cascade\n    // (`deleteChildrenImmediate`) throws ErrorType.CONFIGURATION on any user that has a\n    // features row. See .claude/plans/composition-oncreate-lifecycle.md (FEATURES wave).\n    CoreResourceOperation.DELETE,\n  ],\n\n  customOperation: {} as Record<string, never>,\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_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }\n      ]\n    },\n\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_MEMBER],\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});\n"]}
+{"version":3,"file":"user-features.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/features/user-features.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * User Features Shared Resource Configuration\n *\n * Resource configuration for user-level feature management.\n * Controls which features are available to individual users (overrides/additions).\n * Uses ScopeFeaturesWithOverridesSchema as mainSchema (same pattern as org features).\n */\n\nimport { ScopeFeaturesWithOverridesSchema } from './scope-features.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.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, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\n\ntype UserFeaturesCoreOperations =\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.UPDATE_MANY\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.UPDATE\n  | CoreResourceOperation.DELETE;\n\nexport const userFeaturesResourceConfiguration_InitializationFactory = (resourcesRelationships: ResourceRelationship[]) => createResourceConfiguration_Initialization<\n  Record<string, never>,\n  UserFeaturesCoreOperations,\n  typeof ScopeFeaturesWithOverridesSchema\n>({\n  mainSchema: ScopeFeaturesWithOverridesSchema,\n  resourceIdentifier: CoreResourceType.USER_FEATURES,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USER_FEATURES],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n\n  /** Subject-export disclosure. The subject's own data. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. */\n  systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },\n  portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.DERIVED },\n\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, not a default: this resource holds feature toggles, added\n   * and removed feature keys, and numeric limit overrides. Its only link to a person is the scope\n   * foreign key, which the never-scrub floor protects in every mode. Declaring the mode is what lets a\n   * notice say what erasure does to these rows instead of reporting them as undeclared.\n   *\n   * The assertion is CHECKED: the factory refuses `RETAIN_ONLY` if any field declares an impersonalize\n   * treatment, because a treatment that would never run is a config claiming something the runtime\n   * would not honour.\n   */\n  retentionPolicy: {\n    mode: ErasureRetentionMode.RETAIN_ONLY,\n  },\n\n  /** The subject is the person whose features these are, reached through the scope key. */\n  dataSubjectPolicy: { kind: ResourceDataSubjectKind.SELF_PRINCIPAL },\n\n  coreOperations: [\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.READ,\n    CoreResourceOperation.SEARCH,\n    CoreResourceOperation.UPDATE,\n    // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY (see the variants).\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.UPDATE_MANY,\n    // DELETE is REPOSITORY_ONLY (no HTTP route): the scope-features ledger is not\n    // API-deletable, but the composition `onParentDelete` cascade must physically\n    // delete the row when its owning user is deleted. Without a DELETE op the cascade\n    // (`deleteChildrenImmediate`) throws ErrorType.CONFIGURATION on any user that has a\n    // features row. See .claude/plans/composition-oncreate-lifecycle.md (FEATURES wave).\n    CoreResourceOperation.DELETE,\n  ],\n\n  customOperation: {} as Record<string, never>,\n\n  operationsConfiguration: {\n    /*\n     * Route-less retention plumbing — INTERNAL_CALL registers no route. Not REPOSITORY_ONLY: the\n     * retention primitives resolve through `getServiceOperationPathDefault`, which excludes it, so\n     * that spelling passes the boot guard and fails when an erasure runs. LIST is LOW because a\n     * read-shaped operation may not claim the HIGH/CRITICAL band — that band carries an audit-emission\n     * obligation, checked over the real engine catalogue.\n     */\n    [CoreResourceOperation.LIST]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n    [CoreResourceOperation.UPDATE_MANY]: {\n      variants: [\n        {\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.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_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }\n      ]\n    },\n\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_MEMBER],\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});\n"]}

package/dist/esm/files/file-upload-grant.shared.schemas.d.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+import { FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+import { FileStatus } from './files.shared.schemas';
+/**
+ * File upload grant — the shared contract between the two mint doors (REST, MCP), the upload route,
+ * the status read, and the browser drop page (issue #312).
+ *
+ * A grant is a single-use consumable token. Nothing durable is created at mint but the token: an
+ * abandoned grant leaves a dead token and nothing else. The upload itself goes through the resource's
+ * EXISTING file-upload route, authenticated by the grant alone, and the ordinary authorizer decides.
+ */
+/**
+ * Public frontend route the browser drop page lives on; the token follows as the next path segment
+ * (`/upload-grant/<token>`). Declared HERE so the backend (which builds `uploadPageUrl`) and the
+ * frontend (which mounts the route) read one source — the backend cannot import frontend route
+ * constants.
+ */
+export declare const FILE_UPLOAD_GRANT_PAGE_PATH = "/upload-grant";
+/** @wildo_source:part:start saas.models.file-upload-grant facet:layer:shared facet:family:files
+ *
+ * Lifetime bounds of an upload grant, in minutes. The ceiling is fixed by the framework and enforced
+ * when the grant is minted — a request above it is REFUSED, never clamped, so a caller that asked for
+ * two hours learns from an error that the bound is sixty minutes rather than from an expiry it did not
+ * expect. The bound is the framework's to own because the grant is designed to leave the trust
+ * boundary: it lands in an AI agent's transcript, a model provider's logs, a shell history.
+ */
+export declare const FILE_UPLOAD_GRANT_DEFAULT_MINUTES = 15;
+export declare const FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES = 60;
+/**
+ * Which write the grant is for. A grant minted on the CREATE upload route uploads a file that a
+ * later CREATE will reference; one minted on the UPDATE route (`…/{resourceId}/files/<field>`) is
+ * bound to that row. The two routes authorize differently, so a grant may not cross from one to the
+ * other — the upload middleware checks this against the route it is presented on.
+ */
+export declare const FILE_UPLOAD_GRANT_OPERATIONS: readonly [CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE];
+export type FileUploadGrantOperation = (typeof FILE_UPLOAD_GRANT_OPERATIONS)[number];
+/** Derived from `CoreResourceOperation` — the named source — rather than a second enum spelling the same two words. */
+export declare const FileUploadGrantOperationSchema: z.ZodEnum<{
+    [K in FileUploadGrantOperation]: K;
+}>;
+/**
+ * Lifecycle of a grant as the status read reports it. Derived from the token row — `isConsumed`,
+ * `expiresAt`, `revokedAt` — never stored, so it cannot drift from the row.
+ */
+export declare enum FileUploadGrantState {
+    /** Minted, unexpired, unrevoked, not yet redeemed: an upload will be accepted. */
+    PENDING = "pending",
+    /** Redeemed by exactly one upload. `file` names what it produced when the write-back succeeded. */
+    REDEEMED = "redeemed",
+    /** Past `expiresAt` without being redeemed. Mint a new one. */
+    EXPIRED = "expired",
+    /** Revoked by the minter or an administrator before redemption. */
+    REVOKED = "revoked"
+}
+export declare const FileUploadGrantStateSchema: z.ZodEnum<typeof FileUploadGrantState>;
+/**
+ * The `metadata` a FILE_UPLOAD_GRANT token carries — the ROUTE binding, as opposed to the identity
+ * the typed token fields carry. The upload middleware reads this; the execution-context creator
+ * deliberately does not.
+ */
+export declare const FileUploadGrantMetadataSchema: z.ZodObject<{
+    fieldName: z.ZodString;
+    operation: z.ZodEnum<{
+        [K in FileUploadGrantOperation]: K;
+    }>;
+    minter: z.ZodObject<{
+        entityType: z.ZodEnum<typeof FileUploaderEntityType>;
+        id: z.ZodString;
+    }>;
+    uploadUrl: z.ZodString;
+    producedFileId: z.ZodOptional<z.ZodString>;
+}>;
+export type FileUploadGrantMetadata = z.infer<typeof FileUploadGrantMetadataSchema>;
+/**
+ * What a mint returns — identical on the REST door and the MCP tool. Two affordances for one
+ * token: `uploadCommand` for a caller that can execute, `uploadPageUrl` for one that must hand a
+ * human a link. The token appears in `uploadHeader.value` and inside both commands and the page URL;
+ * it is the credential and cannot be omitted. It never appears in any audit row.
+ */
+export declare const FileUploadGrantSchema: z.ZodObject<{
+    grantId: z.ZodString;
+    state: z.ZodEnum<typeof FileUploadGrantState>;
+    expiresAt: z.ZodString;
+    singleUse: z.ZodLiteral<true>;
+    target: z.ZodObject<{
+        resourceType: z.ZodString;
+        fieldName: z.ZodString;
+        operation: z.ZodEnum<{
+            [K in FileUploadGrantOperation]: K;
+        }>;
+        resourceId: z.ZodNullable<z.ZodString>;
+    }>;
+    constraints: z.ZodObject<{
+        maxBytes: z.ZodNumber;
+        allowedMimeTypes: z.ZodArray<z.ZodString>;
+    }>;
+    uploadUrl: z.ZodString;
+    uploadHeader: z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }>;
+    uploadCommand: z.ZodString;
+    uploadCommandPowerShell: z.ZodString;
+    uploadPageUrl: z.ZodNullable<z.ZodString>;
+    statusUrl: z.ZodString;
+    note: z.ZodString;
+}>;
+export type FileUploadGrant = z.infer<typeof FileUploadGrantSchema>;
+/**
+ * What the public status read returns. The token is the credential, so the read is unauthenticated
+ * and returns only what the drop page needs to render and the agent needs to learn the `fileId`:
+ * never the file's name (the status URL may be pasted around).
+ */
+export declare const FileUploadGrantStatusSchema: z.ZodObject<{
+    grantId: z.ZodString;
+    state: z.ZodEnum<typeof FileUploadGrantState>;
+    expiresAt: z.ZodString;
+    target: z.ZodObject<{
+        resourceType: z.ZodString;
+        fieldName: z.ZodString;
+        operation: z.ZodEnum<{
+            [K in FileUploadGrantOperation]: K;
+        }>;
+        resourceId: z.ZodNullable<z.ZodString>;
+    }>;
+    constraints: z.ZodObject<{
+        maxBytes: z.ZodNumber;
+        allowedMimeTypes: z.ZodArray<z.ZodString>;
+    }>;
+    uploadUrl: z.ZodString;
+    uploadHeaderName: z.ZodString;
+    file: z.ZodNullable<z.ZodObject<{
+        fileId: z.ZodString;
+        status: z.ZodEnum<typeof FileStatus>;
+    }>>;
+}>;
+export type FileUploadGrantStatus = z.infer<typeof FileUploadGrantStatusSchema>;
+/**
+ * Body accepted by both mint doors.
+ *
+ * The three optional file facts mirror what the MCP File Objects proposal has a client declare when
+ * it asks to upload (`name`, `mimeType`, `size`): declaring them lets the server refuse a file the
+ * field would never accept BEFORE handing out a link, instead of at redemption when the link is
+ * already spent. They are advisory for the upload itself — the bytes are validated on receipt
+ * regardless — and a declaration that later disagrees with the bytes is refused on receipt too.
+ */
+export declare const FileUploadGrantMintRequestSchema: z.ZodObject<{
+    expiresInMinutes: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodNumber>;
+}>;
+export type FileUploadGrantMintRequest = z.infer<typeof FileUploadGrantMintRequestSchema>;
+/** @wildo_source:part:end saas.models.file-upload-grant */
+//# sourceMappingURL=file-upload-grant.shared.schemas.d.ts.map

package/dist/esm/files/file-upload-grant.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload-grant.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/files/file-upload-grant.shared.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/files/file-upload-grant.shared.schemas.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+import { CoreResourceOperation } from '../resources/resources.shared.core.definitions.js';
+import { FileStatus } from './files.shared.schemas.js';
+/**
+ * File upload grant — the shared contract between the two mint doors (REST, MCP), the upload route,
+ * the status read, and the browser drop page (issue #312).
+ *
+ * A grant is a single-use consumable token. Nothing durable is created at mint but the token: an
+ * abandoned grant leaves a dead token and nothing else. The upload itself goes through the resource's
+ * EXISTING file-upload route, authenticated by the grant alone, and the ordinary authorizer decides.
+ */
+/**
+ * Public frontend route the browser drop page lives on; the token follows as the next path segment
+ * (`/upload-grant/<token>`). Declared HERE so the backend (which builds `uploadPageUrl`) and the
+ * frontend (which mounts the route) read one source — the backend cannot import frontend route
+ * constants.
+ */
+export const FILE_UPLOAD_GRANT_PAGE_PATH = '/upload-grant';
+/** @wildo_source:part:start saas.models.file-upload-grant facet:layer:shared facet:family:files
+ *
+ * Lifetime bounds of an upload grant, in minutes. The ceiling is fixed by the framework and enforced
+ * when the grant is minted — a request above it is REFUSED, never clamped, so a caller that asked for
+ * two hours learns from an error that the bound is sixty minutes rather than from an expiry it did not
+ * expect. The bound is the framework's to own because the grant is designed to leave the trust
+ * boundary: it lands in an AI agent's transcript, a model provider's logs, a shell history.
+ */
+export const FILE_UPLOAD_GRANT_DEFAULT_MINUTES = 15;
+export const FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES = 60;
+/**
+ * Which write the grant is for. A grant minted on the CREATE upload route uploads a file that a
+ * later CREATE will reference; one minted on the UPDATE route (`…/{resourceId}/files/<field>`) is
+ * bound to that row. The two routes authorize differently, so a grant may not cross from one to the
+ * other — the upload middleware checks this against the route it is presented on.
+ */
+export const FILE_UPLOAD_GRANT_OPERATIONS = [CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE];
+/** Derived from `CoreResourceOperation` — the named source — rather than a second enum spelling the same two words. */
+export const FileUploadGrantOperationSchema = z.enum(FILE_UPLOAD_GRANT_OPERATIONS);
+/**
+ * Lifecycle of a grant as the status read reports it. Derived from the token row — `isConsumed`,
+ * `expiresAt`, `revokedAt` — never stored, so it cannot drift from the row.
+ */
+export var FileUploadGrantState;
+(function (FileUploadGrantState) {
+    /** Minted, unexpired, unrevoked, not yet redeemed: an upload will be accepted. */
+    FileUploadGrantState["PENDING"] = "pending";
+    /** Redeemed by exactly one upload. `file` names what it produced when the write-back succeeded. */
+    FileUploadGrantState["REDEEMED"] = "redeemed";
+    /** Past `expiresAt` without being redeemed. Mint a new one. */
+    FileUploadGrantState["EXPIRED"] = "expired";
+    /** Revoked by the minter or an administrator before redemption. */
+    FileUploadGrantState["REVOKED"] = "revoked";
+})(FileUploadGrantState || (FileUploadGrantState = {}));
+export const FileUploadGrantStateSchema = z.enum(FileUploadGrantState);
+/**
+ * The `metadata` a FILE_UPLOAD_GRANT token carries — the ROUTE binding, as opposed to the identity
+ * the typed token fields carry. The upload middleware reads this; the execution-context creator
+ * deliberately does not.
+ */
+export const FileUploadGrantMetadataSchema = z.object({
+    /** The `z_file()` field the upload lands on, as authored (dotted for nested fields). */
+    fieldName: z.string().min(1),
+    operation: FileUploadGrantOperationSchema,
+    /**
+     * Who minted — recorded so the uploaded file is attributed to a PERSON or MACHINE, not to the
+     * grant.
+     *
+     * `entityType` is the ENUM, not a string. It was `z.string().min(1)` until 2026-09-08, with the
+     * stated reason that "the uploader enum lives in `zod-decorators`, upstream of this package" —
+     * which is exactly backwards: upstream is what a package MAY import, and this one already does.
+     * `files.shared.schemas.ts` in this very directory imports `FileUploaderEntityType` from
+     * `@wildo-ai/zod-decorators`, re-exports it, and writes `z.enum(FileUploaderEntityType)` on the
+     * FILES row's own `uploadedByEntityType`. So the vocabulary was one import away the whole time and
+     * the metadata's copy of the same field was the only one left open.
+     *
+     * What the enum buys: `metadata` is an UNTYPED bag on the token row, so nothing between the write
+     * and the read guarantees its shape — the read is the only place that can. Every reader here goes
+     * through `FileUploadGrantMetadataSchema.safeParse`, so an out-of-vocabulary entity type now makes
+     * the whole metadata unparseable and the redemption path refuses the grant instead of casting the
+     * value into `FileUploaderPrincipal` and carrying it three layers to `validateUploadedByEntityType`.
+     *
+     * NOT narrowed to the three values `mint` can actually produce (mint refuses an anonymous and a
+     * token-borne minter, so `ANONYMOUS_USER` is unreachable): that refusal is a MINT policy, enforced
+     * and explained at mint, and re-encoding it here would put half a policy in a schema that cannot
+     * say why. The vocabulary of this field is the vocabulary of the principal it names.
+     */
+    minter: z.object({ entityType: z.enum(FileUploaderEntityType), id: z.string().min(1) }),
+    /**
+     * The concrete upload URL the grant was minted for. Two jobs, and the second one is why it must be
+     * absolute: the status read hands it to the drop page, AND the redemption path compares its PATH
+     * against the route the token is presented on (`assertGrantMatchesRoute`). Until 2026-09-08 it was
+     * recorded and never read back, so a grant bound to one concrete route could be redeemed on any
+     * other route reaching the same (resource, field, operation, row).
+     */
+    uploadUrl: z.string().url(),
+    /** Written after a successful redemption; absent until then. */
+    producedFileId: z.string().min(1).optional(),
+});
+/**
+ * What a mint returns — identical on the REST door and the MCP tool. Two affordances for one
+ * token: `uploadCommand` for a caller that can execute, `uploadPageUrl` for one that must hand a
+ * human a link. The token appears in `uploadHeader.value` and inside both commands and the page URL;
+ * it is the credential and cannot be omitted. It never appears in any audit row.
+ */
+export const FileUploadGrantSchema = z.object({
+    grantId: z.string().min(1),
+    state: FileUploadGrantStateSchema,
+    expiresAt: z.string().datetime(),
+    singleUse: z.literal(true),
+    target: z.object({
+        resourceType: z.string().min(1),
+        fieldName: z.string().min(1),
+        operation: FileUploadGrantOperationSchema,
+        resourceId: z.string().min(1).nullable(),
+    }),
+    /** From the field's own constraint resolver — the same one the upload enforces, so the two cannot disagree. */
+    constraints: z.object({
+        maxBytes: z.number().int().positive(),
+        /** Empty means every type is accepted. */
+        allowedMimeTypes: z.array(z.string()),
+    }),
+    uploadUrl: z.string().url(),
+    /** The credential travels in a HEADER on the curl form: paths are logged by every proxy, headers are not. */
+    uploadHeader: z.object({ name: z.string().min(1), value: z.string().min(1) }),
+    /** No `-f`: on a refusal the JSON error body is the only thing that tells the caller why. */
+    uploadCommand: z.string().min(1),
+    /** In PowerShell `curl` aliases Invoke-WebRequest, which does not understand `-F`; the real binary is `curl.exe`. */
+    uploadCommandPowerShell: z.string().min(1),
+    /** `null` when the application declares no frontend service — a headless API has no page to hand a human. */
+    uploadPageUrl: z.string().url().nullable(),
+    statusUrl: z.string().url(),
+    note: z.string().min(1),
+});
+/**
+ * What the public status read returns. The token is the credential, so the read is unauthenticated
+ * and returns only what the drop page needs to render and the agent needs to learn the `fileId`:
+ * never the file's name (the status URL may be pasted around).
+ */
+export const FileUploadGrantStatusSchema = z.object({
+    grantId: z.string().min(1),
+    state: FileUploadGrantStateSchema,
+    expiresAt: z.string().datetime(),
+    target: z.object({
+        resourceType: z.string().min(1),
+        fieldName: z.string().min(1),
+        operation: FileUploadGrantOperationSchema,
+        resourceId: z.string().min(1).nullable(),
+    }),
+    constraints: z.object({ maxBytes: z.number().int().positive(), allowedMimeTypes: z.array(z.string()) }),
+    uploadUrl: z.string().url(),
+    /** The page sets this header itself; the token it already holds is the value. */
+    uploadHeaderName: z.string().min(1),
+    /** `null` until redeemed, or when the post-redemption write-back failed (re-read the resource instead). */
+    file: z.object({ fileId: z.string().min(1), status: z.enum(FileStatus) }).nullable(),
+});
+/**
+ * Body accepted by both mint doors.
+ *
+ * The three optional file facts mirror what the MCP File Objects proposal has a client declare when
+ * it asks to upload (`name`, `mimeType`, `size`): declaring them lets the server refuse a file the
+ * field would never accept BEFORE handing out a link, instead of at redemption when the link is
+ * already spent. They are advisory for the upload itself — the bytes are validated on receipt
+ * regardless — and a declaration that later disagrees with the bytes is refused on receipt too.
+ */
+export const FileUploadGrantMintRequestSchema = z.object({
+    expiresInMinutes: z.number().int().min(1).max(FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES).optional(),
+    /** The file name the caller intends to upload; used for the curl example and checked against nothing else. */
+    name: z.string().min(1).max(255).optional(),
+    /** Declared MIME type; refused at mint when the field does not accept it. */
+    mimeType: z.string().min(1).max(255).optional(),
+    /** Declared size in bytes; refused at mint when above the field's maximum. */
+    size: z.number().int().positive().optional(),
+}).strict();
+/** @wildo_source:part:end saas.models.file-upload-grant */
+//# sourceMappingURL=file-upload-grant.shared.schemas.js.map

package/dist/esm/files/file-upload-grant.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload-grant.shared.schemas.js","sourceRoot":"","sources":["../../../../src/files/file-upload-grant.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { FileUploaderEntityType } from '@wildo-ai/zod-decorators';\nimport { CoreResourceOperation } from '../resources/resources.shared.core.definitions';\nimport { FileStatus } from './files.shared.schemas';\n\n/**\n * File upload grant — the shared contract between the two mint doors (REST, MCP), the upload route,\n * the status read, and the browser drop page (issue #312).\n *\n * A grant is a single-use consumable token. Nothing durable is created at mint but the token: an\n * abandoned grant leaves a dead token and nothing else. The upload itself goes through the resource's\n * EXISTING file-upload route, authenticated by the grant alone, and the ordinary authorizer decides.\n */\n\n/**\n * Public frontend route the browser drop page lives on; the token follows as the next path segment\n * (`/upload-grant/<token>`). Declared HERE so the backend (which builds `uploadPageUrl`) and the\n * frontend (which mounts the route) read one source — the backend cannot import frontend route\n * constants.\n */\nexport const FILE_UPLOAD_GRANT_PAGE_PATH = '/upload-grant';\n\n/** @wildo_source:part:start saas.models.file-upload-grant facet:layer:shared facet:family:files\n *\n * Lifetime bounds of an upload grant, in minutes. The ceiling is fixed by the framework and enforced\n * when the grant is minted — a request above it is REFUSED, never clamped, so a caller that asked for\n * two hours learns from an error that the bound is sixty minutes rather than from an expiry it did not\n * expect. The bound is the framework's to own because the grant is designed to leave the trust\n * boundary: it lands in an AI agent's transcript, a model provider's logs, a shell history.\n */\nexport const FILE_UPLOAD_GRANT_DEFAULT_MINUTES = 15;\nexport const FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES = 60;\n\n/**\n * Which write the grant is for. A grant minted on the CREATE upload route uploads a file that a\n * later CREATE will reference; one minted on the UPDATE route (`…/{resourceId}/files/<field>`) is\n * bound to that row. The two routes authorize differently, so a grant may not cross from one to the\n * other — the upload middleware checks this against the route it is presented on.\n */\nexport const FILE_UPLOAD_GRANT_OPERATIONS = [CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE] as const;\nexport type FileUploadGrantOperation = (typeof FILE_UPLOAD_GRANT_OPERATIONS)[number];\n/** Derived from `CoreResourceOperation` — the named source — rather than a second enum spelling the same two words. */\nexport const FileUploadGrantOperationSchema: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }> = z.enum(FILE_UPLOAD_GRANT_OPERATIONS);\n\n/**\n * Lifecycle of a grant as the status read reports it. Derived from the token row — `isConsumed`,\n * `expiresAt`, `revokedAt` — never stored, so it cannot drift from the row.\n */\nexport enum FileUploadGrantState {\n  /** Minted, unexpired, unrevoked, not yet redeemed: an upload will be accepted. */\n  PENDING = 'pending',\n  /** Redeemed by exactly one upload. `file` names what it produced when the write-back succeeded. */\n  REDEEMED = 'redeemed',\n  /** Past `expiresAt` without being redeemed. Mint a new one. */\n  EXPIRED = 'expired',\n  /** Revoked by the minter or an administrator before redemption. */\n  REVOKED = 'revoked',\n}\nexport const FileUploadGrantStateSchema: z.ZodEnum<typeof FileUploadGrantState> = z.enum(FileUploadGrantState);\n\n/**\n * The `metadata` a FILE_UPLOAD_GRANT token carries — the ROUTE binding, as opposed to the identity\n * the typed token fields carry. The upload middleware reads this; the execution-context creator\n * deliberately does not.\n */\nexport const FileUploadGrantMetadataSchema: z.ZodObject<{\n  fieldName: z.ZodString;\n  operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;\n  minter: z.ZodObject<{ entityType: z.ZodEnum<typeof FileUploaderEntityType>; id: z.ZodString }>;\n  uploadUrl: z.ZodString;\n  producedFileId: z.ZodOptional<z.ZodString>;\n}> = z.object({\n  /** The `z_file()` field the upload lands on, as authored (dotted for nested fields). */\n  fieldName: z.string().min(1),\n  operation: FileUploadGrantOperationSchema,\n  /**\n   * Who minted — recorded so the uploaded file is attributed to a PERSON or MACHINE, not to the\n   * grant.\n   *\n   * `entityType` is the ENUM, not a string. It was `z.string().min(1)` until 2026-09-08, with the\n   * stated reason that \"the uploader enum lives in `zod-decorators`, upstream of this package\" —\n   * which is exactly backwards: upstream is what a package MAY import, and this one already does.\n   * `files.shared.schemas.ts` in this very directory imports `FileUploaderEntityType` from\n   * `@wildo-ai/zod-decorators`, re-exports it, and writes `z.enum(FileUploaderEntityType)` on the\n   * FILES row's own `uploadedByEntityType`. So the vocabulary was one import away the whole time and\n   * the metadata's copy of the same field was the only one left open.\n   *\n   * What the enum buys: `metadata` is an UNTYPED bag on the token row, so nothing between the write\n   * and the read guarantees its shape — the read is the only place that can. Every reader here goes\n   * through `FileUploadGrantMetadataSchema.safeParse`, so an out-of-vocabulary entity type now makes\n   * the whole metadata unparseable and the redemption path refuses the grant instead of casting the\n   * value into `FileUploaderPrincipal` and carrying it three layers to `validateUploadedByEntityType`.\n   *\n   * NOT narrowed to the three values `mint` can actually produce (mint refuses an anonymous and a\n   * token-borne minter, so `ANONYMOUS_USER` is unreachable): that refusal is a MINT policy, enforced\n   * and explained at mint, and re-encoding it here would put half a policy in a schema that cannot\n   * say why. The vocabulary of this field is the vocabulary of the principal it names.\n   */\n  minter: z.object({ entityType: z.enum(FileUploaderEntityType), id: z.string().min(1) }),\n  /**\n   * The concrete upload URL the grant was minted for. Two jobs, and the second one is why it must be\n   * absolute: the status read hands it to the drop page, AND the redemption path compares its PATH\n   * against the route the token is presented on (`assertGrantMatchesRoute`). Until 2026-09-08 it was\n   * recorded and never read back, so a grant bound to one concrete route could be redeemed on any\n   * other route reaching the same (resource, field, operation, row).\n   */\n  uploadUrl: z.string().url(),\n  /** Written after a successful redemption; absent until then. */\n  producedFileId: z.string().min(1).optional(),\n});\nexport type FileUploadGrantMetadata = z.infer<typeof FileUploadGrantMetadataSchema>;\n\n/**\n * What a mint returns — identical on the REST door and the MCP tool. Two affordances for one\n * token: `uploadCommand` for a caller that can execute, `uploadPageUrl` for one that must hand a\n * human a link. The token appears in `uploadHeader.value` and inside both commands and the page URL;\n * it is the credential and cannot be omitted. It never appears in any audit row.\n */\nexport const FileUploadGrantSchema: z.ZodObject<{\n  grantId: z.ZodString;\n  state: z.ZodEnum<typeof FileUploadGrantState>;\n  expiresAt: z.ZodString;\n  singleUse: z.ZodLiteral<true>;\n  target: z.ZodObject<{\n    resourceType: z.ZodString;\n    fieldName: z.ZodString;\n    operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;\n    resourceId: z.ZodNullable<z.ZodString>;\n  }>;\n  constraints: z.ZodObject<{\n    maxBytes: z.ZodNumber;\n    allowedMimeTypes: z.ZodArray<z.ZodString>;\n  }>;\n  uploadUrl: z.ZodString;\n  uploadHeader: z.ZodObject<{ name: z.ZodString; value: z.ZodString }>;\n  uploadCommand: z.ZodString;\n  uploadCommandPowerShell: z.ZodString;\n  uploadPageUrl: z.ZodNullable<z.ZodString>;\n  statusUrl: z.ZodString;\n  note: z.ZodString;\n}> = z.object({\n  grantId: z.string().min(1),\n  state: FileUploadGrantStateSchema,\n  expiresAt: z.string().datetime(),\n  singleUse: z.literal(true),\n  target: z.object({\n    resourceType: z.string().min(1),\n    fieldName: z.string().min(1),\n    operation: FileUploadGrantOperationSchema,\n    resourceId: z.string().min(1).nullable(),\n  }),\n  /** From the field's own constraint resolver — the same one the upload enforces, so the two cannot disagree. */\n  constraints: z.object({\n    maxBytes: z.number().int().positive(),\n    /** Empty means every type is accepted. */\n    allowedMimeTypes: z.array(z.string()),\n  }),\n  uploadUrl: z.string().url(),\n  /** The credential travels in a HEADER on the curl form: paths are logged by every proxy, headers are not. */\n  uploadHeader: z.object({ name: z.string().min(1), value: z.string().min(1) }),\n  /** No `-f`: on a refusal the JSON error body is the only thing that tells the caller why. */\n  uploadCommand: z.string().min(1),\n  /** In PowerShell `curl` aliases Invoke-WebRequest, which does not understand `-F`; the real binary is `curl.exe`. */\n  uploadCommandPowerShell: z.string().min(1),\n  /** `null` when the application declares no frontend service — a headless API has no page to hand a human. */\n  uploadPageUrl: z.string().url().nullable(),\n  statusUrl: z.string().url(),\n  note: z.string().min(1),\n});\nexport type FileUploadGrant = z.infer<typeof FileUploadGrantSchema>;\n\n/**\n * What the public status read returns. The token is the credential, so the read is unauthenticated\n * and returns only what the drop page needs to render and the agent needs to learn the `fileId`:\n * never the file's name (the status URL may be pasted around).\n */\nexport const FileUploadGrantStatusSchema: z.ZodObject<{\n  grantId: z.ZodString;\n  state: z.ZodEnum<typeof FileUploadGrantState>;\n  expiresAt: z.ZodString;\n  target: z.ZodObject<{\n    resourceType: z.ZodString;\n    fieldName: z.ZodString;\n    operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;\n    resourceId: z.ZodNullable<z.ZodString>;\n  }>;\n  constraints: z.ZodObject<{ maxBytes: z.ZodNumber; allowedMimeTypes: z.ZodArray<z.ZodString> }>;\n  uploadUrl: z.ZodString;\n  uploadHeaderName: z.ZodString;\n  file: z.ZodNullable<z.ZodObject<{ fileId: z.ZodString; status: z.ZodEnum<typeof FileStatus> }>>;\n}> = z.object({\n  grantId: z.string().min(1),\n  state: FileUploadGrantStateSchema,\n  expiresAt: z.string().datetime(),\n  target: z.object({\n    resourceType: z.string().min(1),\n    fieldName: z.string().min(1),\n    operation: FileUploadGrantOperationSchema,\n    resourceId: z.string().min(1).nullable(),\n  }),\n  constraints: z.object({ maxBytes: z.number().int().positive(), allowedMimeTypes: z.array(z.string()) }),\n  uploadUrl: z.string().url(),\n  /** The page sets this header itself; the token it already holds is the value. */\n  uploadHeaderName: z.string().min(1),\n  /** `null` until redeemed, or when the post-redemption write-back failed (re-read the resource instead). */\n  file: z.object({ fileId: z.string().min(1), status: z.enum(FileStatus) }).nullable(),\n});\nexport type FileUploadGrantStatus = z.infer<typeof FileUploadGrantStatusSchema>;\n\n/**\n * Body accepted by both mint doors.\n *\n * The three optional file facts mirror what the MCP File Objects proposal has a client declare when\n * it asks to upload (`name`, `mimeType`, `size`): declaring them lets the server refuse a file the\n * field would never accept BEFORE handing out a link, instead of at redemption when the link is\n * already spent. They are advisory for the upload itself — the bytes are validated on receipt\n * regardless — and a declaration that later disagrees with the bytes is refused on receipt too.\n */\nexport const FileUploadGrantMintRequestSchema: z.ZodObject<{\n  expiresInMinutes: z.ZodOptional<z.ZodNumber>;\n  name: z.ZodOptional<z.ZodString>;\n  mimeType: z.ZodOptional<z.ZodString>;\n  size: z.ZodOptional<z.ZodNumber>;\n}> = z.object({\n  expiresInMinutes: z.number().int().min(1).max(FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES).optional(),\n  /** The file name the caller intends to upload; used for the curl example and checked against nothing else. */\n  name: z.string().min(1).max(255).optional(),\n  /** Declared MIME type; refused at mint when the field does not accept it. */\n  mimeType: z.string().min(1).max(255).optional(),\n  /** Declared size in bytes; refused at mint when above the field's maximum. */\n  size: z.number().int().positive().optional(),\n}).strict();\nexport type FileUploadGrantMintRequest = z.infer<typeof FileUploadGrantMintRequestSchema>;\n/** @wildo_source:part:end saas.models.file-upload-grant */\n"]}