@cldmv/git-embedded 1.0.0 → 1.1.2

package/src/api/embedded/branch.mjs

@@ -0,0 +1,62 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+function git(args, opts = {}) {
+	const res = context.spawnSync("git", args, { encoding: "utf8", ...opts });
+	return { code: res.status ?? 1, stdout: (res.stdout || "").trim(), stderr: (res.stderr || "").trim() };
+}
+
+/**
+ * Branch helpers for embedded children — inference of the branch a pin lives
+ * on, and attaching a child to a branch at a pin. Used by `restore` (initial
+ * branch-aware checkout) and `sync` (day-2 fast-forward of the registered
+ * branch).
+ *
+ * @namespace api.embedded.branch
+ */
+
+/**
+ * Infer the branch a pinned commit lives on: exactly ONE `origin` remote
+ * branch must contain the pin, otherwise inference declines (returns null) and
+ * the caller keeps detached-HEAD behavior.
+ *
+ * Full refnames (`%(refname)`) are load-bearing: `origin/HEAD` short-forms to
+ * bare `origin`, which would enter the candidate set as a phantom "branch" and
+ * poison the uniqueness check. Matching `refs/remotes/origin/<name>` and
+ * excluding `HEAD` explicitly keeps the symref out.
+ *
+ * @param {string} childDir absolute path of the child working tree
+ * @param {string} sha the pinned commit
+ * @returns {string|null} the single containing branch name, or null when the
+ *   pin is on no remote branch or more than one (ambiguous)
+ */
+export function infer(childDir, sha) {
+	const res = git(["-C", childDir, "branch", "-r", "--contains", sha, "--format=%(refname)"]);
+	if (res.code !== 0) return null;
+	const names = res.stdout
+		.split(/\r?\n/)
+		.map((line) => (line.match(/^refs\/remotes\/origin\/(?!HEAD$)(.+)$/) || [])[1])
+		.filter(Boolean);
+	const unique = new Set(names);
+	return unique.size === 1 ? names[0] : null;
+}
+
+/**
+ * Put a child ON `branch` at `sha`: `checkout -B` (create or reset the local
+ * branch at the pin) plus a soft `--set-upstream-to=origin/<branch>` — soft
+ * because a registered branch need not exist on the remote (a local working
+ * branch is legitimate), and tracking is a convenience, not a correctness
+ * requirement.
+ *
+ * @param {string} childDir absolute path of the child working tree
+ * @param {string} branch branch name to attach
+ * @param {string} sha the pinned commit the branch should point at
+ * @returns {boolean} true when the checkout succeeded (upstream is best-effort)
+ */
+export function attach(childDir, branch, sha) {
+	const checkout = git(["-C", childDir, "checkout", "--quiet", "-B", branch, sha]);
+	if (checkout.code !== 0) return false;
+	git(["-C", childDir, "branch", `--set-upstream-to=origin/${branch}`, "--", branch]);
+	return true;
+}
+
+export default { infer, attach };

package/src/api/embedded/gitlinks.mjs

@@ -0,0 +1,45 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+function git(args, opts = {}) {
+	const res = context.spawnSync("git", args, { encoding: "utf8", ...opts });
+	return { code: res.status ?? 1, stdout: (res.stdout || "").trim(), stderr: (res.stderr || "").trim() };
+}
+
+/**
+ * Enumerate the anonymous gitlinks recorded in the parent's HEAD tree.
+ *
+ * Reads `git ls-tree -r HEAD` and keeps only mode-`160000` / type-`commit`
+ * entries — the same detection the `update-embedded-repos` and
+ * `reference-transaction` hooks use. No `.gitmodules` is consulted; the pinned
+ * SHA in the parent tree is the only committed information about a child.
+ *
+ * @param {string} [cwd] working directory inside the parent repo (default: cwd)
+ * @returns {Array<{ path: string, sha: string }>} gitlink path + pinned SHA,
+ *   in tree order. Empty when HEAD has no gitlinks or `cwd` is not a repo.
+ *
+ * @example
+ * const links = self.embedded.gitlinks();
+ * // → [{ path: "tests", sha: "a1b2c3…" }, { path: "vendor/foo", sha: "d4e5…" }]
+ */
+export default function gitlinks(cwd = process.cwd()) {
+	const res = git(["ls-tree", "-r", "HEAD"], { cwd });
+	if (res.code !== 0) return [];
+	const out = [];
+	for (const line of res.stdout.split(/\r?\n/)) {
+		if (!line) continue;
+		// <mode> SP <type> SP <sha> TAB <path>
+		const tab = line.indexOf("\t");
+		/* v8 ignore next -- defensive: `git ls-tree -r HEAD` always emits
+		   `<mode> SP <type> SP <sha> TAB <path>`, so a non-empty line with no tab is
+		   unreachable (the empty-line case is already handled above). */
+		if (tab < 0) continue;
+		const meta = line.slice(0, tab).split(/\s+/);
+		/* v8 ignore next -- defensive: the pre-tab field is always exactly
+		   `<mode> <type> <sha>` (3 tokens) for `-r HEAD`, so fewer than 3 is unreachable. */
+		if (meta.length < 3) continue;
+		const [mode, type, sha] = meta;
+		if (mode !== "160000" || type !== "commit") continue;
+		out.push({ path: line.slice(tab + 1), sha });
+	}
+	return out;
+}

package/src/api/embedded/manifest.mjs

@@ -0,0 +1,71 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+/**
+ * The manifest is a TRANSFER FORMAT only — a JSON document that carries child
+ * URLs between machines by hand. It is never committed to any repo (that would
+ * defeat the whole point of anonymous gitlinks); it lives outside the tree, in
+ * the user's own hands. Shape:
+ *
+ *   { "version": 1, "children": { "<path>": { "url": "…", "branch": "…" } } }
+ *
+ * @namespace api.embedded.manifest
+ */
+
+/**
+ * Read and parse a manifest file.
+ * @param {string} file manifest path (absolute, or relative to `cwd`)
+ * @param {string} [cwd] base directory for a relative `file`
+ * @returns {{ version: number, children: object }|null} parsed manifest, or
+ *   null when the file does not exist
+ * @throws {Error} when the file exists but is not valid manifest JSON
+ */
+export function read(file, cwd = process.cwd()) {
+	const { fs, path } = context;
+	const abs = path.isAbsolute(file) ? file : path.resolve(cwd, file);
+	if (!fs.existsSync(abs)) return null;
+	let obj;
+	try {
+		obj = JSON.parse(fs.readFileSync(abs, "utf8"));
+	} catch (err) {
+		throw new Error(`manifest ${abs} is not valid JSON: ${err.message}`);
+	}
+	if (!obj || typeof obj !== "object" || typeof obj.children !== "object" || obj.children === null || Array.isArray(obj.children)) {
+		throw new Error(`manifest ${abs} is missing a "children" object (a path → { url, branch } map, not an array)`);
+	}
+	// Gate the format version so an incompatible manifest fails loudly at read
+	// time instead of producing hard-to-diagnose behavior downstream.
+	if (obj.version !== 1) {
+		throw new Error(`manifest ${abs} has unsupported version ${JSON.stringify(obj.version)} (expected 1)`);
+	}
+	return obj;
+}
+
+/**
+ * Build a manifest object from registry entries.
+ * @param {Array<{ path: string, url?: string, branch?: string }>} entries
+ * @returns {{ version: number, children: object }} manifest object; entries
+ *   without a URL are dropped (a manifest without a URL is useless)
+ */
+export function build(entries) {
+	// Null-prototype map: a child path named __proto__ must become a plain own
+	// key, never a prototype mutation.
+	const children = Object.create(null);
+	for (const e of entries || []) {
+		if (!e || !e.url) continue;
+		children[e.path] = { url: e.url };
+		if (e.branch) children[e.path].branch = e.branch;
+	}
+	return { version: 1, children };
+}
+
+/**
+ * Serialize a manifest object to its on-disk JSON text (tab-indented, trailing
+ * newline).
+ * @param {object} manifestObj manifest object from {@link build}
+ * @returns {string}
+ */
+export function serialize(manifestObj) {
+	return JSON.stringify(manifestObj, null, "\t") + "\n";
+}
+
+export default { read, build, serialize };

package/src/api/embedded/record.mjs

@@ -0,0 +1,46 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+/**
+ * Record engine: for each embedded child present on disk, write its
+ * `remote.origin.url` and current branch into the parent's LOCAL config
+ * registry. This is how a machine that already has the children populates the
+ * registry so it can later `export` a manifest or re-`restore` without
+ * re-deriving URLs.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] working directory inside the parent repo
+ * @param {string[]} [opts.paths] restrict to these gitlink paths (default: all
+ *   gitlink children present on disk)
+ * @returns {{ results: Array<{ path: string, url?: string, branch?: string|null,
+ *   outcome: "recorded"|"no-repo"|"no-origin" }> }}
+ */
+export default function record(opts = {}) {
+	const { cwd = process.cwd() } = opts;
+	const { paths = [] } = opts;
+
+	const root = self.git.getRepoRoot(cwd) || cwd;
+	// Same filter-spelling normalization as restore/sync: gitlink paths from
+	// gitlinks() are root-relative with forward slashes, so accept "./tests",
+	// "tests/", and Windows "vendor\\foo" instead of silently not matching.
+	const normalizePath = (p) =>
+		String(p)
+			.replace(/\\/g, "/")
+			.replace(/^\.\/+/, "")
+			.replace(/\/+$/, "");
+	const wantSet = paths.length ? new Set(paths.map(normalizePath)) : null;
+
+	const links = self.embedded.gitlinks(root);
+	const results = [];
+	for (const { path: childPath } of links) {
+		if (wantSet && !wantSet.has(childPath)) continue;
+		const abs = context.path.resolve(root, childPath);
+		if (!context.fs.existsSync(context.path.join(abs, ".git"))) {
+			// Only children present on disk can be recorded; skip the rest silently
+			// unless explicitly requested.
+			if (wantSet) results.push({ path: childPath, outcome: "no-repo" });
+			continue;
+		}
+		results.push(self.embedded.registry.recordOne(childPath, root));
+	}
+	return { results };
+}

package/src/api/embedded/registry.mjs

@@ -0,0 +1,119 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+function git(args, opts = {}) {
+	const res = context.spawnSync("git", args, { encoding: "utf8", ...opts });
+	return { code: res.status ?? 1, stdout: (res.stdout || "").trim(), stderr: (res.stderr || "").trim() };
+}
+
+/**
+ * The per-clone URL registry: `embedded.<path>.url` / `embedded.<path>.branch`
+ * keys in the PARENT repo's LOCAL `.git/config`. This is registry layer 1 (the
+ * strictest resolution source) and it is NEVER committed — it lives only in the
+ * clone that wrote it. The gitlink path is stored as the config subsection, so
+ * paths with slashes (e.g. `vendor/foo`) round-trip correctly.
+ *
+ * @namespace api.embedded.registry
+ */
+
+/**
+ * Read a child's recorded clone URL from the parent's local config.
+ * @param {string} childPath gitlink path (the config subsection)
+ * @param {string} [cwd] working directory inside the parent repo
+ * @returns {string|null} the URL, or null when unset
+ */
+export function getUrl(childPath, cwd = process.cwd()) {
+	const res = git(["config", "--local", "--get", `embedded.${childPath}.url`], { cwd });
+	return res.code === 0 && res.stdout ? res.stdout : null;
+}
+
+/**
+ * Read a child's recorded branch from the parent's local config.
+ * @param {string} childPath gitlink path
+ * @param {string} [cwd] working directory inside the parent repo
+ * @returns {string|null} the branch, or null when unset
+ */
+export function getBranch(childPath, cwd = process.cwd()) {
+	const res = git(["config", "--local", "--get", `embedded.${childPath}.branch`], { cwd });
+	return res.code === 0 && res.stdout ? res.stdout : null;
+}
+
+/**
+ * Write a child's clone URL into the parent's local config.
+ * @param {string} childPath gitlink path
+ * @param {string} url clone URL to record
+ * @param {string} [cwd] working directory inside the parent repo
+ * @returns {boolean} true on success
+ */
+export function setUrl(childPath, url, cwd = process.cwd()) {
+	// `--` so a value starting with "-" is never parsed as a git option.
+	return git(["config", "--local", "--", `embedded.${childPath}.url`, url], { cwd }).code === 0;
+}
+
+/**
+ * Write a child's branch into the parent's local config.
+ * @param {string} childPath gitlink path
+ * @param {string} branch branch name to record
+ * @param {string} [cwd] working directory inside the parent repo
+ * @returns {boolean} true on success
+ */
+export function setBranch(childPath, branch, cwd = process.cwd()) {
+	return git(["config", "--local", "--", `embedded.${childPath}.branch`, branch], { cwd }).code === 0;
+}
+
+/**
+ * List every registry entry currently in the parent's local config.
+ * @param {string} [cwd] working directory inside the parent repo
+ * @returns {Array<{ path: string, url?: string, branch?: string }>} one entry
+ *   per recorded child path
+ */
+export function entries(cwd = process.cwd()) {
+	const res = git(["config", "--local", "--get-regexp", "^embedded\\..*\\.(url|branch)$"], { cwd });
+	if (res.code !== 0) return [];
+	const map = new Map();
+	for (const line of res.stdout.split(/\r?\n/)) {
+		if (!line) continue;
+		const sp = line.indexOf(" ");
+		if (sp < 0) continue;
+		const fullKey = line.slice(0, sp);
+		const value = line.slice(sp + 1);
+		// fullKey is `embedded.<subsection>.<name>`; git preserves the subsection
+		// (the path, possibly containing dots) verbatim, so split off the trailing
+		// `.url`/`.branch` name and the leading `embedded.` section.
+		const rest = fullKey.slice("embedded.".length);
+		const lastDot = rest.lastIndexOf(".");
+		if (lastDot < 0) continue;
+		const sub = rest.slice(0, lastDot);
+		const name = rest.slice(lastDot + 1);
+		if (!map.has(sub)) map.set(sub, { path: sub });
+		map.get(sub)[name] = value;
+	}
+	return Array.from(map.values());
+}
+
+/**
+ * Record one present child: read its `remote.origin.url` and current branch and
+ * write them to the parent registry. Used by `record`, `export --scan`, and the
+ * `link` command after a fresh clone.
+ * @param {string} childPath gitlink path
+ * @param {string} root parent repo root (child lives at `<root>/<childPath>`)
+ * @returns {{ path: string, url?: string, branch?: string|null, outcome: "recorded"|"no-repo"|"no-origin" }}
+ */
+export function recordOne(childPath, root) {
+	const { fs, path } = context;
+	const abs = path.resolve(root, childPath);
+	const gitMarker = path.join(abs, ".git");
+	if (!fs.existsSync(gitMarker)) return { path: childPath, outcome: "no-repo" };
+
+	const urlRes = git(["-C", abs, "config", "--get", "remote.origin.url"]);
+	const url = urlRes.code === 0 && urlRes.stdout ? urlRes.stdout : null;
+	if (!url) return { path: childPath, outcome: "no-origin" };
+	setUrl(childPath, url, root);
+
+	const brRes = git(["-C", abs, "symbolic-ref", "--short", "HEAD"]);
+	const branch = brRes.code === 0 && brRes.stdout ? brRes.stdout : null;
+	if (branch) setBranch(childPath, branch, root);
+
+	return { path: childPath, url, branch, outcome: "recorded" };
+}
+
+export default { getUrl, getBranch, setUrl, setBranch, entries, recordOne };

package/src/api/embedded/resolve.mjs

@@ -0,0 +1,87 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+/**
+ * Last path segment of a gitlink path (its "basename"), slash-normalized so
+ * `vendor/foo` → `foo` and a trailing slash is ignored.
+ * @param {string} childPath
+ * @returns {string}
+ */
+function basename(childPath) {
+	const parts = String(childPath).split("/").filter(Boolean);
+	return parts.length ? parts[parts.length - 1] : String(childPath);
+}
+
+/**
+ * Convention URL: the child is a sibling of wherever the parent was cloned
+ * from. Takes the parent's origin URL, drops its final path segment (the
+ * parent's own repo name), and appends `<basename>.git`.
+ *
+ * Handles both scp-style (`git@host:org/parent.git`) and URL-style
+ * (`https://host/org/parent.git`, `/srv/remotes/parent.git`) origins: the split
+ * is on the last `/` when one exists; a scp-style origin whose repo sits at the
+ * path root (`git@host:parent.git`) has no `/`, so the sibling lives after the
+ * last `:` instead.
+ *
+ * @param {string|null} parentOrigin the parent's `remote.origin.url`
+ * @param {string} childPath gitlink path
+ * @returns {string|null} the derived URL, or null when no origin is available
+ */
+export function conventionUrl(parentOrigin, childPath) {
+	if (!parentOrigin) return null;
+	const trimmed = parentOrigin.replace(/\/+$/, "");
+	const idx = trimmed.lastIndexOf("/");
+	if (idx >= 0) return `${trimmed.slice(0, idx)}/${basename(childPath)}.git`;
+	const colon = trimmed.lastIndexOf(":");
+	if (colon < 0) return null;
+	return `${trimmed.slice(0, colon)}:${basename(childPath)}.git`;
+}
+
+/**
+ * Resolve a child's clone URL, strictest source first. This is the security
+ * model's heart: URL knowledge is never committed, so a URL can only come from
+ * one of three OPTIONAL layers, tried in order —
+ *
+ *   1. `local-config` — the per-clone registry (`embedded.<path>.url`).
+ *   2. `manifest`      — a hand-carried transfer file passed via `--from`.
+ *   3. `base`          — an explicit `--base <url-base>` + `<basename>.git`.
+ *   4. `convention`    — sibling of the parent's origin (zero committed state).
+ *
+ * A `base`/`convention` result is only a *guess*; the caller SHA-verifies every
+ * clone so a wrong guess fails closed rather than planting the wrong repo.
+ *
+ * @param {string} childPath gitlink path to resolve
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] parent repo working directory (for layer 1)
+ * @param {object|null} [opts.manifest] parsed manifest `{ children: {…} }` (layer 2)
+ * @param {string|null} [opts.base] explicit URL base (layer 3)
+ * @param {string|null} [opts.parentOrigin] parent `remote.origin.url` (layer 4)
+ * @returns {{ url: string, source: "local-config"|"manifest"|"base"|"convention" }
+ *   | { url: null, source: null }}
+ */
+export default function resolve(childPath, opts = {}) {
+	const { cwd = process.cwd(), manifest = null, base = null, parentOrigin = null } = opts;
+
+	// 1. Local-config registry — strictest, per-clone, never committed.
+	const cfgUrl = self.embedded.registry.getUrl(childPath, cwd);
+	if (cfgUrl) return { url: cfgUrl, source: "local-config" };
+
+	// 2. Manifest file (transfer format, carried out-of-band via --from).
+	// Own properties only — direct indexing could read inherited keys (e.g. a
+	// path named "constructor"), and Object.hasOwn also behaves correctly for
+	// null-prototype children maps.
+	const child = manifest && manifest.children && Object.hasOwn(manifest.children, childPath) ? manifest.children[childPath] : null;
+	if (child && child.url) return { url: child.url, source: "manifest" };
+
+	// 3. Explicit --base + basename.
+	if (base) {
+		const dir = String(base).replace(/\/+$/, "");
+		return { url: `${dir}/${basename(childPath)}.git`, source: "base" };
+	}
+
+	// 4. Convention: sibling of the parent's origin. Zero committed state; a
+	//    wrong guess is caught by SHA verification downstream.
+	const conv = conventionUrl(parentOrigin, childPath);
+	if (conv) return { url: conv, source: "convention" };
+
+	return { url: null, source: null };
+}

package/src/api/embedded/restore.mjs

@@ -0,0 +1,242 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+function git(args, opts = {}) {
+	const res = context.spawnSync("git", args, { encoding: "utf8", ...opts });
+	return { code: res.status ?? 1, stdout: (res.stdout || "").trim(), stderr: (res.stderr || "").trim() };
+}
+
+/**
+ * Remove a clone WE created, without ever touching a pre-existing directory.
+ * When the target did not exist before we cloned, the whole directory is ours
+ * to delete. When it pre-existed (git materializes a gitlink as an empty dir),
+ * only our clone's contents are removed — the directory itself is left in place.
+ * @param {string} absChild absolute child path
+ * @param {boolean} existedBefore whether the directory existed before the clone
+ */
+function removeClone(absChild, existedBefore) {
+	const { fs, path } = context;
+	if (!existedBefore) {
+		fs.rmSync(absChild, { recursive: true, force: true });
+		return;
+	}
+	for (const entry of fs.readdirSync(absChild)) {
+		fs.rmSync(path.join(absChild, entry), { recursive: true, force: true });
+	}
+}
+
+/**
+ * Restore engine: clone missing embedded children and check out their pinned
+ * SHAs, resolving each URL strictest-source-first and SHA-verifying every clone
+ * so a wrong convention guess fails closed.
+ *
+ * Branch-aware: a branch for the child is resolved with the same layering as
+ * the URL — the registry (`embedded.<path>.branch`), then the manifest — and
+ * when neither supplies one it is inferred from the pin (exactly ONE `origin`
+ * branch containing it). With a branch the child ends ON that branch at the
+ * pin (upstream set best-effort, branch auto-registered); without one —
+ * including an ambiguous pin — the checkout stays detached.
+ *
+ * Partial restore is normal — a public cloner without access to a private child
+ * passes that path in `skip` and the rest still restore.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] working directory inside the parent repo
+ * @param {string[]} [opts.paths] restrict to these gitlink paths (default: all)
+ * @param {string} [opts.from] manifest file to read child URLs from
+ * @param {string} [opts.base] explicit URL base (`<base>/<basename>.git`)
+ * @param {string[]} [opts.skip] gitlink paths to skip
+ * @param {boolean} [opts.dryRun] resolve and report only; clone/write nothing
+ * @returns {{ results: Array<object>, exitCode: number }} per-child outcomes and
+ *   a process exit code (non-zero when any non-skipped child ends `unresolved`
+ *   or `pinned-mismatch`)
+ */
+export default function restore(opts = {}) {
+	const { fs, path } = context;
+	const { cwd = process.cwd(), paths = [], from = null, base = null, skip = [], dryRun = false } = opts;
+
+	const root = self.git.getRepoRoot(cwd) || cwd;
+	const parentOrigin = git(["-C", root, "config", "--get", "remote.origin.url"]).stdout || null;
+	const manifest = from ? self.embedded.manifest.read(from, cwd) : null;
+
+	// Gitlink paths from ls-tree are root-relative with forward slashes; accept
+	// the common user spellings of the same path ("./tests", "tests/", Windows
+	// "vendor\\foo") for --skip / path filters instead of silently not matching.
+	const normalizePath = (p) =>
+		String(p)
+			.replace(/\\/g, "/")
+			.replace(/^\.\/+/, "")
+			.replace(/\/+$/, "");
+	const skipSet = new Set(skip.map(normalizePath));
+	const wantSet = paths.length ? new Set(paths.map(normalizePath)) : null;
+
+	const links = self.embedded.gitlinks(root);
+	const results = [];
+
+	for (const { path: childPath, sha } of links) {
+		if (wantSet && !wantSet.has(childPath)) continue;
+
+		const record = { path: childPath, sha, url: null, source: null, branch: null, note: null };
+
+		if (skipSet.has(childPath)) {
+			results.push({ ...record, outcome: "skipped" });
+			continue;
+		}
+
+		const absChild = path.resolve(root, childPath);
+
+		// lstat BEFORE probing for `.git` so a symlinked child is refused before
+		// anything follows it. A symlink that resolves to a real repo would
+		// otherwise satisfy the existsSync(.git) check below and be blessed as
+		// already-present — yet the packaged hooks cd into the child and would
+		// follow that link out of the parent worktree. lstat (not stat) sees the
+		// link itself, and also catches a broken symlink that existsSync misses.
+		let targetStat = null;
+		try {
+			targetStat = fs.lstatSync(absChild);
+		} catch (err) {
+			// Only ENOENT means "missing — clone will create it". A non-ENOENT
+			// lstat error (EACCES/ENOTDIR on an existing path) must be refused, not
+			// assumed absent — otherwise we could clone into, and later removeClone
+			// against, a pre-existing path we can't even stat.
+			if (err.code !== "ENOENT") {
+				/* v8 ignore next -- defensive: an fs error object always carries a `.code`, so the `|| err.message` fallback is unreachable. */
+				results.push({ ...record, outcome: "unresolved", note: `target unreadable (${err.code || err.message}) — refusing to touch it` });
+				continue;
+			}
+		}
+		if (targetStat && targetStat.isSymbolicLink()) {
+			results.push({ ...record, outcome: "unresolved", note: "target is a symbolic link — refusing to touch it" });
+			continue;
+		}
+
+		const hasGit = fs.existsSync(path.join(absChild, ".git"));
+		if (hasGit) {
+			results.push({ ...record, outcome: "already-present" });
+			continue;
+		}
+
+		// The only acceptable pre-existing target is an EMPTY, REAL directory —
+		// what a fresh parent clone materializes for a gitlink. A file or a
+		// directory with contents is user data: never clone into it, never remove
+		// it. (A symlink was already refused above.)
+		if (targetStat) {
+			let refuse = null;
+			if (!targetStat.isDirectory()) refuse = "target exists and is not a directory";
+			else {
+				try {
+					if (fs.readdirSync(absChild).length > 0) refuse = "target directory is not empty";
+				} catch (err) {
+					/* v8 ignore next -- defensive: an fs error object always carries a `.code`, so the `|| err.message` fallback is unreachable. */
+					refuse = `target unreadable (${err.code || err.message})`;
+				}
+			}
+			if (refuse) {
+				results.push({ ...record, outcome: "unresolved", note: `${refuse} — refusing to touch it` });
+				continue;
+			}
+		}
+
+		const resolved = self.embedded.resolve(childPath, { cwd: root, manifest, base, parentOrigin });
+		record.url = resolved.url;
+		record.source = resolved.source;
+		if (!resolved.url) {
+			results.push({ ...record, outcome: "unresolved", note: "no URL from local config, manifest, --base, or convention" });
+			continue;
+		}
+
+		// Branch precedence mirrors URL precedence: the per-clone registry first,
+		// then the manifest. Inference from the pin needs the clone to exist, so
+		// it runs after SHA verification below. Own-property manifest access for
+		// the same reason as resolve (a child path named "constructor").
+		const manifestChild =
+			manifest && manifest.children && Object.hasOwn(manifest.children, childPath) ? manifest.children[childPath] : null;
+		const wantedBranch = self.embedded.registry.getBranch(childPath, root) || (manifestChild && manifestChild.branch) || null;
+		record.branch = wantedBranch;
+
+		if (dryRun) {
+			results.push({ ...record, outcome: "restored", dryRun: true });
+			continue;
+		}
+
+		const existedBefore = fs.existsSync(absChild);
+		// `--` ends option parsing: a URL from config/manifest/--base that starts
+		// with "-" must never be interpreted as a git option (e.g. --upload-pack).
+		// cwd=root anchors a RELATIVE url (e.g. "../sibling.git") to the parent repo
+		// root, so a restore resolves the same regardless of where the caller ran
+		// from. Without it git resolves the url against the Node process CWD (the
+		// destination is absolute, so only the source url is affected).
+		const clone = git(["clone", "--quiet", "--", resolved.url, absChild], { cwd: root });
+		if (clone.code !== 0) {
+			if (fs.existsSync(absChild)) removeClone(absChild, existedBefore);
+			/* v8 ignore next -- git normally writes to stderr on a clone failure; the empty-stderr `|| exit N` fallback covers a stderr-less failure (e.g. signal kill) — real, just not reproducible in the suite */
+			results.push({ ...record, outcome: "unresolved", note: `clone failed: ${clone.stderr || `exit ${clone.code}`}` });
+			continue;
+		}
+
+		// SHA verification: the parent's pinned commit MUST exist in the clone.
+		// One fetch is attempted before giving up, in case origin's default
+		// refspec did not include the pinned commit.
+		let present = git(["-C", absChild, "cat-file", "-e", `${sha}^{commit}`]).code === 0;
+		let fetchErr = null;
+		if (!present) {
+			const fetch = git(["-C", absChild, "fetch", "--quiet", "origin"]);
+			/* v8 ignore next -- the clone above just succeeded from this same origin (git
+			   stores it as an absolute path), so the follow-up fetch normally succeeds; a
+			   mid-call network failure (remote unreachable) is real but not reproducible in the suite. */
+			if (fetch.code !== 0) fetchErr = fetch.stderr || `git fetch exited ${fetch.code}`;
+			present = git(["-C", absChild, "cat-file", "-e", `${sha}^{commit}`]).code === 0;
+		}
+		if (!present) {
+			removeClone(absChild, existedBefore);
+			// A failed fetch (auth/network) is not the same as "wrong repo" — surface
+			// it so a pinned-mismatch isn't misread as a bad convention guess.
+			const why = fetchErr
+				? /* v8 ignore next -- fetchErr is set only by the fetch-failure path above — a mid-call network failure, real but not reproducible in the suite */
+					`fetch from ${resolved.source} repo failed (${fetchErr})`
+				: `pinned ${sha.slice(0, 12)} absent in ${resolved.source} repo`;
+			results.push({
+				...record,
+				outcome: "pinned-mismatch",
+				note: `${why}; clone removed`
+			});
+			continue;
+		}
+
+		// Branch-aware checkout: registry/manifest branch wins; otherwise infer it
+		// from the pin. Attach failure (e.g. an invalid branch name in the
+		// registry) falls back to today's detached checkout rather than failing
+		// the restore — the pin is verified present, so detached is always safe.
+		const branch = wantedBranch || self.embedded.branch.infer(absChild, sha);
+		let attached = false;
+		if (branch) {
+			attached = self.embedded.branch.attach(absChild, branch, sha);
+			if (!attached) record.note = `could not attach branch ${branch}; checked out detached`;
+		}
+		record.branch = attached ? branch : null;
+		if (!attached) {
+			const checkout = git(["-C", absChild, "checkout", "--quiet", "--detach", sha]);
+			/* v8 ignore start -- the pin was just SHA-verified present in this fresh clone,
+			   so the detached checkout normally succeeds; an I/O error or mid-call corruption
+			   is real but not reproducible in the suite. */
+			if (checkout.code !== 0) {
+				removeClone(absChild, existedBefore);
+				results.push({
+					...record,
+					outcome: "pinned-mismatch",
+					note: `could not check out ${sha.slice(0, 12)}: ${checkout.stderr || `git checkout exited ${checkout.code}`}; clone removed`
+				});
+				continue;
+			}
+			/* v8 ignore stop */
+		}
+
+		// Persist the resolved URL (and the branch the child ended on) so day-2
+		// re-restores and `sync` don't re-derive them.
+		self.embedded.registry.setUrl(childPath, resolved.url, root);
+		if (attached) self.embedded.registry.setBranch(childPath, branch, root);
+		results.push({ ...record, outcome: "restored" });
+	}
+
+	const exitCode = results.some((r) => r.outcome === "unresolved" || r.outcome === "pinned-mismatch") ? 1 : 0;
+	return { results, exitCode };
+}