@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/attachment-local/lib/index.js

@@ -1,27 +1,117 @@
 import { dirname, join, parse, resolve } from "node:path";
-import z from "@nomix-ai/schemastery";
-import { AttachmentError, AttachmentId, AttachmentStore } from "../../attachment/lib/index.js";
+import z from "../../schemastery/lib/index.mjs";
+import { AttachmentError, AttachmentId, AttachmentStore, ImageVariantId } from "../../attachment/lib/index.js";
 import { resolveNomixHome } from "../../home-paths/lib/index.js";
 import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { chmod, link, mkdir, open, readFile, unlink } from "node:fs/promises";
+import { chmod, link, mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import sharp from "sharp";
+//#region lib/types/compression-limiter.js
+/** Instance-owned concurrency bound for native image transformations. */
+/** FIFO limiter for asynchronous compression work. */
+var CompressionLimiter = class {
+	concurrency;
+	active = 0;
+	waiting = [];
+	/**
+	* @param concurrency - positive maximum number of active tasks.
+	*/
+	constructor(concurrency) {
+		this.concurrency = concurrency;
+	}
+	/**
+	* Run one task after an instance slot becomes available.
+	* @param task - compression operation occupying one slot until settlement.
+	* @returns the task result.
+	*/
+	run(task) {
+		return new Promise((resolve, reject) => {
+			const start = () => {
+				this.active += 1;
+				const release = () => {
+					this.active -= 1;
+					this.waiting.shift()?.();
+				};
+				Promise.resolve().then(task).then((value) => {
+					release();
+					resolve(value);
+				}, (error) => {
+					release();
+					reject(error instanceof Error ? error : new Error("Image compression task rejected with a non-Error value.", { cause: error }));
+				});
+			};
+			if (this.active < this.concurrency) start();
+			else this.waiting.push(start);
+		});
+	}
+};
+//#endregion
+//#region lib/types/encoding.js
+/** Shared lazy candidate execution for normalization and request-image encoders. */
+/**
+* Execute encoding candidates in preference order and stop after the first fitting output.
+* @param attempts - lazy encoders ordered from preferred to fallback representation.
+* @param maxBytes - positive encoded-byte cap.
+* @returns the first fitting candidate, otherwise the smallest completed fallback.
+*/
+async function encodeFirstWithinLimit(attempts, maxBytes) {
+	const [first, ...remaining] = attempts;
+	if (first === void 0) throw new Error("image encoding requires at least one candidate");
+	let smallest = await first();
+	if (smallest.data.byteLength <= maxBytes) return smallest;
+	for (const attempt of remaining) {
+		const candidate = await attempt();
+		if (candidate.data.byteLength <= maxBytes) return candidate;
+		if (candidate.data.byteLength < smallest.data.byteLength) smallest = candidate;
+	}
+	return { smallest };
+}
+/**
+* Whether a lazy encoding result exhausted every candidate at one size.
+* @param result - first fitting candidate or exhausted result.
+* @returns whether every candidate exceeded the byte cap.
+*/
+function isExhaustedEncoding(result) {
+	return "smallest" in result;
+}
+//#endregion
 //#region lib/types/image.js
 /** Raster inspection: full decode at admission, header-only probe on verified reads. */
+/**
+* Check alpha metadata for bytes produced by this package's encoders.
+* Sharp/libvips may omit an all-opaque alpha plane from WebP output; every
+* other addition or removal indicates that the encoded result is incompatible
+* with its source facts.
+* @param sourceHasAlpha - whether the source bytes declare an alpha plane, or undefined when the source frame is unspecified.
+* @param output - decoded media type and alpha metadata from the encoded result.
+* @returns whether the output alpha metadata is compatible with the source.
+*/
+function encodedAlphaIsCompatible(sourceHasAlpha, output) {
+	return sourceHasAlpha === void 0 || output.hasAlpha === sourceHasAlpha || sourceHasAlpha && !output.hasAlpha && output.mediaType === "image/webp";
+}
 const MEDIA_TYPES = {
 	png: "image/png",
 	jpeg: "image/jpeg",
 	webp: "image/webp",
 	gif: "image/gif"
 };
+function carriesRetainedMetadata(metadata) {
+	return metadata.exif !== void 0 || metadata.xmp !== void 0 || metadata.iptc !== void 0 || metadata.icc !== void 0 || metadata.hasProfile || metadata.tifftagPhotoshop !== void 0 || metadata.comments !== void 0 || metadata.orientation !== void 0;
+}
 async function imageMetadata(image) {
 	const metadata = await image.metadata();
 	const mediaType = MEDIA_TYPES[metadata.format];
 	if (mediaType === void 0) throw new AttachmentError("Unsupported or malformed image data.", "INVALID_IMAGE");
+	const transposed = metadata.orientation !== void 0 && metadata.orientation >= 5;
 	return {
 		mediaType,
-		width: metadata.width,
-		height: metadata.height
+		width: transposed ? metadata.height : metadata.width,
+		height: transposed ? metadata.width : metadata.height,
+		animated: (metadata.pages ?? 1) > 1,
+		carriesMetadata: carriesRetainedMetadata(metadata),
+		depth: metadata.depth,
+		space: metadata.space,
+		hasAlpha: metadata.hasAlpha
 	};
 }
 /**
@@ -46,17 +136,18 @@ async function probeImage(data) {
 /**
 * Fully decode a supported raster and return its intrinsic metadata.
 * @param data - complete encoded image bytes.
-* @param maxPixels - decoded-pixel admission limit.
+* @param limits - intrinsic-dimension admission limits.
 * @returns verified format and dimensions.
 */
-async function detectImage(data, maxPixels) {
+async function detectImage(data, limits) {
 	try {
 		const image = sharp(data, {
 			failOn: "error",
 			limitInputPixels: false
 		});
 		const detected = await imageMetadata(image);
-		if (maxPixels !== void 0 && detected.width * detected.height > maxPixels) throw new AttachmentError("Image exceeds the configured decoded-pixel limit.", "IMAGE_TOO_MANY_PIXELS");
+		if (limits?.maxPixels !== void 0 && detected.width * detected.height > limits.maxPixels) throw new AttachmentError("Image exceeds the configured decoded-pixel limit.", "IMAGE_TOO_MANY_PIXELS");
+		if (limits?.maxDimension !== void 0 && Math.max(detected.width, detected.height) > limits.maxDimension) throw new AttachmentError("Image exceeds the configured per-side pixel limit.", "IMAGE_DIMENSION_TOO_LARGE");
 		await image.raw().toBuffer();
 		return detected;
 	} catch (error) {
@@ -65,11 +156,144 @@ async function detectImage(data, maxPixels) {
 	}
 }
 //#endregion
+//#region lib/types/normalization.js
+/** Deterministic provider-independent image normalization. */
+const NORMALIZATION_QUALITIES = [
+	85,
+	80,
+	75
+];
+const LOW_COLOUR_SAMPLE_EDGE = 128;
+const LOW_COLOUR_LIMIT = 256;
+const MIN_SCALE_STEP = .9;
+/** Encode one prepared pipeline and report exact output facts. */
+async function encode(pipeline, mediaType, quality, palette = true) {
+	const { data, info } = await (mediaType === "image/png" ? pipeline.png({
+		compressionLevel: 9,
+		palette
+	}) : mediaType === "image/webp" ? pipeline.webp({ quality }) : pipeline.jpeg({ quality })).toBuffer({ resolveWithObject: true });
+	return {
+		data: new Uint8Array(data),
+		mediaType,
+		width: info.width,
+		height: info.height
+	};
+}
+/**
+* Whether bytes already satisfy the normalization requirements.
+* @param detected - fully decoded source facts.
+* @param bytes - encoded source length.
+* @param policy - resolved normalization limits.
+* @returns whether the source can pass through byte-identically.
+*/
+function canPassThroughNormalization(detected, bytes, policy) {
+	return detected.mediaType !== "image/gif" && !detected.animated && !detected.carriesMetadata && detected.depth === "uchar" && detected.space === "srgb" && bytes <= policy.maxBytes && Math.max(detected.width, detected.height) <= policy.maxDimension;
+}
+/**
+* Classify a bounded pixel sample without assuming that a PNG source is a screenshot.
+* @param pipeline - oriented sRGB source pipeline before output resizing.
+* @returns whether the nearest-neighbour sample stays within the low-color threshold.
+*/
+async function hasLowColourCount(pipeline) {
+	const { data, info } = await pipeline.clone().resize({
+		width: LOW_COLOUR_SAMPLE_EDGE,
+		height: LOW_COLOUR_SAMPLE_EDGE,
+		fit: "inside",
+		withoutEnlargement: true,
+		kernel: sharp.kernel.nearest,
+		fastShrinkOnLoad: false
+	}).raw().toBuffer({ resolveWithObject: true });
+	const colours = /* @__PURE__ */ new Set();
+	for (let offset = 0; offset < data.length; offset += info.channels) {
+		const red = data.readUInt8(offset);
+		const green = data.readUInt8(offset + 1);
+		const blue = data.readUInt8(offset + 2);
+		const alpha = info.channels === 4 ? data.readUInt8(offset + 3) : 255;
+		colours.add(red >> 3 << 15 | green >> 3 << 10 | blue >> 3 << 5 | alpha >> 3);
+		if (colours.size > LOW_COLOUR_LIMIT) return false;
+	}
+	return true;
+}
+/** Assert that a normalized output is an 8-bit sRGB/sRGBA single-frame image with matching facts. */
+async function verifyNormalizedImage(image, expectedAlpha) {
+	const detected = await detectImage(image.data);
+	if (detected.mediaType !== image.mediaType || detected.width !== image.width || detected.height !== image.height || detected.animated || detected.carriesMetadata || detected.depth !== "uchar" || detected.space !== "srgb" || !encodedAlphaIsCompatible(expectedAlpha, detected)) throw new AttachmentError("Image normalization did not produce a single-frame 8-bit sRGB image with matching metadata.", "ATTACHMENT_WRITE_FAILED");
+	return image;
+}
+/** Build one fixed-size, oriented, metadata-free sRGB pipeline from submitted bytes. */
+function preparedPipeline(data, width, height) {
+	return sharp(data, {
+		failOn: "error",
+		limitInputPixels: false
+	}).rotate().toColourspace("srgb").resize({
+		width,
+		height,
+		fit: "inside",
+		withoutEnlargement: true
+	});
+}
+/** Dimensions after the long edge is capped without changing aspect ratio. */
+function initialDimensions(detected, maxDimension) {
+	const scale = Math.min(1, maxDimension / Math.max(detected.width, detected.height));
+	return {
+		width: Math.max(1, Math.round(detected.width * scale)),
+		height: Math.max(1, Math.round(detected.height * scale))
+	};
+}
+/** Lazy encoding order for one size, separated by sampled colour complexity and alpha. */
+function encodingAttemptsAtSize(data, width, height, hasAlpha, lowColour) {
+	const prepared = preparedPipeline(data, width, height);
+	const webp = NORMALIZATION_QUALITIES.map((quality) => (() => encode(prepared.clone(), "image/webp", quality)));
+	if (lowColour) return [() => encode(prepared.clone(), "image/png", void 0, !hasAlpha), ...webp];
+	if (hasAlpha) return webp;
+	return NORMALIZATION_QUALITIES.map((quality) => (() => encode(prepared.clone(), "image/jpeg", quality)));
+}
+/**
+* Produce the persisted provider-independent normalized version of one fully decoded source.
+* The source is passed through only when it is already clean, single-frame, 8-bit sRGB/sRGBA,
+* and inside both normalization limits. Re-encoding never removes transparency. After the fixed
+* quality floor is reached, dimensions continue shrinking until the independent byte cap holds.
+* @param data - complete admitted source bytes.
+* @param detected - fully decoded source facts.
+* @param policy - resolved independent normalization limits.
+* @returns verified provider-independent normalized bytes and metadata.
+*/
+async function normalizeImage(data, detected, policy) {
+	if (canPassThroughNormalization(detected, data.byteLength, policy)) return {
+		data,
+		mediaType: detected.mediaType,
+		width: detected.width,
+		height: detected.height
+	};
+	try {
+		let { width, height } = initialDimensions(detected, policy.maxDimension);
+		const lowColour = await hasLowColourCount(sharp(data, {
+			failOn: "error",
+			limitInputPixels: false
+		}).rotate().toColourspace("srgb"));
+		for (;;) {
+			const encoded = await encodeFirstWithinLimit(encodingAttemptsAtSize(data, width, height, detected.hasAlpha, lowColour), policy.maxBytes);
+			if (!isExhaustedEncoding(encoded)) return await verifyNormalizedImage(encoded, detected.mediaType === "image/gif" ? void 0 : detected.hasAlpha);
+			if (width === 1 && height === 1) break;
+			const sizeScale = Math.sqrt(policy.maxBytes / encoded.smallest.data.byteLength) * .95;
+			const scale = Math.min(MIN_SCALE_STEP, sizeScale);
+			const nextWidth = Math.max(1, Math.floor(width * scale));
+			const nextHeight = Math.max(1, Math.floor(height * scale));
+			width = nextWidth;
+			height = nextHeight;
+		}
+	} catch (error) {
+		if (error instanceof AttachmentError) throw error;
+		throw new AttachmentError(`The ${detected.mediaType === "image/png" && detected.depth !== "uchar" ? `${detected.depth === "ushort" ? "16-bit" : detected.depth} PNG` : `${detected.depth} ${detected.mediaType.slice(6).toUpperCase()}`} could not be converted to the normalized 8-bit sRGB form.`, "ATTACHMENT_WRITE_FAILED", { cause: error });
+	}
+	throw new AttachmentError("Image cannot be encoded within the configured normalized-image byte cap.", "IMAGE_TOO_LARGE");
+}
+//#endregion
 //#region lib/types/store.js
 /** Content-addressed, owner-private local attachment storage. */
 const ID_PATTERN = /^sha256:([a-f0-9]{64})$/;
 const durableHomes = /* @__PURE__ */ new Set();
-function digest(data) {
+function digest$1(data) {
 	return createHash("sha256").update(data).digest("hex");
 }
 function displayName(value) {
@@ -85,24 +309,56 @@ function ensureReference(ref) {
 	if (match?.[1] === void 0) throw new AttachmentError("Attachment reference is invalid.", "INVALID_ATTACHMENT_REF");
 	return match[1];
 }
-async function inspectMetadata(data, declaredMediaType, maxPixels) {
+async function inspectMetadata(data, declaredMediaType, limits) {
 	if (data.byteLength === 0) throw new AttachmentError("Image is empty.", "INVALID_IMAGE");
-	const detected = await detectImage(data, maxPixels);
+	const detected = await detectImage(data, {
+		maxPixels: limits.maxImagePixels,
+		maxDimension: limits.maxImageDimension
+	});
 	if (detected.mediaType !== declaredMediaType) throw new AttachmentError("Declared image type does not match its bytes.", "IMAGE_TYPE_MISMATCH");
-	return {
-		...detected,
-		bytes: data.byteLength
-	};
+	return detected;
 }
 /**
-* Run the full admission policy for one image without touching storage.
+* Run the full admission policy for one image without touching storage,
+* including normalization: a batch whose members all validate cannot later
+* be refused by the normalized image byte cap during publication.
 * @param input - encoded bytes and declared metadata.
-* @param limits - resolved storage policy.
-* @returns completion after the encoded raster has been fully decoded.
+* @param limits - resolved source admission policy.
+* @param policy - resolved normalization policy.
+* @returns completion after the raster has been decoded and its normalized version proven to fit.
+*/
+async function validateImageFile(input, limits, policy) {
+	await prepareImageFile(input, limits, policy);
+}
+/**
+* Decode, normalize, and verify one submitted image without touching storage.
+* @param input - submitted encoded bytes and declared media type.
+* @param limits - source admission policy.
+* @param policy - independent normalization policy.
+* @returns immutable reference facts beside bytes ready for atomic publication.
 */
-async function validateImageFile(input, limits) {
+async function prepareImageFile(input, limits, policy) {
 	if (input.data.byteLength > limits.maxImageBytes) throw new AttachmentError("Image exceeds the configured byte limit.", "IMAGE_TOO_LARGE");
-	await inspectMetadata(input.data, input.mediaType, limits.maxImagePixels);
+	const detected = await inspectMetadata(input.data, input.mediaType, limits);
+	const normalized = await normalizeImage(input.data, detected, policy);
+	const sha256 = digest$1(normalized.data);
+	const name = displayName(input.name);
+	const downscaled = detected.width !== normalized.width || detected.height !== normalized.height;
+	return {
+		data: normalized.data,
+		ref: {
+			attachmentId: AttachmentId(`sha256:${sha256}`),
+			mediaType: normalized.mediaType,
+			width: normalized.width,
+			height: normalized.height,
+			bytes: normalized.data.byteLength,
+			...name !== void 0 ? { name } : {},
+			...downscaled ? { originalDimensions: {
+				width: detected.width,
+				height: detected.height
+			} } : {}
+		}
+	};
 }
 /**
 * Make a directory's entries durable (fsync on a read-only directory handle).
@@ -164,16 +420,15 @@ async function ensureDurableHome(path) {
 	return home;
 }
 /**
-* Save and verify immutable image bytes below a versioned attachment root.
+* Publish one already verified normalized image below a versioned attachment root.
 * @param root - absolute `NOMIX_HOME/attachments/v1` root.
-* @param input - encoded bytes and declared metadata.
-* @param limits - resolved storage policy.
-* @returns durable content-addressed reference.
+* @param prepared - deterministic normalized bytes and reference.
+* @returns durable content-addressed normalized image reference.
 */
-async function saveImageFile(root, input, limits) {
-	if (input.data.byteLength > limits.maxImageBytes) throw new AttachmentError("Image exceeds the configured byte limit.", "IMAGE_TOO_LARGE");
-	const metadata = await inspectMetadata(input.data, input.mediaType, limits.maxImagePixels);
-	const sha256 = digest(input.data);
+async function commitPreparedImageFile(root, prepared) {
+	const normalized = prepared.data;
+	const sha256 = ensureReference(prepared.ref);
+	if (digest$1(normalized) !== sha256 || normalized.byteLength !== prepared.ref.bytes) throw new AttachmentError("Prepared attachment bytes do not match their reference.", "ATTACHMENT_CORRUPT");
 	const bucket = join(root, "objects", sha256.slice(0, 2));
 	const staging = join(root, "tmp");
 	const boundary = await ensureDurableHome(dirname(dirname(resolve(root))));
@@ -184,7 +439,7 @@ async function saveImageFile(root, input, limits) {
 	let handle;
 	try {
 		handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 384);
-		await handle.writeFile(input.data);
+		await handle.writeFile(normalized);
 		await handle.sync();
 		await handle.close();
 		handle = void 0;
@@ -193,7 +448,7 @@ async function saveImageFile(root, input, limits) {
 		} catch (error) {
 			/* v8 ignore next -- Private same-filesystem directories make EEXIST the only recoverable link race. */
 			if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
-			if (digest(new Uint8Array(await readFile(target))) !== sha256) throw new AttachmentError("Stored attachment failed integrity verification.", "ATTACHMENT_CORRUPT");
+			if (digest$1(new Uint8Array(await readFile(target))) !== sha256) throw new AttachmentError("Stored attachment failed integrity verification.", "ATTACHMENT_CORRUPT");
 		}
 		await syncDirectory(bucket);
 		await syncDirectory(join(root, "objects"));
@@ -214,12 +469,18 @@ async function saveImageFile(root, input, limits) {
 		if (error instanceof AttachmentError) throw error;
 		throw new AttachmentError("Unable to persist image attachment.", "ATTACHMENT_WRITE_FAILED", { cause: error });
 	}
-	const name = displayName(input.name);
-	return {
-		attachmentId: AttachmentId(`sha256:${sha256}`),
-		...metadata,
-		...name !== void 0 ? { name } : {}
-	};
+	return prepared.ref;
+}
+/**
+* Decode and normalize one image once, then publish the prepared object.
+* @param root - absolute `NOMIX_HOME/attachments/v1` root.
+* @param input - submitted encoded bytes and declared media type.
+* @param limits - resolved source admission policy.
+* @param policy - resolved normalization policy.
+* @returns durable content-addressed normalized image reference.
+*/
+async function saveImageFile(root, input, limits, policy) {
+	return commitPreparedImageFile(root, await prepareImageFile(input, limits, policy));
 }
 /**
 * Read and verify one content-addressed image.
@@ -241,7 +502,7 @@ async function readImageFile(root, ref, signal) {
 		throw new AttachmentError("Unable to read image attachment.", "ATTACHMENT_READ_FAILED", { cause: error });
 	}
 	signal?.throwIfAborted();
-	if (digest(data) !== sha256) throw new AttachmentError("Stored attachment failed integrity verification.", "ATTACHMENT_CORRUPT");
+	if (digest$1(data) !== sha256) throw new AttachmentError("Stored attachment failed integrity verification.", "ATTACHMENT_CORRUPT");
 	const metadata = await probeImage(data);
 	signal?.throwIfAborted();
 	if (metadata.mediaType !== ref.mediaType || data.byteLength !== ref.bytes || metadata.width !== ref.width || metadata.height !== ref.height) throw new AttachmentError("Stored attachment metadata does not match its reference.", "ATTACHMENT_CORRUPT");
@@ -251,16 +512,298 @@ async function readImageFile(root, ref, signal) {
 	};
 }
 //#endregion
+//#region lib/types/request-image.js
+/** Deterministic cached image versions for model requests. */
+/** Transform version included in every cache and upload-index identity. */
+const REQUEST_IMAGE_TRANSFORM_VERSION = "request-image-v4";
+/** DeepSeek request versions normally fit at these two preferred qualities. */
+const REQUEST_IMAGE_QUALITIES = [85, 80];
+function digest(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+/**
+* Compute aspect-preserving integer dimensions within a hard total-pixel budget.
+* @param width - positive source width.
+* @param height - positive source height.
+* @param maxPixels - positive width-times-height cap.
+* @returns inward-rounded dimensions; small images are not enlarged.
+*/
+function requestImageDimensions(width, height, maxPixels) {
+	const scale = Math.min(1, Math.sqrt(maxPixels / (width * height)));
+	if (scale === 1) return {
+		width,
+		height
+	};
+	if (width >= height) {
+		let projectedWidth = Math.max(1, Math.floor(width * scale));
+		let projectedHeight = Math.max(1, Math.round(projectedWidth * height / width));
+		while (projectedWidth * projectedHeight > maxPixels && projectedWidth > 1) {
+			projectedWidth -= 1;
+			projectedHeight = Math.max(1, Math.round(projectedWidth * height / width));
+		}
+		return {
+			width: projectedWidth,
+			height: projectedHeight
+		};
+	}
+	let projectedHeight = Math.max(1, Math.floor(height * scale));
+	let projectedWidth = Math.max(1, Math.round(projectedHeight * width / height));
+	while (projectedWidth * projectedHeight > maxPixels && projectedHeight > 1) {
+		projectedHeight -= 1;
+		projectedWidth = Math.max(1, Math.round(projectedHeight * width / height));
+	}
+	return {
+		width: projectedWidth,
+		height: projectedHeight
+	};
+}
+function checkedInteger(value, name) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new AttachmentError(`${name} must be a positive integer.`, "INVALID_ATTACHMENT_REF");
+	return value;
+}
+function validatePolicy(policy) {
+	checkedInteger(policy.maxPixels, "Image request maxPixels");
+	checkedInteger(policy.maxBytes, "Image request maxBytes");
+}
+function descriptor(attachment, policy) {
+	return JSON.stringify({
+		transformVersion: REQUEST_IMAGE_TRANSFORM_VERSION,
+		attachmentId: attachment.attachmentId,
+		routePixelBudget: policy.maxPixels,
+		encodedByteBudget: policy.maxBytes,
+		encoding: {
+			png: {
+				compressionLevel: 9,
+				palette: "opaque-only"
+			},
+			webpQualities: REQUEST_IMAGE_QUALITIES,
+			jpegQualities: REQUEST_IMAGE_QUALITIES,
+			order: [
+				"low-colour:png-webp",
+				"alpha:webp",
+				"opaque:jpeg"
+			],
+			colourspace: "srgb"
+		}
+	});
+}
+/**
+* Complete deterministic identity for one attachment and route-owned request policy.
+* @param attachment - provider-independent durable normalized attachment reference.
+* @param policy - route-owned pixel and byte policy.
+* @returns branded digest over every request transform input.
+*/
+function requestImageVariantId(attachment, policy) {
+	return ImageVariantId(`sha256:${digest(descriptor(attachment, policy))}`);
+}
+function pipeline(attachment, width, height) {
+	return sourcePipeline(attachment).resize({
+		width,
+		height,
+		fit: "inside",
+		withoutEnlargement: true
+	});
+}
+function sourcePipeline(attachment) {
+	return sharp(attachment.data, {
+		failOn: "error",
+		limitInputPixels: false
+	}).toColourspace("srgb");
+}
+async function encoded(image, mediaType, quality, palette = true) {
+	const { data, info } = await (mediaType === "image/png" ? image.png({
+		compressionLevel: 9,
+		palette
+	}) : mediaType === "image/webp" ? image.webp({ quality }) : image.jpeg({ quality })).toBuffer({ resolveWithObject: true });
+	return {
+		data: new Uint8Array(data),
+		mediaType,
+		width: info.width,
+		height: info.height
+	};
+}
+function encodingAttempts(attachment, width, height, hasAlpha, lowColour) {
+	const prepared = pipeline(attachment, width, height);
+	const webp = REQUEST_IMAGE_QUALITIES.map((quality) => (() => encoded(prepared.clone(), "image/webp", quality)));
+	if (lowColour) return [() => encoded(prepared.clone(), "image/png", void 0, !hasAlpha), ...webp];
+	if (hasAlpha) return webp;
+	return REQUEST_IMAGE_QUALITIES.map((quality) => (() => encoded(prepared.clone(), "image/jpeg", quality)));
+}
+async function createRequestImage(attachment, policy, hasAlpha) {
+	let dimensions = requestImageDimensions(attachment.ref.width, attachment.ref.height, policy.maxPixels);
+	if (dimensions.width === attachment.ref.width && dimensions.height === attachment.ref.height && attachment.data.byteLength <= policy.maxBytes) return {
+		data: attachment.data,
+		mediaType: attachment.ref.mediaType,
+		width: attachment.ref.width,
+		height: attachment.ref.height
+	};
+	const lowColour = await hasLowColourCount(sourcePipeline(attachment));
+	for (;;) {
+		const encodedVersion = await encodeFirstWithinLimit(encodingAttempts(attachment, dimensions.width, dimensions.height, hasAlpha, lowColour), policy.maxBytes);
+		if (!isExhaustedEncoding(encodedVersion)) return encodedVersion;
+		if (dimensions.width === 1 && dimensions.height === 1) break;
+		const scale = Math.min(.9, Math.sqrt(policy.maxBytes / encodedVersion.smallest.data.byteLength) * .95);
+		dimensions = {
+			width: Math.max(1, Math.floor(dimensions.width * scale)),
+			height: Math.max(1, Math.floor(dimensions.height * scale))
+		};
+	}
+	throw new AttachmentError("Image cannot be encoded within the model-request byte budget.", "IMAGE_TOO_LARGE");
+}
+function cachePath(root, hash) {
+	return join(root, "request-images", hash.slice(0, 2), hash);
+}
+async function readCached(path, attachment, policy, expectedAlpha, signal) {
+	try {
+		const data = new Uint8Array(await readFile(path, { signal }));
+		const detected = await probeImage(data);
+		const maximum = requestImageDimensions(attachment.ref.width, attachment.ref.height, policy.maxPixels);
+		if (data.byteLength > policy.maxBytes || detected.depth !== "uchar" || detected.space !== "srgb" || detected.width > maximum.width || detected.height > maximum.height || !encodedAlphaIsCompatible(expectedAlpha, detected)) return void 0;
+		return {
+			data,
+			mediaType: detected.mediaType,
+			width: detected.width,
+			height: detected.height,
+			hasAlpha: detected.hasAlpha
+		};
+	} catch (error) {
+		if (error?.code === "ENOENT") return void 0;
+		signal?.throwIfAborted();
+		return;
+	}
+}
+async function verifyRequestImage(image, expectedAlpha) {
+	const detected = await detectImage(image.data);
+	if (detected.depth !== "uchar" || detected.space !== "srgb" || detected.width !== image.width || detected.height !== image.height || detected.mediaType !== image.mediaType || !encodedAlphaIsCompatible(expectedAlpha, detected)) throw new AttachmentError("Encoded model-request image does not match its verified 8-bit sRGB metadata.", "ATTACHMENT_WRITE_FAILED");
+	return {
+		...image,
+		hasAlpha: detected.hasAlpha
+	};
+}
+async function writeCached(path, data) {
+	await mkdir(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, data, {
+			mode: 384,
+			flag: "wx"
+		});
+		await rename(temporary, path);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}
+/**
+* Generate or reuse one request image below the local attachment root.
+* @param root - absolute versioned attachment storage root.
+* @param attachment - verified normalized attachment bytes and reference.
+* @param policy - exact route request-image policy.
+* @param signal - optional cancellation for cache I/O and image transformation.
+* @returns verified request bytes and deterministic variant identity.
+*/
+async function readRequestImageFile(root, attachment, policy, signal) {
+	signal?.throwIfAborted();
+	validatePolicy(policy);
+	const source = await probeImage(attachment.data);
+	const variantId = requestImageVariantId(attachment.ref, policy);
+	const path = cachePath(root, String(variantId).slice(7));
+	const cached = await readCached(path, attachment, policy, source.hasAlpha, signal);
+	const created = cached ?? await createRequestImage(attachment, policy, source.hasAlpha);
+	const version = cached ?? (created.data === attachment.data ? {
+		...created,
+		hasAlpha: source.hasAlpha
+	} : await verifyRequestImage(created, source.hasAlpha));
+	signal?.throwIfAborted();
+	if (cached === void 0 && version.data !== attachment.data) await writeCached(path, version.data);
+	return {
+		variantId,
+		attachment: attachment.ref,
+		data: version.data,
+		mediaType: version.mediaType,
+		bytes: version.data.byteLength,
+		width: version.width,
+		height: version.height,
+		depth: "uchar",
+		space: "srgb",
+		hasAlpha: version.hasAlpha
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /** Local durable attachment backend rooted below `NOMIX_HOME`. @module @nomix-ai/nomix-attachment-local */
-/** Default maximum encoded bytes for one image. */
-const DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+/** Default maximum encoded bytes for one submitted image; oversized sources are refused, not shrunk. */
+const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 /** Default maximum images in one prompt. */
 const DEFAULT_MAX_IMAGES_PER_MESSAGE = 20;
 /** Default maximum aggregate image bytes in one prompt. */
-const DEFAULT_MAX_MESSAGE_IMAGE_BYTES = 100 * 1024 * 1024;
-/** Default maximum intrinsic pixels for one image. */
-const DEFAULT_MAX_IMAGE_PIXELS = 4e7;
+const DEFAULT_MAX_MESSAGE_IMAGE_BYTES = 200 * 1024 * 1024;
+/** Default maximum intrinsic pixels for one submitted image. */
+const DEFAULT_MAX_IMAGE_PIXELS = 64e6;
+/** Default per-side pixel cap for one submitted image. */
+const DEFAULT_MAX_IMAGE_DIMENSION = 8192;
+/**
+* Default long-edge target of the stored normalized image. A larger source
+* is admitted and downscaled to this edge, so admission bounds what rides
+* every later model request without refusing ordinary large sources.
+*/
+const DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION = 2048;
+/** Default independent safety cap for one stored normalized image. */
+const DEFAULT_NORMALIZED_IMAGE_MAX_BYTES = 4 * 1024 * 1024;
+/** Conservative default number of simultaneous native image transformations per store. */
+const DEFAULT_IMAGE_COMPRESSION_CONCURRENCY = 2;
+/** Maximum configurable native image transformations per store. */
+const MAX_IMAGE_COMPRESSION_CONCURRENCY = 8;
+function abortReason(signal) {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new Error("Attachment request cancelled with a non-Error reason.", { cause: reason });
+}
+var SharedRequest = class {
+	controller = new AbortController();
+	promise;
+	settled = false;
+	waiters = 0;
+	constructor(start) {
+		this.promise = start(this.controller.signal).finally(() => {
+			this.settled = true;
+		});
+	}
+	wait(signal) {
+		signal?.throwIfAborted();
+		this.waiters += 1;
+		if (signal === void 0) return this.promise.finally(() => {
+			this.release(false);
+		});
+		let released = false;
+		const release = (cancelled) => {
+			if (released) return;
+			released = true;
+			this.release(cancelled, signal);
+		};
+		return new Promise((resolve, reject) => {
+			const abort = () => {
+				release(true);
+				reject(abortReason(signal));
+			};
+			signal.addEventListener("abort", abort, { once: true });
+			this.promise.then((value) => {
+				signal.removeEventListener("abort", abort);
+				release(false);
+				resolve(value);
+			}, (error) => {
+				signal.removeEventListener("abort", abort);
+				release(false);
+				reject(error);
+			});
+		});
+	}
+	release(cancelled, signal) {
+		this.waiters -= 1;
+		if (cancelled && this.waiters === 0 && !this.settled && signal !== void 0) this.controller.abort(abortReason(signal));
+	}
+};
 /** Persistent content-addressed local attachment store. */
 var LocalAttachmentStore = class extends AttachmentStore {
 	static Config = z.object({
@@ -268,19 +811,30 @@ var LocalAttachmentStore = class extends AttachmentStore {
 		maxImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGE_BYTES),
 		maxImagesPerMessage: z.number().step(1).min(1).default(20),
 		maxMessageImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_MESSAGE_IMAGE_BYTES),
-		maxImagePixels: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGE_PIXELS)
+		maxImagePixels: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGE_PIXELS),
+		maxImageDimension: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGE_DIMENSION),
+		normalizedImageMaxDimension: z.number().step(1).min(1).default(DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION),
+		normalizedImageMaxBytes: z.number().step(1).min(1).default(DEFAULT_NORMALIZED_IMAGE_MAX_BYTES),
+		imageCompressionConcurrency: z.number().step(1).min(1).max(8).default(2)
 	});
 	/** Absolute versioned storage root. */
 	root;
 	imageLimits;
+	/** Resolved provider-independent normalization policy. */
+	normalizationPolicy;
+	/** Resolved instance-level compression limit. */
+	imageCompressionConcurrency;
+	compression;
+	requestInflight = /* @__PURE__ */ new Map();
 	constructor(ctx, config) {
 		super(ctx);
 		this.root = resolve(join(resolveNomixHome(config.nomixHome), "attachments", "v1"));
 		this.imageLimits = Object.freeze({
-			maxImageBytes: config.maxImageBytes ?? 5242880,
+			maxImageBytes: config.maxImageBytes ?? 20971520,
 			maxImagesPerMessage: config.maxImagesPerMessage ?? 20,
-			maxMessageImageBytes: config.maxMessageImageBytes ?? 104857600,
-			maxImagePixels: config.maxImagePixels ?? 4e7,
+			maxMessageImageBytes: config.maxMessageImageBytes ?? 209715200,
+			maxImagePixels: config.maxImagePixels ?? 64e6,
+			maxImageDimension: config.maxImageDimension ?? 8192,
 			mediaTypes: Object.freeze([
 				"image/png",
 				"image/jpeg",
@@ -288,16 +842,54 @@ var LocalAttachmentStore = class extends AttachmentStore {
 				"image/gif"
 			])
 		});
+		this.normalizationPolicy = Object.freeze({
+			maxDimension: config.normalizedImageMaxDimension ?? 2048,
+			maxBytes: config.normalizedImageMaxBytes ?? 4194304
+		});
+		const compressionConcurrency = config.imageCompressionConcurrency ?? 2;
+		if (!Number.isSafeInteger(compressionConcurrency) || compressionConcurrency < 1 || compressionConcurrency > 8) throw new Error(`attachment-local: imageCompressionConcurrency must be an integer from 1 through 8`);
+		this.imageCompressionConcurrency = compressionConcurrency;
+		this.compression = new CompressionLimiter(compressionConcurrency);
 	}
 	async validateImage(input) {
-		await validateImageFile(input, this.imageLimits);
+		await this.compression.run(() => validateImageFile(input, this.imageLimits, this.normalizationPolicy));
+	}
+	async saveImages(inputs) {
+		this.validateImageBatch(inputs);
+		const prepared = await Promise.all(inputs.map((input) => this.compression.run(() => prepareImageFile(input, this.imageLimits, this.normalizationPolicy))));
+		const refs = [];
+		for (const image of prepared) refs.push(await commitPreparedImageFile(this.root, image));
+		return refs;
 	}
 	async saveImage(input) {
-		return saveImageFile(this.root, input, this.imageLimits);
+		const prepared = await this.compression.run(() => prepareImageFile(input, this.imageLimits, this.normalizationPolicy));
+		return commitPreparedImageFile(this.root, prepared);
 	}
 	async readImage(ref, signal) {
 		return readImageFile(this.root, ref, signal);
 	}
+	async readImageRequest(ref, policy, signal) {
+		return this.requestVersion(ref, policy, void 0, signal);
+	}
+	requestVersion(ref, policy, stored, signal) {
+		signal?.throwIfAborted();
+		const variantId = requestImageVariantId(ref, policy);
+		const key = String(variantId);
+		let operation = this.requestInflight.get(key);
+		if (operation?.controller.signal.aborted) {
+			this.requestInflight.delete(key);
+			operation = void 0;
+		}
+		if (operation === void 0) {
+			const shared = new SharedRequest((sharedSignal) => this.compression.run(async () => readRequestImageFile(this.root, stored ?? await this.readImage(ref, sharedSignal), policy, sharedSignal)));
+			operation = shared;
+			this.requestInflight.set(key, shared);
+			shared.promise.finally(() => {
+				if (this.requestInflight.get(key) === shared) this.requestInflight.delete(key);
+			}).catch(() => {});
+		}
+		return operation.wait(signal);
+	}
 };
 //#endregion
-export { DEFAULT_MAX_IMAGES_PER_MESSAGE, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_IMAGE_PIXELS, DEFAULT_MAX_MESSAGE_IMAGE_BYTES, LocalAttachmentStore, LocalAttachmentStore as default, detectImage, readImageFile, saveImageFile, validateImageFile };
+export { DEFAULT_IMAGE_COMPRESSION_CONCURRENCY, DEFAULT_MAX_IMAGES_PER_MESSAGE, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_IMAGE_DIMENSION, DEFAULT_MAX_IMAGE_PIXELS, DEFAULT_MAX_MESSAGE_IMAGE_BYTES, DEFAULT_NORMALIZED_IMAGE_MAX_BYTES, DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION, LocalAttachmentStore, LocalAttachmentStore as default, MAX_IMAGE_COMPRESSION_CONCURRENCY, canPassThroughNormalization, commitPreparedImageFile, normalizeImage, prepareImageFile, readImageFile, readRequestImageFile, requestImageDimensions, requestImageVariantId, saveImageFile, validateImageFile };