@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/attachment-local/lib/types/normalization.js

@@ -0,0 +1,148 @@
+/** Deterministic provider-independent image normalization. */
+import sharp from 'sharp';
+import { AttachmentError } from '../../../attachment/lib/index.js';
+import { encodeFirstWithinLimit, isExhaustedEncoding } from "./encoding.js";
+import { detectImage, encodedAlphaIsCompatible } from "./image.js";
+const NORMALIZATION_QUALITIES = [85, 80, 75];
+const LOW_COLOUR_SAMPLE_EDGE = 128;
+const LOW_COLOUR_LIMIT = 256;
+const MIN_SCALE_STEP = 0.9;
+/** Encode one prepared pipeline and report exact output facts. */
+async function encode(pipeline, mediaType, quality, palette = true) {
+    const encoded = mediaType === 'image/png'
+        ? pipeline.png({ compressionLevel: 9, palette })
+        : mediaType === 'image/webp'
+            ? pipeline.webp({ quality })
+            : pipeline.jpeg({ quality });
+    const { data, info } = await encoded.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.
+ */
+export 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.
+ */
+export 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 = 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', undefined, !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.
+ */
+export 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 classificationPipeline = sharp(data, { failOn: 'error', limitInputPixels: false })
+            .rotate()
+            .toColourspace('srgb');
+        const lowColour = await hasLowColourCount(classificationPipeline);
+        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' ? undefined : detected.hasAlpha);
+            }
+            if (width === 1 && height === 1)
+                break;
+            const sizeScale = Math.sqrt(policy.maxBytes / encoded.smallest.data.byteLength) * 0.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;
+        const source = detected.mediaType === 'image/png' && detected.depth !== 'uchar'
+            ? `${detected.depth === 'ushort' ? '16-bit' : detected.depth} PNG`
+            : `${detected.depth} ${detected.mediaType.slice('image/'.length).toUpperCase()}`;
+        throw new AttachmentError(`The ${source} 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');
+}
+//# sourceMappingURL=normalization.js.map

package/dist/kernel/attachment-local/lib/types/request-image.d.ts

@@ -0,0 +1,35 @@
+/** Deterministic cached image versions for model requests. */
+import { ImageVariantId } from '../../../attachment/lib/index.js';
+import type { ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, StoredImageAttachment } from '../../../attachment/lib/index.js';
+/** Transform version included in every cache and upload-index identity. */
+export declare const REQUEST_IMAGE_TRANSFORM_VERSION = "request-image-v4";
+/** DeepSeek request versions normally fit at these two preferred qualities. */
+export declare const REQUEST_IMAGE_QUALITIES: readonly [85, 80];
+/**
+ * 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.
+ */
+export declare function requestImageDimensions(width: number, height: number, maxPixels: number): {
+    width: number;
+    height: number;
+};
+/**
+ * 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.
+ */
+export declare function requestImageVariantId(attachment: ImageAttachmentRef, policy: ImageRequestPolicy): ReturnType<typeof ImageVariantId>;
+/**
+ * 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.
+ */
+export declare function readRequestImageFile(root: string, attachment: StoredImageAttachment, policy: ImageRequestPolicy, signal?: AbortSignal): Promise<RequestImageAttachment>;
+//# sourceMappingURL=request-image.d.ts.map

package/dist/kernel/attachment-local/lib/types/request-image.js

@@ -0,0 +1,208 @@
+/** Deterministic cached image versions for model requests. */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import sharp from 'sharp';
+import { AttachmentError, ImageVariantId } from '../../../attachment/lib/index.js';
+import { hasLowColourCount } from "./normalization.js";
+import { encodeFirstWithinLimit, isExhaustedEncoding } from "./encoding.js";
+import { detectImage, encodedAlphaIsCompatible, probeImage } from "./image.js";
+/** Transform version included in every cache and upload-index identity. */
+export const REQUEST_IMAGE_TRANSFORM_VERSION = 'request-image-v4';
+/** DeepSeek request versions normally fit at these two preferred qualities. */
+export 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.
+ */
+export 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.
+ */
+export 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 output = mediaType === 'image/png'
+        ? image.png({ compressionLevel: 9, palette })
+        : mediaType === 'image/webp'
+            ? image.webp({ quality })
+            : image.jpeg({ quality });
+    const { data, info } = await output.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', undefined, !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(0.9, Math.sqrt(policy.maxBytes / encodedVersion.smallest.data.byteLength) * 0.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 undefined;
+        return { data, mediaType: detected.mediaType, width: detected.width, height: detected.height, hasAlpha: detected.hasAlpha };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return undefined;
+        signal?.throwIfAborted();
+        return undefined;
+    }
+}
+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: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, data, { mode: 0o600, 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.
+ */
+export async function readRequestImageFile(root, attachment, policy, signal) {
+    signal?.throwIfAborted();
+    validatePolicy(policy);
+    const source = await probeImage(attachment.data);
+    const variantId = requestImageVariantId(attachment.ref, policy);
+    const hash = String(variantId).slice('sha256:'.length);
+    const path = cachePath(root, hash);
+    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 === undefined && 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,
+    };
+}
+//# sourceMappingURL=request-image.js.map

package/dist/kernel/attachment-local/lib/types/store.d.ts

@@ -1,20 +1,47 @@
 /** Content-addressed, owner-private local attachment storage. */
 import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '../../../attachment/lib/index.js';
+import type { NormalizationPolicy } from './normalization.ts';
 /**
- * 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.
  */
-export declare function validateImageFile(input: SaveImageAttachment, limits: ImageAttachmentLimits): Promise<void>;
+export declare function validateImageFile(input: SaveImageAttachment, limits: ImageAttachmentLimits, policy: NormalizationPolicy): Promise<void>;
+/** Fully prepared normalized object, verified before any batch member is persisted. */
+export interface PreparedImageFile {
+    /** Deterministic normalized bytes whose digest is {@link ref.attachmentId}. */
+    data: Uint8Array;
+    /** Durable reference describing {@link data}. */
+    ref: ImageAttachmentRef;
+}
 /**
- * Save and verify immutable image bytes below a versioned attachment root.
+ * 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.
+ */
+export declare function prepareImageFile(input: SaveImageAttachment, limits: ImageAttachmentLimits, policy: NormalizationPolicy): Promise<PreparedImageFile>;
+/**
+ * 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.
+ */
+export declare function commitPreparedImageFile(root: string, prepared: PreparedImageFile): Promise<ImageAttachmentRef>;
+/**
+ * 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.
  */
-export declare function saveImageFile(root: string, input: SaveImageAttachment, limits: ImageAttachmentLimits): Promise<ImageAttachmentRef>;
+export declare function saveImageFile(root: string, input: SaveImageAttachment, limits: ImageAttachmentLimits, policy: NormalizationPolicy): Promise<ImageAttachmentRef>;
 /**
  * Read and verify one content-addressed image.
  * @param root - absolute `NOMIX_HOME/attachments/v1` root.

package/dist/kernel/attachment-local/lib/types/store.js

@@ -4,6 +4,7 @@ import { constants } from 'node:fs';
 import { chmod, link, mkdir, open, readFile, unlink } from 'node:fs/promises';
 import { dirname, join, parse, resolve } from 'node:path';
 import { AttachmentError, AttachmentId, } from '../../../attachment/lib/index.js';
+import { normalizeImage } from "./normalization.js";
 import { detectImage, probeImage } from "./image.js";
 const ID_PATTERN = /^sha256:([a-f0-9]{64})$/;
 const durableHomes = new Set();
@@ -29,25 +30,54 @@ function ensureReference(ref) {
         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.
  */
-export async function validateImageFile(input, limits) {
+export 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.
+ */
+export 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(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 !== undefined ? { name } : {}),
+            ...downscaled ? { originalDimensions: { width: detected.width, height: detected.height } } : {},
+        },
+    };
 }
 /**
  * Make a directory's entries durable (fsync on a read-only directory handle).
@@ -109,17 +139,17 @@ 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.
  */
-export 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);
+export async function commitPreparedImageFile(root, prepared) {
+    const normalized = prepared.data;
+    const sha256 = ensureReference(prepared.ref);
+    if (digest(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');
     // Establish NOMIX_HOME itself against the filesystem root once per process.
@@ -133,7 +163,7 @@ export async function saveImageFile(root, input, limits) {
     let handle;
     try {
         handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
-        await handle.writeFile(input.data);
+        await handle.writeFile(normalized);
         await handle.sync();
         await handle.close();
         handle = undefined;
@@ -173,12 +203,18 @@ export async function saveImageFile(root, input, limits) {
             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 !== undefined ? { 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.
+ */
+export async function saveImageFile(root, input, limits, policy) {
+    return commitPreparedImageFile(root, await prepareImageFile(input, limits, policy));
 }
 /**
  * Read and verify one content-addressed image.

package/dist/kernel/attachment-local/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomix-ai/nomix-attachment-local",
   "description": "Private content-addressed NOMIX_HOME attachment storage",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },