@forgeax/engine-ddc 0.1.2

package/dist/index.mjs

@@ -0,0 +1,896 @@
+import { createHash, randomUUID } from 'crypto';
+import { mkdir, writeFile, stat, rm, rename, readdir, readFile } from 'fs/promises';
+import { join, isAbsolute, normalize } from 'path';
+
+// src/entry-store.ts
+
+// 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
+      )
+    };
+  }
+};
+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/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()}`);
+    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 };
+  }
+  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 });
+    try {
+      await stat(target);
+      const existing = await this.readDirectory(target, false);
+      await rm(staged.path, { recursive: true, force: true });
+      return existingResult(existing, candidate, staged.key);
+    } 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;
+      const existing = await this.readDirectory(target, false);
+      await rm(staged.path, { recursive: true, force: true });
+      return existingResult(existing, candidate, staged.key);
+    }
+  }
+  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) {
+  const value = { ...result };
+  Object.defineProperty(value, "revision", { value: revision, 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.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);
+    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 failure = recordedFailure ?? entryFailure;
+    const currentValue = currentEntry?.ok === true ? currentEntry.value : null;
+    const state = failure !== void 0 ? "failed" : record.currentKey === desiredKey && currentValue?.guid === guid ? "current" : record.stale === true ? "stale" : record.active?.desiredKey === desiredKey ? "cooking" : "stale";
+    return {
+      guid,
+      desiredKey,
+      state,
+      currentKey: record.currentKey,
+      lastKnownGoodKey: record.lastKnownGoodKey,
+      revision: record.revision,
+      ...record.generation === void 0 ? {} : { generation: record.generation },
+      ...record.active === void 0 ? {} : { activeLease: record.active },
+      ...failure === void 0 ? {} : { failure }
+    };
+  }
+  async begin(guid, desiredKey) {
+    return withDdcLock(this.root, `head-${guid}`, async () => {
+      const previous = await this.read(guid);
+      const generation = await this.allocateGeneration();
+      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;
+    });
+  }
+  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) {
+        await this.write({
+          guid: lease.guid,
+          desiredKey: lease.desiredKey,
+          revision: current.revision + 1,
+          generation: lease.generation,
+          ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+          failure: {
+            desiredKey: lease.desiredKey,
+            code: "entry-invalid",
+            detail: "validated DDC key has no readable entry for this asset"
+          }
+        });
+        return withRevision({ result: "invalid", key: validatedKey }, current.revision + 1);
+      }
+      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);
+    });
+  }
+  async fail(lease, failure) {
+    await withDdcLock(this.root, `head-${lease.guid}`, async () => {
+      const current = await this.read(lease.guid);
+      if (current?.active?.attempt !== lease.attempt) return;
+      await this.write({
+        guid: lease.guid,
+        desiredKey: lease.desiredKey,
+        revision: current.revision + 1,
+        generation: lease.generation,
+        ...current.currentKey === void 0 ? {} : { currentKey: current.currentKey },
+        ...current.lastKnownGoodKey === void 0 ? {} : { lastKnownGoodKey: current.lastKnownGoodKey },
+        failure: { desiredKey: lease.desiredKey, ...failure }
+      });
+    });
+  }
+  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 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.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);
+    });
+  }
+  async allocateGeneration() {
+    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.isInteger(record.next))
+        next = Math.max(1, record.next);
+    } catch {
+    }
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    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 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/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, DdcLifecycle, DdcStoreError, assertRuntimeScope, collectDdcGarbage, createRuntimeScope, ddcOutputDigest, isDdcLayout, projectDdcStatusForBrowser, resolveBuildDdcLayout, resolveDdcLayout, runtimeScopeHash, semanticDdcKey, serializeDdcStatus, toBrowserDdcStatus };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map