@wildo-ai/saas-models 1.1.2 → 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/files/file-upload-grant.shared.schemas.d.ts

@@ -1,4 +1,5 @@
 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';
 /**
@@ -64,7 +65,7 @@ export declare const FileUploadGrantMetadataSchema: z.ZodObject<{
         [K in FileUploadGrantOperation]: K;
     }>;
     minter: z.ZodObject<{
-        entityType: z.ZodString;
+        entityType: z.ZodEnum<typeof FileUploaderEntityType>;
         id: z.ZodString;
     }>;
     uploadUrl: z.ZodString;
@@ -135,9 +136,20 @@ export declare const FileUploadGrantStatusSchema: z.ZodObject<{
     }>>;
 }>;
 export type FileUploadGrantStatus = z.infer<typeof FileUploadGrantStatusSchema>;
-/** Body accepted by both mint doors. */
+/**
+ * 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 */

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

@@ -1 +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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"}
+{"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

@@ -1,4 +1,5 @@
 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';
 /**
@@ -62,11 +63,35 @@ export const FileUploadGrantMetadataSchema = z.object({
     operation: FileUploadGrantOperationSchema,
     /**
      * Who minted — recorded so the uploaded file is attributed to a PERSON or MACHINE, not to the
-     * grant. `entityType` is a `FileUploaderEntityType` value; kept as a string here because the
-     * uploader enum lives in `zod-decorators`, upstream of this package.
+     * 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).
      */
-    minter: z.object({ entityType: z.string().min(1), id: z.string().min(1) }),
-    /** The concrete upload URL the grant was minted for — recorded so the status read can hand it to the drop page. */
     uploadUrl: z.string().url(),
     /** Written after a successful redemption; absent until then. */
     producedFileId: z.string().min(1).optional(),
@@ -128,9 +153,23 @@ export const FileUploadGrantStatusSchema = z.object({
     /** `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. */
+/**
+ * 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

@@ -1 +1 @@
-{"version":3,"file":"file-upload-grant.shared.schemas.js","sourceRoot":"","sources":["../../../../src/files/file-upload-grant.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AACpD,MAAM,CAAC,MAAM,sCAAsC,GAAG,EAAE,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,CAAC,MAAM,CAAU,CAAC;AAElH,uHAAuH;AACvH,MAAM,CAAC,MAAM,8BAA8B,GAAsD,CAAC,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;AAEtI;;;GAGG;AACH,MAAM,CAAN,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC9B,kFAAkF;IAClF,2CAAmB,CAAA;IACnB,mGAAmG;IACnG,6CAAqB,CAAA;IACrB,+DAA+D;IAC/D,2CAAmB,CAAA;IACnB,mEAAmE;IACnE,2CAAmB,CAAA;AACrB,CAAC,EATW,oBAAoB,KAApB,oBAAoB,QAS/B;AACD,MAAM,CAAC,MAAM,0BAA0B,GAA2C,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;AAE/G;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAMrC,CAAC,CAAC,MAAM,CAAC;IACZ,wFAAwF;IACxF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,SAAS,EAAE,8BAA8B;IACzC;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,mHAAmH;IACnH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,gEAAgE;IAChE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAsB7B,CAAC,CAAC,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,KAAK,EAAE,0BAA0B;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,SAAS,EAAE,8BAA8B;QACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;KACzC,CAAC;IACF,+GAA+G;IAC/G,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;QACrC,0CAA0C;QAC1C,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KACtC,CAAC;IACF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,6GAA6G;IAC7G,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,6FAA6F;IAC7F,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,qHAAqH;IACrH,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,6GAA6G;IAC7G,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAC1C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAcnC,CAAC,CAAC,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,KAAK,EAAE,0BAA0B;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,SAAS,EAAE,8BAA8B;QACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;KACzC,CAAC;IACF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;IACvG,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,iFAAiF;IACjF,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,2GAA2G;IAC3G,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;CACrF,CAAC,CAAC;AAGH,wCAAwC;AACxC,MAAM,CAAC,MAAM,gCAAgC,GAAkE,CAAC,CAAC,MAAM,CAAC;IACtH,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC,QAAQ,EAAE;CACjG,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,2DAA2D","sourcesContent":["import { z } from 'zod';\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.ZodString; 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. `entityType` is a `FileUploaderEntityType` value; kept as a string here because the\n   * uploader enum lives in `zod-decorators`, upstream of this package.\n   */\n  minter: z.object({ entityType: z.string().min(1), id: z.string().min(1) }),\n  /** The concrete upload URL the grant was minted for — recorded so the status read can hand it to the drop page. */\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/** Body accepted by both mint doors. */\nexport const FileUploadGrantMintRequestSchema: z.ZodObject<{ expiresInMinutes: z.ZodOptional<z.ZodNumber> }> = z.object({\n  expiresInMinutes: z.number().int().min(1).max(FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES).optional(),\n}).strict();\nexport type FileUploadGrantMintRequest = z.infer<typeof FileUploadGrantMintRequestSchema>;\n/** @wildo_source:part:end saas.models.file-upload-grant */\n"]}
+{"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"]}

package/dist/esm/files/files.shared.schemas.d.ts

@@ -83,14 +83,21 @@ export declare function parseFileServeVariant(raw: unknown): FileServeVariant;
  * to CLEAN / INFECTED / QUARANTINED. `SCANNING`, `INFECTED` and `QUARANTINED` are absent from this
  * set and therefore blocked, which is the post-scan half of the original Wave 1 note.
  *
- * ⚠️ `UPLOADED` is still admitted, and that is the OPEN question this comment used to hide behind
- * "scanning is not enforced yet". Two reasons it is not simply a leftover, and neither is settled:
- * scanning is opt-in per field (`shouldScan` reads the field's `fileMetadata`), so an unscanned
- * file legitimately terminates at UPLOADED and removing it from this set would make every such
- * field undownloadable; and `initiateScan` is fired without being awaited, so even for a scanned
- * field there is a window between the upload committing and the status reaching SCANNING in which
- * the bytes are servable. Closing that window is a behaviour change with its own decision — see
- * the tracker — not something to infer from this comment.
+ * `UPLOADED` IS admitted, and that is correct rather than a leftover — but only because of where
+ * the scan gate now sits. Scanning is opt-in per field (`shouldScan` reads the field's
+ * `fileMetadata`), so an unscanned file legitimately terminates at UPLOADED and removing it from
+ * this set would make every such field undownloadable.
+ *
+ * The window that used to sit behind that reasoning is CLOSED (#433, 2026-09-08). A file whose
+ * field requires a scan never sits at UPLOADED at all: `resource-file-upload-handler` now AWAITS
+ * `initiateScan` — which awaits the UPLOADED -> SCANNING transition and only then fires the scan
+ * pipeline — BEFORE the upload response is sent. Previously it was fired afterwards without being
+ * awaited, so the bytes were servable for the gap between the upload committing and the transition
+ * landing.
+ *
+ * So the invariant this set relies on is external to it: **a required scan reaches SCANNING before
+ * anyone learns the upload succeeded.** Do not restore a fire-and-forget scan initiation, and do
+ * not add UPLOADED-adjacent statuses here without asking which side of that gate they fall on.
  */
 export declare const FILE_DOWNLOADABLE_STATUSES: ReadonlySet<FileStatus>;
 /**

package/dist/esm/files/files.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/files/files.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtI,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAG7E,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACvF,YAAY,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,oBAAY,UAAU;IACpB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;IAEjB,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,WAAW,gBAAgB;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,oBAAY,gBAAgB;IAC1B,QAAQ,aAAa;IACrB,SAAS,cAAc;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAIpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,UAAU,CAK7D,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,UAAU,CAElE,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,aAAa,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,UAAU,CAOxD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAWvF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,UAAU,CAGzD,CAAC;AAGH,eAAO,MAAM,mBAAmB,iHAItB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAyBpE,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAqBV;AAuGD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,GAAG,qBAAqB,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"files.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/files/files.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtI,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAG7E,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACvF,YAAY,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,oBAAY,UAAU;IACpB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;IAEjB,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,WAAW,gBAAgB;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,oBAAY,gBAAgB;IAC1B,QAAQ,aAAa;IACrB,SAAS,cAAc;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAIpE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,UAAU,CAK7D,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,UAAU,CAElE,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,aAAa,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,UAAU,CAOxD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAWvF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,UAAU,CAGzD,CAAC;AAGH,eAAO,MAAM,mBAAmB,iHAItB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAyBpE,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAqBV;AAuGD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,GAAG,qBAAqB,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/esm/files/files.shared.schemas.js

@@ -88,14 +88,21 @@ export function parseFileServeVariant(raw) {
  * to CLEAN / INFECTED / QUARANTINED. `SCANNING`, `INFECTED` and `QUARANTINED` are absent from this
  * set and therefore blocked, which is the post-scan half of the original Wave 1 note.
  *
- * ⚠️ `UPLOADED` is still admitted, and that is the OPEN question this comment used to hide behind
- * "scanning is not enforced yet". Two reasons it is not simply a leftover, and neither is settled:
- * scanning is opt-in per field (`shouldScan` reads the field's `fileMetadata`), so an unscanned
- * file legitimately terminates at UPLOADED and removing it from this set would make every such
- * field undownloadable; and `initiateScan` is fired without being awaited, so even for a scanned
- * field there is a window between the upload committing and the status reaching SCANNING in which
- * the bytes are servable. Closing that window is a behaviour change with its own decision — see
- * the tracker — not something to infer from this comment.
+ * `UPLOADED` IS admitted, and that is correct rather than a leftover — but only because of where
+ * the scan gate now sits. Scanning is opt-in per field (`shouldScan` reads the field's
+ * `fileMetadata`), so an unscanned file legitimately terminates at UPLOADED and removing it from
+ * this set would make every such field undownloadable.
+ *
+ * The window that used to sit behind that reasoning is CLOSED (#433, 2026-09-08). A file whose
+ * field requires a scan never sits at UPLOADED at all: `resource-file-upload-handler` now AWAITS
+ * `initiateScan` — which awaits the UPLOADED -> SCANNING transition and only then fires the scan
+ * pipeline — BEFORE the upload response is sent. Previously it was fired afterwards without being
+ * awaited, so the bytes were servable for the gap between the upload committing and the transition
+ * landing.
+ *
+ * So the invariant this set relies on is external to it: **a required scan reaches SCANNING before
+ * anyone learns the upload succeeded.** Do not restore a fire-and-forget scan initiation, and do
+ * not add UPLOADED-adjacent statuses here without asking which side of that gate they fall on.
  */
 export const FILE_DOWNLOADABLE_STATUSES = new Set([
     FileStatus.UPLOADED,

package/dist/esm/files/files.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.shared.schemas.js","sourceRoot":"","sources":["../../../../src/files/files.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Files Shared Schemas\n *\n * Reusable schemas for file uploads and file handling.\n *\n * ## Scope Model\n *\n * Files use a **segregated scope model** where scope identifiers are separate fields\n * (not hierarchical). A file belongs to exactly one primary scope:\n * - APPLICATION: App-level shared files (e.g., branding assets)\n * - ORGANIZATIONS: Org-scoped files (e.g., org documents)\n * - USER_SELF: User-private files owned by a single user (NO org — USER_SELF and\n *   ORGANIZATIONS are independent primary-scope axes; `applicationId` is the bucket anchor)\n *\n * `ANONYMOUS` is intentionally excluded from the file contract for now. The\n * file layer does not yet define anonymous upload, storage, and access semantics\n * end to end, so file resources fail closed instead of pretending support.\n *\n * Scope is **derived from the parent resource's resourcePrimaryScope** when linking.\n * Access rights are **inherited from the z_file() field** on the parent resource.\n *\n * Note: FileMetadata is defined in @wildo-ai/zod-decorators\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { FileDisplayNature, FileStorageAccepted, FileUploaderEntityType, type FileUploaderOwnership } from '@wildo-ai/zod-decorators';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\n\n// Re-export FileMetadata from zod-decorators for convenience\nexport type { FileMetadata } from '@wildo-ai/zod-decorators';\nexport { FileUploaderEntityType, FileStorageAccepted } from '@wildo-ai/zod-decorators';\nexport type { FileUploaderOwnership } from '@wildo-ai/zod-decorators';\n\n/**\n * File status lifecycle enum\n *\n * NOTE — no extraction/indexing members. `EXTRACTING` / `EXTRACTED` / `INDEXED` were removed\n * 2026-08-26 with the resource-native RAG reshape (plan `resource-rag-capability`, Phase 1):\n * text extraction and embedding state are per-FIELD, per-CHUNK facts, and the RAG chunk rows\n * (Phase 2's derived-data tier, keyed `(resourceType, resourceId, fieldName, chunkIndex)` with a\n * NULLABLE `vector` as the \"needs embedding\" ledger) carry them. A single file-level status could\n * never say WHICH field's corpus was current — it was the wrong shape, not merely unused — and\n * `INDEXED` had already shipped one false claim (written to mean \"text was copied\", read as\n * \"searchable\": https://github.com/wildo-ai/wildo-ai/issues/46). The file lifecycle now ends at\n * upload/scan/link/erasure concerns, which really are per-file.\n */\nexport enum FileStatus {\n  PENDING = 'pending',\n  UPLOADED = 'uploaded',\n  LINKED = 'linked',\n  DELETED = 'deleted',\n  ORPHANED = 'orphaned',\n  FAILED = 'failed',\n\n  SCANNING = 'scanning',\n  CLEAN = 'clean',\n  INFECTED = 'infected',\n  QUARANTINED = 'quarantined',\n}\n\n/**\n * Rendition of a file's bytes requested from the serve route via `?variant=`.\n *\n * - `ORIGINAL` — the stored bytes, unchanged (the default when the param is absent).\n * - `THUMBNAIL` — a small, downscaled `webp` derived on the fly for preview surfaces\n *   (nav avatar, list/card image) so a preview never pulls a multi-MB original. Only\n *   raster images are eligible; for any other file the serve route transparently\n *   falls back to the original bytes.\n *\n * This is the WIRE CONTRACT for the serve route's `variant` query parameter — shared\n * by the frontend (which builds `?variant=thumbnail` preview URLs) and the backend\n * serve route (which parses it). Keep the string values stable across releases.\n */\nexport enum FileServeVariant {\n  ORIGINAL = 'original',\n  THUMBNAIL = 'thumbnail',\n}\n\n/**\n * Parse an untrusted `?variant=` query value into a {@link FileServeVariant}.\n * Absent or unrecognized values fall back to `ORIGINAL` (fail-safe: an unknown\n * variant serves the untransformed bytes rather than erroring).\n */\nexport function parseFileServeVariant(raw: unknown): FileServeVariant {\n  return raw === FileServeVariant.THUMBNAIL\n    ? FileServeVariant.THUMBNAIL\n    : FileServeVariant.ORIGINAL;\n}\n\n/**\n * Statuses in which a file's bytes are safe to serve for download.\n *\n * AV scanning IS wired: `FileScanningBackendService` is bound in the container and the resource\n * upload handler calls `shouldScan` then `initiateScan`, so a scanned file moves through SCANNING\n * to CLEAN / INFECTED / QUARANTINED. `SCANNING`, `INFECTED` and `QUARANTINED` are absent from this\n * set and therefore blocked, which is the post-scan half of the original Wave 1 note.\n *\n * ⚠️ `UPLOADED` is still admitted, and that is the OPEN question this comment used to hide behind\n * \"scanning is not enforced yet\". Two reasons it is not simply a leftover, and neither is settled:\n * scanning is opt-in per field (`shouldScan` reads the field's `fileMetadata`), so an unscanned\n * file legitimately terminates at UPLOADED and removing it from this set would make every such\n * field undownloadable; and `initiateScan` is fired without being awaited, so even for a scanned\n * field there is a window between the upload committing and the status reaching SCANNING in which\n * the bytes are servable. Closing that window is a behaviour change with its own decision — see\n * the tracker — not something to infer from this comment.\n */\nexport const FILE_DOWNLOADABLE_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.UPLOADED,\n  FileStatus.LINKED,\n  FileStatus.ORPHANED,\n  FileStatus.CLEAN,\n]);\n\n/**\n * Statuses in which a file's own METADATA must no longer be disclosed on the GLOBAL\n * `GET /files/:fileId/metadata` route (gate **G-FILE**).\n *\n * Blocking the BYTES is not enough. A privacy erasure marks the file `DELETED`, but physical cleanup\n * is a batch that runs much later — so between the two, `originalFilename` (`passport-jane-doe.pdf`)\n * and `uploadedBy` stayed readable by any member of the file's scope. \"Erased\" that leaves the\n * filename readable for weeks is not erased.\n *\n * DELIBERATELY NARROWER than {@link FILE_BLOCKED_STATUSES}: `PENDING`, `SCANNING`, `FAILED` and\n * `INFECTED` files are not servable either, but their metadata IS the diagnostic surface an uploader\n * legitimately polls (\"upload failed\", \"scan in progress\"). Withholding those would break upload UX\n * while protecting nothing — none of them is an erasure outcome. `DELETED` is the terminal state (it\n * has no outgoing transition in {@link FILE_STATUS_TRANSITIONS}) and the one an erasure produces.\n */\nexport const FILE_METADATA_WITHHELD_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.DELETED,\n]);\n\n/**\n * Value written over a file's `filename` / `originalFilename` when the file is erased for privacy.\n *\n * Both fields are REQUIRED (`z.string().min(1)`), so an erasure cannot null them without a schema\n * reshape; overwriting with one shared, non-identifying constant erases the personal data while\n * keeping the row valid, greppable and obviously-erased in logs and admin surfaces. Deliberately a\n * fixed constant rather than a per-file token: two erased files must not be distinguishable by name.\n */\nexport const ERASED_FILE_NAME_PLACEHOLDER = '[erased]';\n\n/**\n * Statuses that represent terminal or non-servable states.\n * Files in these states must not be served for download.\n */\nexport const FILE_BLOCKED_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.PENDING,\n  FileStatus.DELETED,\n  FileStatus.FAILED,\n  FileStatus.SCANNING,\n  FileStatus.INFECTED,\n  FileStatus.QUARANTINED,\n]);\n\n/**\n * Valid lifecycle transitions.\n *\n * Each key is a source status; the value is the set of statuses it can\n * transition to. Any transition not listed here is invalid.\n */\nexport const FILE_STATUS_TRANSITIONS: Readonly<Record<FileStatus, readonly FileStatus[]>> = {\n  [FileStatus.PENDING]:      [FileStatus.UPLOADED, FileStatus.FAILED],\n  [FileStatus.UPLOADED]:     [FileStatus.LINKED, FileStatus.SCANNING, FileStatus.ORPHANED, FileStatus.DELETED, FileStatus.FAILED],\n  [FileStatus.SCANNING]:     [FileStatus.CLEAN, FileStatus.INFECTED, FileStatus.FAILED],\n  [FileStatus.CLEAN]:        [FileStatus.LINKED, FileStatus.ORPHANED, FileStatus.DELETED],\n  [FileStatus.INFECTED]:     [FileStatus.QUARANTINED, FileStatus.DELETED],\n  [FileStatus.QUARANTINED]:  [FileStatus.DELETED],\n  [FileStatus.LINKED]:       [FileStatus.ORPHANED, FileStatus.DELETED],\n  [FileStatus.ORPHANED]:     [FileStatus.LINKED, FileStatus.DELETED],\n  [FileStatus.DELETED]:      [],\n  [FileStatus.FAILED]:       [FileStatus.DELETED],\n};\n\n/**\n * Statuses from which a file may be LINKED to a resource field — the set the link-time checks\n * (`FileOperationHandlerBackendService.validateFileFieldsForCreate/Update`,\n * `FilesBackendService.linkFileToResource`) consult.\n *\n * ## Why this set exists (issue #320)\n *\n * Those checks used to compare against the literal `FileStatus.UPLOADED`, while\n * {@link FILE_STATUS_TRANSITIONS} — the authority on what a status MEANS — already allowed\n * `CLEAN → LINKED`. So a file the scanner had just certified safe was refused at the one moment it was\n * needed, with an error naming `UPLOADED` as the expected state, and whether a scanned file could be\n * attached at all depended on how fast the caller was relative to the scanner. Two `$in` queries in\n * `FilesBackendService` had meanwhile grown their own `[UPLOADED, CLEAN]` pairs — three copies of one\n * answer, one of them wrong. This is the single copy.\n *\n * ## Derived-CHECKED against the map, not computed from it\n *\n * Every member here has `LINKED` among its outgoing transitions (pinned by\n * `files.shared.status-sets.test.ts`), so this set can never admit a transition the map forbids.\n * It is nonetheless written out rather than computed, because the map is a superset of what linking\n * should admit today:\n *\n * - `ORPHANED → LINKED` is legal in the map (a re-link after the parent was deleted with the file\n *   kept) and is DELIBERATELY NOT admitted here. Re-linking an orphan is a distinct capability with\n *   its own questions — whose scope does the file re-enter, what happens to its old key — and\n *   admitting it as a side effect of fixing the `CLEAN` refusal would decide those questions by\n *   accident. The pin asserts this exclusion by name so widening it is a choice, not drift.\n * - `SCANNING` is absent because the map forbids `SCANNING → LINKED`: a file whose scan is in\n *   flight is not yet known to be safe. The link path names that case with\n *   `FILE_SCAN_IN_PROGRESS` so the caller learns to retry, rather than the generic refusal.\n */\nexport const FILE_LINKABLE_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.UPLOADED,\n  FileStatus.CLEAN,\n]);\n\n\nexport const FILE_PRIMARY_SCOPES = [\n  ResourcePrimaryScope.APPLICATION,\n  ResourcePrimaryScope.ORGANIZATIONS,\n  ResourcePrimaryScope.USER_SELF,\n] as const;\n\nexport type FilePrimaryScope = (typeof FILE_PRIMARY_SCOPES)[number];\n\nfunction hasFileScopeIdentifierValue(value: string | undefined): boolean {\n  return typeof value === 'string' && value.trim() !== '';\n}\n\nfunction validateUploaderPair(\n  file: {\n    uploadedBy?: string;\n    uploadedByEntityType?: FileUploaderEntityType;\n  },\n  ctx: z.RefinementCtx,\n): void {\n  const hasUploadedBy = hasFileScopeIdentifierValue(file.uploadedBy);\n  const hasUploadedByEntityType = file.uploadedByEntityType !== undefined;\n\n  if (hasUploadedBy !== hasUploadedByEntityType) {\n    ctx.addIssue({\n      code: 'custom',\n      path: hasUploadedBy ? ['uploadedByEntityType'] : ['uploadedBy'],\n      message: 'uploadedBy and uploadedByEntityType must either both be set or both be omitted',\n    });\n  }\n}\n\nexport function validateFileScopeIdentifiers(scope: {\n  primaryScope: FilePrimaryScope;\n  applicationId: string;\n  organizationId?: string;\n  userId?: string;\n}): boolean {\n  const hasApplicationId = hasFileScopeIdentifierValue(scope.applicationId);\n  const hasOrganizationId = hasFileScopeIdentifierValue(scope.organizationId);\n  const hasUserId = hasFileScopeIdentifierValue(scope.userId);\n\n  switch (scope.primaryScope) {\n    case ResourcePrimaryScope.APPLICATION:\n      return hasApplicationId && !hasOrganizationId && !hasUserId;\n    case ResourcePrimaryScope.ORGANIZATIONS:\n      // applicationId is always required (tenant isolation); organizationId is the scope discriminator.\n      return hasApplicationId && hasOrganizationId && !hasUserId;\n    case ResourcePrimaryScope.USER_SELF:\n      // Primary scopes are a SEPARATION OF CONCERN: USER_SELF and ORGANIZATIONS are\n      // independent axes. A user's self-owned file is user-owned, NOT org-owned —\n      // `userId` is the scope discriminator and `applicationId` is the tenant/bucket\n      // anchor. `organizationId` MUST be absent (a present org would conflate the two\n      // scopes). Fail closed on any org value.\n      return hasApplicationId && hasUserId && !hasOrganizationId;\n    default:\n      return false;\n  }\n}\n\n/**\n * File resource schema\n *\n * Stores file metadata and links files to resources.\n * Files are stored via app-managed storage providers (MinIO/S3, local directory, etc.),\n * this schema tracks metadata only.\n *\n * ## Storage Identity Convention\n * `storageProvider` + `storageRef` are the persisted routing truth used to\n * reach the active storage backend. `storageKey` remains framework metadata\n * that captures the file's derived scope path for bookkeeping, diagnostics,\n * and future storage contract evolution.\n *\n * `storageKey` includes scope path derived from primaryScope:\n * - APPLICATION: `app/{applicationId}/{fileId}`\n * - ORGANIZATIONS: `org/{organizationId}/{fileId}`\n * - USER_SELF: `user/{userId}/{fileId}` (owner is the user; no org segment)\n */\nconst FileSchemaBase = z.object({\n  fileId: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  // ========== File Metadata ==========\n  // USER_CONTENT on both names. A filename is chosen by the person and routinely IS the personal\n  // datum — \"scan-2026-medical.pdf\" discloses a special category before the file is opened. The\n  // file's BYTES are not a field here (this resource is metadata over object storage), so this is the\n  // only place the content axis can be declared at all.\n  filename: z.string().min(1).isDBIndexed().isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT),\n  originalFilename: z.string().min(1).isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT),\n  mimeType: z.string().min(1).isDBIndexed().isSummaryField(),\n  size: z.number().min(0).isSummaryField(),\n  extension: z.string().optional(),\n  checksum: z.string().optional().isDBIndexed(),\n\n  // ========== Storage ==========\n  // `storageProvider` + `storageRef` are the persisted backend-routing truth.\n  storageProvider: z.enum(FileStorageAccepted).optional().isDBIndexed(),\n  storageRef: z.string().min(1).optional().isDBIndexed(),\n  // `storageKey` is still scoped metadata, not the storage backend handle. It embeds the\n  // file identity (`_id`, surfaced as the `fileId` virtual), so it is derived + persisted\n  // AFTER the row is created (insert-first) — hence optional at create time. `createFile`\n  // sets it once `_id` exists, and `linkFileToResource` re-derives it when the file's scope\n  // is finalized.\n  storageKey: z.string().min(1).optional().isDBIndexed(),\n  url: z.url().optional(), // Cached URL (may be presigned)\n\n  // ========== Status & Lifecycle ==========\n  status: z.enum(FileStatus).default(FileStatus.PENDING).isDBIndexed().isSummaryField(),\n\n  // ========== Nature-specific Metadata ==========\n  // Inferred from MIME type or set by analysis services (F4-03)\n  // Resolved display nature (IMAGE/VIDEO/AUDIO/DOCUMENT/GENERIC) — NOT the schema-level FileNature.\n  // Set by resolveFileDisplayNature() during upload or inferred from MIME type in toMetadataResponse().\n  // Schema declares FileNature (e.g., PDF, OFFICE), but the DB stores the resolved FileDisplayNature.\n  nature: z.enum(FileDisplayNature).optional().isDBIndexed(),\n  // Image-specific\n  width: z.number().positive().optional(),\n  height: z.number().positive().optional(),\n  thumbnailUrl: z.url().optional(),\n  // Video/Audio-specific (populated by IFileVideoAnalyzer / IFileAudioAnalyzer)\n  duration: z.number().positive().optional(), // Duration in seconds\n  // Document-specific (populated by IFileDocumentAnalyzer)\n  pageCount: z.number().positive().optional(),\n\n  // ========== Resource Linking ==========\n  // When linked, scope is derived from parent resource's resourcePrimaryScope\n  linkedResourceType: z.string().optional().isDBIndexed(),\n  linkedResourceId: z.string().optional().isDBIndexed(),\n  linkedFieldName: z.string().optional(),\n\n  // ========== Primary Scope ==========\n  // Derived from parent resource's resourcePrimaryScope when linking\n  // Determines access control and storage path\n  primaryScope: z.enum(FILE_PRIMARY_SCOPES).optional().isDBIndexed(),\n\n  // ========== Scope Identifiers ==========\n  // applicationId is ALWAYS set (from execution context at creation time) — it is the\n  // top-level tenant isolation field present on every file record regardless of primaryScope.\n  // organizationId and userId are populated only when the file's primaryScope requires them.\n\n  applicationId: z.string().isDBIndexed(),\n\n  // ORGANIZATIONS scope: org-scoped files. Set ONLY for ORGANIZATIONS-scoped files —\n  // never for USER_SELF (the two scopes are independent axes, separation of concern).\n  organizationId: z.string().optional().isDBIndexed(),\n\n  // USER_SELF scope: user-private files owned by one user. Set ONLY for USER_SELF-scoped\n  // files; the owner is the user (no org). `applicationId` is the tenant/bucket anchor.\n  userId: z.string().optional().isDBIndexed(),\n\n  // ========== Upload Metadata ==========\n  // The uploader principal is persisted as a raw id + type pair only.\n  // Any richer label/entity hydration is intentionally client-driven.\n  uploadedBy: z.string().trim().min(1).optional().isDBIndexed(),\n  uploadedByEntityType: z.enum(FileUploaderEntityType).optional().isDBIndexed(),\n\n  // ========== Timestamps ==========\n  uploadedAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  deletedAt: z.date().optional().isDBIndexed().excludeFromCreate(),\n});\n\nexport const FileSchema = FileSchemaBase.superRefine((file, ctx) => {\n  validateUploaderPair(file, ctx);\n\n  if (!file.primaryScope) {\n    // Pre-link state: applicationId is always present (set from execution context at upload time),\n    // but organizationId/userId must not be set without a primaryScope discriminator.\n    if (hasFileScopeIdentifierValue(file.organizationId) || hasFileScopeIdentifierValue(file.userId)) {\n      ctx.addIssue({\n        code: 'custom',\n        path: ['primaryScope'],\n        message: 'primaryScope is required when organizationId or userId are present',\n      });\n    }\n    return;\n  }\n\n  if (!validateFileScopeIdentifiers({\n    primaryScope: file.primaryScope,\n    applicationId: file.applicationId,\n    organizationId: file.organizationId,\n    userId: file.userId,\n  })) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['primaryScope'],\n      message: 'File scope identifiers must match the declared primaryScope',\n    });\n  }\n\n});\nexport type File = z.infer<typeof FileSchema> & FileUploaderOwnership;\n\n/**\n * Scope identifiers for file access control.\n * Populated based on primaryScope when file is created/linked.\n */\nexport interface FileScopeIdentifiers {\n  primaryScope: FilePrimaryScope;\n  /** Always required — top-level tenant isolation key, set from execution context at file creation. */\n  applicationId: string;\n  organizationId?: string;\n  userId?: string;\n}\n"]}
+{"version":3,"file":"files.shared.schemas.js","sourceRoot":"","sources":["../../../../src/files/files.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Files Shared Schemas\n *\n * Reusable schemas for file uploads and file handling.\n *\n * ## Scope Model\n *\n * Files use a **segregated scope model** where scope identifiers are separate fields\n * (not hierarchical). A file belongs to exactly one primary scope:\n * - APPLICATION: App-level shared files (e.g., branding assets)\n * - ORGANIZATIONS: Org-scoped files (e.g., org documents)\n * - USER_SELF: User-private files owned by a single user (NO org — USER_SELF and\n *   ORGANIZATIONS are independent primary-scope axes; `applicationId` is the bucket anchor)\n *\n * `ANONYMOUS` is intentionally excluded from the file contract for now. The\n * file layer does not yet define anonymous upload, storage, and access semantics\n * end to end, so file resources fail closed instead of pretending support.\n *\n * Scope is **derived from the parent resource's resourcePrimaryScope** when linking.\n * Access rights are **inherited from the z_file() field** on the parent resource.\n *\n * Note: FileMetadata is defined in @wildo-ai/zod-decorators\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { FileDisplayNature, FileStorageAccepted, FileUploaderEntityType, type FileUploaderOwnership } from '@wildo-ai/zod-decorators';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\n\n// Re-export FileMetadata from zod-decorators for convenience\nexport type { FileMetadata } from '@wildo-ai/zod-decorators';\nexport { FileUploaderEntityType, FileStorageAccepted } from '@wildo-ai/zod-decorators';\nexport type { FileUploaderOwnership } from '@wildo-ai/zod-decorators';\n\n/**\n * File status lifecycle enum\n *\n * NOTE — no extraction/indexing members. `EXTRACTING` / `EXTRACTED` / `INDEXED` were removed\n * 2026-08-26 with the resource-native RAG reshape (plan `resource-rag-capability`, Phase 1):\n * text extraction and embedding state are per-FIELD, per-CHUNK facts, and the RAG chunk rows\n * (Phase 2's derived-data tier, keyed `(resourceType, resourceId, fieldName, chunkIndex)` with a\n * NULLABLE `vector` as the \"needs embedding\" ledger) carry them. A single file-level status could\n * never say WHICH field's corpus was current — it was the wrong shape, not merely unused — and\n * `INDEXED` had already shipped one false claim (written to mean \"text was copied\", read as\n * \"searchable\": https://github.com/wildo-ai/wildo-ai/issues/46). The file lifecycle now ends at\n * upload/scan/link/erasure concerns, which really are per-file.\n */\nexport enum FileStatus {\n  PENDING = 'pending',\n  UPLOADED = 'uploaded',\n  LINKED = 'linked',\n  DELETED = 'deleted',\n  ORPHANED = 'orphaned',\n  FAILED = 'failed',\n\n  SCANNING = 'scanning',\n  CLEAN = 'clean',\n  INFECTED = 'infected',\n  QUARANTINED = 'quarantined',\n}\n\n/**\n * Rendition of a file's bytes requested from the serve route via `?variant=`.\n *\n * - `ORIGINAL` — the stored bytes, unchanged (the default when the param is absent).\n * - `THUMBNAIL` — a small, downscaled `webp` derived on the fly for preview surfaces\n *   (nav avatar, list/card image) so a preview never pulls a multi-MB original. Only\n *   raster images are eligible; for any other file the serve route transparently\n *   falls back to the original bytes.\n *\n * This is the WIRE CONTRACT for the serve route's `variant` query parameter — shared\n * by the frontend (which builds `?variant=thumbnail` preview URLs) and the backend\n * serve route (which parses it). Keep the string values stable across releases.\n */\nexport enum FileServeVariant {\n  ORIGINAL = 'original',\n  THUMBNAIL = 'thumbnail',\n}\n\n/**\n * Parse an untrusted `?variant=` query value into a {@link FileServeVariant}.\n * Absent or unrecognized values fall back to `ORIGINAL` (fail-safe: an unknown\n * variant serves the untransformed bytes rather than erroring).\n */\nexport function parseFileServeVariant(raw: unknown): FileServeVariant {\n  return raw === FileServeVariant.THUMBNAIL\n    ? FileServeVariant.THUMBNAIL\n    : FileServeVariant.ORIGINAL;\n}\n\n/**\n * Statuses in which a file's bytes are safe to serve for download.\n *\n * AV scanning IS wired: `FileScanningBackendService` is bound in the container and the resource\n * upload handler calls `shouldScan` then `initiateScan`, so a scanned file moves through SCANNING\n * to CLEAN / INFECTED / QUARANTINED. `SCANNING`, `INFECTED` and `QUARANTINED` are absent from this\n * set and therefore blocked, which is the post-scan half of the original Wave 1 note.\n *\n * `UPLOADED` IS admitted, and that is correct rather than a leftover — but only because of where\n * the scan gate now sits. Scanning is opt-in per field (`shouldScan` reads the field's\n * `fileMetadata`), so an unscanned file legitimately terminates at UPLOADED and removing it from\n * this set would make every such field undownloadable.\n *\n * The window that used to sit behind that reasoning is CLOSED (#433, 2026-09-08). A file whose\n * field requires a scan never sits at UPLOADED at all: `resource-file-upload-handler` now AWAITS\n * `initiateScan` — which awaits the UPLOADED -> SCANNING transition and only then fires the scan\n * pipeline — BEFORE the upload response is sent. Previously it was fired afterwards without being\n * awaited, so the bytes were servable for the gap between the upload committing and the transition\n * landing.\n *\n * So the invariant this set relies on is external to it: **a required scan reaches SCANNING before\n * anyone learns the upload succeeded.** Do not restore a fire-and-forget scan initiation, and do\n * not add UPLOADED-adjacent statuses here without asking which side of that gate they fall on.\n */\nexport const FILE_DOWNLOADABLE_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.UPLOADED,\n  FileStatus.LINKED,\n  FileStatus.ORPHANED,\n  FileStatus.CLEAN,\n]);\n\n/**\n * Statuses in which a file's own METADATA must no longer be disclosed on the GLOBAL\n * `GET /files/:fileId/metadata` route (gate **G-FILE**).\n *\n * Blocking the BYTES is not enough. A privacy erasure marks the file `DELETED`, but physical cleanup\n * is a batch that runs much later — so between the two, `originalFilename` (`passport-jane-doe.pdf`)\n * and `uploadedBy` stayed readable by any member of the file's scope. \"Erased\" that leaves the\n * filename readable for weeks is not erased.\n *\n * DELIBERATELY NARROWER than {@link FILE_BLOCKED_STATUSES}: `PENDING`, `SCANNING`, `FAILED` and\n * `INFECTED` files are not servable either, but their metadata IS the diagnostic surface an uploader\n * legitimately polls (\"upload failed\", \"scan in progress\"). Withholding those would break upload UX\n * while protecting nothing — none of them is an erasure outcome. `DELETED` is the terminal state (it\n * has no outgoing transition in {@link FILE_STATUS_TRANSITIONS}) and the one an erasure produces.\n */\nexport const FILE_METADATA_WITHHELD_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.DELETED,\n]);\n\n/**\n * Value written over a file's `filename` / `originalFilename` when the file is erased for privacy.\n *\n * Both fields are REQUIRED (`z.string().min(1)`), so an erasure cannot null them without a schema\n * reshape; overwriting with one shared, non-identifying constant erases the personal data while\n * keeping the row valid, greppable and obviously-erased in logs and admin surfaces. Deliberately a\n * fixed constant rather than a per-file token: two erased files must not be distinguishable by name.\n */\nexport const ERASED_FILE_NAME_PLACEHOLDER = '[erased]';\n\n/**\n * Statuses that represent terminal or non-servable states.\n * Files in these states must not be served for download.\n */\nexport const FILE_BLOCKED_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.PENDING,\n  FileStatus.DELETED,\n  FileStatus.FAILED,\n  FileStatus.SCANNING,\n  FileStatus.INFECTED,\n  FileStatus.QUARANTINED,\n]);\n\n/**\n * Valid lifecycle transitions.\n *\n * Each key is a source status; the value is the set of statuses it can\n * transition to. Any transition not listed here is invalid.\n */\nexport const FILE_STATUS_TRANSITIONS: Readonly<Record<FileStatus, readonly FileStatus[]>> = {\n  [FileStatus.PENDING]:      [FileStatus.UPLOADED, FileStatus.FAILED],\n  [FileStatus.UPLOADED]:     [FileStatus.LINKED, FileStatus.SCANNING, FileStatus.ORPHANED, FileStatus.DELETED, FileStatus.FAILED],\n  [FileStatus.SCANNING]:     [FileStatus.CLEAN, FileStatus.INFECTED, FileStatus.FAILED],\n  [FileStatus.CLEAN]:        [FileStatus.LINKED, FileStatus.ORPHANED, FileStatus.DELETED],\n  [FileStatus.INFECTED]:     [FileStatus.QUARANTINED, FileStatus.DELETED],\n  [FileStatus.QUARANTINED]:  [FileStatus.DELETED],\n  [FileStatus.LINKED]:       [FileStatus.ORPHANED, FileStatus.DELETED],\n  [FileStatus.ORPHANED]:     [FileStatus.LINKED, FileStatus.DELETED],\n  [FileStatus.DELETED]:      [],\n  [FileStatus.FAILED]:       [FileStatus.DELETED],\n};\n\n/**\n * Statuses from which a file may be LINKED to a resource field — the set the link-time checks\n * (`FileOperationHandlerBackendService.validateFileFieldsForCreate/Update`,\n * `FilesBackendService.linkFileToResource`) consult.\n *\n * ## Why this set exists (issue #320)\n *\n * Those checks used to compare against the literal `FileStatus.UPLOADED`, while\n * {@link FILE_STATUS_TRANSITIONS} — the authority on what a status MEANS — already allowed\n * `CLEAN → LINKED`. So a file the scanner had just certified safe was refused at the one moment it was\n * needed, with an error naming `UPLOADED` as the expected state, and whether a scanned file could be\n * attached at all depended on how fast the caller was relative to the scanner. Two `$in` queries in\n * `FilesBackendService` had meanwhile grown their own `[UPLOADED, CLEAN]` pairs — three copies of one\n * answer, one of them wrong. This is the single copy.\n *\n * ## Derived-CHECKED against the map, not computed from it\n *\n * Every member here has `LINKED` among its outgoing transitions (pinned by\n * `files.shared.status-sets.test.ts`), so this set can never admit a transition the map forbids.\n * It is nonetheless written out rather than computed, because the map is a superset of what linking\n * should admit today:\n *\n * - `ORPHANED → LINKED` is legal in the map (a re-link after the parent was deleted with the file\n *   kept) and is DELIBERATELY NOT admitted here. Re-linking an orphan is a distinct capability with\n *   its own questions — whose scope does the file re-enter, what happens to its old key — and\n *   admitting it as a side effect of fixing the `CLEAN` refusal would decide those questions by\n *   accident. The pin asserts this exclusion by name so widening it is a choice, not drift.\n * - `SCANNING` is absent because the map forbids `SCANNING → LINKED`: a file whose scan is in\n *   flight is not yet known to be safe. The link path names that case with\n *   `FILE_SCAN_IN_PROGRESS` so the caller learns to retry, rather than the generic refusal.\n */\nexport const FILE_LINKABLE_STATUSES: ReadonlySet<FileStatus> = new Set([\n  FileStatus.UPLOADED,\n  FileStatus.CLEAN,\n]);\n\n\nexport const FILE_PRIMARY_SCOPES = [\n  ResourcePrimaryScope.APPLICATION,\n  ResourcePrimaryScope.ORGANIZATIONS,\n  ResourcePrimaryScope.USER_SELF,\n] as const;\n\nexport type FilePrimaryScope = (typeof FILE_PRIMARY_SCOPES)[number];\n\nfunction hasFileScopeIdentifierValue(value: string | undefined): boolean {\n  return typeof value === 'string' && value.trim() !== '';\n}\n\nfunction validateUploaderPair(\n  file: {\n    uploadedBy?: string;\n    uploadedByEntityType?: FileUploaderEntityType;\n  },\n  ctx: z.RefinementCtx,\n): void {\n  const hasUploadedBy = hasFileScopeIdentifierValue(file.uploadedBy);\n  const hasUploadedByEntityType = file.uploadedByEntityType !== undefined;\n\n  if (hasUploadedBy !== hasUploadedByEntityType) {\n    ctx.addIssue({\n      code: 'custom',\n      path: hasUploadedBy ? ['uploadedByEntityType'] : ['uploadedBy'],\n      message: 'uploadedBy and uploadedByEntityType must either both be set or both be omitted',\n    });\n  }\n}\n\nexport function validateFileScopeIdentifiers(scope: {\n  primaryScope: FilePrimaryScope;\n  applicationId: string;\n  organizationId?: string;\n  userId?: string;\n}): boolean {\n  const hasApplicationId = hasFileScopeIdentifierValue(scope.applicationId);\n  const hasOrganizationId = hasFileScopeIdentifierValue(scope.organizationId);\n  const hasUserId = hasFileScopeIdentifierValue(scope.userId);\n\n  switch (scope.primaryScope) {\n    case ResourcePrimaryScope.APPLICATION:\n      return hasApplicationId && !hasOrganizationId && !hasUserId;\n    case ResourcePrimaryScope.ORGANIZATIONS:\n      // applicationId is always required (tenant isolation); organizationId is the scope discriminator.\n      return hasApplicationId && hasOrganizationId && !hasUserId;\n    case ResourcePrimaryScope.USER_SELF:\n      // Primary scopes are a SEPARATION OF CONCERN: USER_SELF and ORGANIZATIONS are\n      // independent axes. A user's self-owned file is user-owned, NOT org-owned —\n      // `userId` is the scope discriminator and `applicationId` is the tenant/bucket\n      // anchor. `organizationId` MUST be absent (a present org would conflate the two\n      // scopes). Fail closed on any org value.\n      return hasApplicationId && hasUserId && !hasOrganizationId;\n    default:\n      return false;\n  }\n}\n\n/**\n * File resource schema\n *\n * Stores file metadata and links files to resources.\n * Files are stored via app-managed storage providers (MinIO/S3, local directory, etc.),\n * this schema tracks metadata only.\n *\n * ## Storage Identity Convention\n * `storageProvider` + `storageRef` are the persisted routing truth used to\n * reach the active storage backend. `storageKey` remains framework metadata\n * that captures the file's derived scope path for bookkeeping, diagnostics,\n * and future storage contract evolution.\n *\n * `storageKey` includes scope path derived from primaryScope:\n * - APPLICATION: `app/{applicationId}/{fileId}`\n * - ORGANIZATIONS: `org/{organizationId}/{fileId}`\n * - USER_SELF: `user/{userId}/{fileId}` (owner is the user; no org segment)\n */\nconst FileSchemaBase = z.object({\n  fileId: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  // ========== File Metadata ==========\n  // USER_CONTENT on both names. A filename is chosen by the person and routinely IS the personal\n  // datum — \"scan-2026-medical.pdf\" discloses a special category before the file is opened. The\n  // file's BYTES are not a field here (this resource is metadata over object storage), so this is the\n  // only place the content axis can be declared at all.\n  filename: z.string().min(1).isDBIndexed().isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT),\n  originalFilename: z.string().min(1).isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT),\n  mimeType: z.string().min(1).isDBIndexed().isSummaryField(),\n  size: z.number().min(0).isSummaryField(),\n  extension: z.string().optional(),\n  checksum: z.string().optional().isDBIndexed(),\n\n  // ========== Storage ==========\n  // `storageProvider` + `storageRef` are the persisted backend-routing truth.\n  storageProvider: z.enum(FileStorageAccepted).optional().isDBIndexed(),\n  storageRef: z.string().min(1).optional().isDBIndexed(),\n  // `storageKey` is still scoped metadata, not the storage backend handle. It embeds the\n  // file identity (`_id`, surfaced as the `fileId` virtual), so it is derived + persisted\n  // AFTER the row is created (insert-first) — hence optional at create time. `createFile`\n  // sets it once `_id` exists, and `linkFileToResource` re-derives it when the file's scope\n  // is finalized.\n  storageKey: z.string().min(1).optional().isDBIndexed(),\n  url: z.url().optional(), // Cached URL (may be presigned)\n\n  // ========== Status & Lifecycle ==========\n  status: z.enum(FileStatus).default(FileStatus.PENDING).isDBIndexed().isSummaryField(),\n\n  // ========== Nature-specific Metadata ==========\n  // Inferred from MIME type or set by analysis services (F4-03)\n  // Resolved display nature (IMAGE/VIDEO/AUDIO/DOCUMENT/GENERIC) — NOT the schema-level FileNature.\n  // Set by resolveFileDisplayNature() during upload or inferred from MIME type in toMetadataResponse().\n  // Schema declares FileNature (e.g., PDF, OFFICE), but the DB stores the resolved FileDisplayNature.\n  nature: z.enum(FileDisplayNature).optional().isDBIndexed(),\n  // Image-specific\n  width: z.number().positive().optional(),\n  height: z.number().positive().optional(),\n  thumbnailUrl: z.url().optional(),\n  // Video/Audio-specific (populated by IFileVideoAnalyzer / IFileAudioAnalyzer)\n  duration: z.number().positive().optional(), // Duration in seconds\n  // Document-specific (populated by IFileDocumentAnalyzer)\n  pageCount: z.number().positive().optional(),\n\n  // ========== Resource Linking ==========\n  // When linked, scope is derived from parent resource's resourcePrimaryScope\n  linkedResourceType: z.string().optional().isDBIndexed(),\n  linkedResourceId: z.string().optional().isDBIndexed(),\n  linkedFieldName: z.string().optional(),\n\n  // ========== Primary Scope ==========\n  // Derived from parent resource's resourcePrimaryScope when linking\n  // Determines access control and storage path\n  primaryScope: z.enum(FILE_PRIMARY_SCOPES).optional().isDBIndexed(),\n\n  // ========== Scope Identifiers ==========\n  // applicationId is ALWAYS set (from execution context at creation time) — it is the\n  // top-level tenant isolation field present on every file record regardless of primaryScope.\n  // organizationId and userId are populated only when the file's primaryScope requires them.\n\n  applicationId: z.string().isDBIndexed(),\n\n  // ORGANIZATIONS scope: org-scoped files. Set ONLY for ORGANIZATIONS-scoped files —\n  // never for USER_SELF (the two scopes are independent axes, separation of concern).\n  organizationId: z.string().optional().isDBIndexed(),\n\n  // USER_SELF scope: user-private files owned by one user. Set ONLY for USER_SELF-scoped\n  // files; the owner is the user (no org). `applicationId` is the tenant/bucket anchor.\n  userId: z.string().optional().isDBIndexed(),\n\n  // ========== Upload Metadata ==========\n  // The uploader principal is persisted as a raw id + type pair only.\n  // Any richer label/entity hydration is intentionally client-driven.\n  uploadedBy: z.string().trim().min(1).optional().isDBIndexed(),\n  uploadedByEntityType: z.enum(FileUploaderEntityType).optional().isDBIndexed(),\n\n  // ========== Timestamps ==========\n  uploadedAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  deletedAt: z.date().optional().isDBIndexed().excludeFromCreate(),\n});\n\nexport const FileSchema = FileSchemaBase.superRefine((file, ctx) => {\n  validateUploaderPair(file, ctx);\n\n  if (!file.primaryScope) {\n    // Pre-link state: applicationId is always present (set from execution context at upload time),\n    // but organizationId/userId must not be set without a primaryScope discriminator.\n    if (hasFileScopeIdentifierValue(file.organizationId) || hasFileScopeIdentifierValue(file.userId)) {\n      ctx.addIssue({\n        code: 'custom',\n        path: ['primaryScope'],\n        message: 'primaryScope is required when organizationId or userId are present',\n      });\n    }\n    return;\n  }\n\n  if (!validateFileScopeIdentifiers({\n    primaryScope: file.primaryScope,\n    applicationId: file.applicationId,\n    organizationId: file.organizationId,\n    userId: file.userId,\n  })) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['primaryScope'],\n      message: 'File scope identifiers must match the declared primaryScope',\n    });\n  }\n\n});\nexport type File = z.infer<typeof FileSchema> & FileUploaderOwnership;\n\n/**\n * Scope identifiers for file access control.\n * Populated based on primaryScope when file is created/linked.\n */\nexport interface FileScopeIdentifiers {\n  primaryScope: FilePrimaryScope;\n  /** Always required — top-level tenant isolation key, set from execution context at file creation. */\n  applicationId: string;\n  organizationId?: string;\n  userId?: string;\n}\n"]}

package/dist/esm/flows-actors/actors.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actors.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/actors.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAmG,oBAAoB,EAAG,MAAM,sCAAsC,CAAC;AAe9K,oBAAY,mBAAmB;IAC7B,WAAW,gBAAgB;IAC3B,YAAY,iBAAiB;IAC7B,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,iBAAiB,sBAAsB;IACvC,cAAc,mBAAmB;CAClC;AAGD,oBAAY,mBAAmB;IAC7B,OAAO,YAAY;IACnB,cAAc,mBAAmB;IACjC,iBAAiB,sBAAsB;CACxC;AAED,eAAO,MAAM,WAAW;;;;;;;iBAOtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAS5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAO5D,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}
+{"version":3,"file":"actors.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/actors.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,kBAAkB,EAA6B,MAAM,uCAAuC,CAAC;AACtG,OAAO,EAAmG,oBAAoB,EAAG,MAAM,sCAAsC,CAAC;AAe9K,oBAAY,mBAAmB;IAC7B,WAAW,gBAAgB;IAC3B,YAAY,iBAAiB;IAC7B,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,iBAAiB,sBAAsB;IACvC,cAAc,mBAAmB;CAClC;AAGD,oBAAY,mBAAmB;IAC7B,OAAO,YAAY;IACnB,cAAc,mBAAmB;IACjC,iBAAiB,sBAAsB;CACxC;AAED,eAAO,MAAM,WAAW;;;;;;;iBAOtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAMhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAS5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAO5D,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/esm/flows-actors/actors.shared.schemas.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { WildoError_BackendSchema } from "../errors/errors.shared.schemas.js";
-import { FlowsActors_Status } from "./flows-actors.commons.shared.schemas.js";
+import { FlowsActors_Status, describeFlowsActorsStatus } from "./flows-actors.commons.shared.schemas.js";
 import { FlowActorSystem_BaseSchema, FlowActorSystem_ErrorStates_Schema, FlowActorSystem_ExecutionSchema, FlowActorSystem_Kind, } from "./flows-actors.system.shared.schemas.js";
 import { Actors_Task_Schema, Actors_Walkthrough_Schema, ActorsSystem_ExecutionPlan_Schema } from "./tasks.actors.shared.schemas.js";
 //===============================================================
@@ -73,7 +73,8 @@ export const ActorSystem_ExecutionSchema = FlowActorSystem_ExecutionSchema.exten
         status: z.enum(FlowsActors_Status),
         updatedAt: z.iso.datetime(),
         statusChanges: z.array(z.object({
-            status: z.enum(FlowsActors_Status),
+            status: z.enum(FlowsActors_Status)
+                .describe(describeFlowsActorsStatus("The state this run moved into at `timestamp`. The list is the run's history, oldest first.")),
             timestamp: z.iso.datetime(),
         })),
     }).array(),

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

@@ -1 +1 @@
-{"version":3,"file":"actors.shared.schemas.js","sourceRoot":"","sources":["../../../../src/flows-actors/actors.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport { WildoError_BackendSchema } from \"../errors/errors.shared.schemas\";\nimport { FlowsActors_Status } from \"./flows-actors.commons.shared.schemas\";\nimport { FlowActorSystem_BaseSchema, FlowActorSystem_ErrorStates_Schema, FlowActorSystem_ExecutionSchema, FlowActorSystem_Kind, } from \"./flows-actors.system.shared.schemas\";\nimport { Actors_Task_Schema, Actors_Walkthrough_Schema, ActorsSystem_ExecutionPlan_Schema } from \"./tasks.actors.shared.schemas\";\n\n\n//===============================================================\n//  Actor\n// --------\n// Actors are reactive components that subscribe to event topics\n// and respond with automated processing. They enable event-driven\n// architecture by processing messages asynchronously, supporting\n// batch processing, filtering, and various error handling strategies.\n// Actors can emit new events, creating event chains and workflows.\n//===============================================================\n\n\nexport enum Actor_Role_Category {\n  COORDINATOR = \"coordinator\",\n  TASK_PLANNER = \"task_planner\",\n  OPERATOR = \"operator\",\n  ANALYZER = \"analyzer\",\n  REVIEWER = \"reviewer\",\n  HUMAN_IN_THE_LOOP = \"human_in_the_loop\",\n  FLOW_EXECUTION = \"flow_execution\"\n}\n\n\nexport enum Actor_ExecutionMode {\n  AGENTIC = \"agentic\",\n  FLOW_EXECUTION = \"flow_execution\",\n  HUMAN_INTERACTION = \"human_interaction\",\n}\n\nexport const ActorSchema = z.object({\n  ref: z.string().min(1),\n  displayName: z.string().min(1),\n  roleCategory: z.enum(Actor_Role_Category),\n  executionMode: z.enum(Actor_ExecutionMode),\n  agentRef: z.string().optional(),\n  flowRef: z.string().optional(),\n});\nexport type Actor = z.infer<typeof ActorSchema>;\n\n//===============================================================\n//  Actor System\n//===============================================================\n\n/**\n * The ACTOR specialization of the system base — the schema that OWNS a system's\n * actor list. `actors` is declared here and in no other system schema: the base\n * cannot declare it, because a FLOW system has no actors. (Unrelated `actors`\n * members exist on the TASK schemas; those point at one actor, they are not a\n * system's roster.)\n *\n * An actor system must therefore be parsed with this schema, or one derived\n * from it. Parsing one with `FlowActorSystem_BaseSchema` strips `actors`\n * silently — see the warning there.\n */\nexport const ActorSystemSchema = FlowActorSystem_BaseSchema.extend({\n  /**\n   * Narrows the inherited `kind` discriminant to ACTOR. The historical shape\n   * added a separate `type` field here while every consumer (backend registry,\n   * execution schemas, flows counterpart) discriminates on `kind` — fixed\n   * 2026-07-02 (meta-workflows Step 0 hygiene; no `.type` consumer existed).\n   */\n  kind: z.literal(FlowActorSystem_Kind.ACTOR),\n  actors: z.array(z.lazy(() => ActorSchema)),\n});\nexport type ActorSystem = z.infer<typeof ActorSystemSchema>;\n\n\n//===============================================================\n//  Actor System Execution\n//===============================================================\n\nexport const ActorSystem_ExecutionSchema = FlowActorSystem_ExecutionSchema.extend({\n  kind: z.literal(FlowActorSystem_Kind.ACTOR),\n\n  plan: ActorsSystem_ExecutionPlan_Schema.optional(),\n  walkthrough: Actors_Walkthrough_Schema.optional(),\n  standaloneTasks: z.array(Actors_Task_Schema),\n\n  standaloneTaskStates: z.object({\n    taskId: z.string(),\n    status: z.enum(FlowsActors_Status),\n    updatedAt: z.iso.datetime(),\n    statusChanges: z.array(z.object({\n      status: z.enum(FlowsActors_Status),\n      timestamp: z.iso.datetime(),\n    })),\n  }).array(),\n\n  /**\n   * Overrides the base `errorItems` with the actor-execution-scoped variant\n   * (adds taskId/planStepId locators). Historically this extension used a\n   * divergent `errors` key coexisting with the base `errorItems` — aligned\n   * 2026-07-02 (meta-workflows Step 0 hygiene; the field had no consumers).\n   */\n  errorStates : FlowActorSystem_ErrorStates_Schema.extend({\n    errorItems: WildoError_BackendSchema.extend({\n      systemRef: z.string(),\n      taskId: z.string().optional(),\n      planStepId: z.string().optional(),\n    }).array().optional(),\n  }).optional(),\n});\nexport type ActorSystem_Execution = z.infer<typeof ActorSystem_ExecutionSchema>;\n"]}
+{"version":3,"file":"actors.shared.schemas.js","sourceRoot":"","sources":["../../../../src/flows-actors/actors.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport { WildoError_BackendSchema } from \"../errors/errors.shared.schemas\";\nimport { FlowsActors_Status, describeFlowsActorsStatus } from \"./flows-actors.commons.shared.schemas\";\nimport { FlowActorSystem_BaseSchema, FlowActorSystem_ErrorStates_Schema, FlowActorSystem_ExecutionSchema, FlowActorSystem_Kind, } from \"./flows-actors.system.shared.schemas\";\nimport { Actors_Task_Schema, Actors_Walkthrough_Schema, ActorsSystem_ExecutionPlan_Schema } from \"./tasks.actors.shared.schemas\";\n\n\n//===============================================================\n//  Actor\n// --------\n// Actors are reactive components that subscribe to event topics\n// and respond with automated processing. They enable event-driven\n// architecture by processing messages asynchronously, supporting\n// batch processing, filtering, and various error handling strategies.\n// Actors can emit new events, creating event chains and workflows.\n//===============================================================\n\n\nexport enum Actor_Role_Category {\n  COORDINATOR = \"coordinator\",\n  TASK_PLANNER = \"task_planner\",\n  OPERATOR = \"operator\",\n  ANALYZER = \"analyzer\",\n  REVIEWER = \"reviewer\",\n  HUMAN_IN_THE_LOOP = \"human_in_the_loop\",\n  FLOW_EXECUTION = \"flow_execution\"\n}\n\n\nexport enum Actor_ExecutionMode {\n  AGENTIC = \"agentic\",\n  FLOW_EXECUTION = \"flow_execution\",\n  HUMAN_INTERACTION = \"human_interaction\",\n}\n\nexport const ActorSchema = z.object({\n  ref: z.string().min(1),\n  displayName: z.string().min(1),\n  roleCategory: z.enum(Actor_Role_Category),\n  executionMode: z.enum(Actor_ExecutionMode),\n  agentRef: z.string().optional(),\n  flowRef: z.string().optional(),\n});\nexport type Actor = z.infer<typeof ActorSchema>;\n\n//===============================================================\n//  Actor System\n//===============================================================\n\n/**\n * The ACTOR specialization of the system base — the schema that OWNS a system's\n * actor list. `actors` is declared here and in no other system schema: the base\n * cannot declare it, because a FLOW system has no actors. (Unrelated `actors`\n * members exist on the TASK schemas; those point at one actor, they are not a\n * system's roster.)\n *\n * An actor system must therefore be parsed with this schema, or one derived\n * from it. Parsing one with `FlowActorSystem_BaseSchema` strips `actors`\n * silently — see the warning there.\n */\nexport const ActorSystemSchema = FlowActorSystem_BaseSchema.extend({\n  /**\n   * Narrows the inherited `kind` discriminant to ACTOR. The historical shape\n   * added a separate `type` field here while every consumer (backend registry,\n   * execution schemas, flows counterpart) discriminates on `kind` — fixed\n   * 2026-07-02 (meta-workflows Step 0 hygiene; no `.type` consumer existed).\n   */\n  kind: z.literal(FlowActorSystem_Kind.ACTOR),\n  actors: z.array(z.lazy(() => ActorSchema)),\n});\nexport type ActorSystem = z.infer<typeof ActorSystemSchema>;\n\n\n//===============================================================\n//  Actor System Execution\n//===============================================================\n\nexport const ActorSystem_ExecutionSchema = FlowActorSystem_ExecutionSchema.extend({\n  kind: z.literal(FlowActorSystem_Kind.ACTOR),\n\n  plan: ActorsSystem_ExecutionPlan_Schema.optional(),\n  walkthrough: Actors_Walkthrough_Schema.optional(),\n  standaloneTasks: z.array(Actors_Task_Schema),\n\n  standaloneTaskStates: z.object({\n    taskId: z.string(),\n    status: z.enum(FlowsActors_Status),\n    updatedAt: z.iso.datetime(),\n    statusChanges: z.array(z.object({\n      status: z.enum(FlowsActors_Status)\n        .describe(describeFlowsActorsStatus(\"The state this run moved into at `timestamp`. The list is the run's history, oldest first.\")),\n      timestamp: z.iso.datetime(),\n    })),\n  }).array(),\n\n  /**\n   * Overrides the base `errorItems` with the actor-execution-scoped variant\n   * (adds taskId/planStepId locators). Historically this extension used a\n   * divergent `errors` key coexisting with the base `errorItems` — aligned\n   * 2026-07-02 (meta-workflows Step 0 hygiene; the field had no consumers).\n   */\n  errorStates : FlowActorSystem_ErrorStates_Schema.extend({\n    errorItems: WildoError_BackendSchema.extend({\n      systemRef: z.string(),\n      taskId: z.string().optional(),\n      planStepId: z.string().optional(),\n    }).array().optional(),\n  }).optional(),\n});\nexport type ActorSystem_Execution = z.infer<typeof ActorSystem_ExecutionSchema>;\n"]}