@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/files/files.shared.resources-config.schemas.js

@@ -29,6 +29,32 @@ import { FileSchema } from './files.shared.schemas.js';
  * Files are managed internally by the file upload system and not exposed
  * as standard REST API endpoints. Repository operations are used internally
  * by FilesBackendService.
+ *
+ * ## Persistence
+ *
+ * There is deliberately NO `persistenceAdapter` here: FILES FOLLOWS the application's default
+ * adapter. It used to be pinned to MongoDB, on the grounds that "file metadata relies on
+ * Mongo-backed transactional/link semantics throughout the upload/link/unlink/cleanup pipeline".
+ * Measured rather than trusted, that was substantially true when written and is no longer:
+ *
+ * - the upload/link transaction opened on `MongoDBService` BY NAME; it now opens on whichever
+ *   store FILES resolves to;
+ * - the cleanup batch cleared link metadata through a raw-MongoDB `$unset`; it now uses the
+ *   adapter-neutral guarded set-and-clear on the repository contract;
+ * - the file-id validation was believed to require an ObjectId shape. It never did —
+ *   `Resources_SharedUtils.isValidResourceId` has always accepted ObjectId AND UUID, and only the
+ *   comment claimed otherwise.
+ *
+ * Blobs were never the issue: there is no GridFS. They live in object storage, and MongoDB held
+ * only this metadata row.
+ *
+ * **The pin was also what forced file metadata into a SECOND store**, which is why removing it
+ * closes more than it opens: a resource and its file metadata on one adapter share ONE native
+ * transaction, so generated-document materialization (PDFs) stops being refused as a cross-adapter
+ * boundary, and no saga or outbox is needed to make it atomic.
+ *
+ * An application is expected to be wholly one adapter (plan Wave 4.5). Following the default is
+ * what makes that true for FILES instead of quietly exempting it.
  */
 export const filesResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
     mainSchema: FileSchema,
@@ -36,10 +62,6 @@ export const filesResourceConfiguration_InitializationFactory = (resourcesRelati
     resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.FILES],
     resourceRelationships: resourcesRelationships,
     isSystemResource: true,
-    // File metadata currently relies on Mongo-backed transactional/link semantics
-    // throughout the upload/link/unlink/cleanup pipeline. Pinning FILES here avoids
-    // silent drift when an app switches its default adapter to PostgreSQL.
-    persistenceAdapter: 'mongodb',
     coreOperations: [
         CoreResourceOperation.READ,
         CoreResourceOperation.LIST,
@@ -100,4 +122,4 @@ export const filesResourceConfiguration_InitializationFactory = (resourcesRelati
         },
     },
 });
-//# sourceMappingURL=files.shared.resources-config.schemas.js.map
+//# sourceMappingURL=files.shared.resources-config.schemas.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"files.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../src/files/files.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,0CAA0C,EAAE,MAAM,8CAA8C,CAAC;AAC1G,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kCAAkC,EAAE,MAAM,gDAAgD,CAAC;AAC7I,OAAO,EAAE,0BAA0B,EAAE,4BAA4B,EAA8C,MAAM,uCAAuC,CAAC;AAC7J,OAAO,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AASpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAG,CAC9D,sBAA8C,EAC9C,EAAE,CAAC,0CAA0C,CAI7C;IACA,UAAU,EAAE,UAAU;IACtB,kBAAkB,EAAE,gBAAgB,CAAC,KAAK;IAC1C,uBAAuB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,KAAK,CAAC;IACnF,qBAAqB,EAAE,sBAAsB;IAC7C,gBAAgB,EAAE,IAAI;IACtB,8EAA8E;IAC9E,gFAAgF;IAChF,uEAAuE;IACvE,kBAAkB,EAAE,SAAS;IAC7B,cAAc,EAAE;QACd,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;KAC7B;IACD,uBAAuB,EAAE;QACvB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;KACF;CACF,CAAC,CAAC"}
+{"version":3,"file":"files.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/files/files.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,0CAA0C,EAAE,MAAM,8CAA8C,CAAC;AAC1G,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kCAAkC,EAAE,MAAM,gDAAgD,CAAC;AAC7I,OAAO,EAAE,0BAA0B,EAAE,4BAA4B,EAA8C,MAAM,uCAAuC,CAAC;AAC7J,OAAO,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AASpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAG,CAC9D,sBAA8C,EAC9C,EAAE,CAAC,0CAA0C,CAI7C;IACA,UAAU,EAAE,UAAU;IACtB,kBAAkB,EAAE,gBAAgB,CAAC,KAAK;IAC1C,uBAAuB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,KAAK,CAAC;IACnF,qBAAqB,EAAE,sBAAsB;IAC7C,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE;QACd,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;KAC7B;IACD,uBAAuB,EAAE;QACvB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE;gBACR;oBACE,WAAW,EAAE,4BAA4B,CAAC,eAAe;oBACzD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC;oBAClC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACF;SACF;KACF;CACF,CAAC,CAAC","sourcesContent":["/**\n * Files Resource Configuration (Repository-only)\n * \n * Provides repository operations for file metadata management.\n * Files are managed internally by the file upload system.\n * \n * ## Scope Model\n * \n * Files use a **dynamic scope** that is derived from the parent resource's\n * resourcePrimaryScope when linked. The FILES resource itself is configured\n * with ORGANIZATIONS as default primaryScope, but individual file records\n * store their actual scope in the `primaryScope` field.\n * \n * This allows files to be correctly scoped to:\n * - APPLICATION: App-level shared files\n * - ORGANIZATIONS: Org-scoped files (default)\n * - USER_SELF: User-private files\n *\n */\n\nimport { z } from 'zod';\nimport { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory';\nimport { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport { ResourceOperationRiskLevel, ResourceOperationVariantType, ResourceRelationship, ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { FileSchema } from './files.shared.schemas';\n\ntype FilesCoreOperations = \n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE\n  | CoreResourceOperation.DELETE;\n\n/**\n * Files Resource Configuration Factory\n * \n * Creates a REPOSITORY_ONLY resource configuration for file metadata.\n * Files are managed internally by the file upload system and not exposed\n * as standard REST API endpoints. Repository operations are used internally\n * by FilesBackendService.\n *\n * ## Persistence\n *\n * There is deliberately NO `persistenceAdapter` here: FILES FOLLOWS the application's default\n * adapter. It used to be pinned to MongoDB, on the grounds that \"file metadata relies on\n * Mongo-backed transactional/link semantics throughout the upload/link/unlink/cleanup pipeline\".\n * Measured rather than trusted, that was substantially true when written and is no longer:\n *\n * - the upload/link transaction opened on `MongoDBService` BY NAME; it now opens on whichever\n *   store FILES resolves to;\n * - the cleanup batch cleared link metadata through a raw-MongoDB `$unset`; it now uses the\n *   adapter-neutral guarded set-and-clear on the repository contract;\n * - the file-id validation was believed to require an ObjectId shape. It never did —\n *   `Resources_SharedUtils.isValidResourceId` has always accepted ObjectId AND UUID, and only the\n *   comment claimed otherwise.\n *\n * Blobs were never the issue: there is no GridFS. They live in object storage, and MongoDB held\n * only this metadata row.\n *\n * **The pin was also what forced file metadata into a SECOND store**, which is why removing it\n * closes more than it opens: a resource and its file metadata on one adapter share ONE native\n * transaction, so generated-document materialization (PDFs) stops being refused as a cross-adapter\n * boundary, and no saga or outbox is needed to make it atomic.\n *\n * An application is expected to be wholly one adapter (plan Wave 4.5). Following the default is\n * what makes that true for FILES instead of quietly exempting it.\n */\nexport const filesResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  undefined,\n  FilesCoreOperations,\n  typeof FileSchema\n>({\n  mainSchema: FileSchema,\n  resourceIdentifier: CoreResourceType.FILES,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.FILES],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.UPDATE,\n    CoreResourceOperation.DELETE,\n  ],\n  operationsConfiguration: {\n    [CoreResourceOperation.READ]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n    [CoreResourceOperation.LIST]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n    [CoreResourceOperation.CREATE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n    [CoreResourceOperation.UPDATE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n    [CoreResourceOperation.DELETE]: {\n      variants: [\n        {\n          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,\n          isDefault: true,\n          roles: [CORE_ORG_ROLES.ORG_MEMBER],\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        },\n      ],\n    },\n  },\n});\n"]}

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

@@ -9,7 +9,8 @@
  * (not hierarchical). A file belongs to exactly one primary scope:
  * - APPLICATION: App-level shared files (e.g., branding assets)
  * - ORGANIZATIONS: Org-scoped files (e.g., org documents)
- * - USER_SELF: User-private files within an org context
+ * - USER_SELF: User-private files owned by a single user (NO org — USER_SELF and
+ *   ORGANIZATIONS are independent primary-scope axes; `applicationId` is the bucket anchor)
  *
  * `ANONYMOUS` is intentionally excluded from the file contract for now. The
  * file layer does not yet define anonymous upload, storage, and access semantics
@@ -22,12 +23,22 @@
  */
 import { z } from 'zod';
 import { FileDisplayNature, FileStorageAccepted, FileUploaderEntityType, type FileUploaderOwnership } from '@wildo-ai/zod-decorators';
-import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
 export type { FileMetadata } from '@wildo-ai/zod-decorators';
-export { FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+export { FileUploaderEntityType, FileStorageAccepted } from '@wildo-ai/zod-decorators';
 export type { FileUploaderOwnership } from '@wildo-ai/zod-decorators';
 /**
  * File status lifecycle enum
+ *
+ * NOTE — no extraction/indexing members. `EXTRACTING` / `EXTRACTED` / `INDEXED` were removed
+ * 2026-08-26 with the resource-native RAG reshape (plan `resource-rag-capability`, Phase 1):
+ * text extraction and embedding state are per-FIELD, per-CHUNK facts, and the RAG chunk rows
+ * (Phase 2's derived-data tier, keyed `(resourceType, resourceId, fieldName, chunkIndex)` with a
+ * NULLABLE `vector` as the "needs embedding" ledger) carry them. A single file-level status could
+ * never say WHICH field's corpus was current — it was the wrong shape, not merely unused — and
+ * `INDEXED` had already shipped one false claim (written to mean "text was copied", read as
+ * "searchable": https://github.com/wildo-ai/wildo-ai/issues/46). The file lifecycle now ends at
+ * upload/scan/link/erasure concerns, which really are per-file.
  */
 export declare enum FileStatus {
     PENDING = "pending",
@@ -39,10 +50,31 @@ export declare enum FileStatus {
     SCANNING = "scanning",
     CLEAN = "clean",
     INFECTED = "infected",
-    QUARANTINED = "quarantined",
-    EXTRACTING = "extracting",
-    INDEXED = "indexed"
+    QUARANTINED = "quarantined"
+}
+/**
+ * Rendition of a file's bytes requested from the serve route via `?variant=`.
+ *
+ * - `ORIGINAL` — the stored bytes, unchanged (the default when the param is absent).
+ * - `THUMBNAIL` — a small, downscaled `webp` derived on the fly for preview surfaces
+ *   (nav avatar, list/card image) so a preview never pulls a multi-MB original. Only
+ *   raster images are eligible; for any other file the serve route transparently
+ *   falls back to the original bytes.
+ *
+ * This is the WIRE CONTRACT for the serve route's `variant` query parameter — shared
+ * by the frontend (which builds `?variant=thumbnail` preview URLs) and the backend
+ * serve route (which parses it). Keep the string values stable across releases.
+ */
+export declare enum FileServeVariant {
+    ORIGINAL = "original",
+    THUMBNAIL = "thumbnail"
 }
+/**
+ * Parse an untrusted `?variant=` query value into a {@link FileServeVariant}.
+ * Absent or unrecognized values fall back to `ORIGINAL` (fail-safe: an unknown
+ * variant serves the untransformed bytes rather than erroring).
+ */
+export declare function parseFileServeVariant(raw: unknown): FileServeVariant;
 /**
  * Statuses in which a file's bytes are safe to serve for download.
  *
@@ -52,6 +84,31 @@ export declare enum FileStatus {
  * QUARANTINED must be blocked.
  */
 export declare const FILE_DOWNLOADABLE_STATUSES: ReadonlySet<FileStatus>;
+/**
+ * Statuses in which a file's own METADATA must no longer be disclosed on the GLOBAL
+ * `GET /files/:fileId/metadata` route (gate **G-FILE**).
+ *
+ * Blocking the BYTES is not enough. A privacy erasure marks the file `DELETED`, but physical cleanup
+ * is a batch that runs much later — so between the two, `originalFilename` (`passport-jane-doe.pdf`)
+ * and `uploadedBy` stayed readable by any member of the file's scope. "Erased" that leaves the
+ * filename readable for weeks is not erased.
+ *
+ * DELIBERATELY NARROWER than {@link FILE_BLOCKED_STATUSES}: `PENDING`, `SCANNING`, `FAILED` and
+ * `INFECTED` files are not servable either, but their metadata IS the diagnostic surface an uploader
+ * legitimately polls ("upload failed", "scan in progress"). Withholding those would break upload UX
+ * while protecting nothing — none of them is an erasure outcome. `DELETED` is the terminal state (it
+ * has no outgoing transition in {@link FILE_STATUS_TRANSITIONS}) and the one an erasure produces.
+ */
+export declare const FILE_METADATA_WITHHELD_STATUSES: ReadonlySet<FileStatus>;
+/**
+ * Value written over a file's `filename` / `originalFilename` when the file is erased for privacy.
+ *
+ * Both fields are REQUIRED (`z.string().min(1)`), so an erasure cannot null them without a schema
+ * reshape; overwriting with one shared, non-identifying constant erases the personal data while
+ * keeping the row valid, greppable and obviously-erased in logs and admin surfaces. Deliberately a
+ * fixed constant rather than a per-file token: two erased files must not be distinguishable by name.
+ */
+export declare const ERASED_FILE_NAME_PLACEHOLDER = "[erased]";
 /**
  * Statuses that represent terminal or non-servable states.
  * Files in these states must not be served for download.
@@ -68,21 +125,21 @@ export declare const FILE_PRIMARY_SCOPES: readonly [ResourcePrimaryScope.APPLICA
 export type FilePrimaryScope = (typeof FILE_PRIMARY_SCOPES)[number];
 export declare function validateFileScopeIdentifiers(scope: {
     primaryScope: FilePrimaryScope;
-    applicationId?: string;
+    applicationId: string;
     organizationId?: string;
     userId?: string;
 }): boolean;
 export declare const FileSchema: z.ZodObject<{
     fileId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
-    filename: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
-    originalFilename: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    filename: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    originalFilename: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     mimeType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     size: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
     extension: z.ZodOptional<z.ZodString>;
     checksum: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     storageProvider: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<typeof FileStorageAccepted>>>;
     storageRef: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
-    storageKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    storageKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     url: z.ZodOptional<z.ZodURL>;
     status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof FileStatus>>>>;
     nature: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<typeof FileDisplayNature>>>;
@@ -99,7 +156,7 @@ export declare const FileSchema: z.ZodObject<{
         organizations: ResourcePrimaryScope.ORGANIZATIONS;
         applications: ResourcePrimaryScope.APPLICATION;
     }>>>;
-    applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
     organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     userId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     uploadedBy: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
@@ -107,7 +164,7 @@ export declare const FileSchema: z.ZodObject<{
     uploadedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>>;
     deletedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type File = z.infer<typeof FileSchema> & FileUploaderOwnership;
 /**
  * Scope identifiers for file access control.
@@ -115,7 +172,8 @@ export type File = z.infer<typeof FileSchema> & FileUploaderOwnership;
  */
 export interface FileScopeIdentifiers {
     primaryScope: FilePrimaryScope;
-    applicationId?: string;
+    /** Always required — top-level tenant isolation key, set from execution context at file creation. */
+    applicationId: string;
     organizationId?: string;
     userId?: string;
 }

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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,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,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;GAEG;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;IAE3B,UAAU,eAAe;IACzB,OAAO,YAAY;CACpB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,UAAU,CAO7D,CAAC;AAEH;;;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,CAavF,CAAC;AAEF,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,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAeV;AA8FD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCA8BrB,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,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,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;;;;;;;GAOG;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,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

@@ -9,7 +9,8 @@
  * (not hierarchical). A file belongs to exactly one primary scope:
  * - APPLICATION: App-level shared files (e.g., branding assets)
  * - ORGANIZATIONS: Org-scoped files (e.g., org documents)
- * - USER_SELF: User-private files within an org context
+ * - USER_SELF: User-private files owned by a single user (NO org — USER_SELF and
+ *   ORGANIZATIONS are independent primary-scope axes; `applicationId` is the bucket anchor)
  *
  * `ANONYMOUS` is intentionally excluded from the file contract for now. The
  * file layer does not yet define anonymous upload, storage, and access semantics
@@ -21,11 +22,22 @@
  * Note: FileMetadata is defined in @wildo-ai/zod-decorators
  */
 import { z } from 'zod';
+import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
 import { FileDisplayNature, FileStorageAccepted, FileUploaderEntityType } from '@wildo-ai/zod-decorators';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
-export { FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+export { FileUploaderEntityType, FileStorageAccepted } from '@wildo-ai/zod-decorators';
 /**
  * File status lifecycle enum
+ *
+ * NOTE — no extraction/indexing members. `EXTRACTING` / `EXTRACTED` / `INDEXED` were removed
+ * 2026-08-26 with the resource-native RAG reshape (plan `resource-rag-capability`, Phase 1):
+ * text extraction and embedding state are per-FIELD, per-CHUNK facts, and the RAG chunk rows
+ * (Phase 2's derived-data tier, keyed `(resourceType, resourceId, fieldName, chunkIndex)` with a
+ * NULLABLE `vector` as the "needs embedding" ledger) carry them. A single file-level status could
+ * never say WHICH field's corpus was current — it was the wrong shape, not merely unused — and
+ * `INDEXED` had already shipped one false claim (written to mean "text was copied", read as
+ * "searchable": https://github.com/wildo-ai/wildo-ai/issues/46). The file lifecycle now ends at
+ * upload/scan/link/erasure concerns, which really are per-file.
  */
 export var FileStatus;
 (function (FileStatus) {
@@ -39,9 +51,35 @@ export var FileStatus;
     FileStatus["CLEAN"] = "clean";
     FileStatus["INFECTED"] = "infected";
     FileStatus["QUARANTINED"] = "quarantined";
-    FileStatus["EXTRACTING"] = "extracting";
-    FileStatus["INDEXED"] = "indexed";
 })(FileStatus || (FileStatus = {}));
+/**
+ * Rendition of a file's bytes requested from the serve route via `?variant=`.
+ *
+ * - `ORIGINAL` — the stored bytes, unchanged (the default when the param is absent).
+ * - `THUMBNAIL` — a small, downscaled `webp` derived on the fly for preview surfaces
+ *   (nav avatar, list/card image) so a preview never pulls a multi-MB original. Only
+ *   raster images are eligible; for any other file the serve route transparently
+ *   falls back to the original bytes.
+ *
+ * This is the WIRE CONTRACT for the serve route's `variant` query parameter — shared
+ * by the frontend (which builds `?variant=thumbnail` preview URLs) and the backend
+ * serve route (which parses it). Keep the string values stable across releases.
+ */
+export var FileServeVariant;
+(function (FileServeVariant) {
+    FileServeVariant["ORIGINAL"] = "original";
+    FileServeVariant["THUMBNAIL"] = "thumbnail";
+})(FileServeVariant || (FileServeVariant = {}));
+/**
+ * Parse an untrusted `?variant=` query value into a {@link FileServeVariant}.
+ * Absent or unrecognized values fall back to `ORIGINAL` (fail-safe: an unknown
+ * variant serves the untransformed bytes rather than erroring).
+ */
+export function parseFileServeVariant(raw) {
+    return raw === FileServeVariant.THUMBNAIL
+        ? FileServeVariant.THUMBNAIL
+        : FileServeVariant.ORIGINAL;
+}
 /**
  * Statuses in which a file's bytes are safe to serve for download.
  *
@@ -55,9 +93,34 @@ export const FILE_DOWNLOADABLE_STATUSES = new Set([
     FileStatus.LINKED,
     FileStatus.ORPHANED,
     FileStatus.CLEAN,
-    FileStatus.EXTRACTING,
-    FileStatus.INDEXED,
 ]);
+/**
+ * Statuses in which a file's own METADATA must no longer be disclosed on the GLOBAL
+ * `GET /files/:fileId/metadata` route (gate **G-FILE**).
+ *
+ * Blocking the BYTES is not enough. A privacy erasure marks the file `DELETED`, but physical cleanup
+ * is a batch that runs much later — so between the two, `originalFilename` (`passport-jane-doe.pdf`)
+ * and `uploadedBy` stayed readable by any member of the file's scope. "Erased" that leaves the
+ * filename readable for weeks is not erased.
+ *
+ * DELIBERATELY NARROWER than {@link FILE_BLOCKED_STATUSES}: `PENDING`, `SCANNING`, `FAILED` and
+ * `INFECTED` files are not servable either, but their metadata IS the diagnostic surface an uploader
+ * legitimately polls ("upload failed", "scan in progress"). Withholding those would break upload UX
+ * while protecting nothing — none of them is an erasure outcome. `DELETED` is the terminal state (it
+ * has no outgoing transition in {@link FILE_STATUS_TRANSITIONS}) and the one an erasure produces.
+ */
+export const FILE_METADATA_WITHHELD_STATUSES = new Set([
+    FileStatus.DELETED,
+]);
+/**
+ * Value written over a file's `filename` / `originalFilename` when the file is erased for privacy.
+ *
+ * Both fields are REQUIRED (`z.string().min(1)`), so an erasure cannot null them without a schema
+ * reshape; overwriting with one shared, non-identifying constant erases the personal data while
+ * keeping the row valid, greppable and obviously-erased in logs and admin surfaces. Deliberately a
+ * fixed constant rather than a per-file token: two erased files must not be distinguishable by name.
+ */
+export const ERASED_FILE_NAME_PLACEHOLDER = '[erased]';
 /**
  * Statuses that represent terminal or non-servable states.
  * Files in these states must not be served for download.
@@ -78,13 +141,11 @@ export const FILE_BLOCKED_STATUSES = new Set([
  */
 export const FILE_STATUS_TRANSITIONS = {
     [FileStatus.PENDING]: [FileStatus.UPLOADED, FileStatus.FAILED],
-    [FileStatus.UPLOADED]: [FileStatus.LINKED, FileStatus.SCANNING, FileStatus.EXTRACTING, FileStatus.ORPHANED, FileStatus.DELETED, FileStatus.FAILED],
+    [FileStatus.UPLOADED]: [FileStatus.LINKED, FileStatus.SCANNING, FileStatus.ORPHANED, FileStatus.DELETED, FileStatus.FAILED],
     [FileStatus.SCANNING]: [FileStatus.CLEAN, FileStatus.INFECTED, FileStatus.FAILED],
-    [FileStatus.CLEAN]: [FileStatus.LINKED, FileStatus.EXTRACTING, FileStatus.ORPHANED, FileStatus.DELETED],
+    [FileStatus.CLEAN]: [FileStatus.LINKED, FileStatus.ORPHANED, FileStatus.DELETED],
     [FileStatus.INFECTED]: [FileStatus.QUARANTINED, FileStatus.DELETED],
     [FileStatus.QUARANTINED]: [FileStatus.DELETED],
-    [FileStatus.EXTRACTING]: [FileStatus.INDEXED, FileStatus.FAILED],
-    [FileStatus.INDEXED]: [FileStatus.LINKED, FileStatus.ORPHANED, FileStatus.DELETED],
     [FileStatus.LINKED]: [FileStatus.ORPHANED, FileStatus.DELETED],
     [FileStatus.ORPHANED]: [FileStatus.LINKED, FileStatus.DELETED],
     [FileStatus.DELETED]: [],
@@ -103,7 +164,7 @@ function validateUploaderPair(file, ctx) {
     const hasUploadedByEntityType = file.uploadedByEntityType !== undefined;
     if (hasUploadedBy !== hasUploadedByEntityType) {
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             path: hasUploadedBy ? ['uploadedByEntityType'] : ['uploadedBy'],
             message: 'uploadedBy and uploadedByEntityType must either both be set or both be omitted',
         });
@@ -117,9 +178,15 @@ export function validateFileScopeIdentifiers(scope) {
         case ResourcePrimaryScope.APPLICATION:
             return hasApplicationId && !hasOrganizationId && !hasUserId;
         case ResourcePrimaryScope.ORGANIZATIONS:
-            return !hasApplicationId && hasOrganizationId && !hasUserId;
+            // applicationId is always required (tenant isolation); organizationId is the scope discriminator.
+            return hasApplicationId && hasOrganizationId && !hasUserId;
         case ResourcePrimaryScope.USER_SELF:
-            return !hasApplicationId && hasOrganizationId && hasUserId;
+            // Primary scopes are a SEPARATION OF CONCERN: USER_SELF and ORGANIZATIONS are
+            // independent axes. A user's self-owned file is user-owned, NOT org-owned —
+            // `userId` is the scope discriminator and `applicationId` is the tenant/bucket
+            // anchor. `organizationId` MUST be absent (a present org would conflate the two
+            // scopes). Fail closed on any org value.
+            return hasApplicationId && hasUserId && !hasOrganizationId;
         default:
             return false;
     }
@@ -140,23 +207,31 @@ export function validateFileScopeIdentifiers(scope) {
  * `storageKey` includes scope path derived from primaryScope:
  * - APPLICATION: `app/{applicationId}/{fileId}`
  * - ORGANIZATIONS: `org/{organizationId}/{fileId}`
- * - USER_SELF: `user/{organizationId}/{userId}/{fileId}`
+ * - USER_SELF: `user/{userId}/{fileId}` (owner is the user; no org segment)
  */
 const FileSchemaBase = z.object({
     fileId: z.string().min(1).isPrimaryKey().isSummaryField(),
     // ========== File Metadata ==========
-    filename: z.string().min(1).isDBIndexed().isSummaryField(),
-    originalFilename: z.string().min(1).isSummaryField(),
+    // USER_CONTENT on both names. A filename is chosen by the person and routinely IS the personal
+    // datum — "scan-2026-medical.pdf" discloses a special category before the file is opened. The
+    // file's BYTES are not a field here (this resource is metadata over object storage), so this is the
+    // only place the content axis can be declared at all.
+    filename: z.string().min(1).isDBIndexed().isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT),
+    originalFilename: z.string().min(1).isSummaryField().dataCategories(PersonalDataCategory.USER_CONTENT),
     mimeType: z.string().min(1).isDBIndexed().isSummaryField(),
     size: z.number().min(0).isSummaryField(),
     extension: z.string().optional(),
     checksum: z.string().optional().isDBIndexed(),
     // ========== Storage ==========
     // `storageProvider` + `storageRef` are the persisted backend-routing truth.
-    storageProvider: z.nativeEnum(FileStorageAccepted).optional().isDBIndexed(),
+    storageProvider: z.enum(FileStorageAccepted).optional().isDBIndexed(),
     storageRef: z.string().min(1).optional().isDBIndexed(),
-    // `storageKey` is still scoped metadata, not the storage backend handle.
-    storageKey: z.string().min(1).isDBIndexed(),
+    // `storageKey` is still scoped metadata, not the storage backend handle. It embeds the
+    // file identity (`_id`, surfaced as the `fileId` virtual), so it is derived + persisted
+    // AFTER the row is created (insert-first) — hence optional at create time. `createFile`
+    // sets it once `_id` exists, and `linkFileToResource` re-derives it when the file's scope
+    // is finalized.
+    storageKey: z.string().min(1).optional().isDBIndexed(),
     url: z.url().optional(), // Cached URL (may be presigned)
     // ========== Status & Lifecycle ==========
     status: z.enum(FileStatus).default(FileStatus.PENDING).isDBIndexed().isSummaryField(),
@@ -183,15 +258,16 @@ const FileSchemaBase = z.object({
     // Derived from parent resource's resourcePrimaryScope when linking
     // Determines access control and storage path
     primaryScope: z.enum(FILE_PRIMARY_SCOPES).optional().isDBIndexed(),
-    // ========== Scope Identifiers (Segregated) ==========
-    // Exactly one set of identifiers is populated based on primaryScope.
-    // These are SEGREGATED (not hierarchical) - a user can belong to multiple orgs.
-    // APPLICATION scope: app-level shared files
-    applicationId: z.string().optional().isDBIndexed(),
-    // ORGANIZATIONS scope: org-scoped files
-    // Also used as context for USER_SELF scope
+    // ========== Scope Identifiers ==========
+    // applicationId is ALWAYS set (from execution context at creation time) — it is the
+    // top-level tenant isolation field present on every file record regardless of primaryScope.
+    // organizationId and userId are populated only when the file's primaryScope requires them.
+    applicationId: z.string().isDBIndexed(),
+    // ORGANIZATIONS scope: org-scoped files. Set ONLY for ORGANIZATIONS-scoped files —
+    // never for USER_SELF (the two scopes are independent axes, separation of concern).
     organizationId: z.string().optional().isDBIndexed(),
-    // USER_SELF scope: user-private files (requires organizationId context)
+    // USER_SELF scope: user-private files owned by one user. Set ONLY for USER_SELF-scoped
+    // files; the owner is the user (no org). `applicationId` is the tenant/bucket anchor.
     userId: z.string().optional().isDBIndexed(),
     // ========== Upload Metadata ==========
     // The uploader principal is persisted as a raw id + type pair only.
@@ -204,16 +280,15 @@ const FileSchemaBase = z.object({
     deletedAt: z.date().optional().isDBIndexed().excludeFromCreate(),
 });
 export const FileSchema = FileSchemaBase.superRefine((file, ctx) => {
-    const hasAnyScopeIdentifier = hasFileScopeIdentifierValue(file.applicationId)
-        || hasFileScopeIdentifierValue(file.organizationId)
-        || hasFileScopeIdentifierValue(file.userId);
     validateUploaderPair(file, ctx);
     if (!file.primaryScope) {
-        if (hasAnyScopeIdentifier) {
+        // Pre-link state: applicationId is always present (set from execution context at upload time),
+        // but organizationId/userId must not be set without a primaryScope discriminator.
+        if (hasFileScopeIdentifierValue(file.organizationId) || hasFileScopeIdentifierValue(file.userId)) {
             ctx.addIssue({
-                code: z.ZodIssueCode.custom,
+                code: 'custom',
                 path: ['primaryScope'],
-                message: 'primaryScope is required when file scope identifiers are present',
+                message: 'primaryScope is required when organizationId or userId are present',
             });
         }
         return;
@@ -225,10 +300,10 @@ export const FileSchema = FileSchemaBase.superRefine((file, ctx) => {
         userId: file.userId,
     })) {
         ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: 'custom',
             path: ['primaryScope'],
             message: 'File scope identifiers must match the declared primaryScope',
         });
     }
 });
-//# sourceMappingURL=files.shared.schemas.js.map
+//# sourceMappingURL=files.shared.schemas.js.map

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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"}
+{"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 * Wave 1 rule: AV scanning is not enforced yet, so UPLOADED and LINKED\n * remain downloadable (optimistic). When AV is active, only CLEAN / LINKED\n * (post-scan) files should be downloadable; SCANNING / INFECTED /\n * QUARANTINED must be blocked.\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\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/files/files.shared.utils.d.ts

@@ -4,7 +4,7 @@
  * Utility class for file scope operations including validation,
  * storage path construction, and scope extraction.
  */
-import { type File, type FileScopeIdentifiers } from './files.shared.schemas.js';
+import { type File, type FileScopeIdentifiers } from './files.shared.schemas';
 /**
  * Utility class for file scope operations.
  * All methods are static and can be called without instantiation.
@@ -13,10 +13,14 @@ export declare class FileScopeUtils {
     /**
      * Validates that scope identifiers are consistent with primaryScope.
      *
+     * applicationId is always required for all scope types — it is the tenant isolation field
+     * set from the execution context at file creation time, regardless of primaryScope.
+     *
      * Rules:
-     * - APPLICATION: requires applicationId
-     * - ORGANIZATIONS: requires organizationId
-     * - USER_SELF: requires organizationId + userId
+     * - APPLICATION: requires applicationId only (no organizationId, no userId)
+     * - ORGANIZATIONS: requires applicationId + organizationId (no userId)
+     * - USER_SELF: requires applicationId + userId, and NO organizationId (USER_SELF and
+     *   ORGANIZATIONS are independent primary-scope axes — a self-owned file is never org-scoped)
      *
      * ANONYMOUS is intentionally not supported for files yet. The file layer
      * fails closed until anonymous file semantics are defined end to end.
@@ -31,7 +35,7 @@ export declare class FileScopeUtils {
      *
      * @param scope - The scope identifiers
      * @param fileId - The file identifier
-     * @returns Path suffix like "org/{orgId}/{fileId}" or "user/{orgId}/{userId}/{fileId}"
+     * @returns Path suffix like "org/{orgId}/{fileId}" or "user/{userId}/{fileId}"
      * @throws Error if primaryScope is unsupported or unknown
      */
     static buildStoragePath(scope: FileScopeIdentifiers, fileId: string): string;

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

@@ -1 +1 @@
-{"version":3,"file":"files.shared.utils.d.ts","sourceRoot":"","sources":["../../../src/files/files.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,oBAAoB,EAC1B,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO;IAIrD;;;;;;;;OAQG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAiB5E;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,oBAAoB,GAAG,IAAI;CAahE"}
+{"version":3,"file":"files.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/files/files.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,oBAAoB,EAC1B,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO;IAIrD;;;;;;;;OAQG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAiB5E;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,oBAAoB,GAAG,IAAI;CAahE"}