@ai-matrx/media 0.8.0 → 0.9.0

package/dist/files/engine/types.d.ts

@@ -0,0 +1,1081 @@
+/**
+ * features/files/types.ts
+ *
+ * Single source of truth for all cloud-files types. Import from
+ * `@/features/files/types` — never duplicate types in feature subfolders.
+ *
+ * LAYERS
+ * ------
+ *   1. Domain types    — camelCase, what components and Redux work with.
+ *   2. DB row types    — snake_case, derived from Supabase-generated `Database`.
+ *   3. API types       — from Python OpenAPI-generated `components["schemas"]`.
+ *   4. Runtime records — domain types + dirty/loading/error metadata for Redux.
+ *   5. Tree & UI types — normalized structure + UI state shapes.
+ *   6. Upload types    — upload orchestrator state.
+ *   7. Error types     — re-export of BackendApiError, plus files-specific codes.
+ *
+ * Do NOT duplicate or re-declare any type from here in feature subfolders.
+ */
+import type { components } from "@ai-matrx/agents/generated/api-types";
+import type { Database } from "./db-types.js";
+import type { FieldFlags } from "@ai-matrx/agents/field-flags";
+import type { readFileRowById } from "./filesDb.js";
+/**
+ * THE canonical `platform.visibility` enum, in enum order:
+ * `personal < internal < link < public`. Identical on the server
+ * (`matrx_utils.visibility.VisibilityLiteral`) and in the DB. One vocabulary,
+ * no per-domain dialect.
+ *
+ * Two bugs are fossilized here; do not reintroduce either.
+ *
+ * 1. `internal` was folded into `personal` on read until 2026-07-26, so a file
+ *    readable by an entire organization was labelled "Only you" everywhere.
+ *    Never collapse a level to shrink this union — they are different facts.
+ *
+ * 2. This domain used to call `link` "shared". That is NOT a synonym: `shared`
+ *    was RETIRED from the DB enum on 2026-07-21, and the server's legacy map
+ *    reconciles it to `personal`. So the old code read `link` as `"shared"`
+ *    and, on any write-back, silently DOWNGRADED the file to `personal`.
+ *    Never send `shared` or `private` to the server.
+ */
+import type { Visibility, PermissionLevel, MediaRef, FileIdentityHint } from "../../files.js";
+export type { Visibility, PermissionLevel, MediaRef, FileIdentityHint };
+export type ResourceType = "file" | "folder";
+/**
+ * Who a grant targets. Mirrors the canonical `iam.permissions` three-way
+ * mutual exclusion (CHECK `user_or_org_or_public`): exactly one of a user, an
+ * organization, or the public sentinel per row.
+ *   - `"user"`   — `granted_to_user_id` set; `granteeId` is that user id.
+ *   - `"group"`  — `granted_to_organization_id` set; `granteeId` is that org id.
+ *   - `"public"` — `is_public = true`; there is NO grantee id, so `granteeId`
+ *                  carries the permission row's own id (never `""`). A public
+ *                  grant is "anyone with access", not a member — member/avatar
+ *                  UIs must exclude it, and it is revoked by flipping the
+ *                  resource's visibility (see `features/sharing/FEATURE.md`),
+ *                  not via the by-grantee-id REST endpoint.
+ */
+export type GranteeType = "user" | "group" | "public";
+/**
+ * Metadata a caller may already know when all it has is a durable file id.
+ * These values seed the canonical Redux record before field hydration runs;
+ * omitted keys remain genuinely unloaded and are fetched on demand.
+ */
+type FilesTables = Database["files"]["Tables"];
+type IamTables = Database["iam"]["Tables"];
+export type CloudFileRow = FilesTables["files"]["Row"];
+export type CloudFileInsert = FilesTables["files"]["Insert"];
+export type CloudFileUpdate = FilesTables["files"]["Update"];
+/**
+ * What the client is actually ALLOWED to read from `files.files` — DERIVED from
+ * `FILES_TABLE_COLUMNS` (the ONE canonical select, in [filesDb.ts](./filesDb.ts))
+ * rather than declared beside it, so the two can never disagree.
+ *
+ * `files.files` grants `authenticated` NO table-level SELECT: every readable
+ * column carries its own column grant, which is how the server-only native
+ * storage location stays server-only. So a column ADDED to the table is
+ * readable by nobody until a migration grants it, and a column list that names
+ * an ungranted column fails the WHOLE read with "permission denied for table
+ * files". Subtracting one name from the generated Row type therefore described
+ * a row the client cannot actually read: on 2026-09-13 the table gained
+ * `origin_device_id` and `client_modified_at` (folder-sync 028, no client
+ * grant then) and every selected row stopped matching this type. Deriving from
+ * the query makes the select list the single truth. (2026-09-24: `authenticated`
+ * now holds SELECT on `origin_device_id` and `artifact_kind`, verified live, and
+ * both are in the select list — Recents needs the first.)
+ *
+ * Same deal for `file_versions` via `FILE_VERSIONS_TABLE_COLUMNS`.
+ */
+export type CloudFileReadRow = NonNullable<Awaited<ReturnType<typeof readFileRowById>>>;
+export type CloudFileVersionReadRow = Omit<FilesTables["file_versions"]["Row"], "storage_uri" | "custom_fields">;
+export type CloudFolderRow = FilesTables["folders"]["Row"];
+export type CloudFolderInsert = FilesTables["folders"]["Insert"];
+export type CloudFolderUpdate = FilesTables["folders"]["Update"];
+export type CloudFileVersionRow = FilesTables["file_versions"]["Row"];
+/**
+ * File-permission grants live in the CANONICAL grant store `iam.permissions`
+ * (resource_type='file'), NOT in the legacy cld_ file-permission duplicate
+ * (deprecated in the 2026 DB cutover — see docs/db_rebuild/03-app-agent-cutover-instructions.md §1a).
+ */
+export type CloudFilePermissionRow = IamTables["permissions"]["Row"];
+/**
+ * Summary JSON returned by `iam.fn_list_resource_permissions` and
+ * `iam.fn_grant_resource_permission` — NOT a full `iam.permissions` row.
+ * Maps grantee/org columns into `grantee_id` + `grantee_type` and file-level
+ * `read|write|admin` permission strings.
+ */
+export interface IamResourcePermissionRpcRow {
+    resource_id: string;
+    resource_type: string;
+    grantee_id: string;
+    grantee_type: string;
+    permission_level: string;
+    granted_by: string | null;
+    expires_at: string | null;
+}
+export type FileRecordApi = components["schemas"]["FileRecord"];
+export type FileUploadResponse = components["schemas"]["FileUploadResponse"];
+export type FilePatchRequest = components["schemas"]["FilePatchRequest"];
+export type GrantPermissionRequest = components["schemas"]["GrantPermissionRequest"];
+/**
+ * Discriminator on every cloud-file record. Real records are bytes in S3;
+ * virtual records are Postgres rows surfaced by a `VirtualSourceAdapter`
+ * (Notes, Agent Apps, Tool UIs, code-files snippets, etc.) — see
+ * [features/files/virtual-sources/types.ts](./virtual-sources/types.ts).
+ *
+ * The `source` field defaults to `{ kind: "real" }` everywhere so existing
+ * callers compile unchanged. Synthetic ids of shape
+ * `vfs:<adapterId>:<virtualId>[:<fieldId>]` keep the cloud-files Redux
+ * `filesById` / `foldersById` maps a single keyspace.
+ */
+export type FileSource = {
+    kind: "real";
+} | {
+    kind: "virtual";
+    adapterId: string;
+    virtualId: string;
+    fieldId?: string;
+};
+export interface CloudFile {
+    id: string;
+    ownerId: string;
+    /** Canonical owning workspace from `files.files.organization_id`. */
+    organizationId?: string | null;
+    filePath: string;
+    fileName: string;
+    mimeType: string | null;
+    fileSize: number | null;
+    checksum: string | null;
+    visibility: Visibility;
+    currentVersion: number;
+    parentFolderId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+    /**
+     * Permanent CDN URL (Cloudflare-fronted) when the file is public AND
+     * the server has the CDN feature enabled. ``null`` otherwise — callers
+     * should fall back to ``useFileSrc({ kind: "file_id", fileId })`` for the durable URL.
+     *
+     * Carries a ``?v=<checksum[:8]>`` cache-buster so a content change
+     * invalidates the cache instantly. **Do not strip the query string.**
+     *
+     * Populated by the API converter (``apiFileRecordToCloudFile``);
+     * always ``null`` for rows that came in via the direct DB read path
+     * because the DB has no ``public_url`` column — it's computed
+     * server-side from visibility + storage location + checksum. For DB-sourced
+     * rows, fall back to ``useFileSrc({ kind: "file_id", fileId })`` to fetch the canonical
+     * URL (which the server returns as a CDN URL when applicable).
+     */
+    publicUrl: string | null;
+    /**
+     * The DURABLE URL envelope the REST `FileRecord` carries. `url` is the
+     * server's canonical always-renderable pick (CDN for public, the durable
+     * `/files/{id}/download?inline=1` route for private — authenticated by
+     * the `mx_files_session` cookie). `cdnUrl` is public-only and permanent.
+     * `downloadUrl` carries attachment disposition. None of them expire.
+     *
+     * These are populated by `apiFileRecordToCloudFile` from the REST
+     * response. They are `null` on the direct-DB read path (the `cld_files`
+     * table has no computed-URL columns) — DB-sourced rows build the durable
+     * URL from the file id via the resolver.
+     */
+    url: string | null;
+    cdnUrl: string | null;
+    downloadUrl: string | null;
+    /**
+     * Backend-rendered thumbnail URL (Phase 1b universal thumbnails). Set
+     * for **every** uploaded file regardless of MIME — Python now renders
+     * SOCIAL_BASELINE variants (og_url / thumbnail_url / tiny_url) for
+     * images, PDFs (page 1), videos (10%-mark frame), audio (waveform),
+     * and even archives / text / unknown mimes (mime-family icon PNGs).
+     *
+     * Populated by `apiFileRecordToCloudFile` from `FileRecord.thumbnail_url`
+     * — the REST response field. The server resolves this from the
+     * variants store at request time (post-Phase-1b the legacy
+     * `cld_files.thumbnail_url` column is dropped).
+     *
+     * `null` for rows coming in via the direct Supabase read path — the
+     * row doesn't carry resolved URLs. Those callers should fall back to
+     * `useFileAsset(fileId)` and read `asset.variants["thumbnail_url"].url`,
+     * or `MediaThumbnail` will fall back to the category icon.
+     *
+     * Phase 1c: PDFs additionally get `Asset.variants["page1_url"]`
+     * (page 1 at 150 DPI ~1200×1700) for full-page detail views, and
+     * videos get `Asset.variants["poster_url"]` (native-res frame) for
+     * the HTML5 `<video poster>` attribute. Those are separate from this
+     * `thumbnailUrl` field and require the asset fetch.
+     */
+    thumbnailUrl: string | null;
+    /** Real S3-backed bytes vs. virtual Postgres-backed adapter row. */
+    source: FileSource;
+    /**
+     * Binary lineage — points to the cld_files row this one was derived
+     * from (e.g. "extracted text from this PDF" or "page range 5–10 of
+     * the parent PDF"). Set by Phase 4A migration `0006_cld_files_lineage`.
+     * Null when the file was uploaded directly with no derivation.
+     * Optional on the FE because it is null for nearly every existing
+     * file and was added to the API after the initial schema landed.
+     */
+    parentFileId?: string | null;
+    /**
+     * Free-form classifier set by the deriving system: "pdf_text_extract",
+     * "page_range_5_10", "ocr_re_run", "merge", … Used by lineage chips
+     * to label *how* the parent relates to this file.
+     */
+    derivationKind?: string | null;
+    derivationMetadata?: Record<string, unknown> | null;
+    /**
+     * The registered device (`public.app_instances.id`) that wrote this row — a
+     * desktop sync client — or null for an in-app write. A device's write is the
+     * person's file but never their recent activity: Recents keys on this via
+     * `isRecentActivityFile` (mirror of `files.is_recent_activity`).
+     */
+    originDeviceId?: string | null;
+    /**
+     * When set, this row is a deliberate parallel copy of `duplicateOfFileId`
+     * (the keeper). Set by:
+     *   - the dedup consolidation script (soft-deletes the duplicate row +
+     *     stamps the keeper's id here so refs to the dup still resolve), or
+     *   - `intent: "force_new_copy"` uploads (user explicitly asked for a
+     *     second copy of identical content).
+     * Null for every freshly-uploaded file.
+     *
+     * UI: surface a "duplicate of <keeper>" chip on rows where this is set.
+     * Refs that hit a `deletedAt != null` row should `useFile(duplicateOfFileId)`
+     * to follow the chain to the live keeper.
+     */
+    duplicateOfFileId?: string | null;
+    /**
+     * Points at the "official" `processed_documents.id` for this file —
+     * the canonical text-extraction row out of potentially many re_extract /
+     * re_clean variants. UIs that show "extracted text" or feed Knowledge should
+     * use this column to find THE extract, not the freshest one.
+     */
+    canonicalProcessedDocumentId?: string | null;
+}
+export interface CloudFolder {
+    id: string;
+    ownerId: string;
+    folderPath: string;
+    folderName: string;
+    parentId: string | null;
+    visibility: Visibility;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+    /** Real cloud-folder vs. virtual adapter root / nested adapter folder. */
+    source: FileSource;
+}
+export interface CloudFileVersion {
+    id: string;
+    fileId: string;
+    versionNumber: number;
+    fileSize: number | null;
+    checksum: string | null;
+    createdBy: string | null;
+    createdAt: string;
+    changeSummary: string | null;
+}
+export interface CloudFilePermission {
+    id: string;
+    resourceId: string;
+    resourceType: ResourceType;
+    granteeId: string;
+    granteeType: GranteeType;
+    permissionLevel: PermissionLevel;
+    grantedBy: string | null;
+    grantedAt: string;
+    expiresAt: string | null;
+}
+/**
+ * A canonical share link (`platform.share_links`) scoped to a file or folder.
+ * Minted/listed/revoked via the canonical RPC family (`create_share_link` /
+ * `list_share_links` / `revoke_share_link` — see `utils/permissions/shareLinks.ts`).
+ */
+export interface CloudShareLink {
+    id: string;
+    resourceId: string;
+    resourceType: ResourceType;
+    shareToken: string;
+    permissionLevel: "viewer" | "editor";
+    label: string | null;
+    createdAt: string | null;
+    expiresAt: string | null;
+    maxUses: number | null;
+    useCount: number;
+    isActive: boolean;
+}
+export interface CloudTreeFileRow {
+    kind: "file";
+    id: string;
+    file_path: string;
+    file_name: string;
+    parent_folder_id: string | null;
+    mime_type: string | null;
+    /**
+     * File size in bytes. Renamed from `file_size` in Phase 0 (see
+     * docs/PYTHON_UPDATES.md §3). The RPC `tree_for_owner` (and friends)
+     * now returns `size_bytes`; converters read both names defensively
+     * during the transition. Consumers should always read `size_bytes`.
+     */
+    size_bytes: number | null;
+    visibility: Visibility;
+    current_version: number;
+    effective_permission: PermissionLevel | null;
+    owner_id: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    /** Device that wrote the row (desktop sync), null for an in-app write. */
+    origin_device_id: string | null;
+    /**
+     * The row's metadata as the RPC returns it — carries `system_artifact`, the
+     * marker every file list reads through `isListedFile` (2026-09-29; the tree
+     * used to drop it, so system files could not be told apart in the store).
+     */
+    metadata: Record<string, unknown>;
+}
+export interface CloudTreeFolderRow {
+    kind: "folder";
+    id: string;
+    folder_path: string;
+    folder_name: string;
+    parent_id: string | null;
+    visibility: Visibility;
+    effective_permission: PermissionLevel | null;
+    owner_id: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    metadata: Record<string, unknown>;
+}
+export type CloudTreeRow = CloudTreeFileRow | CloudTreeFolderRow;
+export interface RuntimeMetadata<K extends string> {
+    _dirty: boolean;
+    _dirtyFields: FieldFlags<K>;
+    _loadedFields: FieldFlags<K>;
+    _loading: boolean;
+    _error: string | null;
+    _pendingRequestIds: string[];
+}
+export type CloudFileFieldSnapshot = Partial<Pick<CloudFile, "fileName" | "filePath" | "visibility" | "parentFolderId" | "metadata" | "deletedAt">>;
+export interface CloudFileRecord extends CloudFile, RuntimeMetadata<keyof CloudFile> {
+    _fieldHistory: CloudFileFieldSnapshot;
+}
+export type CloudFolderFieldSnapshot = Partial<Pick<CloudFolder, "folderName" | "folderPath" | "parentId" | "visibility" | "metadata">>;
+export interface CloudFolderRecord extends CloudFolder, RuntimeMetadata<keyof CloudFolder> {
+    _fieldHistory: CloudFolderFieldSnapshot;
+}
+export interface TreeChildren {
+    folderIds: string[];
+    fileIds: string[];
+}
+export interface TreeState {
+    rootFolderIds: string[];
+    rootFileIds: string[];
+    childrenByFolderId: Record<string, TreeChildren>;
+    fullyLoadedFolderIds: Record<string, true>;
+    status: "idle" | "loading" | "loaded" | "error";
+    error: string | null;
+    lastReconciledAt: number | null;
+}
+export type ViewMode = "list" | "grid" | "columns";
+/**
+ * Sticky filter chips above the file table. Mirrors the `FilterChips`
+ * component's union — re-declared here (not imported) so the slice
+ * stays component-cycle-free. Keep in sync with
+ * `features/files/components/surfaces/desktop/FilterChips.tsx`.
+ */
+export type ChipFilter = "recents" | "starred";
+/**
+ * Column sort keys. Mirror the file-table columns so users can sort by any
+ * column they're looking at. Folders always group ahead of files regardless
+ * of the active key (Box / Drive / Dropbox convention) — see `compareNodes`.
+ */
+export type SortBy = "name" | "type" | "extension" | "mime" | "path" | "owner" | "size" | "version" | "updated_at" | "created_at";
+export type SortDirection = "asc" | "desc";
+/** Whether the file table shows files only, folders only, or both. */
+export type KindFilter = "all" | "files" | "folders";
+/** Optional details surface (extension, mime, dimensions, etc.) on rows. */
+export type DetailsLevel = "compact" | "extended";
+/** Modified-date preset filter — "today", "week" = last 7d, "month" = last 30d. */
+export type ModifiedFilter = "any" | "today" | "week" | "month";
+/** Size preset filter — buckets familiar to users. */
+export type SizeFilter = "any" | "small" | "medium" | "large" | "huge";
+/**
+ * Access (visibility) filter. One option per `Visibility` level plus "any" —
+ * a level with no option is a level whose rows can never be filtered to.
+ */
+export type AccessFilter = "any" | Visibility;
+/**
+ * Type filter — multi-select set of file categories (CODE, DOCUMENT, IMAGE,
+ * VIDEO, …). Empty array = "any type". Modeled as `string[]` (not the
+ * `FileCategory` enum from `utils/file-types.ts`) to keep the slice type
+ * import-cycle-free; the selectors / pickers cast at the boundary.
+ */
+export type TypeFilter = string[];
+/** Owner filter — multi-select set of owner user ids. Empty = "any owner". */
+export type OwnerFilter = string[];
+/**
+ * Per-file Knowledge indexing status.
+ *
+ *   - `indexed`     — backend has a `processed_documents` row for this file
+ *   - `not_indexed` — file exists but no doc row (`/files/{id}/document` 404)
+ *   - `pending`     — request is in flight
+ *   - `unknown`     — endpoint returned a transient error or hasn't been
+ *                     called yet for this file
+ *
+ * The pending state matters because the user toggles "Show Knowledge status"
+ * across hundreds of files at once — the column needs to show "Checking…"
+ * for the rows still in flight rather than flickering "Not indexed".
+ */
+export type RagStatus = "indexed" | "not_indexed" | "pending" | "unknown";
+/**
+ * Knowledge filter — multi-select of statuses. Empty array = "any status".
+ * Modeled as `string[]` (not `RagStatus[]`) to mirror `TypeFilter` /
+ * `OwnerFilter` and keep the slice type import-cycle-free.
+ */
+export type RagFilter = string[];
+/** Per-column filters surfaced through the column-header dropdowns. */
+export interface ColumnFilters {
+    /** Name "contains" — column-scoped text filter, distinct from the
+     *  global search box. */
+    name: string;
+    /** File category multi-select (Image / Video / Code / …). */
+    type: TypeFilter;
+    /** Extension "contains" — e.g. "pdf", "jp" matches jpg & jpeg. */
+    extension: string;
+    /** MIME "contains" — e.g. "image/" matches every image. */
+    mime: string;
+    /** Folder path "contains" — useful in tree-wide search results. */
+    path: string;
+    /** Owner user-id multi-select. */
+    owner: OwnerFilter;
+    modified: ModifiedFilter;
+    /** Same preset semantics as `modified`, applied to `createdAt`. */
+    created: ModifiedFilter;
+    size: SizeFilter;
+    access: AccessFilter;
+    /**
+     * Knowledge indexing status multi-select. Only meaningful when the user has
+     * fetched Knowledge statuses (via the Knowledge column toggle in column-settings or
+     * the column-header refresh button) — folders never pass this filter
+     * since Knowledge indexing is a file-only concept.
+     */
+    rag: RagFilter;
+}
+/**
+ * Stable ids for every optional / required column rendered in the file
+ * table. Hidden vs. visible columns are tracked in
+ * `UiState.visibleColumns` — a Box.com / Google-Drive-style "Choose
+ * columns" panel toggles each on/off. `name` and `access` are conceptually
+ * always present but are still included here so the type remains the
+ * single source of truth.
+ */
+export type ColumnId = "name" | "type" | "extension" | "mime" | "path" | "owner" | "size" | "version" | "updated_at" | "created_at" | "access" | "rag_status" | "context";
+export type VisibleColumns = Record<ColumnId, boolean>;
+/**
+ * Default column set on first load. Tuned to match what users coming from
+ * Box.com / Google Drive expect to see by default — Type is shown
+ * because "what kind of file is this" is the second-most-important
+ * question after "what's its name", and the previous shipping default
+ * (just Name / Modified / Size / Access) silently hid that signal.
+ *
+ * `rag_status` is OFF by default because populating it requires a per-file
+ * network probe that the user explicitly opts into.
+ */
+export declare const DEFAULT_VISIBLE_COLUMNS: VisibleColumns;
+export interface UiState {
+    viewMode: ViewMode;
+    sortBy: SortBy;
+    sortDir: SortDirection;
+    /** Files-only / folders-only / both. Default = "all". */
+    kindFilter: KindFilter;
+    /** Whether to show extra detail columns (Extension, Type, Owner, …). */
+    detailsLevel: DetailsLevel;
+    /** Per-column filter values driven by the column-header dropdowns. */
+    columnFilters: ColumnFilters;
+    /** Which optional columns are mounted in the file table. */
+    visibleColumns: VisibleColumns;
+    /**
+     * Tree-wide search box value. Lives in Redux (not local component state)
+     * so the URL-sync layer can reflect it as `?q=…` and so cross-component
+     * reads (e.g. clearing search from a chip) don't need callbacks.
+     */
+    searchQuery: string;
+    /**
+     * Sticky filter chip currently active (Recents / Starred). Independent
+     * of `kindFilter` — chips apply preset semantics on top of any column
+     * filters. `null` = no chip.
+     */
+    chipFilter: ChipFilter | null;
+    activeFileId: string | null;
+    activeFolderId: string | null;
+    /**
+     * The single item (file or folder id) that has "keyboard/visual focus" — the
+     * highlighted row in the Google Drive sense. Set after create/upload so the
+     * newly-created item is immediately highlighted and scrolled into view.
+     * Clicking any row also moves focus to that row.
+     */
+    focusedId: string | null;
+}
+export interface SelectionState {
+    selectedIds: string[];
+    anchorId: string | null;
+}
+export type UploadStatus = "pending" | "uploading" | "success" | "error" | "cancelled";
+export interface UploadState {
+    requestId: string;
+    fileName: string;
+    fileSize: number;
+    parentFolderId: string | null;
+    /**
+     * The logical `folderPath` this upload targeted (`UploadFilesArg.folderPath`),
+     * verbatim — `null` when the caller used `parentFolderId` instead.
+     *
+     * This is the ONE correlation channel a container-scoped surface has for
+     * finding its own failed uploads: `state.uploads` is a flat, app-wide map
+     * (every uploader shares it — the Files page, chat attachments, the
+     * Rulebook Resources card…), so a surface that wants "MY failed uploads,
+     * not anyone else's" gives itself a folder path nothing else uses and reads
+     * back entries matching it exactly (see
+     * `RulebookSourcesPanel.tsx`'s `sourcesFolderPath`).
+     */
+    folderPath: string | null;
+    status: UploadStatus;
+    bytesUploaded: number;
+    startedAt: number;
+    completedAt: number | null;
+    error: string | null;
+    retries: number;
+    /** Populated on success; null until then. */
+    fileId: string | null;
+}
+/**
+ * Per-file Knowledge indexing status, hydrated lazily by the
+ * `prefetchRagStatusesForFiles` thunk. The thunk de-duplicates against
+ * `byFileId` so toggling the Knowledge column on/off doesn't re-fetch already
+ * known answers (use the column header's refresh action to force).
+ */
+export interface RagStatusState {
+    byFileId: Record<string, RagStatus>;
+    /** True while a batch fetch is in flight. */
+    isFetching: boolean;
+    /** ms timestamp of the most-recent successful batch (any source). */
+    lastFetchedAt: number | null;
+}
+export interface CloudFilesState {
+    filesById: Record<string, CloudFileRecord>;
+    foldersById: Record<string, CloudFolderRecord>;
+    versionsByFileId: Record<string, CloudFileVersion[]>;
+    permissionsByResourceId: Record<string, CloudFilePermission[]>;
+    shareLinksByResourceId: Record<string, CloudShareLink[]>;
+    tree: TreeState;
+    selection: SelectionState;
+    ui: UiState;
+    uploads: Record<string, UploadState>;
+    /** Per-file Knowledge indexing status, populated on demand. */
+    ragStatus: RagStatusState;
+    /**
+     * Realtime attachment status. Mirrors the supabase Channel lifecycle.
+     */
+    realtime: {
+        status: "detached" | "connecting" | "subscribed" | "errored" | "closed";
+        userId: string | null;
+        lastEventAt: number | null;
+        error: string | null;
+    };
+}
+export interface CreateFolderArg {
+    folderName: string;
+    parentId: string | null;
+    visibility?: Visibility;
+    metadata?: Record<string, unknown>;
+}
+export interface DeleteFolderArg {
+    folderId: string;
+}
+export interface EnsureFolderPathArg {
+    /**
+     * A folder path like "Images/2026/Q1". Each segment is created if missing.
+     * Returns the leaf folder's id.
+     */
+    folderPath: string;
+    visibility?: Visibility;
+}
+export interface UploadFilesArg {
+    files: File[];
+    /**
+     * Existing folder id (rare — only when you've already created/loaded the
+     * folder via realtime or the tree RPC). Prefer `folderPath` for new
+     * uploads — the backend auto-creates folders so the browser doesn't
+     * need to query `cld_folders` (which can recurse on RLS until the
+     * SECURITY DEFINER policy fix lands; see HANDOFF.md).
+     */
+    parentFolderId?: string | null;
+    /**
+     * Logical folder path (e.g. "Images/Chat" or "Debug Uploads"). The
+     * Python backend creates any missing folders during upload. This is
+     * the recommended option for new uploads — it doesn't trigger any
+     * supabase-js queries on `cld_folders` from the browser.
+     */
+    folderPath?: string | null;
+    visibility?: Visibility;
+    shareWith?: string[];
+    shareLevel?: PermissionLevel;
+    changeSummary?: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Per-upload options forwarded to the backend `options_json` field.
+     * Notably `rag.trigger_now` to run Knowledge immediately on upload instead of
+     * waiting for the scheduled auto-Knowledge sweep. Only menu/explicit uploads set
+     * this — drag-drop leaves it unset (scheduled sweep still runs).
+     */
+    options?: {
+        rag?: {
+            trigger_now?: boolean;
+        };
+    };
+    /** Parallel upload ceiling. Defaults to 3. */
+    concurrency?: number;
+    /**
+     * Per-file path overrides. Keyed by index into `files` (string
+     * because Records use string keys). When set for a file, the
+     * upload uses this exact path (relative to the parent prefix)
+     * instead of the file's own name — i.e. it can target an EXISTING
+     * file's path so the backend version-bumps it.
+     *
+     * The auto " (1)" / " (2)" rename in `uploadFiles` is bypassed
+     * for any index that has an override, since the override is the
+     * user's explicit choice (typically "Overwrite" from the
+     * duplicate-upload dialog).
+     *
+     * Indices not present here use the default name resolution.
+     */
+    filenameOverrides?: Record<number, string>;
+    /**
+     * Indices to drop from the upload entirely. Used by the
+     * duplicate-upload dialog's "Skip" action — we want to keep the
+     * batch shape stable for telemetry, but not actually upload
+     * those files. Indices reference the original `files` array.
+     */
+    skipIndices?: number[];
+    /**
+     * Indices whose duplicate-dialog decision was explicitly "Make a copy".
+     * The upload keeps its unique display name and sends the backend's strict
+     * `force_new_copy` intent so checksum-identical bytes create a distinct,
+     * durable row linked through `duplicate_of_file_id`.
+     */
+    forceNewCopyIndices?: number[];
+}
+export interface RenameFileArg {
+    fileId: string;
+    newName: string;
+}
+export interface MoveFileArg {
+    fileId: string;
+    newParentFolderId: string | null;
+}
+export interface UpdateFileMetadataArg {
+    fileId: string;
+    patch: {
+        visibility?: Visibility;
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface DeleteFileArg {
+    fileId: string;
+}
+/**
+ * Save new content as the next version of an EXISTING file (edit-in-place).
+ * `content` is the whole new body; the file keeps its id, name and folder.
+ */
+export interface SaveFileNewVersionArg {
+    fileId: string;
+    content: string | Blob;
+    changeSummary?: string;
+}
+/** What a successful save wrote: the same file id at its new version. */
+export interface SaveFileNewVersionResult {
+    fileId: string;
+    versionNumber: number;
+}
+export interface RestoreVersionArg {
+    fileId: string;
+    versionNumber: number;
+}
+/**
+ * Grant/revoke via the by-grantee REST path. `granteeType` here is a `user` or
+ * `group` grant only — `"public"` is not a by-grantee grant (it is toggled on
+ * the resource's visibility), and the grant/revoke thunks throw if it is passed
+ * (see `requireByGranteeType` in `redux/thunks.ts`). Defaults to `"user"`.
+ */
+export interface GrantPermissionArg {
+    resourceId: string;
+    resourceType: ResourceType;
+    granteeId: string;
+    granteeType?: GranteeType;
+    level: PermissionLevel;
+    expiresAt?: string;
+}
+export interface RevokePermissionArg {
+    resourceId: string;
+    resourceType: ResourceType;
+    granteeId: string;
+    granteeType?: GranteeType;
+}
+export interface CreateShareLinkArg {
+    resourceId: string;
+    resourceType: ResourceType;
+    permissionLevel: "viewer" | "editor";
+    expiresAt?: string;
+    maxUses?: number;
+}
+export interface RevokeShareLinkArg {
+    /** `platform.share_links.id` — the canonical revoke key. */
+    linkId: string;
+}
+/**
+ * Request body for `POST /folders` — create a folder. The Python team
+ * accepts a logical path (e.g. "Images/Chat") OR an explicit name + parentId.
+ * Path-style is preferred because the backend creates intermediate folders
+ * atomically and idempotently, matching upload's auto-create semantics.
+ */
+/**
+ * Body for `POST /folders`. Path-style ONLY — the backend creates any missing
+ * segments and REJECTS `{folder_name, parent_id}` (`validation_error`).
+ * DERIVED from the contract so the phantom name/parent fields can't be sent.
+ */
+export type CreateFolderRequest = components["schemas"]["CreateFolderRequest"];
+/**
+ * Body for `PATCH /folders/{id}`. Rename AND move are expressed as the target
+ * `folder_path` — the server renames, reparents, and cascades descendants from
+ * it. The backend SILENTLY IGNORES `folder_name`/`parent_id` (they are not on
+ * the model), so sending them made rename/move no-op server-side. DERIVED from
+ * the contract to make that mistake a compile error.
+ */
+export type FolderPatchRequest = components["schemas"]["PatchFolderRequest"];
+/** Body for `DELETE /files/bulk`. */
+export interface BulkDeleteFilesRequest {
+    file_ids: string[];
+}
+/** Body for `POST /files/bulk/move`. */
+export interface BulkMoveFilesRequest {
+    file_ids: string[];
+    /** Target parent folder id, or null to move to root. */
+    new_parent_folder_id: string | null;
+}
+/** Body for `POST /folders/bulk/move`. */
+export interface BulkMoveFoldersRequest {
+    folder_ids: string[];
+    /** Target parent folder id, or null to move to root. */
+    new_parent_id: string | null;
+}
+/**
+ * Per-item outcome inside a bulk response. Matches the backend
+ * `BulkResultItem` shape: `{ id, ok, error }` per item plus the
+ * aggregate counters returned alongside.
+ */
+export interface BulkResultItem {
+    id: string;
+    ok: boolean;
+    /** Error code/message string when `ok` is false; null on success. */
+    error: string | null;
+}
+/**
+ * Aggregate envelope returned by every bulk endpoint:
+ *   - `DELETE /files/bulk`
+ *   - `POST /files/bulk/move`
+ *   - `POST /folders/bulk/move`
+ *
+ * The aggregate `succeeded` and `failed` are NUMBERS (counts), not
+ * arrays. Per-item detail lives in `results`.
+ */
+export interface BulkResponse {
+    results: BulkResultItem[];
+    succeeded: number;
+    failed: number;
+}
+/**
+ * Response body of `GET /files/usage`. Drives the storage indicator,
+ * the tier badge, and feature gating in the UI. `null` on a numeric
+ * field means "no cap" (typically Enterprise tier).
+ */
+export interface StorageUsageResponse {
+    tier_id: string;
+    tier_name: string;
+    is_blocked: boolean;
+    blocked_reason: string | null;
+    bytes_used: number;
+    files_count: number;
+    daily_upload_count: number;
+    daily_upload_bytes: number;
+    max_storage_bytes: number | null;
+    max_file_size_bytes: number | null;
+    max_files: number | null;
+    max_versions_per_file: number | null;
+    max_daily_uploads: number | null;
+    max_daily_upload_bytes: number | null;
+    max_bulk_items: number | null;
+    rate_limit_uploads_per_min: number | null;
+    rate_limit_downloads_per_min: number | null;
+    features: Record<string, unknown>;
+    /**
+     * TRUE when `files.user_storage_usage` actually holds a row for this user.
+     *
+     * `get_usage_status` synthesizes `{bytes_used: 0, files_count: 0, …}` when
+     * the ledger row is ABSENT, which on screen is indistinguishable from a
+     * genuinely empty account — so the UI would say "0 bytes of 5 GB" about an
+     * account whose usage nobody has measured. The flattener detects the
+     * synthesized shape (it carries no `user_id`) and says so here, and the
+     * meter renders "usage being recalculated" instead of a number it does not
+     * have. folder-sync SPEC-SERVER §8: metering only just landed on the
+     * standalone service, and FS-L6 still has to rebuild and re-grain the
+     * ledger — an unbuilt row is the expected state, not an error.
+     */
+    ledger_measured: boolean;
+    /** When the ledger row was last written, or null when there is no row. */
+    ledger_measured_at: string | null;
+}
+/**
+ * Response body of `GET /files/trash`. Soft-deleted files + folders for
+ * the authenticated user (or guest fingerprint).
+ */
+export interface TrashListResponse {
+    files: FileRecordApi[];
+    folders: CloudFolderRow[];
+}
+/**
+ * Response body of `GET /files/search?q=&mime_prefix=&limit=&offset=`.
+ * The backend matches against filename + path substring; `mime_prefix`
+ * filters by `mime_type LIKE 'prefix%'`.
+ */
+export interface SearchFilesResponse {
+    results: FileRecordApi[];
+    query: string;
+    total_returned: number;
+}
+export interface SearchFilesParams {
+    q: string;
+    mimePrefix?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface RenameFileRequest {
+    /** Full new logical path including filename. Backend auto-creates parents. */
+    new_path: string;
+}
+export interface CopyFileRequest {
+    /** Full target logical path including filename. Backend auto-creates parents. */
+    target_path: string;
+    /** Default false. When false, conflicts return `409 file_already_exists`. */
+    overwrite?: boolean;
+}
+export interface BulkDeleteFilesArg {
+    fileIds: string[];
+}
+export interface BulkMoveFilesArg {
+    fileIds: string[];
+    newParentFolderId: string | null;
+}
+export interface BulkMoveFoldersArg {
+    folderIds: string[];
+    newParentId: string | null;
+}
+export interface UpdateFolderArg {
+    folderId: string;
+    patch: {
+        folderName?: string;
+        parentId?: string | null;
+        visibility?: Visibility;
+        metadata?: Record<string, unknown>;
+    };
+}
+export interface RenameFileToPathArg {
+    fileId: string;
+    /** Full new logical path including filename. */
+    newPath: string;
+}
+export interface CopyFileArg {
+    fileId: string;
+    /** Full target logical path including filename. */
+    targetPath: string;
+    overwrite?: boolean;
+}
+export interface SearchFilesArg {
+    q: string;
+    mimePrefix?: string;
+    limit?: number;
+    offset?: number;
+}
+export type RequestKind = "upload" | "update" | "delete" | "move" | "rename" | "restore-version" | "grant-permission" | "revoke-permission" | "create-share-link" | "revoke-share-link" | "folder-create" | "folder-update" | "folder-delete" | "bulk-delete-files" | "file-rename-path" | "file-copy" | "file-restore" | "bulk-move-files" | "bulk-move-folders";
+export interface LedgerEntry {
+    requestId: string;
+    kind: RequestKind;
+    resourceId: string | null;
+    resourceType: ResourceType | null;
+    createdAt: number;
+}
+export type { BackendApiError } from "@ai-matrx/agents/matrx";
+/**
+ * Files-specific error codes.
+ *
+ * Aligned with the Python backend's error envelope. The retry posture
+ * column is the FE contract — every caller must respect it:
+ *
+ * | Code                      | HTTP | Retry?  | UX hint                 |
+ * |---------------------------|------|---------|--------------------------|
+ * | invalid_request           | 400  | no      | fix the request          |
+ * | invalid_path              | 400  | no      | fix the path             |
+ * | invalid_metadata          | 400  | no      | fix the patch            |
+ * | fingerprint_required      | 400  | no      | guest header missing     |
+ * | auth_required             | 401  | no      | sign in                  |
+ * | permission_denied         | 403  | no      | request access           |
+ * | guest_id_mismatch         | 403  | no      | re-auth                  |
+ * | not_found                 | 404  | no      | resource gone            |
+ * | conflict                  | 409  | no      | overwrite=true to force  |
+ * | file_already_exists       | 409  | no      | overwrite=true to force  |
+ * | guest_locked              | 409  | no      | already migrated         |
+ * | file_too_large            | 413  | no      | upgrade tier             |
+ * | storage_quota_exceeded    | 413  | no      | upgrade tier             |
+ * | file_count_exceeded       | 413  | no      | upgrade tier             |
+ * | daily_uploads_exceeded    | 413  | no      | wait until tomorrow      |
+ * | daily_bytes_exceeded      | 413  | no      | wait until tomorrow      |
+ * | bulk_too_large            | 413  | no      | smaller batch            |
+ * | rate_limited              | 429  | YES (b) | exponential backoff      |
+ * | account_blocked           | 423  | no      | contact support          |
+ * | share_link_invalid        | 410  | no      | link revoked / expired   |
+ * | internal                  | 5xx  | YES (b) | exponential backoff      |
+ * | cld_sync_unavailable      | 503  | YES (b) | exponential backoff      |
+ */
+export type CloudFilesErrorCode = "invalid_request" | "invalid_path" | "invalid_metadata" | "fingerprint_required" | "auth_required" | "permission_denied" | "guest_id_mismatch" | "not_found" | "conflict" | "file_already_exists" | "guest_locked" | "file_too_large" | "storage_quota_exceeded" | "file_count_exceeded" | "daily_uploads_exceeded" | "daily_bytes_exceeded" | "bulk_too_large" | "rate_limited" | "account_blocked" | "share_link_invalid" | "internal" | "cld_sync_unavailable";
+export declare function isCloudTreeFileRow(row: CloudTreeRow): row is CloudTreeFileRow;
+export declare function isCloudTreeFolderRow(row: CloudTreeRow): row is CloudTreeFolderRow;
+/**
+ * Preset name accepted by `POST /assets` and `POST /assets/{id}/variants`.
+ * Adding a new preset on the backend is a coordinated change — extend
+ * this union in lockstep.
+ */
+export type AssetPreset = "raw" | "podcast" | "social" | "web" | "email" | "logo" | "avatar" | "favicon";
+/**
+ * One rendered variant inside an `Asset`. Each variant is a distinct
+ * `cld_files` row (so it shows up in the file tree and has its own
+ * permissions) but the `Asset` envelope groups them under a single
+ * `primary_key`-rooted record.
+ *
+ * URL fields (all durable — none expire):
+ *   - `url`          canonical inline-renderable URL. CDN for public,
+ *                    the durable download route for private/shared.
+ *                    **Use this** for `<img src>` / `<video src>` /
+ *                    `<audio src>`.
+ *   - `cdn_url`      permanent CDN URL when public + CDN configured;
+ *                    null otherwise.
+ *   - `download_url` durable URL with `Content-Disposition: attachment`
+ *                    — forces a download dialog.
+ */
+export interface AssetVariant {
+    key: string;
+    file_id: string;
+    file_path: string;
+    width: number | null;
+    height: number | null;
+    mime_type: string | null;
+    /**
+     * File size in bytes. Renamed from `file_size` in Phase 0 (see
+     * docs/PYTHON_UPDATES.md §3). Old servers may still send `file_size`
+     * during the transition — consumers should fall back to the legacy
+     * field name when reading older responses.
+     */
+    size_bytes: number | null;
+    /**
+     * Legacy alias for `size_bytes`. Populated by older servers during
+     * the Phase 0 transition window. Read `size_bytes` first; fall back
+     * to this only when re-hydrating older persisted responses.
+     *
+     * @deprecated Use `size_bytes`.
+     */
+    file_size?: number | null;
+    url: string | null;
+    cdn_url: string | null;
+    download_url: string | null;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Canonical envelope returned by every `/assets/*` and
+ * `/files/{id}/asset` endpoint.
+ *
+ *   - `file_id`     master file id (the upload's "original" row).
+ *   - `primary_key` which variant the FE should render by default
+ *                   (e.g. `"cover_url"` for podcast, `"original"` for raw).
+ *   - `primary_url` shorthand for `variants[primary_key].url`.
+ *   - `variants`    always includes `"original"` plus zero or more
+ *                   preset-driven derivatives.
+ */
+export interface Asset {
+    file_id: string;
+    visibility: Visibility;
+    folder: string;
+    preset: string | null;
+    primary_key: string;
+    primary_url: string | null;
+    variants: Record<string, AssetVariant>;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Request body for `POST /assets/{id}/variants`. Sends additional
+ * variants for an already-uploaded file. Idempotent on `(file_id, key)`.
+ */
+export interface AddAssetVariantsRequest {
+    preset?: AssetPreset;
+    custom_variants?: ReadonlyArray<{
+        key: string;
+        suffix?: string;
+        width?: number;
+        height?: number;
+        quality?: number;
+        format?: string;
+    }>;
+    include_social_baseline?: boolean;
+}
+/**
+ * Request body for `PATCH /assets/{id}`. Sparse — any field omitted is
+ * left unchanged. `metadata` is MERGED server-side (matches the
+ * `/files/{id}` PATCH semantics).
+ */
+export interface AssetPatchRequest {
+    visibility?: Visibility;
+    /** Comma-separated user IDs OR an explicit list. */
+    share_with?: string | ReadonlyArray<string>;
+    share_level?: PermissionLevel;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * One row in the `GET /assets/presets` response — describes a single
+ * variant a preset will render.
+ */
+export interface AssetPresetVariantDescriptor {
+    key: string;
+    width: number | null;
+    height: number | null;
+    format: string | null;
+}
+/**
+ * One preset row in the `GET /assets/presets` response.
+ */
+export interface AssetPresetDescriptor {
+    name: AssetPreset;
+    primary_key: string;
+    include_baseline: boolean;
+    variants: ReadonlyArray<AssetPresetVariantDescriptor>;
+}
+/**
+ * Response body for `GET /assets/presets`. Drives the picker UI in
+ * admin tools and lets agents enumerate every server-known preset
+ * without hard-coding the list.
+ */
+export interface PresetsRegistryResponse {
+    presets: ReadonlyArray<AssetPresetDescriptor>;
+    social_baseline: ReadonlyArray<AssetPresetVariantDescriptor>;
+}