@xrkseek/harness-cli 0.0.11 → 0.1.0

package/node_modules/@xrkseek/attachment-local/dist/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 } from '@xrkseek/attachment';
+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 `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/node_modules/@xrkseek/attachment-local/dist/request-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-image.js","sourceRoot":"","sources":["../src/request-image.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/attachment-local/dist/store.d.ts

@@ -0,0 +1,58 @@
+/** Content-addressed, owner-private local attachment storage. */
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@xrkseek/attachment';
+import type { NormalizationPolicy } from './normalization.js';
+/**
+ * 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 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, 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;
+}
+/**
+ * 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 `DSH_HOME/attachments/v1` root.
+ * @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 `DSH_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, policy: NormalizationPolicy): Promise<ImageAttachmentRef>;
+/**
+ * Read and verify one content-addressed image.
+ * @param root - absolute `DSH_HOME/attachments/v1` root.
+ * @param ref - reference recorded in the session log.
+ * @param signal - optional cancellation for filesystem and verification work.
+ * @returns verified bytes and reference.
+ * @throws the signal reason when aborted, or an AttachmentError when verification fails.
+ */
+export declare function readImageFile(root: string, ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+/**
+ * Read by opaque attachment id when session metadata is not available.
+ */
+export declare function readImageByAttachmentId(root: string, attachmentId: string, signal?: AbortSignal): Promise<StoredImageAttachment>;
+//# sourceMappingURL=store.d.ts.map

package/node_modules/@xrkseek/attachment-local/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAOjE,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AA+C7D;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,IAAI,EAAE,UAAU,CAAA;IAChB,iDAAiD;IACjD,GAAG,EAAE,kBAAkB,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAqB5B;AA6DD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAuD7B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,kBAAkB,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,qBAAqB,CAAC,CAwChC"}

package/node_modules/@xrkseek/attachment-local/dist/store.js

@@ -0,0 +1,290 @@
+/** Content-addressed, owner-private local attachment storage. */
+import { createHash, randomUUID } from 'node:crypto';
+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 } from '@xrkseek/attachment';
+import { normalizeImage } from './normalization.js';
+import { detectImage, probeImage } from './image.js';
+const ID_PATTERN = /^sha256:([a-f0-9]{64})$/;
+const durableHomes = new Set();
+function digest(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function displayName(value) {
+    if (value === undefined)
+        return undefined;
+    // Strip both separator styles by hand: a POSIX host treats `\` as an
+    // ordinary character, so path.basename would keep a Windows client's full
+    // local path and leak it into the reference and the session log.
+    const leaf = value.slice(Math.max(value.lastIndexOf('/'), value.lastIndexOf('\\')) + 1);
+    const clean = leaf.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 255);
+    return clean === '' ? undefined : clean;
+}
+function objectPath(root, sha256) {
+    return join(root, 'objects', sha256.slice(0, 2), sha256);
+}
+function ensureReference(ref) {
+    const match = ID_PATTERN.exec(String(ref.attachmentId));
+    if (match?.[1] === undefined)
+        throw new AttachmentError('Attachment reference is invalid.', 'INVALID_ATTACHMENT_REF');
+    return match[1];
+}
+async function inspectMetadata(data, declaredMediaType, limits) {
+    if (data.byteLength === 0)
+        throw new AttachmentError('Image is empty.', 'INVALID_IMAGE');
+    const detected = await detectImage(data, {
+        maxPixels: limits.maxImagePixels,
+        ...(limits.maxImageDimension !== undefined
+            ? { maxDimension: limits.maxImageDimension }
+            : {}),
+    });
+    if (detected.mediaType !== declaredMediaType)
+        throw new AttachmentError('Declared image type does not match its bytes.', 'IMAGE_TYPE_MISMATCH');
+    return detected;
+}
+/**
+ * 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 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, 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');
+    }
+    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: `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).
+ * A synced file alone does not survive a crash when its directory entry never
+ * reached storage, so the publication directory is synced before a durable
+ * reference is reported.
+ */
+async function syncDirectory(path) {
+    /* v8 ignore next -- Windows cannot open directory handles; NTFS metadata journaling owns entry durability there. */
+    if (process.platform === 'win32')
+        return;
+    /* v8 ignore start -- Windows cannot exercise directory fsync; POSIX behavior tests enforce this peer. */
+    const handle = await open(path, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    /* v8 ignore stop */
+}
+/**
+ * Create one private directory tree and persist every ancestor entry up to a
+ * caller-vouched durable boundary. The walk deliberately ignores what mkdir
+ * reports as newly created: a concurrent first save can create a level this
+ * process then merely observes, so "already existed" is not "already durable"
+ * �?the entry may still be unsynced in the creator, and a crash would drop a
+ * directory the session checkpoint already references. Re-syncing a durable
+ * entry is harmless; skipping an unsynced one is not.
+ * @param path - absolute directory to create.
+ * @param boundary - absolute ancestor the caller vouches is already durable.
+ */
+async function ensureDurableDirectory(path, boundary) {
+    const target = resolve(path);
+    const stop = resolve(boundary);
+    await mkdir(target, { recursive: true, mode: 0o700 });
+    await chmod(target, 0o700);
+    let level = target;
+    while (level !== stop) {
+        const parent = dirname(level);
+        await syncDirectory(parent);
+        /* v8 ignore next -- filesystem-root guard: callers pass a boundary that is an ancestor of path, so the walk reaches it first. */
+        if (parent === level)
+            return;
+        level = parent;
+    }
+}
+/**
+ * Establish this process's proof that one DSH_HOME entry and every ancestor
+ * below the filesystem root are durable. Mere existence is insufficient: a
+ * concurrent process may have created the directory but not synced its parent.
+ */
+async function ensureDurableHome(path) {
+    const home = resolve(path);
+    if (!durableHomes.has(home)) {
+        await ensureDurableDirectory(home, parse(home).root);
+        durableHomes.add(home);
+    }
+    return home;
+}
+/**
+ * Publish one already verified normalized image below a versioned attachment root.
+ * @param root - absolute `DSH_HOME/attachments/v1` root.
+ * @param prepared - deterministic normalized bytes and reference.
+ * @returns durable content-addressed normalized image reference.
+ */
+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 DSH_HOME itself against the filesystem root once per process.
+    // Every process performs that proof independently, so observing a directory
+    // another process created can never be mistaken for durable publication.
+    const boundary = await ensureDurableHome(dirname(dirname(resolve(root))));
+    await ensureDurableDirectory(bucket, boundary);
+    await ensureDurableDirectory(staging, boundary);
+    const temporary = join(staging, randomUUID());
+    const target = objectPath(root, sha256);
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        await handle.writeFile(normalized);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        try {
+            await link(temporary, target);
+        }
+        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;
+            const existing = new Uint8Array(await readFile(target));
+            if (digest(existing) !== sha256)
+                throw new AttachmentError('Stored attachment failed integrity verification.', 'ATTACHMENT_CORRUPT');
+        }
+        // Persist the target entry and close a concurrent bucket-creation window
+        // before the reference can reach a session checkpoint. The dedup path
+        // repeats both syncs because it may observe another writer's link before
+        // that writer reaches its own durability boundary.
+        await syncDirectory(bucket);
+        await syncDirectory(join(root, 'objects'));
+        await unlink(temporary);
+    }
+    catch (error) {
+        /* v8 ignore next -- A descriptor can remain open only when the underlying write/sync/close operation fails. */
+        if (handle !== undefined)
+            await handle.close().catch(
+            /* v8 ignore next -- Close failure is superseded by the storage operation that entered cleanup. */
+            () => { });
+        await unlink(temporary).catch(
+        /* v8 ignore next -- The callback requires a second independent staging-unlink failure. */
+        (cleanupError) => {
+            /* v8 ignore next -- Cleanup is best-effort only for a staging file already removed by a failed operation. */
+            if (!(cleanupError instanceof Error && 'code' in cleanupError && cleanupError.code === 'ENOENT'))
+                throw cleanupError;
+        });
+        if (error instanceof AttachmentError)
+            throw error;
+        throw new AttachmentError('Unable to persist image attachment.', 'ATTACHMENT_WRITE_FAILED', { cause: error });
+    }
+    return prepared.ref;
+}
+/**
+ * Decode and normalize one image once, then publish the prepared object.
+ * @param root - absolute `DSH_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.
+ * @param root - absolute `DSH_HOME/attachments/v1` root.
+ * @param ref - reference recorded in the session log.
+ * @param signal - optional cancellation for filesystem and verification work.
+ * @returns verified bytes and reference.
+ * @throws the signal reason when aborted, or an AttachmentError when verification fails.
+ */
+export async function readImageFile(root, ref, signal) {
+    signal?.throwIfAborted();
+    const sha256 = ensureReference(ref);
+    let data;
+    try {
+        data = new Uint8Array(await readFile(objectPath(root, sha256), { signal }));
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            throw new AttachmentError('Attachment object is missing.', 'ATTACHMENT_NOT_FOUND');
+        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');
+    // The digest proves these are the exact bytes admission fully decoded, so
+    // the read path only re-derives the header fields (no raster decode, no
+    // per-request pixel amplification on history replay).
+    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');
+    }
+    return { ref, data };
+}
+/**
+ * Read by opaque attachment id when session metadata is not available.
+ */
+export async function readImageByAttachmentId(root, attachmentId, signal) {
+    const match = ID_PATTERN.exec(attachmentId);
+    if (match?.[1] === undefined) {
+        throw new AttachmentError("Attachment reference is invalid.", "INVALID_ATTACHMENT_REF");
+    }
+    let data;
+    try {
+        data = new Uint8Array(await readFile(objectPath(root, match[1]), { signal }));
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new AttachmentError("Attachment object is missing.", "ATTACHMENT_NOT_FOUND");
+        }
+        throw new AttachmentError("Unable to read image attachment.", "ATTACHMENT_READ_FAILED", { cause: error });
+    }
+    const metadata = await probeImage(data);
+    const ref = {
+        attachmentId,
+        mediaType: metadata.mediaType,
+        bytes: data.byteLength,
+        width: metadata.width,
+        height: metadata.height,
+    };
+    return readImageFile(root, ref, signal);
+}
+//# sourceMappingURL=store.js.map

package/node_modules/@xrkseek/attachment-local/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/attachment-local/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@xrkseek/attachment-local",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "dependencies": {
+    "@xrkseek/attachment": "workspace:*",
+    "@xrkseek/protocol": "workspace:*",
+    "sharp": "^0.35.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xrkseek/XRK-harness.git",
+    "directory": "packages/attachment-local"
+  },
+  "private": true
+}

package/node_modules/@xrkseek/exec-fs/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { ToolDefinition } from "@xrkseek/core-tools";
 import { type FsGlobOptions, type FsGrepHit, type FsGrepOptions } from "./search.js";
 export { PathEscapeError, resolveWithinRoot } from "./paths.js";
+export { createReadImageTool, formatImageReadOutput, imageMediaTypeForPath, type CreateReadImageToolOptions, type ImageReadValue, type ReadImageFs, } from "./read-image.js";
 export { globToRegExp, matchGlob, type FsGlobOptions, type FsGrepHit, type FsGrepOptions, } from "./search.js";
 export { langFromPath, presentEditCall, presentEditResult, presentGlobCall, presentGlobResult, presentGrepCall, presentGrepResult, presentReadCall, presentReadResult, presentWriteCall, presentWriteResult, } from "./present.js";
 export declare class EditWithoutOldError extends Error {
@@ -24,6 +25,8 @@ export interface FsService {
     readonly root: string;
     resolvePath(userPath: string): string;
     read(userPath: string, maxBytes?: number): Promise<FsReadResult>;
+    /** Read raw bytes (binary files, images). */
+    readBytes(userPath: string, maxBytes?: number): Promise<Uint8Array>;
     write(userPath: string, content: string): Promise<void>;
     /** Replace only when on-disk content matches `oldContent`. */
     edit(userPath: string, oldContent: string, newContent: string): Promise<void>;