@ai-matrx/media 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @ai-matrx/media
 
+## 0.9.0
+
+New subpath `@ai-matrx/media/files/engine` plus one subpath per engine module
+(`@ai-matrx/media/files/engine/<dir>/<module>`) — chat package independence P16f, batch 2:
+the files engine moved verbatim from matrx-frontend `features/files` + `lib/media`: the
+`cloudFiles` slice, `cloudFilesRealtimeMiddleware`, `cloudFilesMutationToastMiddleware`,
+thunks and selectors, the file handler (`normalize`, `resolve`, `upload`, `toMediaRef`,
+`toTarget`), `useFile`/`useFileUpload`, multipart + TUS uploads and the dedup upload guard,
+the byte cache, `recognizeOurFileUrl`. ESM-only, one module per file.
+
+**Consumer action:** call `configureFilesHost({ db, server, store })` once before creating the
+store (optionally `scope`, `ensureOrganizationContext`, `shareLinks`, `notify`), mount
+`cloudFilesReducer` under `cloudFiles`, and add both middlewares. New peers (optional for
+every other entry): `@reduxjs/toolkit` >=2, `react-redux` >=9.
+
 ## 0.8.0
 
 New subpath `@ai-matrx/media/files` (chat package independence P16f, first batch): the file

package/dist/files/engine/api/assets.d.ts

@@ -0,0 +1,223 @@
+/**
+ * features/files/api/assets.ts
+ *
+ * Typed REST wrapper for the unified asset (image / media) pipeline.
+ *
+ *   POST   /assets                          multipart upload + render
+ *   GET    /assets/{file_id}                read Asset envelope
+ *   PATCH  /assets/{file_id}                visibility / share / metadata
+ *   POST   /assets/{file_id}/variants       render more variants
+ *   GET    /assets/presets                  list every server-known preset
+ *   GET    /files/{file_id}/asset           any cld_files row → Asset envelope
+ *
+ * Every endpoint returns the same {@link Asset} envelope (see
+ * `features/files/types.ts`). `GET /files/{id}/asset` is the canonical
+ * "click-to-render" primitive — pass any file_id, get back inline-renderable
+ * URLs grouped by variant key.
+ *
+ * Auth + request-id + idempotency-key + bypass-secret plumbing all flow
+ * through the same client helpers used by `files.ts`; see
+ * [./client.ts](./client.ts) for the contract.
+ */
+import { type RequestOptions, type ResponseMeta, type UploadProgressEvent } from "../host/python-client.js";
+import type { AddAssetVariantsRequest, Asset, AssetPatchRequest, AssetPreset, PresetsRegistryResponse, Visibility } from "../types.js";
+import type { components } from "@ai-matrx/agents/generated/api-types";
+/**
+ * Spec for a one-off custom variant — sent verbatim to the server in
+ * `custom_variants_json`. Use this for ad-hoc dimensions that don't fit
+ * any built-in preset. Prefer the preset registry when possible so the
+ * resulting variant has a well-known key downstream renderers recognize.
+ */
+export interface CustomVariantSpec {
+    key: string;
+    suffix?: string;
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: string;
+}
+export interface UploadAssetParams {
+    file: File;
+    /** Preset name. Default: `"raw"` — no derived variants. */
+    preset?: AssetPreset;
+    /** Logical folder path. Server defaults to `Assets/<uuid>` when omitted. */
+    folder?: string;
+    /** Default `"public"`. */
+    visibility?: Visibility;
+    /** Comma-separated user IDs OR an explicit list (the wrapper joins). */
+    shareWith?: string | ReadonlyArray<string>;
+    /** Default `"read"`. */
+    shareLevel?: "read" | "write" | "admin";
+    /** Override the preset's default `include_social_baseline`. */
+    includeSocialBaseline?: boolean;
+    /** Free-form metadata to attach to every variant + the master row. */
+    metadata?: Record<string, unknown>;
+    /** Ad-hoc variant specs in addition to (or instead of) the preset. */
+    customVariants?: ReadonlyArray<CustomVariantSpec>;
+}
+/**
+ * Upload an asset and render preset variants in one round-trip.
+ * Returns the canonical {@link Asset} envelope — the same shape every
+ * other endpoint in this module returns.
+ */
+export declare function uploadAsset(params: UploadAssetParams, opts?: RequestOptions): Promise<{
+    data: Asset;
+    meta: ResponseMeta;
+}>;
+/**
+ * Same as `uploadAsset` but with progress callbacks. Useful for big
+ * uploads where the user expects a `Uploading 12 / 30 MB…` indicator.
+ */
+export declare function uploadAssetWithProgress(params: UploadAssetParams, onProgress: (event: UploadProgressEvent) => void, opts?: RequestOptions): Promise<{
+    data: Asset;
+    meta: ResponseMeta;
+}>;
+export interface GetAssetParams {
+}
+/**
+ * Read the Asset envelope for a known asset master file id.
+ *
+ * Use this when you already uploaded through `/assets` and want to
+ * re-read the envelope (e.g. after a visibility change). For a generic
+ * "give me an Asset for this file_id" call (where the file may or may
+ * not have been uploaded through the asset pipeline), prefer
+ * {@link getAssetForFile}.
+ */
+export declare function getAsset(fileId: string, _params?: GetAssetParams, opts?: RequestOptions): Promise<{
+    data: Asset;
+    meta: ResponseMeta;
+}>;
+/**
+ * Canonical click-to-render primitive: hand any cld_files row id, get
+ * back an Asset envelope (with at least an `original` variant). Works
+ * regardless of whether the file was uploaded through the asset
+ * pipeline. The hook around this is {@link useFileAsset}.
+ */
+export declare function getAssetForFile(fileId: string, _params?: GetAssetParams, opts?: RequestOptions): Promise<{
+    data: Asset;
+    meta: ResponseMeta;
+}>;
+/**
+ * PATCH `/assets/{file_id}` — change visibility / share / metadata.
+ * Returns the new Asset envelope reflecting the change (URLs included).
+ */
+export declare function patchAsset(fileId: string, body: AssetPatchRequest, opts?: RequestOptions): Promise<{
+    data: Asset;
+    meta: ResponseMeta;
+}>;
+/**
+ * POST `/assets/{file_id}/variants` — render more variants for an
+ * existing asset. Idempotent on `(file_id, variant_key)`: re-rendering
+ * a key that already exists is a no-op (the server returns the
+ * existing variant).
+ */
+export declare function addAssetVariants(fileId: string, body: AddAssetVariantsRequest, opts?: RequestOptions): Promise<{
+    data: Asset;
+    meta: ResponseMeta;
+}>;
+/**
+ * List every server-known preset and its variants. Use this to drive
+ * picker UIs / admin tooling instead of hardcoding the list in TS.
+ */
+export declare function getAssetPresets(opts?: RequestOptions): Promise<{
+    data: PresetsRegistryResponse;
+    meta: ResponseMeta;
+}>;
+/**
+ * Spec for a single preview variant — width/height drives the resize;
+ * `format` and `quality` control the output encoding. Sent verbatim to
+ * the server (no client-side image processing).
+ *
+ * `position` and `background_color` are honored when `fit: "cover"`:
+ *   - Anchor strings (`"top"`, `"top-left"`, `"entropy"`, etc.) pick the
+ *     crop region against one of nine fixed anchors or sharp's smart
+ *     strategies.
+ *   - A `{x, y}` point (each in `[0, 1]`) places the crop's centre at
+ *     that focal point in the source image. The server clamps so the
+ *     crop never escapes the source bounds.
+ *
+ * `background_color` is consulted in two places:
+ *   - `fit: "contain"` — letterbox padding colour.
+ *   - `format: "jpeg" | "avif"` — alpha-flatten colour (those formats
+ *     don't carry alpha; transparent pixels become opaque).
+ *
+ * Field names are snake_case to match the Python multipart body schema
+ * verbatim — `position` / `background_color` reach Python as-is inside
+ * the `variants_json` array.
+ *
+ * These are DERIVED from the OpenAPI-generated schema, never hand-mirrored.
+ * A backend rename (e.g. `key` → `preset_id`) changes the generated type,
+ * which turns every drifted callsite into a compile error in the same PR
+ * that runs `pnpm sync-types`. Do NOT redeclare these as standalone
+ * interfaces — that severs the link and lets the wire contract drift
+ * silently (which is exactly how the `invalid_variant_spec` 400 shipped).
+ */
+export type PreviewVariantSpec = components["schemas"]["PreviewVariantSpec"];
+/** Named anchor / smart-crop mode / focal point for `fit: "cover"`. */
+export type PreviewVariantPosition = NonNullable<PreviewVariantSpec["position"]>;
+/** One rendered variant in the `/assets/preview*` response. */
+export type PreviewVariantResult = components["schemas"]["AssetPreviewVariant"];
+/** Response envelope for `POST /assets/preview` and `.../multipart`. */
+export type AssetPreviewResult = components["schemas"]["AssetPreviewResponse"];
+export interface PdfCompressResult {
+    original_size: number;
+    compressed_size: number;
+    /** 0..1 — fraction of bytes saved. */
+    reduction_ratio: number;
+    mime_type: string;
+    data_url: string | null;
+    /** 5-minute row-less scratch URL — the ONLY lawful expiring URL shape. */
+    ephemeral_url: string | null;
+    /** Seconds until ephemeral_url expires (ephemeral mode only). */
+    expires_in?: number | null;
+    /** Tier the caller asked for. */
+    level_requested?: number | null;
+    /** Tier that actually produced the output (cap escalation may raise it). */
+    level_used?: number | null;
+    /** Whether max_size_bytes was met (null when no cap was sent). */
+    cap_satisfied?: boolean | null;
+    /** "inplace" | "raster" — which compression path produced the output. */
+    strategy_used?: string | null;
+}
+/**
+ * `POST /assets/preview/multipart` — render preview variants WITHOUT
+ * persisting the master. Image Studio uses this for the drag-and-drop
+ * preview flow; the user can then commit-to-save via `POST /assets`.
+ *
+ * Each variant comes back as either an inline `data_url` (small) or an
+ * `ephemeral_url` (5-minute row-less preview scratch).
+ */
+export declare function previewAssetMultipart(file: File | Blob, variants: PreviewVariantSpec[], options?: {
+    maxInlineBytes?: number;
+}, opts?: RequestOptions): Promise<{
+    data: AssetPreviewResult;
+    meta: ResponseMeta;
+}>;
+/**
+ * `POST /assets/pdf-compress/multipart` — compress a PDF WITHOUT
+ * persisting it. Returns `data_url` (≤256 KB) or `ephemeral_url`
+ * (5-minute row-less scratch). Replaces the deleted Next.js Sharp/PDF route.
+ *
+ * @param level minimum compression tier (1..5). Default 3. Server may
+ *   escalate above this when `maxSizeBytes` forces it.
+ * @param maxSizeBytes optional absolute upper bound on output size.
+ */
+export declare function compressPdfMultipart(file: File | Blob, options?: {
+    level?: number;
+    maxSizeBytes?: number;
+    maxInlineBytes?: number;
+}, opts?: RequestOptions): Promise<{
+    data: PdfCompressResult;
+    meta: ResponseMeta;
+}>;
+/**
+ * Materialize a `PreviewVariantResult` / `PdfCompressResult` body that
+ * carries either `data_url` or `ephemeral_url` into a `Blob`. Useful when
+ * the FE needs the bytes locally (e.g. to wrap in a `File` for further
+ * upload).
+ */
+export declare function materializeAssetResult(result: {
+    data_url: string | null;
+    ephemeral_url: string | null;
+    mime_type: string;
+}): Promise<Blob>;

package/dist/files/engine/api/assets.js

@@ -0,0 +1,124 @@
+import {
+  getJson,
+  patchJson,
+  postJson,
+  postMultipart,
+  uploadWithProgress
+} from "../host/python-client.js";
+import { withFileOrganization } from "./fileOrganization.js";
+import { ENDPOINTS } from "@ai-matrx/agents/matrx";
+import { apiMultipart } from "../host/typed-client.js";
+function buildUploadForm(params) {
+  const form = new FormData();
+  form.append("file", params.file);
+  if (params.preset) form.append("preset", params.preset);
+  if (params.folder) form.append("folder", params.folder);
+  if (params.visibility) form.append("visibility", params.visibility);
+  if (params.shareWith !== void 0) {
+    const joined = Array.isArray(params.shareWith) ? params.shareWith.join(",") : params.shareWith;
+    if (joined) form.append("share_with", joined);
+  }
+  if (params.shareLevel) form.append("share_level", params.shareLevel);
+  if (params.includeSocialBaseline !== void 0)
+    form.append(
+      "include_social_baseline",
+      params.includeSocialBaseline ? "true" : "false"
+    );
+  if (params.metadata)
+    form.append("metadata_json", JSON.stringify(params.metadata));
+  if (params.customVariants && params.customVariants.length)
+    form.append("custom_variants_json", JSON.stringify(params.customVariants));
+  return form;
+}
+async function uploadAsset(params, opts = {}) {
+  const form = buildUploadForm(params);
+  return postMultipart(ENDPOINTS.assets.upload, form, opts);
+}
+async function uploadAssetWithProgress(params, onProgress, opts = {}) {
+  const form = buildUploadForm(params);
+  return uploadWithProgress(
+    ENDPOINTS.assets.upload,
+    form,
+    onProgress,
+    opts
+  );
+}
+async function getAsset(fileId, _params = {}, opts = {}) {
+  return getJson(ENDPOINTS.assets.detail(fileId), withFileOrganization(fileId, opts));
+}
+async function getAssetForFile(fileId, _params = {}, opts = {}) {
+  return getJson(ENDPOINTS.assets.forFile(fileId), withFileOrganization(fileId, opts));
+}
+async function patchAsset(fileId, body, opts = {}) {
+  const normalised = {
+    ...body,
+    share_with: Array.isArray(body.share_with) ? body.share_with.join(",") : body.share_with
+  };
+  return patchJson(
+    ENDPOINTS.assets.patch(fileId),
+    normalised,
+    opts
+  );
+}
+async function addAssetVariants(fileId, body, opts = {}) {
+  return postJson(
+    ENDPOINTS.assets.addVariants(fileId),
+    body,
+    opts
+  );
+}
+async function getAssetPresets(opts = {}) {
+  return getJson(ENDPOINTS.assets.presets, opts);
+}
+async function previewAssetMultipart(file, variants, options = {}, opts = {}) {
+  const form = new FormData();
+  form.append("file", file);
+  form.append("variants_json", JSON.stringify(variants));
+  if (typeof options.maxInlineBytes === "number") {
+    form.append("max_inline_bytes", String(options.maxInlineBytes));
+  }
+  return apiMultipart(ENDPOINTS.assets.previewMultipart, form, opts);
+}
+async function compressPdfMultipart(file, options = {}, opts = {}) {
+  const form = new FormData();
+  form.append("file", file);
+  form.append("level", String(options.level ?? 3));
+  if (typeof options.maxSizeBytes === "number") {
+    form.append("max_size_bytes", String(options.maxSizeBytes));
+  }
+  if (typeof options.maxInlineBytes === "number") {
+    form.append("max_inline_bytes", String(options.maxInlineBytes));
+  }
+  return postMultipart(
+    ENDPOINTS.assets.pdfCompressMultipart,
+    form,
+    opts
+  );
+}
+async function materializeAssetResult(result) {
+  if (result.data_url) {
+    const response = await fetch(result.data_url);
+    return response.blob();
+  }
+  if (result.ephemeral_url) {
+    const response = await fetch(result.ephemeral_url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ephemeral asset URL: HTTP ${response.status}`);
+    }
+    return response.blob();
+  }
+  throw new Error("Asset result has neither data_url nor ephemeral_url");
+}
+export {
+  addAssetVariants,
+  compressPdfMultipart,
+  getAsset,
+  getAssetForFile,
+  getAssetPresets,
+  materializeAssetResult,
+  patchAsset,
+  previewAssetMultipart,
+  uploadAsset,
+  uploadAssetWithProgress
+};
+//# sourceMappingURL=assets.js.map

package/dist/files/engine/api/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/assets.ts"],"sourcesContent":["/**\n * features/files/api/assets.ts\n *\n * Typed REST wrapper for the unified asset (image / media) pipeline.\n *\n *   POST   /assets                          multipart upload + render\n *   GET    /assets/{file_id}                read Asset envelope\n *   PATCH  /assets/{file_id}                visibility / share / metadata\n *   POST   /assets/{file_id}/variants       render more variants\n *   GET    /assets/presets                  list every server-known preset\n *   GET    /files/{file_id}/asset           any cld_files row → Asset envelope\n *\n * Every endpoint returns the same {@link Asset} envelope (see\n * `features/files/types.ts`). `GET /files/{id}/asset` is the canonical\n * \"click-to-render\" primitive — pass any file_id, get back inline-renderable\n * URLs grouped by variant key.\n *\n * Auth + request-id + idempotency-key + bypass-secret plumbing all flow\n * through the same client helpers used by `files.ts`; see\n * [./client.ts](./client.ts) for the contract.\n */\n\nimport {\n  getJson,\n  patchJson,\n  postJson,\n  postMultipart,\n  uploadWithProgress,\n  type RequestOptions,\n  type ResponseMeta,\n  type UploadProgressEvent,\n} from \"../host/python-client\";\nimport { withFileOrganization } from \"./fileOrganization\";\nimport type {\n  AddAssetVariantsRequest,\n  Asset,\n  AssetPatchRequest,\n  AssetPreset,\n  PresetsRegistryResponse,\n  Visibility,\n} from \"../types\";\nimport { ENDPOINTS } from \"@ai-matrx/agents/matrx\";\nimport { apiMultipart } from \"../host/typed-client\";\nimport type { components } from \"@ai-matrx/agents/generated/api-types\";\n\n// ---------------------------------------------------------------------------\n// Upload\n// ---------------------------------------------------------------------------\n\n/**\n * Spec for a one-off custom variant — sent verbatim to the server in\n * `custom_variants_json`. Use this for ad-hoc dimensions that don't fit\n * any built-in preset. Prefer the preset registry when possible so the\n * resulting variant has a well-known key downstream renderers recognize.\n */\nexport interface CustomVariantSpec {\n  key: string;\n  suffix?: string;\n  width?: number;\n  height?: number;\n  quality?: number;\n  format?: string;\n}\n\nexport interface UploadAssetParams {\n  file: File;\n  /** Preset name. Default: `\"raw\"` — no derived variants. */\n  preset?: AssetPreset;\n  /** Logical folder path. Server defaults to `Assets/<uuid>` when omitted. */\n  folder?: string;\n  /** Default `\"public\"`. */\n  visibility?: Visibility;\n  /** Comma-separated user IDs OR an explicit list (the wrapper joins). */\n  shareWith?: string | ReadonlyArray<string>;\n  /** Default `\"read\"`. */\n  shareLevel?: \"read\" | \"write\" | \"admin\";\n  /** Override the preset's default `include_social_baseline`. */\n  includeSocialBaseline?: boolean;\n  /** Free-form metadata to attach to every variant + the master row. */\n  metadata?: Record<string, unknown>;\n  /** Ad-hoc variant specs in addition to (or instead of) the preset. */\n  customVariants?: ReadonlyArray<CustomVariantSpec>;\n}\n\nfunction buildUploadForm(params: UploadAssetParams): FormData {\n  const form = new FormData();\n  form.append(\"file\", params.file);\n  if (params.preset) form.append(\"preset\", params.preset);\n  if (params.folder) form.append(\"folder\", params.folder);\n  if (params.visibility) form.append(\"visibility\", params.visibility);\n  if (params.shareWith !== undefined) {\n    const joined = Array.isArray(params.shareWith)\n      ? params.shareWith.join(\",\")\n      : (params.shareWith as string);\n    if (joined) form.append(\"share_with\", joined);\n  }\n  if (params.shareLevel) form.append(\"share_level\", params.shareLevel);\n  if (params.includeSocialBaseline !== undefined)\n    form.append(\n      \"include_social_baseline\",\n      params.includeSocialBaseline ? \"true\" : \"false\",\n    );\n  if (params.metadata)\n    form.append(\"metadata_json\", JSON.stringify(params.metadata));\n  if (params.customVariants && params.customVariants.length)\n    form.append(\"custom_variants_json\", JSON.stringify(params.customVariants));\n  return form;\n}\n\n/**\n * Upload an asset and render preset variants in one round-trip.\n * Returns the canonical {@link Asset} envelope — the same shape every\n * other endpoint in this module returns.\n */\nexport async function uploadAsset(\n  params: UploadAssetParams,\n  opts: RequestOptions = {},\n): Promise<{ data: Asset; meta: ResponseMeta }> {\n  const form = buildUploadForm(params);\n  return postMultipart<Asset>(ENDPOINTS.assets.upload, form, opts);\n}\n\n/**\n * Same as `uploadAsset` but with progress callbacks. Useful for big\n * uploads where the user expects a `Uploading 12 / 30 MB…` indicator.\n */\nexport async function uploadAssetWithProgress(\n  params: UploadAssetParams,\n  onProgress: (event: UploadProgressEvent) => void,\n  opts: RequestOptions = {},\n): Promise<{ data: Asset; meta: ResponseMeta }> {\n  const form = buildUploadForm(params);\n  return uploadWithProgress<Asset>(\n    ENDPOINTS.assets.upload,\n    form,\n    onProgress,\n    opts,\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Read\n// ---------------------------------------------------------------------------\n\nexport interface GetAssetParams {}\n\n/**\n * Read the Asset envelope for a known asset master file id.\n *\n * Use this when you already uploaded through `/assets` and want to\n * re-read the envelope (e.g. after a visibility change). For a generic\n * \"give me an Asset for this file_id\" call (where the file may or may\n * not have been uploaded through the asset pipeline), prefer\n * {@link getAssetForFile}.\n */\nexport async function getAsset(\n  fileId: string,\n  _params: GetAssetParams = {},\n  opts: RequestOptions = {},\n): Promise<{ data: Asset; meta: ResponseMeta }> {\n  return getJson<Asset>(ENDPOINTS.assets.detail(fileId), withFileOrganization(fileId, opts));\n}\n\n/**\n * Canonical click-to-render primitive: hand any cld_files row id, get\n * back an Asset envelope (with at least an `original` variant). Works\n * regardless of whether the file was uploaded through the asset\n * pipeline. The hook around this is {@link useFileAsset}.\n */\nexport async function getAssetForFile(\n  fileId: string,\n  _params: GetAssetParams = {},\n  opts: RequestOptions = {},\n): Promise<{ data: Asset; meta: ResponseMeta }> {\n  return getJson<Asset>(ENDPOINTS.assets.forFile(fileId), withFileOrganization(fileId, opts));\n}\n\n// ---------------------------------------------------------------------------\n// Mutate\n// ---------------------------------------------------------------------------\n\n/**\n * PATCH `/assets/{file_id}` — change visibility / share / metadata.\n * Returns the new Asset envelope reflecting the change (URLs included).\n */\nexport async function patchAsset(\n  fileId: string,\n  body: AssetPatchRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: Asset; meta: ResponseMeta }> {\n  // The backend accepts `share_with` as either a comma-separated string\n  // or a list; normalise to the string form so callers can pass either.\n  const normalised: AssetPatchRequest = {\n    ...body,\n    share_with: Array.isArray(body.share_with)\n      ? body.share_with.join(\",\")\n      : body.share_with,\n  };\n  return patchJson<Asset, AssetPatchRequest>(\n    ENDPOINTS.assets.patch(fileId),\n    normalised,\n    opts,\n  );\n}\n\n/**\n * POST `/assets/{file_id}/variants` — render more variants for an\n * existing asset. Idempotent on `(file_id, variant_key)`: re-rendering\n * a key that already exists is a no-op (the server returns the\n * existing variant).\n */\nexport async function addAssetVariants(\n  fileId: string,\n  body: AddAssetVariantsRequest,\n  opts: RequestOptions = {},\n): Promise<{ data: Asset; meta: ResponseMeta }> {\n  return postJson<Asset, AddAssetVariantsRequest>(\n    ENDPOINTS.assets.addVariants(fileId),\n    body,\n    opts,\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Presets registry\n// ---------------------------------------------------------------------------\n\n/**\n * List every server-known preset and its variants. Use this to drive\n * picker UIs / admin tooling instead of hardcoding the list in TS.\n */\nexport async function getAssetPresets(\n  opts: RequestOptions = {},\n): Promise<{ data: PresetsRegistryResponse; meta: ResponseMeta }> {\n  return getJson<PresetsRegistryResponse>(ENDPOINTS.assets.presets, opts);\n}\n\n// ---------------------------------------------------------------------------\n// No-persist preview + PDF compress (E.16 + E.17, matrx-utils v1.1.0)\n// ---------------------------------------------------------------------------\n\n/**\n * Spec for a single preview variant — width/height drives the resize;\n * `format` and `quality` control the output encoding. Sent verbatim to\n * the server (no client-side image processing).\n *\n * `position` and `background_color` are honored when `fit: \"cover\"`:\n *   - Anchor strings (`\"top\"`, `\"top-left\"`, `\"entropy\"`, etc.) pick the\n *     crop region against one of nine fixed anchors or sharp's smart\n *     strategies.\n *   - A `{x, y}` point (each in `[0, 1]`) places the crop's centre at\n *     that focal point in the source image. The server clamps so the\n *     crop never escapes the source bounds.\n *\n * `background_color` is consulted in two places:\n *   - `fit: \"contain\"` — letterbox padding colour.\n *   - `format: \"jpeg\" | \"avif\"` — alpha-flatten colour (those formats\n *     don't carry alpha; transparent pixels become opaque).\n *\n * Field names are snake_case to match the Python multipart body schema\n * verbatim — `position` / `background_color` reach Python as-is inside\n * the `variants_json` array.\n *\n * These are DERIVED from the OpenAPI-generated schema, never hand-mirrored.\n * A backend rename (e.g. `key` → `preset_id`) changes the generated type,\n * which turns every drifted callsite into a compile error in the same PR\n * that runs `pnpm sync-types`. Do NOT redeclare these as standalone\n * interfaces — that severs the link and lets the wire contract drift\n * silently (which is exactly how the `invalid_variant_spec` 400 shipped).\n */\nexport type PreviewVariantSpec = components[\"schemas\"][\"PreviewVariantSpec\"];\n\n/** Named anchor / smart-crop mode / focal point for `fit: \"cover\"`. */\nexport type PreviewVariantPosition = NonNullable<\n  PreviewVariantSpec[\"position\"]\n>;\n\n/** One rendered variant in the `/assets/preview*` response. */\nexport type PreviewVariantResult = components[\"schemas\"][\"AssetPreviewVariant\"];\n\n/** Response envelope for `POST /assets/preview` and `.../multipart`. */\nexport type AssetPreviewResult = components[\"schemas\"][\"AssetPreviewResponse\"];\n\nexport interface PdfCompressResult {\n  original_size: number;\n  compressed_size: number;\n  /** 0..1 — fraction of bytes saved. */\n  reduction_ratio: number;\n  mime_type: string;\n  data_url: string | null;\n  /** 5-minute row-less scratch URL — the ONLY lawful expiring URL shape. */\n  ephemeral_url: string | null;\n  /** Seconds until ephemeral_url expires (ephemeral mode only). */\n  expires_in?: number | null;\n  /** Tier the caller asked for. */\n  level_requested?: number | null;\n  /** Tier that actually produced the output (cap escalation may raise it). */\n  level_used?: number | null;\n  /** Whether max_size_bytes was met (null when no cap was sent). */\n  cap_satisfied?: boolean | null;\n  /** \"inplace\" | \"raster\" — which compression path produced the output. */\n  strategy_used?: string | null;\n}\n\n/**\n * `POST /assets/preview/multipart` — render preview variants WITHOUT\n * persisting the master. Image Studio uses this for the drag-and-drop\n * preview flow; the user can then commit-to-save via `POST /assets`.\n *\n * Each variant comes back as either an inline `data_url` (small) or an\n * `ephemeral_url` (5-minute row-less preview scratch).\n */\nexport async function previewAssetMultipart(\n  file: File | Blob,\n  variants: PreviewVariantSpec[],\n  options: { maxInlineBytes?: number } = {},\n  opts: RequestOptions = {},\n): Promise<{ data: AssetPreviewResult; meta: ResponseMeta }> {\n  const form = new FormData();\n  form.append(\"file\", file);\n  // Python's multipart body declares `variants_json` (not `variants`) per\n  // its OpenAPI schema. Match the wire name verbatim.\n  form.append(\"variants_json\", JSON.stringify(variants));\n  if (typeof options.maxInlineBytes === \"number\") {\n    form.append(\"max_inline_bytes\", String(options.maxInlineBytes));\n  }\n  // Contract-bound: the response type is DERIVED from the OpenAPI operation\n  // for this exact path, not asserted. A backend response-shape change turns\n  // every reader of the result into a compile error after `pnpm sync-types`.\n  return apiMultipart(ENDPOINTS.assets.previewMultipart, form, opts);\n}\n\n/**\n * `POST /assets/pdf-compress/multipart` — compress a PDF WITHOUT\n * persisting it. Returns `data_url` (≤256 KB) or `ephemeral_url`\n * (5-minute row-less scratch). Replaces the deleted Next.js Sharp/PDF route.\n *\n * @param level minimum compression tier (1..5). Default 3. Server may\n *   escalate above this when `maxSizeBytes` forces it.\n * @param maxSizeBytes optional absolute upper bound on output size.\n */\nexport async function compressPdfMultipart(\n  file: File | Blob,\n  options: { level?: number; maxSizeBytes?: number; maxInlineBytes?: number } = {},\n  opts: RequestOptions = {},\n): Promise<{ data: PdfCompressResult; meta: ResponseMeta }> {\n  const form = new FormData();\n  form.append(\"file\", file);\n  form.append(\"level\", String(options.level ?? 3));\n  if (typeof options.maxSizeBytes === \"number\") {\n    form.append(\"max_size_bytes\", String(options.maxSizeBytes));\n  }\n  if (typeof options.maxInlineBytes === \"number\") {\n    form.append(\"max_inline_bytes\", String(options.maxInlineBytes));\n  }\n  return postMultipart<PdfCompressResult>(\n    ENDPOINTS.assets.pdfCompressMultipart,\n    form,\n    opts,\n  );\n}\n\n/**\n * Materialize a `PreviewVariantResult` / `PdfCompressResult` body that\n * carries either `data_url` or `ephemeral_url` into a `Blob`. Useful when\n * the FE needs the bytes locally (e.g. to wrap in a `File` for further\n * upload).\n */\nexport async function materializeAssetResult(\n  result: {\n    data_url: string | null;\n    ephemeral_url: string | null;\n    mime_type: string;\n  },\n): Promise<Blob> {\n  if (result.data_url) {\n    const response = await fetch(result.data_url);\n    return response.blob();\n  }\n  if (result.ephemeral_url) {\n    const response = await fetch(result.ephemeral_url);\n    if (!response.ok) {\n      throw new Error(`Failed to fetch ephemeral asset URL: HTTP ${response.status}`);\n    }\n    return response.blob();\n  }\n  throw new Error(\"Asset result has neither data_url nor ephemeral_url\");\n}\n"],"mappings":"AAsBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AACP,SAAS,4BAA4B;AASrC,SAAS,iBAAiB;AAC1B,SAAS,oBAAoB;AA0C7B,SAAS,gBAAgB,QAAqC;AAC5D,QAAM,OAAO,IAAI,SAAS;AAC1B,OAAK,OAAO,QAAQ,OAAO,IAAI;AAC/B,MAAI,OAAO,OAAQ,MAAK,OAAO,UAAU,OAAO,MAAM;AACtD,MAAI,OAAO,OAAQ,MAAK,OAAO,UAAU,OAAO,MAAM;AACtD,MAAI,OAAO,WAAY,MAAK,OAAO,cAAc,OAAO,UAAU;AAClE,MAAI,OAAO,cAAc,QAAW;AAClC,UAAM,SAAS,MAAM,QAAQ,OAAO,SAAS,IACzC,OAAO,UAAU,KAAK,GAAG,IACxB,OAAO;AACZ,QAAI,OAAQ,MAAK,OAAO,cAAc,MAAM;AAAA,EAC9C;AACA,MAAI,OAAO,WAAY,MAAK,OAAO,eAAe,OAAO,UAAU;AACnE,MAAI,OAAO,0BAA0B;AACnC,SAAK;AAAA,MACH;AAAA,MACA,OAAO,wBAAwB,SAAS;AAAA,IAC1C;AACF,MAAI,OAAO;AACT,SAAK,OAAO,iBAAiB,KAAK,UAAU,OAAO,QAAQ,CAAC;AAC9D,MAAI,OAAO,kBAAkB,OAAO,eAAe;AACjD,SAAK,OAAO,wBAAwB,KAAK,UAAU,OAAO,cAAc,CAAC;AAC3E,SAAO;AACT;AAOA,eAAsB,YACpB,QACA,OAAuB,CAAC,GACsB;AAC9C,QAAM,OAAO,gBAAgB,MAAM;AACnC,SAAO,cAAqB,UAAU,OAAO,QAAQ,MAAM,IAAI;AACjE;AAMA,eAAsB,wBACpB,QACA,YACA,OAAuB,CAAC,GACsB;AAC9C,QAAM,OAAO,gBAAgB,MAAM;AACnC,SAAO;AAAA,IACL,UAAU,OAAO;AAAA,IACjB;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAiBA,eAAsB,SACpB,QACA,UAA0B,CAAC,GAC3B,OAAuB,CAAC,GACsB;AAC9C,SAAO,QAAe,UAAU,OAAO,OAAO,MAAM,GAAG,qBAAqB,QAAQ,IAAI,CAAC;AAC3F;AAQA,eAAsB,gBACpB,QACA,UAA0B,CAAC,GAC3B,OAAuB,CAAC,GACsB;AAC9C,SAAO,QAAe,UAAU,OAAO,QAAQ,MAAM,GAAG,qBAAqB,QAAQ,IAAI,CAAC;AAC5F;AAUA,eAAsB,WACpB,QACA,MACA,OAAuB,CAAC,GACsB;AAG9C,QAAM,aAAgC;AAAA,IACpC,GAAG;AAAA,IACH,YAAY,MAAM,QAAQ,KAAK,UAAU,IACrC,KAAK,WAAW,KAAK,GAAG,IACxB,KAAK;AAAA,EACX;AACA,SAAO;AAAA,IACL,UAAU,OAAO,MAAM,MAAM;AAAA,IAC7B;AAAA,IACA;AAAA,EACF;AACF;AAQA,eAAsB,iBACpB,QACA,MACA,OAAuB,CAAC,GACsB;AAC9C,SAAO;AAAA,IACL,UAAU,OAAO,YAAY,MAAM;AAAA,IACnC;AAAA,IACA;AAAA,EACF;AACF;AAUA,eAAsB,gBACpB,OAAuB,CAAC,GACwC;AAChE,SAAO,QAAiC,UAAU,OAAO,SAAS,IAAI;AACxE;AA6EA,eAAsB,sBACpB,MACA,UACA,UAAuC,CAAC,GACxC,OAAuB,CAAC,GACmC;AAC3D,QAAM,OAAO,IAAI,SAAS;AAC1B,OAAK,OAAO,QAAQ,IAAI;AAGxB,OAAK,OAAO,iBAAiB,KAAK,UAAU,QAAQ,CAAC;AACrD,MAAI,OAAO,QAAQ,mBAAmB,UAAU;AAC9C,SAAK,OAAO,oBAAoB,OAAO,QAAQ,cAAc,CAAC;AAAA,EAChE;AAIA,SAAO,aAAa,UAAU,OAAO,kBAAkB,MAAM,IAAI;AACnE;AAWA,eAAsB,qBACpB,MACA,UAA8E,CAAC,GAC/E,OAAuB,CAAC,GACkC;AAC1D,QAAM,OAAO,IAAI,SAAS;AAC1B,OAAK,OAAO,QAAQ,IAAI;AACxB,OAAK,OAAO,SAAS,OAAO,QAAQ,SAAS,CAAC,CAAC;AAC/C,MAAI,OAAO,QAAQ,iBAAiB,UAAU;AAC5C,SAAK,OAAO,kBAAkB,OAAO,QAAQ,YAAY,CAAC;AAAA,EAC5D;AACA,MAAI,OAAO,QAAQ,mBAAmB,UAAU;AAC9C,SAAK,OAAO,oBAAoB,OAAO,QAAQ,cAAc,CAAC;AAAA,EAChE;AACA,SAAO;AAAA,IACL,UAAU,OAAO;AAAA,IACjB;AAAA,IACA;AAAA,EACF;AACF;AAQA,eAAsB,uBACpB,QAKe;AACf,MAAI,OAAO,UAAU;AACnB,UAAM,WAAW,MAAM,MAAM,OAAO,QAAQ;AAC5C,WAAO,SAAS,KAAK;AAAA,EACvB;AACA,MAAI,OAAO,eAAe;AACxB,UAAM,WAAW,MAAM,MAAM,OAAO,aAAa;AACjD,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,6CAA6C,SAAS,MAAM,EAAE;AAAA,IAChF;AACA,WAAO,SAAS,KAAK;AAAA,EACvB;AACA,QAAM,IAAI,MAAM,qDAAqD;AACvE;","names":[]}

package/dist/files/engine/api/direct.d.ts

@@ -0,0 +1,43 @@
+/**
+ * features/files/api/direct.ts
+ *
+ * **Canonical data path for cloud-files.** Pure UI↔DB operations go DIRECT via
+ * supabase-js — never through the Python REST `/files/*` API. Our FE has
+ * Supabase; the REST layer exists only for consumers without it (the extension,
+ * external clients) and for byte-bearing ops (upload/download/sign). Routing a
+ * plain DB read/write through Python is two wasted hops through a slow server.
+ * See CLAUDE.md "Data flow" + features/files/CLOUD_FILES_RPC_DISPOSITIONS.md.
+ *
+ * The cloud-files tables live in the `files` Postgres schema (reach via
+ * `filesDb()`); the operations here are exposed as `public` SECURITY DEFINER
+ * RPCs that self-authorize against `auth.uid()`. The REST modules
+ * (`./files`, `./folders`, …) remain ONLY for byte-bearing ops + non-Supabase
+ * consumers — do not add pure-DB ops there.
+ */
+import type { StorageUsageResponse } from "../types.js";
+/**
+ * Read the authed user's tier + storage usage **directly** via the
+ * `get_usage_status` RPC (replaces `GET /files/usage`). The RPC enforces
+ * `auth.uid() = p_user_id`. Flattens the RPC's `{ limits, usage }` envelope
+ * into the flat `StorageUsageResponse` the UI consumes (same shape the Python
+ * endpoint produced).
+ */
+export declare function getUsageStatusDirect(userId: string, opts?: {
+    isGuest?: boolean;
+    signal?: AbortSignal;
+}): Promise<StorageUsageResponse>;
+/** Soft-delete a file (trash). Returns true if a row was deleted. */
+export declare function softDeleteFileDirect(fileId: string): Promise<boolean>;
+/** Soft-delete a folder + its descendant subtree (cascades in SQL). */
+export declare function softDeleteFolderDirect(folderId: string): Promise<{
+    folders: number;
+    files: number;
+    links: number;
+}>;
+/** Restore a soft-deleted file from trash. Returns true if restored. */
+export declare function restoreFileDirect(fileId: string): Promise<boolean>;
+/** Restore a soft-deleted folder + its descendant subtree. */
+export declare function restoreFolderDirect(folderId: string): Promise<{
+    folders: number;
+    files: number;
+}>;

package/dist/files/engine/api/direct.js

@@ -0,0 +1,73 @@
+import { supabase } from "../host/supabase.js";
+import { pgErrorToError } from "@ai-matrx/data";
+import { runWithSessionRetry } from "../host/supabase.js";
+async function getUsageStatusDirect(userId, opts = {}) {
+  const { data, error } = await runWithSessionRetry(() => {
+    let q = supabase.rpc("get_usage_status", {
+      p_user_id: userId,
+      p_is_guest: opts.isGuest ?? false
+    });
+    if (opts.signal) q = q.abortSignal(opts.signal);
+    return q;
+  });
+  if (error) throw pgErrorToError(error);
+  const { limits, usage } = data;
+  return {
+    tier_id: limits.tier_id,
+    tier_name: limits.tier_name,
+    is_blocked: limits.is_blocked,
+    blocked_reason: limits.blocked_reason,
+    bytes_used: usage.bytes_used,
+    files_count: usage.files_count,
+    daily_upload_count: usage.daily_upload_count,
+    daily_upload_bytes: usage.daily_upload_bytes,
+    max_storage_bytes: limits.max_storage_bytes,
+    max_file_size_bytes: limits.max_file_size_bytes,
+    max_files: limits.max_files,
+    max_versions_per_file: limits.max_versions_per_file,
+    max_daily_uploads: limits.max_daily_uploads,
+    max_daily_upload_bytes: limits.max_daily_upload_bytes,
+    max_bulk_items: limits.max_bulk_items,
+    rate_limit_uploads_per_min: limits.rate_limit_uploads_per_min,
+    rate_limit_downloads_per_min: limits.rate_limit_downloads_per_min,
+    features: limits.features ?? {},
+    ledger_measured: Boolean(usage.user_id),
+    ledger_measured_at: usage.updated_at ?? null
+  };
+}
+async function softDeleteFileDirect(fileId) {
+  const { data, error } = await supabase.rpc("soft_delete_file", {
+    p_file_id: fileId
+  });
+  if (error) throw pgErrorToError(error);
+  return Boolean(data);
+}
+async function softDeleteFolderDirect(folderId) {
+  const { data, error } = await supabase.rpc("soft_delete_folder", {
+    p_folder_id: folderId
+  });
+  if (error) throw pgErrorToError(error);
+  return data;
+}
+async function restoreFileDirect(fileId) {
+  const { data, error } = await supabase.rpc("restore_file", {
+    p_file_id: fileId
+  });
+  if (error) throw pgErrorToError(error);
+  return Boolean(data);
+}
+async function restoreFolderDirect(folderId) {
+  const { data, error } = await supabase.rpc("restore_folder", {
+    p_folder_id: folderId
+  });
+  if (error) throw pgErrorToError(error);
+  return data;
+}
+export {
+  getUsageStatusDirect,
+  restoreFileDirect,
+  restoreFolderDirect,
+  softDeleteFileDirect,
+  softDeleteFolderDirect
+};
+//# sourceMappingURL=direct.js.map

package/dist/files/engine/api/direct.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/direct.ts"],"sourcesContent":["/**\n * features/files/api/direct.ts\n *\n * **Canonical data path for cloud-files.** Pure UI↔DB operations go DIRECT via\n * supabase-js — never through the Python REST `/files/*` API. Our FE has\n * Supabase; the REST layer exists only for consumers without it (the extension,\n * external clients) and for byte-bearing ops (upload/download/sign). Routing a\n * plain DB read/write through Python is two wasted hops through a slow server.\n * See CLAUDE.md \"Data flow\" + features/files/CLOUD_FILES_RPC_DISPOSITIONS.md.\n *\n * The cloud-files tables live in the `files` Postgres schema (reach via\n * `filesDb()`); the operations here are exposed as `public` SECURITY DEFINER\n * RPCs that self-authorize against `auth.uid()`. The REST modules\n * (`./files`, `./folders`, …) remain ONLY for byte-bearing ops + non-Supabase\n * consumers — do not add pure-DB ops there.\n */\n\nimport { supabase } from \"../host/supabase\";\nimport { pgErrorToError } from \"@ai-matrx/data\";\nimport { runWithSessionRetry } from \"../host/supabase\";\nimport type { StorageUsageResponse } from \"../types\";\n\n// ---------------------------------------------------------------------------\n// Usage / quota\n// ---------------------------------------------------------------------------\n\n/** Nested shape returned by the `get_usage_status` RPC. */\ninterface UsageStatusRpc {\n  limits: {\n    tier_id: string;\n    tier_name: string;\n    is_blocked: boolean;\n    blocked_reason: string | null;\n    max_storage_bytes: number | null;\n    max_file_size_bytes: number | null;\n    max_files: number | null;\n    max_versions_per_file: number | null;\n    max_daily_uploads: number | null;\n    max_daily_upload_bytes: number | null;\n    max_bulk_items: number | null;\n    rate_limit_uploads_per_min: number | null;\n    rate_limit_downloads_per_min: number | null;\n    features: Record<string, unknown> | null;\n  };\n  /**\n   * Either a real `files.user_storage_usage` row (which carries `user_id` and\n   * `updated_at`) or the zero object the RPC synthesizes when no row exists.\n   * The presence of `user_id` is the ONLY difference, and it is what tells the\n   * meter whether the number was measured or invented.\n   */\n  usage: {\n    user_id?: string | null;\n    updated_at?: string | null;\n    bytes_used: number;\n    files_count: number;\n    daily_upload_count: number;\n    daily_upload_bytes: number;\n  };\n}\n\n/**\n * Read the authed user's tier + storage usage **directly** via the\n * `get_usage_status` RPC (replaces `GET /files/usage`). The RPC enforces\n * `auth.uid() = p_user_id`. Flattens the RPC's `{ limits, usage }` envelope\n * into the flat `StorageUsageResponse` the UI consumes (same shape the Python\n * endpoint produced).\n */\nexport async function getUsageStatusDirect(\n  userId: string,\n  opts: { isGuest?: boolean; signal?: AbortSignal } = {},\n): Promise<StorageUsageResponse> {\n  const { data, error } = await runWithSessionRetry(() => {\n    let q = supabase.rpc(\"get_usage_status\", {\n      p_user_id: userId,\n      p_is_guest: opts.isGuest ?? false,\n    });\n    if (opts.signal) q = q.abortSignal(opts.signal);\n    return q;\n  });\n  if (error) throw pgErrorToError(error);\n\n  // get_usage_status returns Json directly (no row schema) — sanctioned\n  // Json-direct cast per the type-safety skill's supabase-patterns.md.\n  const { limits, usage } = data as unknown as UsageStatusRpc;\n  return {\n    tier_id: limits.tier_id,\n    tier_name: limits.tier_name,\n    is_blocked: limits.is_blocked,\n    blocked_reason: limits.blocked_reason,\n    bytes_used: usage.bytes_used,\n    files_count: usage.files_count,\n    daily_upload_count: usage.daily_upload_count,\n    daily_upload_bytes: usage.daily_upload_bytes,\n    max_storage_bytes: limits.max_storage_bytes,\n    max_file_size_bytes: limits.max_file_size_bytes,\n    max_files: limits.max_files,\n    max_versions_per_file: limits.max_versions_per_file,\n    max_daily_uploads: limits.max_daily_uploads,\n    max_daily_upload_bytes: limits.max_daily_upload_bytes,\n    max_bulk_items: limits.max_bulk_items,\n    rate_limit_uploads_per_min: limits.rate_limit_uploads_per_min,\n    rate_limit_downloads_per_min: limits.rate_limit_downloads_per_min,\n    features: limits.features ?? {},\n    ledger_measured: Boolean(usage.user_id),\n    ledger_measured_at: usage.updated_at ?? null,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Soft delete / restore (metadata-only — NO byte cleanup, so direct)\n// ---------------------------------------------------------------------------\n//\n// There is no hard delete of a person's file or folder (delete means archive,\n// 2026-09-27); version prune purges S3 objects, so it stays on the Python path.\n// The mutation RPCs are hardened (auth.uid() + iam.has_access) — see\n// migrations/cld_files_mutation_rpc_auth_hardening.sql. The realtime middleware\n// applies a soft-delete echo idempotently (deletedAt → removeFile), so losing\n// the request-id echo dedup is harmless here.\n\n/** Soft-delete a file (trash). Returns true if a row was deleted. */\nexport async function softDeleteFileDirect(fileId: string): Promise<boolean> {\n  const { data, error } = await supabase.rpc(\"soft_delete_file\", {\n    p_file_id: fileId,\n  });\n  if (error) throw pgErrorToError(error);\n  return Boolean(data);\n}\n\n/** Soft-delete a folder + its descendant subtree (cascades in SQL). */\nexport async function softDeleteFolderDirect(\n  folderId: string,\n): Promise<{ folders: number; files: number; links: number }> {\n  const { data, error } = await supabase.rpc(\"soft_delete_folder\", {\n    p_folder_id: folderId,\n  });\n  if (error) throw pgErrorToError(error);\n  // soft_delete_folder returns Json directly (no row schema) — sanctioned\n  // Json-direct cast per the type-safety skill's supabase-patterns.md.\n  return data as unknown as { folders: number; files: number; links: number };\n}\n\n/** Restore a soft-deleted file from trash. Returns true if restored. */\nexport async function restoreFileDirect(fileId: string): Promise<boolean> {\n  const { data, error } = await supabase.rpc(\"restore_file\", {\n    p_file_id: fileId,\n  });\n  if (error) throw pgErrorToError(error);\n  return Boolean(data);\n}\n\n/** Restore a soft-deleted folder + its descendant subtree. */\nexport async function restoreFolderDirect(\n  folderId: string,\n): Promise<{ folders: number; files: number }> {\n  const { data, error } = await supabase.rpc(\"restore_folder\", {\n    p_folder_id: folderId,\n  });\n  if (error) throw pgErrorToError(error);\n  // restore_folder returns Json directly (no row schema) — sanctioned\n  // Json-direct cast per the type-safety skill's supabase-patterns.md.\n  return data as unknown as { folders: number; files: number };\n}\n"],"mappings":"AAiBA,SAAS,gBAAgB;AACzB,SAAS,sBAAsB;AAC/B,SAAS,2BAA2B;AAgDpC,eAAsB,qBACpB,QACA,OAAoD,CAAC,GACtB;AAC/B,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,oBAAoB,MAAM;AACtD,QAAI,IAAI,SAAS,IAAI,oBAAoB;AAAA,MACvC,WAAW;AAAA,MACX,YAAY,KAAK,WAAW;AAAA,IAC9B,CAAC;AACD,QAAI,KAAK,OAAQ,KAAI,EAAE,YAAY,KAAK,MAAM;AAC9C,WAAO;AAAA,EACT,CAAC;AACD,MAAI,MAAO,OAAM,eAAe,KAAK;AAIrC,QAAM,EAAE,QAAQ,MAAM,IAAI;AAC1B,SAAO;AAAA,IACL,SAAS,OAAO;AAAA,IAChB,WAAW,OAAO;AAAA,IAClB,YAAY,OAAO;AAAA,IACnB,gBAAgB,OAAO;AAAA,IACvB,YAAY,MAAM;AAAA,IAClB,aAAa,MAAM;AAAA,IACnB,oBAAoB,MAAM;AAAA,IAC1B,oBAAoB,MAAM;AAAA,IAC1B,mBAAmB,OAAO;AAAA,IAC1B,qBAAqB,OAAO;AAAA,IAC5B,WAAW,OAAO;AAAA,IAClB,uBAAuB,OAAO;AAAA,IAC9B,mBAAmB,OAAO;AAAA,IAC1B,wBAAwB,OAAO;AAAA,IAC/B,gBAAgB,OAAO;AAAA,IACvB,4BAA4B,OAAO;AAAA,IACnC,8BAA8B,OAAO;AAAA,IACrC,UAAU,OAAO,YAAY,CAAC;AAAA,IAC9B,iBAAiB,QAAQ,MAAM,OAAO;AAAA,IACtC,oBAAoB,MAAM,cAAc;AAAA,EAC1C;AACF;AAcA,eAAsB,qBAAqB,QAAkC;AAC3E,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,SAAS,IAAI,oBAAoB;AAAA,IAC7D,WAAW;AAAA,EACb,CAAC;AACD,MAAI,MAAO,OAAM,eAAe,KAAK;AACrC,SAAO,QAAQ,IAAI;AACrB;AAGA,eAAsB,uBACpB,UAC4D;AAC5D,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,SAAS,IAAI,sBAAsB;AAAA,IAC/D,aAAa;AAAA,EACf,CAAC;AACD,MAAI,MAAO,OAAM,eAAe,KAAK;AAGrC,SAAO;AACT;AAGA,eAAsB,kBAAkB,QAAkC;AACxE,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,SAAS,IAAI,gBAAgB;AAAA,IACzD,WAAW;AAAA,EACb,CAAC;AACD,MAAI,MAAO,OAAM,eAAe,KAAK;AACrC,SAAO,QAAQ,IAAI;AACrB;AAGA,eAAsB,oBACpB,UAC6C;AAC7C,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,SAAS,IAAI,kBAAkB;AAAA,IAC3D,aAAa;AAAA,EACf,CAAC;AACD,MAAI,MAAO,OAAM,eAAe,KAAK;AAGrC,SAAO;AACT;","names":[]}

package/dist/files/engine/api/fileOrganization.d.ts

@@ -0,0 +1,34 @@
+/**
+ * features/files/api/fileOrganization.ts — LANE GATES-TAIL (VERIFIER-21 #2)
+ *
+ * A REQUEST ABOUT ONE FILE CARRIES THAT FILE'S ORGANIZATION — READ FROM THE FILE, NEVER FROM
+ * THE PERSON'S PICKER.
+ *
+ * The defect: in a fresh session (header "Choose org") `/files/f/<id>` named the file and then
+ * said "Couldn't load this file — GET /files/<id>/download → HTTP 400", because every per-file
+ * request to the files service went out with no `X-Organization-Id` and the service refused it
+ * ("Choose the organization you're working in"). Picking an organization in the shell made it
+ * open. Access is personal (Arman, 2026-09-23): whether ONE object opens is never decided by
+ * which organization is selected, and an object page resolves its organization FROM THE OBJECT.
+ *
+ * Where the file's organization comes from, in order:
+ *   1. an organization the caller already named (`opts.organizationId`) — always wins;
+ *   2. an organization remembered for this file id — the file page seeds it from the row it
+ *      read under RLS as the person (`files.files.organization_id`), and every per-file read
+ *      that answers records the row's own `organization_id`;
+ *   3. the file row already in the files slice (`cloudFiles.filesById[id].organizationId`),
+ *      loaded by a list or tree under the person's access.
+ * With none of these the request goes as before (the transport's own rule decides); nothing
+ * here ever reads the active selection, so nothing here can guess.
+ */
+import type { RequestOptions } from "../host/python-client.js";
+/** Record the organization a file lives in, as the file's own row says. */
+export declare function rememberFileOrganization(fileId: string | null | undefined, organizationId: string | null | undefined): void;
+/** Record it from any per-file answer that carries the row (`FileRecordApi` and kin). */
+export declare function rememberFileOrganizationFrom(record: unknown): void;
+/** The organization this file lives in, as far as the file itself has told us; null otherwise. */
+export declare function fileOrganizationId(fileId: string): string | null;
+/** `opts` with the file's own organization filled in when the caller named none. */
+export declare function withFileOrganization<T extends RequestOptions>(fileId: string, opts: T): T;
+/** Test seam: forget every remembered file organization. */
+export declare function __resetFileOrganizationsForTest(): void;

package/dist/files/engine/api/fileOrganization.js

@@ -0,0 +1,38 @@
+import { getStoreSingleton } from "../host/store.js";
+const remembered = /* @__PURE__ */ new Map();
+function isOrganizationId(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function rememberFileOrganization(fileId, organizationId) {
+  if (!fileId || !isOrganizationId(organizationId)) return;
+  remembered.set(fileId, organizationId);
+}
+function rememberFileOrganizationFrom(record) {
+  if (!record || typeof record !== "object") return;
+  const row = record;
+  const id = typeof row.id === "string" ? row.id : typeof row.file_id === "string" ? row.file_id : null;
+  rememberFileOrganization(id, row.organization_id);
+}
+function fileOrganizationId(fileId) {
+  const known = remembered.get(fileId);
+  if (known) return known;
+  const state = getStoreSingleton()?.getState();
+  const fromSlice = state?.cloudFiles?.filesById?.[fileId]?.organizationId;
+  return isOrganizationId(fromSlice) ? fromSlice : null;
+}
+function withFileOrganization(fileId, opts) {
+  if (opts.organizationId) return opts;
+  const organizationId = fileOrganizationId(fileId);
+  return organizationId ? { ...opts, organizationId } : opts;
+}
+function __resetFileOrganizationsForTest() {
+  remembered.clear();
+}
+export {
+  __resetFileOrganizationsForTest,
+  fileOrganizationId,
+  rememberFileOrganization,
+  rememberFileOrganizationFrom,
+  withFileOrganization
+};
+//# sourceMappingURL=fileOrganization.js.map

package/dist/files/engine/api/fileOrganization.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/api/fileOrganization.ts"],"sourcesContent":["/**\n * features/files/api/fileOrganization.ts — LANE GATES-TAIL (VERIFIER-21 #2)\n *\n * A REQUEST ABOUT ONE FILE CARRIES THAT FILE'S ORGANIZATION — READ FROM THE FILE, NEVER FROM\n * THE PERSON'S PICKER.\n *\n * The defect: in a fresh session (header \"Choose org\") `/files/f/<id>` named the file and then\n * said \"Couldn't load this file — GET /files/<id>/download → HTTP 400\", because every per-file\n * request to the files service went out with no `X-Organization-Id` and the service refused it\n * (\"Choose the organization you're working in\"). Picking an organization in the shell made it\n * open. Access is personal (Arman, 2026-09-23): whether ONE object opens is never decided by\n * which organization is selected, and an object page resolves its organization FROM THE OBJECT.\n *\n * Where the file's organization comes from, in order:\n *   1. an organization the caller already named (`opts.organizationId`) — always wins;\n *   2. an organization remembered for this file id — the file page seeds it from the row it\n *      read under RLS as the person (`files.files.organization_id`), and every per-file read\n *      that answers records the row's own `organization_id`;\n *   3. the file row already in the files slice (`cloudFiles.filesById[id].organizationId`),\n *      loaded by a list or tree under the person's access.\n * With none of these the request goes as before (the transport's own rule decides); nothing\n * here ever reads the active selection, so nothing here can guess.\n */\n\nimport type { RequestOptions } from \"../host/python-client\";\nimport { getStoreSingleton } from \"../host/store\";\n\nconst remembered = new Map<string, string>();\n\nfunction isOrganizationId(value: unknown): value is string {\n  return typeof value === \"string\" && value.length > 0;\n}\n\n/** Record the organization a file lives in, as the file's own row says. */\nexport function rememberFileOrganization(\n  fileId: string | null | undefined,\n  organizationId: string | null | undefined,\n): void {\n  if (!fileId || !isOrganizationId(organizationId)) return;\n  remembered.set(fileId, organizationId);\n}\n\n/** Record it from any per-file answer that carries the row (`FileRecordApi` and kin). */\nexport function rememberFileOrganizationFrom(record: unknown): void {\n  if (!record || typeof record !== \"object\") return;\n  const row = record as { id?: unknown; file_id?: unknown; organization_id?: unknown };\n  const id = typeof row.id === \"string\" ? row.id : typeof row.file_id === \"string\" ? row.file_id : null;\n  rememberFileOrganization(id, row.organization_id as string | null | undefined);\n}\n\n/** The organization this file lives in, as far as the file itself has told us; null otherwise. */\nexport function fileOrganizationId(fileId: string): string | null {\n  const known = remembered.get(fileId);\n  if (known) return known;\n  const state = getStoreSingleton()?.getState() as\n    | { cloudFiles?: { filesById?: Record<string, { organizationId?: string | null } | undefined> } }\n    | undefined;\n  const fromSlice = state?.cloudFiles?.filesById?.[fileId]?.organizationId;\n  return isOrganizationId(fromSlice) ? fromSlice : null;\n}\n\n/** `opts` with the file's own organization filled in when the caller named none. */\nexport function withFileOrganization<T extends RequestOptions>(fileId: string, opts: T): T {\n  if (opts.organizationId) return opts;\n  const organizationId = fileOrganizationId(fileId);\n  return organizationId ? { ...opts, organizationId } : opts;\n}\n\n/** Test seam: forget every remembered file organization. */\nexport function __resetFileOrganizationsForTest(): void {\n  remembered.clear();\n}\n"],"mappings":"AAyBA,SAAS,yBAAyB;AAElC,MAAM,aAAa,oBAAI,IAAoB;AAE3C,SAAS,iBAAiB,OAAiC;AACzD,SAAO,OAAO,UAAU,YAAY,MAAM,SAAS;AACrD;AAGO,SAAS,yBACd,QACA,gBACM;AACN,MAAI,CAAC,UAAU,CAAC,iBAAiB,cAAc,EAAG;AAClD,aAAW,IAAI,QAAQ,cAAc;AACvC;AAGO,SAAS,6BAA6B,QAAuB;AAClE,MAAI,CAAC,UAAU,OAAO,WAAW,SAAU;AAC3C,QAAM,MAAM;AACZ,QAAM,KAAK,OAAO,IAAI,OAAO,WAAW,IAAI,KAAK,OAAO,IAAI,YAAY,WAAW,IAAI,UAAU;AACjG,2BAAyB,IAAI,IAAI,eAA4C;AAC/E;AAGO,SAAS,mBAAmB,QAA+B;AAChE,QAAM,QAAQ,WAAW,IAAI,MAAM;AACnC,MAAI,MAAO,QAAO;AAClB,QAAM,QAAQ,kBAAkB,GAAG,SAAS;AAG5C,QAAM,YAAY,OAAO,YAAY,YAAY,MAAM,GAAG;AAC1D,SAAO,iBAAiB,SAAS,IAAI,YAAY;AACnD;AAGO,SAAS,qBAA+C,QAAgB,MAAY;AACzF,MAAI,KAAK,eAAgB,QAAO;AAChC,QAAM,iBAAiB,mBAAmB,MAAM;AAChD,SAAO,iBAAiB,EAAE,GAAG,MAAM,eAAe,IAAI;AACxD;AAGO,SAAS,kCAAwC;AACtD,aAAW,MAAM;AACnB;","names":[]}