@hraness/slopcamera 3.2.4

package/apps/desktop/studio/assets/README.md

@@ -0,0 +1,39 @@
+# Retained Poly Haven assets
+
+This adapter finds free Poly Haven assets and imports an explicitly selected file set into a local studio source directory. Search and import results identify Poly Haven, retain the artists' credits, and distinguish the CC0 asset license from the API service terms.
+
+Poly Haven's current API terms permit personal and commercial use without a key or payment. API clients must identify their application and make the source of surfaced content clear. SLOPCAMERA sends `SLOPCAMERA/StudioAssets (+https://slopcamera.com)` and returns `Powered by Poly Haven`. The assets themselves remain CC0 without an attribution requirement. These terms were checked on September 9, 2026 against the [current API terms](https://raw.githubusercontent.com/Poly-Haven/Public-API/master/ToS.md), the [July 18 API announcement](https://polyhaven.com/our-api), and the [asset license](https://polyhaven.com/license).
+
+## Service interface
+
+`createPolyHavenAssetService({storageRoot, fetch?, signal?, beforePublication?})` exposes `search(input)`, `describe(assetId)`, `plan(selection)`, and `importAsset(plan)`. `storageRoot` must be an existing physical private directory, normally below `artifacts/slopcamera/generated/studio-assets`. The optional fetch and publication hooks are host-owned runtime dependencies; they never enter a retained plan.
+
+Search input is `{provider:"poly-haven",query:"warm studio",type:"hdris",limit:8}`. Types are `all`, `hdris`, `textures`, and `models`; limits are one through 20. The adapter calls the documented `/search` endpoint and fetches metadata only for those bounded results. It preserves provider result order. Similarity scores do not independently explain the hybrid ranking or prove suitability. [Official API specification](https://raw.githubusercontent.com/Poly-Haven/Public-API/master/swagger.yml)
+
+Selections require `provider`, `assetId`, `resolution`, `kind`, and `format`. `maximumTotalBytes` defaults to 50 MiB and cannot exceed 512 MiB. Supported resolutions are `1k`, `2k`, and `4k`.
+
+| Kind | Formats | Selection |
+| --- | --- | --- |
+| `hdri` | `hdr`, `exr` | One exact environment file |
+| `texture` | `png`, `jpg`, `exr` | An explicit `maps` array using catalog names such as `Diffuse`, `Rough`, and `nor_gl` |
+| `model` | `gltf` | One glTF 2.0 file and its complete catalog `include` dependencies |
+
+`describe` returns asset/author metadata and bounded provider snapshots, so an agent can inspect available variants before selecting one. Plans retain canonical snapshots, exact selected URLs, MD5 checksums, byte counts, relative paths, credits, and a SHA-256 plan identity. `parsePolyHavenAssetPlan` recomputes the entire plan from its snapshots and selection. It rejects changed counts, omitted dependencies, conflicting paths, unexpected fields, and altered provenance.
+
+## Acquisition and replay
+
+Downloads use only HTTPS `api.polyhaven.com` metadata endpoints and `dl.polyhaven.org/file/ph-assets/` asset paths. Credentials, URL fragments, query strings on asset downloads, alternate ports, redirects, and arbitrary remote URLs reject. Each file is at most 128 MiB, each complete selection is at most 64 files, and response capture checks actual streamed bytes. Requests have a bounded deadline and honor host cancellation. There are no automatic retries, uploads, credential reads, or provider charges.
+
+Import verifies catalog size and MD5, checks supported file signatures, and computes local SHA-256 identities. The shared physical storage adapter publishes each exact source file with atomic no-replace semantics. Completion is published only after the entire source closure verifies. An interrupted import can reuse already verified files; a completed import rechecks all retained files and its receipt without network access. Conflicting bytes or undeclared files reject rather than being replaced.
+
+Exact download stages remain retained as recovery evidence, so disk usage can exceed the network byte budget. Source files live in `imports/<planSha256>/source`; the canonical plan and receipt live beside that directory. The import result returns the private absolute `sourceRoot`, the relative `receiptPath`, and its receipt identity. Agents explicitly include the selected source files in the ordinary studio bundle before rendering. Acquisition does not execute a renderer or append objects to a scene.
+
+The glTF subset accepts explicit local `.bin`, PNG, and JPEG dependencies. It verifies every buffer/image URI against the catalog closure and checks declared buffer byte lengths. Remote/data URIs, hidden resource references, unsupported extensions, omitted dependencies, and unreferenced catalog includes reject. Common material and texture-transform extensions are supported; compressed geometry and additional image formats require a separately qualified profile. Native `.blend`, scripts, archives, FBX, USD, and GLB are not acquired by this subset. Existing explicit native-source import paths retain such source as inert bytes until a separately authorized render.
+
+Provider metadata and transport checksums are evidence of what was fetched. They do not establish cryptographically authenticated authorship, renderer compatibility, physical calibration, or absence of hostile native decoder inputs. API thumbnail metadata is not assigned the CC0 asset-file license, and the importer does not fetch preview images.
+
+## Validation
+
+`bun test apps/desktop/studio/assets/poly-haven.test.ts` runs network-free regressions for canonical plans, foreign accessors, source URLs, budgets, glTF dependencies, cancellation, publication custody, interrupted acquisition, and offline replay.
+
+The opt-in `qualify-live.ts <fresh-absolute-ignored-directory>` imports `venice_sunset` at 1k HDR and `dirty_football` at 1k glTF. It enforces a combined 50 MiB free download ceiling and requires both complete imports to replay with networking disabled. The September 9 qualification retained six exact files totaling 3,435,401 bytes: 1,440,400 bytes of HDRI and 1,995,001 bytes of model/source dependencies. The qualification writes its evidence into the requested ignored directory. This verifies acquisition and local dependency closure, not a native render of the imported asset.

package/apps/desktop/studio/assets/contracts.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { canonicalJson, boundedCanonicalJsonSha256 } from "../../../../src/code/canonical-json";
+import { createBoundedJsonValueSnapshot, deepFreezeJson } from "../../../../src/code/json-snapshot";
+import { StudioPathSchema } from "../../../../src/studio";
+
+export const POLY_HAVEN = Object.freeze({ provider: "poly-haven" as const, api: "https://api.polyhaven.com", download: "https://dl.polyhaven.org", credit: "Powered by Poly Haven", homepage: "https://polyhaven.com", license: "CC0-1.0", licenseUrl: "https://creativecommons.org/publicdomain/zero/1.0/", termsUrl: "https://github.com/Poly-Haven/Public-API/blob/master/ToS.md", userAgent: "SLOPCAMERA/StudioAssets (+https://slopcamera.com)" });
+export const ASSET_LIMITS = Object.freeze({ jsonBytes: 4 * 1024 * 1024, fileBytes: 128 * 1024 * 1024, totalBytes: 512 * 1024 * 1024, files: 64, requestMs: 120_000 });
+export const AssetIdSchema = z.string().regex(/^[a-z0-9][a-z0-9_-]{0,127}$/u);
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const text = z.string().min(1).max(512).refine(value => !/[\u0000-\u001f\u007f]/u.test(value));
+const resolution = z.enum(["1k", "2k", "4k"]);
+const common = { provider: z.literal("poly-haven"), assetId: AssetIdSchema, resolution, maximumTotalBytes: z.number().int().min(1).max(ASSET_LIMITS.totalBytes).default(50 * 1024 * 1024) };
+export const AssetSelectionSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ ...common, kind: z.literal("hdri"), format: z.enum(["hdr", "exr"]) }),
+  z.strictObject({ ...common, kind: z.literal("texture"), format: z.enum(["png", "jpg", "exr"]), maps: z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/u)).min(1).max(16) }).refine(value => new Set(value.maps).size === value.maps.length, "Texture maps must be unique."),
+  z.strictObject({ ...common, kind: z.literal("model"), format: z.literal("gltf") }),
+]);
+export type AssetSelection = z.infer<typeof AssetSelectionSchema>;
+export const AssetSearchSchema = z.strictObject({ provider: z.literal("poly-haven"), query: z.string().trim().min(1).max(100).refine(value => !/[\u0000-\u001f\u007f]/u.test(value)).transform(value => value.toLowerCase()), type: z.enum(["all", "hdris", "textures", "models"]).default("all"), limit: z.number().int().min(1).max(20).default(8) });
+export type AssetSearch = z.infer<typeof AssetSearchSchema>;
+export function captureAssetJson(value: unknown): unknown {
+  return createBoundedJsonValueSnapshot(value, ASSET_LIMITS.jsonBytes, "studio asset data", { maximumDepth: 24, maximumValues: 150_000 }).value;
+}
+export function parseAssetSelection(value: unknown): AssetSelection { return deepFreezeJson(AssetSelectionSchema.parse(captureAssetJson(value))); }
+export function parseAssetSearch(value: unknown): AssetSearch { return deepFreezeJson(AssetSearchSchema.parse(captureAssetJson(value))); }
+export const assetJson = (value: unknown): string => `${canonicalJson(value)}\n`;
+export const assetHash = (value: unknown): string => boundedCanonicalJsonSha256(value, { maximumBytes: ASSET_LIMITS.jsonBytes });
+
+export function downloadUrl(value: unknown): string {
+  if (typeof value !== "string" || value.length > 2048) throw new Error("Invalid Poly Haven download URL.");
+  const url = new URL(value);
+  if (url.origin !== POLY_HAVEN.download || url.username || url.password || url.port || url.hash || url.search || !url.pathname.startsWith("/file/ph-assets/") || /%2f|%5c/iu.test(url.pathname)) throw new Error("Poly Haven downloads require the fixed HTTPS asset origin and path.");
+  const path = decodeURIComponent(url.pathname.slice("/file/ph-assets/".length));
+  StudioPathSchema.parse(path);
+  if (url.href !== value) throw new Error("Poly Haven download URLs must be canonical.");
+  return value;
+}
+function record(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected Poly Haven object metadata.");
+  return value as Record<string, unknown>;
+}
+function own(value: unknown, key: string): unknown {
+  const object = record(value);
+  if (!Object.hasOwn(object, key)) throw new Error("The selected Poly Haven variant is unavailable.");
+  return object[key];
+}
+function validateMetadataUrls(value: unknown): void {
+  if (Array.isArray(value)) { value.forEach(validateMetadataUrls); return; }
+  if (value === null || typeof value !== "object") return;
+  for (const [key, item] of Object.entries(value)) {
+    if (/^(url|thumbnail_url)$/u.test(key) && item !== null) {
+      if (key === "url") downloadUrl(item);
+      else {
+        const url = new URL(z.string().max(2048).parse(item));
+        if (url.origin !== "https://cdn.polyhaven.com" || url.username || url.password || url.port || url.hash || !url.pathname.startsWith("/asset_img/") || [...url.searchParams.keys()].some(key => !["width", "height", "v"].includes(key))) throw new Error("Unexpected Poly Haven thumbnail URL.");
+      }
+    }
+    validateMetadataUrls(item);
+  }
+}
+export function capturePolyHavenSnapshots(input: unknown): { readonly info: unknown; readonly files: unknown } {
+  const captured = z.strictObject({ info: z.unknown(), files: z.unknown() }).parse(captureAssetJson(input));
+  const snapshots = { info: record(captured.info), files: record(captured.files) };
+  validateMetadataUrls(snapshots);
+  return deepFreezeJson(snapshots);
+}
+export interface PolyHavenAsset { readonly assetId: string; readonly name: string; readonly type: "hdris" | "textures" | "models"; readonly authors: readonly { readonly name: string; readonly role: string }[]; readonly assetPage: string }
+export function describePolyHavenAsset(assetIdInput: unknown, infoInput: unknown): PolyHavenAsset {
+  const assetId = AssetIdSchema.parse(assetIdInput), info = record(captureAssetJson(infoInput));
+  validateMetadataUrls(info);
+  const type = z.number().int().min(0).max(2).parse(info.type), authors = record(info.authors);
+  if (Object.keys(authors).length < 1 || Object.keys(authors).length > 64) throw new Error("Poly Haven author metadata is missing or exceeds its bound.");
+  return deepFreezeJson({ assetId, name: text.parse(info.name), type: (["hdris", "textures", "models"] as const)[type]!, authors: Object.entries(authors).map(([name, role]) => ({ name: text.parse(name), role: text.parse(role) })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0), assetPage: `${POLY_HAVEN.homepage}/a/${assetId}` });
+}
+export interface AssetPlannedFile { readonly path: string; readonly url: string; readonly bytes: number; readonly md5: string; readonly role: "environment" | "texture" | "model" | "dependency"; readonly map?: string }
+const sourceFile = z.object({ url: z.string(), size: z.number().int().positive().max(ASSET_LIMITS.fileBytes), md5: z.string().regex(/^[a-f0-9]{32}$/u), include: z.record(z.string(), z.unknown()).optional() });
+function selectedFile(value: unknown, role: AssetPlannedFile["role"], pathInput?: string, map?: string): { file: AssetPlannedFile; includes: Record<string, unknown> } {
+  const source = sourceFile.parse(value), url = downloadUrl(source.url);
+  if (role === "model" && source.size > ASSET_LIMITS.jsonBytes) throw new Error("Selected glTF JSON exceeds its four MiB decode profile.");
+  const basename = decodeURIComponent(new URL(url).pathname.split("/").at(-1)!);
+  const path = StudioPathSchema.parse(pathInput ?? basename);
+  const allowed = role === "model" ? /\.gltf$/u : role === "dependency" ? /\.(?:bin|png|jpg|jpeg)$/u : /\.(?:hdr|exr|png|jpg)$/u;
+  if (!allowed.test(path) || !allowed.test(basename)) throw new Error("Unsupported asset file; archives and executable sources are not imported by this adapter.");
+  return { file: { path, url, bytes: source.size, md5: source.md5, role, ...(map === undefined ? {} : { map }) }, includes: source.include ?? {} };
+}
+export interface PolyHavenAssetPlan {
+  readonly kind: "slopcamera.studio-asset-plan"; readonly schemaVersion: 1; readonly provider: "poly-haven"; readonly selection: AssetSelection;
+  readonly asset: PolyHavenAsset; readonly license: { readonly spdx: "CC0-1.0"; readonly url: string; readonly scope: "asset-files" };
+  readonly credit: string; readonly apiTermsUrl: string; readonly snapshots: { readonly info: unknown; readonly files: unknown };
+  readonly files: readonly AssetPlannedFile[]; readonly totalBytes: number; readonly planSha256: string;
+}
+export function planPolyHavenAsset(selectionInput: unknown, snapshotsInput: { readonly info: unknown; readonly files: unknown }): PolyHavenAssetPlan {
+  const selection = parseAssetSelection(selectionInput), snapshots = capturePolyHavenSnapshots(snapshotsInput);
+  const asset = describePolyHavenAsset(selection.assetId, snapshots.info);
+  if (asset.type !== ({ hdri: "hdris", texture: "textures", model: "models" } as const)[selection.kind]) throw new Error("Selected asset kind differs from its provider metadata.");
+  const files: AssetPlannedFile[] = [];
+  for (const map of selection.kind === "texture" ? [...selection.maps].sort() : [selection.kind === "hdri" ? "hdri" : "gltf"]) {
+    const variant = own(own(own(snapshots.files, map), selection.resolution), selection.format);
+    const selected = selectedFile(variant, selection.kind === "hdri" ? "environment" : selection.kind, undefined, selection.kind === "texture" ? map : undefined);
+    if (!selected.file.path.endsWith(`.${selection.format}`)) throw new Error("Selected asset format differs from its download filename.");
+    files.push(selected.file);
+    const includes = Object.entries(selected.includes);
+    if (selection.kind !== "model" && includes.length > 0) throw new Error("The selected standalone map unexpectedly requires dependencies.");
+    for (const [path, value] of includes) {
+      const dependency = selectedFile(value, "dependency", path);
+      if (Object.keys(dependency.includes).length > 0) throw new Error("Nested native dependencies require a separately supported import profile.");
+      files.push(dependency.file);
+    }
+  }
+  const paths = new Set<string>();
+  for (const file of files) {
+    const key = file.path.toLowerCase();
+    if (paths.has(key)) throw new Error("Selected asset paths collide.");
+    paths.add(key);
+  }
+  for (const path of paths) for (let offset = path.indexOf("/"); offset !== -1; offset = path.indexOf("/", offset + 1)) if (paths.has(path.slice(0, offset))) throw new Error("Selected asset uses a file as a directory.");
+  const totalBytes = files.reduce((total, file) => total + file.bytes, 0);
+  if (files.length > ASSET_LIMITS.files || totalBytes > selection.maximumTotalBytes) throw new Error("Selected complete asset exceeds its explicit file or byte budget.");
+  const body = { kind: "slopcamera.studio-asset-plan" as const, schemaVersion: 1 as const, provider: "poly-haven" as const, selection, asset, license: { spdx: "CC0-1.0" as const, url: POLY_HAVEN.licenseUrl, scope: "asset-files" as const }, credit: POLY_HAVEN.credit, apiTermsUrl: POLY_HAVEN.termsUrl, snapshots, files: files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0), totalBytes };
+  return deepFreezeJson({ ...body, planSha256: assetHash(body) });
+}
+export function parsePolyHavenAssetPlan(input: unknown): PolyHavenAssetPlan {
+  const value = record(captureAssetJson(input));
+  const snapshots = z.strictObject({ info: z.unknown(), files: z.unknown() }).parse(value.snapshots);
+  digest.parse(value.planSha256);
+  const derived = planPolyHavenAsset(value.selection, { info: snapshots.info, files: snapshots.files });
+  if (canonicalJson(value) !== canonicalJson(derived)) throw new Error("Asset plan differs from its exact canonical provider snapshots and selection.");
+  return derived;
+}

package/apps/desktop/studio/assets/network.ts

@@ -0,0 +1,64 @@
+import { ASSET_LIMITS, POLY_HAVEN, downloadUrl } from "./contracts";
+
+export type AssetFetch = (input: string, init: RequestInit) => Promise<Response>;
+function aborted(signal: AbortSignal): void { if (signal.aborted) throw new Error("Poly Haven asset operation was cancelled or timed out."); }
+async function withCancellation<Value>(pending: Promise<Value>, signal: AbortSignal): Promise<Value> {
+  let onAbort: (() => void) | undefined;
+  try {
+    return await Promise.race([pending, new Promise<never>((_, reject) => {
+      onAbort = () => reject(new Error("Poly Haven response was cancelled or timed out."));
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted) onAbort();
+    })]);
+  } finally { if (onAbort !== undefined) signal.removeEventListener("abort", onAbort); }
+}
+export function createPolyHavenNetwork(options: { readonly fetch?: AssetFetch; readonly signal?: AbortSignal }) {
+  const request = options.fetch ?? globalThis.fetch;
+  const cancellation = options.signal;
+  async function read(url: string, maximumBytes: number, expectedBytes?: number): Promise<Buffer> {
+    const signal = AbortSignal.any([AbortSignal.timeout(ASSET_LIMITS.requestMs), ...(cancellation === undefined ? [] : [cancellation])]);
+    aborted(signal);
+    const response = await withCancellation(request(url, { method: "GET", redirect: "error", credentials: "omit", signal, headers: { "user-agent": POLY_HAVEN.userAgent, accept: "application/json, application/octet-stream;q=0.9" } }), signal);
+    if (signal.aborted) { void response.body?.cancel().catch(() => undefined); aborted(signal); }
+    if (response.status !== 200 || response.redirected || response.url !== "" && response.url !== url || response.body === null) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new Error(`Poly Haven returned an unsupported response (HTTP ${response.status}).`);
+    }
+    const declared = response.headers.get("content-length");
+    if (declared !== null && (!/^\d+$/u.test(declared) || !Number.isSafeInteger(Number(declared)) || Number(declared) > maximumBytes)) {
+      void response.body.cancel().catch(() => undefined);
+      throw new Error("Poly Haven response exceeds its byte bound.");
+    }
+    const reader = response.body.getReader(), chunks: Buffer[] = [];
+    let length = 0;
+    try {
+      for (;;) {
+        aborted(signal);
+        const next = await withCancellation(reader.read(), signal);
+        if (next.done) break;
+        length += next.value.byteLength;
+        if (length > maximumBytes) throw new Error("Poly Haven response exceeds its byte bound.");
+        chunks.push(Buffer.from(next.value));
+      }
+      aborted(signal);
+      if (expectedBytes !== undefined && length !== expectedBytes) throw new Error("Poly Haven file length differs from its selected catalog entry.");
+      return Buffer.concat(chunks, length);
+    } catch (error) {
+      // Cancellation of an injected or broken stream must not postpone failure.
+      void reader.cancel().catch(() => undefined);
+      throw error;
+    } finally { reader.releaseLock(); }
+  }
+  return {
+    async json(path: string, query?: URLSearchParams): Promise<unknown> {
+      if (!/^\/(?:search|info\/[a-z0-9][a-z0-9_-]{0,127}|files\/[a-z0-9][a-z0-9_-]{0,127})$/u.test(path)) throw new Error("Unsupported Poly Haven API endpoint.");
+      const url = `${POLY_HAVEN.api}${path}${query === undefined ? "" : `?${query.toString()}`}`;
+      const bytes = await read(url, ASSET_LIMITS.jsonBytes);
+      return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as unknown;
+    },
+    async file(url: string, bytes: number): Promise<Buffer> {
+      if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > ASSET_LIMITS.fileBytes) throw new Error("Asset file exceeds its byte bound.");
+      return read(downloadUrl(url), bytes, bytes);
+    },
+  };
+}

package/apps/desktop/studio/assets/poly-haven.ts

@@ -0,0 +1,148 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { StudioPathSchema } from "../../../../src/studio";
+import { deepFreezeJson } from "../../../../src/code/json-snapshot";
+import { createNodeBundleFileSystem } from "../../core/storage";
+import { ensurePhysicalPrivateDirectoryWithin } from "../../cli/paths";
+import { inventoryStudioFiles, readStudioBytes } from "../../cli/studio-files";
+import { ASSET_LIMITS, AssetIdSchema, POLY_HAVEN, assetJson, captureAssetJson, capturePolyHavenSnapshots, describePolyHavenAsset, parseAssetSearch, parseAssetSelection, parsePolyHavenAssetPlan, planPolyHavenAsset, type AssetPlannedFile, type PolyHavenAssetPlan } from "./contracts";
+import { createPolyHavenNetwork, type AssetFetch } from "./network";
+
+const hash = (algorithm: "md5" | "sha256", bytes: Uint8Array): string => createHash(algorithm).update(bytes).digest("hex");
+const absent = (error: unknown): boolean => error instanceof Error && "code" in error && error.code === "ENOENT";
+export interface ImportedAssetFile extends AssetPlannedFile { readonly sha256: string }
+export interface PolyHavenAssetReceipt {
+  readonly kind: "slopcamera.studio-asset-import"; readonly schemaVersion: 1; readonly provider: "poly-haven"; readonly planSha256: string;
+  readonly asset: PolyHavenAssetPlan["asset"]; readonly license: PolyHavenAssetPlan["license"]; readonly credit: string; readonly apiTermsUrl: string;
+  readonly files: readonly ImportedAssetFile[]; readonly totalBytes: number; readonly sourceDirectory: "source"; readonly verification: "catalog-md5-and-local-sha256";
+}
+function fileChecks(file: AssetPlannedFile, bytes: Buffer): void {
+  if (bytes.length !== file.bytes || hash("md5", bytes) !== file.md5) throw new Error("Downloaded asset differs from its selected catalog size or MD5.");
+  const extension = file.path.split(".").at(-1);
+  const valid = extension === "bin" || extension === "gltf" || extension === "png" && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+    || (extension === "jpg" || extension === "jpeg") && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255
+    || extension === "exr" && bytes.subarray(0, 4).equals(Buffer.from([0x76, 0x2f, 0x31, 0x01]))
+    || extension === "hdr" && /^(?:#\?RADIANCE|#\?RGBE)\r?\n/u.test(bytes.subarray(0, 32).toString("ascii"));
+  if (!valid) throw new Error("Asset file signature differs from its selected format.");
+}
+export function validateGltfAssetClosure(bytes: Uint8Array, planInput: unknown): void {
+  const plan = parsePolyHavenAssetPlan(planInput);
+  if (plan.selection.kind !== "model" || bytes.byteLength > ASSET_LIMITS.jsonBytes) throw new Error("glTF source exceeds the supported JSON profile.");
+  const raw = captureAssetJson(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+  const document = z.object({ asset: z.object({ version: z.literal("2.0") }), buffers: z.array(z.object({ uri: z.string(), byteLength: z.number().int().positive() })).max(64).default([]), images: z.array(z.object({ uri: z.string() })).max(64).default([]), extensionsUsed: z.array(z.string()).max(32).default([]), extensionsRequired: z.array(z.string()).max(32).default([]) }).parse(raw);
+  const allowed = new Set(["KHR_materials_ior", "KHR_materials_specular", "KHR_materials_transmission", "KHR_materials_volume", "KHR_materials_clearcoat", "KHR_materials_sheen", "KHR_materials_emissive_strength", "KHR_materials_unlit", "KHR_texture_transform", "KHR_mesh_quantization"]);
+  if ([...document.extensionsUsed, ...document.extensionsRequired].some(name => !allowed.has(name))) throw new Error("glTF uses an extension outside the supported asset profile.");
+  function inspect(value: unknown, path: string): void {
+    if (Array.isArray(value)) { value.forEach((item, index) => inspect(item, `${path}/${index}`)); return; }
+    if (value === null || typeof value !== "object") return;
+    for (const [key, item] of Object.entries(value)) {
+      if (key === "uri" && !/^\/(?:images|buffers)\/\d+$/u.test(path)) throw new Error("glTF contains a resource outside its supported buffer/image closure.");
+      if (key === "extensions" && (item === null || typeof item !== "object" || Array.isArray(item) || Object.keys(item).some(name => !allowed.has(name)))) throw new Error("glTF contains an undeclared unsupported extension.");
+      inspect(item, `${path}/${key}`);
+    }
+  }
+  inspect(raw, "");
+  const actual = new Set<string>(), expected = plan.files.filter(file => file.role === "dependency");
+  for (const item of [...document.buffers, ...document.images]) {
+    if (/[?#\\:]/u.test(item.uri) || /%2f|%5c/iu.test(item.uri)) throw new Error("glTF resource references must be local explicit paths.");
+    const path = StudioPathSchema.parse(decodeURIComponent(item.uri));
+    const file = expected.find(file => file.path === path);
+    if (file === undefined || "byteLength" in item && item.byteLength !== file.bytes) throw new Error("glTF resource differs from its complete selected dependency closure.");
+    actual.add(path);
+  }
+  if (expected.some(file => !actual.has(file.path))) throw new Error("glTF catalog contains an unreferenced dependency outside the source closure.");
+}
+
+export function createPolyHavenAssetService(options: { readonly storageRoot: string; readonly fetch?: AssetFetch; readonly signal?: AbortSignal; readonly beforePublication?: () => Promise<void> }) {
+  const network = createPolyHavenNetwork(options);
+  const storageRoot = options.storageRoot, cancellation = options.signal, beforePublication = options.beforePublication;
+  async function fence(): Promise<void> {
+    if (cancellation?.aborted) throw new Error("Poly Haven asset operation was cancelled.");
+    await beforePublication?.();
+    if (cancellation?.aborted) throw new Error("Poly Haven asset operation was cancelled.");
+  }
+  async function describe(assetIdInput: unknown) {
+    const assetId = AssetIdSchema.parse(captureAssetJson(assetIdInput));
+    const snapshots = capturePolyHavenSnapshots({ info: await network.json(`/info/${assetId}`), files: await network.json(`/files/${assetId}`) });
+    const asset = describePolyHavenAsset(assetId, snapshots.info);
+    return deepFreezeJson({ provider: POLY_HAVEN.provider, credit: POLY_HAVEN.credit, apiTermsUrl: POLY_HAVEN.termsUrl, asset, snapshots });
+  }
+  async function verify(directory: string, plan: PolyHavenAssetPlan, receiptInput?: unknown): Promise<PolyHavenAssetReceipt> {
+    const fs = createNodeBundleFileSystem(directory), files: ImportedAssetFile[] = [];
+    const inventory = await inventoryStudioFiles(join(directory, "source"), ASSET_LIMITS.files, plan.selection.maximumTotalBytes);
+    if (inventory.length !== plan.files.length) throw new Error("Retained asset source closure contains missing or undeclared files.");
+    for (const file of plan.files) {
+      const integrity = await fs.inspectFile!(`source/${file.path}`, file.bytes);
+      const bytes = await readStudioBytes(join(directory, "source", file.path), integrity, ASSET_LIMITS.fileBytes);
+      fileChecks(file, bytes);
+      if (file.role === "model") validateGltfAssetClosure(bytes, plan);
+      files.push({ ...file, sha256: integrity.sha256 });
+    }
+    const receipt: PolyHavenAssetReceipt = { kind: "slopcamera.studio-asset-import", schemaVersion: 1, provider: "poly-haven", planSha256: plan.planSha256, asset: plan.asset, license: plan.license, credit: plan.credit, apiTermsUrl: plan.apiTermsUrl, files, totalBytes: plan.totalBytes, sourceDirectory: "source", verification: "catalog-md5-and-local-sha256" };
+    if (receiptInput !== undefined && assetJson(captureAssetJson(receiptInput)) !== assetJson(receipt)) throw new Error("Retained asset receipt conflicts with its verified source files.");
+    await fence();
+    return deepFreezeJson(receipt);
+  }
+  return {
+    async search(input: unknown) {
+      const query = parseAssetSearch(input);
+      const result = z.object({ query: z.string().max(100), type: z.string(), total: z.number().int().nonnegative(), results: z.array(z.object({ slug: AssetIdSchema, score: z.number().finite().min(-1).max(1) })).max(20) }).parse(captureAssetJson(await network.json("/search", new URLSearchParams({ q: query.query, t: query.type, limit: String(query.limit) }))));
+      if (result.results.length > query.limit || result.query !== query.query || result.type !== query.type || new Set(result.results.map(item => item.slug)).size !== result.results.length) throw new Error("Poly Haven search differs from its bounded request.");
+      const items = [];
+      for (const resultItem of result.results) {
+        const asset = describePolyHavenAsset(resultItem.slug, await network.json(`/info/${resultItem.slug}`));
+        if (query.type !== "all" && asset.type !== query.type) throw new Error("Poly Haven search returned an asset outside the requested type.");
+        items.push({ ...asset, score: resultItem.score });
+      }
+      return deepFreezeJson({ provider: POLY_HAVEN.provider, credit: POLY_HAVEN.credit, apiTermsUrl: POLY_HAVEN.termsUrl, query, total: result.total, items });
+    },
+    describe,
+    async plan(input: unknown): Promise<PolyHavenAssetPlan> {
+      const selection = parseAssetSelection(input), found = await describe(selection.assetId);
+      return planPolyHavenAsset(selection, found.snapshots);
+    },
+    async importAsset(input: unknown) {
+      const plan = parsePolyHavenAssetPlan(input);
+      await fence();
+      const root = resolve(storageRoot), details = await lstat(root);
+      if (!details.isDirectory() || details.isSymbolicLink() || await realpath(root) !== root) throw new Error("Asset storage requires an existing physical root.");
+      const relative = `imports/${plan.planSha256}`, directory = await ensurePhysicalPrivateDirectoryWithin(root, relative), fs = createNodeBundleFileSystem(root);
+      await ensurePhysicalPrivateDirectoryWithin(directory, "source");
+      await fs.writeTextNoReplace!(`${relative}/plan.json`, assetJson(plan), fence);
+      if (await fs.readText(`${relative}/plan.json`) !== assetJson(plan)) throw new Error("Retained asset plan conflicts with the requested plan.");
+      const retained = await fs.readText(`${relative}/receipt.json`).catch(error => { if (absent(error)) return undefined; throw error; });
+      if (retained !== undefined) {
+        const receipt = await verify(directory, plan, JSON.parse(retained));
+        return deepFreezeJson({ disposition: "reused" as const, receipt, receiptPath: `${relative}/receipt.json`, sourceRoot: join(directory, "source"), receiptSha256: hash("sha256", Buffer.from(assetJson(receipt))) });
+      }
+      for (const file of [...plan.files].sort((a, b) => Number(b.role === "model") - Number(a.role === "model"))) {
+        await fence();
+        const destination = `${relative}/source/${file.path}`;
+        const existing = await fs.inspectFile!(destination, file.bytes).catch(error => { if (absent(error)) return undefined; throw error; });
+        if (existing !== undefined) {
+          const bytes = await readStudioBytes(join(root, destination), existing, ASSET_LIMITS.fileBytes);
+          fileChecks(file, bytes);
+          if (file.role === "model") validateGltfAssetClosure(bytes, plan);
+          continue;
+        }
+        const bytes = await network.file(file.url, file.bytes);
+        fileChecks(file, bytes);
+        if (file.role === "model") validateGltfAssetClosure(bytes, plan);
+        const staging = `staging/${randomUUID()}`, stage = await ensurePhysicalPrivateDirectoryWithin(root, staging);
+        const handle = await open(join(stage, "download"), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+        // Keep the exact downloaded stage as recoverable evidence. The source copy
+        // uses shared inode-pinned, guarded, atomic no-replace publication.
+        await fs.copyFileNoReplace!(`${staging}/download`, destination, { bytes: bytes.length, sha256: hash("sha256", bytes) }, fence);
+      }
+      const receipt = await verify(directory, plan);
+      await fs.writeTextNoReplace!(`${relative}/receipt.json`, assetJson(receipt), fence);
+      const winner = JSON.parse(await fs.readText(`${relative}/receipt.json`)) as unknown;
+      const verified = await verify(directory, plan, winner);
+      return deepFreezeJson({ disposition: "created" as const, receipt: verified, receiptPath: `${relative}/receipt.json`, sourceRoot: join(directory, "source"), receiptSha256: hash("sha256", Buffer.from(assetJson(verified))) });
+    },
+  };
+}