@stackstackstack/dsh-attachment-local 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/attachment/attachment-local/README.md
+README.md: 0fe265bd50ca78e574e36f8145778d439b33f70e
+README.zh.md: b482c6ae6b6586d24d29f3281d86d33892f658be

package/README.md

@@ -0,0 +1,21 @@
+# @stackstackstack/dsh-attachment-local
+
+English | [中文](README.zh.md)
+
+The private local implementation of [`@stackstackstack/dsh-attachment`](../attachment). Objects land at `<DSH_HOME>/attachments/v1/objects/<sha256-prefix>/<sha256>` and are addressed by an opaque `sha256:` id. Each process proves a home durable once by syncing every ancestor entry to the filesystem root, so a directory another process created but has not yet synced is never mistaken for a safe boundary. Writes then use a private staging directory, owner-only files, a synced temporary file, an atomic exclusive hard-link publish, and directory syncs on the publication path (POSIX; Windows relies on filesystem metadata journaling) so the reported reference survives a crash. Write admission and reads fully decode the raster before accepting its format and dimensions; reads also re-check the digest and logged metadata. Byte and pixel limits are write-time admission policy, so a later policy reduction does not make already-admitted history unreadable.
+
+`DSH_HOME` resolves through the shared path policy: explicit config, `$DSH_HOME`, then `~/.dsh`. Session logs contain only the reference and verified metadata, never this host path. `readImage` forwards optional cancellation into the filesystem read, observes it around verification, and preserves it instead of wrapping it as `ATTACHMENT_READ_FAILED`.
+
+## Model Experience
+
+Indirectly, through durable replay of historical user images and structured model image output after restart and fork.
+
+#### KV Cache effect
+
+None beyond the image block owned by the requesting adapter.
+
+## Known Limitations and Deferred Work
+
+- Objects are retained indefinitely; reference-aware garbage collection is deferred.
+- The local backend assumes the host and provider adapter share this filesystem service.
+- Animated GIF metadata is validated from the logical screen; frame-level decoding policy is provider-owned.

package/README.zh.md

@@ -0,0 +1,21 @@
+# @stackstackstack/dsh-attachment-local
+
+[English](README.md) | 中文
+
+这是 [`@stackstackstack/dsh-attachment`](../attachment) 的私有本地实现。对象存放在 `<DSH_HOME>/attachments/v1/objects/<sha256-prefix>/<sha256>`，并通过不透明的 `sha256:` 标识符寻址。每个进程都会通过将每个祖先目录项逐级同步到文件系统根目录，为某个 home 一次性证明其持久性，因此绝不会把另一个进程已经创建但尚未同步的目录误认为安全边界。随后，写入过程使用私有暂存目录、仅所有者可访问的文件、经过同步的临时文件、原子且排他的硬链接发布，并对发布路径执行目录同步（适用于 POSIX；Windows 依赖文件系统元数据日志），确保已报告的引用能够在崩溃后继续存在。写入准入与读取都会完整解码光栅图片，之后才接受其格式和尺寸；读取还会重新校验摘要和已记录的元数据。字节和像素限制属于写入时的准入策略，因此后续收紧限制不会导致已经接纳的历史记录变得不可读。
+
+`DSH_HOME` 按共享路径策略解析：显式配置、`$DSH_HOME`，最后是 `~/.dsh`。会话日志只包含引用和经过校验的元数据，绝不包含这个宿主路径。`readImage` 会把可选取消信号传入文件系统读取、在校验前后观察该信号，并保留取消语义，而不会将其包装成 `ATTACHMENT_READ_FAILED`。
+
+## 模型体验
+
+该包通过重启和 fork 后对历史用户图片与结构化模型图片输出的持久回放间接影响模型。
+
+#### KV 缓存影响
+
+除发起请求的适配器所持有的图片块外，不产生其他影响。
+
+## 已知限制与待完成工作
+
+- 对象会无限期保留；基于引用的垃圾回收尚未实现。
+- 本地后端假定宿主与提供方适配器共享同一个文件系统服务。
+- 动态 GIF 的元数据根据逻辑屏幕进行校验；逐帧解码策略由提供方持有。

package/lib/index.js

@@ -0,0 +1,303 @@
+import { dirname, join, parse, resolve } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { AttachmentError, AttachmentId, AttachmentStore } from "@stackstackstack/dsh-attachment";
+import { resolveDshHome } from "@stackstackstack/dsh-home-paths";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, link, mkdir, open, readFile, unlink } from "node:fs/promises";
+import sharp from "sharp";
+//#region lib/types/image.js
+/** Raster inspection: full decode at admission, header-only probe on verified reads. */
+const MEDIA_TYPES = {
+	png: "image/png",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	gif: "image/gif"
+};
+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");
+	return {
+		mediaType,
+		width: metadata.width,
+		height: metadata.height
+	};
+}
+/**
+* Parse a supported raster's header and return its intrinsic metadata without
+* decoding pixels. Digest-verified reads use this: admission already proved
+* that these exact bytes decode completely, so the read path only re-derives
+* the reference fields instead of paying the full-raster decode again.
+* @param data - complete encoded image bytes.
+* @returns verified format and dimensions.
+*/
+async function probeImage(data) {
+	try {
+		return await imageMetadata(sharp(data, {
+			failOn: "error",
+			limitInputPixels: false
+		}));
+	} catch (error) {
+		if (error instanceof AttachmentError) throw error;
+		throw new AttachmentError("Unsupported or malformed image data.", "INVALID_IMAGE", { cause: error });
+	}
+}
+/**
+* Fully decode a supported raster and return its intrinsic metadata.
+* @param data - complete encoded image bytes.
+* @param maxPixels - decoded-pixel admission limit.
+* @returns verified format and dimensions.
+*/
+async function detectImage(data, maxPixels) {
+	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");
+		await image.raw().toBuffer();
+		return detected;
+	} catch (error) {
+		if (error instanceof AttachmentError) throw error;
+		throw new AttachmentError("Unsupported or malformed image data.", "INVALID_IMAGE", { cause: error });
+	}
+}
+//#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) {
+	return createHash("sha256").update(data).digest("hex");
+}
+function displayName(value) {
+	if (value === void 0) return void 0;
+	const clean = value.slice(Math.max(value.lastIndexOf("/"), value.lastIndexOf("\\")) + 1).replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, 255);
+	return clean === "" ? void 0 : 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] === void 0) throw new AttachmentError("Attachment reference is invalid.", "INVALID_ATTACHMENT_REF");
+	return match[1];
+}
+async function inspectMetadata(data, declaredMediaType, maxPixels) {
+	if (data.byteLength === 0) throw new AttachmentError("Image is empty.", "INVALID_IMAGE");
+	const detected = await detectImage(data, maxPixels);
+	if (detected.mediaType !== declaredMediaType) throw new AttachmentError("Declared image type does not match its bytes.", "IMAGE_TYPE_MISMATCH");
+	return {
+		...detected,
+		bytes: data.byteLength
+	};
+}
+/**
+* Run the full admission policy for one image without touching storage.
+* @param input - encoded bytes and declared metadata.
+* @param limits - resolved storage policy.
+* @returns completion after the encoded raster has been fully decoded.
+*/
+async function validateImageFile(input, limits) {
+	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);
+}
+/**
+* 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: 448
+	});
+	await chmod(target, 448);
+	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;
+}
+/**
+* Save and verify immutable image bytes below a versioned attachment root.
+* @param root - absolute `DSH_HOME/attachments/v1` root.
+* @param input - encoded bytes and declared metadata.
+* @param limits - resolved storage policy.
+* @returns durable content-addressed 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);
+	const bucket = join(root, "objects", sha256.slice(0, 2));
+	const staging = join(root, "tmp");
+	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, 384);
+		await handle.writeFile(input.data);
+		await handle.sync();
+		await handle.close();
+		handle = void 0;
+		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;
+			if (digest(new Uint8Array(await readFile(target))) !== sha256) throw new AttachmentError("Stored attachment failed integrity verification.", "ATTACHMENT_CORRUPT");
+		}
+		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 !== void 0) 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 });
+	}
+	const name = displayName(input.name);
+	return {
+		attachmentId: AttachmentId(`sha256:${sha256}`),
+		...metadata,
+		...name !== void 0 ? { name } : {}
+	};
+}
+/**
+* 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.
+*/
+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");
+	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
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Local durable attachment backend rooted below `DSH_HOME`. @module @stackstackstack/dsh-attachment-local */
+/** Default maximum encoded bytes for one image. */
+const DEFAULT_MAX_IMAGE_BYTES = 5 * 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;
+/** Persistent content-addressed local attachment store. */
+var LocalAttachmentStore = class extends AttachmentStore {
+	static Config = z.object({
+		dshHome: z.string(),
+		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)
+	});
+	/** Absolute versioned storage root. */
+	root;
+	imageLimits;
+	constructor(ctx, config) {
+		super(ctx);
+		this.root = resolve(join(resolveDshHome(config.dshHome), "attachments", "v1"));
+		this.imageLimits = Object.freeze({
+			maxImageBytes: config.maxImageBytes ?? 5242880,
+			maxImagesPerMessage: config.maxImagesPerMessage ?? 20,
+			maxMessageImageBytes: config.maxMessageImageBytes ?? 104857600,
+			maxImagePixels: config.maxImagePixels ?? 4e7,
+			mediaTypes: Object.freeze([
+				"image/png",
+				"image/jpeg",
+				"image/webp",
+				"image/gif"
+			])
+		});
+	}
+	async validateImage(input) {
+		await validateImageFile(input, this.imageLimits);
+	}
+	async saveImage(input) {
+		return saveImageFile(this.root, input, this.imageLimits);
+	}
+	async readImage(ref, signal) {
+		return readImageFile(this.root, ref, 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 };

package/lib/invariant.js

@@ -0,0 +1,19 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for `@stackstackstack/dsh-attachment-local`.
+* @module @stackstackstack/dsh-attachment-local/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-attachment-local";
+/** Cordis companion plugin name. */
+const name = "attachment-local-invariant";
+/** Services required before package ownership can be reserved. */
+const inject = ["invariants", "attachments"];
+/** No runtime invariant: immutable writes and verified reads are enforced directly at the backend boundary. */
+const install = () => {};
+/**
+* Register the package invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the registration disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/image.d.ts

@@ -0,0 +1,25 @@
+/** Raster inspection: full decode at admission, header-only probe on verified reads. */
+import type { ImageMediaType } from '@stackstackstack/dsh-attachment';
+/** Decoded metadata from a supported image. */
+export interface DetectedImage {
+    mediaType: ImageMediaType;
+    width: number;
+    height: number;
+}
+/**
+ * Parse a supported raster's header and return its intrinsic metadata without
+ * decoding pixels. Digest-verified reads use this: admission already proved
+ * that these exact bytes decode completely, so the read path only re-derives
+ * the reference fields instead of paying the full-raster decode again.
+ * @param data - complete encoded image bytes.
+ * @returns verified format and dimensions.
+ */
+export declare function probeImage(data: Uint8Array): Promise<DetectedImage>;
+/**
+ * Fully decode a supported raster and return its intrinsic metadata.
+ * @param data - complete encoded image bytes.
+ * @param maxPixels - decoded-pixel admission limit.
+ * @returns verified format and dimensions.
+ */
+export declare function detectImage(data: Uint8Array, maxPixels?: number): Promise<DetectedImage>;
+//# sourceMappingURL=image.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,41 @@
+/** Local durable attachment backend rooted below `DSH_HOME`. @module @stackstackstack/dsh-attachment-local */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { AttachmentStore } from '@stackstackstack/dsh-attachment';
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@stackstackstack/dsh-attachment';
+export { detectImage } from './image.ts';
+export { readImageFile, saveImageFile, validateImageFile } from './store.ts';
+/** Default maximum encoded bytes for one image. */
+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;
+/** Local attachment backend configuration. */
+export interface Config {
+    /** Explicit harness home; omitted follows `DSH_HOME`, then `~/.dsh`. */
+    dshHome?: string;
+    /** Maximum encoded bytes accepted for one image. */
+    maxImageBytes?: number;
+    /** Maximum image count accepted in one submitted message. */
+    maxImagesPerMessage?: number;
+    /** Maximum aggregate encoded image bytes accepted in one submitted message. */
+    maxMessageImageBytes?: number;
+    /** Maximum intrinsic width multiplied by height accepted for one image. */
+    maxImagePixels?: number;
+}
+/** Persistent content-addressed local attachment store. */
+export declare class LocalAttachmentStore extends AttachmentStore {
+    static Config: z<Config>;
+    /** Absolute versioned storage root. */
+    readonly root: string;
+    readonly imageLimits: ImageAttachmentLimits;
+    constructor(ctx: Context, config: Config);
+    validateImage(input: SaveImageAttachment): Promise<void>;
+    saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
+    readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+}
+export default LocalAttachmentStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/** Package-owned invariant companion for `@stackstackstack/dsh-attachment-local`.
+ * @module @stackstackstack/dsh-attachment-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "attachment-local-invariant";
+/** Services required before package ownership can be reserved. */
+export declare const inject: string[];
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the registration disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/store.d.ts

@@ -0,0 +1,27 @@
+/** Content-addressed, owner-private local attachment storage. */
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@stackstackstack/dsh-attachment';
+/**
+ * Run the full admission policy for one image without touching storage.
+ * @param input - encoded bytes and declared metadata.
+ * @param limits - resolved storage policy.
+ * @returns completion after the encoded raster has been fully decoded.
+ */
+export declare function validateImageFile(input: SaveImageAttachment, limits: ImageAttachmentLimits): Promise<void>;
+/**
+ * Save and verify immutable image bytes below a versioned attachment root.
+ * @param root - absolute `DSH_HOME/attachments/v1` root.
+ * @param input - encoded bytes and declared metadata.
+ * @param limits - resolved storage policy.
+ * @returns durable content-addressed reference.
+ */
+export declare function saveImageFile(root: string, input: SaveImageAttachment, limits: ImageAttachmentLimits): 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>;
+//# sourceMappingURL=store.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stackstackstack/dsh-attachment-local",
+  "description": "Private content-addressed DSH_HOME attachment storage",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/attachment/attachment-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-attachment": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-home-paths": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "sharp": "^0.35.3",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-attachment": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-home-paths": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}