@aotter/mantle-runtime 0.0.11-alpha.13 → 0.0.11-alpha.14

package/dist/usecase/dto/media/index.js

@@ -1,8 +1,15 @@
 /**
  * Media use-case DTOs. Distinct from `MediaStorage` port request types:
- * the use case receives caller-supplied fields, derives the rest
- * (storageKey via the adapter, expiresAt via the clock, maxBytes via
- * adapter config), and forwards a port-shaped request internally.
+ * the use case receives caller-supplied variant declarations, derives
+ * the rest (uploadGroupId via IdGenerator, storage keys via the
+ * adapter, expiresAt via the clock, per-mime maxBytes via site
+ * config), and forwards port-shaped requests internally.
+ *
+ * The shape is multi-variant from the start (#272): one
+ * `create_media_upload` call yields N presigned URLs (one per
+ * format), and one `commit_media_upload` finalises the whole
+ * bundle. Optimization runs agent-side via
+ * `@aotter/mantle-media-tools` — the runtime never transforms bytes.
  */
 export {};
 //# sourceMappingURL=index.js.map

package/dist/usecase/dto/media/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/usecase/dto/media/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/usecase/dto/media/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/usecase/media/CommitMediaUploadUseCase.d.ts

@@ -1,15 +1,25 @@
 import type { Clock } from "../../domain/port/Clock.js";
 import type { KvCache } from "../../domain/port/KvCache.js";
+import type { MediaAssetRepository } from "../../domain/port/MediaAssetRepository.js";
 import type { MediaAsset, MediaStorage } from "../../domain/port/MediaStorage.js";
 import type { CommitMediaUploadRequest } from "../dto/media/index.js";
+/**
+ * Finalise the variant bundle issued by `create_media_upload`. Reads
+ * the `PendingUploadRecord` from KV (each variant's expected
+ * mime + size + storageKey), asks the adapter to verify every
+ * uploaded object (HEAD + bytes), and on success persists the
+ * resulting `MediaAsset` to the `media_assets` table.
+ *
+ * All-or-nothing: any variant failing HEAD-verify rejects the whole
+ * commit. The orphan sweeper (#254) cleans up partially-uploaded
+ * bundles whose pending record expired.
+ */
 export declare class CommitMediaUploadUseCase {
     private readonly storage;
     private readonly kv;
     private readonly clock;
-    private readonly opts;
-    constructor(storage: MediaStorage, kv: KvCache, clock: Clock, opts?: {
-        readonly maxBytes?: number;
-    });
+    private readonly assets;
+    constructor(storage: MediaStorage, kv: KvCache, clock: Clock, assets: MediaAssetRepository);
     execute(request: CommitMediaUploadRequest): Promise<MediaAsset>;
 }
 //# sourceMappingURL=CommitMediaUploadUseCase.d.ts.map

package/dist/usecase/media/CommitMediaUploadUseCase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommitMediaUploadUseCase.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/CommitMediaUploadUseCase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAClF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAUtE,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAHJ,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,KAAK,EACZ,IAAI,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO;IAGtD,OAAO,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,UAAU,CAAC;CA8BtE"}
+{"version":3,"file":"CommitMediaUploadUseCase.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/CommitMediaUploadUseCase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,KAAK,EAEV,UAAU,EACV,YAAY,EACb,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAKtE;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAHN,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,oBAAoB;IAGzC,OAAO,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,UAAU,CAAC;CAkCtE"}

package/dist/usecase/media/CommitMediaUploadUseCase.js

@@ -1,40 +1,51 @@
 import { DiagnosticError } from "@aotter/mantle-spec";
-import { mediaUploadExpiredDiagnostic, } from "./diagnostics.js";
-import { DEFAULT_MAX_BYTES, PENDING_UPLOAD_KV_PREFIX, } from "./mediaAllowlist.js";
+import { mediaUploadExpiredDiagnostic } from "./diagnostics.js";
+import { PENDING_UPLOAD_KV_PREFIX } from "./mediaAllowlist.js";
+/**
+ * Finalise the variant bundle issued by `create_media_upload`. Reads
+ * the `PendingUploadRecord` from KV (each variant's expected
+ * mime + size + storageKey), asks the adapter to verify every
+ * uploaded object (HEAD + bytes), and on success persists the
+ * resulting `MediaAsset` to the `media_assets` table.
+ *
+ * All-or-nothing: any variant failing HEAD-verify rejects the whole
+ * commit. The orphan sweeper (#254) cleans up partially-uploaded
+ * bundles whose pending record expired.
+ */
 export class CommitMediaUploadUseCase {
     storage;
     kv;
     clock;
-    opts;
-    constructor(storage, kv, clock, opts = {}) {
+    assets;
+    constructor(storage, kv, clock, assets) {
         this.storage = storage;
         this.kv = kv;
         this.clock = clock;
-        this.opts = opts;
+        this.assets = assets;
     }
     async execute(request) {
         const opPath = "usecase/CommitMediaUpload";
-        const kvKey = `${PENDING_UPLOAD_KV_PREFIX}${request.uploadId}`;
+        const kvKey = `${PENDING_UPLOAD_KV_PREFIX}${request.uploadGroupId}`;
         const raw = await this.kv.get(kvKey);
         if (!raw) {
-            throw new DiagnosticError(mediaUploadExpiredDiagnostic(opPath, request.uploadId));
+            throw new DiagnosticError(mediaUploadExpiredDiagnostic(opPath, request.uploadGroupId));
         }
         const record = JSON.parse(raw);
-        const adapterCap = this.opts.maxBytes ?? DEFAULT_MAX_BYTES;
-        // Per-upload ceiling: tighter of (caller-declared at create) vs
-        // (adapter-wide cap). Defends against an adapter that accepted a
-        // larger PUT than the use case minted the URL for.
-        const maxBytes = Math.min(adapterCap, record.expectedSize);
+        const variantSpecs = record.variants.map((v) => ({
+            mimeType: v.mimeType,
+            role: v.role,
+            storageKey: v.storageKey,
+            maxBytes: Math.min(v.maxBytes, v.expectedSize),
+        }));
         const asset = await this.storage.commitUpload({
-            uploadId: request.uploadId,
-            storageKey: record.storageKey,
-            expectedMimeType: record.expectedMimeType,
-            maxBytes,
-            alt: request.alt,
-            caption: request.caption,
-            checksum: request.checksum,
+            uploadGroupId: request.uploadGroupId,
+            filename: record.filename,
+            variants: variantSpecs,
+            alt: request.alt ?? record.alt,
+            caption: request.caption ?? record.caption,
             now: this.clock.now(),
         });
+        await this.assets.save(asset);
         // Best-effort cleanup. KV TTL covers us if delete fails.
         await this.kv.delete(kvKey).catch(() => undefined);
         return asset;

package/dist/usecase/media/CommitMediaUploadUseCase.js.map

@@ -1 +1 @@
-{"version":3,"file":"CommitMediaUploadUseCase.js","sourceRoot":"","sources":["../../../src/usecase/media/CommitMediaUploadUseCase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAKtD,OAAO,EACL,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,OAAO,wBAAwB;IAEhB;IACA;IACA;IACA;IAJnB,YACmB,OAAqB,EACrB,EAAW,EACX,KAAY,EACZ,OAAuC,EAAE;QAHzC,YAAO,GAAP,OAAO,CAAc;QACrB,OAAE,GAAF,EAAE,CAAS;QACX,UAAK,GAAL,KAAK,CAAO;QACZ,SAAI,GAAJ,IAAI,CAAqC;IACzD,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,OAAiC;QAC7C,MAAM,MAAM,GAAG,2BAA2B,CAAC;QAC3C,MAAM,KAAK,GAAG,GAAG,wBAAwB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC/D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,eAAe,CAAC,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACpF,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;QACtD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC;QAC3D,gEAAgE;QAChE,iEAAiE;QACjE,mDAAmD;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;QAE3D,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;YAC5C,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,QAAQ;YACR,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;QAEH,yDAAyD;QACzD,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAEnD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}
+{"version":3,"file":"CommitMediaUploadUseCase.js","sourceRoot":"","sources":["../../../src/usecase/media/CommitMediaUploadUseCase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAUtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;;;;;;;GAUG;AACH,MAAM,OAAO,wBAAwB;IAEhB;IACA;IACA;IACA;IAJnB,YACmB,OAAqB,EACrB,EAAW,EACX,KAAY,EACZ,MAA4B;QAH5B,YAAO,GAAP,OAAO,CAAc;QACrB,OAAE,GAAF,EAAE,CAAS;QACX,UAAK,GAAL,KAAK,CAAO;QACZ,WAAM,GAAN,MAAM,CAAsB;IAC5C,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,OAAiC;QAC7C,MAAM,MAAM,GAAG,2BAA2B,CAAC;QAC3C,MAAM,KAAK,GAAG,GAAG,wBAAwB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;QACpE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,eAAe,CACvB,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAC5D,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;QAEtD,MAAM,YAAY,GAA2C,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACvF,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,YAAY,CAAC;SAC/C,CAAC,CAAC,CAAC;QAEJ,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;YAC5C,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,YAAY;YACtB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG;YAC9B,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;YAC1C,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE9B,yDAAyD;QACzD,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAEnD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/usecase/media/CreateMediaUploadUseCase.d.ts

@@ -1,18 +1,50 @@
 import type { Clock } from "../../domain/port/Clock.js";
+import type { IdGenerator } from "../../domain/port/IdGenerator.js";
 import type { KvCache } from "../../domain/port/KvCache.js";
 import type { MediaStorage } from "../../domain/port/MediaStorage.js";
 import type { SiteConfigRepository } from "../../domain/port/SiteConfigRepository.js";
 import type { CreateMediaUploadRequest, CreateMediaUploadResponse } from "../dto/media/index.js";
+/**
+ * Issue presigned upload capabilities for every variant the agent
+ * declares for one logical media asset (#272). The asset's `id` is
+ * minted here and surfaces as `uploadGroupId` in the response — the
+ * caller passes it back to `commit_media_upload`.
+ *
+ * Optimization runs agent-side via `@aotter/mantle-media-tools`. This
+ * use case enforces policy only — never transforms bytes:
+ *  - purpose must be declared in `siteDefaults.media.purposes`
+ *  - variants must cover every required mime for that purpose
+ *  - each variant's byteSize ≤ `policy.maxBytes[mime]`
+ *  - mime allowlist (still gates per variant; SVG opt-in via ctor)
+ *  - "suspicious shape" heuristic: modern formats (avif / webp) MUST
+ *    NOT be larger than the fallback (jpeg) — uploader skipped
+ *    optimization → hard fail rather than emit a `<picture>` slower
+ *    than the bare `<img>`.
+ */
 export declare class CreateMediaUploadUseCase {
     private readonly storage;
     private readonly kv;
     private readonly clock;
+    private readonly idgen;
     private readonly siteConfig;
     private readonly opts;
-    constructor(storage: MediaStorage, kv: KvCache, clock: Clock, siteConfig: SiteConfigRepository, opts?: {
+    constructor(storage: MediaStorage, kv: KvCache, clock: Clock, idgen: IdGenerator, siteConfig: SiteConfigRepository, opts?: {
         readonly allowSvg: boolean;
-        readonly maxBytes?: number;
     });
     execute(request: CreateMediaUploadRequest): Promise<CreateMediaUploadResponse>;
+    private assertVariantsCoverPolicy;
+    /** Enforce per-mime byte caps from the purpose policy BEFORE the
+     *  adapter signs presigned PUT URLs. Mantle docs / ADR-0017
+     *  promise this gate at create time — without it, oversized
+     *  variants only fail after R2 has accepted the bytes (wasted
+     *  upload + potential bill).
+     *
+     *  Also gates on positive-integer byteSize. JSON-RPC and HTTP
+     *  validation only narrow to `typeof === "number"`, so 0, -1, or
+     *  0.5 can reach here and produce signed URLs against a maxBytes
+     *  comparison that accepts them. */
+    private assertVariantSizesUnderCap;
+    private assertEachVariantAccepted;
+    private assertNoSuspiciousSizing;
 }
 //# sourceMappingURL=CreateMediaUploadUseCase.d.ts.map

package/dist/usecase/media/CreateMediaUploadUseCase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CreateMediaUploadUseCase.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/CreateMediaUploadUseCase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,uBAAuB,CAAC;AAiB/B,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAJJ,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,oBAAoB,EAChC,IAAI,GAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAE9E;IAGG,OAAO,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;CAkErF"}
+{"version":3,"file":"CreateMediaUploadUseCase.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/CreateMediaUploadUseCase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EAEV,YAAY,EACb,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAE1B,MAAM,uBAAuB,CAAC;AAqB/B;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBALJ,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,oBAAoB,EAChC,IAAI,GAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;KAAwB;IAGvE,OAAO,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IA0EpF,OAAO,CAAC,yBAAyB;IA8CjC;;;;;;;;;wCASoC;IACpC,OAAO,CAAC,0BAA0B;IA4BlC,OAAO,CAAC,yBAAyB;IAcjC,OAAO,CAAC,wBAAwB;CAmBjC"}

package/dist/usecase/media/CreateMediaUploadUseCase.js

@@ -1,71 +1,196 @@
 import { DiagnosticError } from "@aotter/mantle-spec";
-import { mediaMimeRejectedDiagnostic, mediaPurposeRejectedDiagnostic, mediaSizeExceededDiagnostic, mediaSvgRejectedDiagnostic, } from "./diagnostics.js";
-import { DEFAULT_MAX_BYTES, MEDIA_SVG_MIME, PENDING_UPLOAD_KV_PREFIX, PENDING_UPLOAD_KV_TTL_SECONDS, UPLOAD_URL_TTL_SECONDS, isAllowedMime, } from "./mediaAllowlist.js";
+import { mediaMimeRejectedDiagnostic, mediaPurposeRejectedDiagnostic, mediaSvgRejectedDiagnostic, mediaVariantSizeExceededDiagnostic, mediaVariantsIncompleteDiagnostic, mediaVariantsSuspiciousSizeDiagnostic, } from "./diagnostics.js";
+import { MEDIA_SVG_MIME, PENDING_UPLOAD_KV_PREFIX, PENDING_UPLOAD_KV_TTL_SECONDS, UPLOAD_URL_TTL_SECONDS, isAllowedMime, } from "./mediaAllowlist.js";
+/**
+ * Issue presigned upload capabilities for every variant the agent
+ * declares for one logical media asset (#272). The asset's `id` is
+ * minted here and surfaces as `uploadGroupId` in the response — the
+ * caller passes it back to `commit_media_upload`.
+ *
+ * Optimization runs agent-side via `@aotter/mantle-media-tools`. This
+ * use case enforces policy only — never transforms bytes:
+ *  - purpose must be declared in `siteDefaults.media.purposes`
+ *  - variants must cover every required mime for that purpose
+ *  - each variant's byteSize ≤ `policy.maxBytes[mime]`
+ *  - mime allowlist (still gates per variant; SVG opt-in via ctor)
+ *  - "suspicious shape" heuristic: modern formats (avif / webp) MUST
+ *    NOT be larger than the fallback (jpeg) — uploader skipped
+ *    optimization → hard fail rather than emit a `<picture>` slower
+ *    than the bare `<img>`.
+ */
 export class CreateMediaUploadUseCase {
     storage;
     kv;
     clock;
+    idgen;
     siteConfig;
     opts;
-    constructor(storage, kv, clock, siteConfig, opts = {
-        allowSvg: false,
-    }) {
+    constructor(storage, kv, clock, idgen, siteConfig, opts = { allowSvg: false }) {
         this.storage = storage;
         this.kv = kv;
         this.clock = clock;
+        this.idgen = idgen;
         this.siteConfig = siteConfig;
         this.opts = opts;
     }
     async execute(request) {
         const opPath = "usecase/CreateMediaUpload";
-        const maxBytes = this.opts.maxBytes ?? DEFAULT_MAX_BYTES;
-        // Fail-closed purpose enforcement (#262). Empty `media.purposes` —
-        // either undeclared or operator-cleared — disables uploads entirely
-        // at this layer; the MCP tool catalog + admin endpoint also gate on
-        // the same condition for cleaner UX. Reading per request rather
-        // than snapshotting at boot lets operator edits via the admin
-        // Settings page take effect without a redeploy.
         const declared = await this.siteConfig.readMediaPurposes();
-        if (declared.length === 0 || !request.purpose || !declared.includes(request.purpose)) {
-            throw new DiagnosticError(mediaPurposeRejectedDiagnostic(opPath, request.purpose, declared));
-        }
-        if (request.mimeType === MEDIA_SVG_MIME && !this.opts.allowSvg) {
-            throw new DiagnosticError(mediaSvgRejectedDiagnostic(opPath));
-        }
-        if (!isAllowedMime(request.mimeType, this.opts.allowSvg)) {
-            throw new DiagnosticError(mediaMimeRejectedDiagnostic(opPath, request.mimeType));
-        }
-        // Enforce the ceiling before minting a presigned URL — see
-        // CreateMediaUploadRequest.byteSize for the WHY.
-        if (request.byteSize > maxBytes) {
-            throw new DiagnosticError(mediaSizeExceededDiagnostic(opPath, request.byteSize, maxBytes));
+        const declaredNames = declared.map((p) => p.name);
+        const policy = declared.find((p) => p.name === request.purpose);
+        if (!policy) {
+            throw new DiagnosticError(mediaPurposeRejectedDiagnostic(opPath, request.purpose, declaredNames));
         }
+        this.assertVariantsCoverPolicy(opPath, request, policy);
+        this.assertEachVariantAccepted(opPath, request);
+        this.assertVariantSizesUnderCap(opPath, request, policy);
+        this.assertNoSuspiciousSizing(opPath, request);
         const now = this.clock.now();
         const expiresAt = now + UPLOAD_URL_TTL_SECONDS * 1000;
-        const capability = await this.storage.createUpload({
-            filename: request.filename,
-            mimeType: request.mimeType,
-            byteSize: request.byteSize,
-            maxBytes,
+        const uploadGroupId = this.idgen.next();
+        const variantSpecs = request.variants.map((v) => ({
+            mimeType: v.mimeType,
+            byteSize: v.byteSize,
+            maxBytes: policy.maxBytes[v.mimeType] ?? Number.MAX_SAFE_INTEGER,
+            role: v.role,
+        }));
+        const result = await this.storage.createUpload({
+            uploadGroupId,
             purpose: request.purpose,
+            filename: request.filename,
+            variants: variantSpecs,
             now,
             expiresAt,
         });
+        const pendingVariants = result.capabilities.map((cap, i) => ({
+            mimeType: cap.mimeType,
+            role: cap.role,
+            storageKey: cap.storageKey,
+            expectedSize: variantSpecs[i].byteSize,
+            maxBytes: variantSpecs[i].maxBytes,
+        }));
         const record = {
-            storageKey: capability.storageKey,
-            expectedMimeType: request.mimeType,
-            expectedSize: request.byteSize,
-            expiresAt: capability.expiresAt,
+            purpose: request.purpose,
+            filename: request.filename,
+            variants: pendingVariants,
+            alt: request.alt,
+            caption: request.caption,
+            expiresAt: result.expiresAt,
             createdAt: now,
         };
-        await this.kv.put(`${PENDING_UPLOAD_KV_PREFIX}${capability.uploadId}`, JSON.stringify(record), { expirationTtl: PENDING_UPLOAD_KV_TTL_SECONDS });
+        await this.kv.put(`${PENDING_UPLOAD_KV_PREFIX}${result.uploadGroupId}`, JSON.stringify(record), { expirationTtl: PENDING_UPLOAD_KV_TTL_SECONDS });
         return {
-            uploadId: capability.uploadId,
-            uploadUrl: capability.uploadUrl,
-            method: capability.method,
-            requiredHeaders: capability.requiredHeaders,
-            expiresAt: capability.expiresAt,
+            uploadGroupId: result.uploadGroupId,
+            capabilities: result.capabilities.map((cap) => ({
+                mimeType: cap.mimeType,
+                role: cap.role,
+                method: cap.method,
+                uploadUrl: cap.uploadUrl,
+                requiredHeaders: cap.requiredHeaders,
+            })),
+            expiresAt: result.expiresAt,
         };
     }
+    assertVariantsCoverPolicy(opPath, request, policy) {
+        const supplied = request.variants.map((v) => v.mimeType);
+        const missing = policy.required.filter((m) => !supplied.includes(m));
+        if (missing.length > 0) {
+            throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+        }
+        // Closed set: the policy declares which mimes belong to this
+        // purpose. Extras (e.g. an `image/png` alongside the declared
+        // avif/webp/jpeg trio) would land without a per-mime byte cap
+        // and bypass the size gate entirely. Reject any supplied mime
+        // outside `policy.required`.
+        const allowed = new Set(policy.required);
+        const extras = request.variants.filter((v) => !allowed.has(v.mimeType));
+        if (extras.length > 0) {
+            throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+        }
+        // Exactly one primary. Storage key layout is `<group>/<role>.<ext>`,
+        // so two primaries collide on the same R2 key + ambiguate which
+        // variant `<img>` falls back to. Same for any duplicated (mime, role)
+        // pair — two `image/jpeg` alternates would also collide on key.
+        const primaries = request.variants.filter((v) => v.role === "primary");
+        if (primaries.length !== 1) {
+            throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+        }
+        const seen = new Set();
+        for (const v of request.variants) {
+            const key = `${v.mimeType}/${v.role}`;
+            if (seen.has(key)) {
+                throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+            }
+            seen.add(key);
+        }
+    }
+    /** Enforce per-mime byte caps from the purpose policy BEFORE the
+     *  adapter signs presigned PUT URLs. Mantle docs / ADR-0017
+     *  promise this gate at create time — without it, oversized
+     *  variants only fail after R2 has accepted the bytes (wasted
+     *  upload + potential bill).
+     *
+     *  Also gates on positive-integer byteSize. JSON-RPC and HTTP
+     *  validation only narrow to `typeof === "number"`, so 0, -1, or
+     *  0.5 can reach here and produce signed URLs against a maxBytes
+     *  comparison that accepts them. */
+    assertVariantSizesUnderCap(opPath, request, policy) {
+        for (const v of request.variants) {
+            if (!Number.isSafeInteger(v.byteSize) || v.byteSize <= 0) {
+                throw new DiagnosticError(mediaVariantSizeExceededDiagnostic(opPath, v.mimeType, v.byteSize, 0));
+            }
+            const cap = policy.maxBytes[v.mimeType];
+            // mime outside policy.required was already rejected in
+            // assertVariantsCoverPolicy; defensive check so a future
+            // refactor doesn't silently uncap.
+            if (cap === undefined) {
+                throw new DiagnosticError(mediaVariantSizeExceededDiagnostic(opPath, v.mimeType, v.byteSize, 0));
+            }
+            if (v.byteSize > cap) {
+                throw new DiagnosticError(mediaVariantSizeExceededDiagnostic(opPath, v.mimeType, v.byteSize, cap));
+            }
+        }
+    }
+    assertEachVariantAccepted(opPath, request) {
+        for (const v of request.variants) {
+            if (v.mimeType === MEDIA_SVG_MIME && !this.opts.allowSvg) {
+                throw new DiagnosticError(mediaSvgRejectedDiagnostic(opPath));
+            }
+            if (!isAllowedMime(v.mimeType, this.opts.allowSvg)) {
+                throw new DiagnosticError(mediaMimeRejectedDiagnostic(opPath, v.mimeType));
+            }
+        }
+    }
+    assertNoSuspiciousSizing(opPath, request) {
+        const fallback = pickFallbackForSizing(request.variants);
+        if (!fallback)
+            return;
+        for (const v of request.variants) {
+            if (v === fallback)
+                continue;
+            if (!MODERN_FORMATS.has(v.mimeType))
+                continue;
+            if (v.byteSize > fallback.byteSize) {
+                throw new DiagnosticError(mediaVariantsSuspiciousSizeDiagnostic(opPath, `${v.mimeType} (${v.byteSize}B) > ${fallback.mimeType} (${fallback.byteSize}B)`));
+            }
+        }
+    }
+}
+/** Modern formats that, by convention, should be smaller than the
+ *  universal fallback (jpeg / png). Used by the "suspicious sizing"
+ *  heuristic — if any of these weigh more than the fallback, the
+ *  uploader almost certainly skipped optimization. */
+const MODERN_FORMATS = new Set(["image/avif", "image/webp"]);
+/** Pick the variant to compare modern formats against — preferred
+ *  order: jpeg → png → gif. Returns undefined when none of the
+ *  classic-format variants are present (e.g. an avif-only upload),
+ *  in which case the heuristic skips. */
+function pickFallbackForSizing(variants) {
+    for (const mime of ["image/jpeg", "image/png", "image/gif"]) {
+        const found = variants.find((v) => v.mimeType === mime);
+        if (found)
+            return found;
+    }
+    return undefined;
 }
 //# sourceMappingURL=CreateMediaUploadUseCase.js.map

package/dist/usecase/media/CreateMediaUploadUseCase.js.map

@@ -1 +1 @@
-{"version":3,"file":"CreateMediaUploadUseCase.js","sourceRoot":"","sources":["../../../src/usecase/media/CreateMediaUploadUseCase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CreateMediaUploadUseCase.js","sourceRoot":"","sources":["../../../src/usecase/media/CreateMediaUploadUseCase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA2B,MAAM,qBAAqB,CAAC;AAc/E,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,EAC9B,0BAA0B,EAC1B,kCAAkC,EAClC,iCAAiC,EACjC,qCAAqC,GACtC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,6BAA6B,EAC7B,sBAAsB,EACtB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAM7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,wBAAwB;IAEhB;IACA;IACA;IACA;IACA;IACA;IANnB,YACmB,OAAqB,EACrB,EAAW,EACX,KAAY,EACZ,KAAkB,EAClB,UAAgC,EAChC,OAAuC,EAAE,QAAQ,EAAE,KAAK,EAAE;QAL1D,YAAO,GAAP,OAAO,CAAc;QACrB,OAAE,GAAF,EAAE,CAAS;QACX,UAAK,GAAL,KAAK,CAAO;QACZ,UAAK,GAAL,KAAK,CAAa;QAClB,eAAU,GAAV,UAAU,CAAsB;QAChC,SAAI,GAAJ,IAAI,CAAsD;IAC1E,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,OAAiC;QAC7C,MAAM,MAAM,GAAG,2BAA2B,CAAC;QAE3C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC;QAC3D,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,eAAe,CACvB,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,CACvE,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,yBAAyB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC,0BAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACzD,IAAI,CAAC,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAE/C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,GAAG,GAAG,sBAAsB,GAAG,IAAI,CAAC;QACtD,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAExC,MAAM,YAAY,GAA2C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACxF,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,gBAAgB;YAChE,IAAI,EAAE,CAAC,CAAC,IAAI;SACb,CAAC,CAAC,CAAC;QAEJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC;YAC7C,aAAa;YACb,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,YAAY;YACtB,GAAG;YACH,SAAS;SACV,CAAC,CAAC;QAEH,MAAM,eAAe,GAA2B,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACnF,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,YAAY,EAAE,YAAY,CAAC,CAAC,CAAE,CAAC,QAAQ;YACvC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAE,CAAC,QAAQ;SACpC,CAAC,CAAC,CAAC;QAEJ,MAAM,MAAM,GAAwB;YAClC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,eAAe;YACzB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,GAAG;SACf,CAAC;QAEF,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CACf,GAAG,wBAAwB,GAAG,MAAM,CAAC,aAAa,EAAE,EACpD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EACtB,EAAE,aAAa,EAAE,6BAA6B,EAAE,CACjD,CAAC;QAEF,OAAO;YACL,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAC9C,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,eAAe,EAAE,GAAG,CAAC,eAAe;aACrC,CAAC,CAAC;YACH,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC;IACJ,CAAC;IAEO,yBAAyB,CAC/B,MAAc,EACd,OAAiC,EACjC,MAA0B;QAE1B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,eAAe,CACvB,iCAAiC,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAClF,CAAC;QACJ,CAAC;QACD,6DAA6D;QAC7D,8DAA8D;QAC9D,8DAA8D;QAC9D,8DAA8D;QAC9D,6BAA6B;QAC7B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACxE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,eAAe,CACvB,iCAAiC,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAClF,CAAC;QACJ,CAAC;QACD,qEAAqE;QACrE,gEAAgE;QAChE,sEAAsE;QACtE,gEAAgE;QAChE,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;QACvE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,eAAe,CACvB,iCAAiC,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAClF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,MAAM,IAAI,eAAe,CACvB,iCAAiC,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAClF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;wCASoC;IAC5B,0BAA0B,CAChC,MAAc,EACd,OAAiC,EACjC,MAA0B;QAE1B,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;gBACzD,MAAM,IAAI,eAAe,CACvB,kCAAkC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CACtE,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACxC,uDAAuD;YACvD,yDAAyD;YACzD,mCAAmC;YACnC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAI,eAAe,CACvB,kCAAkC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CACtE,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC;gBACrB,MAAM,IAAI,eAAe,CACvB,kCAAkC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CACxE,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAEO,yBAAyB,CAC/B,MAAc,EACd,OAAiC;QAEjC,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjC,IAAI,CAAC,CAAC,QAAQ,KAAK,cAAc,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACzD,MAAM,IAAI,eAAe,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC;YAChE,CAAC;YACD,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnD,MAAM,IAAI,eAAe,CAAC,2BAA2B,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC;IACH,CAAC;IAEO,wBAAwB,CAC9B,MAAc,EACd,OAAiC;QAEjC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACzD,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,QAAQ;gBAAE,SAAS;YAC7B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAAE,SAAS;YAC9C,IAAI,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACnC,MAAM,IAAI,eAAe,CACvB,qCAAqC,CACnC,MAAM,EACN,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,QAAQ,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,IAAI,CAChF,CACF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED;;;sDAGsD;AACtD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAE7D;;;yCAGyC;AACzC,SAAS,qBAAqB,CAC5B,QAAoD;IAEpD,KAAK,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACxD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/usecase/media/PendingUploadRecord.d.ts

@@ -1,17 +1,36 @@
+import type { MediaVariantRole } from "../../domain/port/MediaStorage.js";
 /** KV record persisted by `CreateMediaUploadUseCase` and read by
  *  `CommitMediaUploadUseCase`. Stored under
- *  `${PENDING_UPLOAD_KV_PREFIX}${uploadId}` with a TTL set to
- *  `PENDING_UPLOAD_KV_TTL_SECONDS`. */
+ *  `${PENDING_UPLOAD_KV_PREFIX}${uploadGroupId}` with a TTL set to
+ *  `PENDING_UPLOAD_KV_TTL_SECONDS`.
+ *
+ *  Multi-variant from the start (#272): one record tracks every
+ *  variant the agent declared, so commit can HEAD all N R2 objects
+ *  in one atomic shot.
+ */
 export interface PendingUploadRecord {
-    readonly storageKey: string;
-    readonly expectedMimeType: string;
-    /** Caller-declared byte size, persisted at create time so commit can
-     *  enforce a tight per-upload ceiling instead of just the adapter-
-     *  wide `maxBytes`. Adapter ultimately verifies actual stored bytes
-     *  ≤ commit-supplied maxBytes — `CommitMediaUploadUseCase` passes
-     *  `min(adapterCap, record.expectedSize)`. */
-    readonly expectedSize: number;
+    readonly purpose: string;
+    /** Original filename — forwarded by commit into R2 customMetadata
+     *  on every variant. Preserved here so the commit path sees it
+     *  without a second hop. */
+    readonly filename: string;
+    readonly variants: ReadonlyArray<PendingUploadVariant>;
+    readonly alt?: string;
+    readonly caption?: string;
     readonly expiresAt: number;
     readonly createdAt: number;
 }
+export interface PendingUploadVariant {
+    readonly mimeType: string;
+    readonly role: MediaVariantRole;
+    readonly storageKey: string;
+    /** Caller-declared byte size, persisted at create time so commit
+     *  can enforce a tight per-variant ceiling rather than just the
+     *  per-purpose `maxBytes`. The adapter ultimately verifies actual
+     *  stored bytes ≤ this. */
+    readonly expectedSize: number;
+    /** Per-purpose `maxBytes[mimeType]`. Forwarded to the adapter so
+     *  HEAD-verify rejects oversized PUTs with the right cap message. */
+    readonly maxBytes: number;
+}
 //# sourceMappingURL=PendingUploadRecord.d.ts.map

package/dist/usecase/media/PendingUploadRecord.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PendingUploadRecord.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/PendingUploadRecord.ts"],"names":[],"mappings":"AAAA;;;uCAGuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;kDAI8C;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"PendingUploadRecord.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/PendingUploadRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;gCAE4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;+BAG2B;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;yEACqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/usecase/media/diagnostics.d.ts

@@ -3,8 +3,8 @@ export declare function mediaNotConfiguredDiagnostic(opPath: string): Diagnostic
 export declare function mediaMimeRejectedDiagnostic(opPath: string, mime: string): Diagnostic;
 export declare function mediaSvgRejectedDiagnostic(opPath: string): Diagnostic;
 export declare function mediaSizeExceededDiagnostic(opPath: string, byteSize: number, maxBytes: number): Diagnostic;
-export declare function mediaUploadExpiredDiagnostic(opPath: string, uploadId: string): Diagnostic;
-export declare function mediaObjectNotFoundDiagnostic(opPath: string, uploadId: string): Diagnostic;
+export declare function mediaUploadExpiredDiagnostic(opPath: string, uploadGroupId: string): Diagnostic;
+export declare function mediaObjectNotFoundDiagnostic(opPath: string, uploadGroupId: string): Diagnostic;
 /** Caller supplied a `purpose` that this deployment did not declare in
  *  `siteDefaults.media.purposes`. Fail-closed per #262: alpha has no
  *  production consumers, so there is no warn-and-allow compatibility
@@ -12,4 +12,21 @@ export declare function mediaObjectNotFoundDiagnostic(opPath: string, uploadId:
  *  field carries the declared set so agents can self-correct without
  *  another round trip. */
 export declare function mediaPurposeRejectedDiagnostic(opPath: string, purpose: string | undefined, declared: readonly string[]): Diagnostic;
+/** Caller's variants manifest is missing one or more mimes the
+ *  purpose policy declares as required. The expected field carries
+ *  the declared required set + the supplied set so the agent script
+ *  can self-correct without another round trip. */
+export declare function mediaVariantsIncompleteDiagnostic(opPath: string, purpose: string, required: readonly string[], supplied: readonly string[]): Diagnostic;
+export declare function mediaVariantSizeExceededDiagnostic(opPath: string, mime: string, byteSize: number, maxBytes: number): Diagnostic;
+/**
+ * Variant byte sizes don't match the format hierarchy the uploader
+ * promised — typically avif > webp > jpeg (each modern format
+ * smaller). When the upload manifest claims a modern format that's
+ * larger than the universal-fallback (e.g. `avif` weighing more than
+ * `jpeg`), the uploader almost certainly skipped optimization for
+ * that variant. Fail hard rather than emit a `<picture>` that's
+ * slower than the bare `<img>` fallback.
+ */
+export declare function mediaVariantsSuspiciousSizeDiagnostic(opPath: string, detail: string): Diagnostic;
+export declare function mediaAssetNotFoundDiagnostic(opPath: string, id: string): Diagnostic;
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/usecase/media/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAUvE;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CASpF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAUrE;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,UAAU,CASZ;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAUzF;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAU1F;AAED;;;;;0BAK0B;AAC1B,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,UAAU,CAiBZ"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAUvE;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CASpF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAUrE;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,UAAU,CASZ;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,UAAU,CAU9F;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,UAAU,CAU/F;AAED;;;;;0BAK0B;AAC1B,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,UAAU,CAiBZ;AAED;;;mDAGmD;AACnD,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,UAAU,CAaZ;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,UAAU,CAWZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,UAAU,CAYZ;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,CAWnF"}