@wildo-ai/saas-models 1.0.1

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

@@ -0,0 +1,103 @@
+/**
+ * Files Resource Configuration (Repository-only)
+ *
+ * Provides repository operations for file metadata management.
+ * Files are managed internally by the file upload system.
+ *
+ * ## Scope Model
+ *
+ * Files use a **dynamic scope** that is derived from the parent resource's
+ * resourcePrimaryScope when linked. The FILES resource itself is configured
+ * with ORGANIZATIONS as default primaryScope, but individual file records
+ * store their actual scope in the `primaryScope` field.
+ *
+ * This allows files to be correctly scoped to:
+ * - APPLICATION: App-level shared files
+ * - ORGANIZATIONS: Org-scoped files (default)
+ * - USER_SELF: User-private files
+ *
+ */
+import { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory.js';
+import { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions.js';
+import { ResourceOperationRiskLevel, ResourceOperationVariantType } from '../resources/resources.shared.schemas.js';
+import { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+import { FileSchema } from './files.shared.schemas.js';
+/**
+ * Files Resource Configuration Factory
+ *
+ * Creates a REPOSITORY_ONLY resource configuration for file metadata.
+ * Files are managed internally by the file upload system and not exposed
+ * as standard REST API endpoints. Repository operations are used internally
+ * by FilesBackendService.
+ */
+export const filesResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
+    mainSchema: FileSchema,
+    resourceIdentifier: CoreResourceType.FILES,
+    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,
+        CoreResourceOperation.CREATE,
+        CoreResourceOperation.UPDATE,
+        CoreResourceOperation.DELETE,
+    ],
+    operationsConfiguration: {
+        [CoreResourceOperation.READ]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
+        },
+        [CoreResourceOperation.LIST]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
+        },
+        [CoreResourceOperation.CREATE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
+        },
+        [CoreResourceOperation.UPDATE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
+        },
+        [CoreResourceOperation.DELETE]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_MEMBER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
+        },
+    },
+});
+//# sourceMappingURL=files.shared.resources-config.schemas.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,122 @@
+/**
+ * Files Shared Schemas
+ *
+ * Reusable schemas for file uploads and file handling.
+ *
+ * ## Scope Model
+ *
+ * Files use a **segregated scope model** where scope identifiers are separate fields
+ * (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
+ *
+ * `ANONYMOUS` is intentionally excluded from the file contract for now. The
+ * file layer does not yet define anonymous upload, storage, and access semantics
+ * end to end, so file resources fail closed instead of pretending support.
+ *
+ * Scope is **derived from the parent resource's resourcePrimaryScope** when linking.
+ * Access rights are **inherited from the z_file() field** on the parent resource.
+ *
+ * Note: FileMetadata is defined in @wildo-ai/zod-decorators
+ */
+import { z } from 'zod';
+import { FileDisplayNature, FileStorageAccepted, FileUploaderEntityType, type FileUploaderOwnership } from '@wildo-ai/zod-decorators';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+export type { FileMetadata } from '@wildo-ai/zod-decorators';
+export { FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+export type { FileUploaderOwnership } from '@wildo-ai/zod-decorators';
+/**
+ * File status lifecycle enum
+ */
+export declare enum FileStatus {
+    PENDING = "pending",
+    UPLOADED = "uploaded",
+    LINKED = "linked",
+    DELETED = "deleted",
+    ORPHANED = "orphaned",
+    FAILED = "failed",
+    SCANNING = "scanning",
+    CLEAN = "clean",
+    INFECTED = "infected",
+    QUARANTINED = "quarantined",
+    EXTRACTING = "extracting",
+    INDEXED = "indexed"
+}
+/**
+ * Statuses in which a file's bytes are safe to serve for download.
+ *
+ * Wave 1 rule: AV scanning is not enforced yet, so UPLOADED and LINKED
+ * remain downloadable (optimistic). When AV is active, only CLEAN / LINKED
+ * (post-scan) files should be downloadable; SCANNING / INFECTED /
+ * QUARANTINED must be blocked.
+ */
+export declare const FILE_DOWNLOADABLE_STATUSES: ReadonlySet<FileStatus>;
+/**
+ * Statuses that represent terminal or non-servable states.
+ * Files in these states must not be served for download.
+ */
+export declare const FILE_BLOCKED_STATUSES: ReadonlySet<FileStatus>;
+/**
+ * Valid lifecycle transitions.
+ *
+ * Each key is a source status; the value is the set of statuses it can
+ * transition to. Any transition not listed here is invalid.
+ */
+export declare const FILE_STATUS_TRANSITIONS: Readonly<Record<FileStatus, readonly FileStatus[]>>;
+export declare const FILE_PRIMARY_SCOPES: readonly [ResourcePrimaryScope.APPLICATION, ResourcePrimaryScope.ORGANIZATIONS, ResourcePrimaryScope.USER_SELF];
+export type FilePrimaryScope = (typeof FILE_PRIMARY_SCOPES)[number];
+export declare function validateFileScopeIdentifiers(scope: {
+    primaryScope: FilePrimaryScope;
+    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>;
+    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>;
+    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>>>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    thumbnailUrl: z.ZodOptional<z.ZodURL>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    pageCount: z.ZodOptional<z.ZodNumber>;
+    linkedResourceType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    linkedResourceId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    linkedFieldName: z.ZodOptional<z.ZodString>;
+    primaryScope: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<{
+        user_self: ResourcePrimaryScope.USER_SELF;
+        organizations: ResourcePrimaryScope.ORGANIZATIONS;
+        applications: ResourcePrimaryScope.APPLICATION;
+    }>>>;
+    applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<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>>;
+    uploadedByEntityType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<typeof FileUploaderEntityType>>>;
+    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>;
+export type File = z.infer<typeof FileSchema> & FileUploaderOwnership;
+/**
+ * Scope identifiers for file access control.
+ * Populated based on primaryScope when file is created/linked.
+ */
+export interface FileScopeIdentifiers {
+    primaryScope: FilePrimaryScope;
+    applicationId?: string;
+    organizationId?: string;
+    userId?: string;
+}
+//# sourceMappingURL=files.shared.schemas.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,234 @@
+/**
+ * Files Shared Schemas
+ *
+ * Reusable schemas for file uploads and file handling.
+ *
+ * ## Scope Model
+ *
+ * Files use a **segregated scope model** where scope identifiers are separate fields
+ * (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
+ *
+ * `ANONYMOUS` is intentionally excluded from the file contract for now. The
+ * file layer does not yet define anonymous upload, storage, and access semantics
+ * end to end, so file resources fail closed instead of pretending support.
+ *
+ * Scope is **derived from the parent resource's resourcePrimaryScope** when linking.
+ * Access rights are **inherited from the z_file() field** on the parent resource.
+ *
+ * Note: FileMetadata is defined in @wildo-ai/zod-decorators
+ */
+import { z } from 'zod';
+import { FileDisplayNature, FileStorageAccepted, FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+export { FileUploaderEntityType } from '@wildo-ai/zod-decorators';
+/**
+ * File status lifecycle enum
+ */
+export var FileStatus;
+(function (FileStatus) {
+    FileStatus["PENDING"] = "pending";
+    FileStatus["UPLOADED"] = "uploaded";
+    FileStatus["LINKED"] = "linked";
+    FileStatus["DELETED"] = "deleted";
+    FileStatus["ORPHANED"] = "orphaned";
+    FileStatus["FAILED"] = "failed";
+    FileStatus["SCANNING"] = "scanning";
+    FileStatus["CLEAN"] = "clean";
+    FileStatus["INFECTED"] = "infected";
+    FileStatus["QUARANTINED"] = "quarantined";
+    FileStatus["EXTRACTING"] = "extracting";
+    FileStatus["INDEXED"] = "indexed";
+})(FileStatus || (FileStatus = {}));
+/**
+ * Statuses in which a file's bytes are safe to serve for download.
+ *
+ * Wave 1 rule: AV scanning is not enforced yet, so UPLOADED and LINKED
+ * remain downloadable (optimistic). When AV is active, only CLEAN / LINKED
+ * (post-scan) files should be downloadable; SCANNING / INFECTED /
+ * QUARANTINED must be blocked.
+ */
+export const FILE_DOWNLOADABLE_STATUSES = new Set([
+    FileStatus.UPLOADED,
+    FileStatus.LINKED,
+    FileStatus.ORPHANED,
+    FileStatus.CLEAN,
+    FileStatus.EXTRACTING,
+    FileStatus.INDEXED,
+]);
+/**
+ * Statuses that represent terminal or non-servable states.
+ * Files in these states must not be served for download.
+ */
+export const FILE_BLOCKED_STATUSES = new Set([
+    FileStatus.PENDING,
+    FileStatus.DELETED,
+    FileStatus.FAILED,
+    FileStatus.SCANNING,
+    FileStatus.INFECTED,
+    FileStatus.QUARANTINED,
+]);
+/**
+ * Valid lifecycle transitions.
+ *
+ * Each key is a source status; the value is the set of statuses it can
+ * transition to. Any transition not listed here is invalid.
+ */
+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.SCANNING]: [FileStatus.CLEAN, FileStatus.INFECTED, FileStatus.FAILED],
+    [FileStatus.CLEAN]: [FileStatus.LINKED, FileStatus.EXTRACTING, 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]: [],
+    [FileStatus.FAILED]: [FileStatus.DELETED],
+};
+export const FILE_PRIMARY_SCOPES = [
+    ResourcePrimaryScope.APPLICATION,
+    ResourcePrimaryScope.ORGANIZATIONS,
+    ResourcePrimaryScope.USER_SELF,
+];
+function hasFileScopeIdentifierValue(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function validateUploaderPair(file, ctx) {
+    const hasUploadedBy = hasFileScopeIdentifierValue(file.uploadedBy);
+    const hasUploadedByEntityType = file.uploadedByEntityType !== undefined;
+    if (hasUploadedBy !== hasUploadedByEntityType) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: hasUploadedBy ? ['uploadedByEntityType'] : ['uploadedBy'],
+            message: 'uploadedBy and uploadedByEntityType must either both be set or both be omitted',
+        });
+    }
+}
+export function validateFileScopeIdentifiers(scope) {
+    const hasApplicationId = hasFileScopeIdentifierValue(scope.applicationId);
+    const hasOrganizationId = hasFileScopeIdentifierValue(scope.organizationId);
+    const hasUserId = hasFileScopeIdentifierValue(scope.userId);
+    switch (scope.primaryScope) {
+        case ResourcePrimaryScope.APPLICATION:
+            return hasApplicationId && !hasOrganizationId && !hasUserId;
+        case ResourcePrimaryScope.ORGANIZATIONS:
+            return !hasApplicationId && hasOrganizationId && !hasUserId;
+        case ResourcePrimaryScope.USER_SELF:
+            return !hasApplicationId && hasOrganizationId && hasUserId;
+        default:
+            return false;
+    }
+}
+/**
+ * File resource schema
+ *
+ * Stores file metadata and links files to resources.
+ * Files are stored via app-managed storage providers (MinIO/S3, local directory, etc.),
+ * this schema tracks metadata only.
+ *
+ * ## Storage Identity Convention
+ * `storageProvider` + `storageRef` are the persisted routing truth used to
+ * reach the active storage backend. `storageKey` remains framework metadata
+ * that captures the file's derived scope path for bookkeeping, diagnostics,
+ * and future storage contract evolution.
+ *
+ * `storageKey` includes scope path derived from primaryScope:
+ * - APPLICATION: `app/{applicationId}/{fileId}`
+ * - ORGANIZATIONS: `org/{organizationId}/{fileId}`
+ * - USER_SELF: `user/{organizationId}/{userId}/{fileId}`
+ */
+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(),
+    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(),
+    storageRef: z.string().min(1).optional().isDBIndexed(),
+    // `storageKey` is still scoped metadata, not the storage backend handle.
+    storageKey: z.string().min(1).isDBIndexed(),
+    url: z.url().optional(), // Cached URL (may be presigned)
+    // ========== Status & Lifecycle ==========
+    status: z.enum(FileStatus).default(FileStatus.PENDING).isDBIndexed().isSummaryField(),
+    // ========== Nature-specific Metadata ==========
+    // Inferred from MIME type or set by analysis services (F4-03)
+    // Resolved display nature (IMAGE/VIDEO/AUDIO/DOCUMENT/GENERIC) — NOT the schema-level FileNature.
+    // Set by resolveFileDisplayNature() during upload or inferred from MIME type in toMetadataResponse().
+    // Schema declares FileNature (e.g., PDF, OFFICE), but the DB stores the resolved FileDisplayNature.
+    nature: z.enum(FileDisplayNature).optional().isDBIndexed(),
+    // Image-specific
+    width: z.number().positive().optional(),
+    height: z.number().positive().optional(),
+    thumbnailUrl: z.url().optional(),
+    // Video/Audio-specific (populated by IFileVideoAnalyzer / IFileAudioAnalyzer)
+    duration: z.number().positive().optional(), // Duration in seconds
+    // Document-specific (populated by IFileDocumentAnalyzer)
+    pageCount: z.number().positive().optional(),
+    // ========== Resource Linking ==========
+    // When linked, scope is derived from parent resource's resourcePrimaryScope
+    linkedResourceType: z.string().optional().isDBIndexed(),
+    linkedResourceId: z.string().optional().isDBIndexed(),
+    linkedFieldName: z.string().optional(),
+    // ========== Primary Scope ==========
+    // 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
+    organizationId: z.string().optional().isDBIndexed(),
+    // USER_SELF scope: user-private files (requires organizationId context)
+    userId: z.string().optional().isDBIndexed(),
+    // ========== Upload Metadata ==========
+    // The uploader principal is persisted as a raw id + type pair only.
+    // Any richer label/entity hydration is intentionally client-driven.
+    uploadedBy: z.string().trim().min(1).optional().isDBIndexed(),
+    uploadedByEntityType: z.enum(FileUploaderEntityType).optional().isDBIndexed(),
+    // ========== Timestamps ==========
+    uploadedAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    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) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['primaryScope'],
+                message: 'primaryScope is required when file scope identifiers are present',
+            });
+        }
+        return;
+    }
+    if (!validateFileScopeIdentifiers({
+        primaryScope: file.primaryScope,
+        applicationId: file.applicationId,
+        organizationId: file.organizationId,
+        userId: file.userId,
+    })) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['primaryScope'],
+            message: 'File scope identifiers must match the declared primaryScope',
+        });
+    }
+});
+//# sourceMappingURL=files.shared.schemas.js.map

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

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

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

@@ -0,0 +1,46 @@
+/**
+ * File Scope Utilities
+ *
+ * Utility class for file scope operations including validation,
+ * storage path construction, and scope extraction.
+ */
+import { type File, type FileScopeIdentifiers } from './files.shared.schemas.js';
+/**
+ * Utility class for file scope operations.
+ * All methods are static and can be called without instantiation.
+ */
+export declare class FileScopeUtils {
+    /**
+     * Validates that scope identifiers are consistent with primaryScope.
+     *
+     * Rules:
+     * - APPLICATION: requires applicationId
+     * - ORGANIZATIONS: requires organizationId
+     * - USER_SELF: requires organizationId + userId
+     *
+     * ANONYMOUS is intentionally not supported for files yet. The file layer
+     * fails closed until anonymous file semantics are defined end to end.
+     *
+     * @param scope - The scope identifiers to validate
+     * @returns true if valid, false otherwise
+     */
+    static validate(scope: FileScopeIdentifiers): boolean;
+    /**
+     * Builds storage path suffix based on scope identifiers.
+     * Full path is constructed by gateway as: applications/{appId}/environments/{appEnv}/files/{scopePath}
+     *
+     * @param scope - The scope identifiers
+     * @param fileId - The file identifier
+     * @returns Path suffix like "org/{orgId}/{fileId}" or "user/{orgId}/{userId}/{fileId}"
+     * @throws Error if primaryScope is unsupported or unknown
+     */
+    static buildStoragePath(scope: FileScopeIdentifiers, fileId: string): string;
+    /**
+     * Extracts scope identifiers from a File record.
+     *
+     * @param file - The file record to extract scope from
+     * @returns FileScopeIdentifiers if primaryScope is set, null otherwise
+     */
+    static extractFromFile(file: File): FileScopeIdentifiers | null;
+}
+//# sourceMappingURL=files.shared.utils.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,74 @@
+/**
+ * File Scope Utilities
+ *
+ * Utility class for file scope operations including validation,
+ * storage path construction, and scope extraction.
+ */
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { validateFileScopeIdentifiers, } from './files.shared.schemas.js';
+/**
+ * Utility class for file scope operations.
+ * All methods are static and can be called without instantiation.
+ */
+export class FileScopeUtils {
+    /**
+     * Validates that scope identifiers are consistent with primaryScope.
+     *
+     * Rules:
+     * - APPLICATION: requires applicationId
+     * - ORGANIZATIONS: requires organizationId
+     * - USER_SELF: requires organizationId + userId
+     *
+     * ANONYMOUS is intentionally not supported for files yet. The file layer
+     * fails closed until anonymous file semantics are defined end to end.
+     *
+     * @param scope - The scope identifiers to validate
+     * @returns true if valid, false otherwise
+     */
+    static validate(scope) {
+        return validateFileScopeIdentifiers(scope);
+    }
+    /**
+     * Builds storage path suffix based on scope identifiers.
+     * Full path is constructed by gateway as: applications/{appId}/environments/{appEnv}/files/{scopePath}
+     *
+     * @param scope - The scope identifiers
+     * @param fileId - The file identifier
+     * @returns Path suffix like "org/{orgId}/{fileId}" or "user/{orgId}/{userId}/{fileId}"
+     * @throws Error if primaryScope is unsupported or unknown
+     */
+    static buildStoragePath(scope, fileId) {
+        if (!this.validate(scope)) {
+            throw new Error(`Invalid scope identifiers for primaryScope: ${scope.primaryScope}`);
+        }
+        switch (scope.primaryScope) {
+            case ResourcePrimaryScope.APPLICATION:
+                return `app/${scope.applicationId}/${fileId}`;
+            case ResourcePrimaryScope.ORGANIZATIONS:
+                return `org/${scope.organizationId}/${fileId}`;
+            case ResourcePrimaryScope.USER_SELF:
+                return `user/${scope.organizationId}/${scope.userId}/${fileId}`;
+            default:
+                throw new Error(`Unknown primaryScope: ${scope.primaryScope}`);
+        }
+    }
+    /**
+     * Extracts scope identifiers from a File record.
+     *
+     * @param file - The file record to extract scope from
+     * @returns FileScopeIdentifiers if primaryScope is set, null otherwise
+     */
+    static extractFromFile(file) {
+        if (!file.primaryScope) {
+            return null;
+        }
+        const scope = {
+            primaryScope: file.primaryScope,
+            applicationId: file.applicationId,
+            organizationId: file.organizationId,
+            userId: file.userId,
+        };
+        return this.validate(scope) ? scope : null;
+    }
+}
+//# sourceMappingURL=files.shared.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.shared.utils.js","sourceRoot":"","sources":["../../../src/files/files.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,4BAA4B,GAG7B,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,MAAM,OAAO,cAAc;IACzB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,QAAQ,CAAC,KAA2B;QACzC,OAAO,4BAA4B,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAA2B,EAAE,MAAc;QACjE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,+CAA+C,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;QACvF,CAAC;QAED,QAAQ,KAAK,CAAC,YAAY,EAAE,CAAC;YAC3B,KAAK,oBAAoB,CAAC,WAAW;gBACnC,OAAO,OAAO,KAAK,CAAC,aAAa,IAAI,MAAM,EAAE,CAAC;YAChD,KAAK,oBAAoB,CAAC,aAAa;gBACrC,OAAO,OAAO,KAAK,CAAC,cAAc,IAAI,MAAM,EAAE,CAAC;YACjD,KAAK,oBAAoB,CAAC,SAAS;gBACjC,OAAO,QAAQ,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YAClE;gBACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,IAAU;QAC/B,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,GAAG;YACZ,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;QAEF,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;CACF"}