@ai-matrx/media 0.8.0 → 0.9.1

package/dist/files/engine/upload/tusUpload.js

@@ -0,0 +1,258 @@
+import * as tus from "tus-js-client";
+import { buildHeaders, resolveBaseUrlForPath } from "../host/python-client.js";
+import * as Files from "../api/files.js";
+import { extractErrorMessage } from "@ai-matrx/data/net";
+const TUS_CHUNK_SIZE_BYTES = 16 * 1024 * 1024;
+const TUS_UPLOAD_PATH = "/files/upload/tus";
+function buildUploadMetadataEnvelope(metadata) {
+  const envelope = {
+    // Origin tag aids backend log triage when something goes wrong.
+    origin: "cloudUpload",
+    ...metadata ?? {}
+  };
+  if (!hasUploadOrganization(envelope)) {
+    console.warn(
+      "[buildUploadMetadataEnvelope] upload carries no scope.organization_id \u2014 it will be filed in an organization nobody chose. Route this upload through cloudUpload/cloudUploadRaw so the organization gate runs."
+    );
+  }
+  return envelope;
+}
+function hasUploadOrganization(envelope) {
+  if (typeof envelope.organization_id === "string" && envelope.organization_id)
+    return true;
+  const scope = envelope.scope;
+  return Boolean(
+    scope && typeof scope === "object" && typeof scope.organization_id === "string" && scope.organization_id
+  );
+}
+const URL_DB_NAME = "mtx-tus-urls";
+const URL_STORE = "urls";
+let urlDbPromise = null;
+function openUrlDb() {
+  if (urlDbPromise) return urlDbPromise;
+  urlDbPromise = new Promise((resolve, reject) => {
+    if (typeof indexedDB === "undefined") {
+      reject(new Error("[tusUpload] IndexedDB unavailable"));
+      return;
+    }
+    const req = indexedDB.open(URL_DB_NAME, 1);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(URL_STORE)) {
+        const store = db.createObjectStore(URL_STORE, {
+          keyPath: "urlStorageKey"
+        });
+        store.createIndex("fingerprint", "fingerprint", { unique: false });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("[tusUpload] failed to open mtx-tus-urls"));
+  });
+  urlDbPromise.catch(() => {
+    urlDbPromise = null;
+  });
+  return urlDbPromise;
+}
+function idbRequest(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("IndexedDB failed"));
+  });
+}
+function createTusUrlStorage() {
+  return {
+    async findAllUploads() {
+      const db = await openUrlDb();
+      const tx = db.transaction(URL_STORE, "readonly");
+      const all = await idbRequest(
+        tx.objectStore(URL_STORE).getAll()
+      );
+      return all;
+    },
+    async findUploadsByFingerprint(fingerprint) {
+      const db = await openUrlDb();
+      const tx = db.transaction(URL_STORE, "readonly");
+      const matches = await idbRequest(
+        tx.objectStore(URL_STORE).index("fingerprint").getAll(fingerprint)
+      );
+      return matches;
+    },
+    async removeUpload(urlStorageKey) {
+      const db = await openUrlDb();
+      const tx = db.transaction(URL_STORE, "readwrite");
+      tx.objectStore(URL_STORE).delete(urlStorageKey);
+      await new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error ?? new Error("IndexedDB tx failed"));
+      });
+    },
+    async addUpload(fingerprint, upload) {
+      const urlStorageKey = `tus::${fingerprint}::${Date.now().toString(36)}`;
+      const record = {
+        urlStorageKey,
+        fingerprint,
+        size: upload.size,
+        metadata: upload.metadata,
+        creationTime: upload.creationTime,
+        uploadUrl: upload.uploadUrl,
+        parallelUploadUrls: upload.parallelUploadUrls
+      };
+      const db = await openUrlDb();
+      const tx = db.transaction(URL_STORE, "readwrite");
+      tx.objectStore(URL_STORE).put(record);
+      await new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error ?? new Error("IndexedDB tx failed"));
+      });
+      return urlStorageKey;
+    }
+  };
+}
+async function listStoredTusUploads() {
+  try {
+    const db = await openUrlDb();
+    const tx = db.transaction(URL_STORE, "readonly");
+    const all = await idbRequest(
+      tx.objectStore(URL_STORE).getAll()
+    );
+    return all.map((r) => ({
+      urlStorageKey: r.urlStorageKey,
+      fingerprint: r.fingerprint,
+      size: r.size,
+      metadata: r.metadata,
+      creationTime: r.creationTime,
+      uploadUrl: r.uploadUrl
+    }));
+  } catch (err) {
+    console.error("[tusUpload] listStoredTusUploads failed:", err);
+    return [];
+  }
+}
+async function tusUploadRaw(file, filePath, options, idempotencyKey, deps = {}) {
+  const endpoint = deps.endpointOverride ?? `${resolveBaseUrlForPath(TUS_UPLOAD_PATH, void 0, "POST")}${TUS_UPLOAD_PATH}`;
+  const metadataEnvelope = buildUploadMetadataEnvelope(options.metadata);
+  let cldFileId = null;
+  let aborted = false;
+  try {
+    await new Promise((resolve, reject) => {
+      const upload = new tus.Upload(file, {
+        endpoint,
+        chunkSize: TUS_CHUNK_SIZE_BYTES,
+        retryDelays: [0, 1e3, 3e3, 5e3, 1e4],
+        removeFingerprintOnSuccess: true,
+        urlStorage: deps.urlStorage ?? createTusUrlStorage(),
+        ...deps.httpStack ? { httpStack: deps.httpStack } : {},
+        ...deps.fileReader ? { fileReader: deps.fileReader } : {},
+        metadata: {
+          filename: file.name,
+          filepath: filePath,
+          // ONE validated JSON envelope — tus-js-client base64-encodes the
+          // value per the Upload-Metadata spec; the server parses and merges
+          // it exactly like the buffered `metadata_json` form field.
+          metadata_json: JSON.stringify(metadataEnvelope),
+          ...options.visibility ? { visibility: options.visibility } : {}
+        },
+        onBeforeRequest: async (req) => {
+          const { headers } = await buildHeaders({}, false);
+          if (headers.Authorization) {
+            req.setHeader("Authorization", headers.Authorization);
+          }
+          if (headers["X-Guest-Fingerprint"]) {
+            req.setHeader("X-Guest-Fingerprint", headers["X-Guest-Fingerprint"]);
+          }
+          if (headers["X-Organization-Id"]) {
+            req.setHeader("X-Organization-Id", headers["X-Organization-Id"]);
+          }
+          if (req.getMethod() === "POST") {
+            req.setHeader("X-Idempotency-Key", idempotencyKey);
+          }
+        },
+        onAfterResponse: (_req, res) => {
+          const id = res.getHeader("X-Cld-File-Id");
+          if (id) cldFileId = id;
+        },
+        onProgress: (bytesSent, bytesTotal) => {
+          options.onProgress?.({ loaded: bytesSent, total: bytesTotal });
+        },
+        onSuccess: () => resolve(),
+        onError: (error) => reject(error)
+      });
+      if (options.signal) {
+        if (options.signal.aborted) {
+          aborted = true;
+          reject(new Error("Upload cancelled"));
+          return;
+        }
+        options.signal.addEventListener(
+          "abort",
+          () => {
+            aborted = true;
+            void upload.abort();
+            reject(new Error("Upload cancelled"));
+          },
+          { once: true }
+        );
+      }
+      void upload.findPreviousUploads().then((previous) => {
+        if (previous.length > 0) {
+          upload.resumeFromPreviousUpload(previous[0]);
+        }
+        upload.start();
+      }).catch((err) => {
+        console.warn(
+          "[tusUpload] previous-upload lookup failed \u2014 starting fresh:",
+          err
+        );
+        upload.start();
+      });
+    });
+  } catch (err) {
+    if (cldFileId && !aborted) {
+      console.warn(
+        `[tusUpload] transfer reported an error but the server exposed X-Cld-File-Id=${cldFileId} \u2014 recovering the completed session.`
+      );
+    } else {
+      return {
+        ok: false,
+        error: extractErrorMessage(err),
+        errorCode: aborted ? "upload_cancelled" : "tus_upload_failed",
+        fileName: file.name
+      };
+    }
+  }
+  if (!cldFileId) {
+    return {
+      ok: false,
+      error: "TUS upload finished but the server never exposed X-Cld-File-Id \u2014 the file cannot be resolved. Check server CORS expose_headers.",
+      errorCode: "tus_missing_file_id",
+      fileName: file.name
+    };
+  }
+  try {
+    const { data: record } = await Files.getFile(cldFileId);
+    return {
+      ok: true,
+      fileId: record.id,
+      filePath: record.file_path,
+      fileSize: record.size_bytes ?? file.size,
+      versionNumber: record.current_version ?? 1,
+      url: null
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `TUS upload completed (file ${cldFileId}) but the record fetch failed: ${extractErrorMessage(err)}`,
+      errorCode: "tus_record_fetch_failed",
+      fileName: file.name
+    };
+  }
+}
+export {
+  TUS_CHUNK_SIZE_BYTES,
+  TUS_UPLOAD_PATH,
+  buildUploadMetadataEnvelope,
+  createTusUrlStorage,
+  listStoredTusUploads,
+  tusUploadRaw
+};
+//# sourceMappingURL=tusUpload.js.map

package/dist/files/engine/upload/tusUpload.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/upload/tusUpload.ts"],"sourcesContent":["/**\n * features/files/upload/tusUpload.ts\n *\n * Resumable (TUS) upload transport for the file handler — the large-file\n * sibling of the buffered multipart path in `cloudUpload.ts`. Callers never\n * import this directly: `cloudUpload` routes here per the transport policy\n * (size ≥ `TUS_TRANSPORT_THRESHOLD_BYTES`, or an explicit\n * `transport: \"tus\"` override).\n *\n * Wire contract (common-docs/systems/media/media-capture/FEATURE.md § TUS):\n * - Endpoint: `${PYTHON_BACKEND}/files/upload/tus` (resolved through the same\n *   base-url helper the python-client uses — server toggle respected).\n * - Explicit chunk size 16 MiB (server bounds 8–32 MiB; never the client\n *   default).\n * - `Upload-Metadata` carries `filename`, `filepath`, and ONE `metadata_json`\n *   key — the base64 of the SAME JSON object the buffered path sends as its\n *   `metadata_json` form field (tus-js-client base64-encodes values; the\n *   object is built by the shared `buildUploadMetadataEnvelope`). Parity with\n *   buffered uploads is a tested invariant.\n * - FRESH Authorization per request (`onBeforeRequest` re-reads the Supabase\n *   session — long uploads outlive a single JWT).\n * - `X-Idempotency-Key` on the creation POST only.\n * - Final `X-Cld-File-Id` captured from response headers (final PATCH, or the\n *   completed-session HEAD/POST recovery paths) — a lost final response never\n *   forces a re-upload.\n * - Resume URLs live in a dedicated tiny IndexedDB (`mtx-tus-urls`) — NEVER\n *   the recorder chunk journal DB.\n *\n * NOT LIVE-TESTED against production: the server side (CORS, metadata parity,\n * completed-HEAD recovery) exists in aidream locally but is not deployed —\n * see features/files/handler/FEATURE.md § Transport policy for the pending\n * E2E note. The client is unit-tested with an injected HttpStack.\n */\n\nimport * as tus from \"tus-js-client\";\nimport { buildHeaders, resolveBaseUrlForPath } from \"../host/python-client\";\n// eslint-disable-next-line no-restricted-imports -- transport sibling INSIDE the ring-fenced upload internals (same as cloudUpload.ts's own internal imports)\nimport * as Files from \"../api/files\";\nimport { extractErrorMessage } from \"@ai-matrx/data/net\";\n// eslint-disable-next-line no-restricted-imports -- type-only import between the two upload transports (both internal to features/files/upload)\nimport type {\n  CloudUploadOptions,\n  CloudUploadResult,\n} from \"./cloudUpload\";\n\n// ─── Constants ───────────────────────────────────────────────────────────────\n\n/** Server-bounded chunk size (8–32 MiB allowed): 16 MiB. */\nexport const TUS_CHUNK_SIZE_BYTES = 16 * 1024 * 1024;\n\nexport const TUS_UPLOAD_PATH = \"/files/upload/tus\";\n\n// ─── Shared metadata envelope (buffered ↔ TUS parity) ────────────────────────\n\n/**\n * The ONE builder for the upload metadata JSON object. The buffered path\n * serializes this into the `metadata_json` form field\n * (`features/files/api/files.ts`); the TUS path serializes the SAME object\n * into the `metadata_json` Upload-Metadata key. One builder ⇒ the two\n * transports can never drift (parity is unit-tested).\n *\n * 🚨 `scope.organization_id` is the OWNING WORKSPACE of the uploaded file, and\n * it is not decoration. The server reads it (`SyncEngine._metadata_organization_id`,\n * membership-checked against `iam.has_org_access_for`) and stamps\n * `files.files.organization_id` from it. Omit it and the server falls back to\n * the uploader's OWN organization — which is how, on 2026-08-30, a screenshot\n * attached from the composer landed in a own organization nobody had chosen\n * and then disagreed with the team organization the person actually picked.\n *\n * Callers never set it by hand: `bindUploadOrganization` in `cloudUpload.ts`\n * resolves it for every upload before a byte moves, so it is already present in\n * `metadata` by the time this builder runs. This function keeps the shape\n * canonical and is where the contract is written down.\n */\nexport function buildUploadMetadataEnvelope(\n  metadata: Record<string, unknown> | undefined,\n): Record<string, unknown> {\n  const envelope: Record<string, unknown> = {\n    // Origin tag aids backend log triage when something goes wrong.\n    origin: \"cloudUpload\",\n    ...(metadata ?? {}),\n  };\n  if (\n    process.env.NODE_ENV !== \"production\" &&\n    !hasUploadOrganization(envelope)\n  ) {\n    // Loud in development, never a hard failure in production: a missing\n    // organization is a silent mis-filing, and silence is exactly what made the\n    // original bug survive. The server still fails closed on its own terms.\n    console.warn(\n      \"[buildUploadMetadataEnvelope] upload carries no scope.organization_id — \" +\n        \"it will be filed in an organization nobody chose. Route this \" +\n        \"upload through cloudUpload/cloudUploadRaw so the organization gate runs.\",\n    );\n  }\n  return envelope;\n}\n\nfunction hasUploadOrganization(envelope: Record<string, unknown>): boolean {\n  if (typeof envelope.organization_id === \"string\" && envelope.organization_id)\n    return true;\n  const scope = envelope.scope;\n  return Boolean(\n    scope &&\n      typeof scope === \"object\" &&\n      typeof (scope as Record<string, unknown>).organization_id === \"string\" &&\n      (scope as Record<string, unknown>).organization_id,\n  );\n}\n\n// ─── Dedicated resume-URL storage (mtx-tus-urls) ─────────────────────────────\n\nconst URL_DB_NAME = \"mtx-tus-urls\";\nconst URL_STORE = \"urls\";\n\ninterface StoredTusUpload {\n  urlStorageKey: string;\n  fingerprint: string;\n  size: number | null;\n  metadata: Record<string, string>;\n  creationTime: string;\n  uploadUrl: string | null;\n  parallelUploadUrls: string[] | null;\n}\n\nlet urlDbPromise: Promise<IDBDatabase> | null = null;\n\nfunction openUrlDb(): Promise<IDBDatabase> {\n  if (urlDbPromise) return urlDbPromise;\n  urlDbPromise = new Promise<IDBDatabase>((resolve, reject) => {\n    if (typeof indexedDB === \"undefined\") {\n      reject(new Error(\"[tusUpload] IndexedDB unavailable\"));\n      return;\n    }\n    const req = indexedDB.open(URL_DB_NAME, 1);\n    req.onupgradeneeded = () => {\n      const db = req.result;\n      if (!db.objectStoreNames.contains(URL_STORE)) {\n        const store = db.createObjectStore(URL_STORE, {\n          keyPath: \"urlStorageKey\",\n        });\n        store.createIndex(\"fingerprint\", \"fingerprint\", { unique: false });\n      }\n    };\n    req.onsuccess = () => resolve(req.result);\n    req.onerror = () =>\n      reject(req.error ?? new Error(\"[tusUpload] failed to open mtx-tus-urls\"));\n  });\n  urlDbPromise.catch(() => {\n    urlDbPromise = null;\n  });\n  return urlDbPromise;\n}\n\nfunction idbRequest<T>(req: IDBRequest<T>): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    req.onsuccess = () => resolve(req.result);\n    req.onerror = () => reject(req.error ?? new Error(\"IndexedDB failed\"));\n  });\n}\n\ntype PreviousUpload = Awaited<\n  ReturnType<tus.Upload[\"findPreviousUploads\"]>\n>[number];\n\n/** tus-js-client UrlStorage backed by the dedicated `mtx-tus-urls` DB —\n *  deliberately SEPARATE from the recorder chunk journal. */\nexport function createTusUrlStorage(): NonNullable<\n  ConstructorParameters<typeof tus.Upload>[1][\"urlStorage\"]\n> {\n  return {\n    async findAllUploads(): Promise<PreviousUpload[]> {\n      const db = await openUrlDb();\n      const tx = db.transaction(URL_STORE, \"readonly\");\n      const all = await idbRequest(\n        tx.objectStore(URL_STORE).getAll() as IDBRequest<StoredTusUpload[]>,\n      );\n      return all;\n    },\n    async findUploadsByFingerprint(\n      fingerprint: string,\n    ): Promise<PreviousUpload[]> {\n      const db = await openUrlDb();\n      const tx = db.transaction(URL_STORE, \"readonly\");\n      const matches = await idbRequest(\n        tx\n          .objectStore(URL_STORE)\n          .index(\"fingerprint\")\n          .getAll(fingerprint) as IDBRequest<StoredTusUpload[]>,\n      );\n      return matches;\n    },\n    async removeUpload(urlStorageKey: string): Promise<void> {\n      const db = await openUrlDb();\n      const tx = db.transaction(URL_STORE, \"readwrite\");\n      tx.objectStore(URL_STORE).delete(urlStorageKey);\n      await new Promise<void>((resolve, reject) => {\n        tx.oncomplete = () => resolve();\n        tx.onerror = () => reject(tx.error ?? new Error(\"IndexedDB tx failed\"));\n      });\n    },\n    async addUpload(\n      fingerprint: string,\n      upload: PreviousUpload,\n    ): Promise<string> {\n      const urlStorageKey = `tus::${fingerprint}::${Date.now().toString(36)}`;\n      const record: StoredTusUpload = {\n        urlStorageKey,\n        fingerprint,\n        size: upload.size,\n        metadata: upload.metadata,\n        creationTime: upload.creationTime,\n        uploadUrl: upload.uploadUrl,\n        parallelUploadUrls: upload.parallelUploadUrls,\n      };\n      const db = await openUrlDb();\n      const tx = db.transaction(URL_STORE, \"readwrite\");\n      tx.objectStore(URL_STORE).put(record);\n      await new Promise<void>((resolve, reject) => {\n        tx.oncomplete = () => resolve();\n        tx.onerror = () => reject(tx.error ?? new Error(\"IndexedDB tx failed\"));\n      });\n      return urlStorageKey;\n    },\n  };\n}\n\n/** Read-only summary of a stored TUS resume session (diagnostics surfaces —\n *  /camera's resume-pending indicator, /camera/admin). */\nexport interface StoredTusUploadSummary {\n  urlStorageKey: string;\n  fingerprint: string;\n  size: number | null;\n  metadata: Record<string, string>;\n  creationTime: string;\n  uploadUrl: string | null;\n}\n\n/**\n * List every stored TUS resume-URL entry (the `mtx-tus-urls` DB). Read-only —\n * resuming still happens inside `tusUploadRaw` via the UrlStorage; this only\n * lets management surfaces SHOW that a resumable session is pending. Returns\n * [] where IndexedDB is unavailable (never throws — diagnostics must not\n * break a page).\n */\nexport async function listStoredTusUploads(): Promise<\n  StoredTusUploadSummary[]\n> {\n  try {\n    const db = await openUrlDb();\n    const tx = db.transaction(URL_STORE, \"readonly\");\n    const all = await idbRequest(\n      tx.objectStore(URL_STORE).getAll() as IDBRequest<StoredTusUpload[]>,\n    );\n    return all.map((r) => ({\n      urlStorageKey: r.urlStorageKey,\n      fingerprint: r.fingerprint,\n      size: r.size,\n      metadata: r.metadata,\n      creationTime: r.creationTime,\n      uploadUrl: r.uploadUrl,\n    }));\n  } catch (err) {\n    console.error(\"[tusUpload] listStoredTusUploads failed:\", err);\n    return [];\n  }\n}\n\n// ─── The transport ───────────────────────────────────────────────────────────\n\nexport interface TusUploadDeps {\n  /** Injected HttpStack for unit tests (mock wire, no XHR). */\n  httpStack?: tus.HttpStack;\n  /** Injected file reader for unit tests (Node builds of tus-js-client\n   *  cannot slice browser Files). */\n  fileReader?: ConstructorParameters<typeof tus.Upload>[1][\"fileReader\"];\n  /** Override the endpoint (tests). */\n  endpointOverride?: string;\n  /** Override URL storage (tests). */\n  urlStorage?: ReturnType<typeof createTusUrlStorage>;\n}\n\n/**\n * Resumable upload of one file via TUS. Same result contract as\n * `cloudUploadRaw` — `{ ok: true, fileId, ... } | { ok: false, error }`,\n * never throws. Automatically resumes a previous session for the same file\n * (custom UrlStorage + server HEAD), including the completed-session\n * recovery: when the server reports the session already finished and hands\n * back `X-Cld-File-Id`, the upload is skipped and the file resolves directly.\n */\nexport async function tusUploadRaw(\n  file: File,\n  filePath: string,\n  options: CloudUploadOptions,\n  idempotencyKey: string,\n  deps: TusUploadDeps = {},\n): Promise<CloudUploadResult> {\n  const endpoint =\n    deps.endpointOverride ??\n    `${resolveBaseUrlForPath(TUS_UPLOAD_PATH, undefined, \"POST\")}${TUS_UPLOAD_PATH}`;\n\n  const metadataEnvelope = buildUploadMetadataEnvelope(options.metadata);\n\n  let cldFileId: string | null = null;\n  let aborted = false;\n\n  try {\n    await new Promise<void>((resolve, reject) => {\n      const upload: tus.Upload = new tus.Upload(file, {\n        endpoint,\n        chunkSize: TUS_CHUNK_SIZE_BYTES,\n        retryDelays: [0, 1000, 3000, 5000, 10000],\n        removeFingerprintOnSuccess: true,\n        urlStorage: deps.urlStorage ?? createTusUrlStorage(),\n        ...(deps.httpStack ? { httpStack: deps.httpStack } : {}),\n        ...(deps.fileReader ? { fileReader: deps.fileReader } : {}),\n        metadata: {\n          filename: file.name,\n          filepath: filePath,\n          // ONE validated JSON envelope — tus-js-client base64-encodes the\n          // value per the Upload-Metadata spec; the server parses and merges\n          // it exactly like the buffered `metadata_json` form field.\n          metadata_json: JSON.stringify(metadataEnvelope),\n          ...(options.visibility ? { visibility: options.visibility } : {}),\n        },\n        onBeforeRequest: async (req) => {\n          // FRESH auth on EVERY request — long uploads outlive a JWT.\n          //\n          // `buildHeaders` (lib/python-client.ts) is mandatory-org, fail-closed:\n          // it resolves the organization the SAME way `bindUploadOrganization`\n          // in cloudUpload.ts already committed it (that gate dispatches into\n          // Redux BEFORE this ever runs — see OrganizationGateDialog's\n          // `resolveOrganizationForBlockedAction` — so the selection is already\n          // there by the time the first chunk goes out). Until this fix,\n          // X-Organization-Id was computed here and then silently dropped —\n          // only Authorization and X-Guest-Fingerprint were copied onto the\n          // TUS request, so every resumable upload reached the server\n          // completely unscoped (aidream commit 8e5ee0b93 now 400s that).\n          const { headers } = await buildHeaders({}, false);\n          if (headers.Authorization) {\n            req.setHeader(\"Authorization\", headers.Authorization);\n          }\n          if (headers[\"X-Guest-Fingerprint\"]) {\n            req.setHeader(\"X-Guest-Fingerprint\", headers[\"X-Guest-Fingerprint\"]);\n          }\n          if (headers[\"X-Organization-Id\"]) {\n            req.setHeader(\"X-Organization-Id\", headers[\"X-Organization-Id\"]);\n          }\n          if (req.getMethod() === \"POST\") {\n            // Creation only — one intended upload, one key.\n            req.setHeader(\"X-Idempotency-Key\", idempotencyKey);\n          }\n        },\n        onAfterResponse: (_req, res) => {\n          // The final PATCH (and the completed-session HEAD recovery) carry\n          // the created file id. Capture it whenever it appears.\n          const id = res.getHeader(\"X-Cld-File-Id\");\n          if (id) cldFileId = id;\n        },\n        onProgress: (bytesSent, bytesTotal) => {\n          options.onProgress?.({ loaded: bytesSent, total: bytesTotal });\n        },\n        onSuccess: () => resolve(),\n        onError: (error) => reject(error),\n      });\n\n      if (options.signal) {\n        if (options.signal.aborted) {\n          aborted = true;\n          reject(new Error(\"Upload cancelled\"));\n          return;\n        }\n        options.signal.addEventListener(\n          \"abort\",\n          () => {\n            aborted = true;\n            void upload.abort();\n            reject(new Error(\"Upload cancelled\"));\n          },\n          { once: true },\n        );\n      }\n\n      // Resume automatically when a previous session for this file exists —\n      // tus-js-client HEADs the stored URL; a completed session resolves via\n      // the X-Cld-File-Id captured in onAfterResponse.\n      void upload\n        .findPreviousUploads()\n        .then((previous) => {\n          if (previous.length > 0) {\n            upload.resumeFromPreviousUpload(previous[0]);\n          }\n          upload.start();\n        })\n        .catch((err) => {\n          console.warn(\n            \"[tusUpload] previous-upload lookup failed — starting fresh:\",\n            err,\n          );\n          upload.start();\n        });\n    });\n  } catch (err) {\n    if (cldFileId && !aborted) {\n      // Completed-session recovery: the transfer errored (e.g. a lost final\n      // response surfaced as an error) but the server told us the file\n      // exists. Resolve it instead of failing/re-uploading. LOUD by design.\n      console.warn(\n        `[tusUpload] transfer reported an error but the server exposed ` +\n          `X-Cld-File-Id=${cldFileId} — recovering the completed session.`,\n      );\n    } else {\n      return {\n        ok: false,\n        error: extractErrorMessage(err),\n        errorCode: aborted ? \"upload_cancelled\" : \"tus_upload_failed\",\n        fileName: file.name,\n      };\n    }\n  }\n\n  if (!cldFileId) {\n    return {\n      ok: false,\n      error:\n        \"TUS upload finished but the server never exposed X-Cld-File-Id — \" +\n        \"the file cannot be resolved. Check server CORS expose_headers.\",\n      errorCode: \"tus_missing_file_id\",\n      fileName: file.name,\n    };\n  }\n\n  // Hydrate the canonical row so the result matches the buffered contract.\n  try {\n    const { data: record } = await Files.getFile(cldFileId);\n    return {\n      ok: true,\n      fileId: record.id,\n      filePath: record.file_path,\n      fileSize: record.size_bytes ?? file.size,\n      versionNumber: record.current_version ?? 1,\n      url: null,\n    };\n  } catch (err) {\n    return {\n      ok: false,\n      error: `TUS upload completed (file ${cldFileId}) but the record fetch failed: ${extractErrorMessage(err)}`,\n      errorCode: \"tus_record_fetch_failed\",\n      fileName: file.name,\n    };\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/files/engine/upload/uploadDedupGuard.d.ts

@@ -0,0 +1,58 @@
+/**
+ * features/files/upload/uploadDedupGuard.ts
+ *
+ * Root cause (`common-docs/projects/acquisition-frontier/own-files/VERIFICATION.md`
+ * §12, 2026-09-18): in a 7-file pile, both zero-byte files were uploaded
+ * TWICE, 18s apart, the second auto-renamed "(1)" by `uniqueName()` in
+ * `features/files/redux/thunks.ts` — right after the dev server had refused
+ * connections. A client-side retry of the whole `uploadFiles()` dispatch
+ * after a transient failure re-sends a file whose first attempt may already
+ * have landed server-side (the client only knows its OWN request failed —
+ * a connection reset gives no proof the server never received the bytes).
+ *
+ * The obvious fix is the backend's OWN `X-Idempotency-Key` mechanism
+ * (`lib/python-client.ts` already sends it, `aidream` already stores it in
+ * `metadata._idempotency_key`) — but it is not the full answer here: the
+ * key is only reused *within* a single `uploadFiles()` dispatch
+ * (`newRequestId()` mints a fresh one per worker() call in thunks.ts), and
+ * server-side `_replayable_412` in `aidream/aidream/api/routers/files/__init__.py`
+ * only replays a 412 (precondition-failed) response under the key — a
+ * SUCCESSFUL upload is never deduped by the server on replay. So a second,
+ * independent `uploadFiles()` dispatch for the same intended file — the
+ * shape a caller-level retry takes — is indistinguishable from a genuinely
+ * new upload to both client and server.
+ *
+ * This guard closes the gap client-side, per (folder, name, size): the
+ * FIRST claim for a signature performs the real network request; any
+ * SECOND claim for the same signature while that request is still in
+ * flight, or shortly after it landed, reuses the first attempt's outcome
+ * instead of sending the bytes again. A claim that ends in failure is
+ * cleared immediately, so a genuine "it never landed, please retry" case is
+ * never blocked — only a request whose outcome is still pending, or already
+ * known-good, is deduped.
+ */
+export interface DedupedUploadOutcome {
+    fileId: string;
+    filePath: string;
+}
+/** The dedup key: same folder, same original name, same byte count. */
+export declare function uploadDedupKey(folderPath: string, fileName: string, fileSize: number): string;
+export type UploadClaim = {
+    shared: true;
+    promise: Promise<DedupedUploadOutcome>;
+} | {
+    shared: false;
+    /**
+     * The caller that owns this claim MUST call `settle` exactly once
+     * with the real upload's outcome (or a rejected promise on failure).
+     */
+    settle: (outcome: Promise<DedupedUploadOutcome>) => void;
+};
+/**
+ * Claim a signature before starting an upload. See module doc for the
+ * contract: a `shared: true` result means someone else already owns this
+ * signature — await its `promise` instead of sending the file again.
+ */
+export declare function claimUpload(key: string): UploadClaim;
+/** Test-only: clears every claim so suites don't leak state between tests. */
+export declare function __resetUploadDedupGuardForTests(): void;

package/dist/files/engine/upload/uploadDedupGuard.js

@@ -0,0 +1,41 @@
+const CLAIM_WINDOW_MS = 3 * 60 * 1e3;
+const claims = /* @__PURE__ */ new Map();
+function uploadDedupKey(folderPath, fileName, fileSize) {
+  return [folderPath, fileName, String(fileSize)].join("\\0");
+}
+function claimUpload(key) {
+  const now = Date.now();
+  const existing = claims.get(key);
+  if (existing && existing.expiresAt > now) {
+    return { shared: true, promise: existing.promise };
+  }
+  let settleFn;
+  const publicPromise = new Promise(
+    (resolve, reject) => {
+      settleFn = (outcome) => {
+        outcome.then(
+          (value) => {
+            resolve(value);
+          },
+          (err) => {
+            claims.delete(key);
+            reject(err instanceof Error ? err : new Error(String(err)));
+          }
+        );
+      };
+    }
+  );
+  publicPromise.catch(() => {
+  });
+  claims.set(key, { promise: publicPromise, expiresAt: now + CLAIM_WINDOW_MS });
+  return { shared: false, settle: settleFn };
+}
+function __resetUploadDedupGuardForTests() {
+  claims.clear();
+}
+export {
+  __resetUploadDedupGuardForTests,
+  claimUpload,
+  uploadDedupKey
+};
+//# sourceMappingURL=uploadDedupGuard.js.map

package/dist/files/engine/upload/uploadDedupGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/upload/uploadDedupGuard.ts"],"sourcesContent":["/**\n * features/files/upload/uploadDedupGuard.ts\n *\n * Root cause (`common-docs/projects/acquisition-frontier/own-files/VERIFICATION.md`\n * §12, 2026-09-18): in a 7-file pile, both zero-byte files were uploaded\n * TWICE, 18s apart, the second auto-renamed \"(1)\" by `uniqueName()` in\n * `features/files/redux/thunks.ts` — right after the dev server had refused\n * connections. A client-side retry of the whole `uploadFiles()` dispatch\n * after a transient failure re-sends a file whose first attempt may already\n * have landed server-side (the client only knows its OWN request failed —\n * a connection reset gives no proof the server never received the bytes).\n *\n * The obvious fix is the backend's OWN `X-Idempotency-Key` mechanism\n * (`lib/python-client.ts` already sends it, `aidream` already stores it in\n * `metadata._idempotency_key`) — but it is not the full answer here: the\n * key is only reused *within* a single `uploadFiles()` dispatch\n * (`newRequestId()` mints a fresh one per worker() call in thunks.ts), and\n * server-side `_replayable_412` in `aidream/aidream/api/routers/files/__init__.py`\n * only replays a 412 (precondition-failed) response under the key — a\n * SUCCESSFUL upload is never deduped by the server on replay. So a second,\n * independent `uploadFiles()` dispatch for the same intended file — the\n * shape a caller-level retry takes — is indistinguishable from a genuinely\n * new upload to both client and server.\n *\n * This guard closes the gap client-side, per (folder, name, size): the\n * FIRST claim for a signature performs the real network request; any\n * SECOND claim for the same signature while that request is still in\n * flight, or shortly after it landed, reuses the first attempt's outcome\n * instead of sending the bytes again. A claim that ends in failure is\n * cleared immediately, so a genuine \"it never landed, please retry\" case is\n * never blocked — only a request whose outcome is still pending, or already\n * known-good, is deduped.\n */\n\nexport interface DedupedUploadOutcome {\n  fileId: string;\n  filePath: string;\n}\n\ninterface Claim {\n  promise: Promise<DedupedUploadOutcome>;\n  expiresAt: number;\n}\n\n/**\n * How long a landed (or in-flight) upload's signature stays claimed. Long\n * enough to cover the 18s gap actually observed between the two identical\n * uploads in the verifier's run, with wide margin for a slower connection.\n */\nconst CLAIM_WINDOW_MS = 3 * 60 * 1000;\n\nconst claims = new Map<string, Claim>();\n\n/** The dedup key: same folder, same original name, same byte count. */\nexport function uploadDedupKey(\n  folderPath: string,\n  fileName: string,\n  fileSize: number,\n): string {\n  return [folderPath, fileName, String(fileSize)].join(\"\\\\0\");\n}\n\nexport type UploadClaim =\n  | { shared: true; promise: Promise<DedupedUploadOutcome> }\n  | {\n      shared: false;\n      /**\n       * The caller that owns this claim MUST call `settle` exactly once\n       * with the real upload's outcome (or a rejected promise on failure).\n       */\n      settle: (outcome: Promise<DedupedUploadOutcome>) => void;\n    };\n\n/**\n * Claim a signature before starting an upload. See module doc for the\n * contract: a `shared: true` result means someone else already owns this\n * signature — await its `promise` instead of sending the file again.\n */\nexport function claimUpload(key: string): UploadClaim {\n  const now = Date.now();\n  const existing = claims.get(key);\n  if (existing && existing.expiresAt > now) {\n    return { shared: true, promise: existing.promise };\n  }\n\n  let settleFn!: (outcome: Promise<DedupedUploadOutcome>) => void;\n  const publicPromise = new Promise<DedupedUploadOutcome>(\n    (resolve, reject) => {\n      settleFn = (outcome) => {\n        outcome.then(\n          (value) => {\n            // Success stays claimed for the full window — a landed upload\n            // must keep deduping late-arriving retries too.\n            resolve(value);\n          },\n          (err) => {\n            // A failed attempt must never haunt a real retry: clear the\n            // slot immediately so the next claim for this signature runs\n            // for real instead of replaying a failure forever.\n            claims.delete(key);\n            reject(err instanceof Error ? err : new Error(String(err)));\n          },\n        );\n      };\n    },\n  );\n  // Every claim gets a silent subscriber of its own: a claim nobody ever\n  // shares (the common case — most uploads never race a retry) must not\n  // trip Node's unhandled-rejection detector when it fails. This does not\n  // swallow the failure for a real shared consumer — each `.then()`/`.catch()`\n  // on the same promise still sees the rejection independently.\n  publicPromise.catch(() => {});\n  claims.set(key, { promise: publicPromise, expiresAt: now + CLAIM_WINDOW_MS });\n  return { shared: false, settle: settleFn };\n}\n\n/** Test-only: clears every claim so suites don't leak state between tests. */\nexport function __resetUploadDedupGuardForTests(): void {\n  claims.clear();\n}\n"],"mappings":"AAiDA,MAAM,kBAAkB,IAAI,KAAK;AAEjC,MAAM,SAAS,oBAAI,IAAmB;AAG/B,SAAS,eACd,YACA,UACA,UACQ;AACR,SAAO,CAAC,YAAY,UAAU,OAAO,QAAQ,CAAC,EAAE,KAAK,KAAK;AAC5D;AAkBO,SAAS,YAAY,KAA0B;AACpD,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,WAAW,OAAO,IAAI,GAAG;AAC/B,MAAI,YAAY,SAAS,YAAY,KAAK;AACxC,WAAO,EAAE,QAAQ,MAAM,SAAS,SAAS,QAAQ;AAAA,EACnD;AAEA,MAAI;AACJ,QAAM,gBAAgB,IAAI;AAAA,IACxB,CAAC,SAAS,WAAW;AACnB,iBAAW,CAAC,YAAY;AACtB,gBAAQ;AAAA,UACN,CAAC,UAAU;AAGT,oBAAQ,KAAK;AAAA,UACf;AAAA,UACA,CAAC,QAAQ;AAIP,mBAAO,OAAO,GAAG;AACjB,mBAAO,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,UAC5D;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAMA,gBAAc,MAAM,MAAM;AAAA,EAAC,CAAC;AAC5B,SAAO,IAAI,KAAK,EAAE,SAAS,eAAe,WAAW,MAAM,gBAAgB,CAAC;AAC5E,SAAO,EAAE,QAAQ,OAAO,QAAQ,SAAS;AAC3C;AAGO,SAAS,kCAAwC;AACtD,SAAO,MAAM;AACf;","names":[]}

package/dist/files/engine/upload/uploadGuardOpeners.d.ts

@@ -0,0 +1,70 @@
+/**
+ * features/files/upload/uploadGuardOpeners.ts
+ *
+ * Module-level imperative API for the upload-guard system. Same shape
+ * as `cloudFilesPickerOpeners` — a single host component registers a
+ * handler at mount, and any code anywhere can call `requestUpload`
+ * without threading state.
+ *
+ * The host pre-flights uploaded files for duplicates (identical
+ * checksum or filename collisions in the target folder), shows a
+ * resolution dialog if needed, and only then dispatches the upload.
+ * If the host hasn't mounted yet, `requestUpload` warns in dev and
+ * falls back to a direct thunk dispatch so we don't break the upload
+ * for the (rare) caller that fires during boot.
+ *
+ * Pure TypeScript — no React, no dialog markup. Safe to import from
+ * anywhere, including the static graph of route entries.
+ */
+import type { UploadFilesArg } from "../types.js";
+/**
+ * The handler the host registers at mount. Returns a promise that
+ * resolves with the same shape as the underlying `uploadFiles` thunk
+ * payload — `{ uploaded: string[], failed: [...] }`.
+ */
+export type UploadGuardHandler = (arg: UploadFilesArg) => Promise<UploadGuardResult>;
+export interface UploadGuardResult {
+    uploaded: string[];
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+    /** True when the user dismissed the duplicate dialog. */
+    cancelled: boolean;
+    /**
+     * Files the user chose to NOT re-upload because a duplicate already
+     * exists, and they explicitly picked "use the existing one." Each
+     * entry maps the index of the original input file (in `arg.files`)
+     * to the existing `cld_files.id` the user picked.
+     *
+     * The chat-resource-attach flow uses this to wire the existing
+     * fileId into its parent context (e.g. attach the existing PDF to
+     * the conversation) so the user gets a confirmed-and-attached file
+     * with zero wasted bytes. Other callers can iterate `aliased` to
+     * surface "found N existing matches" UI.
+     *
+     * Empty for the normal "no duplicates" upload path.
+     */
+    aliased: Array<{
+        inputIndex: number;
+        existingFileId: string;
+    }>;
+}
+/** Called once by the host's `useEffect` mount. */
+export declare function registerUploadGuardHandler(handler: UploadGuardHandler): void;
+/** Called by the host's cleanup. */
+export declare function unregisterUploadGuardHandler(handler: UploadGuardHandler): void;
+/**
+ * Public entry point. Call from any UI surface that initiates an
+ * upload (drag-drop, paste, FAB, picker). Returns the same shape as
+ * `uploadFiles.unwrap()` plus a `cancelled` flag.
+ *
+ * Behaviour:
+ *   - If the host is mounted: pre-flight scan → optional dialog →
+ *     dispatch with the user's choices. Resolves when uploads finish
+ *     or when the user cancels (`cancelled: true`, no dispatch).
+ *   - If the host is NOT mounted: dispatches directly with no
+ *     duplicate check, so old call paths keep working. Logs a dev
+ *     warning so the missing host gets noticed.
+ */
+export declare function requestUpload(arg: UploadFilesArg): Promise<UploadGuardResult>;

package/dist/files/engine/upload/uploadGuardOpeners.js

@@ -0,0 +1,54 @@
+let registered = null;
+function registerUploadGuardHandler(handler) {
+  registered = handler;
+}
+function unregisterUploadGuardHandler(handler) {
+  if (registered === handler) registered = null;
+}
+async function requestUpload(arg) {
+  if (registered) {
+    return registered(arg);
+  }
+  if (true) {
+    console.warn(
+      "[upload-guard] requestUpload called before <UploadGuardHost/> mounted \u2014 falling back to direct dispatch with no duplicate check."
+    );
+  }
+  const [{ getStore }, { uploadFiles }] = await Promise.all([
+    import("../host/store.js"),
+    import("../redux/thunks.js")
+  ]);
+  const store = getStore();
+  if (!store) {
+    return {
+      uploaded: [],
+      failed: arg.files.map((f) => ({
+        name: f.name,
+        error: "Store not ready"
+      })),
+      cancelled: false,
+      aliased: []
+    };
+  }
+  try {
+    const dispatch = store.dispatch;
+    const result = await dispatch(uploadFiles(arg)).unwrap();
+    return { ...result, cancelled: false, aliased: [] };
+  } catch (err) {
+    return {
+      uploaded: [],
+      failed: arg.files.map((f) => ({
+        name: f.name,
+        error: err instanceof Error ? err.message : String(err)
+      })),
+      cancelled: false,
+      aliased: []
+    };
+  }
+}
+export {
+  registerUploadGuardHandler,
+  requestUpload,
+  unregisterUploadGuardHandler
+};
+//# sourceMappingURL=uploadGuardOpeners.js.map

package/dist/files/engine/upload/uploadGuardOpeners.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/files/engine/upload/uploadGuardOpeners.ts"],"sourcesContent":["/**\n * features/files/upload/uploadGuardOpeners.ts\n *\n * Module-level imperative API for the upload-guard system. Same shape\n * as `cloudFilesPickerOpeners` — a single host component registers a\n * handler at mount, and any code anywhere can call `requestUpload`\n * without threading state.\n *\n * The host pre-flights uploaded files for duplicates (identical\n * checksum or filename collisions in the target folder), shows a\n * resolution dialog if needed, and only then dispatches the upload.\n * If the host hasn't mounted yet, `requestUpload` warns in dev and\n * falls back to a direct thunk dispatch so we don't break the upload\n * for the (rare) caller that fires during boot.\n *\n * Pure TypeScript — no React, no dialog markup. Safe to import from\n * anywhere, including the static graph of route entries.\n */\n\nimport type { UploadFilesArg } from \"../types\";\nimport type { AppDispatch } from \"../host/store\";\n\n/**\n * The handler the host registers at mount. Returns a promise that\n * resolves with the same shape as the underlying `uploadFiles` thunk\n * payload — `{ uploaded: string[], failed: [...] }`.\n */\nexport type UploadGuardHandler = (\n  arg: UploadFilesArg,\n) => Promise<UploadGuardResult>;\n\nexport interface UploadGuardResult {\n  uploaded: string[];\n  failed: Array<{ name: string; error: string }>;\n  /** True when the user dismissed the duplicate dialog. */\n  cancelled: boolean;\n  /**\n   * Files the user chose to NOT re-upload because a duplicate already\n   * exists, and they explicitly picked \"use the existing one.\" Each\n   * entry maps the index of the original input file (in `arg.files`)\n   * to the existing `cld_files.id` the user picked.\n   *\n   * The chat-resource-attach flow uses this to wire the existing\n   * fileId into its parent context (e.g. attach the existing PDF to\n   * the conversation) so the user gets a confirmed-and-attached file\n   * with zero wasted bytes. Other callers can iterate `aliased` to\n   * surface \"found N existing matches\" UI.\n   *\n   * Empty for the normal \"no duplicates\" upload path.\n   */\n  aliased: Array<{ inputIndex: number; existingFileId: string }>;\n}\n\nlet registered: UploadGuardHandler | null = null;\n\n/** Called once by the host's `useEffect` mount. */\nexport function registerUploadGuardHandler(handler: UploadGuardHandler): void {\n  registered = handler;\n}\n\n/** Called by the host's cleanup. */\nexport function unregisterUploadGuardHandler(\n  handler: UploadGuardHandler,\n): void {\n  if (registered === handler) registered = null;\n}\n\n/**\n * Public entry point. Call from any UI surface that initiates an\n * upload (drag-drop, paste, FAB, picker). Returns the same shape as\n * `uploadFiles.unwrap()` plus a `cancelled` flag.\n *\n * Behaviour:\n *   - If the host is mounted: pre-flight scan → optional dialog →\n *     dispatch with the user's choices. Resolves when uploads finish\n *     or when the user cancels (`cancelled: true`, no dispatch).\n *   - If the host is NOT mounted: dispatches directly with no\n *     duplicate check, so old call paths keep working. Logs a dev\n *     warning so the missing host gets noticed.\n */\nexport async function requestUpload(\n  arg: UploadFilesArg,\n): Promise<UploadGuardResult> {\n  if (registered) {\n    return registered(arg);\n  }\n  // Fallback path — should rarely fire in practice. Imported lazily\n  // to keep this opener module dispatch-free at module load.\n  if (process.env.NODE_ENV !== \"production\") {\n    // eslint-disable-next-line no-console\n    console.warn(\n      \"[upload-guard] requestUpload called before <UploadGuardHost/> mounted — falling back to direct dispatch with no duplicate check.\",\n    );\n  }\n  const [{ getStore }, { uploadFiles }] = await Promise.all([\n    import(\"../host/store\"),\n    import(\"../redux/thunks\"),\n  ]);\n  const store = getStore();\n  if (!store) {\n    return {\n      uploaded: [],\n      failed: arg.files.map((f) => ({\n        name: f.name,\n        error: \"Store not ready\",\n      })),\n      cancelled: false,\n      aliased: [],\n    };\n  }\n  try {\n    const dispatch = store.dispatch as AppDispatch;\n    const result = await dispatch(uploadFiles(arg)).unwrap();\n    return { ...result, cancelled: false, aliased: [] };\n  } catch (err) {\n    return {\n      uploaded: [],\n      failed: arg.files.map((f) => ({\n        name: f.name,\n        error: err instanceof Error ? err.message : String(err),\n      })),\n      cancelled: false,\n      aliased: [],\n    };\n  }\n}\n"],"mappings":"AAqDA,IAAI,aAAwC;AAGrC,SAAS,2BAA2B,SAAmC;AAC5E,eAAa;AACf;AAGO,SAAS,6BACd,SACM;AACN,MAAI,eAAe,QAAS,cAAa;AAC3C;AAeA,eAAsB,cACpB,KAC4B;AAC5B,MAAI,YAAY;AACd,WAAO,WAAW,GAAG;AAAA,EACvB;AAGA,MAAI,MAAuC;AAEzC,YAAQ;AAAA,MACN;AAAA,IACF;AAAA,EACF;AACA,QAAM,CAAC,EAAE,SAAS,GAAG,EAAE,YAAY,CAAC,IAAI,MAAM,QAAQ,IAAI;AAAA,IACxD,OAAO,eAAe;AAAA,IACtB,OAAO,iBAAiB;AAAA,EAC1B,CAAC;AACD,QAAM,QAAQ,SAAS;AACvB,MAAI,CAAC,OAAO;AACV,WAAO;AAAA,MACL,UAAU,CAAC;AAAA,MACX,QAAQ,IAAI,MAAM,IAAI,CAAC,OAAO;AAAA,QAC5B,MAAM,EAAE;AAAA,QACR,OAAO;AAAA,MACT,EAAE;AAAA,MACF,WAAW;AAAA,MACX,SAAS,CAAC;AAAA,IACZ;AAAA,EACF;AACA,MAAI;AACF,UAAM,WAAW,MAAM;AACvB,UAAM,SAAS,MAAM,SAAS,YAAY,GAAG,CAAC,EAAE,OAAO;AACvD,WAAO,EAAE,GAAG,QAAQ,WAAW,OAAO,SAAS,CAAC,EAAE;AAAA,EACpD,SAAS,KAAK;AACZ,WAAO;AAAA,MACL,UAAU,CAAC;AAAA,MACX,QAAQ,IAAI,MAAM,IAAI,CAAC,OAAO;AAAA,QAC5B,MAAM,EAAE;AAAA,QACR,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,MACxD,EAAE;AAAA,MACF,WAAW;AAAA,MACX,SAAS,CAAC;AAAA,IACZ;AAAA,EACF;AACF;","names":[]}