@forgeax/engine-ddc 0.0.0-dev.8d955ade1c79

package/dist/index.mjs

@@ -0,0 +1,1574 @@
+import { existsSync } from 'fs';
+import { resolve, join, dirname, isAbsolute, normalize } from 'path';
+import { createHash, randomUUID } from 'crypto';
+import { mkdir, writeFile, rm, stat, rename, readdir, readFile } from 'fs/promises';
+import { err, ok } from '@forgeax/engine-types';
+
+// src/build-cache.ts
+function canonicalDdcJson(value) {
+  const sorted = sortValue(value);
+  return JSON.stringify(sorted) ?? "null";
+}
+function sortValue(value) {
+  if (value instanceof Uint8Array) {
+    return { encoding: "base64", bytes: Buffer.from(value).toString("base64") };
+  }
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+      result[key] = sortValue(value[key]);
+    }
+    return result;
+  }
+  return value;
+}
+function semanticDdcKey(input) {
+  const semantic = {
+    schemaVersion: input.schemaVersion,
+    importer: input.importer,
+    codec: input.codec,
+    settings: input.settings,
+    sourceBytes: input.sourceBytes,
+    declaredGuids: [...input.declaredGuids].sort(),
+    targetProfile: input.targetProfile,
+    producer: input.producer
+  };
+  return createHash("sha256").update(canonicalDdcJson(semantic)).digest("hex");
+}
+
+// src/build-cache.ts
+function resolveDdcRoot(cwd) {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(join(current, "pnpm-workspace.yaml"))) {
+      return join(current, "node_modules/.cache/forgeax-ddc");
+    }
+    const parent = dirname(current);
+    if (parent === current) return join(resolve(cwd), "node_modules/.cache/forgeax-ddc");
+    current = parent;
+  }
+}
+function semanticBuildKey(input) {
+  const hasSourceOverrides = input.sourceOverrides !== void 0 && typeof input.sourceOverrides === "object" && input.sourceOverrides !== null && !Array.isArray(input.sourceOverrides) && Object.keys(input.sourceOverrides).length > 0;
+  const settings = hasSourceOverrides ? { settings: input.settings, sourceOverrides: input.sourceOverrides } : input.settings;
+  return semanticDdcKey({
+    schemaVersion: input.schemaVersion,
+    importer: input.importerVersion,
+    codec: input.codecVersion,
+    settings,
+    sourceBytes: input.sourceDependencies.map(
+      (dependency) => typeof dependency === "string" ? dependency.replaceAll("\\", "/").replace(/^.*\/(assets\/)/, "$1") : dependency.digest
+    ).sort().map((digest3) => new TextEncoder().encode(digest3)),
+    declaredGuids: input.declaredGuids,
+    targetProfile: input.cookProfile,
+    producer: input.importerVersion
+  });
+}
+
+// src/errors.ts
+var DDC_ERROR_CODES = [
+  "ddc-project-root-required",
+  "ddc-object-conflict",
+  "ddc-head-conflict",
+  "ddc-generation-conflict",
+  "ddc-scope-mismatch",
+  "ddc-lease-expired"
+];
+var defaultHints = {
+  "ddc-project-root-required": "inject the canonical projectDdcRoot before serving or publishing",
+  "ddc-object-conflict": "keep the verified object and reject the competing publication",
+  "ddc-head-conflict": "inspect the current head and retry with a fresh revision",
+  "ddc-generation-conflict": "allocate a new persistent generation; do not edit the counter",
+  "ddc-scope-mismatch": "reinspect the canonical root and allocate a new scope",
+  "ddc-lease-expired": "discard the stale commit and acquire a new lease",
+  "ddc-entry-incomplete": "discard the partial entry and cold-cook from author authority",
+  "ddc-entry-invalid": "preserve last-known-good, inspect the entry, then cold-cook",
+  "ddc-entry-conflict": "keep the verified entry and reject the competing publication"
+};
+function defaultExpected(code) {
+  if (code === "ddc-project-root-required") return "projectDdcRoot";
+  if (code === "ddc-entry-incomplete" || code === "ddc-entry-invalid") {
+    return "a complete DDC entry whose receipt and integrity digests validate";
+  }
+  return "a valid DDC owner, scope, generation, revision, and lease";
+}
+function defaultActions(code) {
+  switch (code) {
+    case "ddc-project-root-required":
+    case "ddc-scope-mismatch":
+      return [
+        { kind: "inspect", executable: true },
+        { kind: "retry", executable: true }
+      ];
+    case "ddc-generation-conflict":
+      return [{ kind: "allocate-generation", executable: true }];
+    case "ddc-lease-expired":
+      return [
+        { kind: "release-lease", executable: true },
+        { kind: "retry", executable: true }
+      ];
+    case "ddc-object-conflict":
+    case "ddc-head-conflict":
+      return [
+        { kind: "inspect", executable: true },
+        { kind: "retry", executable: true }
+      ];
+    case "ddc-entry-incomplete":
+    case "ddc-entry-invalid":
+      return [{ kind: "cold-rebuild", executable: true }];
+    case "ddc-entry-conflict":
+      return [{ kind: "inspect", executable: true }];
+  }
+}
+var DdcStoreError = class extends Error {
+  code;
+  detail;
+  hint;
+  expected;
+  actual;
+  owner;
+  rootKind;
+  scope;
+  generation;
+  lease;
+  revision;
+  recoveryActions;
+  hostPath;
+  constructor(inputOrCode, legacyDetail) {
+    const input = typeof inputOrCode === "string" ? { code: inputOrCode, detail: legacyDetail ?? inputOrCode } : inputOrCode;
+    super(input.detail);
+    this.name = "DdcStoreError";
+    this.code = input.code;
+    this.detail = input.detail;
+    this.hint = input.hint ?? defaultHints[input.code];
+    this.expected = input.expected ?? defaultExpected(input.code);
+    this.actual = input.actual;
+    this.owner = input.owner;
+    this.rootKind = input.rootKind;
+    this.scope = input.scope;
+    this.generation = input.generation;
+    this.lease = input.lease;
+    this.revision = input.revision;
+    this.recoveryActions = input.recoveryActions ?? defaultActions(input.code);
+    this.hostPath = input.hostPath;
+  }
+  toBrowserProjection() {
+    return {
+      code: this.code,
+      hint: this.hint,
+      expected: this.expected,
+      ...this.actual === void 0 ? {} : { actual: this.actual },
+      ...this.owner === void 0 ? {} : { owner: this.owner },
+      ...this.rootKind === void 0 ? {} : { rootKind: this.rootKind },
+      ...this.scope === void 0 ? {} : { scope: this.scope },
+      ...this.generation === void 0 ? {} : { generation: this.generation },
+      ...this.lease === void 0 ? {} : { lease: this.lease },
+      ...this.revision === void 0 ? {} : { revision: this.revision },
+      recoveryActions: this.recoveryActions.map(
+        ({ exactTarget: _exactTarget, ...action }) => action
+      )
+    };
+  }
+};
+
+// src/entry-store.ts
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function artifactFile(key) {
+  if (/^[A-Za-z0-9._-]+$/.test(key)) return key;
+  return Buffer.from(key, "utf8").toString("base64url");
+}
+function validateKey(key) {
+  if (!/^[a-f0-9]{64}$/.test(key)) {
+    throw new DdcStoreError("ddc-entry-invalid", `invalid semantic key: ${key}`);
+  }
+}
+function errorCode(error) {
+  if (error !== null && typeof error === "object" && "code" in error) {
+    const code = error.code;
+    return typeof code === "string" ? code : void 0;
+  }
+  return void 0;
+}
+function sortedArtifacts(entry) {
+  return Object.entries(entry.artifacts).sort(([left], [right]) => left.localeCompare(right));
+}
+function ddcOutputDigest(entry) {
+  return `sha256:${digest(
+    canonicalDdcJson({
+      guid: entry.guid,
+      payload: entry.payload,
+      refs: entry.refs,
+      artifacts: Object.fromEntries(
+        sortedArtifacts(entry).map(([key, artifact]) => [
+          key,
+          {
+            mediaType: artifact.mediaType,
+            bytes: artifact.bytes
+          }
+        ])
+      )
+    })
+  )}`;
+}
+function existingResult(existing, candidate, key) {
+  return canonicalDdcJson(existing) === canonicalDdcJson(candidate) ? { result: "existing", key } : { result: "conflict", key };
+}
+function entryShape(entry) {
+  return {
+    key: entry.key,
+    guid: entry.guid,
+    payload: entry.payload,
+    refs: entry.refs,
+    receipt: entry.receipt,
+    artifacts: Object.fromEntries(
+      sortedArtifacts(entry).map(([key, artifact]) => [
+        key,
+        { mediaType: artifact.mediaType, byteLength: artifact.bytes.byteLength }
+      ])
+    )
+  };
+}
+function integrityFor(entry) {
+  const artifacts = Object.fromEntries(
+    sortedArtifacts(entry).map(([key, artifact]) => [
+      key,
+      {
+        mediaType: artifact.mediaType,
+        byteLength: artifact.bytes.byteLength,
+        digest: digest(artifact.bytes)
+      }
+    ])
+  );
+  return {
+    payload: digest(canonicalDdcJson(entry.payload)),
+    refs: digest(canonicalDdcJson(entry.refs)),
+    receipt: digest(canonicalDdcJson(entry.receipt)),
+    artifacts,
+    entry: digest(canonicalDdcJson(entryShape(entry)))
+  };
+}
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+var DdcEntryStore = class {
+  entries;
+  staging;
+  constructor(root) {
+    this.entries = join(root, "entries");
+    this.staging = join(root, "staging");
+  }
+  async stage(entry) {
+    validateKey(entry.key);
+    if (entry.receipt.key !== entry.key || entry.receipt.guid !== entry.guid) {
+      throw new DdcStoreError("ddc-entry-invalid", "receipt identity does not match entry");
+    }
+    if (entry.receipt.outputDigest !== ddcOutputDigest(entry)) {
+      throw new DdcStoreError("ddc-entry-invalid", "receipt output digest does not match entry");
+    }
+    const path = join(this.staging, `${entry.key}-${randomUUID()}`);
+    try {
+      await mkdir(join(path, "artifacts"), { recursive: true });
+      await writeFile(join(path, "payload.json"), canonicalDdcJson(entry.payload));
+      await writeFile(join(path, "refs.json"), canonicalDdcJson(entry.refs));
+      await writeFile(join(path, "receipt.json"), canonicalDdcJson(entry.receipt));
+      const artifacts = {};
+      for (const [key, artifact] of sortedArtifacts(entry)) {
+        const file = artifactFile(key);
+        artifacts[key] = { mediaType: artifact.mediaType, file };
+        await writeFile(join(path, "artifacts", `${file}.bin`), artifact.bytes);
+      }
+      await writeFile(join(path, "artifacts.json"), canonicalDdcJson(artifacts));
+      await writeFile(join(path, "integrity.json"), canonicalDdcJson(integrityFor(entry)));
+      return { key: entry.key, path };
+    } catch (error) {
+      await rm(path, { recursive: true, force: true }).catch(() => {
+      });
+      throw error;
+    }
+  }
+  async publish(staged) {
+    validateKey(staged.key);
+    const candidate = await this.readDirectory(staged.path, true);
+    const target = join(this.entries, staged.key);
+    await mkdir(this.entries, { recursive: true });
+    const useExisting = async () => {
+      const existing = await this.readDirectory(target, false);
+      await rm(staged.path, { recursive: true, force: true });
+      return existingResult(existing, candidate, staged.key);
+    };
+    try {
+      await stat(target);
+      return useExisting();
+    } catch (error) {
+      if (error instanceof DdcStoreError) throw error;
+      if (errorCode(error) !== "ENOENT") throw error;
+    }
+    try {
+      await rename(staged.path, target);
+      return { result: "published", key: staged.key };
+    } catch (error) {
+      if (!["EEXIST", "ENOTEMPTY", "EISDIR"].includes(errorCode(error) ?? "")) throw error;
+      return useExisting();
+    }
+  }
+  async discard(staged) {
+    await rm(staged.path, { recursive: true, force: true });
+  }
+  async write(entry) {
+    const staged = await this.stage(entry);
+    return this.publish(staged);
+  }
+  async read(key) {
+    try {
+      validateKey(key);
+      return await this.readDirectory(join(this.entries, key), false);
+    } catch {
+      return null;
+    }
+  }
+  async listKeys() {
+    const entries = await readdir(this.entries, { withFileTypes: true }).catch(() => []);
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  }
+  async remove(key) {
+    validateKey(key);
+    await rm(join(this.entries, key), { recursive: true, force: false });
+  }
+  /** Read with a machine-readable corruption result for recovery tooling. */
+  async readChecked(key) {
+    try {
+      validateKey(key);
+      try {
+        await stat(join(this.entries, key));
+      } catch (error) {
+        if (errorCode(error) === "ENOENT") return { ok: true, value: null };
+        throw error;
+      }
+      try {
+        return { ok: true, value: await this.readDirectory(join(this.entries, key), false) };
+      } catch (error) {
+        if (error instanceof DdcStoreError && error.code === "ddc-entry-incomplete") {
+          return { ok: true, value: null };
+        }
+        throw error;
+      }
+    } catch (error) {
+      const normalized = error instanceof DdcStoreError ? error : new DdcStoreError("ddc-entry-invalid", "entry is unreadable");
+      return { ok: false, error: normalized };
+    }
+  }
+  async readDirectory(path, incompleteIsError) {
+    try {
+      const payload = await readJson(join(path, "payload.json"));
+      const refs = await readJson(join(path, "refs.json"));
+      const receipt = await readJson(join(path, "receipt.json"));
+      const manifest = await readJson(join(path, "artifacts.json"));
+      const integrity = await readJson(join(path, "integrity.json"));
+      const artifacts = {};
+      for (const [key, descriptor] of Object.entries(manifest).sort(
+        ([left], [right]) => left.localeCompare(right)
+      )) {
+        const bytes = new Uint8Array(
+          await readFile(join(path, "artifacts", `${descriptor.file}.bin`))
+        );
+        artifacts[key] = { mediaType: descriptor.mediaType, bytes };
+      }
+      const entry = { key: receipt.key, guid: receipt.guid, payload, refs, artifacts, receipt };
+      if (entry.receipt.outputDigest !== ddcOutputDigest(entry)) {
+        throw new DdcStoreError("ddc-entry-invalid", "receipt output digest does not match entry");
+      }
+      const actual = integrityFor(entry);
+      if (canonicalDdcJson(actual) !== canonicalDdcJson(integrity)) {
+        throw new DdcStoreError("ddc-entry-invalid", "entry integrity mismatch");
+      }
+      return entry;
+    } catch (error) {
+      if (incompleteIsError) {
+        if (error instanceof DdcStoreError) throw error;
+        throw new DdcStoreError("ddc-entry-incomplete", "staged entry is incomplete");
+      }
+      if (error instanceof DdcStoreError) throw error;
+      throw new DdcStoreError("ddc-entry-invalid", "entry is unreadable");
+    }
+  }
+};
+var LOCK_WAIT_MS = 10;
+var LOCK_TIMEOUT_MS = 5e3;
+var LEASE_TTL_MS = 3e4;
+function headFile(heads, guid) {
+  return join(heads, `${encodeURIComponent(guid)}.json`);
+}
+function lockFile(root, name) {
+  return join(root, "locks", `${encodeURIComponent(name)}.lock`);
+}
+function withRevision(result, revision, restoreFence) {
+  const value = { ...result };
+  Object.defineProperty(value, "revision", { value: revision, enumerable: false });
+  if (restoreFence !== void 0) {
+    Object.defineProperty(value, "restoreFence", { value: restoreFence, enumerable: false });
+  }
+  return value;
+}
+async function delay(ms) {
+  await new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isLeaseRecord(value) {
+  if (!isRecord(value)) return false;
+  return isString(value.guid) && isString(value.desiredKey) && isString(value.attempt) && isNonNegativeInteger(value.generation) && isNonNegativeInteger(value.expectedRevision) && isString(value.instanceId) && typeof value.expiresAt === "number" && Number.isFinite(value.expiresAt);
+}
+function isHeadRecord(value) {
+  if (!isRecord(value)) return false;
+  if (!isString(value.guid) || !isString(value.desiredKey) || !isNonNegativeInteger(value.revision)) {
+    return false;
+  }
+  if (value.currentKey !== void 0 && !isString(value.currentKey)) return false;
+  if (value.lastKnownGoodKey !== void 0 && !isString(value.lastKnownGoodKey)) return false;
+  if (value.generation !== void 0 && (!isNonNegativeInteger(value.generation) || value.generation === 0)) {
+    return false;
+  }
+  if (value.active !== void 0 && !isLeaseRecord(value.active)) return false;
+  if (value.supersededAttempts !== void 0 && (!Array.isArray(value.supersededAttempts) || !value.supersededAttempts.every(isString))) {
+    return false;
+  }
+  if (value.stale !== void 0 && typeof value.stale !== "boolean") return false;
+  if (value.empty !== void 0 && typeof value.empty !== "boolean") return false;
+  if (value.failure !== void 0) {
+    if (!isRecord(value.failure)) return false;
+    if (!isString(value.failure.desiredKey) || !isString(value.failure.code) || !isString(value.failure.detail)) {
+      return false;
+    }
+  }
+  return true;
+}
+function malformedHeadError(actual) {
+  const detail = actual === "syntax-invalid" ? "DDC head JSON is syntactically invalid" : actual === "schema-invalid" ? "DDC head record does not match the lifecycle schema" : "DDC head file is not readable";
+  return new DdcStoreError({
+    code: "ddc-head-conflict",
+    detail,
+    expected: "a valid DDC head record",
+    actual,
+    hint: "inspect the current head and retry with a fresh revision",
+    owner: "engine-ddc",
+    rootKind: "project-ddc",
+    recoveryActions: [
+      { kind: "inspect", executable: true },
+      { kind: "retry", executable: true }
+    ]
+  });
+}
+async function withDdcLock(root, name, operation) {
+  const path = lockFile(root, name);
+  await mkdir(join(root, "locks"), { recursive: true });
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (true) {
+    try {
+      await mkdir(path);
+      await writeFile(
+        join(path, "owner.json"),
+        JSON.stringify({ pid: process.pid, acquiredAt: Date.now() })
+      );
+      try {
+        return await operation();
+      } finally {
+        await rm(path, { recursive: true, force: true });
+      }
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let ownerPid;
+      try {
+        ownerPid = JSON.parse(await readFile(join(path, "owner.json"), "utf8")).pid;
+      } catch {
+        ownerPid = void 0;
+      }
+      if (ownerPid === void 0) {
+        if (Date.now() >= deadline) {
+          throw new DdcStoreError({
+            code: "ddc-lease-expired",
+            detail: `DDC lock ${name} did not publish an owner record`,
+            hint: "inspect the lock owner and retry after the incomplete instance exits",
+            expected: "a lock owner record",
+            actual: { path },
+            rootKind: "project-ddc"
+          });
+        }
+        await delay(LOCK_WAIT_MS);
+        continue;
+      }
+      let alive = false;
+      try {
+        process.kill(ownerPid, 0);
+        alive = true;
+      } catch {
+        alive = false;
+      }
+      if (!alive) {
+        await rm(path, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new DdcStoreError({
+          code: "ddc-lease-expired",
+          detail: `DDC lock ${name} remained owned by process ${ownerPid}`,
+          hint: "inspect the owner and retry after the stale instance exits",
+          expected: "an available project lock",
+          actual: { ownerPid },
+          rootKind: "project-ddc",
+          lease: String(ownerPid)
+        });
+      }
+      await delay(LOCK_WAIT_MS);
+    }
+  }
+}
+var DdcLifecycle = class {
+  heads;
+  entries;
+  root;
+  leaseTtlMs;
+  constructor(root, options) {
+    this.root = root;
+    this.heads = join(root, "heads");
+    this.entries = new DdcEntryStore(root);
+    this.leaseTtlMs = options?.leaseTtlMs ?? LEASE_TTL_MS;
+  }
+  async inspect(guid, desiredKey) {
+    const record = await this.read(guid);
+    return this.projectHead(guid, desiredKey, record);
+  }
+  /** Begin a lease and capture the accepted rollback snapshot under one head lock. */
+  async beginWithSnapshot(guid, desiredKey) {
+    return withDdcLock(this.root, `head-${guid}`, async () => {
+      const previous = await this.read(guid);
+      const previousHead = await this.projectHead(guid, desiredKey, previous, false);
+      const generation = await this.allocateGeneration(previous?.generation ?? 0);
+      const lease = {
+        guid,
+        desiredKey,
+        attempt: randomUUID(),
+        generation,
+        expectedRevision: previous?.revision ?? 0,
+        instanceId: `${process.pid}:${randomUUID()}`,
+        expiresAt: Date.now() + this.leaseTtlMs
+      };
+      const lastKnownGoodKey = previous?.currentKey !== void 0 && previous.currentKey !== desiredKey ? previous.currentKey : previous?.lastKnownGoodKey;
+      const supersededAttempts = [
+        ...previous?.supersededAttempts ?? [],
+        ...previous?.active === void 0 ? [] : [previous.active.attempt]
+      ];
+      await this.write({
+        guid,
+        desiredKey,
+        revision: previous?.revision ?? 0,
+        generation,
+        active: lease,
+        ...previous?.currentKey === void 0 ? {} : { currentKey: previous.currentKey },
+        ...supersededAttempts.length === 0 ? {} : { supersededAttempts },
+        ...lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey }
+      });
+      return { lease, previousHead };
+    });
+  }
+  async begin(guid, desiredKey) {
+    return (await this.beginWithSnapshot(guid, desiredKey)).lease;
+  }
+  async commit(lease, validatedKey) {
+    return withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.attempt !== lease.attempt) {
+        if (current?.supersededAttempts?.includes(lease.attempt)) {
+          await this.write({ ...current, stale: true });
+          return withRevision({ result: "stale", key: validatedKey }, current.revision);
+        }
+        return withRevision({ result: "lease-lost", key: validatedKey }, current?.revision ?? 0);
+      }
+      if (Date.now() > lease.expiresAt) {
+        throw new DdcStoreError({
+          code: "ddc-lease-expired",
+          detail: "cook lease expired before commit fencing",
+          expected: { attempt: lease.attempt, revision: lease.expectedRevision },
+          actual: { revision: current.revision },
+          owner: "engine-ddc",
+          rootKind: "project-ddc",
+          generation: lease.generation,
+          lease: lease.attempt,
+          revision: current.revision
+        });
+      }
+      if (current.revision !== lease.expectedRevision || current.desiredKey !== lease.desiredKey || validatedKey !== lease.desiredKey) {
+        await this.write({ ...current, stale: true });
+        return withRevision({ result: "stale", key: validatedKey }, current.revision);
+      }
+      const entry = await this.entries.read(validatedKey);
+      if (entry === null || entry.guid !== lease.guid || entry.receipt.key !== validatedKey) {
+        const nextRevision2 = current.revision + 1;
+        const failure2 = {
+          desiredKey: lease.desiredKey,
+          code: "entry-invalid",
+          detail: "validated DDC key has no readable entry for this asset"
+        };
+        await this.write({
+          guid: lease.guid,
+          desiredKey: lease.desiredKey,
+          revision: nextRevision2,
+          generation: lease.generation,
+          ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+          ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
+          failure: failure2
+        });
+        return withRevision({ result: "invalid", key: validatedKey }, nextRevision2, {
+          attempt: lease.attempt,
+          generation: lease.generation,
+          revision: nextRevision2,
+          desiredKey: lease.desiredKey,
+          outcome: "invalid",
+          ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+          failure: { code: failure2.code, detail: failure2.detail }
+        });
+      }
+      const lastKnownGoodKey = current.currentKey !== void 0 && current.currentKey !== validatedKey ? current.currentKey : current.lastKnownGoodKey;
+      const nextRevision = current.revision + 1;
+      await this.write({
+        guid: lease.guid,
+        desiredKey: lease.desiredKey,
+        revision: nextRevision,
+        generation: lease.generation,
+        currentKey: validatedKey,
+        stale: false,
+        ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
+        ...lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey }
+      });
+      return withRevision({ result: "current", key: validatedKey }, nextRevision, {
+        attempt: lease.attempt,
+        generation: lease.generation,
+        revision: nextRevision,
+        desiredKey: lease.desiredKey,
+        outcome: "current",
+        key: validatedKey,
+        currentKey: validatedKey,
+        ...lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey }
+      });
+    });
+  }
+  async fail(lease, failure2) {
+    return withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.attempt !== lease.attempt) return;
+      const nextRevision = current.revision + 1;
+      await this.write({
+        guid: lease.guid,
+        desiredKey: lease.desiredKey,
+        revision: nextRevision,
+        generation: lease.generation,
+        ...current.currentKey === void 0 ? {} : { currentKey: current.currentKey },
+        ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+        ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
+        failure: { desiredKey: lease.desiredKey, ...failure2 }
+      });
+      return {
+        attempt: lease.attempt,
+        generation: lease.generation,
+        revision: nextRevision,
+        desiredKey: lease.desiredKey,
+        outcome: "failed",
+        ...current.currentKey === void 0 ? {} : { currentKey: current.currentKey },
+        ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+        failure: failure2
+      };
+    });
+  }
+  async heartbeat(lease) {
+    return withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.attempt !== lease.attempt) {
+        throw new DdcStoreError({
+          code: "ddc-lease-expired",
+          detail: "heartbeat belongs to a stale lease",
+          expected: lease.attempt,
+          actual: current?.active?.attempt,
+          lease: lease.attempt,
+          generation: lease.generation,
+          rootKind: "project-ddc"
+        });
+      }
+      const refreshed = { ...lease, expiresAt: Date.now() + this.leaseTtlMs };
+      await this.write({ ...current, active: refreshed });
+      return refreshed;
+    });
+  }
+  async close(lease) {
+    await withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.instanceId !== lease.instanceId) return;
+      const { active: _active, ...withoutActive } = current;
+      await this.write({
+        ...withoutActive,
+        revision: current.revision + 1,
+        stale: current.currentKey === void 0
+      });
+    });
+  }
+  async discard(lease) {
+    await withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.attempt !== lease.attempt) return;
+      const { active: _active, ...withoutActive } = current;
+      await this.write({
+        ...withoutActive,
+        revision: current.revision + 1,
+        generation: lease.generation,
+        stale: current.currentKey === void 0
+      });
+    });
+  }
+  /**
+   * Restore accepted content only when this lease still owns the mutable head.
+   * A newer active or terminal mutation makes rollback a deliberate no-op.
+   */
+  async restore(head, lease, fence) {
+    const inferredLease = lease ?? ("activeLease" in head && head.activeLease !== void 0 ? head.activeLease : void 0);
+    if (inferredLease === void 0) {
+      return {
+        result: "not-owner",
+        revision: head.revision ?? 0,
+        ...head.generation === void 0 ? {} : { generation: head.generation }
+      };
+    }
+    const snapshot = this.rollbackSnapshot(head);
+    return this.restoreIfCurrent(snapshot, inferredLease, fence);
+  }
+  async restoreIfCurrent(snapshot, lease, fence) {
+    return withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current === null || current.guid !== snapshot.guid) {
+        return {
+          result: "not-owner",
+          revision: current?.revision ?? 0,
+          ...current?.generation === void 0 ? {} : { generation: current.generation }
+        };
+      }
+      const ownsActive = current.active?.attempt === lease.attempt && current.active.generation === lease.generation && current.active.desiredKey === lease.desiredKey;
+      const ownsTerminal = fence !== void 0 && this.matchesRestoreFence(current, lease, fence);
+      if (!ownsActive && !ownsTerminal) {
+        return {
+          result: "not-owner",
+          revision: current.revision,
+          ...current.generation === void 0 ? {} : { generation: current.generation }
+        };
+      }
+      const nextRevision = current.revision + 1;
+      const generation = Math.max(
+        current.generation ?? 0,
+        lease.generation,
+        snapshot.generation ?? 0
+      );
+      const supersededAttempts = current.supersededAttempts;
+      const restored = {
+        guid: snapshot.guid,
+        desiredKey: snapshot.desiredKey,
+        revision: nextRevision,
+        generation,
+        ...snapshot.currentKey === void 0 ? {} : { currentKey: snapshot.currentKey },
+        ...snapshot.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: snapshot.lastKnownGoodKey },
+        ...supersededAttempts === void 0 ? {} : { supersededAttempts },
+        ...snapshot.state === "missing" ? { empty: true } : {},
+        ...snapshot.state === "stale" ? { stale: true } : {},
+        ...snapshot.failure === void 0 ? {} : { failure: { desiredKey: snapshot.desiredKey, ...snapshot.failure } }
+      };
+      await this.write(restored);
+      return { result: "restored", revision: nextRevision, generation };
+    });
+  }
+  async revoke(lease) {
+    await this.fail(lease, {
+      code: "lease-lost",
+      detail: "cook lease was revoked before validation"
+    });
+  }
+  async recover(guid, desiredKey) {
+    return withDdcLock(this.root, `head-${guid}`, async () => {
+      const current = await this.read(guid);
+      if (current?.active?.desiredKey === desiredKey) {
+        await this.write({
+          guid,
+          desiredKey,
+          revision: current.revision + 1,
+          ...current.generation === void 0 ? {} : { generation: current.generation },
+          ...current.supersededAttempts === void 0 ? {} : { supersededAttempts: current.supersededAttempts },
+          ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+          failure: {
+            desiredKey,
+            code: "writer-crashed",
+            detail: "active cook attempt was recovered after process interruption"
+          }
+        });
+      }
+      return this.inspect(guid, desiredKey);
+    });
+  }
+  rollbackSnapshot(head) {
+    const { activeLease: _activeLease, ...snapshot } = head;
+    if (snapshot.state !== "cooking") return snapshot;
+    return {
+      ...snapshot,
+      state: snapshot.currentKey === void 0 ? "missing" : "stale"
+    };
+  }
+  matchesRestoreFence(current, lease, fence) {
+    if (fence.attempt !== lease.attempt || fence.generation !== lease.generation || current.active !== void 0 || current.revision !== fence.revision || current.generation !== fence.generation || current.desiredKey !== fence.desiredKey || current.currentKey !== fence.currentKey || current.lastKnownGoodKey !== fence.lastKnownGoodKey) {
+      return false;
+    }
+    if (fence.outcome === "current") {
+      return fence.key !== void 0 && current.currentKey === fence.key && current.failure === void 0 && current.stale !== true;
+    }
+    if (fence.failure === void 0 || current.failure === void 0 || current.failure.desiredKey !== fence.desiredKey || current.failure.code !== fence.failure.code || current.failure.detail !== fence.failure.detail) {
+      return false;
+    }
+    return fence.outcome === "invalid" ? fence.currentKey === void 0 : true;
+  }
+  async projectHead(guid, desiredKey, record, includeActive = true) {
+    if (record === null) {
+      return {
+        guid,
+        desiredKey,
+        state: "missing",
+        currentKey: void 0,
+        lastKnownGoodKey: void 0,
+        revision: 0
+      };
+    }
+    const recordedFailure = record.failure?.desiredKey === desiredKey ? { code: record.failure.code, detail: record.failure.detail } : void 0;
+    const currentEntry = record.currentKey === void 0 ? null : await this.entries.readChecked(record.currentKey);
+    const entryFailure = currentEntry !== null && !currentEntry.ok ? { code: currentEntry.error.code, detail: currentEntry.error.detail } : void 0;
+    const failure2 = recordedFailure ?? entryFailure;
+    const currentValue = currentEntry?.ok === true ? currentEntry.value : null;
+    const state = failure2 !== void 0 ? "failed" : record.currentKey === desiredKey && currentValue?.guid === guid ? "current" : record.stale === true ? "stale" : includeActive && record.active?.desiredKey === desiredKey ? "cooking" : record.empty === true ? "missing" : "stale";
+    return {
+      guid,
+      desiredKey,
+      state,
+      currentKey: record.currentKey,
+      lastKnownGoodKey: record.lastKnownGoodKey,
+      revision: record.revision,
+      ...record.generation === void 0 ? {} : { generation: record.generation },
+      ...includeActive && record.active === void 0 ? {} : includeActive && record.active !== void 0 ? { activeLease: record.active } : {},
+      ...failure2 === void 0 ? {} : { failure: failure2 }
+    };
+  }
+  async allocateGeneration(minimumExclusive = 0) {
+    return withDdcLock(this.root, "generation-counter", async () => {
+      const path = join(this.root, "generations", "counter.json");
+      await mkdir(join(this.root, "generations"), { recursive: true });
+      let next = 1;
+      try {
+        const record = JSON.parse(await readFile(path, "utf8"));
+        if (record.schemaVersion === "forgeax-ddc-generation/v2" && Number.isSafeInteger(record.next) && record.next >= 1)
+          next = Math.max(1, record.next);
+      } catch {
+      }
+      const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+      next = Math.max(next, minimumExclusive + 1);
+      await writeFile(
+        temporary,
+        JSON.stringify({ schemaVersion: "forgeax-ddc-generation/v2", next: next + 1 })
+      );
+      await rename(temporary, path);
+      return next;
+    });
+  }
+  async read(guid) {
+    const path = headFile(this.heads, guid);
+    let source;
+    try {
+      source = await readFile(path, "utf8");
+    } catch (error) {
+      if (error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        return null;
+      }
+      throw malformedHeadError("unreadable");
+    }
+    let value;
+    try {
+      value = JSON.parse(source);
+    } catch {
+      throw malformedHeadError("syntax-invalid");
+    }
+    if (!isHeadRecord(value) || value.guid !== guid) throw malformedHeadError("schema-invalid");
+    return value;
+  }
+  async write(record) {
+    await mkdir(this.heads, { recursive: true });
+    const path = headFile(this.heads, record.guid);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify(record));
+    await rename(temporary, path);
+  }
+};
+
+// src/gc.ts
+async function collectDdcGarbage(root, input) {
+  return withDdcLock(root, "gc", async () => {
+    const protectedKeys = /* @__PURE__ */ new Set([
+      ...input.currentKeys,
+      ...input.lastKnownGoodKeys,
+      ...input.activeLeaseKeys
+    ]);
+    const entries = await readdir(join(root, "entries"), { withFileTypes: true }).catch(() => []);
+    const deleted = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || protectedKeys.has(entry.name)) continue;
+      await rm(join(root, "entries", entry.name), { recursive: true, force: false });
+      deleted.push(entry.name);
+    }
+    return { deleted, protected: [...protectedKeys].sort() };
+  });
+}
+var DDC_LAYOUT_VERSION = "v2";
+function rootOrError(root, name) {
+  if (!isAbsolute(root)) {
+    return {
+      code: "ddc-root-absolute-required",
+      detail: `${name} must be an absolute injected path`,
+      hint: `inject the canonical ${name} from the host root policy`,
+      expected: "an absolute filesystem path",
+      actual: root
+    };
+  }
+  const normalized = normalize(root);
+  return normalized.replace(/[\\/]+$/, "") || normalized;
+}
+function buildLayout(root) {
+  return { objects: `${root}/objects`, staging: `${root}/staging` };
+}
+function projectLayout(root) {
+  return {
+    root,
+    scope: `${root}/scope.json`,
+    heads: `${root}/heads`,
+    generations: `${root}/generations`,
+    leases: `${root}/leases`,
+    staging: `${root}/staging`
+  };
+}
+function resolveBuildDdcLayout(options) {
+  const root = rootOrError(options.buildCacheRoot, "buildCacheRoot");
+  return typeof root === "string" ? { ok: true, value: buildLayout(root) } : { ok: false, error: root };
+}
+function resolveDdcLayout(options) {
+  const buildRoot = rootOrError(options.buildCacheRoot, "buildCacheRoot");
+  if (typeof buildRoot !== "string") return { ok: false, error: buildRoot };
+  if (options.projectDdcRoot === void 0 || options.projectDdcRoot.trim().length === 0) {
+    return {
+      ok: false,
+      error: {
+        code: "ddc-project-root-required",
+        detail: "serve and publication require an explicitly injected projectDdcRoot",
+        hint: "canonicalize the game directory in the host and inject its .forgeax/ddc/v2 root",
+        expected: "projectDdcRoot"
+      }
+    };
+  }
+  const projectRoot = rootOrError(options.projectDdcRoot, "projectDdcRoot");
+  if (typeof projectRoot !== "string") return { ok: false, error: projectRoot };
+  return {
+    ok: true,
+    value: {
+      version: DDC_LAYOUT_VERSION,
+      buildCacheRoot: buildRoot,
+      projectDdcRoot: projectRoot,
+      build: buildLayout(buildRoot),
+      project: projectLayout(projectRoot)
+    }
+  };
+}
+function isDdcLayout(value) {
+  return value !== null && typeof value === "object" && value.version === DDC_LAYOUT_VERSION;
+}
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stable(record[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+function digest2(value) {
+  return `sha256:${createHash("sha256").update(stable(value)).digest("hex")}`;
+}
+function scriptablePackOutputSetDigest(outputs) {
+  return digest2(
+    outputs.map((output) => ({
+      guid: output.guid.toLowerCase(),
+      sourceKey: output.sourceKey,
+      kind: output.kind,
+      digest: output.digest,
+      refs: [...output.refs].map((guid) => guid.toLowerCase())
+    }))
+  );
+}
+function scriptablePackPublicationGeneration(input) {
+  const hash = createHash("sha256").update(input.sourceRevision).update("\n").update(input.digest).update("\n").update(input.outputSetDigest).digest("hex");
+  const generation = Number.parseInt(hash.slice(0, 8), 16);
+  return generation > 0 ? generation : 1;
+}
+function createAcceptedPublication(input) {
+  const outputSetDigest = scriptablePackOutputSetDigest(input.outputs);
+  const publicationGeneration = input.generation ?? scriptablePackPublicationGeneration({
+    sourceRevision: input.sourceRevision,
+    digest: input.digest,
+    outputSetDigest
+  });
+  return {
+    schemaVersion: "asset-publication/1",
+    sourcePath: input.sourcePath,
+    sourceRevision: input.sourceRevision,
+    generation: publicationGeneration,
+    digest: input.digest,
+    outputSetDigest,
+    outputs: input.outputs,
+    receipt: {
+      schemaVersion: "asset-publication-receipt/1",
+      sourcePath: input.sourcePath,
+      sourceRevision: input.sourceRevision,
+      inputFingerprint: input.inputFingerprint,
+      outputDigest: input.digest,
+      outputSetDigest,
+      externalEvidence: input.externalEvidence
+    },
+    externalEvidence: input.externalEvidence,
+    current: {
+      generation: publicationGeneration,
+      digest: input.digest,
+      outputSetDigest,
+      packageUrl: input.packageUrl,
+      receiptKey: input.inputFingerprint
+    }
+  };
+}
+function locatorFor(envelope) {
+  return {
+    generation: envelope.generation,
+    digest: envelope.digest,
+    outputSetDigest: envelope.outputSetDigest,
+    packageUrl: envelope.current?.packageUrl ?? "",
+    receiptKey: envelope.receipt.inputFingerprint
+  };
+}
+function recoveryFor(retryable, useLastKnownGood) {
+  return {
+    retryable,
+    preserveCurrent: true,
+    useLastKnownGood,
+    actions: retryable ? ["inspect-publication-failure", "retry-rebuild", "continue-last-known-good"] : ["inspect-publication-failure", "edit-source", "continue-last-known-good"]
+  };
+}
+function failure(envelope, code, stage, reason, retryable, current, lastKnownGood) {
+  return {
+    code,
+    stage,
+    sourcePath: envelope.sourcePath,
+    sourceRevision: envelope.sourceRevision,
+    generation: envelope.generation,
+    reason,
+    recovery: recoveryFor(retryable, lastKnownGood !== void 0),
+    ...current === void 0 ? {} : { current: locatorFor(current) },
+    ...lastKnownGood === void 0 ? {} : { lastKnownGood: locatorFor(lastKnownGood) }
+  };
+}
+function validateOutputs(envelope, current, lastKnownGood) {
+  const guids = /* @__PURE__ */ new Set();
+  const sourceKeys = /* @__PURE__ */ new Set();
+  for (const output of envelope.outputs) {
+    const guid = output.guid.toLowerCase();
+    if (guids.has(guid) || sourceKeys.has(output.sourceKey)) {
+      return failure(
+        envelope,
+        "asset-publication-output-duplicate",
+        "output",
+        "publication output GUIDs and sourceKeys must be unique",
+        false,
+        current,
+        lastKnownGood
+      );
+    }
+    guids.add(guid);
+    sourceKeys.add(output.sourceKey);
+  }
+  if (envelope.outputs.length === 0 || scriptablePackOutputSetDigest(envelope.outputs) !== envelope.outputSetDigest) {
+    return failure(
+      envelope,
+      "asset-publication-output-set-mismatch",
+      "receipt",
+      "receipt outputSetDigest does not match the complete output tuple",
+      false,
+      current,
+      lastKnownGood
+    );
+  }
+  return void 0;
+}
+function validateReceipt(envelope, current, lastKnownGood) {
+  const receipt = envelope.receipt;
+  if (receipt.schemaVersion !== "asset-publication-receipt/1" || receipt.sourcePath !== envelope.sourcePath || receipt.sourceRevision !== envelope.sourceRevision || receipt.outputSetDigest !== envelope.outputSetDigest || receipt.outputDigest !== envelope.digest || stable(receipt.externalEvidence) !== stable(envelope.externalEvidence)) {
+    return failure(
+      envelope,
+      "asset-publication-receipt-mismatch",
+      "receipt",
+      "publication receipt does not match the candidate output tuple",
+      false,
+      current,
+      lastKnownGood
+    );
+  }
+  return void 0;
+}
+function validateEnvelope(envelope, current, lastKnownGood) {
+  if (envelope.schemaVersion !== "asset-publication/1") {
+    return failure(
+      envelope,
+      "asset-publication-schema-invalid",
+      "receipt",
+      "publication envelope schemaVersion is not supported",
+      false,
+      current,
+      lastKnownGood
+    );
+  }
+  if (!Number.isSafeInteger(envelope.generation) || envelope.generation < 1) {
+    return failure(
+      envelope,
+      "asset-publication-generation-invalid",
+      "receipt",
+      "publication generation must be a positive integer",
+      false,
+      current,
+      lastKnownGood
+    );
+  }
+  const outputError = validateOutputs(envelope, current, lastKnownGood);
+  if (outputError !== void 0) return outputError;
+  const receiptError = validateReceipt(envelope, current, lastKnownGood);
+  if (receiptError !== void 0) return receiptError;
+  const sameTuple = current !== void 0 && envelope.generation === current.generation && envelope.sourcePath === current.sourcePath && envelope.sourceRevision === current.sourceRevision && envelope.digest === current.digest && envelope.outputSetDigest === current.outputSetDigest;
+  if (sameTuple) return void 0;
+  if (current !== void 0 && envelope.generation <= current.generation) {
+    return failure(
+      envelope,
+      "asset-publication-stale",
+      "cancelled",
+      `candidate generation ${envelope.generation} is not newer than current ${current.generation}`,
+      true,
+      current,
+      lastKnownGood
+    );
+  }
+  return void 0;
+}
+function validateCandidate(state, candidate, cancelledReason) {
+  const current = state.snapshot.current;
+  const lastKnownGood = state.snapshot.lastKnownGood ?? current;
+  if (candidate.cancelled === true) {
+    return failure(
+      candidate.envelope,
+      "asset-publication-cancelled",
+      "cancelled",
+      cancelledReason,
+      true,
+      current,
+      lastKnownGood
+    );
+  }
+  return validateEnvelope(candidate.envelope, current, lastKnownGood);
+}
+async function publishCandidate(state, candidate, commitRoute) {
+  const current = state.snapshot.current;
+  const lastKnownGood = state.snapshot.lastKnownGood ?? current;
+  const invalid = validateCandidate(
+    state,
+    candidate,
+    "publication request was cancelled before route commit"
+  );
+  if (invalid !== void 0) {
+    state.snapshot = { ...state.snapshot, failure: invalid };
+    return err(invalid);
+  }
+  try {
+    await commitRoute();
+  } catch (error) {
+    const failed = failure(
+      candidate.envelope,
+      "asset-publication-route-failed",
+      "route",
+      error instanceof Error ? error.message : String(error),
+      true,
+      current,
+      lastKnownGood
+    );
+    state.snapshot = { ...state.snapshot, failure: failed };
+    return err(failed);
+  }
+  const published = {
+    ...candidate.envelope,
+    current: locatorFor(candidate.envelope),
+    ...current === void 0 ? {} : { lastKnownGood: locatorFor(current) },
+    recovery: recoveryFor(false, current !== void 0)
+  };
+  state.snapshot = {
+    current: published,
+    ...current === void 0 ? {} : { lastKnownGood: current }
+  };
+  return ok(state.snapshot);
+}
+function createAcceptedPublicationStore() {
+  const states = /* @__PURE__ */ new Map();
+  function stateFor(sourcePath) {
+    const existing = states.get(sourcePath);
+    if (existing !== void 0) return existing;
+    const created = { snapshot: {}, staged: /* @__PURE__ */ new Set() };
+    states.set(sourcePath, created);
+    return created;
+  }
+  return {
+    observe(sourcePath) {
+      return stateFor(sourcePath).snapshot;
+    },
+    stage(sourcePath, candidate) {
+      const invalid = validateCandidate(
+        stateFor(sourcePath),
+        candidate,
+        "publication request was cancelled before DDC commit"
+      );
+      if (invalid !== void 0) return err(invalid);
+      stateFor(sourcePath).staged.add(candidate.envelope);
+      return ok(void 0);
+    },
+    async commit(sourcePath, candidate, commitRoute) {
+      const state = stateFor(sourcePath);
+      if (!state.staged.has(candidate.envelope)) {
+        const current = state.snapshot.current;
+        const lastKnownGood = state.snapshot.lastKnownGood ?? current;
+        return err(
+          failure(
+            candidate.envelope,
+            "asset-publication-cancelled",
+            "cancelled",
+            "publication candidate was discarded before DDC commit",
+            true,
+            current,
+            lastKnownGood
+          )
+        );
+      }
+      const result = await publishCandidate(state, candidate, commitRoute);
+      state.staged.delete(candidate.envelope);
+      return result;
+    },
+    discard(sourcePath, candidate) {
+      stateFor(sourcePath).staged.delete(candidate);
+    },
+    restore(sourcePath, snapshot) {
+      const state = stateFor(sourcePath);
+      state.staged.clear();
+      state.snapshot = snapshot;
+    }
+  };
+}
+function scopeHash(scopeId) {
+  return createHash("sha256").update(scopeId, "utf8").digest("hex");
+}
+function runtimeScopeHash(scopeId) {
+  return scopeHash(scopeId);
+}
+async function createRuntimeScope(root, scopeId) {
+  if (scopeId.length === 0) {
+    throw new DdcStoreError({
+      code: "ddc-scope-mismatch",
+      detail: "runtime scope id must not be empty",
+      expected: "a non-empty original scope id",
+      actual: scopeId,
+      rootKind: "project-ddc"
+    });
+  }
+  const hash = scopeHash(scopeId);
+  const scopeRoot = join(root, "scopes", hash);
+  const metadataPath = join(scopeRoot, "scope.json");
+  await mkdir(scopeRoot, { recursive: true });
+  const expected = {
+    schemaVersion: "forgeax-ddc-scope/v2",
+    scopeId,
+    scopeHash: hash
+  };
+  try {
+    const actual = JSON.parse(await readFile(metadataPath, "utf8"));
+    if (actual.schemaVersion !== expected.schemaVersion || actual.scopeId !== expected.scopeId || actual.scopeHash !== expected.scopeHash) {
+      throw new DdcStoreError({
+        code: "ddc-scope-mismatch",
+        detail: "runtime scope metadata does not match the requested scope",
+        expected,
+        actual,
+        rootKind: "project-ddc",
+        scope: scopeId
+      });
+    }
+  } catch (error) {
+    if (error instanceof DdcStoreError) throw error;
+    const temporary = `${metadataPath}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(expected));
+    await rename(temporary, metadataPath);
+  }
+  return { scopeId, scopeHash: hash, root: scopeRoot, metadataPath };
+}
+async function assertRuntimeScope(root, scope) {
+  const expectedHash = scopeHash(scope.scopeId);
+  if (scope.scopeHash !== expectedHash) {
+    throw new DdcStoreError({
+      code: "ddc-scope-mismatch",
+      detail: "runtime scope hash does not match the original scope id",
+      expected: expectedHash,
+      actual: scope.scopeHash,
+      rootKind: "project-ddc",
+      scope: scope.scopeId
+    });
+  }
+  return createRuntimeScope(root, scope.scopeId);
+}
+
+// src/session.ts
+var DdcGenerationSession = class {
+  generation;
+  lifecycle;
+  entries;
+  candidates = /* @__PURE__ */ new Map();
+  restoreFences = /* @__PURE__ */ new WeakMap();
+  heartbeatTimers = /* @__PURE__ */ new Map();
+  counters = {
+    hitCount: 0,
+    missCount: 0,
+    corruptCount: 0,
+    writeFailureCount: 0
+  };
+  accepting = true;
+  constructor(root, options) {
+    if (!Number.isSafeInteger(options.generation) || options.generation < 1) {
+      throw new TypeError("DDC generation must be a positive safe integer");
+    }
+    this.generation = options.generation;
+    this.lifecycle = new DdcLifecycle(
+      root,
+      options.leaseTtlMs === void 0 ? void 0 : { leaseTtlMs: options.leaseTtlMs }
+    );
+    this.entries = new DdcEntryStore(root);
+  }
+  async beginCandidate(guid, desiredKey) {
+    this.assertOpen();
+    const { lease, previousHead } = await this.lifecycle.beginWithSnapshot(guid, desiredKey);
+    if (previousHead.state === "current") this.counters.hitCount += 1;
+    else this.counters.missCount += 1;
+    const candidate = {
+      generation: this.generation,
+      lease,
+      previousHead
+    };
+    this.candidates.set(lease.attempt, candidate);
+    this.scheduleHeartbeat(candidate);
+    return candidate;
+  }
+  async stageEntry(entry) {
+    this.assertOpen();
+    const candidate = await this.beginCandidate(
+      entry.guid,
+      entry.key
+    );
+    try {
+      const staged = await this.entries.stage(entry);
+      const entryCandidate = Object.assign(candidate, {
+        staged
+      });
+      this.candidates.set(candidate.lease.attempt, entryCandidate);
+      return entryCandidate;
+    } catch (error) {
+      const fence = await this.lifecycle.fail(candidate.lease, {
+        code: "ddc-entry-stage-failed",
+        detail: error instanceof Error ? error.message : String(error)
+      });
+      if (fence !== void 0) this.restoreFences.set(candidate, fence);
+      this.stopHeartbeat(candidate);
+      this.candidates.delete(candidate.lease.attempt);
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+  async inspect(guid, desiredKey) {
+    this.assertOpen();
+    const head = await this.lifecycle.inspect(guid, desiredKey);
+    if (head.state === "current") this.counters.hitCount += 1;
+    else this.counters.missCount += 1;
+    return head;
+  }
+  async commitCandidate(candidate, validatedKey) {
+    const registered = this.assertCandidate(candidate);
+    try {
+      const result = await this.lifecycle.commit(registered.lease, validatedKey);
+      if (result.restoreFence !== void 0)
+        this.restoreFences.set(registered, result.restoreFence);
+      if (result.result === "invalid") this.counters.corruptCount += 1;
+      this.stopHeartbeat(registered);
+      this.candidates.delete(registered.lease.attempt);
+      return result;
+    } catch (error) {
+      this.stopHeartbeat(registered);
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+  async commitEntry(candidate, validatedKey) {
+    const registered = this.assertCandidate(candidate);
+    try {
+      await this.entries.publish(candidate.staged);
+      const result = await this.lifecycle.commit(registered.lease, validatedKey);
+      if (result.restoreFence !== void 0)
+        this.restoreFences.set(registered, result.restoreFence);
+      this.stopHeartbeat(registered);
+      this.candidates.delete(registered.lease.attempt);
+      return result;
+    } catch (error) {
+      this.stopHeartbeat(registered);
+      const fence = await this.lifecycle.fail(registered.lease, {
+        code: "ddc-entry-publish-failed",
+        detail: error instanceof Error ? error.message : String(error)
+      });
+      if (fence !== void 0) this.restoreFences.set(registered, fence);
+      await this.entries.discard(candidate.staged).catch(() => {
+      });
+      this.candidates.delete(registered.lease.attempt);
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+  async discardCandidate(candidate) {
+    const registered = this.candidates.get(candidate.lease.attempt);
+    if (registered === void 0) return;
+    try {
+      this.stopHeartbeat(registered);
+      await this.lifecycle.discard(registered.lease);
+      this.candidates.delete(registered.lease.attempt);
+    } catch (error) {
+      this.counters.writeFailureCount += 1;
+      throw error;
+    }
+  }
+  async discardEntry(candidate) {
+    await Promise.all([this.discardCandidate(candidate), this.entries.discard(candidate.staged)]);
+  }
+  async restoreEntry(candidate) {
+    const registered = this.candidates.get(candidate.lease.attempt);
+    const ownerLease = registered?.lease ?? candidate.lease;
+    const fence = this.restoreFences.get(candidate);
+    this.stopHeartbeat(ownerLease);
+    let result = {
+      result: "not-owner",
+      revision: candidate.previousHead.revision ?? 0,
+      ...candidate.previousHead.generation === void 0 ? {} : { generation: candidate.previousHead.generation }
+    };
+    let restoreError;
+    try {
+      result = await this.lifecycle.restoreIfCurrent(candidate.previousHead, ownerLease, fence);
+    } catch (error) {
+      restoreError = error;
+    } finally {
+      await this.entries.discard(candidate.staged).catch(() => {
+      });
+      if (registered !== void 0) {
+        this.candidates.delete(registered.lease.attempt);
+      }
+    }
+    if (restoreError !== void 0) throw restoreError;
+    return result;
+  }
+  metrics() {
+    return { ...this.counters };
+  }
+  async close() {
+    if (!this.accepting) return;
+    this.accepting = false;
+    for (const timer of this.heartbeatTimers.values()) clearTimeout(timer);
+    this.heartbeatTimers.clear();
+    const pending = [...this.candidates.values()];
+    for (const candidate of pending) {
+      try {
+        await this.lifecycle.discard(candidate.lease);
+      } catch {
+        this.counters.writeFailureCount += 1;
+      }
+    }
+    this.candidates.clear();
+  }
+  assertOpen() {
+    if (!this.accepting) throw new Error("DDC generation session is closed");
+  }
+  assertCandidate(candidate) {
+    this.assertOpen();
+    const registered = this.candidates.get(candidate.lease.attempt);
+    if (candidate.generation !== this.generation || registered === void 0) {
+      throw new Error("DDC candidate belongs to another generation session");
+    }
+    return registered;
+  }
+  scheduleHeartbeat(candidate) {
+    const attempt = candidate.lease.attempt;
+    this.stopHeartbeat(candidate);
+    const delay2 = Math.max(1, Math.floor((candidate.lease.expiresAt - Date.now()) / 2));
+    const timer = setTimeout(() => {
+      this.heartbeatTimers.delete(attempt);
+      if (!this.accepting || this.candidates.get(attempt) !== candidate) return;
+      void this.lifecycle.heartbeat(candidate.lease).then((lease) => {
+        if (!this.accepting || this.candidates.get(attempt) !== candidate) return;
+        candidate.lease = lease;
+        this.scheduleHeartbeat(candidate);
+      }).catch(() => {
+        this.stopHeartbeat(candidate);
+      });
+    }, delay2);
+    timer.unref?.();
+    this.heartbeatTimers.set(attempt, timer);
+  }
+  stopHeartbeat(candidate) {
+    const attempt = "lease" in candidate ? candidate.lease.attempt : candidate.attempt;
+    const timer = this.heartbeatTimers.get(attempt);
+    if (timer === void 0) return;
+    clearTimeout(timer);
+    this.heartbeatTimers.delete(attempt);
+  }
+};
+
+// src/status.ts
+var DDC_STATUS_SCHEMA = "forgeax-ddc-status/v2";
+function serializeDdcStatus(status) {
+  return JSON.stringify(status);
+}
+function projectDdcStatusForBrowser(status) {
+  return {
+    schemaVersion: DDC_STATUS_SCHEMA,
+    health: status.health,
+    layers: status.layers.map((layer) => ({
+      ...layer,
+      actions: layer.actions.map(({ exactTarget: _exactTarget, ...action }) => action)
+    }))
+  };
+}
+var toBrowserDdcStatus = projectDdcStatusForBrowser;
+
+export { DDC_ERROR_CODES, DDC_LAYOUT_VERSION, DDC_STATUS_SCHEMA, DdcEntryStore, DdcGenerationSession, DdcLifecycle, DdcStoreError, assertRuntimeScope, collectDdcGarbage, createAcceptedPublication, createAcceptedPublicationStore, createRuntimeScope, ddcOutputDigest, isDdcLayout, projectDdcStatusForBrowser, resolveBuildDdcLayout, resolveDdcLayout, resolveDdcRoot, runtimeScopeHash, scriptablePackOutputSetDigest, scriptablePackPublicationGeneration, semanticBuildKey, semanticDdcKey, serializeDdcStatus, toBrowserDdcStatus };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map