@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/lineage-hash-index.ts

@@ -0,0 +1,305 @@
+/**
+ * The hash index that `chant workspace adopt-lineage` matches a scope against
+ * (#2551, D9, ws-006).
+ *
+ * For each tagged version of a template, the index lists every file the
+ * template has at that version with the SHA-256 of its content. It is computed
+ * on demand from the template's tags: no registry holds it, and a template
+ * needs no extra publishing to be adoptable. A template's CI may publish a copy
+ * (`chant workspace hash-index`) and an adopter may pass it with `--index`.
+ * That copy is a cache only. chant reuses an entry only while the tag still
+ * names the commit the entry records, and it recomputes the entry it adopts
+ * from the template itself before anything reaches the lock.
+ *
+ * ws-006 also names parameter masking: rendering each version with and without
+ * its parameters, so a file that differs only by a parameter value still
+ * matches. The index hashes the files as the tag holds them, with the
+ * template's `chant.template.json` left out, since a project never receives
+ * it (#2627). A file a parameter changed reads as edited when matched against
+ * a scope's files; adopt-lineage records it with its substituted hash once
+ * the version is chosen. Moving a directory lineage onto git renders every
+ * candidate with the recorded parameters instead (./lineage-adopt.ts).
+ *
+ * The network steps are `git ls-remote --tags` and one `git fetch` of the tags
+ * to compute, both catalogued in `test/egress-catalogue.ts`. A local
+ * repository reaches nothing.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { git } from "./lineage-init";
+import { LOCK_FILE, LockError } from "./lineage-lock";
+import { MIGRATIONS_DIR } from "./lineage-migrations";
+import { compareVersions, parseVersion } from "./lineage-version";
+import { TEMPLATE_MANIFEST } from "./template-manifest";
+
+/** The index format this chant reads and writes. */
+export const HASH_INDEX_VERSION = 1;
+
+const Sha256 = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const ObjectId = z.string().regex(/^[0-9a-f]{40,64}$/);
+
+const EntrySchema = z
+  .object({
+    tag: z.string().min(1),
+    commit: ObjectId,
+    /** The tree of the template's directory at the tag. */
+    tree: ObjectId,
+    /** Per file, relative to the template's directory: `sha256:<hex>` of its content. */
+    files: z.record(z.string(), Sha256),
+  })
+  .strict();
+export type HashIndexEntry = z.infer<typeof EntrySchema>;
+
+const IndexSchema = z
+  .object({
+    indexVersion: z.literal(HASH_INDEX_VERSION),
+    /** The template id, as the lock writes it: `github.com/acme/starter#service`. */
+    template: z.string().min(1),
+    /** Oldest version first. */
+    tags: z.array(EntrySchema),
+  })
+  .strict();
+export type HashIndex = z.infer<typeof IndexSchema>;
+
+/** Read and validate an index file, such as a copy a template's CI published. */
+export function readHashIndex(path: string): HashIndex {
+  if (!existsSync(path)) throw new LockError(`no hash index at ${path}`);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    throw new LockError(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const parsed = IndexSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new LockError(`invalid hash index ${path}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+  }
+  return parsed.data;
+}
+
+export function renderHashIndex(index: HashIndex): string {
+  return JSON.stringify(IndexSchema.parse(index), null, 2) + "\n";
+}
+
+/** Whether a template path is left out of the index: files a project never receives from the template. */
+export function indexExcludes(path: string): boolean {
+  return path === LOCK_FILE || path === TEMPLATE_MANIFEST || path.startsWith(`${MIGRATIONS_DIR}/`);
+}
+
+/** A tag glob (`*` and `?`) as a regular expression over the whole tag name. */
+function globRegExp(glob: string): RegExp {
+  const body = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${body}$`);
+}
+
+export interface RemoteTag {
+  tag: string;
+  /** The commit the tag names, peeled through an annotated tag. */
+  commit: string;
+}
+
+/**
+ * A scratch repository to read a template's tags in. Every method works on it;
+ * `dispose()` deletes it.
+ */
+export class TemplateTags {
+  readonly scratch: string;
+  private readonly blobHashes = new Map<string, string>();
+  private readonly fetched = new Set<string>();
+
+  constructor(
+    readonly url: string,
+    readonly member: string | undefined,
+    readonly label: string,
+  ) {
+    this.scratch = mkdtempSync(join(tmpdir(), "chant-hash-index-"));
+    git(this.scratch, ["init", "-q"]);
+  }
+
+  dispose(): void {
+    rmSync(this.scratch, { recursive: true, force: true });
+  }
+
+  /**
+   * The template's version tags, oldest first: every tag whose name reads as
+   * a version, narrowed by `pattern` when given (`chant-v*`).
+   */
+  listTags(pattern?: string): RemoteTag[] {
+    let out: string;
+    try {
+      // A network step of adopt-lineage and hash-index, catalogued in test/egress-catalogue.ts.
+      out = git(this.scratch, ["ls-remote", "--tags", this.url]);
+    } catch (err) {
+      const stderr = (err as { stderr?: string }).stderr?.toString().trim();
+      throw new LockError(`could not list the tags of ${this.label}${stderr ? `: ${stderr}` : ""}`);
+    }
+    const byTag = new Map<string, string>();
+    const peeled = new Set<string>();
+    for (const line of out.split("\n")) {
+      const [sha, ref] = line.split("\t");
+      if (!sha || !ref?.startsWith("refs/tags/")) continue;
+      const name = ref.slice("refs/tags/".length);
+      if (name.endsWith("^{}")) {
+        const tag = name.slice(0, -3);
+        byTag.set(tag, sha);
+        peeled.add(tag);
+      } else if (!peeled.has(name)) {
+        byTag.set(name, sha);
+      }
+    }
+    const match = pattern ? globRegExp(pattern) : null;
+    return [...byTag.entries()]
+      .filter(([tag]) => parseVersion(tag) !== null && (!match || match.test(tag)))
+      .map(([tag, commit]) => ({ tag, commit }))
+      .sort((a, b) => compareVersions(parseVersion(a.tag)!, parseVersion(b.tag)!) || a.tag.localeCompare(b.tag));
+  }
+
+  /** Fetch the given tags, one commit deep each, in as few `git fetch` calls as the argument limit allows. */
+  fetchTags(tags: string[]): void {
+    const todo = tags.filter((t) => !this.fetched.has(t));
+    for (let i = 0; i < todo.length; i += 100) {
+      const batch = todo.slice(i, i + 100);
+      try {
+        // A network step of adopt-lineage and hash-index, catalogued in test/egress-catalogue.ts.
+        git(this.scratch, ["fetch", "-q", "--depth", "1", "--no-tags", this.url, ...batch.map((t) => `+refs/tags/${t}:refs/tags/${t}`)]);
+      } catch (err) {
+        const stderr = (err as { stderr?: string }).stderr?.toString().trim();
+        throw new LockError(`could not fetch the tags of ${this.label}${stderr ? `: ${stderr}` : ""}`);
+      }
+      for (const t of batch) this.fetched.add(t);
+    }
+  }
+
+  /**
+   * Fetch one ref that is not a version tag, such as a branch or a commit, one
+   * commit deep, and return the commit it names.
+   */
+  fetchRef(ref: string): RemoteTag {
+    try {
+      // A network step of adopt-lineage, catalogued in test/egress-catalogue.ts.
+      git(this.scratch, ["fetch", "-q", "--depth", "1", "--no-tags", this.url, ref]);
+    } catch (err) {
+      const stderr = (err as { stderr?: string }).stderr?.toString().trim();
+      throw new LockError(`could not fetch ${this.label}@${ref}${stderr ? `: ${stderr}` : ""}`);
+    }
+    return { tag: ref, commit: git(this.scratch, ["rev-parse", "FETCH_HEAD^{commit}"]) };
+  }
+
+  /**
+   * The index entry of one fetched tag: its tree and the SHA-256 of every file
+   * under the template's directory. Null when the directory does not exist at
+   * that tag: a template kept in one directory of a larger repository is
+   * absent from the tags cut before it was added.
+   */
+  entry(tag: RemoteTag): HashIndexEntry | null {
+    let tree: string;
+    try {
+      tree = git(this.scratch, ["rev-parse", this.member ? `${tag.commit}:${this.member}` : `${tag.commit}^{tree}`]);
+      if (git(this.scratch, ["cat-file", "-t", tree]) !== "tree") throw new Error("not a tree");
+    } catch {
+      return null;
+    }
+    const listing = execFileSync("git", ["ls-tree", "-r", "-z", tree], { cwd: this.scratch, maxBuffer: 256 * 1024 * 1024 }).toString("utf-8");
+    const blobs: Array<{ path: string; sha: string }> = [];
+    for (const row of listing.split("\0")) {
+      if (!row) continue;
+      const tab = row.indexOf("\t");
+      const [mode, type, sha] = row.slice(0, tab).split(" ");
+      const path = row.slice(tab + 1);
+      // The same files `chant init --from` copies: no symbolic links, submodules, lock or migrations.
+      if (type !== "blob" || mode === "120000" || indexExcludes(path)) continue;
+      blobs.push({ path, sha });
+    }
+    this.hashBlobs(blobs.map((b) => b.sha));
+    const files: Record<string, string> = {};
+    for (const b of blobs.sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0))) files[b.path] = this.blobHashes.get(b.sha)!;
+    return { tag: tag.tag, commit: tag.commit, tree, files };
+  }
+
+  /** SHA-256 each blob not seen yet, read in one `git cat-file --batch`. Blobs shared between tags are hashed once. */
+  private hashBlobs(ids: string[]): void {
+    const todo = [...new Set(ids)].filter((id) => !this.blobHashes.has(id));
+    if (todo.length === 0) return;
+    const out = execFileSync("git", ["cat-file", "--batch"], { cwd: this.scratch, input: todo.join("\n") + "\n", maxBuffer: 1024 * 1024 * 1024 });
+    let at = 0;
+    for (const id of todo) {
+      const eol = out.indexOf(0x0a, at);
+      const header = out.subarray(at, eol).toString("utf-8").split(" ");
+      if (header[0] !== id || header[1] !== "blob") throw new LockError(`${this.label}: could not read blob ${id}`);
+      const size = Number(header[2]);
+      const data = out.subarray(eol + 1, eol + 1 + size);
+      this.blobHashes.set(id, `sha256:${createHash("sha256").update(data).digest("hex")}`);
+      at = eol + 1 + size + 1;
+    }
+  }
+}
+
+export interface ComputedIndex {
+  index: HashIndex;
+  /** Tags whose entry came from the cache, unverified until one is adopted. */
+  cached: Set<string>;
+}
+
+/**
+ * The index of a template, from its tags. With `cache`, an entry is reused when
+ * its tag still names the recorded commit; the others are fetched and
+ * computed. `only` restricts the index to one ref the user named: a version
+ * tag, or any other ref git can fetch, such as a branch or a commit.
+ */
+export function computeHashIndex(
+  tags: TemplateTags,
+  template: string,
+  options: { pattern?: string; cache?: HashIndex; only?: string } = {},
+): ComputedIndex {
+  let remote: RemoteTag[];
+  if (options.only !== undefined) {
+    // A named ref: a version tag when the template has one by that name, otherwise any ref git can fetch.
+    const only = options.only;
+    const tag = tags.listTags().find((t) => t.tag === only);
+    if (!tag) {
+      const ref = tags.fetchRef(only);
+      const entry = tags.entry(ref);
+      if (!entry) throw new LockError(`${tags.label}@${only} has no directory ${tags.member}`);
+      return { index: { indexVersion: HASH_INDEX_VERSION, template, tags: [entry] }, cached: new Set() };
+    }
+    remote = [tag];
+  } else {
+    remote = tags.listTags(options.pattern);
+  }
+  if (remote.length === 0) {
+    throw new LockError(
+      `${tags.label} has no tag that reads as a version${options.pattern ? ` and matches ${options.pattern}` : ""}; adopt-lineage matches against tagged releases`,
+    );
+  }
+  if (options.cache && options.cache.template !== template) {
+    throw new LockError(`the hash index is for ${options.cache.template}, not ${template}`);
+  }
+  const fromCache = new Map((options.cache?.tags ?? []).map((e) => [e.tag, e]));
+  const cached = new Set<string>();
+  const entries: HashIndexEntry[] = [];
+  const toCompute = remote.filter((t) => {
+    const hit = fromCache.get(t.tag);
+    return !hit || hit.commit !== t.commit;
+  });
+  tags.fetchTags(toCompute.map((t) => t.tag));
+  const computed = new Map(toCompute.map((t) => [t.tag, tags.entry(t)]));
+  for (const t of remote) {
+    if (computed.has(t.tag)) {
+      // A tag without the template's directory has no entry.
+      const own = computed.get(t.tag);
+      if (own) entries.push(own);
+    } else {
+      entries.push(fromCache.get(t.tag)!);
+      cached.add(t.tag);
+    }
+  }
+  if (entries.length === 0) {
+    throw new LockError(`${tags.label}: no version tag${options.only !== undefined ? ` ${options.only}` : ""} has the directory ${tags.member}`);
+  }
+  return { index: { indexVersion: HASH_INDEX_VERSION, template, tags: entries }, cached };
+}

package/src/workspace/lineage-init.test.ts

@@ -180,6 +180,15 @@ describe("chant init --from with parameters (#2627)", () => {
     expect(scope.files["chant.template.json"]).toBeUndefined();
     // The merge base is the file as written, with the value in it.
     expect(scope.files["src/main.ts"].sha256).toBe(fileHash(readFileSync(join(target, "src/main.ts"))));
+    // The host-bound parameter, with the listed files that carry it, for export and import (#2552).
+    expect(scope.hostBound).toEqual({ url: ["src/main.ts"] });
+  });
+
+  test("a template with no host-bound parameter records no hostBound (#2552)", async () => {
+    declare({ parameters: { name: MANIFEST.parameters.name }, files: ["package.json"] }, { "src/main.ts": "plain\n" });
+    const target = join(root, "proj");
+    expect((await initFromCommand({ from: `${tpl}@main#svc`, path: target })).error).toBeUndefined();
+    expect(readLock(target)!.scopes["."]).not.toHaveProperty("hostBound");
   });
 
   test("an undeclared --param is refused with the declared names listed, and nothing is written", async () => {

package/src/workspace/lineage-init.ts

@@ -35,7 +35,7 @@ import {
   type Lineage,
 } from "./lineage-lock";
 import { MIGRATIONS_DIR } from "./lineage-migrations";
-import { TEMPLATE_MANIFEST, readManifest, resolveParameters, substituteParameters } from "./template-manifest";
+import { TEMPLATE_MANIFEST, hostBoundFiles, readManifest, resolveParameters, substituteParameters } from "./template-manifest";
 import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 
 // ── The template spec ────────────────────────────────────────────────────────
@@ -71,14 +71,31 @@ function splitMember(spec: string, where: string): { rest: string; member?: stri
  * `git@host:path`, a local path, or `owner/name` for a GitHub repository.
  */
 export function parseTemplateSpec(spec: string, cwd: string = process.cwd()): TemplateSpec {
-  const { rest, member } = splitMember(spec, "the repository");
+  const parsed = parseTemplateSource(spec, cwd, "--from");
+  if (parsed.ref === undefined) {
+    throw new LockError(`--from ${spec}: expected <repo>@<ref>[#<member>], e.g. acme/starter@v1.2.0, or an existing directory`);
+  }
+  return { ...parsed, ref: parsed.ref };
+}
+
+/**
+ * Parse `<repo>[@<ref>][#<member>]`, where the ref may be left out: the form
+ * `chant workspace adopt-lineage --from`, `hash-index --from` and
+ * `upgrade --source` take (#2551). `flag` names the option in messages.
+ */
+export function parseTemplateSource(spec: string, cwd: string = process.cwd(), flag = "--from"): Omit<TemplateSpec, "ref"> & { ref?: string } {
+  const { rest: whole, member } = splitMember(spec, "the repository");
+  let rest = whole;
+  let ref: string | undefined;
   const at = rest.lastIndexOf("@");
   const lastSep = Math.max(rest.lastIndexOf("/"), rest.lastIndexOf(":"));
-  if (at <= 0 || at < lastSep || at === rest.length - 1) {
-    throw new LockError(`--from ${spec}: expected <repo>@<ref>[#<member>], e.g. acme/starter@v1.2.0, or an existing directory`);
+  if (at > 0 && at > lastSep) {
+    if (at === rest.length - 1) throw new LockError(`${flag} ${spec}: the ref after "@" is empty; expected <repo>@<ref>[#<member>]`);
+    ref = rest.slice(at + 1);
+    rest = rest.slice(0, at);
   }
-  const repo = rest.slice(0, at);
-  const ref = rest.slice(at + 1);
+  const repo = rest;
+  if (!repo) throw new LockError(`${flag} ${spec}: no repository`);
 
   let url: string;
   let repoId: string;
@@ -99,9 +116,9 @@ export function parseTemplateSpec(spec: string, cwd: string = process.cwd()): Te
     url = `https://${repo}${repo.endsWith(".git") ? "" : ".git"}`;
     repoId = repo.replace(/\.git$/, "");
   } else {
-    throw new LockError(`--from ${spec}: "${repo}" is not a URL, a local repository or owner/name`);
+    throw new LockError(`${flag} ${spec}: "${repo}" is not a URL, a local repository or owner/name`);
   }
-  return { repo, url, ref, member, id: member ? `${repoId}#${member}` : repoId };
+  return { repo, url, ...(ref !== undefined ? { ref } : {}), member, id: member ? `${repoId}#${member}` : repoId };
 }
 
 // ── Fetch ────────────────────────────────────────────────────────────────────
@@ -415,10 +432,12 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
   let parameters: Record<string, string>;
   let contents: Map<string, Buffer>;
   let repinned: RepinnedRecord[];
+  let hostBound: Record<string, string[]> | undefined;
   try {
     const raw = new Map([...fetched.files].map(([path, f]) => [path, f.data]));
     const manifest = readManifest(raw);
     parameters = resolveParameters(manifest, options.params ?? {});
+    hostBound = hostBoundFiles(raw, manifest);
     // Records that pin a substituted file get its new hash, so a copy's pins hold (#2549).
     ({ files: contents, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []));
   } catch (err) {
@@ -445,6 +464,7 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
 
   const common = {
     parameters,
+    ...(hostBound ? { hostBound } : {}),
     ...(repinned.length > 0 ? { repinned: repinned.filter((r) => written.has(r.record)) } : {}),
     migrations: [],
     files: fileEntries(written, declaredFilesAt(targetDir)),
@@ -487,7 +507,7 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
 }
 
 /** A local repository is recorded relative to the project, so the lock does not name this machine's paths. */
-function portableUrl(url: string, targetDir: string): string {
+export function portableUrl(url: string, targetDir: string): string {
   if (!isAbsolute(url)) return url;
   const rel = relative(targetDir, url).split(sep).join("/");
   return rel.startsWith(".") ? rel : `./${rel}`;

package/src/workspace/lineage-lock.ts

@@ -120,6 +120,49 @@ const ManualStepSchema = z
   .strict();
 export type ManualStep = z.infer<typeof ManualStepSchema>;
 
+const CommitId = z.string().regex(/^[0-9a-f]{40,64}$/);
+
+/**
+ * How a scope got its lineage from `chant workspace adopt-lineage` (#2551, D5,
+ * D9, requirement P7), rather than from `chant init`.
+ *
+ * - `by: "files"`: the scope had no lineage. Its files were matched against
+ *   the template's versions, and the history before the lock is vouched for
+ *   by an exact commit range, `commits.to` and every commit before it. The
+ *   range is the one `.chant/trust.json` lists under `adopted`; once that
+ *   entry is at the base revision, an admin has admitted it, and the scope
+ *   reads as provenance `adopted` (D5). Until then it reads as `unattested`.
+ * - `by: "lineage"`: the scope had a directory lineage (#2647), and it was
+ *   moved onto a git source whose files at the chosen ref reproduce every hash
+ *   the lock recorded. The merge base is unchanged, so no history needs
+ *   vouching for, and `previous` keeps the source it replaced.
+ */
+const AdoptionSchema = z
+  .object({
+    by: z.enum(["files", "lineage"]),
+    /** HEAD when the scope was adopted: the range `.chant/trust.json` admits ends here. */
+    commits: z.object({ to: CommitId }).strict(),
+    /** How the chosen version held up against the scope. */
+    match: z
+      .object({
+        /** Files the template has at that version. */
+        files: z.number().int().nonnegative(),
+        /** Of those, the ones the scope holds (or the lock recorded) byte for byte. */
+        identical: z.number().int().nonnegative(),
+        /** The ones it holds with other content: edited since. */
+        edited: z.number().int().nonnegative(),
+        /** The ones it does not hold. */
+        missing: z.number().int().nonnegative(),
+      })
+      .strict(),
+    /** Where the hash index came from: computed from the template, or a cached copy chant re-checked at the chosen version. */
+    index: z.enum(["computed", "cache"]),
+    /** For `by: "lineage"`: the template and source the lineage had before. */
+    previous: z.object({ template: z.string().min(1), source: SourceSchema }).strict().optional(),
+  })
+  .strict();
+export type Adoption = z.infer<typeof AdoptionSchema>;
+
 const LineageSchema = z
   .object({
     kind: z.enum(["template", "vendor"]),
@@ -133,6 +176,13 @@ const LineageSchema = z
     address: AddressSchema.nullable(),
     /** The parameter values the template was instantiated with. Always empty for vendor scopes. */
     parameters: z.record(z.string(), z.unknown()),
+    /**
+     * The parameters the template marks `hostBound` (#2524 D9, #2552), each
+     * with the files, relative to the scope, whose template text carries its
+     * placeholder. `chant workspace export` switches their values for the
+     * export, and `import` switches them back. Absent when the template has none.
+     */
+    hostBound: z.record(z.string(), z.array(z.string().min(1))).optional(),
     /**
      * Records whose evidence pins were re-pinned to the substituted content
      * of a parameterised file (#2549): each record's path in the scope, and the
@@ -144,6 +194,8 @@ const LineageSchema = z
     /** Per file, relative to the scope directory, in sorted order. */
     files: z.record(z.string(), LockFileEntrySchema),
     manualSteps: z.array(ManualStepSchema),
+    /** Present when the lineage was adopted rather than written at init (#2551). */
+    adoption: AdoptionSchema.optional(),
   })
   .strict();
 export type Lineage = z.infer<typeof LineageSchema>;
@@ -255,10 +307,12 @@ function canonical(lock: LineageLock): LineageLock {
       ...(s.ref !== undefined ? { ref: s.ref } : {}),
       address: s.address,
       parameters: s.parameters,
+      ...(s.hostBound !== undefined ? { hostBound: Object.fromEntries(Object.keys(s.hostBound).sort().map((k) => [k, [...s.hostBound![k]].sort()])) } : {}),
       ...(s.repinned !== undefined ? { repinned: s.repinned } : {}),
       migrations: s.migrations,
       files,
       manualSteps: [...s.manualSteps].sort((a, b) => a.path.localeCompare(b.path)),
+      ...(s.adoption !== undefined ? { adoption: s.adoption } : {}),
     };
   }
   return { lockVersion: lock.lockVersion, scopes };

package/src/workspace/lineage-migrations.test.ts

@@ -85,6 +85,33 @@ describe("planMigrations", () => {
     // With nothing to run, no version is needed.
     expect(planMigrations(lineage("main"), "main", []).chain).toEqual([]);
   });
+
+  // #2551 — moving a scope to another template starts the chain with a bridge.
+  test("a switch starts with the bridge from the scope's template, then the new template's own migrations", () => {
+    const upstream = "github.com/acme/upstream";
+    const plan = planMigrations(lineage("v1.4.0"), "v3.0.0", [
+      migration("bridge-old", "<1.0.0", "1.0.0", "github.com/acme/starter"),
+      migration("bridge", ">=1.0.0 <2.0.0", "2.0.0", "github.com/acme/starter"),
+      migration("own-2", ">=1.0.0 <2.0.0", "2.0.0"),
+      migration("own-3", "2.x", "3.0.0"),
+      migration("other-bridge", "1.x", "2.0.0", "github.com/someone/else"),
+    ], upstream);
+    // own-2 lands where the bridge already did, so it does not run; the fork's version 1.4.0 means nothing to upstream.
+    expect(plan.chain.map((m) => m.migration.id)).toEqual(["bridge", "own-3"]);
+    // No downgrade check across templates: the fork's v5 can bridge to upstream's v3.
+    expect(planMigrations(lineage("v5.0.0"), "v3.0.0", [migration("b", ">=5.0.0", "3.0.0", "github.com/acme/starter")], upstream).chain.map((m) => m.migration.id)).toEqual(["b"]);
+  });
+
+  test("a switch without a bridge is refused when the new template has migrations, and allowed when it has none", () => {
+    const upstream = "github.com/acme/upstream";
+    expect(() => planMigrations(lineage("v1.0.0"), "v2.0.0", [migration("own", "1.x", "2.0.0")], upstream)).toThrow(/needs a bridge migration/);
+    expect(() => planMigrations(lineage("v1.0.0"), "v2.0.0", [migration("b", ">=3.0.0", "2.0.0", "github.com/acme/starter"), migration("own", "1.x", "2.0.0")], upstream)).toThrow(
+      /needs a bridge migration.*found b: >=3\.0\.0/,
+    );
+    expect(planMigrations(lineage("v1.0.0"), "v2.0.0", [], upstream).chain).toEqual([]);
+    // The same id is no switch.
+    expect(planMigrations(lineage("v1.0.0"), "v2.0.0", [migration("a", "1.x", "2.0.0")], "github.com/acme/starter").chain.map((m) => m.migration.id)).toEqual(["a"]);
+  });
 });
 
 describe("migration files", () => {

package/src/workspace/lineage-migrations.ts

@@ -161,39 +161,69 @@ export interface MigrationPlan {
 /**
  * The migrations that take `lineage` from its version to `targetRef`, in order.
  *
+ * With `switchTo`, the upgrade also moves the scope to another template, the
+ * one with that id (#2551). The chain then starts with a bridge migration: one
+ * the new template ships whose `from.template` names the scope's current
+ * template and whose `from.versions` accepts the scope's version. Its `to` is a
+ * version of the new template, and the new template's own migrations carry on
+ * from there. This is how a fork-born scope, adopted against the fork, comes
+ * forward onto the template the fork came from.
+ *
  * Refused, with a {@link MigrationError}:
- * - a target below the scope's version;
+ * - a target below the scope's version (without a switch: versions of two
+ *   templates do not compare);
  * - a pending migration when either end of the upgrade is not a version, so
  *   no chain can be computed;
  * - a gap: a migration in range whose `from` does not accept the version the
- *   scope has reached by then.
+ *   scope has reached by then;
+ * - a switch with no bridge from the scope's version, when the new template
+ *   has migrations of its own, since the scope's place in its history is
+ *   then unknown.
  */
-export function planMigrations(lineage: Lineage, targetRef: string | undefined, available: LoadedMigration[]): MigrationPlan {
+export function planMigrations(lineage: Lineage, targetRef: string | undefined, available: LoadedMigration[], switchTo?: string): MigrationPlan {
   const from = parseVersion(lineage.ref);
   const to = parseVersion(targetRef);
-  if (from && to && compareVersions(to, from) < 0) {
+  const applied = new Set(lineage.migrations);
+  const switching = switchTo !== undefined && switchTo !== lineage.template;
+  if (!switching && from && to && compareVersions(to, from) < 0) {
     throw new MigrationError(`the target ${targetRef} (${formatVersion(to)}) is older than the scope's ${lineage.ref} (${formatVersion(from)}); an upgrade only goes forward`);
   }
-  const applied = new Set(lineage.migrations);
-  const mine = available.filter(
-    ({ migration: m }) => (m.from.template === undefined || m.from.template === lineage.template) && !applied.has(m.id),
-  );
-  if (mine.length === 0) return { chain: [], from, to };
+  const target = switching ? switchTo : lineage.template;
+  const own = available.filter(({ migration: m }) => (m.from.template === undefined || m.from.template === target) && !applied.has(m.id));
+  const bridges = switching ? available.filter(({ migration: m }) => m.from.template === lineage.template && !applied.has(m.id)) : [];
+  if (own.length === 0 && bridges.length === 0) return { chain: [], from, to };
 
   if (!from || !to) {
+    const pending = [...bridges, ...own];
     const which = !from ? `the scope's ref ${lineage.ref ?? "(none)"}` : `the target ${targetRef ?? "(none)"}`;
     throw new MigrationError(
-      `the template has ${mine.length} migration(s) not yet applied (${mine.map((m) => m.migration.id).join(", ")}), but ${which} is not a version, so no chain can be planned. Pin tagged versions, such as v1.2.0.`,
+      `the template has ${pending.length} migration(s) not yet applied (${pending.map((m) => m.migration.id).join(", ")}), but ${which} is not a version, so no chain can be planned. Pin tagged versions, such as v1.2.0.`,
     );
   }
 
-  const inRange = mine
+  let at = from;
+  const chain: LoadedMigration[] = [];
+  if (switching) {
+    // The bridge: the one that accepts the scope's version and lands furthest without passing the target.
+    const fits = bridges
+      .map((m) => ({ ...m, target: parseVersion(m.migration.to)! }))
+      .filter((m) => satisfies(from, m.migration.from.versions) && compareVersions(m.target, to) <= 0)
+      .sort((a, b) => compareVersions(b.target, a.target) || a.migration.id.localeCompare(b.migration.id));
+    if (fits.length === 0) {
+      if (own.length === 0) return { chain: [], from, to };
+      throw new MigrationError(
+        `moving scope from ${lineage.template} to ${switchTo} needs a bridge migration: one in ${switchTo} with from.template "${lineage.template}" whose from.versions accepts ${formatVersion(from)}${bridges.length > 0 ? ` (found ${bridges.map((m) => `${m.migration.id}: ${m.migration.from.versions}`).join(", ")})` : ""}. Without it the scope's place in ${switchTo}'s history is unknown, so the upgrade is refused.`,
+      );
+    }
+    chain.push({ migration: fits[0].migration, file: fits[0].file });
+    at = fits[0].target;
+  }
+
+  const inRange = own
     .map((m) => ({ ...m, target: parseVersion(m.migration.to)! }))
-    .filter((m) => compareVersions(m.target, from) > 0 && compareVersions(m.target, to) <= 0)
+    .filter((m) => compareVersions(m.target, at) > 0 && compareVersions(m.target, to) <= 0)
     .sort((a, b) => compareVersions(a.target, b.target) || a.migration.id.localeCompare(b.migration.id));
 
-  const chain: LoadedMigration[] = [];
-  let at = from;
   let i = 0;
   while (i < inRange.length) {
     const step = inRange[i].target;

package/src/workspace/lineage-provenance.ts

@@ -0,0 +1,40 @@
+/**
+ * The provenance of an adopted lineage (#2551, D5, requirement P7).
+ *
+ * `chant workspace adopt-lineage` records the commit it adopted at, and adds
+ * the range ending there to `.chant/trust.json`. That file is policy, always
+ * read at the base revision (./trust/policy.ts), so an adoption counts only
+ * once its range is in the policy at base, which takes a protected write by
+ * an admin. Until then the scope reads as `unattested`, like any lineage
+ * chant wrote itself.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { Lineage } from "./lineage-lock";
+import { isAdopted, policyAtBase, resolveBase } from "./trust/provenance";
+
+export interface LineageProvenance {
+  level: "adopted" | "unattested";
+  reason: string;
+}
+
+/** Null for a lineage that makes no adoption claim: one chant wrote at init, vendor or upgrade, or a directory lineage moved onto git. */
+export function lineageProvenance(root: string, lineage: Lineage): LineageProvenance | null {
+  const adoption = lineage.adoption;
+  if (!adoption || adoption.by !== "files") return null;
+  const to = adoption.commits.to;
+  let repo: string;
+  try {
+    repo = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    return { level: "unattested", reason: "not in a git repository, so the adopted range cannot be checked" };
+  }
+  const base = resolveBase(repo);
+  if (!base.commit) return { level: "unattested", reason: base.problem ?? "no base revision" };
+  const policy = policyAtBase(repo, base);
+  if (isAdopted(repo, policy, to)) return { level: "adopted", reason: `the policy at ${base.commit.slice(0, 12)} adopts the range up to ${to.slice(0, 12)}` };
+  return {
+    level: "unattested",
+    reason: `the range up to ${to.slice(0, 12)} is not in .chant/trust.json at ${base.commit.slice(0, 12)} (${base.from}); it counts once that change is merged`,
+  };
+}