@ai-matrx/media 0.11.0 → 0.13.0

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

@@ -23,7 +23,7 @@
  * - Final `X-Cld-File-Id` captured from response headers (final PATCH, or the
  *   completed-session HEAD/POST recovery paths) — a lost final response never
  *   forces a re-upload.
- * - Resume URLs live in a dedicated tiny IndexedDB (`mtx-tus-urls`) — NEVER
+ * - Resume URLs live in a dedicated tiny browser store (`mtx-tus-urls`, owned by @ai-matrx/data/files/tus) — NEVER
  *   the recorder chunk journal DB.
  *
  * NOT LIVE-TESTED against production: the server side (CORS, metadata parity,
@@ -31,70 +31,25 @@
  * see features/files/handler/FEATURE.md § Transport policy for the pending
  * E2E note. The client is unit-tested with an injected HttpStack.
  */
-import * as tus from "tus-js-client";
+import { type TusHttpStack, type TusFileReader, type TusUrlStorage } from "@ai-matrx/data/files/tus";
 import type { CloudUploadOptions, CloudUploadResult } from "./cloudUpload.js";
-/** Server-bounded chunk size (8–32 MiB allowed): 16 MiB. */
-export declare const TUS_CHUNK_SIZE_BYTES: number;
-export declare const TUS_UPLOAD_PATH = "/files/upload/tus";
-/**
- * The ONE builder for the upload metadata JSON object. The buffered path
- * serializes this into the `metadata_json` form field
- * (`features/files/api/files.ts`); the TUS path serializes the SAME object
- * into the `metadata_json` Upload-Metadata key. One builder ⇒ the two
- * transports can never drift (parity is unit-tested).
- *
- * 🚨 `scope.organization_id` is the OWNING WORKSPACE of the uploaded file, and
- * it is not decoration. The server reads it (`SyncEngine._metadata_organization_id`,
- * membership-checked against `iam.has_org_access_for`) and stamps
- * `files.files.organization_id` from it. Omit it and the server falls back to
- * the uploader's OWN organization — which is how, on 2026-08-30, a screenshot
- * attached from the composer landed in a own organization nobody had chosen
- * and then disagreed with the team organization the person actually picked.
- *
- * Callers never set it by hand: `bindUploadOrganization` in `cloudUpload.ts`
- * resolves it for every upload before a byte moves, so it is already present in
- * `metadata` by the time this builder runs. This function keeps the shape
- * canonical and is where the contract is written down.
- */
-export declare function buildUploadMetadataEnvelope(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
-/** tus-js-client UrlStorage backed by the dedicated `mtx-tus-urls` DB —
- *  deliberately SEPARATE from the recorder chunk journal. */
-export declare function createTusUrlStorage(): NonNullable<ConstructorParameters<typeof tus.Upload>[1]["urlStorage"]>;
-/** Read-only summary of a stored TUS resume session (diagnostics surfaces —
- *  /camera's resume-pending indicator, /camera/admin). */
-export interface StoredTusUploadSummary {
-    urlStorageKey: string;
-    fingerprint: string;
-    size: number | null;
-    metadata: Record<string, string>;
-    creationTime: string;
-    uploadUrl: string | null;
-}
-/**
- * List every stored TUS resume-URL entry (the `mtx-tus-urls` DB). Read-only —
- * resuming still happens inside `tusUploadRaw` via the UrlStorage; this only
- * lets management surfaces SHOW that a resumable session is pending. Returns
- * [] where IndexedDB is unavailable (never throws — diagnostics must not
- * break a page).
- */
-export declare function listStoredTusUploads(): Promise<StoredTusUploadSummary[]>;
+export { buildUploadMetadataEnvelope, createTusUrlStorage, listStoredTusUploads, TUS_CHUNK_SIZE_BYTES, TUS_UPLOAD_PATH, type StoredTusUploadSummary, } from "@ai-matrx/data/files/tus";
 export interface TusUploadDeps {
     /** Injected HttpStack for unit tests (mock wire, no XHR). */
-    httpStack?: tus.HttpStack;
+    httpStack?: TusHttpStack;
     /** Injected file reader for unit tests (Node builds of tus-js-client
      *  cannot slice browser Files). */
-    fileReader?: ConstructorParameters<typeof tus.Upload>[1]["fileReader"];
+    fileReader?: TusFileReader;
     /** Override the endpoint (tests). */
     endpointOverride?: string;
     /** Override URL storage (tests). */
-    urlStorage?: ReturnType<typeof createTusUrlStorage>;
+    urlStorage?: TusUrlStorage;
 }
 /**
  * Resumable upload of one file via TUS. Same result contract as
  * `cloudUploadRaw` — `{ ok: true, fileId, ... } | { ok: false, error }`,
- * never throws. Automatically resumes a previous session for the same file
- * (custom UrlStorage + server HEAD), including the completed-session
- * recovery: when the server reports the session already finished and hands
- * back `X-Cld-File-Id`, the upload is skipped and the file resolves directly.
+ * never throws. The transfer is data's `tusTransfer`; this binds fresh
+ * host headers (mandatory-org, fail-closed `buildHeaders`) to every request
+ * and hydrates the canonical row so the result matches the buffered contract.
  */
 export declare function tusUploadRaw(file: File, filePath: string, options: CloudUploadOptions, idempotencyKey: string, deps?: TusUploadDeps): Promise<CloudUploadResult>;

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

@@ -1,233 +1,41 @@
-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 (process.env.NODE_ENV !== "production" && !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 [];
-  }
-}
+import {
+  tusTransfer,
+  TUS_UPLOAD_PATH
+} from "@ai-matrx/data/files/tus";
+import {
+  buildUploadMetadataEnvelope,
+  createTusUrlStorage,
+  listStoredTusUploads,
+  TUS_CHUNK_SIZE_BYTES,
+  TUS_UPLOAD_PATH as TUS_UPLOAD_PATH2
+} from "@ai-matrx/data/files/tus";
 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) {
+  const transfer = await tusTransfer(file, {
+    endpoint,
+    filePath,
+    metadata: options.metadata,
+    visibility: options.visibility,
+    idempotencyKey,
+    headers: async () => (await buildHeaders({}, false)).headers,
+    onProgress: options.onProgress ? (loaded, total) => options.onProgress?.({ loaded, total }) : void 0,
+    signal: options.signal,
+    httpStack: deps.httpStack,
+    fileReader: deps.fileReader,
+    urlStorage: deps.urlStorage
+  });
+  if (!transfer.ok) {
     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",
+      error: transfer.error,
+      errorCode: transfer.errorCode,
       fileName: file.name
     };
   }
+  const cldFileId = transfer.fileId;
   try {
     const { data: record } = await Files.getFile(cldFileId);
     return {
@@ -249,7 +57,7 @@ async function tusUploadRaw(file, filePath, options, idempotencyKey, deps = {})
 }
 export {
   TUS_CHUNK_SIZE_BYTES,
-  TUS_UPLOAD_PATH,
+  TUS_UPLOAD_PATH2 as TUS_UPLOAD_PATH,
   buildUploadMetadataEnvelope,
   createTusUrlStorage,
   listStoredTusUploads,

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

@@ -1 +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":[]}
+{"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 browser store (`mtx-tus-urls`, owned by @ai-matrx/data/files/tus) — 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 { 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\";\nimport {\n  tusTransfer,\n  TUS_UPLOAD_PATH,\n  type TusHttpStack,\n  type TusFileReader,\n  type TusUrlStorage,\n} from \"@ai-matrx/data/files/tus\";\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// The wire (TUS client, resume store, metadata envelope) is @ai-matrx/data/files/tus\n// — architecture step 14 (D1). This module binds the host's headers and base URL and\n// hydrates the canonical row; the names below stay importable from here.\nexport {\n  buildUploadMetadataEnvelope,\n  createTusUrlStorage,\n  listStoredTusUploads,\n  TUS_CHUNK_SIZE_BYTES,\n  TUS_UPLOAD_PATH,\n  type StoredTusUploadSummary,\n} from \"@ai-matrx/data/files/tus\";\n\nexport interface TusUploadDeps {\n  /** Injected HttpStack for unit tests (mock wire, no XHR). */\n  httpStack?: TusHttpStack;\n  /** Injected file reader for unit tests (Node builds of tus-js-client\n   *  cannot slice browser Files). */\n  fileReader?: TusFileReader;\n  /** Override the endpoint (tests). */\n  endpointOverride?: string;\n  /** Override URL storage (tests). */\n  urlStorage?: TusUrlStorage;\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. The transfer is data's `tusTransfer`; this binds fresh\n * host headers (mandatory-org, fail-closed `buildHeaders`) to every request\n * and hydrates the canonical row so the result matches the buffered contract.\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 transfer = await tusTransfer(file, {\n    endpoint,\n    filePath,\n    metadata: options.metadata,\n    visibility: options.visibility,\n    idempotencyKey,\n    headers: async () => (await buildHeaders({}, false)).headers,\n    onProgress: options.onProgress\n      ? (loaded, total) => options.onProgress?.({ loaded, total })\n      : undefined,\n    signal: options.signal,\n    httpStack: deps.httpStack,\n    fileReader: deps.fileReader,\n    urlStorage: deps.urlStorage,\n  });\n  if (!transfer.ok) {\n    return {\n      ok: false,\n      error: transfer.error,\n      errorCode: transfer.errorCode,\n      fileName: file.name,\n    };\n  }\n  const cldFileId = transfer.fileId;\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":"AAkCA,SAAS,cAAc,6BAA6B;AAEpD,YAAY,WAAW;AACvB,SAAS,2BAA2B;AACpC;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AAUP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,mBAAAA;AAAA,OAEK;AAqBP,eAAsB,aACpB,MACA,UACA,SACA,gBACA,OAAsB,CAAC,GACK;AAC5B,QAAM,WACJ,KAAK,oBACL,GAAG,sBAAsB,iBAAiB,QAAW,MAAM,CAAC,GAAG,eAAe;AAEhF,QAAM,WAAW,MAAM,YAAY,MAAM;AAAA,IACvC;AAAA,IACA;AAAA,IACA,UAAU,QAAQ;AAAA,IAClB,YAAY,QAAQ;AAAA,IACpB;AAAA,IACA,SAAS,aAAa,MAAM,aAAa,CAAC,GAAG,KAAK,GAAG;AAAA,IACrD,YAAY,QAAQ,aAChB,CAAC,QAAQ,UAAU,QAAQ,aAAa,EAAE,QAAQ,MAAM,CAAC,IACzD;AAAA,IACJ,QAAQ,QAAQ;AAAA,IAChB,WAAW,KAAK;AAAA,IAChB,YAAY,KAAK;AAAA,IACjB,YAAY,KAAK;AAAA,EACnB,CAAC;AACD,MAAI,CAAC,SAAS,IAAI;AAChB,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO,SAAS;AAAA,MAChB,WAAW,SAAS;AAAA,MACpB,UAAU,KAAK;AAAA,IACjB;AAAA,EACF;AACA,QAAM,YAAY,SAAS;AAG3B,MAAI;AACF,UAAM,EAAE,MAAM,OAAO,IAAI,MAAM,MAAM,QAAQ,SAAS;AACtD,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,QAAQ,OAAO;AAAA,MACf,UAAU,OAAO;AAAA,MACjB,UAAU,OAAO,cAAc,KAAK;AAAA,MACpC,eAAe,OAAO,mBAAmB;AAAA,MACzC,KAAK;AAAA,IACP;AAAA,EACF,SAAS,KAAK;AACZ,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO,8BAA8B,SAAS,kCAAkC,oBAAoB,GAAG,CAAC;AAAA,MACxG,WAAW;AAAA,MACX,UAAU,KAAK;AAAA,IACjB;AAAA,EACF;AACF;","names":["TUS_UPLOAD_PATH"]}

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

@@ -1,58 +1 @@
-/**
- * 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;
+export { __resetUploadDedupGuardForTests, claimUpload, uploadDedupKey, type DedupedUploadOutcome, type UploadClaim, } from "@ai-matrx/data/files";

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

@@ -1,38 +1,8 @@
-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();
-}
+import {
+  __resetUploadDedupGuardForTests,
+  claimUpload,
+  uploadDedupKey
+} from "@ai-matrx/data/files";
 export {
   __resetUploadDedupGuardForTests,
   claimUpload,

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

@@ -1 +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":[]}
+{"version":3,"sources":["../../../../src/files/engine/upload/uploadDedupGuard.ts"],"sourcesContent":["// The upload dedup guard lives in @ai-matrx/data/files (architecture step 14, D1:\n// byte transport and its dedup are data's). Re-exported so engine importers keep working.\nexport {\n  __resetUploadDedupGuardForTests,\n  claimUpload,\n  uploadDedupKey,\n  type DedupedUploadOutcome,\n  type UploadClaim,\n} from \"@ai-matrx/data/files\";\n"],"mappings":"AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/media",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The AI Matrx media components kit: durable-ref-only renderers for images, video, audio and file thumbnails plus live TTS playback that just work with the Matrx file system — headless core hooks plus DOM bindings, wired to an injected MediaClient. A signed URL is a handoff, never an identity.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -757,13 +757,12 @@
     "lucide-react": "^1.48.0",
     "reselect": "^5.1.0",
     "tailwind-merge": "^3.7.0",
-    "tus-js-client": "^4.3.1",
-    "@ai-matrx/agents": "latest",
     "@ai-matrx/data": "latest",
-    "@ai-matrx/associations": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/kit": "latest",
-    "@ai-matrx/realtime": "latest"
+    "@ai-matrx/realtime": "latest",
+    "@ai-matrx/agents": "latest",
+    "@ai-matrx/associations": "latest"
   },
   "peerDependencies": {
     "@reduxjs/toolkit": ">=2.0.0",
@@ -833,6 +832,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "verify:tarball": "node ./scripts/verify-tarball.mjs",
-    "db-types": "node ./scripts/generate-db-types.mjs"
+    "db-types": "node ../data/scripts/generate-db-types.mjs"
   }
 }