@nomix-ai/nomix-harness 0.2.5 → 0.2.6

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

@@ -0,0 +1,18 @@
+/** Instance-owned concurrency bound for native image transformations. */
+/** FIFO limiter for asynchronous compression work. */
+export declare class CompressionLimiter {
+    readonly concurrency: number;
+    private active;
+    private readonly waiting;
+    /**
+     * @param concurrency - positive maximum number of active tasks.
+     */
+    constructor(concurrency: number);
+    /**
+     * Run one task after an instance slot becomes available.
+     * @param task - compression operation occupying one slot until settlement.
+     * @returns the task result.
+     */
+    run<T>(task: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=compression-limiter.d.ts.map

package/dist/kernel/attachment-local/lib/types/compression-limiter.js

@@ -0,0 +1,43 @@
+/** Instance-owned concurrency bound for native image transformations. */
+/** FIFO limiter for asynchronous compression work. */
+export class CompressionLimiter {
+    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()?.();
+                };
+                void 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);
+        });
+    }
+}
+//# sourceMappingURL=compression-limiter.js.map

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

@@ -0,0 +1,23 @@
+/** Shared lazy candidate execution for normalization and request-image encoders. */
+/** One encoded candidate carrying its complete bytes. */
+export interface EncodedCandidate {
+    data: Uint8Array;
+}
+/** Result of exhausting candidates at one raster size without a fitting output. */
+export interface ExhaustedEncoding<T extends EncodedCandidate> {
+    smallest: T;
+}
+/**
+ * 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.
+ */
+export declare function encodeFirstWithinLimit<T extends EncodedCandidate>(attempts: readonly (() => Promise<T>)[], maxBytes: number): Promise<T | ExhaustedEncoding<T>>;
+/**
+ * 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.
+ */
+export declare function isExhaustedEncoding<T extends EncodedCandidate>(result: T | ExhaustedEncoding<T>): result is ExhaustedEncoding<T>;
+//# sourceMappingURL=encoding.d.ts.map

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

@@ -0,0 +1,33 @@
+/** 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.
+ */
+export async function encodeFirstWithinLimit(attempts, maxBytes) {
+    const [first, ...remaining] = attempts;
+    if (first === undefined)
+        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.
+ */
+export function isExhaustedEncoding(result) {
+    return 'smallest' in result;
+}
+//# sourceMappingURL=encoding.js.map

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

@@ -3,9 +3,31 @@ import type { ImageMediaType } from '../../../attachment/lib/index.js';
 /** Decoded metadata from a supported image. */
 export interface DetectedImage {
     mediaType: ImageMediaType;
+    /** Intrinsic width with EXIF orientation applied — the width a viewer perceives. */
     width: number;
+    /** Intrinsic height with EXIF orientation applied — the height a viewer perceives. */
     height: number;
+    /** Whether the container carries more than one frame. */
+    animated: boolean;
+    /** Whether the bytes carry descriptive metadata, a color profile, or orientation. */
+    carriesMetadata: boolean;
+    /** Sharp sample depth reported for the decoded channels. */
+    depth: string;
+    /** Sharp colour space reported for the decoded pixels. */
+    space: string;
+    /** Whether decoded pixels carry an alpha channel. */
+    hasAlpha: boolean;
 }
+/**
+ * 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.
+ */
+export declare function encodedAlphaIsCompatible(sourceHasAlpha: boolean | undefined, output: Pick<DetectedImage, 'mediaType' | 'hasAlpha'>): boolean;
 /**
  * Parse a supported raster's header and return its intrinsic metadata without
  * decoding pixels. Digest-verified reads use this: admission already proved
@@ -15,11 +37,18 @@ export interface DetectedImage {
  * @returns verified format and dimensions.
  */
 export declare function probeImage(data: Uint8Array): Promise<DetectedImage>;
+/** Admission limits applied to a decoded raster's intrinsic dimensions. */
+export interface DecodedImageLimits {
+    /** Decoded-pixel (width times height) admission limit. */
+    maxPixels?: number;
+    /** Per-side admission limit applied to width and height independently. */
+    maxDimension?: number;
+}
 /**
  * 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.
  */
-export declare function detectImage(data: Uint8Array, maxPixels?: number): Promise<DetectedImage>;
+export declare function detectImage(data: Uint8Array, limits?: DecodedImageLimits): Promise<DetectedImage>;
 //# sourceMappingURL=image.d.ts.map

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

@@ -1,19 +1,55 @@
 /** Raster inspection: full decode at admission, header-only probe on verified reads. */
 import sharp from 'sharp';
 import { AttachmentError } from '../../../attachment/lib/index.js';
+/**
+ * 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.
+ */
+export function encodedAlphaIsCompatible(sourceHasAlpha, output) {
+    return sourceHasAlpha === undefined
+        || 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 !== undefined
+        || metadata.xmp !== undefined
+        || metadata.iptc !== undefined
+        || metadata.icc !== undefined
+        || metadata.hasProfile
+        || metadata.tifftagPhotoshop !== undefined
+        || metadata.comments !== undefined
+        || metadata.orientation !== undefined;
+}
 async function imageMetadata(image) {
     const metadata = await image.metadata();
     const mediaType = MEDIA_TYPES[metadata.format];
     if (mediaType === undefined) {
         throw new AttachmentError('Unsupported or malformed image data.', 'INVALID_IMAGE');
     }
-    return { mediaType, width: metadata.width, height: metadata.height };
+    // EXIF orientations 5-8 transpose the stored raster; report the perceived
+    // axes so limits, source facts, and coordinate advice all share them.
+    const transposed = metadata.orientation !== undefined && metadata.orientation >= 5;
+    return {
+        mediaType,
+        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,
+    };
 }
 /**
  * Parse a supported raster's header and return its intrinsic metadata without
@@ -36,16 +72,19 @@ export 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.
  */
-export async function detectImage(data, maxPixels) {
+export async function detectImage(data, limits) {
     try {
         const image = sharp(data, { failOn: 'error', limitInputPixels: false });
         const detected = await imageMetadata(image);
-        if (maxPixels !== undefined && detected.width * detected.height > maxPixels) {
+        if (limits?.maxPixels !== undefined && detected.width * detected.height > limits.maxPixels) {
             throw new AttachmentError('Image exceeds the configured decoded-pixel limit.', 'IMAGE_TOO_MANY_PIXELS');
         }
+        if (limits?.maxDimension !== undefined && 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;
     }

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

@@ -2,29 +2,55 @@
 import { Context } from '../../../cordis/lib/index.js';
 import z from '../../../schemastery/lib/index.mjs';
 import { AttachmentStore } from '../../../attachment/lib/index.js';
-import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '../../../attachment/lib/index.js';
-export { detectImage } from './image.ts';
-export { readImageFile, saveImageFile, validateImageFile } from './store.ts';
-/** Default maximum encoded bytes for one image. */
+import type { ImageAttachmentLimits, ImageAttachmentRef, ImageRequestPolicy, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment } from '../../../attachment/lib/index.js';
+import type { NormalizationPolicy } from './normalization.ts';
+export { canPassThroughNormalization, normalizeImage } from './normalization.ts';
+export type { NormalizedImage, NormalizationPolicy } from './normalization.ts';
+export { commitPreparedImageFile, prepareImageFile, readImageFile, saveImageFile, validateImageFile } from './store.ts';
+export type { PreparedImageFile } from './store.ts';
+export { readRequestImageFile, requestImageDimensions, requestImageVariantId } from './request-image.ts';
+/** Default maximum encoded bytes for one submitted image; oversized sources are refused, not shrunk. */
 export declare const DEFAULT_MAX_IMAGE_BYTES: number;
 /** Default maximum images in one prompt. */
 export declare const DEFAULT_MAX_IMAGES_PER_MESSAGE = 20;
 /** Default maximum aggregate image bytes in one prompt. */
 export declare const DEFAULT_MAX_MESSAGE_IMAGE_BYTES: number;
-/** Default maximum intrinsic pixels for one image. */
-export declare const DEFAULT_MAX_IMAGE_PIXELS = 40000000;
+/** Default maximum intrinsic pixels for one submitted image. */
+export declare const DEFAULT_MAX_IMAGE_PIXELS = 64000000;
+/** Default per-side pixel cap for one submitted image. */
+export declare 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.
+ */
+export declare const DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION = 2048;
+/** Default independent safety cap for one stored normalized image. */
+export declare const DEFAULT_NORMALIZED_IMAGE_MAX_BYTES: number;
+/** Conservative default number of simultaneous native image transformations per store. */
+export declare const DEFAULT_IMAGE_COMPRESSION_CONCURRENCY = 2;
+/** Maximum configurable native image transformations per store. */
+export declare const MAX_IMAGE_COMPRESSION_CONCURRENCY = 8;
 /** Local attachment backend configuration. */
 export interface Config {
     /** Explicit harness home; omitted follows `NOMIX_HOME`, then `~/.nomix`. */
     nomixHome?: string;
-    /** Maximum encoded bytes accepted for one image. */
+    /** Maximum encoded bytes accepted for one submitted image. Default: 20 MiB. */
     maxImageBytes?: number;
-    /** Maximum image count accepted in one submitted message. */
+    /** Maximum image count accepted in one submitted message. Default: 20. */
     maxImagesPerMessage?: number;
-    /** Maximum aggregate encoded image bytes accepted in one submitted message. */
+    /** Maximum aggregate encoded image bytes accepted in one submitted message. Default: 200 MiB. */
     maxMessageImageBytes?: number;
-    /** Maximum intrinsic width multiplied by height accepted for one image. */
+    /** Maximum intrinsic width multiplied by height accepted for one submitted image. Default: 64,000,000. */
     maxImagePixels?: number;
+    /** Maximum intrinsic width and maximum intrinsic height accepted for one submitted image. Default: 8192px. */
+    maxImageDimension?: number;
+    /** Long-edge pixel cap of the stored provider-independent normalized image. */
+    normalizedImageMaxDimension?: number;
+    /** Encoded-byte safety cap of the stored provider-independent normalized image. */
+    normalizedImageMaxBytes?: number;
+    /** Maximum simultaneous normalization or request-image transformations in this service instance. */
+    imageCompressionConcurrency?: number;
 }
 /** Persistent content-addressed local attachment store. */
 export declare class LocalAttachmentStore extends AttachmentStore {
@@ -32,10 +58,19 @@ export declare class LocalAttachmentStore extends AttachmentStore {
     /** Absolute versioned storage root. */
     readonly root: string;
     readonly imageLimits: ImageAttachmentLimits;
+    /** Resolved provider-independent normalization policy. */
+    readonly normalizationPolicy: Readonly<NormalizationPolicy>;
+    /** Resolved instance-level compression limit. */
+    readonly imageCompressionConcurrency: number;
+    private readonly compression;
+    private readonly requestInflight;
     constructor(ctx: Context, config: Config);
     validateImage(input: SaveImageAttachment): Promise<void>;
+    saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
     saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
     readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+    readImageRequest(ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?: AbortSignal): Promise<RequestImageAttachment>;
+    private requestVersion;
 }
 export default LocalAttachmentStore;
 //# sourceMappingURL=index.d.ts.map

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

@@ -3,17 +3,91 @@ import { join, resolve } from 'node:path';
 import z from '../../../schemastery/lib/index.mjs';
 import { AttachmentStore } from '../../../attachment/lib/index.js';
 import { resolveNomixHome } from '../../../home-paths/lib/index.js';
-import { readImageFile, saveImageFile, validateImageFile } from "./store.js";
-export { detectImage } from "./image.js";
-export { readImageFile, saveImageFile, validateImageFile } from "./store.js";
-/** Default maximum encoded bytes for one image. */
-export const DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+import { CompressionLimiter } from "./compression-limiter.js";
+import { commitPreparedImageFile, prepareImageFile, readImageFile, validateImageFile } from "./store.js";
+import { readRequestImageFile, requestImageVariantId } from "./request-image.js";
+export { canPassThroughNormalization, normalizeImage } from "./normalization.js";
+export { commitPreparedImageFile, prepareImageFile, readImageFile, saveImageFile, validateImageFile } from "./store.js";
+export { readRequestImageFile, requestImageDimensions, requestImageVariantId } from "./request-image.js";
+/** Default maximum encoded bytes for one submitted image; oversized sources are refused, not shrunk. */
+export const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 /** Default maximum images in one prompt. */
 export const DEFAULT_MAX_IMAGES_PER_MESSAGE = 20;
 /** Default maximum aggregate image bytes in one prompt. */
-export const DEFAULT_MAX_MESSAGE_IMAGE_BYTES = 100 * 1024 * 1024;
-/** Default maximum intrinsic pixels for one image. */
-export const DEFAULT_MAX_IMAGE_PIXELS = 40_000_000;
+export const DEFAULT_MAX_MESSAGE_IMAGE_BYTES = 200 * 1024 * 1024;
+/** Default maximum intrinsic pixels for one submitted image. */
+export const DEFAULT_MAX_IMAGE_PIXELS = 64_000_000;
+/** Default per-side pixel cap for one submitted image. */
+export 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.
+ */
+export const DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION = 2048;
+/** Default independent safety cap for one stored normalized image. */
+export const DEFAULT_NORMALIZED_IMAGE_MAX_BYTES = 4 * 1024 * 1024;
+/** Conservative default number of simultaneous native image transformations per store. */
+export const DEFAULT_IMAGE_COMPRESSION_CONCURRENCY = 2;
+/** Maximum configurable native image transformations per store. */
+export 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 });
+}
+class SharedRequest {
+    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 === undefined) {
+            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 });
+            void this.promise.then((value) => {
+                signal.removeEventListener('abort', abort);
+                release(false);
+                resolve(value);
+            }, (error) => {
+                signal.removeEventListener('abort', abort);
+                release(false);
+                // CompressionLimiter normalizes task rejections before this handler.
+                // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+                reject(error);
+            });
+        });
+    }
+    release(cancelled, signal) {
+        this.waiters -= 1;
+        if (cancelled && this.waiters === 0 && !this.settled && signal !== undefined) {
+            this.controller.abort(abortReason(signal));
+        }
+    }
+}
 /** Persistent content-addressed local attachment store. */
 export class LocalAttachmentStore extends AttachmentStore {
     static Config = z.object({
@@ -22,10 +96,21 @@ export class LocalAttachmentStore extends AttachmentStore {
         maxImagesPerMessage: z.number().step(1).min(1).default(DEFAULT_MAX_IMAGES_PER_MESSAGE),
         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),
+        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(MAX_IMAGE_COMPRESSION_CONCURRENCY)
+            .default(DEFAULT_IMAGE_COMPRESSION_CONCURRENCY),
     });
     /** Absolute versioned storage root. */
     root;
     imageLimits;
+    /** Resolved provider-independent normalization policy. */
+    normalizationPolicy;
+    /** Resolved instance-level compression limit. */
+    imageCompressionConcurrency;
+    compression;
+    requestInflight = new Map();
     constructor(ctx, config) {
         super(ctx);
         this.root = resolve(join(resolveNomixHome(config.nomixHome), 'attachments', 'v1'));
@@ -34,18 +119,63 @@ export class LocalAttachmentStore extends AttachmentStore {
             maxImagesPerMessage: config.maxImagesPerMessage ?? DEFAULT_MAX_IMAGES_PER_MESSAGE,
             maxMessageImageBytes: config.maxMessageImageBytes ?? DEFAULT_MAX_MESSAGE_IMAGE_BYTES,
             maxImagePixels: config.maxImagePixels ?? DEFAULT_MAX_IMAGE_PIXELS,
+            maxImageDimension: config.maxImageDimension ?? DEFAULT_MAX_IMAGE_DIMENSION,
             mediaTypes: Object.freeze(['image/png', 'image/jpeg', 'image/webp', 'image/gif']),
         });
+        this.normalizationPolicy = Object.freeze({
+            maxDimension: config.normalizedImageMaxDimension ?? DEFAULT_NORMALIZED_IMAGE_MAX_DIMENSION,
+            maxBytes: config.normalizedImageMaxBytes ?? DEFAULT_NORMALIZED_IMAGE_MAX_BYTES,
+        });
+        const compressionConcurrency = config.imageCompressionConcurrency ?? DEFAULT_IMAGE_COMPRESSION_CONCURRENCY;
+        if (!Number.isSafeInteger(compressionConcurrency)
+            || compressionConcurrency < 1
+            || compressionConcurrency > MAX_IMAGE_COMPRESSION_CONCURRENCY) {
+            throw new Error(`attachment-local: imageCompressionConcurrency must be an integer from 1 through ${MAX_IMAGE_COMPRESSION_CONCURRENCY}`);
+        }
+        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, undefined, 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 = undefined;
+        }
+        if (operation === undefined) {
+            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);
+            void shared.promise.finally(() => {
+                if (this.requestInflight.get(key) === shared)
+                    this.requestInflight.delete(key);
+            }).catch(() => { });
+        }
+        return operation.wait(signal);
+    }
 }
 export default LocalAttachmentStore;
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,44 @@
+/** Deterministic provider-independent image normalization. */
+import { type Sharp } from 'sharp';
+import type { ImageMediaType } from '../../../attachment/lib/index.js';
+import type { DetectedImage } from './image.ts';
+/** Deployment-resolved policy for the persisted normalized attachment. */
+export interface NormalizationPolicy {
+    /** Long-edge cap in pixels; larger sources are downscaled proportionally. */
+    maxDimension: number;
+    /** Independent safety cap for encoded normalized image bytes. */
+    maxBytes: number;
+}
+/** Normalized bytes beside the facts recorded by a durable reference. */
+export interface NormalizedImage {
+    data: Uint8Array;
+    mediaType: ImageMediaType;
+    width: number;
+    height: number;
+}
+/**
+ * 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 declare function canPassThroughNormalization(detected: DetectedImage, bytes: number, policy: NormalizationPolicy): boolean;
+/**
+ * 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 declare function hasLowColourCount(pipeline: Sharp): Promise<boolean>;
+/**
+ * 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 declare function normalizeImage(data: Uint8Array, detected: DetectedImage, policy: NormalizationPolicy): Promise<NormalizedImage>;
+//# sourceMappingURL=normalization.d.ts.map