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

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":"AAKA,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;IA2EjC;;;;;;;;;wCASoC;IACpC,OAAO,CAAC,0BAA0B;IA4BlC,OAAO,CAAC,yBAAyB;IAcjC,OAAO,CAAC,wBAAwB;CAmBjC"}

package/dist/usecase/media/CreateMediaUploadUseCase.js

@@ -1,71 +1,214 @@
-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 { DiagnosticError, expandPolicyRequired, } from "@aotter/mantle-spec";
+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) {
+        // Expand the `<input accept>`-style grammar (#282) into per-slot
+        // acceptable mime sets. The policy validator already rejected
+        // overlapping mime sets across slots + empty slots, so variant→slot
+        // mapping here is unambiguous: each supplied mime appears in
+        // exactly one slot. Role (primary vs alternate) stays free per
+        // variant — the agent picks which mime is primary, constrained
+        // only by the exactly-one-primary rule below.
+        const slots = expandPolicyRequired(policy.required);
+        const expandedSet = new Set();
+        const mimeToSlot = new Map();
+        slots.forEach((mimes, slotIdx) => {
+            for (const m of mimes) {
+                expandedSet.add(m);
+                mimeToSlot.set(m, slotIdx);
+            }
+        });
+        const supplied = request.variants.map((v) => v.mimeType);
+        // Closed set: any supplied mime outside the expanded acceptable
+        // set has no maxBytes coverage and no slot assignment. Reject.
+        const extras = request.variants.filter((v) => !expandedSet.has(v.mimeType));
+        if (extras.length > 0) {
+            throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+        }
+        // Exactly one variant per slot — covers "missing slot" and
+        // "two variants for the same slot" (e.g. an extra `image/jpeg`
+        // when slot 0 = `image/jpg,image/png`: both jpg and png supplied
+        // would fill slot 0 twice and leave the png slot unfilled if you
+        // count by mime-set).
+        const filledSlots = new Set();
+        for (const v of request.variants) {
+            const slotIdx = mimeToSlot.get(v.mimeType); // safe: extras rejected above
+            if (filledSlots.has(slotIdx)) {
+                throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+            }
+            filledSlots.add(slotIdx);
+        }
+        if (filledSlots.size !== slots.length) {
+            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. Two alternates with different
+        // mimes don't collide (different ext); two alternates with the
+        // same mime are impossible here because the mime-to-slot mapping
+        // would have caught the duplicate above.
+        const primaries = request.variants.filter((v) => v.role === "primary");
+        if (primaries.length !== 1) {
+            throw new DiagnosticError(mediaVariantsIncompleteDiagnostic(opPath, policy.name, policy.required, supplied));
+        }
+    }
+    /** 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":"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"}

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/UploadMediaVariantUseCase.d.ts

@@ -0,0 +1,35 @@
+import type { Clock } from "../../domain/port/Clock.js";
+import type { KvCache } from "../../domain/port/KvCache.js";
+import type { MediaStorage } from "../../domain/port/MediaStorage.js";
+import type { UploadMediaVariantRequest } from "../dto/media/index.js";
+/**
+ * Server-side byte write for one variant of a pending upload — the
+ * sandboxed-agent alternative to the presigned-PUT path produced by
+ * `createUpload`. Used by the `upload_media_variant` MCP tool when
+ * the caller can't reach the storage backend directly (#283 — Claude
+ * Cowork's outbound proxy doesn't allowlist R2 hosts; the MCP
+ * transport gets traffic to the Worker via api.anthropic.com).
+ *
+ * Validates the request against the existing `PendingUploadRecord`
+ * (must match purpose + role + mimeType + size cap) then asks the
+ * storage adapter to write the bytes. The pending record is NOT
+ * deleted here — commit still HEAD-verifies the object via the same
+ * code path as the presigned-PUT case. All-or-nothing across the
+ * variant bundle still applies at commit time; this use case just
+ * lands one variant's bytes.
+ *
+ * Same purpose policies as the presigned path: per-mime `maxBytes`,
+ * per-purpose declared variant set, all already validated by
+ * `CreateMediaUploadUseCase` when the agent first opened the group.
+ */
+export declare class UploadMediaVariantUseCase {
+    private readonly storage;
+    private readonly kv;
+    private readonly clock;
+    constructor(storage: MediaStorage, kv: KvCache, clock: Clock);
+    execute(request: UploadMediaVariantRequest): Promise<{
+        storageKey: string;
+        byteSize: number;
+    }>;
+}
+//# sourceMappingURL=UploadMediaVariantUseCase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UploadMediaVariantUseCase.d.ts","sourceRoot":"","sources":["../../../src/usecase/media/UploadMediaVariantUseCase.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAYvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,yBAAyB;IAElC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFL,OAAO,EAAE,YAAY,EACrB,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,KAAK;IAGzB,OAAO,CACX,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAyDrD"}

package/dist/usecase/media/UploadMediaVariantUseCase.js

@@ -0,0 +1,75 @@
+import { DiagnosticError } from "@aotter/mantle-spec";
+import { mediaUploadExpiredDiagnostic, mediaVariantSizeExceededDiagnostic, mediaMimeRejectedDiagnostic, } from "./diagnostics.js";
+import { PENDING_UPLOAD_KV_PREFIX } from "./mediaAllowlist.js";
+/**
+ * Server-side byte write for one variant of a pending upload — the
+ * sandboxed-agent alternative to the presigned-PUT path produced by
+ * `createUpload`. Used by the `upload_media_variant` MCP tool when
+ * the caller can't reach the storage backend directly (#283 — Claude
+ * Cowork's outbound proxy doesn't allowlist R2 hosts; the MCP
+ * transport gets traffic to the Worker via api.anthropic.com).
+ *
+ * Validates the request against the existing `PendingUploadRecord`
+ * (must match purpose + role + mimeType + size cap) then asks the
+ * storage adapter to write the bytes. The pending record is NOT
+ * deleted here — commit still HEAD-verifies the object via the same
+ * code path as the presigned-PUT case. All-or-nothing across the
+ * variant bundle still applies at commit time; this use case just
+ * lands one variant's bytes.
+ *
+ * Same purpose policies as the presigned path: per-mime `maxBytes`,
+ * per-purpose declared variant set, all already validated by
+ * `CreateMediaUploadUseCase` when the agent first opened the group.
+ */
+export class UploadMediaVariantUseCase {
+    storage;
+    kv;
+    clock;
+    constructor(storage, kv, clock) {
+        this.storage = storage;
+        this.kv = kv;
+        this.clock = clock;
+    }
+    async execute(request) {
+        const opPath = "usecase/UploadMediaVariant";
+        const kvKey = `${PENDING_UPLOAD_KV_PREFIX}${request.uploadGroupId}`;
+        const raw = await this.kv.get(kvKey);
+        if (!raw) {
+            throw new DiagnosticError(mediaUploadExpiredDiagnostic(opPath, request.uploadGroupId));
+        }
+        const record = JSON.parse(raw);
+        // Wall-clock expiry check. KV TTL covers the eventual-deletion
+        // case, but during the window between `expiresAt` and the TTL
+        // firing the record is still readable — reject explicitly so the
+        // agent can't ship variant bytes against a stale capability.
+        if (this.clock.now() >= record.expiresAt) {
+            throw new DiagnosticError(mediaUploadExpiredDiagnostic(opPath, request.uploadGroupId));
+        }
+        // Find the matching declared variant. The pending record's
+        // variants[] is the source of truth for "what role + mime are
+        // valid in this group"; an agent uploading something not in the
+        // declared set is rejected the same way create-then-PUT would
+        // have rejected an unknown storageKey.
+        const declared = findMatchingVariant(record.variants, request.role, request.mimeType);
+        if (!declared) {
+            throw new DiagnosticError(mediaMimeRejectedDiagnostic(opPath, request.mimeType));
+        }
+        const byteSize = request.bytes.byteLength;
+        if (byteSize > declared.maxBytes) {
+            throw new DiagnosticError(mediaVariantSizeExceededDiagnostic(opPath, request.mimeType, byteSize, declared.maxBytes));
+        }
+        const result = await this.storage.putVariantBytes({
+            uploadGroupId: request.uploadGroupId,
+            purpose: record.purpose,
+            role: request.role,
+            mimeType: request.mimeType,
+            filename: record.filename,
+            bytes: request.bytes,
+        });
+        return { storageKey: result.storageKey, byteSize };
+    }
+}
+function findMatchingVariant(variants, role, mimeType) {
+    return variants.find((v) => v.role === role && v.mimeType === mimeType);
+}
+//# sourceMappingURL=UploadMediaVariantUseCase.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UploadMediaVariantUseCase.js","sourceRoot":"","sources":["../../../src/usecase/media/UploadMediaVariantUseCase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAQtD,OAAO,EACL,4BAA4B,EAC5B,kCAAkC,EAClC,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAM/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,yBAAyB;IAEjB;IACA;IACA;IAHnB,YACmB,OAAqB,EACrB,EAAW,EACX,KAAY;QAFZ,YAAO,GAAP,OAAO,CAAc;QACrB,OAAE,GAAF,EAAE,CAAS;QACX,UAAK,GAAL,KAAK,CAAO;IAC5B,CAAC;IAEJ,KAAK,CAAC,OAAO,CACX,OAAkC;QAElC,MAAM,MAAM,GAAG,4BAA4B,CAAC;QAE5C,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,+DAA+D;QAC/D,8DAA8D;QAC9D,iEAAiE;QACjE,6DAA6D;QAC7D,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,IAAI,eAAe,CACvB,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAC5D,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,8DAA8D;QAC9D,gEAAgE;QAChE,8DAA8D;QAC9D,uCAAuC;QACvC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,eAAe,CACvB,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CACtD,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;QAC1C,IAAI,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,eAAe,CACvB,kCAAkC,CAChC,MAAM,EACN,OAAO,CAAC,QAAQ,EAChB,QAAQ,EACR,QAAQ,CAAC,QAAQ,CAClB,CACF,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC;YAChD,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;QAEH,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC;IACrD,CAAC;CACF;AAED,SAAS,mBAAmB,CAC1B,QAA6C,EAC7C,IAAsB,EACtB,QAAgB;IAEhB,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAC1E,CAAC"}

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"}