@forgeax/engine-pack 0.1.2

package/dist/scriptable-pack-node.mjs

@@ -0,0 +1,1590 @@
+import { createHash } from 'crypto';
+import { existsSync } from 'fs';
+import { realpath, readFile, stat, mkdtemp, rm, mkdir, writeFile, rename } from 'fs/promises';
+import { tmpdir } from 'os';
+import { resolve, dirname, extname, relative, sep, isAbsolute } from 'path';
+import { fileURLToPath } from 'url';
+import { Worker } from 'worker_threads';
+import { ok, err, AssetError, ImportError } from '@forgeax/engine-types';
+import ts from 'typescript';
+import { uuidv7obj } from 'uuidv7';
+
+// src/scriptable-pack-node.ts
+
+// src/errors.ts
+var PackError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(args) {
+    super(`[PackError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = "PackError";
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+};
+function brand(bytes) {
+  return bytes;
+}
+var HEX_BYTE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+function bytesToDashForm(bytes) {
+  const h = HEX_BYTE;
+  return `${h[bytes[0]]}${h[bytes[1]]}${h[bytes[2]]}${h[bytes[3]]}-${h[bytes[4]]}${h[bytes[5]]}-${h[bytes[6]]}${h[bytes[7]]}-${h[bytes[8]]}${h[bytes[9]]}-${h[bytes[10]]}${h[bytes[11]]}${h[bytes[12]]}${h[bytes[13]]}${h[bytes[14]]}${h[bytes[15]]}`;
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isValidAssetGuidString(value) {
+  return typeof value === "string" && UUID_RE.test(value);
+}
+function dashFormToBytes(dashForm) {
+  const hex = dashForm.replace(/-/g, "");
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 16; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+var AssetGuid = {
+  /**
+   * Parse a 36-char RFC 4122 dash-form UUID string into an AssetGuid.
+   * Returns Ok(AssetGuid) on success or Err(PackError) with code 'pack-guid-malformed' on failure.
+   * Never throws for expected failures (requirements §4.2 / §14 / charter proposition 4).
+   */
+  parse(dashForm) {
+    if (!isValidAssetGuidString(dashForm)) {
+      return {
+        ok: false,
+        error: new PackError({
+          code: "pack-guid-malformed",
+          expected: "36-char RFC 4122 dash-form UUID",
+          hint: "use AssetGuid.random() or a UUIDv7 generator; all GUID fields must be 36-char RFC 4122 dash-form",
+          detail: {
+            raw: dashForm,
+            reason: "expected 36-char RFC 4122 dash-form UUID"
+          }
+        })
+      };
+    }
+    return { ok: true, value: brand(dashFormToBytes(dashForm)) };
+  },
+  /**
+   * Format an AssetGuid as a 36-char RFC 4122 lowercase dash-form string.
+   */
+  format(guid) {
+    return bytesToDashForm(guid);
+  },
+  /**
+   * Test byte-by-byte equality between two AssetGuids.
+   */
+  equals(a, b) {
+    for (let i = 0; i < 16; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  },
+  /**
+   * Mint a new time-ordered UUIDv7 as an AssetGuid.
+   * Works in both Node.js and browser environments.
+   */
+  random() {
+    const uuid = uuidv7obj();
+    const bytes = new Uint8Array(16);
+    bytes.set(uuid.bytes);
+    return brand(bytes);
+  }
+};
+var SCRIPTABLE_PACK_ASSET_KINDS = [
+  "mesh",
+  "material",
+  "scene",
+  "texture",
+  "equirect",
+  "sampler",
+  "font",
+  "render-pipeline",
+  "tileset",
+  "video",
+  "skeleton",
+  "skin",
+  "animation-clip",
+  "animation-graph",
+  "audio",
+  "particle-effect"
+];
+function isScriptablePackAssetKind(value) {
+  return SCRIPTABLE_PACK_ASSET_KINDS.includes(value);
+}
+var SCRIPTABLE_PACK_REQUEST_ID_SCHEMA = {
+  type: "string",
+  minLength: 1,
+  maxLength: 128,
+  pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
+  description: "Caller-minted identity for one idempotent ScriptablePack operation."
+};
+var SCRIPTABLE_PACK_SOURCE_PATH_SCHEMA = {
+  type: "string",
+  minLength: 8,
+  pattern: "^[^/].*\\.pack\\.ts$",
+  description: "Game-root-relative ScriptablePack source path."
+};
+var SCRIPTABLE_PACK_OWNER_GUID_SCHEMA = {
+  type: "string",
+  format: "uuid",
+  description: "Catalog GUID used to resolve the producer-owned source subject."
+};
+var SCRIPTABLE_PACK_REVISION_SCHEMA = {
+  type: "string",
+  minLength: 64,
+  maxLength: 64,
+  pattern: "^[a-f0-9]{64}$",
+  description: "SHA-256 source revision returned by preflight."
+};
+var SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA = { type: "string", minLength: 1 };
+var SCRIPTABLE_PACK_ASSET_KIND_SCHEMA = {
+  enum: SCRIPTABLE_PACK_ASSET_KINDS,
+  description: "Ordinary Asset kind supported by the ScriptablePack producer/loader matrix."
+};
+var SCRIPTABLE_PACK_NAME_SCHEMA = { type: "string", minLength: 1 };
+function scriptablePackArgsSchema(properties, required, options = {}) {
+  const subjectRequired = ["requestId", ...required];
+  return {
+    type: "object",
+    properties: {
+      sourcePath: SCRIPTABLE_PACK_SOURCE_PATH_SCHEMA,
+      ownerGuid: SCRIPTABLE_PACK_OWNER_GUID_SCHEMA,
+      requestId: SCRIPTABLE_PACK_REQUEST_ID_SCHEMA,
+      ...properties
+    },
+    required: subjectRequired,
+    ...options.subject === false ? {} : {
+      anyOf: [
+        { required: [...subjectRequired, "sourcePath"] },
+        { required: [...subjectRequired, "ownerGuid"] },
+        ...options.guidSubject === false ? [] : [{ required: [...subjectRequired, "guid"] }]
+      ]
+    },
+    additionalProperties: false
+  };
+}
+[
+  {
+    id: "asset-source.create",
+    kind: "create",
+    domain: "session",
+    title: "Create Asset Source",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        name: SCRIPTABLE_PACK_NAME_SCHEMA,
+        initialOutput: {
+          type: "object",
+          properties: {
+            sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+            kind: SCRIPTABLE_PACK_ASSET_KIND_SCHEMA,
+            name: SCRIPTABLE_PACK_NAME_SCHEMA
+          },
+          required: ["sourceKey", "kind"],
+          additionalProperties: false
+        }
+      },
+      ["sourcePath", "initialOutput"],
+      { subject: false }
+    )
+  },
+  {
+    id: "asset-source.add-output",
+    kind: "add-output",
+    domain: "session",
+    title: "Add Asset Source Output",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+        assetKind: SCRIPTABLE_PACK_ASSET_KIND_SCHEMA,
+        name: SCRIPTABLE_PACK_NAME_SCHEMA,
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["sourceKey", "assetKind", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.add-external-asset",
+    kind: "add-external-asset",
+    domain: "session",
+    title: "Add Asset Source External Asset",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        alias: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+        guid: { type: "string", format: "uuid" },
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["alias", "guid", "expectedRevision"],
+      { guidSubject: false }
+    )
+  },
+  {
+    id: "asset-source.rename",
+    kind: "rename",
+    domain: "session",
+    title: "Rename Asset Source Display Name",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        target: {
+          oneOf: [
+            {
+              type: "object",
+              properties: { kind: { const: "package" } },
+              required: ["kind"],
+              additionalProperties: false
+            },
+            {
+              type: "object",
+              properties: {
+                kind: { const: "output" },
+                sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA
+              },
+              required: ["kind", "sourceKey"],
+              additionalProperties: false
+            }
+          ]
+        },
+        name: SCRIPTABLE_PACK_NAME_SCHEMA,
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["target", "name", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.remove-output",
+    kind: "remove-output",
+    domain: "session",
+    title: "Remove Asset Source Output",
+    destructive: true,
+    argsSchema: scriptablePackArgsSchema(
+      {
+        sourceKey: SCRIPTABLE_PACK_SOURCE_KEY_SCHEMA,
+        confirmIncomingRefs: { type: "array", items: { type: "string" } },
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["sourceKey", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.clone",
+    kind: "clone",
+    domain: "session",
+    title: "Clone Asset Source",
+    argsSchema: scriptablePackArgsSchema(
+      {
+        targetPath: SCRIPTABLE_PACK_SOURCE_PATH_SCHEMA,
+        expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA
+      },
+      ["targetPath", "expectedRevision"]
+    )
+  },
+  {
+    id: "asset-source.rebuild",
+    kind: "rebuild",
+    domain: "session",
+    title: "Rebuild Asset Source",
+    argsSchema: scriptablePackArgsSchema({ expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA }, [
+      "expectedRevision"
+    ])
+  },
+  {
+    id: "asset-source.cold-cook",
+    kind: "cold-cook",
+    domain: "session",
+    title: "Cold Cook Asset Source",
+    argsSchema: scriptablePackArgsSchema({ expectedRevision: SCRIPTABLE_PACK_REVISION_SCHEMA }, [
+      "expectedRevision"
+    ])
+  }
+];
+function actual(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (ArrayBuffer.isView(value)) return value.constructor.name;
+  return typeof value;
+}
+function invalid(propertyPath, expected, value, sourcePath) {
+  return err({
+    code: "pack-source-definition-invalid",
+    expected,
+    hint: "repair the default exported ScriptablePack definition, then inspect Meta again",
+    detail: {
+      ...sourcePath === void 0 ? {} : { sourcePath },
+      propertyPath,
+      actual: actual(value)
+    }
+  });
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isAssetGuid(value) {
+  return value instanceof Uint8Array && value.byteLength === 16;
+}
+function guidKey(guid) {
+  return AssetGuid.format(guid);
+}
+function freezeDefinition(definition) {
+  const assets = Object.fromEntries(
+    Object.entries(definition.assets).map(([sourceKey, descriptor]) => [
+      sourceKey,
+      Object.freeze({ ...descriptor, guid: descriptor.guid.slice() })
+    ])
+  );
+  const externalAssets = Object.fromEntries(
+    Object.entries(definition.externalAssets).map(([alias, guid]) => [
+      alias,
+      guid.slice()
+    ])
+  );
+  return Object.freeze({
+    ...definition,
+    packageId: definition.packageId.slice(),
+    assets: Object.freeze(assets),
+    externalAssets: Object.freeze(externalAssets)
+  });
+}
+function validateScriptablePackDefinition(value, sourcePath) {
+  if (!isRecord(value))
+    return invalid("$", "a ScriptablePack definition object", value, sourcePath);
+  if (value.schemaVersion !== "1.0.0") {
+    return invalid("$.schemaVersion", "the literal '1.0.0'", value.schemaVersion, sourcePath);
+  }
+  if (!isAssetGuid(value.packageId)) {
+    return invalid("$.packageId", "a 16-byte AssetGuid", value.packageId, sourcePath);
+  }
+  if (value.name !== void 0 && typeof value.name !== "string") {
+    return invalid("$.name", "a string when present", value.name, sourcePath);
+  }
+  if (!isRecord(value.assets) || Object.keys(value.assets).length === 0) {
+    return invalid(
+      "$.assets",
+      "a non-empty sourceKey to descriptor object",
+      value.assets,
+      sourcePath
+    );
+  }
+  if (!isRecord(value.externalAssets)) {
+    return invalid(
+      "$.externalAssets",
+      "an alias to AssetGuid object",
+      value.externalAssets,
+      sourcePath
+    );
+  }
+  if (typeof value.build !== "function") {
+    return invalid("$.build", "a build(assetReader) function", value.build, sourcePath);
+  }
+  const packageGuid = guidKey(value.packageId);
+  const localGuids = /* @__PURE__ */ new Set();
+  for (const [sourceKey, descriptor] of Object.entries(value.assets)) {
+    if (sourceKey.trim().length === 0) {
+      return invalid("$.assets", "non-empty sourceKey object keys", sourceKey, sourcePath);
+    }
+    if (!isRecord(descriptor)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}]`,
+        "an asset descriptor",
+        descriptor,
+        sourcePath
+      );
+    }
+    if (!isAssetGuid(descriptor.guid)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].guid`,
+        "a 16-byte AssetGuid",
+        descriptor.guid,
+        sourcePath
+      );
+    }
+    if (typeof descriptor.kind !== "string" || !isScriptablePackAssetKind(descriptor.kind)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].kind`,
+        "one of SCRIPTABLE_PACK_ASSET_KINDS",
+        descriptor.kind,
+        sourcePath
+      );
+    }
+    if (descriptor.name !== void 0 && typeof descriptor.name !== "string") {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].name`,
+        "a string when present",
+        descriptor.name,
+        sourcePath
+      );
+    }
+    const guid = guidKey(descriptor.guid);
+    if (guid === packageGuid || localGuids.has(guid)) {
+      return invalid(
+        `$.assets[${JSON.stringify(sourceKey)}].guid`,
+        "a GUID unique within the package and distinct from packageId",
+        descriptor.guid,
+        sourcePath
+      );
+    }
+    localGuids.add(guid);
+  }
+  const externalGuids = /* @__PURE__ */ new Set();
+  for (const [alias, guidValue] of Object.entries(value.externalAssets)) {
+    if (alias.trim().length === 0) {
+      return invalid("$.externalAssets", "non-empty alias object keys", alias, sourcePath);
+    }
+    if (!isAssetGuid(guidValue)) {
+      return invalid(
+        `$.externalAssets[${JSON.stringify(alias)}]`,
+        "a 16-byte AssetGuid",
+        guidValue,
+        sourcePath
+      );
+    }
+    const guid = guidKey(guidValue);
+    if (guid === packageGuid || localGuids.has(guid) || externalGuids.has(guid)) {
+      return invalid(
+        `$.externalAssets[${JSON.stringify(alias)}]`,
+        "a unique foreign GUID not owned by this package",
+        guidValue,
+        sourcePath
+      );
+    }
+    externalGuids.add(guid);
+  }
+  return ok(freezeDefinition(value));
+}
+function projectScriptablePackMeta(definition, source) {
+  const subAssets = Object.entries(definition.assets).sort(([left], [right]) => left.localeCompare(right)).map(([sourceKey, descriptor], sourceIndex) => ({
+    guid: guidKey(descriptor.guid),
+    sourceIndex,
+    sourceKey,
+    kind: descriptor.kind,
+    ...descriptor.name === void 0 ? {} : { name: descriptor.name }
+  }));
+  const externalAssets = Object.entries(definition.externalAssets).sort(([left], [right]) => left.localeCompare(right)).map(([alias, guid]) => ({ alias, guid: guidKey(guid) }));
+  return {
+    schemaVersion: "1.0.0",
+    kind: "external-asset-package",
+    packageId: guidKey(definition.packageId),
+    ...definition.name === void 0 ? {} : { name: definition.name },
+    importer: "pack-ts",
+    source,
+    importSettings: { contractVersion: "1.0.0", externalAssets },
+    subAssets
+  };
+}
+
+// src/evidence/source-inventory.ts
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, stableValue(entry)])
+    );
+  }
+  return value;
+}
+function producerRelativeLogicalPath(producerRoot, sourcePath) {
+  const root = resolve(producerRoot);
+  const source = resolve(sourcePath);
+  const path = relative(root, source);
+  if (path.length === 0 || path === ".." || path.startsWith(`..${sep}`) || resolve(root, path) !== source) {
+    throw new Error("producer source must be inside the injected producer root");
+  }
+  return path.split(sep).join("/");
+}
+function producerRelativeDdcKey(input) {
+  const logicalPath = producerRelativeLogicalPath(input.producerRoot, input.sourcePath);
+  const semantic = {
+    schemaVersion: input.schemaVersion,
+    logicalPath,
+    sourceDigest: input.sourceDigest,
+    importer: input.importer,
+    codec: input.codec,
+    settings: stableValue(input.settings),
+    producer: input.producer,
+    profile: input.profile,
+    declaredGuids: [...input.declaredGuids ?? []].sort()
+  };
+  return createHash("sha256").update(JSON.stringify(semantic)).digest("hex");
+}
+
+// src/scriptable-pack-node.ts
+var IMPORT_META_RESOLVE_FLAG = "--experimental-import-meta-resolve";
+function scriptablePackWorkerExecArgv() {
+  const inherited = process.execArgv.filter((arg) => !arg.startsWith("--input-type"));
+  return inherited.includes(IMPORT_META_RESOLVE_FLAG) ? inherited : [...inherited, IMPORT_META_RESOLVE_FLAG];
+}
+function scriptablePackDdcKey(input) {
+  return producerRelativeDdcKey(input);
+}
+async function readOptionalBuildCache(cache) {
+  try {
+    const cached = await cache.read();
+    if (cached !== null) return { value: cached, fromCache: true };
+  } catch {
+  }
+  return { value: await cache.coldCook(), fromCache: false };
+}
+async function resolveRelativeSourceImport(sourcePath, specifier) {
+  if (!specifier.startsWith(".")) return void 0;
+  const raw = resolve(dirname(sourcePath), specifier);
+  const candidates = extname(raw).length > 0 ? [raw] : [
+    raw,
+    `${raw}.ts`,
+    `${raw}.tsx`,
+    `${raw}.mts`,
+    `${raw}.js`,
+    `${raw}.mjs`,
+    `${raw}.json`,
+    resolve(raw, "index.ts")
+  ];
+  for (const candidate of candidates) {
+    try {
+      if ((await stat(candidate)).isFile()) return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function inventoryScriptablePackSource(sourcePath) {
+  const pending = [await realpath(sourcePath)];
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  while (pending.length > 0) {
+    const path = pending.pop();
+    if (path === void 0 || seen.has(path)) continue;
+    seen.add(path);
+    const bytes = await readFile(path);
+    entries.push({ path, digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}` });
+    const imports = ts.preProcessFile(new TextDecoder().decode(bytes), true, true).importedFiles;
+    for (const imported of imports) {
+      const resolved = await resolveRelativeSourceImport(path, imported.fileName);
+      if (resolved !== void 0) pending.push(await realpath(resolved));
+    }
+  }
+  return entries.sort((left, right) => left.path.localeCompare(right.path));
+}
+function serializeFailure(value) {
+  if (value !== null && typeof value === "object") {
+    const failure = value;
+    return {
+      name: failure.name,
+      code: failure.code,
+      expected: failure.expected,
+      actual: failure.actual,
+      hint: failure.hint,
+      detail: failure.detail,
+      message: failure.message
+    };
+  }
+  return { message: String(value) };
+}
+function hydrateFailure(value) {
+  if (value === null || typeof value !== "object") return value;
+  const failure = value;
+  if (failure.name === "AssetError" && typeof failure.code === "string" && typeof failure.expected === "string" && typeof failure.hint === "string") {
+    const args = {
+      code: failure.code,
+      expected: failure.expected,
+      hint: failure.hint
+    };
+    return failure.detail === void 0 ? new AssetError(args) : new AssetError({
+      ...args,
+      detail: failure.detail
+    });
+  }
+  if (failure.name === "ImportError" && typeof failure.code === "string" && typeof failure.expected === "string" && typeof failure.hint === "string" && failure.detail !== void 0) {
+    return new ImportError({
+      code: failure.code,
+      expected: failure.expected,
+      hint: failure.hint,
+      detail: failure.detail,
+      ...typeof failure.actual === "string" ? { actual: failure.actual } : {}
+    });
+  }
+  if (typeof failure.message === "string") {
+    const error = new Error(failure.message);
+    if (typeof failure.name === "string") error.name = failure.name;
+    return error;
+  }
+  return value;
+}
+var WorkerScriptablePackExecutor = class {
+  worker;
+  compileRoot;
+  nextBuildId = 0;
+  disposal;
+  build;
+  async load(sourcePath) {
+    const workerUrl = scriptablePackWorkerUrl();
+    const compileRoot = await mkdtemp(resolve(tmpdir(), "forgeax-scriptable-pack-"));
+    this.compileRoot = compileRoot;
+    const worker = new Worker(workerUrl, {
+      workerData: { sourcePath: resolve(sourcePath), compileRoot },
+      execArgv: scriptablePackWorkerExecArgv(),
+      resourceLimits: { maxOldGenerationSizeMb: 256, maxYoungGenerationSizeMb: 64 }
+    });
+    this.worker = worker;
+    worker.on("message", (message) => this.onMessage(message));
+    worker.unref();
+    return new Promise((resolveLoad, rejectLoad) => {
+      const onMessage = (message) => {
+        if (message === null || typeof message !== "object") return;
+        const value = message;
+        if (value.kind === "loaded") {
+          worker.off("message", onMessage);
+          resolveLoad({
+            default: value.definition === void 0 ? void 0 : {
+              ...value.definition,
+              build: (reader) => this.runBuild(reader)
+            }
+          });
+        } else if (value.kind === "load-threw") {
+          worker.off("message", onMessage);
+          rejectLoad(hydrateFailure(value.error));
+        }
+      };
+      worker.on("message", onMessage);
+      worker.once("error", rejectLoad);
+      worker.once("exit", (code) => {
+        if (code !== 0) rejectLoad(new Error(`ScriptablePack worker exited with code ${code}`));
+      });
+    });
+  }
+  dispose(reason = "complete") {
+    if (this.disposal !== void 0) return this.disposal;
+    const worker = this.worker;
+    this.worker = void 0;
+    const compileRoot = this.compileRoot;
+    this.compileRoot = void 0;
+    const active = this.build;
+    this.build = void 0;
+    if (active !== void 0) {
+      active.reject(new Error(`ScriptablePack build disposed during ${reason}`));
+    }
+    this.disposal = (async () => {
+      if (worker !== void 0) await worker.terminate();
+      if (compileRoot !== void 0) await rm(compileRoot, { recursive: true, force: true });
+    })();
+    return this.disposal;
+  }
+  runBuild(reader) {
+    const worker = this.worker;
+    if (worker === void 0) return Promise.reject(new Error("ScriptablePack worker is closed"));
+    if (this.build !== void 0)
+      return Promise.reject(new Error("ScriptablePack worker already has an active build"));
+    const id = this.nextBuildId++;
+    return new Promise((resolveBuild, rejectBuild) => {
+      this.build = { id, reader, resolve: resolveBuild, reject: rejectBuild };
+      worker.postMessage({ kind: "build", buildId: id });
+    });
+  }
+  onMessage(message) {
+    if (message === null || typeof message !== "object") return;
+    const value = message;
+    const active = this.build;
+    if (active === void 0 || value.buildId !== active.id) return;
+    if (value.kind === "asset-read" && typeof value.readId === "number") {
+      void active.reader.readByGuid(value.guid).then(
+        (result) => this.worker?.postMessage({
+          kind: "asset-result",
+          readId: value.readId,
+          result: result.ok === true ? result : { ...result, error: serializeFailure(result.error) }
+        })
+      ).catch((error) => {
+        if (this.build?.id !== active.id) return;
+        this.build = void 0;
+        active.reject(error);
+        void this.dispose("failure");
+      });
+      return;
+    }
+    this.build = void 0;
+    if (value.kind === "build-result") active.resolve(value.result);
+    else if (value.kind === "build-threw") active.reject(hydrateFailure(value.error));
+    else this.build = active;
+  }
+};
+function scriptablePackWorkerUrl() {
+  const bundledWorker = new URL("./scriptable-pack-worker.mjs", import.meta.url);
+  return existsSync(fileURLToPath(bundledWorker)) ? bundledWorker : new URL("../dist/scriptable-pack-worker.mjs", import.meta.url);
+}
+var ReusableWorkerScriptablePackExecutor = class {
+  constructor(maxTasksPerWorker, release) {
+    this.maxTasksPerWorker = maxTasksPerWorker;
+    this.release = release;
+    this.worker = new Worker(scriptablePackWorkerUrl(), {
+      workerData: { mode: "reusable" },
+      execArgv: scriptablePackWorkerExecArgv(),
+      resourceLimits: { maxOldGenerationSizeMb: 256, maxYoungGenerationSizeMb: 64 }
+    });
+    this.worker.on("message", (message) => this.onMessage(message));
+    this.worker.on("error", (error) => {
+      this.failed = true;
+      this.rejectActive(error);
+      void this.dispose("failure");
+    });
+    this.worker.on("exit", (code) => {
+      if (code === 0 || this.disposal !== void 0) return;
+      this.failed = true;
+      this.rejectActive(new Error(`ScriptablePack worker exited with code ${code}`));
+      void this.dispose("failure");
+    });
+    this.worker.unref();
+  }
+  maxTasksPerWorker;
+  release;
+  worker;
+  compileRootReady = mkdtemp(resolve(tmpdir(), "forgeax-scriptable-pack-pool-"));
+  compileRoot;
+  nextLoadId = 0;
+  nextBuildId = 0;
+  pendingLoad;
+  build;
+  disposal;
+  forceDispose = false;
+  failed = false;
+  taskCount = 0;
+  released = false;
+  async load(sourcePath) {
+    const activeDisposal = this.disposal;
+    if (activeDisposal !== void 0) {
+      await activeDisposal;
+      if (this.failed) {
+        return Promise.reject(new Error("ScriptablePack executor is not leased"));
+      }
+      this.disposal = void 0;
+    }
+    this.released = false;
+    if (this.pendingLoad !== void 0 || this.build !== void 0) {
+      return Promise.reject(new Error("ScriptablePack executor already has an active task"));
+    }
+    const compileRoot = this.compileRoot ?? await this.compileRootReady;
+    if (this.disposal !== void 0) {
+      const disposal = this.disposal;
+      await disposal;
+      if (this.failed) {
+        return Promise.reject(new Error("ScriptablePack executor is not leased"));
+      }
+      this.disposal = void 0;
+    }
+    const loadId = this.nextLoadId++;
+    this.compileRoot = compileRoot;
+    this.taskCount += 1;
+    return new Promise((resolveLoad, rejectLoad) => {
+      this.pendingLoad = { id: loadId, resolve: resolveLoad, reject: rejectLoad };
+      try {
+        this.worker.postMessage({
+          kind: "load",
+          loadId,
+          sourcePath: resolve(sourcePath),
+          compileRoot
+        });
+      } catch (error) {
+        this.pendingLoad = void 0;
+        rejectLoad(error);
+        void this.dispose("failure");
+      }
+    });
+  }
+  dispose(reason = "complete") {
+    if (reason === "failure") this.forceDispose = true;
+    const activeDisposal = this.disposal;
+    if (activeDisposal !== void 0) {
+      return activeDisposal;
+    }
+    this.rejectActive(new Error(`ScriptablePack task disposed during ${reason}`));
+    this.disposal = (async () => {
+      const compileRoot = this.compileRoot ?? await this.compileRootReady;
+      const reusable = reason === "complete" && !this.failed && !this.forceDispose && this.taskCount < this.maxTasksPerWorker;
+      this.forceDispose = false;
+      if (!reusable) {
+        this.compileRoot = void 0;
+        await this.worker.terminate();
+        await rm(compileRoot, { recursive: true, force: true });
+      }
+      this.released = true;
+      this.disposal = void 0;
+      this.release(this, reusable);
+    })();
+    return this.disposal;
+  }
+  rejectActive(error) {
+    const loading = this.pendingLoad;
+    this.pendingLoad = void 0;
+    loading?.reject(error);
+    const building = this.build;
+    this.build = void 0;
+    building?.reject(error);
+  }
+  runBuild(reader) {
+    if (this.released || this.disposal !== void 0) {
+      return Promise.reject(new Error("ScriptablePack executor is not leased"));
+    }
+    if (this.build !== void 0) {
+      return Promise.reject(new Error("ScriptablePack worker already has an active build"));
+    }
+    const id = this.nextBuildId++;
+    return new Promise((resolveBuild, rejectBuild) => {
+      this.build = { id, reader, resolve: resolveBuild, reject: rejectBuild };
+      try {
+        this.worker.postMessage({ kind: "build", buildId: id });
+      } catch (error) {
+        this.build = void 0;
+        rejectBuild(error);
+        void this.dispose("failure");
+      }
+    });
+  }
+  onMessage(message) {
+    if (message === null || typeof message !== "object") return;
+    const value = message;
+    const loading = this.pendingLoad;
+    if (loading !== void 0 && value.kind === "loaded" && value.loadId === loading.id) {
+      this.pendingLoad = void 0;
+      loading.resolve({
+        default: value.definition === void 0 ? void 0 : {
+          ...value.definition,
+          build: (reader) => this.runBuild(reader)
+        }
+      });
+      return;
+    }
+    if (loading !== void 0 && value.kind === "load-threw" && value.loadId === loading.id) {
+      this.pendingLoad = void 0;
+      loading.reject(hydrateFailure(value.error));
+      return;
+    }
+    const active = this.build;
+    if (active === void 0 || value.buildId !== active.id) return;
+    if (value.kind === "asset-read" && typeof value.readId === "number") {
+      void active.reader.readByGuid(value.guid).then(
+        (result) => this.worker.postMessage({
+          kind: "asset-result",
+          readId: value.readId,
+          result: result.ok === true ? result : { ...result, error: serializeFailure(result.error) }
+        })
+      ).catch((error) => {
+        if (this.build?.id !== active.id) return;
+        this.build = void 0;
+        active.reject(error);
+        void this.dispose("failure");
+      });
+      return;
+    }
+    this.build = void 0;
+    if (value.kind === "build-result") active.resolve(value.result);
+    else if (value.kind === "build-threw") active.reject(hydrateFailure(value.error));
+    else this.build = active;
+  }
+};
+var DefaultScriptablePackModuleExecutorPool = class {
+  maxWorkers;
+  maxTasksPerWorker;
+  idle = [];
+  waiters = [];
+  executors = /* @__PURE__ */ new Set();
+  workerCount = 0;
+  closed = false;
+  constructor(options = {}) {
+    this.maxWorkers = Math.max(1, Math.trunc(options.maxWorkers ?? 2));
+    this.maxTasksPerWorker = Math.max(1, Math.trunc(options.maxTasksPerWorker ?? 32));
+  }
+  acquire() {
+    if (this.closed) return Promise.reject(new Error("ScriptablePack executor pool is closed"));
+    const executor = this.idle.pop();
+    if (executor !== void 0) return Promise.resolve(executor);
+    if (this.workerCount < this.maxWorkers) {
+      this.workerCount += 1;
+      return Promise.resolve(this.createExecutor());
+    }
+    return new Promise(
+      (resolveAcquire, rejectAcquire) => this.waiters.push({ resolve: resolveAcquire, reject: rejectAcquire })
+    );
+  }
+  async dispose() {
+    if (this.closed) return;
+    this.closed = true;
+    const waiters = this.waiters.splice(0);
+    for (const waiter of waiters) {
+      waiter.reject(new Error("ScriptablePack executor pool is closed"));
+    }
+    this.idle.splice(0);
+    await Promise.all([...this.executors].map((executor) => executor.dispose("failure")));
+  }
+  createExecutor() {
+    const executor = new ReusableWorkerScriptablePackExecutor(
+      this.maxTasksPerWorker,
+      (executor2, reusable) => {
+        if (this.closed) {
+          this.executors.delete(executor2);
+          if (!reusable) this.workerCount -= 1;
+          return;
+        }
+        if (!reusable) {
+          this.executors.delete(executor2);
+          this.workerCount -= 1;
+        } else {
+          this.idle.push(executor2);
+        }
+        this.drain();
+      }
+    );
+    this.executors.add(executor);
+    return executor;
+  }
+  drain() {
+    if (this.closed) return;
+    while (this.waiters.length > 0) {
+      const idle = this.idle.pop();
+      if (idle !== void 0) {
+        this.waiters.shift()?.resolve(idle);
+        continue;
+      }
+      if (this.workerCount >= this.maxWorkers) return;
+      this.workerCount += 1;
+      this.waiters.shift()?.resolve(this.createExecutor());
+    }
+  }
+};
+function createScriptablePackModuleExecutorPool(options = {}) {
+  return new DefaultScriptablePackModuleExecutorPool(options);
+}
+function loadFailure(sourcePath, reason, phase, diagnostic, timeoutMs) {
+  return err({
+    code: "pack-source-load-failed",
+    expected: "a trusted synchronous module with a valid default ScriptablePack export",
+    hint: "repair the module load or initialization failure, then inspect Meta again",
+    detail: {
+      sourcePath,
+      reason,
+      phase,
+      diagnostic,
+      ...timeoutMs === void 0 ? {} : { timeoutMs }
+    }
+  });
+}
+function buildTimeoutFailure(sourcePath, timeoutMs) {
+  return {
+    code: "pack-source-load-failed",
+    expected: "a ScriptablePack build to settle within the configured build timeout",
+    hint: "repair the authored build, then retry through a fresh ScriptablePack generation",
+    detail: {
+      sourcePath,
+      reason: "timeout",
+      phase: "build",
+      timeoutMs,
+      diagnostic: `ScriptablePack build exceeded ${timeoutMs}ms`
+    }
+  };
+}
+async function loadScriptablePack(sourcePath, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const buildTimeoutMs = options.buildTimeoutMs ?? 5e3;
+  const executor = options.executor ?? new WorkerScriptablePackExecutor();
+  let disposeReason;
+  let timeout;
+  try {
+    const timeoutSignal = /* @__PURE__ */ Symbol("scriptable-pack-module-timeout");
+    const loaded = await Promise.race([
+      executor.load(sourcePath),
+      new Promise((resolve3) => {
+        timeout = setTimeout(() => resolve3(timeoutSignal), timeoutMs);
+      })
+    ]);
+    if (loaded === timeoutSignal) {
+      disposeReason = "timeout";
+      return loadFailure(
+        sourcePath,
+        "timeout",
+        "module-load",
+        `ScriptablePack module initialization exceeded ${timeoutMs}ms`,
+        timeoutMs
+      );
+    }
+    const moduleValue = loaded !== null && typeof loaded === "object" && "default" in loaded ? loaded.default : void 0;
+    const validated = validateScriptablePackDefinition(moduleValue, sourcePath);
+    if (!validated.ok) {
+      disposeReason = "failure";
+      return validated;
+    }
+    if (options.metadataOnly === true) {
+      disposeReason = "complete";
+      return validated;
+    }
+    const definition = validated.value;
+    return ok({
+      ...definition,
+      build: async (reader) => {
+        let buildTimedOut = false;
+        let buildTimeout;
+        const timeoutResult = err(buildTimeoutFailure(sourcePath, buildTimeoutMs));
+        try {
+          const built = await Promise.race([
+            Promise.resolve(definition.build(reader)),
+            new Promise((resolve3) => {
+              buildTimeout = setTimeout(() => {
+                buildTimedOut = true;
+                resolve3(timeoutResult);
+              }, buildTimeoutMs);
+            })
+          ]);
+          if (buildTimedOut) {
+            await executor.dispose?.("timeout");
+            return built;
+          }
+          await executor.dispose?.("complete");
+          return built;
+        } catch (error) {
+          await executor.dispose?.("failure");
+          throw error;
+        } finally {
+          if (buildTimeout !== void 0) clearTimeout(buildTimeout);
+        }
+      }
+    });
+  } catch (error) {
+    const diagnostic = error instanceof Error ? error.message : String(error);
+    disposeReason = "failure";
+    return loadFailure(sourcePath, "module-load", "module-load", diagnostic);
+  } finally {
+    if (timeout !== void 0) clearTimeout(timeout);
+    if (disposeReason !== void 0) await executor.dispose?.(disposeReason);
+  }
+}
+var CANONICAL_SCAFFOLD_MARKER = "// @forgeax-scriptable-pack canonical-v1";
+var CANONICAL_MANIFEST_NAME = "canonicalManifest";
+var CANONICAL_MUTABLE_KINDS = /* @__PURE__ */ new Set(["scene", "mesh", "material"]);
+function authoringError(code, input) {
+  return {
+    code,
+    expected: input.expected,
+    ...input.actual === void 0 ? {} : { actual: input.actual },
+    hint: input.hint,
+    retryable: input.retryable,
+    recoveryActions: input.recoveryActions,
+    detail: {
+      ...input.requestId === void 0 ? {} : { requestId: input.requestId },
+      ...input.sourcePath === void 0 ? {} : { sourcePath: input.sourcePath },
+      ...input.sourceKey === void 0 ? {} : { sourceKey: input.sourceKey },
+      ...input.incomingRefs === void 0 ? {} : { incomingRefs: input.incomingRefs }
+    }
+  };
+}
+function confinedSourcePath(gameRoot, sourcePath) {
+  const root = resolve(gameRoot);
+  const absolute = resolve(root, sourcePath);
+  const rel = relative(root, absolute);
+  if (rel.length === 0 || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(sourcePath) || !rel.endsWith(".pack.ts")) {
+    return err(
+      authoringError("pack-source-path-invalid", {
+        expected: "a game-root-relative *.pack.ts path confined to the selected game",
+        actual: sourcePath,
+        hint: "choose a relative ScriptablePack source path inside the selected game root",
+        retryable: false,
+        recoveryActions: ["choose-game-relative-source-path"],
+        sourcePath
+      })
+    );
+  }
+  return ok({ absolute, relative: rel.split(sep).join("/") });
+}
+function revisionOf(source) {
+  return createHash("sha256").update(source).digest("hex");
+}
+function unwrapExpression(expression) {
+  if (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isParenthesizedExpression(expression)) {
+    return unwrapExpression(expression.expression);
+  }
+  return expression;
+}
+function literalValue(expression) {
+  const value = unwrapExpression(expression);
+  if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) return value.text;
+  if (value.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (value.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (value.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isNumericLiteral(value)) return Number(value.text);
+  if (ts.isArrayLiteralExpression(value)) return value.elements.map(literalValue);
+  if (ts.isObjectLiteralExpression(value)) {
+    const result = {};
+    for (const property of value.properties) {
+      if (!ts.isPropertyAssignment(property))
+        throw new TypeError("manifest properties must be data");
+      const name = property.name;
+      const key = ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name) ? name.text : void 0;
+      if (key === void 0) throw new TypeError("manifest property names must be static");
+      result[key] = literalValue(property.initializer);
+    }
+    return result;
+  }
+  throw new TypeError("manifest values must be literal data");
+}
+function parseCanonicalManifest(source, sourcePath) {
+  if (!source.startsWith(`${CANONICAL_SCAFFOLD_MARKER}
+`)) return void 0;
+  const file = ts.createSourceFile(
+    sourcePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS
+  );
+  for (const statement of file.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === CANONICAL_MANIFEST_NAME && declaration.initializer !== void 0) {
+        const value = literalValue(declaration.initializer);
+        if (value === null || typeof value !== "object") return void 0;
+        return value;
+      }
+    }
+  }
+  return void 0;
+}
+function guidExpression(value) {
+  return `parseGuid(${JSON.stringify(value)})`;
+}
+function renderCanonicalScriptablePack(manifest) {
+  const data = JSON.stringify(manifest, null, 2);
+  return `${CANONICAL_SCAFFOLD_MARKER}
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
+import type { ScriptablePackDefinition } from '@forgeax/engine-pack/source';
+import type { Asset, AssetGuid as AssetGuidType } from '@forgeax/engine-types';
+import { ok } from '@forgeax/engine-types';
+
+const ${CANONICAL_MANIFEST_NAME} = ${data} as const;
+
+function parseGuid(value: string): AssetGuidType {
+  const parsed = AssetGuid.parse(value);
+  if (!parsed.ok) throw parsed.error;
+  return parsed.value;
+}
+
+function createOutput(kind: string): Asset {
+  switch (kind) {
+    case 'scene':
+      return { kind: 'scene', entities: [], mounts: [] };
+    case 'material':
+      return { kind: 'material', values: {} };
+    case 'mesh': {
+      const vertices = new Float32Array([
+        0, 0.7, 0, 0, 0, 1, 0.5, 1, 0, 0, 0, 1,
+        -0.7, -0.6, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1,
+        0.7, -0.6, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1,
+      ]);
+      return {
+        kind: 'mesh',
+        vertices,
+        indices: new Uint16Array([0, 1, 2]),
+        attributes: { ...buildMeshAttributeMapForUvSets(1), position: vertices },
+        aabb: new Float32Array([-0.7, -0.6, 0, 0.7, 0.7, 0]),
+        submeshes: [{ indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 }],
+        materialSlots: [{ slotName: 'Default' }],
+      };
+    }
+    default:
+      throw new Error(\`canonical ScriptablePack output kind is not mutable: \${kind}\`);
+  }
+}
+
+const assets = Object.fromEntries(
+  Object.entries(${CANONICAL_MANIFEST_NAME}.assets).map(([sourceKey, asset]) => [
+    sourceKey,
+    { ...asset, guid: parseGuid(asset.guid) },
+  ]),
+);
+const externalAssets = Object.fromEntries(
+  Object.entries(${CANONICAL_MANIFEST_NAME}.externalAssets).map(([alias, guid]) => [alias, parseGuid(guid)]),
+);
+
+export default {
+  schemaVersion: '1.0.0',
+  packageId: ${guidExpression(manifest.packageId)},
+  ${manifest.name === void 0 ? "" : `name: ${JSON.stringify(manifest.name)},
+  `}assets,
+  externalAssets,
+  build: () => ok(Object.fromEntries(Object.entries(assets).map(([sourceKey, asset]) => [sourceKey, createOutput(asset.kind)])) as never),
+} satisfies ScriptablePackDefinition;
+`;
+}
+function definitionFromCanonical(manifest) {
+  const packageId = AssetGuid.parse(manifest.packageId);
+  if (!packageId.ok) return invalidCanonicalGuid("$.packageId", manifest.packageId);
+  const assets = {};
+  for (const [sourceKey, output] of Object.entries(manifest.assets)) {
+    const guid = AssetGuid.parse(output.guid);
+    if (!guid.ok)
+      return invalidCanonicalGuid(`$.assets[${JSON.stringify(sourceKey)}].guid`, output.guid);
+    assets[sourceKey] = {
+      guid: guid.value,
+      kind: output.kind,
+      ...output.name === void 0 ? {} : { name: output.name }
+    };
+  }
+  const externalAssets = {};
+  for (const [alias, value] of Object.entries(manifest.externalAssets)) {
+    const guid = AssetGuid.parse(value);
+    if (!guid.ok) return invalidCanonicalGuid(`$.externalAssets[${JSON.stringify(alias)}]`, value);
+    externalAssets[alias] = guid.value;
+  }
+  return validateScriptablePackDefinition({
+    schemaVersion: "1.0.0",
+    packageId: packageId.value,
+    ...manifest.name === void 0 ? {} : { name: manifest.name },
+    assets,
+    externalAssets,
+    build: () => ok({})
+  });
+}
+function invalidCanonicalGuid(propertyPath, actual2) {
+  return err({
+    code: "pack-source-definition-invalid",
+    expected: "a canonical UUID string",
+    hint: "repair the canonical scaffold manifest GUID and inspect Meta again",
+    detail: { propertyPath, actual: actual2 }
+  });
+}
+function invalidCanonicalSource(sourcePath, error) {
+  return err({
+    code: "pack-source-definition-invalid",
+    expected: "a literal canonical-v1 manifest with the required package/assets/external fields",
+    hint: "repair the canonical scaffold or open it as custom source without structured mutation",
+    detail: {
+      sourcePath,
+      propertyPath: "$.canonicalManifest",
+      actual: error instanceof Error ? error.message : String(error)
+    }
+  });
+}
+async function atomicWrite(path, source) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporary, source, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+function sameStrings(left, right) {
+  return [...left].sort().join("\0") === [...right].sort().join("\0");
+}
+function createFileSystemScriptablePackAuthoringPort(options) {
+  const resolvePath = (sourcePath) => confinedSourcePath(options.gameRoot, sourcePath);
+  async function readSource(sourcePath) {
+    const path = resolvePath(sourcePath);
+    if (!path.ok) return path;
+    try {
+      const source = await readFile(path.value.absolute, "utf8");
+      return ok({ ...path.value, source, revision: revisionOf(source) });
+    } catch (error) {
+      return err(
+        authoringError("pack-source-write-failed", {
+          expected: "a readable ScriptablePack source file",
+          actual: error instanceof Error ? error.message : String(error),
+          hint: "restore the source file or create it through the ScriptablePack gateway",
+          retryable: true,
+          recoveryActions: ["inspect-source-path", "retry"],
+          sourcePath
+        })
+      );
+    }
+  }
+  async function inspect(sourcePath) {
+    const read = await readSource(sourcePath);
+    if (!read.ok) return read;
+    let canonical;
+    try {
+      canonical = parseCanonicalManifest(read.value.source, read.value.relative);
+    } catch (error) {
+      return invalidCanonicalSource(read.value.relative, error);
+    }
+    const loaded = canonical === void 0 ? await loadScriptablePack(read.value.absolute, { metadataOnly: true }) : definitionFromCanonical(canonical);
+    if (!loaded.ok) return loaded;
+    return ok({
+      revision: read.value.revision,
+      meta: projectScriptablePackMeta(loaded.value, read.value.relative)
+    });
+  }
+  async function preflight(sourcePath) {
+    const read = await readSource(sourcePath);
+    if (!read.ok) return read;
+    const inspected = await inspect(sourcePath);
+    if (!inspected.ok) return inspected;
+    let canonical;
+    try {
+      canonical = parseCanonicalManifest(read.value.source, read.value.relative);
+    } catch (error) {
+      return invalidCanonicalSource(read.value.relative, error);
+    }
+    const incomingRefs = await options.incomingRefs?.(read.value.relative) ?? [];
+    return ok({
+      revision: inspected.value.revision,
+      meta: inspected.value.meta,
+      capabilities: canonical === void 0 ? {
+        inspect: true,
+        rebuild: true,
+        coldCook: true,
+        reason: "structured mutation is available only for canonical-v1 scaffolds"
+      } : {
+        inspect: true,
+        rebuild: true,
+        coldCook: true,
+        addOutput: true,
+        addExternalAsset: true,
+        renameDisplay: true,
+        removeOutput: true,
+        clone: true
+      },
+      incomingRefs
+    });
+  }
+  async function mutate(operation) {
+    const targetPath = operation.kind === "clone-scriptable-pack" ? operation.targetPath : operation.sourcePath;
+    const target = resolvePath(targetPath);
+    if (!target.ok) return target;
+    let manifest;
+    let currentRevision;
+    if (operation.kind === "create-scriptable-pack") {
+      if (!CANONICAL_MUTABLE_KINDS.has(operation.initialOutput.kind)) {
+        return err(
+          authoringError("pack-source-mutation-unsupported", {
+            expected: "a canonical scene, mesh, or material initial output",
+            actual: operation.initialOutput.kind,
+            hint: "create one of the canonical output kinds, then hand-author advanced outputs",
+            retryable: false,
+            recoveryActions: ["choose-supported-output-kind"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath
+          })
+        );
+      }
+      try {
+        await stat(target.value.absolute);
+        return err(
+          authoringError("pack-source-revision-conflict", {
+            expected: "an unused target source path",
+            actual: "source already exists",
+            hint: "inspect the existing source or choose a new path",
+            retryable: false,
+            recoveryActions: ["asset.preflight", "choose-new-source-path"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath
+          })
+        );
+      } catch {
+      }
+      manifest = {
+        schemaVersion: "1.0.0",
+        packageId: AssetGuid.format(operation.packageId),
+        ...operation.name === void 0 ? {} : { name: operation.name },
+        assets: {
+          [operation.initialOutput.sourceKey]: {
+            guid: AssetGuid.format(operation.initialOutput.guid),
+            kind: operation.initialOutput.kind,
+            ...operation.initialOutput.name === void 0 ? {} : { name: operation.initialOutput.name }
+          }
+        },
+        externalAssets: {}
+      };
+    } else {
+      const read = await readSource(operation.sourcePath);
+      if (!read.ok) return read;
+      currentRevision = read.value.revision;
+      if (operation.expectedRevision !== void 0 && operation.expectedRevision !== currentRevision) {
+        return err(
+          authoringError("pack-source-revision-conflict", {
+            expected: operation.expectedRevision,
+            actual: currentRevision,
+            hint: "inspect the current source revision, reconcile the edit, then retry with a new requestId",
+            retryable: true,
+            recoveryActions: ["asset.preflight", "mint-request-id"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath
+          })
+        );
+      }
+      let parsed;
+      try {
+        parsed = parseCanonicalManifest(read.value.source, read.value.relative);
+      } catch (error) {
+        return invalidCanonicalSource(read.value.relative, error);
+      }
+      if (parsed === void 0) {
+        return err(
+          authoringError("pack-source-mutation-unsupported", {
+            expected: "a canonical-v1 scaffold for structured source mutation",
+            actual: "custom ScriptablePack source",
+            hint: "clone into a canonical scaffold or edit custom source with a code editor",
+            retryable: false,
+            recoveryActions: ["clone-scriptable-pack", "open-code-editor"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath
+          })
+        );
+      }
+      manifest = parsed;
+    }
+    if (operation.kind === "clone-scriptable-pack") {
+      try {
+        await stat(target.value.absolute);
+        return err(
+          authoringError("pack-source-revision-conflict", {
+            expected: "an unused clone target source path",
+            actual: "source already exists",
+            hint: "inspect the existing target or choose a new path",
+            retryable: false,
+            recoveryActions: ["asset.preflight", "choose-new-source-path"],
+            requestId: operation.requestId,
+            sourcePath: target.value.relative
+          })
+        );
+      } catch {
+      }
+    }
+    if (operation.kind === "add-output") {
+      if (!CANONICAL_MUTABLE_KINDS.has(operation.assetKind)) {
+        return err(
+          authoringError("pack-source-mutation-unsupported", {
+            expected: "a canonical scene, mesh, or material output",
+            actual: operation.assetKind,
+            hint: "hand-author advanced output kinds in the source module",
+            retryable: false,
+            recoveryActions: ["open-code-editor"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath,
+            sourceKey: operation.sourceKey
+          })
+        );
+      }
+      manifest = {
+        ...manifest,
+        assets: {
+          ...manifest.assets,
+          [operation.sourceKey]: {
+            guid: AssetGuid.format(operation.guid),
+            kind: operation.assetKind,
+            ...operation.name === void 0 ? {} : { name: operation.name }
+          }
+        }
+      };
+    } else if (operation.kind === "add-external-asset") {
+      manifest = {
+        ...manifest,
+        externalAssets: {
+          ...manifest.externalAssets,
+          [operation.alias]: AssetGuid.format(operation.guid)
+        }
+      };
+    } else if (operation.kind === "rename-display") {
+      if (operation.target.kind === "package") manifest = { ...manifest, name: operation.name };
+      else {
+        const output = manifest.assets[operation.target.sourceKey];
+        if (output === void 0)
+          return err(
+            authoringError("pack-source-mutation-unsupported", {
+              expected: "an existing sourceKey",
+              actual: operation.target.sourceKey,
+              hint: "inspect Meta and choose a current output",
+              retryable: true,
+              recoveryActions: ["asset.preflight"],
+              requestId: operation.requestId,
+              sourcePath: operation.sourcePath,
+              sourceKey: operation.target.sourceKey
+            })
+          );
+        manifest = {
+          ...manifest,
+          assets: {
+            ...manifest.assets,
+            [operation.target.sourceKey]: { ...output, name: operation.name }
+          }
+        };
+      }
+    } else if (operation.kind === "remove-output") {
+      const incomingRefs = await options.incomingRefs?.(operation.sourcePath, operation.sourceKey) ?? [];
+      if (incomingRefs.length > 0 && !sameStrings(incomingRefs, operation.confirmIncomingRefs ?? [])) {
+        return err(
+          authoringError("pack-source-reference-conflict", {
+            expected: "explicit acknowledgement of every current incoming reference",
+            actual: `${incomingRefs.length} incoming references`,
+            hint: "inspect dependents, then confirm the exact incoming reference identities or cancel",
+            retryable: true,
+            recoveryActions: ["inspect-incoming-refs", "confirm-remove-output"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath,
+            sourceKey: operation.sourceKey,
+            incomingRefs
+          })
+        );
+      }
+      const { [operation.sourceKey]: removed, ...assets } = manifest.assets;
+      if (removed === void 0 || Object.keys(assets).length === 0) {
+        return err(
+          authoringError("pack-source-mutation-unsupported", {
+            expected: "an existing output while retaining at least one package output",
+            actual: operation.sourceKey,
+            hint: "keep one output or remove the entire source file through an explicit file operation",
+            retryable: false,
+            recoveryActions: ["asset.preflight"],
+            requestId: operation.requestId,
+            sourcePath: operation.sourcePath,
+            sourceKey: operation.sourceKey
+          })
+        );
+      }
+      manifest = { ...manifest, assets };
+    } else if (operation.kind === "clone-scriptable-pack") {
+      manifest = {
+        ...manifest,
+        packageId: AssetGuid.format(operation.packageId),
+        assets: Object.fromEntries(
+          Object.entries(manifest.assets).map(([sourceKey, output]) => [
+            sourceKey,
+            {
+              ...output,
+              guid: AssetGuid.format(operation.outputGuids[sourceKey])
+            }
+          ])
+        )
+      };
+    }
+    const source = renderCanonicalScriptablePack(manifest);
+    try {
+      await atomicWrite(target.value.absolute, source);
+      return ok({ sourcePath: target.value.relative, revision: revisionOf(source) });
+    } catch (error) {
+      return err(
+        authoringError("pack-source-write-failed", {
+          expected: "an atomic source-file replacement",
+          actual: error instanceof Error ? error.message : String(error),
+          hint: "repair filesystem permissions or disk capacity, then retry with a new requestId",
+          retryable: true,
+          recoveryActions: ["inspect-filesystem", "mint-request-id"],
+          requestId: operation.requestId,
+          sourcePath: target.value.relative
+        })
+      );
+    }
+  }
+  return {
+    preflight,
+    mutate,
+    inspect,
+    async rebuild(sourcePath, mode) {
+      const path = resolvePath(sourcePath);
+      if (!path.ok) return path;
+      const rebuilt = await options.rebuild?.(path.value.relative, mode) ?? ok(void 0);
+      return rebuilt.ok ? inspect(path.value.relative) : rebuilt;
+    }
+  };
+}
+
+export { createFileSystemScriptablePackAuthoringPort, createScriptablePackModuleExecutorPool, inventoryScriptablePackSource, loadScriptablePack, readOptionalBuildCache, renderCanonicalScriptablePack, scriptablePackDdcKey };
+//# sourceMappingURL=scriptable-pack-node.mjs.map
+//# sourceMappingURL=scriptable-pack-node.mjs.map