@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/host/truapi-cli/src/rebase-check.d.ts

@@ -0,0 +1,218 @@
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+import { type HostPatchEntry } from "./patch-manifest.js";
+import type { HostProbeReport, Observed, ProbeVerdict } from "./capability-probes.js";
+/** Invalid input: nothing was checked (exit 2). */
+export declare class RebaseCheckInputError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+/** One manifest patch, read and digest-checked, with its typed hints. */
+export interface CheckPatch {
+    readonly name: string;
+    readonly file: string;
+    readonly path: string;
+    readonly sha256: string;
+    readonly base: string;
+    readonly adds: readonly string[];
+    readonly appliesAfter: readonly string[];
+    readonly provides: readonly ProvidesHint[];
+    readonly retireWhen?: string;
+}
+/**
+ * A manifest `provides` entry, typed: an environment variable, a host
+ * subcommand or a code symbol can be looked for in the target tree; prose
+ * cannot. Finding one is a hint, never proof of the capability.
+ */
+export type ProvidesHint = {
+    readonly kind: "env";
+    readonly text: string;
+    readonly search: string;
+} | {
+    readonly kind: "command";
+    readonly text: string;
+    readonly search: string;
+} | {
+    readonly kind: "symbol";
+    readonly text: string;
+    readonly search: string;
+} | {
+    readonly kind: "prose";
+    readonly text: string;
+};
+export declare function providesHint(text: string): ProvidesHint;
+/**
+ * The manifest's patches in application order: manifest order, every
+ * `appliesAfter` first. Each file's sha256 must match; an unknown dependency
+ * or a cycle is refused. `patchBase` checks the variants written for that
+ * commit (the manifest's `rebased` entries; default: the top-level ones, the
+ * lock's base); a selected patch without one is refused.
+ */
+export declare function checkPatchesFrom(manifest: Readonly<Record<string, HostPatchEntry>>, directory: string, names?: readonly string[], patchBase?: string): CheckPatch[];
+export type PatchStatus = "applied" | "applied-3way" | "upstreamed" | "conflicted" | "skipped";
+export interface PatchResult {
+    readonly name: string;
+    readonly file: string;
+    readonly sha256: string;
+    readonly appliesAfter: readonly string[];
+    readonly status: PatchStatus;
+    /** Applied only with a 3-way merge: the patch should be regenerated against the new base. */
+    readonly needsRefresh?: boolean;
+    /** Conflicted: the files that did not apply. */
+    readonly files?: readonly string[];
+    /** Conflicted: where the plain apply failed (`error: patch failed: <file>:<line>`). */
+    readonly hunks?: readonly {
+        readonly file: string;
+        readonly line?: number;
+    }[];
+    /** Skipped: the dependency that did not apply, and what happened to it. */
+    readonly skippedBecause?: {
+        readonly patch: string;
+        readonly status: PatchStatus;
+    };
+    /** --isolated: the patch alone on the target (information only; the chain decides). */
+    readonly alone?: Exclude<PatchStatus, "skipped">;
+}
+export interface RetirementRow {
+    readonly patch: string;
+    readonly adds: readonly string[];
+    readonly retireWhen?: string;
+    /** The patch's reverse applies on the target: its exact change is upstream. */
+    readonly upstreamed: boolean;
+    readonly hints: readonly (ProvidesHint & {
+        readonly found?: readonly string[];
+    })[];
+    /** The official build's `local-network-check` (only for a patch that adds localNetwork). */
+    readonly officialProbe?: OfficialProbe;
+    /** The official build's behavioural probe for the capability the patch adds (capability-probes.ts). */
+    readonly behaviour: RetirementBehaviour;
+    /** A retirement candidate only on behaviour: an exact upstreaming, hints or the check's echo alone never retire a patch. */
+    readonly verdict: "retirement candidate (the official build shows the behaviour)" | "keep (upstreamed exactly; the official build does not show the behaviour)" | "keep (the official build lacks the behaviour)" | "keep (hints only)" | "keep";
+}
+/** What the official build of the target did for one patch's capability. */
+export type RetirementBehaviour = {
+    readonly status: Exclude<Observed, "untested">;
+    readonly capability: string;
+    /** unsupported (absent or blocked on the official build, which claims nothing) or pass. */
+    readonly verdict: ProbeVerdict;
+    readonly detail: string;
+    readonly version: string;
+    readonly archiveSha256: string;
+} | {
+    readonly status: "untested";
+    readonly reason: string;
+};
+/** The official build's behavioural probes, as the caller ran them (it knows the cache and the sandbox). */
+export type OfficialBehaviour = {
+    readonly status: "probed";
+    readonly version: string;
+    readonly archiveSha256: string;
+    readonly report: HostProbeReport;
+} | {
+    readonly status: "untested";
+    readonly reason: string;
+};
+export type OfficialProbe = {
+    readonly status: "provides";
+    readonly version: string;
+    readonly binary: string;
+    readonly archiveSha256: string;
+} | {
+    readonly status: "absent";
+    readonly version: string;
+    readonly binary: string;
+    readonly archiveSha256: string;
+    readonly detail: string;
+} | {
+    readonly status: "untested";
+    readonly reason: string;
+};
+export interface RebaseCheckReport {
+    readonly schemaVersion: 1;
+    readonly repository: string;
+    readonly target: {
+        readonly requested: string;
+        readonly commit: string;
+        readonly label: string;
+        readonly tag?: string;
+        readonly version?: string;
+    };
+    readonly patchedBase: string;
+    /** Whether the patches were applied on their recorded base first (3-way preimages available). */
+    readonly primed: boolean;
+    readonly source: {
+        readonly kind: "repo" | "mirror";
+        readonly path: string;
+    };
+    readonly patches: readonly PatchResult[];
+    readonly summary: Readonly<Record<PatchStatus, number>>;
+    /** Patches that applied only with a 3-way merge: exit 0, but each should be regenerated against the target. */
+    readonly needsRefresh: readonly string[];
+    /** "<patch> no longer applies to <label>" and the other lines of the text report. */
+    readonly messages: readonly string[];
+    readonly retirement: readonly RetirementRow[];
+    readonly scratchRemoved: boolean;
+    readonly exitCode: 0 | 1;
+}
+export interface RebaseCheckOptions {
+    readonly commands: CommandRunner;
+    /**
+     * Where the commits come from. `repo`: a local clone, only read. `mirror`: the adapter's own bare
+     * cache repository, fetched from `url` first (the only step that uses the network).
+     */
+    readonly source: {
+        readonly kind: "repo";
+        readonly path: string;
+    } | {
+        readonly kind: "mirror";
+        readonly path: string;
+        readonly url: string;
+    };
+    readonly target: {
+        readonly requested: string;
+        readonly commit: string;
+        readonly label: string;
+        readonly tag?: string;
+        readonly version?: string;
+    };
+    readonly repository: string;
+    readonly patches: readonly CheckPatch[];
+    /** An absolute directory; the scratch repository is created inside and removed afterwards. */
+    readonly scratchParent: string;
+    readonly isolated?: boolean;
+    /** The official build's local-network probe, decided by the caller (it knows the cache). */
+    readonly officialProbe?: () => Promise<OfficialProbe>;
+    /** The official build's behavioural capability probes (G4), decided by the caller. */
+    readonly officialBehaviour?: () => Promise<OfficialBehaviour>;
+    readonly signal?: AbortSignal;
+    /** Per git command (default 120 s); a mirror fetch gets `fetchTimeoutMs` (default 600 s). */
+    readonly timeoutMs?: number;
+    readonly fetchTimeoutMs?: number;
+    readonly log?: (line: string) => void;
+}
+/** The failed-hunk locations and files named in `git apply --check` output. */
+export declare function applyFailures(stderr: string): {
+    files: string[];
+    hunks: {
+        file: string;
+        line?: number;
+    }[];
+};
+export declare function checkPatchesOnto(options: RebaseCheckOptions): Promise<RebaseCheckReport>;
+/** One patch's behaviour row from the official build's probes: the capability it adds, as observed there. */
+export declare function retirementBehaviour(patch: Pick<CheckPatch, "adds">, official: OfficialBehaviour | undefined): RetirementBehaviour;
+/** The report as text: one line per patch, then the G4 rows. */
+export declare function rebaseCheckText(report: RebaseCheckReport): string;
+/**
+ * The official build's `local-network-check` with a loopback routing file,
+ * which starts no session: exit 0 echoing the routing means the official build
+ * now provides local networking (a retirement candidate for local-network);
+ * anything else means it does not. The binary must be a digest-verified copy.
+ */
+export declare function probeOfficialLocalNetwork(options: {
+    readonly commands: CommandRunner;
+    readonly binary: string;
+    readonly version: string;
+    readonly archiveSha256: string;
+    readonly scratchParent: string;
+    readonly signal?: AbortSignal;
+}): Promise<OfficialProbe>;

package/adapters/host/truapi-cli/src/rebase-check.js

@@ -0,0 +1,366 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { HostNetworkRoutes } from "@parity/product-lab/domain";
+import { NoPatchForBaseError, patchVariant } from "./patch-manifest.js";
+import { echoesRouting, truapiCliNetworkConfig } from "./network-config.js";
+export class RebaseCheckInputError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "RebaseCheckInputError";
+    }
+}
+export function providesHint(text) {
+    if (/^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/.test(text))
+        return { kind: "env", text, search: text };
+    const command = /^truapi-host ([a-z][a-z0-9-]*)$/.exec(text);
+    if (command)
+        return { kind: "command", text, search: command[1] };
+    if (/^[A-Za-z_]\w*(::[A-Za-z_]\w*)+$/.test(text))
+        return { kind: "symbol", text, search: text.split("::").pop() };
+    return { kind: "prose", text };
+}
+export function checkPatchesFrom(manifest, directory, names, patchBase) {
+    const selected = names?.length ? names : Object.keys(manifest);
+    for (const name of selected)
+        if (!manifest[name])
+            throw new RebaseCheckInputError(`Unknown truapi-host patch ${name}. Known: ${Object.keys(manifest).join(", ")}`);
+    for (const [name, entry] of Object.entries(manifest))
+        for (const before of [entry, ...(entry.rebased ?? [])].flatMap((variant) => variant.appliesAfter ?? []))
+            if (!manifest[before])
+                throw new RebaseCheckInputError(`${name} applies after ${before}, which the manifest does not list`);
+    const order = [];
+    const visit = (name, trail) => {
+        if (order.includes(name))
+            return;
+        if (trail.includes(name))
+            throw new RebaseCheckInputError(`Patch order cycle: ${[...trail, name].join(" -> ")}`);
+        let variant;
+        try {
+            variant = patchVariant(name, manifest[name], patchBase);
+        }
+        catch (error) {
+            if (error instanceof NoPatchForBaseError)
+                throw new RebaseCheckInputError(error.message);
+            throw error;
+        }
+        for (const before of variant.appliesAfter ?? manifest[name].appliesAfter ?? [])
+            visit(before, [...trail, name]);
+        order.push(name);
+    };
+    for (const name of Object.keys(manifest))
+        if (selected.includes(name))
+            visit(name, []);
+    const patches = order.map((name) => {
+        const entry = manifest[name];
+        let variant;
+        try {
+            variant = patchVariant(name, entry, patchBase);
+        }
+        catch (error) {
+            if (error instanceof NoPatchForBaseError)
+                throw new RebaseCheckInputError(error.message);
+            throw error;
+        }
+        const path = join(directory, variant.file);
+        if (!existsSync(path))
+            throw new RebaseCheckInputError(`${variant.file} is missing from ${directory}`);
+        const sha256 = createHash("sha256").update(readFileSync(path)).digest("hex");
+        if (sha256 !== variant.sha256)
+            throw new RebaseCheckInputError(`${variant.file} differs from its manifest digest`);
+        return {
+            name,
+            file: variant.file,
+            path,
+            sha256,
+            base: variant.base,
+            adds: entry.adds,
+            appliesAfter: variant.appliesAfter ?? entry.appliesAfter ?? [],
+            provides: (entry.provides ?? []).map(providesHint),
+            ...(entry.retireWhen ? { retireWhen: entry.retireWhen } : {}),
+        };
+    });
+    if (new Set(patches.map((patch) => patch.base)).size > 1)
+        throw new RebaseCheckInputError("The patches were written against different bases");
+    return patches;
+}
+const COMMIT = /^[a-f0-9]{40}$/;
+const GIT_ENV = { GIT_TERMINAL_PROMPT: "0", GIT_PAGER: "cat", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" };
+export function applyFailures(stderr) {
+    const hunks = [];
+    const files = new Set();
+    for (const match of stderr.matchAll(/^error: patch failed: (.+):(\d+)$/gm)) {
+        hunks.push({ file: match[1], line: Number(match[2]) });
+        files.add(match[1]);
+    }
+    for (const match of stderr.matchAll(/^error: (.+?): (?:patch does not apply|does not exist in index|No such file or directory|already exists in (?:index|working directory))$/gm)) {
+        files.add(match[1]);
+        if (!hunks.some((hunk) => hunk.file === match[1]))
+            hunks.push({ file: match[1] });
+    }
+    return { files: [...files], hunks };
+}
+export async function checkPatchesOnto(options) {
+    const { commands, target, patches } = options;
+    const log = options.log ?? (() => { });
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    if (!COMMIT.test(target.commit))
+        throw new RebaseCheckInputError(`The target must be resolved to a full 40-character commit, not ${JSON.stringify(target.commit)}`);
+    if (!isAbsolute(options.scratchParent))
+        throw new RebaseCheckInputError("The scratch directory must be absolute");
+    if (!isAbsolute(options.source.path))
+        throw new RebaseCheckInputError("--repo must be an absolute path");
+    if (!patches.length)
+        throw new RebaseCheckInputError("No patches to check");
+    const base = patches[0].base;
+    const git = async (cwd, args, limit = timeoutMs) => commands.run({ command: "git", args, cwd, env: GIT_ENV, timeoutMs: limit, ...(options.signal ? { signal: options.signal } : {}) });
+    const must = async (cwd, args, what, limit = timeoutMs) => {
+        const result = await git(cwd, args, limit);
+        if (result.code !== 0)
+            throw new Error(`${what} failed (git ${args.join(" ")}): ${result.stderr.trim() || result.stdout.trim()}`);
+        return result.stdout;
+    };
+    const has = async (cwd, commit) => (await git(cwd, ["cat-file", "-e", `${commit}^{commit}`])).code === 0;
+    const source = options.source.path;
+    if (options.source.kind === "mirror") {
+        mkdirSync(source, { recursive: true });
+        if (!existsSync(join(source, "HEAD")))
+            await must(source, ["init", "--quiet", "--bare"], "Creating the upstream mirror");
+        for (const commit of [target.commit, base]) {
+            if (await has(source, commit))
+                continue;
+            log(`fetching ${commit.slice(0, 12)} from ${options.source.url}`);
+            await must(source, ["fetch", "--quiet", "--no-tags", "--depth=1", options.source.url, `${commit}:refs/product-lab/${commit}`], `Fetching ${commit}`, options.fetchTimeoutMs ?? 600_000);
+        }
+    }
+    else if ((await git(source, ["rev-parse", "--git-dir"])).code !== 0)
+        throw new RebaseCheckInputError(`${source} is not a git repository`);
+    if (!(await has(source, target.commit)))
+        throw new RebaseCheckInputError(`Unknown ref: ${target.requested} (${target.commit}) is not in ${source}`);
+    const primable = await has(source, base);
+    mkdirSync(options.scratchParent, { recursive: true });
+    const scratch = mkdtempSync(join(options.scratchParent, "rebase-check-"));
+    const results = [];
+    const found = new Map();
+    let scratchRemoved = false;
+    let officialProbe;
+    let official;
+    try {
+        await must(scratch, ["init", "--quiet"], "Creating the scratch repository");
+        await must(scratch, ["fetch", "--quiet", "--no-tags", "--depth=1", "--upload-pack", "git -c uploadpack.allowAnySHA1InWant=true upload-pack", source, ...new Set([target.commit, ...(primable ? [base] : [])])], "Fetching the target into the scratch repository");
+        if (primable) {
+            await must(scratch, ["checkout", "--quiet", "--detach", base], "Checking out the patch base");
+            for (const patch of patches) {
+                const applied = await git(scratch, ["apply", "--index", "--whitespace=nowarn", patch.path]);
+                if (applied.code !== 0)
+                    throw new RebaseCheckInputError(`${patch.name} does not apply to its own recorded base ${base.slice(0, 12)}: ${applied.stderr.trim()}`);
+            }
+            await must(scratch, ["reset", "--quiet", "--hard", target.commit], "Checking out the target");
+        }
+        else {
+            log(`the patch base ${base.slice(0, 12)} is not in ${source}: 3-way applies of chained patches lack their preimages`);
+            await must(scratch, ["checkout", "--quiet", "--detach", target.commit], "Checking out the target");
+        }
+        await must(scratch, ["clean", "-fdqx"], "Cleaning the scratch tree");
+        const pristine = (await must(scratch, ["write-tree"], "Recording the target tree")).trim();
+        for (const patch of patches)
+            for (const hint of patch.provides) {
+                if (hint.kind === "prose" || found.has(hint.search))
+                    continue;
+                const grep = await git(scratch, ["grep", "-F", "-l", "-e", hint.search, target.commit]);
+                found.set(hint.search, grep.code === 0 ? grep.stdout.split("\n").filter(Boolean).map((line) => line.replace(`${target.commit}:`, "")) : []);
+            }
+        const restore = async (tree) => {
+            await must(scratch, ["read-tree", "--reset", "-u", tree], "Restoring the tree");
+            await must(scratch, ["clean", "-fdqx"], "Cleaning the scratch tree");
+        };
+        const unmerged = async () => (await must(scratch, ["diff", "--name-only", "--diff-filter=U"], "Listing conflicts")).split("\n").filter(Boolean);
+        const attempt = async (patch, tree) => {
+            const check = await git(scratch, ["apply", "--check", "--index", "--verbose", patch.path]);
+            if (check.code === 0) {
+                await must(scratch, ["apply", "--index", "--whitespace=nowarn", patch.path], `Applying ${patch.name}`);
+                return { status: "applied" };
+            }
+            if ((await git(scratch, ["apply", "--check", "--index", "--reverse", patch.path])).code === 0)
+                return { status: "upstreamed" };
+            const threeWay = await git(scratch, ["apply", "--3way", "--index", "--whitespace=nowarn", patch.path]);
+            const conflicts = await unmerged();
+            if (threeWay.code === 0 && !conflicts.length)
+                return { status: "applied-3way", needsRefresh: true };
+            const failures = applyFailures(check.stderr);
+            await restore(tree);
+            return { status: "conflicted", files: [...new Set([...conflicts, ...failures.files])].sort(), hunks: failures.hunks };
+        };
+        let tree = pristine;
+        for (const patch of patches) {
+            const blocked = patch.appliesAfter
+                .map((name) => results.find((result) => result.name === name))
+                .find((result) => !["applied", "applied-3way", "upstreamed"].includes(result.status));
+            const identity = { name: patch.name, file: patch.file, sha256: patch.sha256, appliesAfter: patch.appliesAfter };
+            if (blocked) {
+                results.push({ ...identity, status: "skipped", skippedBecause: { patch: blocked.name, status: blocked.status } });
+                continue;
+            }
+            const outcome = await attempt(patch, tree);
+            if (outcome.status === "applied" || outcome.status === "applied-3way")
+                tree = (await must(scratch, ["write-tree"], "Recording the tree")).trim();
+            results.push({ ...identity, ...outcome });
+            log(`${patch.name}: ${outcome.status}${outcome.needsRefresh ? " (needs refresh)" : ""}`);
+        }
+        if (options.isolated)
+            for (const [index, patch] of patches.entries()) {
+                await restore(pristine);
+                const alone = await attempt(patch, pristine);
+                results[index] = { ...results[index], alone: alone.status };
+            }
+        if (options.officialProbe && patches.some((patch) => patch.adds.includes("localNetwork")))
+            officialProbe = await options.officialProbe();
+        if (options.officialBehaviour)
+            official = await options.officialBehaviour();
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+        scratchRemoved = !existsSync(scratch);
+    }
+    const summary = { applied: 0, "applied-3way": 0, upstreamed: 0, conflicted: 0, skipped: 0 };
+    for (const result of results)
+        summary[result.status]++;
+    const label = target.label;
+    const messages = results.map((result) => {
+        switch (result.status) {
+            case "applied":
+                return `${result.name} applies to ${label}`;
+            case "applied-3way":
+                return `${result.name} applies to ${label} only with a 3-way merge: needs refresh`;
+            case "upstreamed":
+                return `${result.name} is already in ${label} (its reverse applies): upstreamed`;
+            case "conflicted":
+                return `${result.name} no longer applies to ${label} (${result.files.join(", ") || "no file named"})`;
+            case "skipped":
+                return `${result.name} not checked against ${label}: it applies after ${result.skippedBecause.patch}, which ${result.skippedBecause.status === "skipped" ? "was not checked" : "no longer applies"}`;
+        }
+    });
+    const retirement = patches.map((patch) => {
+        const upstreamed = results.find((result) => result.name === patch.name).status === "upstreamed";
+        const hints = patch.provides.map((hint) => (hint.kind === "prose" ? hint : { ...hint, found: found.get(hint.search) ?? [] }));
+        const probe = patch.adds.includes("localNetwork") ? (officialProbe ?? { status: "untested", reason: "no official probe was requested" }) : undefined;
+        const hinted = hints.some((hint) => "found" in hint && hint.found.length > 0);
+        const behaviour = retirementBehaviour(patch, official);
+        return {
+            patch: patch.name,
+            adds: patch.adds,
+            ...(patch.retireWhen ? { retireWhen: patch.retireWhen } : {}),
+            upstreamed,
+            hints,
+            ...(probe ? { officialProbe: probe } : {}),
+            behaviour,
+            verdict: behaviour.status === "provides"
+                ? "retirement candidate (the official build shows the behaviour)"
+                : upstreamed
+                    ? "keep (upstreamed exactly; the official build does not show the behaviour)"
+                    : behaviour.status === "absent"
+                        ? "keep (the official build lacks the behaviour)"
+                        : hinted
+                            ? "keep (hints only)"
+                            : "keep",
+        };
+    });
+    return {
+        schemaVersion: 1,
+        repository: options.repository,
+        target,
+        patchedBase: base,
+        primed: primable,
+        source: { kind: options.source.kind, path: source },
+        patches: results,
+        summary,
+        needsRefresh: results.filter((result) => result.needsRefresh).map((result) => result.name),
+        messages,
+        retirement,
+        scratchRemoved,
+        exitCode: summary.conflicted || summary.skipped ? 1 : 0,
+    };
+}
+export function retirementBehaviour(patch, official) {
+    if (!official)
+        return { status: "untested", reason: "no official behaviour probe was requested" };
+    if (official.status === "untested")
+        return official;
+    const capabilities = official.report.capabilities;
+    const missing = patch.adds.filter((capability) => !capabilities.some((result) => result.capability === capability));
+    if (missing.length)
+        return { status: "untested", reason: `no behavioural probe covers ${missing.join(", ")}` };
+    const covered = capabilities.filter((result) => patch.adds.includes(result.capability));
+    const found = covered.find((result) => result.observed !== "provides" || result.verdict !== "pass") ?? covered[0];
+    if (!found)
+        return { status: "untested", reason: `no behavioural probe covers ${patch.adds.join(", ") || "this patch"}` };
+    if (found.observed === "untested")
+        return { status: "untested", reason: found.detail };
+    return { status: found.observed, capability: found.capability, verdict: found.verdict, detail: found.detail, version: official.version, archiveSha256: official.archiveSha256 };
+}
+export function rebaseCheckText(report) {
+    const lines = [
+        `truapi-host patches onto ${report.target.label} (${report.target.commit.slice(0, 12)}; patches written on ${report.patchedBase.slice(0, 12)})`,
+        ...report.messages.map((message) => `  ${message}`),
+    ];
+    for (const result of report.patches) {
+        if (result.hunks?.length)
+            lines.push(`    ${result.name}: ${result.hunks.map((hunk) => `${hunk.file}${hunk.line ? `:${hunk.line}` : ""}`).join(", ")}`);
+        if (result.alone)
+            lines.push(`    ${result.name} alone (information only): ${result.alone}`);
+    }
+    if (report.needsRefresh.length)
+        lines.push(`  needs refresh (applied only with a 3-way merge): ${report.needsRefresh.join(", ")}`);
+    if (!report.primed)
+        lines.push("  note: the patch base was not in the source; 3-way applies of chained patches could not use their preimages");
+    lines.push("Retirement (G4): the official build's behaviour decides; hints and an exact upstreaming never retire a patch");
+    for (const row of report.retirement) {
+        const hints = row.hints.filter((hint) => hint.kind !== "prose").map((hint) => `${hint.text}: ${"found" in hint && hint.found.length ? `in ${hint.found.length} file(s)` : "absent"}`);
+        const probe = row.officialProbe ? `; official local-network-check: ${row.officialProbe.status}${row.officialProbe.status === "untested" ? ` (${row.officialProbe.reason})` : ` (${row.officialProbe.version})`}` : "";
+        const behaviour = row.behaviour.status === "untested"
+            ? `untested (${row.behaviour.reason})`
+            : `${row.behaviour.status}, ${row.behaviour.verdict} on official ${row.behaviour.version} (${row.behaviour.detail})`;
+        lines.push(`  ${row.patch}: ${row.verdict}; behaviour ${behaviour}${hints.length ? `; hints ${hints.join(", ")}` : ""}${probe}`);
+    }
+    lines.push(`exit ${report.exitCode}${report.scratchRemoved ? "" : `; scratch repository NOT removed`}`);
+    return lines.join("\n");
+}
+export async function probeOfficialLocalNetwork(options) {
+    const genesis = (n) => `0x${n.toString(16).padStart(2, "0").repeat(32)}`;
+    const routes = HostNetworkRoutes.from({
+        network: "paseo-next-v2",
+        namespace: "paseo",
+        chains: {
+            people: { ws: "ws://127.0.0.1:9", genesis: genesis(1) },
+            "asset-hub": { ws: "ws://127.0.0.1:9", genesis: genesis(2) },
+            bulletin: { ws: "ws://127.0.0.1:9", genesis: genesis(3) },
+        },
+        services: { "identity-backend": "http://127.0.0.1:9" },
+    });
+    mkdirSync(options.scratchParent, { recursive: true });
+    const directory = mkdtempSync(join(options.scratchParent, "official-probe-"));
+    try {
+        const config = join(directory, "host-network.json");
+        writeFileSync(config, JSON.stringify(truapiCliNetworkConfig(routes)), { mode: 0o600 });
+        const result = await options.commands.run({
+            command: options.binary,
+            args: ["local-network-check", "--network", routes.network],
+            env: { HOST_CLI_LOCAL_NETWORK_CONFIG: config },
+            timeoutMs: 15_000,
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        const facts = { version: options.version, binary: options.binary, archiveSha256: options.archiveSha256 };
+        if (result.code === 0) {
+            if (echoesRouting(result.stdout, routes))
+                return { status: "provides", ...facts };
+            return { status: "absent", ...facts, detail: "exit 0 without the complete routing echo" };
+        }
+        return { status: "absent", ...facts, detail: (result.stderr.trim() || result.stdout.trim()).split("\n")[0] ?? `exit ${result.code}` };
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+}

package/adapters/host/truapi-cli/src/resolved-host.d.ts

@@ -0,0 +1,23 @@
+import { LockedComponent, VersionResolution, type ResolvedComponent } from "@parity/product-lab/domain/versions";
+/** The component id of this host in a lock or resolution. */
+export declare const TRUAPI_CLI_COMPONENT = "host:truapi-cli";
+/** An official release and the archive digest acquisition must match. */
+export interface ResolvedHostVersion {
+    /** `x.y.z` of the `@parity/truapi@x.y.z` release. */
+    version: string;
+    /** The archive target this digest is for (`aarch64-apple-darwin`). */
+    target: string;
+    /** sha256 of `truapi-host-<version>-<target>.tar.gz`, lower-case hex. */
+    archiveSha256: string;
+    /** Where the digest comes from, for messages and provenance. */
+    source: string;
+}
+/**
+ * The host version `entry` names for `target`: `entry` is the
+ * `host:truapi-cli` lock entry, the resolved component, or a whole
+ * resolution. Refused (VersionError `invalid`) unless it is an official
+ * host-rust-core release (`@parity/truapi@<version>`) with a sha256 for
+ * `target`: a git-built host is built locally by patch set, and an entry
+ * without this platform's digest cannot be verified.
+ */
+export declare function resolvedHostVersion(entry: LockedComponent | ResolvedComponent | VersionResolution, target: string): ResolvedHostVersion;

package/adapters/host/truapi-cli/src/resolved-host.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ComponentId, LockedComponent, VersionError, VersionResolution } from "@parity/product-lab/domain/versions";
+import { insideProductLabCheckout } from "./checkout.js";
+export const TRUAPI_CLI_COMPONENT = "host:truapi-cli";
+const RELEASE_REPOSITORY = "paritytech/host-rust-core";
+export function resolvedHostVersion(entry, target) {
+    const component = entry instanceof VersionResolution
+        ? entry.get(TRUAPI_CLI_COMPONENT)?.component
+        : entry instanceof LockedComponent
+            ? entry
+            : entry.component;
+    if (!component)
+        throw new VersionError("invalid", `The resolution has no ${TRUAPI_CLI_COMPONENT}`);
+    if (!component.id.equals(ComponentId.parse(TRUAPI_CLI_COMPONENT)))
+        throw new VersionError("invalid", `${component.id} is not ${TRUAPI_CLI_COMPONENT}`);
+    const { source, version } = component;
+    const where = `${TRUAPI_CLI_COMPONENT} ${version}`;
+    if (source.type !== "github-release")
+        throw new VersionError("invalid", `${where} comes from a ${source.type} source; the truAPI CLI host acquires official releases only${insideProductLabCheckout() ? " (a patched or git-built host is built locally: product-lab host build)" : ""}`);
+    if (source.repository !== RELEASE_REPOSITORY)
+        throw new VersionError("invalid", `${where} names ${source.repository}; official truAPI CLI releases come from ${RELEASE_REPOSITORY}`);
+    if (!/^\d+\.\d+\.\d+$/.test(version) || source.tag !== `@parity/truapi@${version}`)
+        throw new VersionError("invalid", `${where}: the release tag ${source.tag} is not @parity/truapi@<x.y.z> for this version`);
+    const digest = component.digests[`archive:${target}`];
+    if (!digest)
+        throw new VersionError("invalid", `${where} records no archive digest for ${target} (archive:${target}), so the download cannot be verified`);
+    if (digest.algorithm !== "sha256")
+        throw new VersionError("invalid", `${where}: archive:${target} is ${digest.algorithm}, not sha256`);
+    return { version, target, archiveSha256: digest.hex, source: `${TRUAPI_CLI_COMPONENT} ${version} (${component.selector}, release ${source.tag})` };
+}