@ai-matrx/data 0.19.2 → 0.21.0

package/dist/files.d.cts

@@ -381,7 +381,14 @@ interface FileUrls {
  * `?inline=1` matches the exact spelling the backend emits on
  * `FileRecord.url`, keeping cache keys identical either way.
  */
-declare function fileUrls(filesBaseUrl: string, fileId: string): FileUrls;
+declare function buildFileUrls(filesBaseUrl: string, fileId: string): FileUrls;
+/**
+ * @deprecated Renamed {@link buildFileUrls} (architecture step 14): `fileUrls(fileId)`
+ * is the ONE caller-facing signature — the host-bound builder in
+ * `@ai-matrx/media/files/engine/handler/utils/python-base`. This alias keeps a
+ * `latest` media build working for one release and is then removed.
+ */
+declare const fileUrls: typeof buildFileUrls;
 /**
  * The clean public byte-streaming share endpoint (`GET /share/{token}`,
  * inline disposition) — the canonical embeddable URL for a minted link.
@@ -563,7 +570,7 @@ declare function createMatrxFilesClient<TSrc extends string = DurableSrc>(config
  * panels — this module never logs.
  */
 
-type FileErrorCode = "access_denied" | "not_found" | "deleted" | "share_link_invalid" | "external_fetch_failed" | "upload_failed" | "internal";
+type FileErrorCode = "access_denied" | "not_found" | "deleted" | "share_link_invalid" | "external_fetch_failed" | "cors_blocked" | "mime_unknown" | "upload_failed" | "upload_cancelled" | "quota_exceeded" | "in_flight" | "internal";
 declare class FileError extends Error {
     readonly code: FileErrorCode;
     readonly fileId?: string | undefined;
@@ -615,6 +622,66 @@ declare function fileErrorFromStatus(status: number, fileId?: string): FileError
  */
 declare function classifyUnavailable(err: unknown): MediaUnavailableReason;
 
+/**
+ * Upload dedup guard — one in-flight/just-landed claim per (folder, name, size).
+ * Origin: @ai-matrx/media files/engine/upload/uploadDedupGuard.ts (architecture step 14).
+ *
+ * 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.
+ */
+interface DedupedUploadOutcome {
+    fileId: string;
+    filePath: string;
+}
+/** The dedup key: same folder, same original name, same byte count. */
+declare function uploadDedupKey(folderPath: string, fileName: string, fileSize: number): string;
+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.
+ */
+declare function claimUpload(key: string): UploadClaim;
+/** Test-only: clears every claim so suites don't leak state between tests. */
+declare function __resetUploadDedupGuardForTests(): void;
+
 /**
  * @ai-matrx/data/files — the `mx_files_session` cookie bootstrap.
  *
@@ -683,4 +750,4 @@ interface FilesSession {
 }
 declare function createFilesSession(options: FilesSessionOptions): FilesSession;
 
-export { type BlobCacheEntry, type BlobCachePort, type DurableSrc, ExternalFetchError, FileAccessDeniedError, FileDeletedError, FileError, type FileErrorCode, type FileMetadata, type FileMetadataPort, FileNotFoundError, type FileOrigins, type FileRecordWire, type FileSessionResponseWire, type FileShownTo, FileUploadError, type FileUploadResponseWire, type FileUrlRecognizer, type FileUrls, type FilesBlobHandle, type FilesDiagnosticsEvent, type FilesDiagnosticsSink, type FilesRecoveryReport, type FilesRecoveryVerdict, type FilesResolution, type FilesSession, type FilesSessionOptions, type FilesSessionSnapshot, type MatrxFilesClient, type MatrxFilesClientConfig, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type MediaUrlKind, SIGNED_URL_RE, ShareLinkInvalidError, type ShareLinkRecordWire, TUS_TRANSPORT_THRESHOLD_BYTES, type UploadTransport, classifyMediaUrl, classifyUnavailable, createFileUrlRecognizer, createFilesSession, createMatrxFilesClient, createMemoryBlobCache, fileErrorFromStatus, fileNameFromUrl, fileUrls, isDurableMediaUrl, isSignedUrl, mimeFromUrl, resolveUploadTransport, shareUrl, shareableMediaUrl, uploadAccessFields };
+export { type BlobCacheEntry, type BlobCachePort, type DedupedUploadOutcome, type DurableSrc, ExternalFetchError, FileAccessDeniedError, FileDeletedError, FileError, type FileErrorCode, type FileMetadata, type FileMetadataPort, FileNotFoundError, type FileOrigins, type FileRecordWire, type FileSessionResponseWire, type FileShownTo, FileUploadError, type FileUploadResponseWire, type FileUrlRecognizer, type FileUrls, type FilesBlobHandle, type FilesDiagnosticsEvent, type FilesDiagnosticsSink, type FilesRecoveryReport, type FilesRecoveryVerdict, type FilesResolution, type FilesSession, type FilesSessionOptions, type FilesSessionSnapshot, type MatrxFilesClient, type MatrxFilesClientConfig, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type MediaUrlKind, SIGNED_URL_RE, ShareLinkInvalidError, type ShareLinkRecordWire, TUS_TRANSPORT_THRESHOLD_BYTES, type UploadClaim, type UploadTransport, __resetUploadDedupGuardForTests, buildFileUrls, claimUpload, classifyMediaUrl, classifyUnavailable, createFileUrlRecognizer, createFilesSession, createMatrxFilesClient, createMemoryBlobCache, fileErrorFromStatus, fileNameFromUrl, fileUrls, isDurableMediaUrl, isSignedUrl, mimeFromUrl, resolveUploadTransport, shareUrl, shareableMediaUrl, uploadAccessFields, uploadDedupKey };

package/dist/files.d.ts

@@ -381,7 +381,14 @@ interface FileUrls {
  * `?inline=1` matches the exact spelling the backend emits on
  * `FileRecord.url`, keeping cache keys identical either way.
  */
-declare function fileUrls(filesBaseUrl: string, fileId: string): FileUrls;
+declare function buildFileUrls(filesBaseUrl: string, fileId: string): FileUrls;
+/**
+ * @deprecated Renamed {@link buildFileUrls} (architecture step 14): `fileUrls(fileId)`
+ * is the ONE caller-facing signature — the host-bound builder in
+ * `@ai-matrx/media/files/engine/handler/utils/python-base`. This alias keeps a
+ * `latest` media build working for one release and is then removed.
+ */
+declare const fileUrls: typeof buildFileUrls;
 /**
  * The clean public byte-streaming share endpoint (`GET /share/{token}`,
  * inline disposition) — the canonical embeddable URL for a minted link.
@@ -563,7 +570,7 @@ declare function createMatrxFilesClient<TSrc extends string = DurableSrc>(config
  * panels — this module never logs.
  */
 
-type FileErrorCode = "access_denied" | "not_found" | "deleted" | "share_link_invalid" | "external_fetch_failed" | "upload_failed" | "internal";
+type FileErrorCode = "access_denied" | "not_found" | "deleted" | "share_link_invalid" | "external_fetch_failed" | "cors_blocked" | "mime_unknown" | "upload_failed" | "upload_cancelled" | "quota_exceeded" | "in_flight" | "internal";
 declare class FileError extends Error {
     readonly code: FileErrorCode;
     readonly fileId?: string | undefined;
@@ -615,6 +622,66 @@ declare function fileErrorFromStatus(status: number, fileId?: string): FileError
  */
 declare function classifyUnavailable(err: unknown): MediaUnavailableReason;
 
+/**
+ * Upload dedup guard — one in-flight/just-landed claim per (folder, name, size).
+ * Origin: @ai-matrx/media files/engine/upload/uploadDedupGuard.ts (architecture step 14).
+ *
+ * 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.
+ */
+interface DedupedUploadOutcome {
+    fileId: string;
+    filePath: string;
+}
+/** The dedup key: same folder, same original name, same byte count. */
+declare function uploadDedupKey(folderPath: string, fileName: string, fileSize: number): string;
+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.
+ */
+declare function claimUpload(key: string): UploadClaim;
+/** Test-only: clears every claim so suites don't leak state between tests. */
+declare function __resetUploadDedupGuardForTests(): void;
+
 /**
  * @ai-matrx/data/files — the `mx_files_session` cookie bootstrap.
  *
@@ -683,4 +750,4 @@ interface FilesSession {
 }
 declare function createFilesSession(options: FilesSessionOptions): FilesSession;
 
-export { type BlobCacheEntry, type BlobCachePort, type DurableSrc, ExternalFetchError, FileAccessDeniedError, FileDeletedError, FileError, type FileErrorCode, type FileMetadata, type FileMetadataPort, FileNotFoundError, type FileOrigins, type FileRecordWire, type FileSessionResponseWire, type FileShownTo, FileUploadError, type FileUploadResponseWire, type FileUrlRecognizer, type FileUrls, type FilesBlobHandle, type FilesDiagnosticsEvent, type FilesDiagnosticsSink, type FilesRecoveryReport, type FilesRecoveryVerdict, type FilesResolution, type FilesSession, type FilesSessionOptions, type FilesSessionSnapshot, type MatrxFilesClient, type MatrxFilesClientConfig, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type MediaUrlKind, SIGNED_URL_RE, ShareLinkInvalidError, type ShareLinkRecordWire, TUS_TRANSPORT_THRESHOLD_BYTES, type UploadTransport, classifyMediaUrl, classifyUnavailable, createFileUrlRecognizer, createFilesSession, createMatrxFilesClient, createMemoryBlobCache, fileErrorFromStatus, fileNameFromUrl, fileUrls, isDurableMediaUrl, isSignedUrl, mimeFromUrl, resolveUploadTransport, shareUrl, shareableMediaUrl, uploadAccessFields };
+export { type BlobCacheEntry, type BlobCachePort, type DedupedUploadOutcome, type DurableSrc, ExternalFetchError, FileAccessDeniedError, FileDeletedError, FileError, type FileErrorCode, type FileMetadata, type FileMetadataPort, FileNotFoundError, type FileOrigins, type FileRecordWire, type FileSessionResponseWire, type FileShownTo, FileUploadError, type FileUploadResponseWire, type FileUrlRecognizer, type FileUrls, type FilesBlobHandle, type FilesDiagnosticsEvent, type FilesDiagnosticsSink, type FilesRecoveryReport, type FilesRecoveryVerdict, type FilesResolution, type FilesSession, type FilesSessionOptions, type FilesSessionSnapshot, type MatrxFilesClient, type MatrxFilesClientConfig, type MediaKind, type MediaMultiUploadResult, type MediaRef, type MediaRefLike, type MediaUnavailableReason, type MediaUploadOptions, type MediaUploadResult, type MediaUrlKind, SIGNED_URL_RE, ShareLinkInvalidError, type ShareLinkRecordWire, TUS_TRANSPORT_THRESHOLD_BYTES, type UploadClaim, type UploadTransport, __resetUploadDedupGuardForTests, buildFileUrls, claimUpload, classifyMediaUrl, classifyUnavailable, createFileUrlRecognizer, createFilesSession, createMatrxFilesClient, createMemoryBlobCache, fileErrorFromStatus, fileNameFromUrl, fileUrls, isDurableMediaUrl, isSignedUrl, mimeFromUrl, resolveUploadTransport, shareUrl, shareableMediaUrl, uploadAccessFields, uploadDedupKey };

package/dist/files.js

@@ -197,11 +197,12 @@ function fileNameFromUrl(url) {
   if (!last || !/\.[a-z0-9]{1,5}$/i.test(last)) return null;
   return decodeURIComponent(last);
 }
-function fileUrls(filesBaseUrl, fileId) {
+function buildFileUrls(filesBaseUrl, fileId) {
   const id = encodeURIComponent(fileId);
   const base = `${filesBaseUrl.replace(/\/$/, "")}/files/${id}/download`;
   return { download: base, inline: `${base}?inline=1` };
 }
+var fileUrls = buildFileUrls;
 function shareUrl(filesBaseUrl, token) {
   return `${filesBaseUrl.replace(/\/$/, "")}/share/${encodeURIComponent(token)}`;
 }
@@ -699,7 +700,7 @@ function createMatrxFilesClient(config) {
   const inflightDownloads = /* @__PURE__ */ new Map();
   async function fetchFileBytes(fileId) {
     const headers = await authHeaders();
-    const response = await fetchImpl(fileUrls(filesBase(), fileId).download, {
+    const response = await fetchImpl(buildFileUrls(filesBase(), fileId).download, {
       headers
     });
     if (!response.ok) {
@@ -961,7 +962,7 @@ function createMatrxFilesClient(config) {
       }
       const transport = kind === "video" || kind === "audio" ? "element" : "blob";
       const resolution = {
-        src: mint(fileUrls(filesBase(), fileId).inline),
+        src: mint(buildFileUrls(filesBase(), fileId).inline),
         kind,
         transport,
         recoverable: true
@@ -1027,7 +1028,7 @@ function createMatrxFilesClient(config) {
         mintStatus: session.snapshot().status,
         fetchBytes: async (base, id) => {
           const headers = await authHeaders();
-          return fetchImpl(fileUrls(base, id).download, { headers });
+          return fetchImpl(buildFileUrls(base, id).download, { headers });
         },
         cacheBlob: (id, blob) => {
           const already = blobCache.get(id);
@@ -1079,6 +1080,43 @@ function createMatrxFilesClient(config) {
   };
   return client;
 }
+
+// src/files/dedup.ts
+var CLAIM_WINDOW_MS = 3 * 60 * 1e3;
+var 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 {
   ExternalFetchError,
   FileAccessDeniedError,
@@ -1089,6 +1127,9 @@ export {
   SIGNED_URL_RE,
   ShareLinkInvalidError,
   TUS_TRANSPORT_THRESHOLD_BYTES,
+  __resetUploadDedupGuardForTests,
+  buildFileUrls,
+  claimUpload,
   classifyMediaUrl,
   classifyUnavailable,
   createFileUrlRecognizer,
@@ -1104,6 +1145,7 @@ export {
   resolveUploadTransport,
   shareUrl,
   shareableMediaUrl,
-  uploadAccessFields
+  uploadAccessFields,
+  uploadDedupKey
 };
 //# sourceMappingURL=files.js.map