@junghanacs/entwurf 0.31.0 → 0.33.0

package/pi-extensions/lib/pi-durable-runtime.ts

@@ -1,80 +1,59 @@
 /**
- * pi-durable-runtime — where the operator-provided durable runtime lives, and whether it is the pin
- * (#129 W, L3).
+ * pi-durable-runtime — whether THIS package's pi-durable carrier can run, and the resolver it runs
+ * under (#129 W, #130).
  *
- * The experimental durable app is SOURCE-ONLY upstream: the published Pi CLI ships no
- * `dist/experimental`, and `@earendil-works/pi-durable` on npm is the library, not this app. So its
- * runtime is a checkout the OPERATOR provides — the pinned commit plus this package's overlay patch
- * and the pinned model data — and Entwurf never downloads, installs, moves or deletes it. This leaf
- * only DETECTS it, at ONE fixed place:
+ * The experimental durable app is source-only upstream: published `@earendil-works/pi-coding-agent`
+ * ships no `dist/experimental`. Entwurf therefore ships the app itself as a CARRIER — the pinned
+ * upstream files, type-stripped and relocated (pi/pi-durable/carrier/, emitted only by the
+ * maintainer's scripts/emit-pi-durable-carrier.ts) — and declares the published SDK set it runs
+ * against as exact production dependencies. Nothing is provisioned beside the package: there is no
+ * runtime directory, no source checkout and no model data to copy (it rides the published pi-ai).
  *
- *   $XDG_DATA_HOME/entwurf/pi-durable/runtime   (an absolute XDG_DATA_HOME; else ~/.local/share)
+ * The carrier counts as runnable only when, read from where this package is installed:
+ *   - every pinned carrier file, the license, the resolver and its relocation grammar are present
+ *     (else `pi-durable-package-incomplete`);
+ *   - each carrier file and the license carry the pinned sha256 (else `pi-durable-carrier-drift`);
+ *   - every declared SDK member and direct dependency resolves from the carrier, and every member
+ *     copy the carrier can reach — at any depth, nested copies included — resolves each of its own
+ *     member dependencies (else `pi-durable-sdk-absent`);
+ *   - each of those PHYSICAL edges lands on a package that is the one it names, at exactly the
+ *     declared version (else `pi-durable-sdk-mismatch`). The members declare each other with caret ranges, so semver
+ *     satisfaction is not the contract — the bytes a carrier import actually binds are. Sharing one
+ *     copy with a host install of the same version is an ordinary layout and passes; how many copies
+ *     of a version exist is not asked.
  *
- * There is no public path override. `ENTWURF_PI_DURABLE_RUNTIME` stays the CHECKOUT-ONLY input of
- * the `check-pi-durable-*` gates; nothing here reads it.
+ * Every refusal names the first failing item, in repair order. This leaf is the native-set check
+ * only: the ordinary Pi HOST on PATH is a different subject (`pi_supported_range` in run.sh).
  *
- * A present runtime counts as the pin only when HEAD equals the pinned commit, the index equals HEAD
- * (nothing staged), `git diff --binary` equals the overlay patch bytes exactly, no non-ignored file is
- * untracked, the experimental source resolver is there, and the git-ignored model data matches the
- * pin's recorded digests. Anything else is present-but-wrong, a named refusal — never a guess and
- * never a repair. The index term is not optional: `git diff` compares the worktree to the INDEX, so a
- * staged edit to any other tracked file — or a staged new file, which is not "untracked" either —
- * would otherwise leave the diff equal to the patch.
- *
- * The diff bytes are compared, so the configuration knobs known to move them are pinned on the
- * command line to the form the packaged patch is in: abbreviation length, prefixes, colour,
- * external/textconv drivers, hunk algorithm and context, relative paths, and blank-context spacing
- * (`diff.suppressBlankEmpty`; the packaged patch has blank context lines). That is a bounded list,
- * not every knob git has: e.g. `diff.orderFile` (multi-file order) and line-ending conversion
- * (`core.autocrlf`/`core.eol`) are not neutralized, and a byte change they cause reads as pin drift.
- * Configuration is not disabled wholesale — `safe.directory` lives in global/system config.
- *
- * The overlay data (pin + patch) ships IN this package and is found relative to this module, at the
- * two depths the module is shipped at: the source checkout (`<root>/pi-extensions/lib/`) and the
- * compiled bridge closure (`<root>/mcp/entwurf-bridge/dist/pi-extensions/lib/`) — the same two-depth
- * arithmetic `metaCapabilitiesFilePath` answers. The compiled durable units are named from that same
- * root, so a launcher, a preflight and the bootstrap all read ONE package closure.
- *
- * Read-only: `git diff` and `git ls-files` run against a private COPY of the runtime's index
- * (`GIT_INDEX_FILE`), with GIT_OPTIONAL_LOCKS=0. The copy is not ceremony: `git diff` was measured
- * to refresh and rewrite a stat-dirty index even with optional locks off, so asking the operator's
- * own index would mutate their checkout. No network, no install, no credential, settings or session read.
- * Each `git` is a direct child with a wall-clock bound; one that does not answer in time is unverifiable.
+ * Read-only: file reads and Node's own package resolution (`module.findPackageJSON`) from the
+ * carrier's location. No git, no network, no environment, no credential, settings or session read.
  */
 
-import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
-import * as os from "node:os";
+import { findPackageJSON } from "node:module";
 import * as path from "node:path";
+import { pathToFileURL } from "node:url";
 
-/** The fixed locator under the data home. Not configurable. */
-export const PI_DURABLE_RUNTIME_SEGMENTS = ["entwurf", "pi-durable", "runtime"] as const;
-
-/** The upstream source resolver the durable app runs under, inside the runtime checkout. */
-export const PI_DURABLE_RESOLVER_RELATIVE = path.join(
-	"packages",
-	"coding-agent",
-	"src",
-	"experimental",
-	"source-resolver.ts",
-);
-
-/** Every way the runtime can be refused. Stable contract: these cross the launcher, setup and the
+/** Every way the carrier can be refused. Stable contract: these cross the launcher, setup and the
  * fresh-call surfaces as named refusals. */
 export type PiDurableRuntimeRejectReason =
 	| "pi-durable-package-incomplete"
-	| "pi-durable-runtime-locator-unset"
-	| "pi-durable-runtime-absent"
-	| "pi-durable-runtime-unverifiable"
-	| "pi-durable-runtime-pin-drift"
-	| "pi-durable-runtime-modeldata-drift";
+	| "pi-durable-carrier-drift"
+	| "pi-durable-sdk-absent"
+	| "pi-durable-sdk-mismatch";
 
-/** The package closure this module belongs to: the overlay data and the compiled durable units. */
+/** The package closure this module belongs to: the pin, the carrier and the compiled durable units. */
 export interface PiDurablePackageLayout {
 	readonly root: string;
 	readonly overlayDir: string;
-	/** The packaged bootstrap the launcher executes under the runtime's resolver. */
+	/** The emitted upstream app files and their license. */
+	readonly carrierDir: string;
+	/** The `--import` resolver the launcher runs the bootstrap under. */
+	readonly resolver: string;
+	/** The relocation grammar the resolver imports. */
+	readonly relocation: string;
+	/** The packaged bootstrap the launcher executes under the resolver. */
 	readonly bootstrap: string;
 	/** The compiled durable contact (birth, doorbell, visible identity decoration). */
 	readonly adapter: string;
@@ -86,11 +65,15 @@ export interface PiDurablePackageLayout {
 
 /** The layout rooted at `root`, as plain paths. */
 export function piDurableLayoutAt(root: string): PiDurablePackageLayout {
+	const durable = path.join(root, "pi", "pi-durable");
 	const dist = path.join(root, "mcp", "entwurf-bridge", "dist");
 	return {
 		root,
-		overlayDir: path.join(root, "pi", "pi-durable", "overlay"),
-		bootstrap: path.join(root, "pi", "pi-durable", "bootstrap.mjs"),
+		overlayDir: path.join(durable, "overlay"),
+		carrierDir: path.join(durable, "carrier"),
+		resolver: path.join(durable, "carrier-resolver.mjs"),
+		relocation: path.join(durable, "carrier-relocation.mjs"),
+		bootstrap: path.join(durable, "bootstrap.mjs"),
 		adapter: path.join(dist, "pi-extensions", "meta-bridge-pi-durable.js"),
 		bridgeEntry: path.join(dist, "mcp", "entwurf-bridge", "src", "index.js"),
 		deliverability: path.join(dist, "pi-extensions", "lib", "entwurf-deliverability.js"),
@@ -99,7 +82,8 @@ export function piDurableLayoutAt(root: string): PiDurablePackageLayout {
 
 /**
  * The package closure, found from where THIS module lives: the source depth first, then the compiled
- * depth. `null` when neither carries the overlay pin — a packaging defect, refused by name.
+ * depth (`<root>/mcp/entwurf-bridge/dist/pi-extensions/lib/`). `null` when neither carries the pin —
+ * a packaging defect, refused by name.
  */
 export function piDurablePackageLayout(from: string = import.meta.dirname): PiDurablePackageLayout | null {
 	for (const up of [
@@ -113,235 +97,189 @@ export function piDurablePackageLayout(from: string = import.meta.dirname): PiDu
 	return null;
 }
 
-/** The fixed runtime location for this environment, or `null` when neither an absolute
- * XDG_DATA_HOME nor HOME exists to anchor it. A relative XDG_DATA_HOME is ignored (XDG spec). */
-export function piDurableRuntimeDir(env: NodeJS.ProcessEnv): string | null {
-	const xdg = env.XDG_DATA_HOME;
-	if (typeof xdg === "string" && xdg.length > 0 && path.isAbsolute(xdg)) {
-		return path.join(xdg, ...PI_DURABLE_RUNTIME_SEGMENTS);
-	}
-	const home = env.HOME;
-	if (typeof home === "string" && home.length > 0 && path.isAbsolute(home)) {
-		return path.join(home, ".local", "share", ...PI_DURABLE_RUNTIME_SEGMENTS);
-	}
-	return null;
+/** What the verifier reads from the packaged pin. */
+export interface PiDurableCarrierPin {
+	readonly files: readonly { readonly name: string; readonly sha256: string }[];
+	readonly license: { readonly sha256: string };
+	/** `@earendil-works/*` members: name → exact version. */
+	readonly members: Readonly<Record<string, string>>;
+	/** Third-party packages a carrier file imports itself: name → exact version. */
+	readonly direct: Readonly<Record<string, string>>;
 }
 
-export interface PiDurablePin {
-	readonly commit: string;
-	readonly patches: readonly string[];
-	readonly modelData: {
-		readonly path: string;
-		readonly files: number;
-		readonly aggregateSha256: string;
-		readonly manifestSha256: string;
-	};
-}
+const SHA256 = /^[0-9a-f]{64}$/;
+const EXACT = /^\d+\.\d+\.\d+$/;
 
-/** The packaged pin and its one patch. A malformed pin throws (crash, don't warn). */
-export function readPiDurablePin(overlayDir: string): { pin: PiDurablePin; patchBytes: Buffer } {
-	const pin = JSON.parse(fs.readFileSync(path.join(overlayDir, "upstream-pin.json"), "utf8")) as PiDurablePin;
-	if (typeof pin.commit !== "string" || !/^[0-9a-f]{40}$/.test(pin.commit)) {
-		throw new Error(`pi-durable pin: commit is not a full sha (${JSON.stringify(pin.commit)})`);
-	}
-	if (!Array.isArray(pin.patches) || pin.patches.length !== 1 || typeof pin.patches[0] !== "string") {
-		throw new Error("pi-durable pin: exactly one overlay patch is expected");
-	}
-	const md = pin.modelData;
+/** The packaged pin's carrier and SDK declarations. A malformed pin throws (crash, don't warn). */
+export function readPiDurableCarrierPin(overlayDir: string): PiDurableCarrierPin {
+	const pin = JSON.parse(fs.readFileSync(path.join(overlayDir, "upstream-pin.json"), "utf8"));
+	const files = pin?.carrier?.files;
+	const license = pin?.carrier?.license;
+	const members = pin?.sdk?.members;
+	const direct = pin?.sdk?.direct;
+	const versions = (set: unknown) =>
+		typeof set === "object" && set !== null && Object.values(set).every((v) => typeof v === "string" && EXACT.test(v));
 	if (
-		typeof md !== "object" ||
-		md === null ||
-		typeof md.path !== "string" ||
-		typeof md.files !== "number" ||
-		typeof md.aggregateSha256 !== "string" ||
-		typeof md.manifestSha256 !== "string"
+		!Array.isArray(files) ||
+		files.length === 0 ||
+		!files.every((f) => typeof f?.name === "string" && /^[a-z0-9-]+\.js$/.test(f.name) && SHA256.test(f?.sha256)) ||
+		!SHA256.test(license?.sha256) ||
+		!versions(members) ||
+		Object.keys(members).length === 0 ||
+		!versions(direct)
 	) {
-		throw new Error("pi-durable pin: modelData is malformed");
+		throw new Error("pi-durable pin: carrier files/license digests and exact sdk members/direct versions are required");
 	}
-	return { pin, patchBytes: fs.readFileSync(path.join(overlayDir, pin.patches[0])) };
+	return { files, license, members, direct };
 }
 
-const sha256 = (data: string | Buffer): string => createHash("sha256").update(data).digest("hex");
-
-/** The patch shape the packaged patch is in, fixed on the command line for the knobs the header lists:
- * git's default output with 8-hex `index` abbreviations. Two of those knobs are config-only and ride
- * beside these as `-c` at the call: `core.abbrev=8` ("auto" scales with the clone's object count) and
- * `diff.suppressBlankEmpty=false` (true drops the space before an empty context line). */
-export const PI_DURABLE_DIFF_SHAPE = [
-	"--binary",
-	"--no-ext-diff",
-	"--no-color",
-	"--no-textconv",
-	"--src-prefix=a/",
-	"--dst-prefix=b/",
-	"--no-relative",
-	"--diff-algorithm=myers",
-	"--indent-heuristic",
-	"-U3",
-	"--inter-hunk-context=0",
-] as const;
-
-/** Wall-clock bound for each local `git` the verifier runs (it also runs inside the bridge process). */
-export const PI_DURABLE_GIT_TIMEOUT_MS = 30_000;
+/** One physical dependency edge: `to` as resolved from `from`'s location. */
+export interface PiDurableSdkEdge {
+	/** `carrier` or the member the edge leaves. */
+	readonly from: string;
+	readonly to: string;
+	readonly want: string;
+	/** The resolved package's version, or `null` when it does not resolve. */
+	readonly got: string | null;
+	/** The name the resolved package.json declares, or `null` — must be `to` itself. */
+	readonly name: string | null;
+	/** The resolved package directory, or `null`. */
+	readonly at: string | null;
+}
 
-/** What a runtime directory holds, read without changing it. */
+/** What the installed package holds, read without changing it. */
 export interface PiDurableRuntimeFacts {
-	readonly runtimeDir: string;
-	readonly present: boolean;
-	/** `git` answered all four questions (rev-parse, cached diff, diff, ls-files). */
-	readonly gitAnswered: boolean;
-	readonly head: string;
-	/** The index equals HEAD: nothing is staged. */
-	readonly indexMatchesHead: boolean;
-	readonly diffEqualsPatch: boolean;
-	readonly untracked: string;
-	readonly resolverPresent: boolean;
-	readonly modelDataFiles: number;
-	readonly modelDataAggregate: string;
-	readonly manifestSha256: string;
+	/** A carrier/resolver/relocation file that is not there. */
+	readonly missing: readonly string[];
+	/** A carrier file (or LICENSE) whose bytes are not the pinned ones. */
+	readonly drifted: readonly string[];
+	readonly edges: readonly PiDurableSdkEdge[];
 }
 
-export function inspectPiDurableRuntime(runtimeDir: string, overlayDir: string): PiDurableRuntimeFacts {
-	const { pin, patchBytes } = readPiDurablePin(overlayDir);
-	const present = (() => {
-		try {
-			return fs.statSync(runtimeDir).isDirectory();
-		} catch {
-			// Bounded environment probe (Hard Rule 15's stated exception): absence is the answer.
-			return false;
-		}
-	})();
-	const base = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
-	const git = (args: string[], env: NodeJS.ProcessEnv = base) =>
-		spawnSync("git", ["-C", runtimeDir, ...args], {
-			maxBuffer: 64 * 1024 * 1024,
-			env,
-			timeout: PI_DURABLE_GIT_TIMEOUT_MS,
-		});
-	const headRun = present ? git(["rev-parse", "HEAD"]) : undefined;
-	// A private copy of the index, so the refresh `git diff` performs lands in a file this process owns.
-	let scratch: string | undefined;
-	let cachedRun: ReturnType<typeof git> | undefined;
-	let diffRun: ReturnType<typeof git> | undefined;
-	let untrackedRun: ReturnType<typeof git> | undefined;
+const sha256 = (data: Buffer): string => createHash("sha256").update(data).digest("hex");
+
+/** `name` resolved from `fromFile` by Node's own package resolution: its version and directory. */
+function resolveEdge(from: string, to: string, want: string, fromFile: string): PiDurableSdkEdge {
+	let manifest: string | undefined;
 	try {
-		const indexPath = present ? git(["rev-parse", "--git-path", "index"]) : undefined;
-		const index = indexPath?.status === 0 ? path.resolve(runtimeDir, indexPath.stdout.toString().trim()) : undefined;
-		if (index !== undefined && fs.existsSync(index)) {
-			scratch = fs.mkdtempSync(path.join(os.tmpdir(), "pi-durable-index-"));
-			const copy = path.join(scratch, "index");
-			fs.copyFileSync(index, copy);
-			const onCopy = { ...base, GIT_INDEX_FILE: copy };
-			// HEAD → index: exit 0 = nothing staged, 1 = something staged; anything else is no answer.
-			cachedRun = git(["diff", "--cached", "--quiet", "--no-ext-diff", "--no-relative"], onCopy);
-			diffRun = git(
-				["-c", "core.abbrev=8", "-c", "diff.suppressBlankEmpty=false", "diff", ...PI_DURABLE_DIFF_SHAPE],
-				onCopy,
-			);
-			untrackedRun = git(["ls-files", "--others", "--exclude-standard"], onCopy);
-		}
-	} finally {
-		if (scratch !== undefined) fs.rmSync(scratch, { recursive: true, force: true });
+		manifest = findPackageJSON(to, pathToFileURL(fromFile));
+	} catch {
+		// Bounded environment probe: an unresolvable package is the `got: null` answer.
+		manifest = undefined;
 	}
-	const gitAnswered =
-		headRun?.status === 0 &&
-		(cachedRun?.status === 0 || cachedRun?.status === 1) &&
-		diffRun?.status === 0 &&
-		untrackedRun?.status === 0;
-	const dataDir = path.join(runtimeDir, pin.modelData.path);
-	const dataFiles = (() => {
-		try {
-			return fs
-				.readdirSync(dataDir)
-				.filter((n) => n.endsWith(".json") && !n.startsWith("."))
-				.sort();
-		} catch {
-			return [];
-		}
-	})();
-	const manifest = path.join(dataDir, ".manifest.json");
+	if (manifest === undefined) return { from, to, want, got: null, name: null, at: null };
+	const json = JSON.parse(fs.readFileSync(manifest, "utf8"));
 	return {
-		runtimeDir,
-		present,
-		gitAnswered,
-		head: headRun?.stdout?.toString().trim() ?? "",
-		indexMatchesHead: cachedRun?.status === 0,
-		diffEqualsPatch: diffRun?.status === 0 && Buffer.isBuffer(diffRun.stdout) && diffRun.stdout.equals(patchBytes),
-		untracked: untrackedRun?.stdout?.toString().trim() ?? "",
-		resolverPresent: present && fs.existsSync(path.join(runtimeDir, PI_DURABLE_RESOLVER_RELATIVE)),
-		modelDataFiles: dataFiles.length,
-		modelDataAggregate: sha256(
-			dataFiles.map((n) => `${sha256(fs.readFileSync(path.join(dataDir, n)))}  ${n}\n`).join(""),
-		),
-		manifestSha256: fs.existsSync(manifest) ? sha256(fs.readFileSync(manifest)) : "absent",
+		from,
+		to,
+		want,
+		got: typeof json.version === "string" ? json.version : null,
+		name: typeof json.name === "string" ? json.name : null,
+		at: fs.realpathSync(path.dirname(manifest)),
 	};
 }
 
-/** The verdict over those facts against the pin: `null` is "this is the pin". */
-export function piDurableRuntimeVerdict(
-	facts: PiDurableRuntimeFacts,
-	pin: PiDurablePin,
-): PiDurableRuntimeRejectReason | null {
-	if (!facts.present) return "pi-durable-runtime-absent";
-	if (!facts.gitAnswered) return "pi-durable-runtime-unverifiable";
-	if (!facts.indexMatchesHead) return "pi-durable-runtime-pin-drift";
-	if (facts.head !== pin.commit || !facts.diffEqualsPatch || facts.untracked !== "" || !facts.resolverPresent) {
-		return "pi-durable-runtime-pin-drift";
+export function inspectPiDurableRuntime(layout: PiDurablePackageLayout): PiDurableRuntimeFacts {
+	const pin = readPiDurableCarrierPin(layout.overlayDir);
+	const missing: string[] = [];
+	const drifted: string[] = [];
+	const pinned = [...pin.files, { name: "LICENSE", sha256: pin.license.sha256 }];
+	for (const file of pinned) {
+		const at = path.join(layout.carrierDir, file.name);
+		if (!fs.existsSync(at)) missing.push(path.relative(layout.root, at));
+		else if (sha256(fs.readFileSync(at)) !== file.sha256) drifted.push(path.relative(layout.root, at));
 	}
-	if (
-		facts.modelDataFiles !== pin.modelData.files ||
-		facts.modelDataAggregate !== pin.modelData.aggregateSha256 ||
-		facts.manifestSha256 !== pin.modelData.manifestSha256
-	) {
-		return "pi-durable-runtime-modeldata-drift";
+	for (const at of [layout.resolver, layout.relocation]) {
+		if (!fs.existsSync(at)) missing.push(path.relative(layout.root, at));
 	}
+	const edges: PiDurableSdkEdge[] = [];
+	// From the carrier's own location: the bare imports its files make resolve from there.
+	const base = path.join(layout.carrierDir, pin.files[0].name);
+	// Every member COPY the carrier can reach is walked, at any depth: a nested copy's own member
+	// dependencies are edges too. One physical directory is walked once (shared and duplicate copies
+	// are ordinary; a member cycle terminates), keyed by its realpath.
+	const pending: { name: string; at: string }[] = [];
+	for (const [name, want] of Object.entries({ ...pin.members, ...pin.direct })) {
+		const edge = resolveEdge("carrier", name, want, base);
+		edges.push(edge);
+		if (name in pin.members && edge.at !== null) pending.push({ name, at: edge.at });
+	}
+	const walked = new Set<string>();
+	for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+		if (walked.has(next.at)) continue;
+		walked.add(next.at);
+		const manifest = path.join(next.at, "package.json");
+		const deps = JSON.parse(fs.readFileSync(manifest, "utf8")).dependencies ?? {};
+		for (const dep of Object.keys(deps)
+			.filter((d) => d in pin.members)
+			.sort()) {
+			const edge = resolveEdge(next.name, dep, pin.members[dep], manifest);
+			edges.push(edge);
+			if (edge.at !== null) pending.push({ name: dep, at: edge.at });
+		}
+	}
+	return { missing, drifted, edges };
+}
+
+const edgeText = (e: PiDurableSdkEdge): string =>
+	`${e.from} → ${e.to} wants ${e.want}, ${
+		e.got === null
+			? "resolves nothing"
+			: `binds ${e.name === e.to ? "" : `${e.name ?? "(unnamed)"}@`}${e.got} at ${e.at}`
+	}`;
+
+/** The verdict over those facts, in repair order: `null` is "the carrier can run". */
+export function piDurableRuntimeVerdict(
+	facts: PiDurableRuntimeFacts,
+): { reason: PiDurableRuntimeRejectReason; detail: string } | null {
+	if (facts.missing.length > 0)
+		return { reason: "pi-durable-package-incomplete", detail: `missing ${facts.missing.join(", ")}` };
+	if (facts.drifted.length > 0)
+		return { reason: "pi-durable-carrier-drift", detail: `changed ${facts.drifted.join(", ")}` };
+	const absent = facts.edges.find((e) => e.got === null);
+	if (absent !== undefined) return { reason: "pi-durable-sdk-absent", detail: edgeText(absent) };
+	const mismatch = facts.edges.find((e) => e.got !== e.want || e.name !== e.to);
+	if (mismatch !== undefined) return { reason: "pi-durable-sdk-mismatch", detail: edgeText(mismatch) };
 	return null;
 }
 
 export type PiDurableRuntimeCheck =
-	| { ok: true; runtimeDir: string; resolver: string }
-	| { ok: false; reason: PiDurableRuntimeRejectReason; runtimeDir: string | null };
+	| { ok: true; resolver: string; edges: readonly PiDurableSdkEdge[] }
+	| { ok: false; reason: PiDurableRuntimeRejectReason; detail: string };
 
-/** Locate and verify, in that order. The launcher, setup and the fresh preflight all ask this. */
-export function checkPiDurableRuntime(
-	env: NodeJS.ProcessEnv,
-	layout: PiDurablePackageLayout | null,
-): PiDurableRuntimeCheck {
-	if (layout === null) return { ok: false, reason: "pi-durable-package-incomplete", runtimeDir: null };
-	const runtimeDir = piDurableRuntimeDir(env);
-	if (runtimeDir === null) return { ok: false, reason: "pi-durable-runtime-locator-unset", runtimeDir: null };
-	const { pin } = readPiDurablePin(layout.overlayDir);
-	const reason = piDurableRuntimeVerdict(inspectPiDurableRuntime(runtimeDir, layout.overlayDir), pin);
-	if (reason !== null) return { ok: false, reason, runtimeDir };
-	return { ok: true, runtimeDir, resolver: path.join(runtimeDir, PI_DURABLE_RESOLVER_RELATIVE) };
+/** Locate and verify. The launcher, setup, the fresh preflight and the durable gates all ask this. */
+export function checkPiDurableRuntime(layout: PiDurablePackageLayout | null): PiDurableRuntimeCheck {
+	if (layout === null) {
+		return { ok: false, reason: "pi-durable-package-incomplete", detail: "no pi-durable pin next to this code" };
+	}
+	const facts = inspectPiDurableRuntime(layout);
+	const verdict = piDurableRuntimeVerdict(facts);
+	if (verdict !== null) return { ok: false, ...verdict };
+	return { ok: true, resolver: layout.resolver, edges: facts.edges };
 }
 
 export const PI_DURABLE_RUNTIME_HINT: Record<PiDurableRuntimeRejectReason, string> = {
 	"pi-durable-package-incomplete":
-		"this Entwurf package carries no pi-durable overlay pin next to its code — reinstall Entwurf; the package itself is incomplete",
-	"pi-durable-runtime-locator-unset":
-		"neither an absolute XDG_DATA_HOME nor HOME is set, so the fixed runtime location cannot be named",
-	"pi-durable-runtime-absent":
-		"no operator-provided durable runtime at the fixed location — Entwurf never installs it: provide the pinned upstream checkout plus the overlay patch and model data there (docs/setup-clean-host.md)",
-	"pi-durable-runtime-unverifiable":
-		"the runtime location exists but git could not read it as a checkout, so it cannot be proven to be the pin",
-	"pi-durable-runtime-pin-drift":
-		"the runtime is not the pin: HEAD, the overlay patch bytes, an untracked file or the source resolver differs from the packaged pi/pi-durable/overlay/upstream-pin.json — re-provision it at the pinned commit with exactly the packaged patch",
-	"pi-durable-runtime-modeldata-drift":
-		"the runtime's git-ignored model data is not the pinned bytes — restore the model data the pin records",
+		"this Entwurf package is missing part of its pi-durable carrier — reinstall Entwurf; nothing outside the package supplies it",
+	"pi-durable-carrier-drift":
+		"a pi-durable carrier file is not the bytes pi/pi-durable/overlay/upstream-pin.json records — reinstall Entwurf; the carrier is never edited in place",
+	"pi-durable-sdk-absent":
+		"a declared pi SDK package does not resolve from the carrier — reinstall Entwurf so its dependencies are installed",
+	"pi-durable-sdk-mismatch":
+		"a pi SDK package the carrier binds is not the declared version (another install's copy, an override or a partial upgrade) — reinstall Entwurf into a tree whose @earendil-works packages are the pinned version",
 };
 
-/** Exit codes of the CLI below, read by `run.sh`: 0 verified, 4 absent (setup SKIP), 3 anything else. */
-export const PI_DURABLE_RUNTIME_EXIT = { verified: 0, absent: 4, refused: 3 } as const;
+/** Exit codes of the CLI below, read by `run.sh`: 0 verified, 3 refused. There is no "absent"
+ * answer any more: the carrier ships in the package, so a missing piece is an incomplete install. */
+export const PI_DURABLE_RUNTIME_EXIT = { verified: 0, refused: 3 } as const;
 
 /**
- * `resolve`: print the verified runtime's source-resolver path (stdout) and exit 0, or print
- * `<reason>: <hint>` (stderr) and exit 4 for an absent runtime / 3 for every other refusal.
- * The launcher execs node under that resolver; setup maps the three codes to PASS / SKIP / FAIL.
+ * `resolve`: print the verified carrier's resolver path (stdout) and exit 0, or print
+ * `<reason>: <detail> — <hint>` (stderr) and exit 3. The launcher execs node under that resolver;
+ * setup maps the two codes to PASS / FAIL.
  */
 export function runPiDurableRuntimeCli(
 	argv: readonly string[],
-	env: NodeJS.ProcessEnv,
 	layout: PiDurablePackageLayout | null,
 	out: { stdout: (line: string) => void; stderr: (line: string) => void },
 ): number {
@@ -349,17 +287,13 @@ export function runPiDurableRuntimeCli(
 		out.stderr("usage: pi-durable-runtime resolve");
 		return 2;
 	}
-	const checked = checkPiDurableRuntime(env, layout);
+	const checked = checkPiDurableRuntime(layout);
 	if (checked.ok) {
 		out.stdout(checked.resolver);
 		return PI_DURABLE_RUNTIME_EXIT.verified;
 	}
-	out.stderr(
-		`${checked.reason}${checked.runtimeDir === null ? "" : ` (${checked.runtimeDir})`}: ${PI_DURABLE_RUNTIME_HINT[checked.reason]}`,
-	);
-	return checked.reason === "pi-durable-runtime-absent"
-		? PI_DURABLE_RUNTIME_EXIT.absent
-		: PI_DURABLE_RUNTIME_EXIT.refused;
+	out.stderr(`${checked.reason}: ${checked.detail} — ${PI_DURABLE_RUNTIME_HINT[checked.reason]}`);
+	return PI_DURABLE_RUNTIME_EXIT.refused;
 }
 
 // RUN AS THE CLI ONLY WHEN THIS FILE IS THE PROCESS ENTRY. Decided by an argv comparison, as in
@@ -377,7 +311,7 @@ const invokedDirectly = (() => {
 	}
 })();
 if (invokedDirectly) {
-	process.exitCode = runPiDurableRuntimeCli(process.argv.slice(2), process.env, piDurablePackageLayout(), {
+	process.exitCode = runPiDurableRuntimeCli(process.argv.slice(2), piDurablePackageLayout(), {
 		stdout: (line) => process.stdout.write(`${line}\n`),
 		stderr: (line) => process.stderr.write(`${line}\n`),
 	});

package/pi-extensions/meta-bridge-pi-durable.ts

@@ -2,8 +2,9 @@
  * meta-bridge-pi-durable — the durable app's native contact, identity leaf (#129 L-identity).
  *
  * WHAT THIS IS. The long-running durable app (`@earendil-works/pi-coding-agent`
- * `experimental/durable`, source-only upstream) owns its runtime, TUI, models/auth, storage,
- * prompt and recovery. This module is the whole Entwurf side of its contact:
+ * `experimental/durable`, which upstream omits from its npm distribution — Entwurf's package
+ * supplies it as a pinned carrier, #130, not as an operator prerequisite) owns its runtime, TUI,
+ * models/auth, storage, prompt and recovery. This module is the whole Entwurf side of its contact:
  *
  *   createPiDurableContact({ bridgeEntry })
  *     .extension          tools-only durable Extension, handed to the overlay's
@@ -13,8 +14,9 @@
  *                         release the tools
  *
  * The bootstrap that composes the two lives with the overlay (`pi/pi-durable/bootstrap.mjs`), not
- * here: this module never imports the durable runtime, so Entwurf carries no path into a
- * vendor checkout and no `@earendil-works/pi-durable` dependency.
+ * here: this module never imports or initializes the durable app runtime and carries no path into
+ * a vendor checkout. That is this module's import boundary, not the package's dependency list: the
+ * package does declare the exact `@earendil-works/pi-durable` (per the pin's SDK set) for its carrier (#130).
  *
  * WHY BIRTH IS AFTER OPEN, BEHIND A GATE. `[read @cd32f77]` The native session id is chosen
  * inside `openDurable` (`runtime.ts:125`, `sessions.ts:18-55`), and `openDurable` calls
@@ -272,9 +274,13 @@ export interface PiDurableRoots {
 }
 
 // ---------------------------------------------------------------------------
-// Durable surface, typed NARROWLY and locally (pi-durable 1.0.2 @cd32f77,
-// `harness/types.ts`). `defineExtension`/`defineTool` are identity functions
-// (`harness/define.ts:6-17`), so a plain object is the extension.
+// Durable surface, typed NARROWLY and locally — read at pi-durable 1.0.2 @cd32f77 (#129,
+// `harness/types.ts`; historical coordinates, not re-anchored here). The current supply is the
+// carrier `pi/pi-durable/overlay/upstream-pin.json` names (1.1.0 at `abe508e`). `[read 2026-10-08]`
+// v1.0.4 → v1.1.0 `harness/types.ts` adds `models`, `contextRetentionMs` and a `context()` options
+// bag only; none of the shapes typed below moved.
+// `defineExtension`/`defineTool` are identity functions (`harness/define.ts:6-17`), so a plain
+// object is the extension.
 // ---------------------------------------------------------------------------
 
 /** `DurableView.session` — `runtime.ts:53`. */