create-thally-docs 0.10.88 → 0.10.90

package/dist/{chunk-JZ75H4V3.js → chunk-HRCNLXFC.js}

@@ -8,7 +8,7 @@ import {
   installDeps,
   runProjectCommand,
   scaffold
-} from "./chunk-YBVSKK53.js";
+} from "./chunk-IX2FP4D5.js";
 import {
   pruneMissingSiteLinks
 } from "./chunk-UG3OXVLE.js";

package/dist/{chunk-YBVSKK53.js → chunk-IX2FP4D5.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-J7255UQA.js";
 import {
   downloadStarter
-} from "./chunk-QCHFKSPD.js";
+} from "./chunk-VHIX2IYK.js";
 import {
   terminal
 } from "./chunk-L2YCVQBR.js";

package/dist/chunk-J5V4UJXD.js

@@ -0,0 +1,471 @@
+#!/usr/bin/env node
+import {
+  downloadStarter
+} from "./chunk-VHIX2IYK.js";
+import {
+  applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
+  mergeStarterOwnershipContracts,
+  parseStarterReleaseManifest,
+  planStarterRuntimeSync,
+  readStarterReleaseManifest,
+  starterManifestSha256
+} from "./chunk-LKI5X3H2.js";
+import {
+  STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES
+} from "./chunk-D7ANFHIL.js";
+
+// src/starter-update.ts
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync
+} from "fs";
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
+import { tmpdir } from "os";
+import { join } from "path";
+
+// src/starter-manual-review.ts
+import { isDeepStrictEqual } from "util";
+var STRUCTURED_MANUAL_REVIEW_PATHS = /* @__PURE__ */ new Set([
+  "package.json",
+  "package-lock.json"
+]);
+var MISSING_JSON_VALUE = /* @__PURE__ */ Symbol("missing-json-value");
+function hasSameBytes(left, right) {
+  if (!left || !right) return left === right;
+  return left.equals(right);
+}
+function isJsonObject(value) {
+  return value !== MISSING_JSON_VALUE && value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function escapeJsonPointerSegment(segment) {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function childJsonPointer(pointer, segment) {
+  return `${pointer}/${escapeJsonPointerSegment(segment)}`;
+}
+function sameJsonValue(left, right) {
+  if (left === MISSING_JSON_VALUE || right === MISSING_JSON_VALUE) {
+    return left === right;
+  }
+  return isDeepStrictEqual(left, right);
+}
+function mergeJsonValue(previous, downstream, target, pointer = "") {
+  if (sameJsonValue(downstream, target)) {
+    return { value: downstream, conflicts: [] };
+  }
+  if (sameJsonValue(previous, target)) {
+    return { value: downstream, conflicts: [] };
+  }
+  if (sameJsonValue(previous, downstream)) {
+    return { value: target, conflicts: [] };
+  }
+  if (isJsonObject(previous) && isJsonObject(downstream) && isJsonObject(target)) {
+    const keys = Array.from(
+      /* @__PURE__ */ new Set([
+        ...Object.keys(downstream),
+        ...Object.keys(target),
+        ...Object.keys(previous)
+      ])
+    );
+    const entries = [];
+    const conflicts = [];
+    for (const key of keys) {
+      const merged = mergeJsonValue(
+        Object.hasOwn(previous, key) ? previous[key] : MISSING_JSON_VALUE,
+        Object.hasOwn(downstream, key) ? downstream[key] : MISSING_JSON_VALUE,
+        Object.hasOwn(target, key) ? target[key] : MISSING_JSON_VALUE,
+        childJsonPointer(pointer, key)
+      );
+      conflicts.push(...merged.conflicts);
+      if (merged.value !== MISSING_JSON_VALUE) {
+        entries.push([key, merged.value]);
+      }
+    }
+    return { value: Object.fromEntries(entries), conflicts };
+  }
+  return { value: downstream, conflicts: [pointer || "/"] };
+}
+function mergeStructuredManualReviewFile(input) {
+  try {
+    const previous = JSON.parse(input.previous.toString("utf8"));
+    const downstream = JSON.parse(
+      input.downstream.toString("utf8")
+    );
+    const target = JSON.parse(input.target.toString("utf8"));
+    const merged = mergeJsonValue(previous, downstream, target);
+    if (merged.conflicts.length > 0 || merged.value === MISSING_JSON_VALUE) {
+      return { conflicts: merged.conflicts };
+    }
+    return {
+      content: Buffer.from(`${JSON.stringify(merged.value, null, 2)}
+`),
+      conflicts: []
+    };
+  } catch {
+    return { conflicts: ["/"] };
+  }
+}
+function resolveManualReviewMutations(paths, downstreamFiles, previousReleaseFiles, targetReleaseFiles) {
+  const mutations = {
+    writeFiles: /* @__PURE__ */ new Map(),
+    deletePaths: [],
+    conflicts: []
+  };
+  for (const path of paths) {
+    const downstream = downstreamFiles.get(path);
+    const previous = previousReleaseFiles.get(path);
+    const target = targetReleaseFiles.get(path);
+    if (hasSameBytes(previous, target) || hasSameBytes(downstream, target)) {
+      continue;
+    }
+    if (hasSameBytes(downstream, previous)) {
+      if (target) mutations.writeFiles.set(path, target);
+      else mutations.deletePaths.push(path);
+      continue;
+    }
+    if (STRUCTURED_MANUAL_REVIEW_PATHS.has(path) && downstream && previous && target) {
+      const merged = mergeStructuredManualReviewFile({
+        previous,
+        downstream,
+        target
+      });
+      if (merged.content) {
+        if (!hasSameBytes(downstream, merged.content)) {
+          mutations.writeFiles.set(path, merged.content);
+        }
+        continue;
+      }
+      mutations.conflicts.push({ path, fields: merged.conflicts });
+      continue;
+    }
+    mutations.conflicts.push({ path, fields: [] });
+  }
+  return mutations;
+}
+
+// src/starter-update.ts
+var EMPTY_PLAN = {
+  copyPaths: [],
+  deletePaths: [],
+  conflictPaths: [],
+  manualReviewPaths: [],
+  preservedPaths: [],
+  unchangedPaths: [],
+  targetPreconditions: {}
+};
+function readDownstreamManifest(targetDir, manifestPath) {
+  const path = join(targetDir, manifestPath);
+  if (!existsSync(path)) {
+    throw new Error(
+      `This project has no ${manifestPath}; update it from a versioned Thally starter first.`
+    );
+  }
+  const entry = lstatSync(path);
+  if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 256 * 1024) {
+    throw new Error("The project starter manifest must be a bounded regular file.");
+  }
+  return readFileSync(path, "utf8");
+}
+function resolveStarterReleaseFromManifest(source, releases = SUPPORTED_SCAFFOLD_RELEASES) {
+  const hash = starterManifestSha256(source);
+  const matching = releases.filter(
+    (release) => release.source.manifestSha256 === hash
+  );
+  if (matching.length !== 1) {
+    throw new Error(
+      "The project starter manifest is edited, unknown, or ambiguously registered; refusing to update."
+    );
+  }
+  parseStarterReleaseManifest(source, matching[0]);
+  return matching[0];
+}
+function starterReleaseProviderError(cause) {
+  return Object.assign(new Error("The public starter release provider is unavailable.", { cause }), {
+    name: "StarterReleaseProviderError",
+    code: "STARTER_RELEASE_PROVIDER_UNAVAILABLE"
+  });
+}
+async function fetchStarterReleaseHint(runtimeCommitSha) {
+  if (!/^[a-f0-9]{40}$/.test(runtimeCommitSha)) return void 0;
+  let response;
+  try {
+    response = await fetch(
+      `https://raw.githubusercontent.com/thallylabs/thally/${runtimeCommitSha}/packages/create-thally-docs/src/stable-scaffold-release.json`,
+      { signal: AbortSignal.timeout(15e3), redirect: "error" }
+    );
+  } catch (error) {
+    throw starterReleaseProviderError(error);
+  }
+  if (response.status === 404) return void 0;
+  if (!response.ok || !response.body) throw starterReleaseProviderError();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        throw starterReleaseProviderError(error);
+      }
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 256 * 1024) return void 0;
+      chunks.push(chunk.value);
+    }
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    } catch {
+      return void 0;
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+function comparableManifest(source) {
+  const manifest = JSON.parse(source);
+  const runtime = manifest.runtime;
+  if (!runtime || typeof runtime !== "object" || Array.isArray(runtime)) return void 0;
+  const runtimeContract = { ...runtime };
+  delete runtimeContract.commitSha;
+  delete runtimeContract.treeSha;
+  return { ...manifest, runtime: runtimeContract };
+}
+function assertRecoveryPackages(targetDir, baselineDir, packages) {
+  const installed = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf8"));
+  const declarations = { ...installed.dependencies, ...installed.devDependencies };
+  for (const [name, version] of Object.entries(packages)) {
+    if (declarations[name] !== version) throw new Error("Installed starter packages do not match the recovery baseline.");
+  }
+  if (existsSync(join(baselineDir, "package-lock.json"))) {
+    const canonical = JSON.parse(readFileSync(join(baselineDir, "package-lock.json"), "utf8"));
+    const current = JSON.parse(readFileSync(join(targetDir, "package-lock.json"), "utf8"));
+    for (const name of Object.keys(packages)) {
+      const path = `node_modules/${name}`;
+      const expected = canonical.packages?.[path];
+      if (!expected?.version || !isDeepStrictEqual2(current.packages?.[path], expected)) {
+        throw new Error("Installed starter package lock does not match the recovery baseline.");
+      }
+    }
+  }
+}
+async function resolveStarterUpdateBase(options) {
+  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
+  const manifestPath = STABLE_SCAFFOLD_RELEASE.source.manifestPath;
+  const source = readDownstreamManifest(options.targetDir, manifestPath);
+  const manifestSha256 = starterManifestSha256(source);
+  const exact = releases.filter((release) => release.source.manifestSha256 === manifestSha256);
+  if (exact.length) return { release: resolveStarterReleaseFromManifest(source, releases), recoveredProvenance: false, manifestSha256 };
+  if (Buffer.byteLength(source, "utf8") > 256 * 1024) throw new Error("The project starter manifest is too large.");
+  let candidate;
+  try {
+    candidate = JSON.parse(source);
+  } catch {
+    throw new Error("The project starter manifest is invalid JSON.");
+  }
+  const runtime = candidate?.runtime;
+  if (!runtime || typeof runtime.commitSha !== "string" || !/^[a-f0-9]{40}$/.test(runtime.commitSha) || typeof runtime.treeSha !== "string" || !/^[a-f0-9]{40}$/.test(runtime.treeSha)) {
+    throw new Error("The project starter manifest has no verifiable recovery baseline.");
+  }
+  let candidates = releases.filter((release) => release.runtime.commitSha === runtime.commitSha);
+  if (!candidates.length) {
+    const hint = await (options.resolveReleaseHint ?? fetchStarterReleaseHint)(runtime.commitSha);
+    const record = hint;
+    candidates = releases.filter((release) => record?.id === release.id && record.source?.commitSha === release.source.commitSha);
+  }
+  const download = options.download ?? (async (directory, release) => {
+    await downloadStarter(directory, void 0, release, { announce: false });
+  });
+  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-base-"));
+  try {
+    for (const [index, release] of candidates.entries()) {
+      const baselineDir = join(workspace, String(index));
+      mkdirSync(baselineDir);
+      await download(baselineDir, release);
+      const baseline = readStarterReleaseManifest(baselineDir, release);
+      const canonicalSource = readFileSync(join(baselineDir, manifestPath), "utf8");
+      if (!isDeepStrictEqual2(comparableManifest(source), comparableManifest(canonicalSource))) continue;
+      const ownership = mergeStarterOwnershipContracts(baseline.ownership, baseline.ownership);
+      const proof = planStarterRuntimeSync(baselineDir, baselineDir, options.targetDir, ownership);
+      if (proof.copyPaths.length || proof.deletePaths.length || proof.preservedPaths.length || proof.conflictPaths.length) continue;
+      assertRecoveryPackages(options.targetDir, baselineDir, baseline.packages);
+      return { release, recoveredProvenance: true, manifestSha256 };
+    }
+    throw new Error("The project starter manifest is edited, unknown, or has no verified published framework baseline; refusing to update.");
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+function assertForwardRelease(previous, target, releases) {
+  if (previous.source.repository !== target.source.repository || previous.source.manifestPath !== target.source.manifestPath) {
+    throw new Error("Starter updates cannot cross repository or manifest contracts.");
+  }
+  if (previous.source.commitSha === target.source.commitSha) return;
+  if (previous.starterVersion > target.starterVersion) {
+    throw new Error("The installed CLI does not contain a newer starter release.");
+  }
+  if (previous.starterVersion === target.starterVersion) {
+    const targetIndex = releases.findIndex(
+      (release) => release.source.commitSha === target.source.commitSha
+    );
+    const previousIndex = releases.findIndex(
+      (release) => release.source.commitSha === previous.source.commitSha
+    );
+    if (targetIndex === -1 || previousIndex === -1 || previousIndex <= targetIndex) {
+      throw new Error("The installed CLI does not contain a newer starter release.");
+    }
+  }
+}
+async function updateStarterProject(options) {
+  const targetRelease = options.targetRelease ?? STABLE_SCAFFOLD_RELEASE;
+  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
+  if (!releases.some((release) => isDeepStrictEqual2(release, targetRelease))) {
+    throw new Error("The target starter release is not in the trusted release catalog.");
+  }
+  const manifestPath = targetRelease.source.manifestPath;
+  const downstreamManifest = readDownstreamManifest(options.targetDir, manifestPath);
+  const base = await resolveStarterUpdateBase({ ...options, releases });
+  const previousRelease = base.release;
+  if (base.manifestSha256 !== starterManifestSha256(downstreamManifest) || readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
+    throw new Error("The project starter manifest changed during update planning.");
+  }
+  assertForwardRelease(previousRelease, targetRelease, releases);
+  if (!base.recoveredProvenance && previousRelease.source.commitSha === targetRelease.source.commitSha) {
+    return {
+      previousRelease,
+      targetRelease,
+      plan: EMPTY_PLAN,
+      isUpToDate: true,
+      applied: false
+    };
+  }
+  if (options.apply && !options.confirmed) {
+    throw new Error("Pass explicit confirmation before applying a starter update.");
+  }
+  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-update-"));
+  const oldStarterDir = join(workspace, "old");
+  const newStarterDir = join(workspace, "new");
+  mkdirSync(oldStarterDir);
+  mkdirSync(newStarterDir);
+  const download = options.download ?? (async (targetDir, release) => {
+    await downloadStarter(targetDir, void 0, release, { announce: false });
+  });
+  try {
+    await download(oldStarterDir, previousRelease);
+    await download(newStarterDir, targetRelease);
+    const oldManifest = readStarterReleaseManifest(oldStarterDir, previousRelease);
+    const newManifest = readStarterReleaseManifest(newStarterDir, targetRelease);
+    const ownership = mergeStarterOwnershipContracts(
+      oldManifest.ownership,
+      newManifest.ownership
+    );
+    if (base.recoveredProvenance) {
+      const proof = planStarterRuntimeSync(
+        oldStarterDir,
+        oldStarterDir,
+        options.targetDir,
+        mergeStarterOwnershipContracts(oldManifest.ownership, oldManifest.ownership)
+      );
+      if (proof.copyPaths.length || proof.deletePaths.length || proof.preservedPaths.length || proof.conflictPaths.length) {
+        throw new Error("The recovery framework changed during update planning.");
+      }
+      assertRecoveryPackages(options.targetDir, oldStarterDir, oldManifest.packages);
+    }
+    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
+      throw new Error("The project starter manifest changed during update planning.");
+    }
+    const plan = planStarterRuntimeSync(
+      oldStarterDir,
+      newStarterDir,
+      options.targetDir,
+      ownership
+    );
+    const allManualPreconditions = Object.fromEntries(plan.manualReviewPaths.map((path) => [
+      path,
+      captureTargetPrecondition(join(options.targetDir, path))
+    ]));
+    const readManualFiles = (root) => new Map(
+      plan.manualReviewPaths.filter((path) => existsSync(join(root, path))).map((path) => {
+        const entry = lstatSync(join(root, path));
+        if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Manual starter updates require regular files.");
+        return [path, readFileSync(join(root, path))];
+      })
+    );
+    const manual = resolveManualReviewMutations(
+      plan.manualReviewPaths,
+      readManualFiles(options.targetDir),
+      readManualFiles(oldStarterDir),
+      readManualFiles(newStarterDir)
+    );
+    const resolvedManualPaths = [...manual.writeFiles.keys(), ...manual.deletePaths].sort();
+    const manualPreconditions = Object.fromEntries(resolvedManualPaths.map((path) => [
+      path,
+      allManualPreconditions[path]
+    ]));
+    plan.conflictPaths = [.../* @__PURE__ */ new Set([...plan.conflictPaths, ...manual.conflicts.map((conflict) => conflict.path)])].sort();
+    plan.manualReviewPaths = manual.conflicts.map((conflict) => conflict.path);
+    if (!options.apply) {
+      return {
+        previousRelease,
+        targetRelease,
+        plan,
+        isUpToDate: false,
+        applied: false,
+        recoveredProvenance: base.recoveredProvenance,
+        manualConflicts: manual.conflicts,
+        resolvedManualPaths,
+        deletedManualPaths: manual.deletePaths
+      };
+    }
+    if (plan.conflictPaths.length > 0) {
+      throw new Error("Resolve starter synchronization conflicts before applying.");
+    }
+    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
+      throw new Error("The project starter manifest changed during update planning.");
+    }
+    applyStarterRuntimeSyncPlan(
+      newStarterDir,
+      options.targetDir,
+      plan,
+      ownership,
+      {
+        confirmed: true,
+        manualMutations: { ...manual, targetPreconditions: manualPreconditions },
+        provenance: {
+          sourcePath: join(newStarterDir, manifestPath),
+          targetPath: join(options.targetDir, manifestPath),
+          expectedSha256: base.manifestSha256
+        }
+      }
+    );
+    return {
+      previousRelease,
+      targetRelease,
+      plan,
+      isUpToDate: false,
+      applied: true,
+      recoveredProvenance: base.recoveredProvenance,
+      manualConflicts: manual.conflicts,
+      resolvedManualPaths,
+      deletedManualPaths: manual.deletePaths
+    };
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+
+export {
+  resolveManualReviewMutations,
+  resolveStarterReleaseFromManifest,
+  starterReleaseProviderError,
+  fetchStarterReleaseHint,
+  resolveStarterUpdateBase,
+  updateStarterProject
+};

package/dist/{chunk-MFJ6H3MQ.js → chunk-LKI5X3H2.js}

@@ -14,6 +14,7 @@ import {
   readFileSync,
   readdirSync,
   renameSync,
+  writeFileSync,
   rmSync
 } from "fs";
 import { dirname, join, relative, resolve, sep } from "path";
@@ -212,6 +213,7 @@ function collectFiles(root, contract, desiredOwnership) {
   const rules = desiredOwnership === "syncable" ? contract.frameworkSyncEligible : contract.manualReview;
   const visit = (absolutePath) => {
     const resolvedPath = resolve(absolutePath);
+    if (resolvedPath !== resolve(root)) assertSafeTargetParents(root, resolvedPath);
     if (visited.has(resolvedPath)) return;
     visited.add(resolvedPath);
     const repositoryPath = filesystemPathToRepositoryPath(root, resolvedPath);
@@ -362,15 +364,20 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
   if (plan.conflictPaths.length > 0) {
     throw new Error("Resolve starter synchronization conflicts before applying.");
   }
-  const uniqueMutations = /* @__PURE__ */ new Set([...plan.copyPaths, ...plan.deletePaths]);
-  if (uniqueMutations.size !== plan.copyPaths.length + plan.deletePaths.length) {
+  const manual = options.manualMutations;
+  const copyPaths = [...plan.copyPaths, ...manual?.writeFiles.keys() ?? []];
+  const deletePaths = [...plan.deletePaths, ...manual?.deletePaths ?? []];
+  const preconditions = { ...plan.targetPreconditions, ...manual?.targetPreconditions };
+  const uniqueMutations = /* @__PURE__ */ new Set([...copyPaths, ...deletePaths]);
+  if (uniqueMutations.size !== copyPaths.length + deletePaths.length) {
     throw new Error("Starter synchronization plan contains conflicting mutations.");
   }
   for (const path of uniqueMutations) {
-    if (classifyStarterPath(path, contract) !== "syncable") {
+    const isManualMutation = manual?.writeFiles.has(path) || manual?.deletePaths.includes(path);
+    if (classifyStarterPath(path, contract) !== (isManualMutation ? "manual" : "syncable")) {
       throw new Error(`Starter synchronization refused owner path ${path}.`);
     }
-    if (!plan.targetPreconditions[path]) {
+    if (!preconditions[path]) {
       throw new Error(`Starter synchronization plan lacks a target precondition for ${path}.`);
     }
   }
@@ -428,7 +435,11 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
     mutationIndex += 1;
   };
   try {
-    for (const path of plan.copyPaths) {
+    for (const path of copyPaths) {
+      if (manual?.writeFiles.has(path)) {
+        writeFileSync(stagePath(path), manual.writeFiles.get(path));
+        continue;
+      }
       const sourcePath = ensureContained(newStarterDir, path);
       if (!existsSync(sourcePath) || !lstatSync(sourcePath).isFile()) {
         throw new Error(`Starter synchronization source is missing ${path}.`);
@@ -446,7 +457,7 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
     for (const path of uniqueMutations) {
       const targetPath = ensureContained(targetDir, path);
       assertSafeTargetParents(targetDir, targetPath);
-      if (!matchesTargetPrecondition(targetPath, plan.targetPreconditions[path])) {
+      if (!matchesTargetPrecondition(targetPath, preconditions[path])) {
         throw new Error(`Starter synchronization target changed after planning: ${path}.`);
       }
     }
@@ -456,18 +467,18 @@ function applyStarterRuntimeSyncPlan(newStarterDir, targetDir, plan, ownership,
         throw new Error("The project starter manifest changed during update planning.");
       }
     }
-    for (const path of plan.deletePaths) {
+    for (const path of deletePaths) {
       mutate(
         path,
         ensureContained(targetDir, path),
-        plan.targetPreconditions[path]
+        preconditions[path]
       );
     }
-    for (const path of plan.copyPaths) {
+    for (const path of copyPaths) {
       mutate(
         path,
         ensureContained(targetDir, path),
-        plan.targetPreconditions[path],
+        preconditions[path],
         ensureContained(stagedDir, path)
       );
     }
@@ -515,6 +526,7 @@ export {
   parseStarterReleaseManifest,
   readStarterReleaseManifest,
   classifyStarterPath,
+  captureTargetPrecondition,
   planStarterRuntimeSync,
   applyStarterRuntimeSyncPlan
 };

package/dist/{chunk-QCHFKSPD.js → chunk-VHIX2IYK.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
+import {
+  terminal
+} from "./chunk-L2YCVQBR.js";
 import {
   readStarterReleaseManifest
-} from "./chunk-MFJ6H3MQ.js";
+} from "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-D7ANFHIL.js";
-import {
-  terminal
-} from "./chunk-L2YCVQBR.js";
 
 // src/download.ts
 import { Readable, Transform, pipeline } from "stream";

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "./chunk-JZ75H4V3.js";
+} from "./chunk-HRCNLXFC.js";
 import {
   parseFrontmatter,
   runCheck
@@ -13,17 +13,17 @@ import {
   scaffold,
   slugify,
   success
-} from "./chunk-YBVSKK53.js";
+} from "./chunk-IX2FP4D5.js";
 import "./chunk-UG3OXVLE.js";
 import "./chunk-J7255UQA.js";
-import "./chunk-QCHFKSPD.js";
-import "./chunk-MFJ6H3MQ.js";
-import "./chunk-D7ANFHIL.js";
+import "./chunk-VHIX2IYK.js";
 import {
   acquireTerminalAccent,
   formatHelp,
   terminal
 } from "./chunk-L2YCVQBR.js";
+import "./chunk-LKI5X3H2.js";
+import "./chunk-D7ANFHIL.js";
 
 // src/index.ts
 import { existsSync as existsSync2, readdirSync } from "fs";

package/dist/migrate/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-JZ75H4V3.js";
+} from "../chunk-HRCNLXFC.js";
 import "../chunk-KDLP27DS.js";
-import "../chunk-YBVSKK53.js";
+import "../chunk-IX2FP4D5.js";
 import "../chunk-UG3OXVLE.js";
 import "../chunk-J7255UQA.js";
-import "../chunk-QCHFKSPD.js";
-import "../chunk-MFJ6H3MQ.js";
-import "../chunk-D7ANFHIL.js";
+import "../chunk-VHIX2IYK.js";
 import "../chunk-L2YCVQBR.js";
+import "../chunk-LKI5X3H2.js";
+import "../chunk-D7ANFHIL.js";
 export {
   migrateDocs
 };

package/dist/scaffold.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   scaffold
-} from "./chunk-YBVSKK53.js";
+} from "./chunk-IX2FP4D5.js";
 import "./chunk-UG3OXVLE.js";
 import "./chunk-J7255UQA.js";
 import {
@@ -9,12 +9,12 @@ import {
   STARTER_COMMIT_SHA,
   STARTER_REPOSITORY,
   validateStarterArchiveEntry
-} from "./chunk-QCHFKSPD.js";
-import "./chunk-MFJ6H3MQ.js";
+} from "./chunk-VHIX2IYK.js";
+import "./chunk-L2YCVQBR.js";
+import "./chunk-LKI5X3H2.js";
 import {
   STABLE_SCAFFOLD_RELEASE
 } from "./chunk-D7ANFHIL.js";
-import "./chunk-L2YCVQBR.js";
 export {
   STABLE_SCAFFOLD_RELEASE,
   STARTER_ARCHIVE_ROOT,

package/dist/starter-sync.d.ts

@@ -5,8 +5,8 @@ import { ScaffoldOwnershipContract, ScaffoldRelease, StarterReleaseManifest } fr
  *
  * The ownership contract comes from the pinned starter archive's
  * `starter-release.json`. Automatic updates touch only framework-eligible files
- * that still match the recorded old starter; owner and manual-review paths are
- * never included in an apply plan.
+ * that still match the recorded old starter. Owner paths are never mutated;
+ * manual-review files join the transaction only after a separate safe merge.
  */
 
 type StarterPathOwnership = 'protected' | 'manual' | 'syncable' | 'unmanaged';
@@ -34,6 +34,12 @@ interface ApplyStarterRuntimeSyncOptions {
     /** Optional immutable provenance file, atomically replaced after mutations. */
     provenance?: StarterApplyProvenance;
     /** Integration hook; an exception aborts and rolls back the transaction. */
+    /** Owner-reviewed paths explicitly resolved by the shared three-way merge. */
+    manualMutations?: {
+        writeFiles: ReadonlyMap<string, Buffer>;
+        deletePaths: readonly string[];
+        targetPreconditions: Record<string, StarterTargetPrecondition>;
+    };
     onMutationApplied?: (path: string, index: number) => void;
 }
 /** Parse and validate the ownership section in `starter-release.json`. */
@@ -57,6 +63,8 @@ declare function parseStarterReleaseManifest(source: string, release?: ScaffoldR
 declare function readStarterReleaseManifest(starterDir: string, release?: ScaffoldRelease): StarterReleaseManifest;
 /** Protected > manual-review > syncable > unmanaged. */
 declare function classifyStarterPath(path: string, contract: ScaffoldOwnershipContract): StarterPathOwnership;
+/** Capture exact file identity before planning a filesystem mutation. */
+declare function captureTargetPrecondition(path: string): StarterTargetPrecondition;
 /**
  * Build a safe three-way update plan from the recorded old starter, the new
  * starter, and the customer's current tree.
@@ -65,4 +73,4 @@ declare function planStarterRuntimeSync(oldStarterDir: string, newStarterDir: st
 /** Apply an explicitly confirmed, conflict-free three-way plan. */
 declare function applyStarterRuntimeSyncPlan(newStarterDir: string, targetDir: string, plan: StarterRuntimeSyncPlan, ownership: ScaffoldOwnershipContract, options: ApplyStarterRuntimeSyncOptions): void;
 
-export { type ApplyStarterRuntimeSyncOptions, type StarterApplyProvenance, type StarterPathOwnership, type StarterRuntimeSyncPlan, type StarterTargetPrecondition, applyStarterRuntimeSyncPlan, classifyStarterPath, mergeStarterOwnershipContracts, parseStarterOwnershipContract, parseStarterReleaseManifest, planStarterRuntimeSync, readStarterReleaseManifest, starterManifestSha256 };
+export { type ApplyStarterRuntimeSyncOptions, type StarterApplyProvenance, type StarterPathOwnership, type StarterRuntimeSyncPlan, type StarterTargetPrecondition, applyStarterRuntimeSyncPlan, captureTargetPrecondition, classifyStarterPath, mergeStarterOwnershipContracts, parseStarterOwnershipContract, parseStarterReleaseManifest, planStarterRuntimeSync, readStarterReleaseManifest, starterManifestSha256 };

package/dist/starter-sync.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
   classifyStarterPath,
   mergeStarterOwnershipContracts,
   parseStarterOwnershipContract,
@@ -8,10 +9,11 @@ import {
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-MFJ6H3MQ.js";
+} from "./chunk-LKI5X3H2.js";
 import "./chunk-D7ANFHIL.js";
 export {
   applyStarterRuntimeSyncPlan,
+  captureTargetPrecondition,
   classifyStarterPath,
   mergeStarterOwnershipContracts,
   parseStarterOwnershipContract,

package/dist/starter-update.d.ts

@@ -1,6 +1,28 @@
 import { ScaffoldRelease } from './release.js';
 import { StarterRuntimeSyncPlan } from './starter-sync.js';
 
+/** File-level and JSON-pointer conflict details without customer file contents. */
+interface StarterManualConflict {
+    path: string;
+    fields: string[];
+}
+/** Complete resolved writes and deletions, or conflicts requiring owner review. */
+interface ManualReviewMutations {
+    writeFiles: Map<string, Buffer>;
+    deletePaths: Array<string>;
+    conflicts: Array<StarterManualConflict>;
+}
+/**
+ * Resolve manual-review files without silently overwriting downstream work.
+ *
+ * Package manifests and lockfiles sit outside the hidden runtime ownership
+ * surface. Their object keys have independent ownership, so non-overlapping
+ * JSON edits merge structurally: a customer package name survives while a
+ * framework dependency advances. Same-field edits and every unstructured
+ * manual-review file remain fail-closed.
+ */
+declare function resolveManualReviewMutations(paths: readonly string[], downstreamFiles: ReadonlyMap<string, Buffer>, previousReleaseFiles: ReadonlyMap<string, Buffer>, targetReleaseFiles: ReadonlyMap<string, Buffer>): ManualReviewMutations;
+
 /**
  * User-reachable orchestration for immutable starter release updates.
  *
@@ -22,6 +44,7 @@ interface UpdateStarterProjectOptions {
     targetRelease?: ScaffoldRelease;
     releases?: readonly ScaffoldRelease[];
     download?: StarterUpdateDownload;
+    resolveReleaseHint?: StarterReleaseHintResolver;
 }
 interface StarterUpdateResult {
     previousRelease: ScaffoldRelease;
@@ -29,9 +52,44 @@ interface StarterUpdateResult {
     plan: StarterRuntimeSyncPlan;
     isUpToDate: boolean;
     applied: boolean;
+    /** A verified published baseline replaced noncanonical manifest provenance. */
+    manualConflicts?: StarterManualConflict[];
+    resolvedManualPaths?: string[];
+    deletedManualPaths?: string[];
+    recoveredProvenance?: boolean;
 }
 /** Resolve exact downstream provenance without consulting a moving branch. */
 declare function resolveStarterReleaseFromManifest(source: string, releases?: readonly ScaffoldRelease[]): ScaffoldRelease;
+/** An untrusted promotion record can suggest only an already trusted release. */
+interface StarterReleaseHintResolver {
+    (runtimeCommitSha: string): Promise<unknown>;
+}
+/** Recognizable transient failure; callers must not cache it as unsupported. */
+declare function starterReleaseProviderError(cause?: unknown): Error & {
+    code: string;
+};
+/** Read a bounded lookup hint from the fixed public repository at an exact SHA. */
+declare function fetchStarterReleaseHint(runtimeCommitSha: string): Promise<unknown>;
+/** Trusted catalog and bounded download seams shared by CLI and managed callers. */
+interface ResolveStarterUpdateBaseOptions {
+    targetDir: string;
+    releases?: readonly ScaffoldRelease[];
+    download?: StarterUpdateDownload;
+    resolveReleaseHint?: StarterReleaseHintResolver;
+}
+/** Published baseline identity plus evidence needed to guard provenance writes. */
+interface StarterUpdateBase {
+    release: ScaffoldRelease;
+    recoveredProvenance: boolean;
+    /** The actual initial bytes, including noncanonical provenance, guard apply. */
+    manifestSha256: string;
+}
+/**
+ * Resolve a published three-way base. Unknown provenance is accepted only when
+ * its contract and complete framework inventory equal a trusted published tree.
+ * Neither arbitrary manifest ownership nor a fetched hint authorizes writes.
+ */
+declare function resolveStarterUpdateBase(options: ResolveStarterUpdateBaseOptions): Promise<StarterUpdateBase>;
 /**
  * Plan or explicitly apply an immutable three-way starter update.
  *
@@ -40,4 +98,4 @@ declare function resolveStarterReleaseFromManifest(source: string, releases?: re
  */
 declare function updateStarterProject(options: UpdateStarterProjectOptions): Promise<StarterUpdateResult>;
 
-export { type StarterUpdateDownload, type StarterUpdateResult, type UpdateStarterProjectOptions, resolveStarterReleaseFromManifest, updateStarterProject };
+export { type ManualReviewMutations, type ResolveStarterUpdateBaseOptions, type StarterManualConflict, type StarterReleaseHintResolver, type StarterUpdateBase, type StarterUpdateDownload, type StarterUpdateResult, type UpdateStarterProjectOptions, fetchStarterReleaseHint, resolveManualReviewMutations, resolveStarterReleaseFromManifest, resolveStarterUpdateBase, starterReleaseProviderError, updateStarterProject };

package/dist/starter-update.js

@@ -1,168 +1,21 @@
 #!/usr/bin/env node
 import {
-  downloadStarter
-} from "./chunk-QCHFKSPD.js";
-import {
-  applyStarterRuntimeSyncPlan,
-  mergeStarterOwnershipContracts,
-  parseStarterReleaseManifest,
-  planStarterRuntimeSync,
-  readStarterReleaseManifest,
-  starterManifestSha256
-} from "./chunk-MFJ6H3MQ.js";
-import {
-  STABLE_SCAFFOLD_RELEASE,
-  SUPPORTED_SCAFFOLD_RELEASES
-} from "./chunk-D7ANFHIL.js";
+  fetchStarterReleaseHint,
+  resolveManualReviewMutations,
+  resolveStarterReleaseFromManifest,
+  resolveStarterUpdateBase,
+  starterReleaseProviderError,
+  updateStarterProject
+} from "./chunk-J5V4UJXD.js";
+import "./chunk-VHIX2IYK.js";
 import "./chunk-L2YCVQBR.js";
-
-// src/starter-update.ts
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync
-} from "fs";
-import { tmpdir } from "os";
-import { join } from "path";
-var EMPTY_PLAN = {
-  copyPaths: [],
-  deletePaths: [],
-  conflictPaths: [],
-  manualReviewPaths: [],
-  preservedPaths: [],
-  unchangedPaths: [],
-  targetPreconditions: {}
-};
-function readDownstreamManifest(targetDir, manifestPath) {
-  const path = join(targetDir, manifestPath);
-  if (!existsSync(path)) {
-    throw new Error(
-      `This project has no ${manifestPath}; update it from a versioned Thally starter first.`
-    );
-  }
-  return readFileSync(path, "utf8");
-}
-function resolveStarterReleaseFromManifest(source, releases = SUPPORTED_SCAFFOLD_RELEASES) {
-  const hash = starterManifestSha256(source);
-  const matching = releases.filter(
-    (release) => release.source.manifestSha256 === hash
-  );
-  if (matching.length !== 1) {
-    throw new Error(
-      "The project starter manifest is edited, unknown, or ambiguously registered; refusing to update."
-    );
-  }
-  parseStarterReleaseManifest(source, matching[0]);
-  return matching[0];
-}
-function assertForwardRelease(previous, target, releases) {
-  if (previous.source.repository !== target.source.repository || previous.source.manifestPath !== target.source.manifestPath) {
-    throw new Error("Starter updates cannot cross repository or manifest contracts.");
-  }
-  if (previous.source.commitSha === target.source.commitSha) return;
-  if (previous.starterVersion > target.starterVersion) {
-    throw new Error("The installed CLI does not contain a newer starter release.");
-  }
-  if (previous.starterVersion === target.starterVersion) {
-    const targetIndex = releases.findIndex(
-      (release) => release.source.commitSha === target.source.commitSha
-    );
-    const previousIndex = releases.findIndex(
-      (release) => release.source.commitSha === previous.source.commitSha
-    );
-    if (targetIndex === -1 || previousIndex === -1 || previousIndex <= targetIndex) {
-      throw new Error("The installed CLI does not contain a newer starter release.");
-    }
-  }
-}
-async function updateStarterProject(options) {
-  const targetRelease = options.targetRelease ?? STABLE_SCAFFOLD_RELEASE;
-  const releases = options.releases ?? SUPPORTED_SCAFFOLD_RELEASES;
-  const manifestPath = targetRelease.source.manifestPath;
-  const downstreamManifest = readDownstreamManifest(options.targetDir, manifestPath);
-  const previousRelease = resolveStarterReleaseFromManifest(
-    downstreamManifest,
-    releases
-  );
-  assertForwardRelease(previousRelease, targetRelease, releases);
-  if (previousRelease.source.commitSha === targetRelease.source.commitSha) {
-    return {
-      previousRelease,
-      targetRelease,
-      plan: EMPTY_PLAN,
-      isUpToDate: true,
-      applied: false
-    };
-  }
-  if (options.apply && !options.confirmed) {
-    throw new Error("Pass explicit confirmation before applying a starter update.");
-  }
-  const workspace = mkdtempSync(join(tmpdir(), "thally-starter-update-"));
-  const oldStarterDir = join(workspace, "old");
-  const newStarterDir = join(workspace, "new");
-  mkdirSync(oldStarterDir);
-  mkdirSync(newStarterDir);
-  const download = options.download ?? (async (targetDir, release) => {
-    await downloadStarter(targetDir, void 0, release, { announce: false });
-  });
-  try {
-    await download(oldStarterDir, previousRelease);
-    await download(newStarterDir, targetRelease);
-    const oldManifest = readStarterReleaseManifest(oldStarterDir, previousRelease);
-    const newManifest = readStarterReleaseManifest(newStarterDir, targetRelease);
-    const ownership = mergeStarterOwnershipContracts(
-      oldManifest.ownership,
-      newManifest.ownership
-    );
-    const plan = planStarterRuntimeSync(
-      oldStarterDir,
-      newStarterDir,
-      options.targetDir,
-      ownership
-    );
-    if (!options.apply) {
-      return {
-        previousRelease,
-        targetRelease,
-        plan,
-        isUpToDate: false,
-        applied: false
-      };
-    }
-    if (plan.conflictPaths.length > 0) {
-      throw new Error("Resolve starter synchronization conflicts before applying.");
-    }
-    if (readDownstreamManifest(options.targetDir, manifestPath) !== downstreamManifest) {
-      throw new Error("The project starter manifest changed during update planning.");
-    }
-    applyStarterRuntimeSyncPlan(
-      newStarterDir,
-      options.targetDir,
-      plan,
-      ownership,
-      {
-        confirmed: true,
-        provenance: {
-          sourcePath: join(newStarterDir, manifestPath),
-          targetPath: join(options.targetDir, manifestPath),
-          expectedSha256: previousRelease.source.manifestSha256
-        }
-      }
-    );
-    return {
-      previousRelease,
-      targetRelease,
-      plan,
-      isUpToDate: false,
-      applied: true
-    };
-  } finally {
-    rmSync(workspace, { recursive: true, force: true });
-  }
-}
+import "./chunk-LKI5X3H2.js";
+import "./chunk-D7ANFHIL.js";
 export {
+  fetchStarterReleaseHint,
+  resolveManualReviewMutations,
   resolveStarterReleaseFromManifest,
+  resolveStarterUpdateBase,
+  starterReleaseProviderError,
   updateStarterProject
 };

package/dist/starter-upgrade-canary.d.ts

@@ -0,0 +1,18 @@
+import { ScaffoldRelease } from './release.js';
+import { StarterUpdateDownload } from './starter-update.js';
+import './starter-sync.js';
+
+/** Immutable candidate and trusted historical baselines used by release gates. */
+interface UpgradeCanaryOptions {
+    target: ScaffoldRelease;
+    candidateDirectory: string;
+    releases?: readonly ScaffoldRelease[];
+    current?: ScaffoldRelease;
+    download?: StarterUpdateDownload;
+}
+/** Reject noncanonical sources before any gate downloads an archive. */
+declare function assertCanonicalScaffoldUpgradeRelease(release: ScaffoldRelease): void;
+/** Run the current and oldest retained bases through the real complete updater. */
+declare function verifyScaffoldUpgrades(options: UpgradeCanaryOptions): Promise<string[]>;
+
+export { type UpgradeCanaryOptions, assertCanonicalScaffoldUpgradeRelease, verifyScaffoldUpgrades };

package/dist/starter-upgrade-canary.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import {
+  updateStarterProject
+} from "./chunk-J5V4UJXD.js";
+import {
+  downloadStarter
+} from "./chunk-VHIX2IYK.js";
+import "./chunk-L2YCVQBR.js";
+import {
+  classifyStarterPath,
+  mergeStarterOwnershipContracts,
+  readStarterReleaseManifest
+} from "./chunk-LKI5X3H2.js";
+import {
+  STABLE_SCAFFOLD_RELEASE,
+  SUPPORTED_SCAFFOLD_RELEASES
+} from "./chunk-D7ANFHIL.js";
+
+// src/starter-upgrade-canary.ts
+import { createHash } from "crypto";
+import { cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { isDeepStrictEqual } from "util";
+function files(root, prefix = "") {
+  const result = /* @__PURE__ */ new Map();
+  for (const entry of readdirSync(join(root, prefix))) {
+    const path = prefix ? `${prefix}/${entry}` : entry;
+    const stat = lstatSync(join(root, path));
+    if (stat.isSymbolicLink()) throw new Error("Canary archives cannot contain symbolic links.");
+    if (stat.isDirectory()) for (const [key, bytes] of files(root, path)) result.set(key, bytes);
+    else if (stat.isFile()) result.set(path, readFileSync(join(root, path)));
+    else throw new Error("Canary archives must contain only regular files.");
+  }
+  return result;
+}
+function assertCanonicalScaffoldUpgradeRelease(release) {
+  if (release.source.repository !== "thallylabs/starter" || release.runtime.repository !== "thallylabs/thally" || !/^[a-f0-9]{40}$/.test(release.source.commitSha) || !/^[a-f0-9]{40}$/.test(release.source.treeSha) || !/^[a-f0-9]{40}$/.test(release.runtime.commitSha) || !/^[a-f0-9]{40}$/.test(release.runtime.treeSha) || !/^[a-f0-9]{64}$/.test(release.source.manifestSha256) || release.source.archiveUrl !== `https://codeload.github.com/thallylabs/starter/tar.gz/${release.source.commitSha}`) {
+    throw new Error("Historical upgrade canaries require immutable canonical releases.");
+  }
+}
+async function verifyScaffoldUpgrades(options) {
+  const { target } = options;
+  assertCanonicalScaffoldUpgradeRelease(target);
+  const targetManifest = readStarterReleaseManifest(options.candidateDirectory, target);
+  const targetFiles = files(options.candidateDirectory);
+  const history = [...options.releases ?? SUPPORTED_SCAFFOLD_RELEASES].filter((release) => release.source.manifestSha256 !== target.source.manifestSha256);
+  if (!history.length) throw new Error("Historical upgrade canary has no retained baseline.");
+  const current = options.current ?? STABLE_SCAFFOLD_RELEASE;
+  const bases = [current, history.at(-1)].filter((release, index, all) => all.findIndex((other) => other.source.manifestSha256 === release.source.manifestSha256) === index);
+  const catalog = [target, ...bases, ...history].filter((release, index, all) => all.findIndex((other) => other.source.manifestSha256 === release.source.manifestSha256) === index);
+  catalog.forEach(assertCanonicalScaffoldUpgradeRelease);
+  const workspace = mkdtempSync(join(tmpdir(), "thally-upgrade-canary-"));
+  const snapshots = /* @__PURE__ */ new Map();
+  const download = async (destination, release) => {
+    if (!catalog.some((known) => known.id === release.id && known.source.manifestSha256 === release.source.manifestSha256)) throw new Error("Canary requested an uncatalogued release.");
+    if (release.source.manifestSha256 === target.source.manifestSha256) cpSync(options.candidateDirectory, destination, { recursive: true });
+    else if (options.download) await options.download(destination, release);
+    else {
+      let snapshot = snapshots.get(release.source.manifestSha256);
+      if (!snapshot) {
+        snapshot = join(workspace, "archives", release.source.manifestSha256);
+        mkdirSync(snapshot, { recursive: true });
+        await downloadStarter(snapshot, void 0, release, { announce: false });
+        readStarterReleaseManifest(snapshot, release);
+        files(snapshot);
+        snapshots.set(release.source.manifestSha256, snapshot);
+      }
+      cpSync(snapshot, destination, { recursive: true });
+    }
+    readStarterReleaseManifest(destination, release);
+    files(destination);
+  };
+  try {
+    for (const [index, base] of bases.entries()) {
+      const customer = join(workspace, String(index));
+      mkdirSync(customer);
+      await download(customer, base);
+      const oldManifest = readStarterReleaseManifest(customer, base);
+      const ownership = mergeStarterOwnershipContracts(oldManifest.ownership, targetManifest.ownership);
+      for (const [path, bytes] of [
+        ["src/content/__upgrade-canary.mdx", Buffer.from("---\ntitle: Upgrade canary\ndescription: Owner preservation\n---\nOwner content.\n")],
+        ["docs.json", Buffer.from('{"name":"Customer upgrade canary","navigation":[]}\n')]
+      ]) {
+        if (classifyStarterPath(path, ownership) !== "protected") throw new Error(`Canary owner path is not protected: ${path}`);
+        mkdirSync(dirname(join(customer, path)), { recursive: true });
+        writeFileSync(join(customer, path), bytes);
+      }
+      const packagePath = join(customer, "package.json");
+      const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+      packageJson.name = "customer-upgrade-canary";
+      writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}
+`);
+      const before = files(customer);
+      const plan = await updateStarterProject({ targetDir: customer, targetRelease: target, releases: catalog, download });
+      if (plan.plan.conflictPaths.length) throw new Error(`Historical upgrade conflicts: ${base.id}`);
+      await updateStarterProject({ targetDir: customer, targetRelease: target, releases: catalog, download, apply: true, confirmed: true });
+      const after = files(customer);
+      for (const [path, bytes] of before) if (path !== target.source.manifestPath && classifyStarterPath(path, ownership) === "protected" && !after.get(path)?.equals(bytes)) throw new Error(`Upgrade changed owner bytes: ${path}`);
+      for (const path of /* @__PURE__ */ new Set([...targetFiles.keys(), ...after.keys()])) if (classifyStarterPath(path, ownership) === "syncable" && (!targetFiles.has(path) || !after.has(path) || !targetFiles.get(path).equals(after.get(path)))) throw new Error(`Upgrade runtime differs from candidate: ${path}`);
+      if (JSON.parse(readFileSync(packagePath, "utf8")).name !== "customer-upgrade-canary") throw new Error("Upgrade lost independent package customization.");
+      for (const path of ["package.json", "package-lock.json"]) {
+        const actual = JSON.parse(readFileSync(join(customer, path), "utf8"));
+        const expected = JSON.parse(readFileSync(join(options.candidateDirectory, path), "utf8"));
+        delete actual.name;
+        delete expected.name;
+        if (actual.packages?.[""]) delete actual.packages[""].name;
+        if (expected.packages?.[""]) delete expected.packages[""].name;
+        if (!isDeepStrictEqual(actual, expected)) throw new Error(`Upgrade package inputs differ from candidate: ${path}`);
+      }
+      const hash = createHash("sha256").update(readFileSync(join(customer, target.source.manifestPath))).digest("hex");
+      if (hash !== target.source.manifestSha256) throw new Error("Upgrade did not advance exact target provenance.");
+    }
+    return bases.map((base) => base.id);
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+}
+export {
+  assertCanonicalScaffoldUpgradeRelease,
+  verifyScaffoldUpgrades
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-thally-docs",
-  "version": "0.10.88",
+  "version": "0.10.90",
   "description": "Scaffold an open-source Thally docs site for people, search engines, and AI tools.",
   "type": "module",
   "engines": {
@@ -33,6 +33,10 @@
     "./terminal": {
       "types": "./dist/terminal.d.ts",
       "import": "./dist/terminal.js"
+    },
+    "./starter-upgrade-canary": {
+      "types": "./dist/starter-upgrade-canary.d.ts",
+      "import": "./dist/starter-upgrade-canary.js"
     }
   },
   "files": [