modwright 0.1.1 → 0.1.3

package/dist/core/safety/restore.js

@@ -2,6 +2,13 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { copyFilePreservingMtime, readManifest, sha256File } from "./backup.js";
 import { isDirectory } from "../fsutil.js";
+function outsideConfinement(entries, roots) {
+    const fold = (p) => (process.platform === "win32" ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const folded = roots.map(fold);
+    return entries
+        .map((e) => e.originalPath)
+        .filter((p) => !folded.some((root) => isUnder(root, fold(p))));
+}
 export async function listBackups(backupRoot) {
     let entries;
     try {
@@ -86,6 +93,14 @@ export async function restoreBackup(backupDir, options = {}) {
         if (!("kind" in entry))
             backupFileFor(backupDir, entry.backupPath);
     }
+    if (options.confineTo) {
+        const outside = outsideConfinement(manifest.entries, options.confineTo);
+        if (outside.length > 0) {
+            const shown = outside.slice(0, 5).join(", ") + (outside.length > 5 ? ` and ${outside.length - 5} more` : "");
+            throw new Error(`safety: this backup would write outside the project and the game's mod roots (${shown}); nothing was restored. ` +
+                `Allowed: ${options.confineTo.join(", ")}. If the manifest is yours and the paths are right, pass allowOutsideRoots: true.`);
+        }
+    }
     if (mode === "dry-run") {
         const operations = [];
         for (const entry of manifest.entries) {
@@ -110,6 +125,7 @@ export async function restoreBackup(backupDir, options = {}) {
     const results = [];
     const locked = [];
     let stopped = false;
+    const commonRoot = commonAncestor(manifest.entries.filter((e) => !("kind" in e)).map((e) => path.dirname(e.originalPath)));
     for (const entry of manifest.entries) {
         if ("kind" in entry) {
             const op = { kind: "junction", path: entry.originalPath, target: entry.linkTarget };
@@ -141,6 +157,16 @@ export async function restoreBackup(backupDir, options = {}) {
             if (sha256 !== entry.sha256) {
                 throw new Error(`backup of ${entry.originalPath} is corrupted: manifest says sha256 ${entry.sha256}, file on disk hashes to ${sha256}`);
             }
+            const link = await linkAncestor(entry.originalPath, commonRoot);
+            if (link) {
+                results.push({
+                    op,
+                    status: "failed",
+                    error: `${link} is now a junction/symlink, so restoring ${entry.originalPath} would write through it into ${await fs.realpath(link).catch(() => "its target")}. ` +
+                        `Remove the link first (deploy --deployMode pak --unlink, or by hand) and run the restore again.`,
+                });
+                continue;
+            }
             await copyFilePreservingMtime(src, entry.originalPath);
             results.push({ op, status: "applied" });
         }
@@ -170,3 +196,39 @@ export async function restoreBackup(backupDir, options = {}) {
                 : "An integrity check failed before that file was restored; the backup itself is untouched, so fix the problem and retry."),
     };
 }
+function commonAncestor(dirs) {
+    if (dirs.length === 0)
+        return undefined;
+    let common = path.resolve(dirs[0]);
+    for (const dir of dirs.slice(1)) {
+        let candidate = path.resolve(dir);
+        while (candidate !== common && !isUnder(common, candidate)) {
+            const parent = path.dirname(common);
+            if (parent === common)
+                return undefined;
+            common = parent;
+        }
+    }
+    return common;
+}
+function isUnder(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+async function linkAncestor(file, stopAt) {
+    let dir = path.dirname(path.resolve(file));
+    for (;;) {
+        try {
+            if ((await fs.lstat(dir)).isSymbolicLink())
+                return dir;
+        }
+        catch {
+        }
+        if (stopAt === undefined || dir === stopAt || !isUnder(stopAt, dir))
+            return undefined;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}

package/dist/core/testplan/registry.js

@@ -262,7 +262,11 @@ const CP2077_PROBES = [
         summary: "Where an entity is. Attested for item objects; unverified for a sector-placed prop.",
         citation: "cp2077.entity.transform",
         paramsSchema: z.object({ entityRef: str() }).strict(),
-        evidence: "Observed in game: a test mod's own init.lua comment says its tag \"removes legacy dynamic cases from older experiments\" and the real case is a static sector prop, so GetTaggedIDs on it returned 0 twice at two locations — not a location miss. That tag marks legacy dev spawns only and is the wrong entry point for a sector-placed prop; a sector-placed prop needs a different probe mechanism, not just a re-run of this one. Stays unverified.",
+        evidence: "Observed in game: a test mod's own init.lua comment says its tag \"removes legacy dynamic cases from older experiments\" and the real case is a static sector prop, so GetTaggedIDs on it returned 0 twice at two locations — not a location miss. That tag marks legacy dev spawns only and is the wrong entry point for a sector-placed prop; a sector-placed prop needs a different probe mechanism, not just a re-run of this one. Stays unverified. " +
+            "RTTI (rayshader/cp2077-nativedb b5d29af, game 2.31): both calls are declared on entEntity itself — " +
+            "GetWorldPosition() -> Vector4, GetWorldOrientation() -> Quaternion — and a loot-container prop's entity class " +
+            "(LootContainerObjectAnimatedByTransform) reaches entEntity through gameLootContainerBase/gameObject/entGameEntity, " +
+            "so such a prop has both methods by inheritance. The methods were never in doubt; getting a handle to the prop is.",
     },
     {
         kind: "cp2077.entity.appearance",
@@ -273,6 +277,12 @@ const CP2077_PROBES = [
         summary: "Acceptance regression, differential: did the sector node's appearanceName resolve?",
         citation: "cp2077.entity.appearance",
         paramsSchema: z.object({ tag: str(), baselineId: str() }).strict(),
+        evidence: "Composite of cp2077.entity.tagged + .components + .transform against a baseline; blocked the same way " +
+            "cp2077.entity.tagged is for a sector-placed prop (its first step). RTTI (rayshader/cp2077-nativedb " +
+            "b5d29af, game 2.31): entEntity::GetCurrentAppearanceName() -> CName exists, inherited by loot-container " +
+            "props, and entIComponent::GetAppearanceName() -> CName exists per component. That is a direct read of the " +
+            "question this row asks (did appearanceName resolve?) and a smaller call than the composite, but no CET mod " +
+            "or wiki page calls it from Lua, so it is a candidate for the next live run, not a redesign of this row.",
     },
     {
         kind: "cp2077.tweakdb.record",
@@ -302,9 +312,48 @@ const CP2077_PROBES = [
         context: "cet",
         effect: "read",
         status: "unverified",
-        summary: "An interaction component is on the entity. The component name is not attested anywhere on disk.",
+        summary: "An interaction component is on the entity. The component name is per-entity: a loot-container template " +
+            "names it \"interactions\" (class gameinteractionsComponent); nothing calls it from Lua yet.",
         citation: "cp2077.interaction.present",
         paramsSchema: z.object({ entityRef: str() }).strict(),
+        evidence: "A loot-container entity template's components list { $type: gameinteractionsComponent, name: \"interactions\" } " +
+            "alongside inventory, scanning, workspotMapper, root, audioSound, vision, UI_Slots, GameplayRole, state_fxes and " +
+            "targeting. RTTI (rayshader/cp2077-nativedb b5d29af): gameinteractionsComponent -> entIPlacedComponent -> " +
+            "entIComponent; entEntity::FindComponentByName(componentName: CName) -> ref<entIComponent>; no generic " +
+            "enumerate-by-class call exists on entEntity/gameObject, so exact names stay the only path. A design-time " +
+            "template field is not an in-engine observation that the component resolves on the streamed instance: stays unverified.",
+    },
+    {
+        kind: "cp2077.entity.nearby",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "read",
+        status: "unverified",
+        summary: "Entities within a radius of an anchor entity (the player by default). filter \"npc\" (default) asks " +
+            "GetNPCsAroundObject; filter \"objects\" asks GetEntitiesAroundObject with an Obj_*-wide target search " +
+            "filter, the shape that could find a placed static prop.",
+        citation: "cp2077.entity.nearby",
+        paramsSchema: z
+            .object({
+            radius: z.number().positive(),
+            filter: z.enum(["npc", "objects"]).optional(),
+            entityRef: str().optional(),
+            tag: str().optional(),
+            index: z.number().int().positive().optional(),
+        })
+            .strict(),
+        evidence: "rayshader/cp2077-nativedb at b5d29af (v2.1.0, game 2.31; RTTI dumped by WopsS/RED4.RTTIDumper) classes.json: " +
+            "gameObject (parent entGameEntity) carries GetNPCsAroundObject(range: Float) -> array<ref<NPCPuppet>> and " +
+            "GetEntitiesAroundObject(range: Float, searchFilter: gameTargetSearchFilter) -> array<ref<entEntity>>; " +
+            "globals.json lists the filter constructors TSF_All/TSF_Any/TSF_Not/TSF_And/TSF_Or/TSF_NPC/TSF_EnemyNPC/" +
+            "TSF_Quickhackable and enums.json the mask members (TSFMV). No shipped CET mod or wiki page calls any of it, " +
+            "but CET's own source (yamashi/CyberEngineTweaks 9a8522f; knowledge facts cp2077.cet.*) pins the Lua side: " +
+            "globals are exposed bare and via Game.*, a returned struct passes back as a parameter, an undeclared enum value " +
+            "is coerced to 0 silently (so the handler builds the filter from declared members via Enum.new and TSF_Or, never " +
+            "an ORed mask), and array returns are 1-based tables with nil holes for null handles. What no source can supply " +
+            "is the live result: TSF_Any/TSF_Or semantics, whether a sector-placed prop is in the targeting set (a " +
+            "loot-container template does carry a gameTargetingComponent), and whether the game marks TSF_* isExec. Never " +
+            "run in game; stays unverified until a live run exercises it.",
     },
 ];
 export const PROBE_CATALOG = [...BG3_PROBES, ...CP2077_PROBES];

package/dist/core/text/converters/index.js

@@ -221,7 +221,7 @@ export async function convert(id, sourceAbs, destAbs, options = {}) {
         const plan = {
             purpose: `text convert ${entry.id}: ${path.basename(sourceAbs)} -> ${path.basename(destAbs)}`,
             operations: [planFile(destAbs, content)],
-            backupRoot: path.join(path.dirname(destAbs), ".modwright", "backups"),
+            ...(options.backupRoot ? { backupRoot: options.backupRoot } : {}),
         };
         const writeReport = await executePlan(plan, {
             mode: "apply",

package/dist/core/text/toolchain.js

@@ -1,5 +1,5 @@
 import { locateTool as coreLocateTool, TOOL_SPECS } from "../toolchain/index.js";
-export function defaultLocateTool(projectOverrides, probe = "all") {
+export function defaultLocateTool(projectOverrides, probe = "all", projectTrust) {
     return async (id) => {
         const spec = TOOL_SPECS.find((s) => s.id === id);
         if (!spec) {
@@ -11,6 +11,6 @@ export function defaultLocateTool(projectOverrides, probe = "all") {
                 hint: `"${id}" is not a known tool id in ModWright's toolchain catalog (see core/toolchain/specs.ts).`,
             };
         }
-        return coreLocateTool(spec, { projectOverrides, probe });
+        return coreLocateTool(spec, { projectOverrides, probe, ...(projectTrust ? { projectTrust } : {}) });
     };
 }

package/dist/core/toolchain/locate.js

@@ -1,9 +1,11 @@
 import { spawn } from "node:child_process";
+import { killTree } from "./run.js";
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { pathExists } from "../fsutil.js";
 import { userDataDir } from "../home.js";
+import { trustRefusal } from "../trust.js";
 import { loadUserConfig } from "../userconfig.js";
 import { toolEnvironment } from "./env.js";
 import { TOOL_SPECS } from "./specs.js";
@@ -145,7 +147,7 @@ async function runVersionProbe(execPath, versionArgs, versionPattern) {
             resolve(result);
         };
         const timer = setTimeout(() => {
-            child.kill();
+            killTree(child);
             finish(out);
         }, VERSION_PROBE_TIMEOUT_MS);
         const outDecoder = new StringDecoder("utf8");
@@ -227,6 +229,16 @@ export async function locateTool(spec, options = {}) {
         return found(fromEnv, "env");
     const override = options.projectOverrides?.[spec.id];
     const fromProject = override ? await resolveOverride(override, spec) : undefined;
+    if (fromProject && options.projectTrust && !options.projectTrust.trusted) {
+        return {
+            ...base,
+            found: false,
+            path: fromProject,
+            source: "project",
+            untrusted: true,
+            hint: trustRefusal(options.projectTrust.root, `its modwright.json points ${spec.id} at ${fromProject}`),
+        };
+    }
     if (fromProject)
         return found(fromProject, "project");
     const userTools = options.userTools === undefined ? (await loadUserConfig()).config.tools : options.userTools;

package/dist/core/toolchain/run.js

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { toolEnvironment } from "./env.js";
+import { DEFAULT_TOOL_TIMEOUT_MS } from "./types.js";
 const MAX_CAPTURE_BYTES = 1_000_000;
 const TRUNCATION_NOTE = "\n...[truncated]";
 export function assertAbsolute(paths) {
@@ -86,7 +87,7 @@ export function batchFileArgv(file, args, env = process.env) {
 export function isBatchFile(p) {
     return /\.(bat|cmd)$/i.test(p);
 }
-function killTree(child) {
+export function killTree(child) {
     if (process.platform === "win32" && child.pid !== undefined) {
         try {
             spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => child.kill());
@@ -151,7 +152,8 @@ export async function runTool(location, options) {
             resolve(spawnFailed(location, command, args, started, err));
             return;
         }
-        const timer = options.timeoutMs
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS;
+        const timer = timeoutMs
             ? setTimeout(() => {
                 if (settled)
                     return;
@@ -171,10 +173,10 @@ export async function runTool(location, options) {
                     stderrTruncated: stderrTruncated.value,
                     error: {
                         code: "timeout",
-                        message: `${location.label} did not finish within ${options.timeoutMs}ms.`,
+                        message: `${location.label} did not finish within ${timeoutMs}ms.`,
                     },
                 });
-            }, options.timeoutMs)
+            }, timeoutMs)
             : undefined;
         const cap = options.maxCaptureBytes ?? MAX_CAPTURE_BYTES;
         const stdoutDecoder = new StringDecoder("utf8");

package/dist/core/toolchain/types.js

@@ -1 +1 @@
-export {};
+export const DEFAULT_TOOL_TIMEOUT_MS = 30 * 60 * 1000;

package/dist/core/trust.js

@@ -0,0 +1,105 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { userConfigDir, userDataDir } from "./home.js";
+import { planFile, planMkdir } from "./safety/index.js";
+export const TRUST_SCHEMA_VERSION = 1;
+export const TRUST_ALL_ENV = "MODWRIGHT_TRUST_ALL";
+const trustEntrySchema = z.object({
+    root: z.string().min(1),
+    name: z.string().optional(),
+    trustedAt: z.string().optional(),
+});
+const trustFileSchema = z.object({
+    schemaVersion: z.literal(TRUST_SCHEMA_VERSION),
+    projects: z.record(trustEntrySchema).default({}),
+});
+export function trustFilePath() {
+    return path.join(userConfigDir(), "trusted-projects.json");
+}
+export function trustKey(root, platform = process.platform) {
+    const resolved = path.resolve(root).replace(/[\\/]+$/, "");
+    return platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+export async function loadTrust(file = trustFilePath()) {
+    const empty = { schemaVersion: TRUST_SCHEMA_VERSION, projects: {} };
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (error) {
+        const missing = error.code === "ENOENT";
+        return { trust: empty, file, exists: !missing, problems: missing ? [] : [`${file} could not be read: ${error.message}`] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^/, ""));
+    }
+    catch (error) {
+        return { trust: empty, file, exists: true, problems: [`${file} is not valid JSON (${error.message}); no project is trusted until it is fixed.`] };
+    }
+    const parsed = trustFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        return { trust: empty, file, exists: true, problems: [`${file} does not match schemaVersion ${TRUST_SCHEMA_VERSION} (${issues}); no project is trusted until it is fixed.`] };
+    }
+    return { trust: parsed.data, file, exists: true, problems: [] };
+}
+export async function isProjectTrusted(root, options = {}) {
+    if ((options.env ?? process.env)[TRUST_ALL_ENV] === "1")
+        return true;
+    const loaded = await loadTrust(options.file);
+    return trustKey(root) in loaded.trust.projects;
+}
+export function projectTrustNeeds(project) {
+    const toolchain = Object.keys(project.toolchain ?? {});
+    const exec = [];
+    (project.build?.steps ?? []).forEach((step, i) => {
+        if (typeof step === "string" || step.step !== "exec")
+            return;
+        exec.push(step.id ? `"${step.id}" (${step.command})` : `#${i} (${step.command})`);
+    });
+    return { toolchain, exec };
+}
+export function trustRefusal(root, what) {
+    return (`${root} is not a trusted project, and ${what}. ModWright runs a project's own executables and commands only after ` +
+        `you trust it once on this machine. Read its modwright.json first, then: check_toolchain action=trust projectPath=${JSON.stringify(root)} mode=apply. ` +
+        `(${TRUST_ALL_ENV}=1 trusts every project, for CI.)`);
+}
+export function describeNeeds(needs) {
+    const parts = [];
+    if (needs.exec.length > 0)
+        parts.push(`its build runs exec step(s) ${needs.exec.join(", ")}`);
+    if (needs.toolchain.length > 0)
+        parts.push(`its modwright.json overrides the tool path(s) for ${needs.toolchain.join(", ")}`);
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
+export async function planTrust(action, root, name, options = {}) {
+    const file = options.file ?? trustFilePath();
+    const loaded = await loadTrust(file);
+    if (loaded.problems.length > 0)
+        return { ok: false, error: `${loaded.problems.join(" ")} Fix or remove ${file} before changing it through ModWright.` };
+    const key = trustKey(root);
+    const previous = loaded.trust.projects[key];
+    const write = (trust, purpose) => ({
+        purpose,
+        operations: [planMkdir(path.dirname(file)), planFile(file, JSON.stringify(trust, null, 2) + "\n")],
+        backupRoot: path.join(userDataDir(), "backups"),
+    });
+    if (action === "untrust") {
+        if (!previous)
+            return { ok: false, error: `${root} is not in ${file}; nothing to untrust.` };
+        const { [key]: _dropped, ...rest } = loaded.trust.projects;
+        return { ok: true, action, root: path.resolve(root), file, plan: write({ ...loaded.trust, projects: rest }, `stop trusting ${root}`), previous };
+    }
+    const entry = { root: path.resolve(root), ...(name ? { name } : {}), trustedAt: (options.now ?? (() => new Date()))().toISOString() };
+    return {
+        ok: true,
+        action,
+        root: entry.root,
+        file,
+        plan: write({ ...loaded.trust, projects: { ...loaded.trust.projects, [key]: entry } }, `trust ${root} to run its toolchain overrides and exec steps`),
+        entry,
+        ...(previous ? { previous } : {}),
+    };
+}

package/dist/core/writes/index.js

@@ -0,0 +1,206 @@
+import { listMods } from "../mods.js";
+const VALUE_CHARS = 200;
+export function shortValue(value) {
+    if (value === undefined)
+        return undefined;
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    if (text === undefined)
+        return undefined;
+    if (text.length <= VALUE_CHARS)
+        return value;
+    return `${text.slice(0, VALUE_CHARS)}…`;
+}
+export async function collectWrites(surface, install, options = {}) {
+    const collection = {
+        writers: [],
+        coverage: { modsScanned: 0, writesFound: 0, rootsScanned: [], errors: [], unitNotes: [] },
+    };
+    if (!surface.extractWrites)
+        return collection;
+    const listOptions = { fileLimit: 20000 };
+    if (options.rootIds)
+        listOptions.rootIds = options.rootIds;
+    const { mods, roots } = await listMods(surface, install, listOptions);
+    const rootById = new Map(roots.map((r) => [r.id, r]));
+    const scannedRoots = new Set();
+    const byWriter = new Map();
+    const scanned = new Set();
+    for (const mod of mods) {
+        const root = rootById.get(mod.rootId);
+        if (!root)
+            continue;
+        let extraction;
+        try {
+            extraction = await surface.extractWrites(mod, root, install);
+        }
+        catch (error) {
+            collection.coverage.errors.push({ writerId: mod.id, file: mod.path, error: error.message });
+            continue;
+        }
+        if (!extraction)
+            continue;
+        scannedRoots.add(root.id);
+        if (extraction.writes.length === 0)
+            scanned.add(mod.id);
+        if (extraction.unitNote && !collection.coverage.unitNotes.includes(extraction.unitNote)) {
+            collection.coverage.unitNotes.push(extraction.unitNote);
+        }
+        for (const err of extraction.errors)
+            collection.coverage.errors.push({ writerId: mod.id, ...err });
+        for (const write of extraction.writes) {
+            const writerId = write.unit ? `${mod.id}/${write.unit}` : mod.id;
+            scanned.add(writerId);
+            let writer = byWriter.get(writerId);
+            if (!writer) {
+                writer = { writerId, name: write.unit ?? mod.name, rootId: mod.rootId, writes: [] };
+                const state = write.unit ? extraction.unitStates?.[write.unit] : undefined;
+                const inactive = state?.inactive ?? extraction.inactive;
+                const identity = state?.identity ?? extraction.identity;
+                if (inactive)
+                    writer.inactive = inactive;
+                if (identity)
+                    writer.identity = identity;
+                byWriter.set(writerId, writer);
+            }
+            writer.writes.push(write);
+            collection.coverage.writesFound++;
+        }
+    }
+    collection.writers = [...byWriter.values()];
+    collection.coverage.modsScanned = scanned.size;
+    const inactive = collection.writers.filter((w) => w.inactive).length;
+    if (inactive > 0)
+        collection.coverage.inactiveWriters = inactive;
+    collection.coverage.rootsScanned = [...scannedRoots];
+    return collection;
+}
+function groupByKey(collection, keep) {
+    const byKey = new Map();
+    for (const writer of collection.writers) {
+        for (const write of writer.writes) {
+            if (!keep(write))
+                continue;
+            const k = write.key.toLowerCase();
+            let entry = byKey.get(k);
+            if (!entry) {
+                entry = { key: write.key, keyKind: write.keyKind, contested: false, writers: [] };
+                byKey.set(k, entry);
+            }
+            const row = {
+                writerId: writer.writerId,
+                name: writer.name,
+                op: write.op,
+                file: write.file,
+                certainty: write.certainty,
+            };
+            const value = shortValue(write.value);
+            if (value !== undefined)
+                row.value = value;
+            if (write.line !== undefined)
+                row.line = write.line;
+            if (write.condition !== undefined)
+                row.condition = write.condition;
+            if (writer.inactive)
+                row.inactive = writer.inactive;
+            if (writer.identity)
+                row.identity = writer.identity;
+            entry.writers.push(row);
+        }
+    }
+    for (const entry of byKey.values()) {
+        const live = entry.writers.filter((w) => !w.inactive);
+        const writers = new Set(live.map((w) => w.identity ?? w.writerId));
+        if (writers.size < 2)
+            continue;
+        if (new Set(live.map((w) => JSON.stringify([w.op, w.value]))).size === 1) {
+            entry.agree = true;
+            continue;
+        }
+        if (live.every((w) => w.op === "append" || w.op === "remove")) {
+            const items = (op) => new Set(live.filter((w) => w.op === op).flatMap((w) => (Array.isArray(w.value) ? w.value : [w.value])).map((v) => JSON.stringify(v)));
+            const appended = items("append");
+            entry.contested = [...items("remove")].some((v) => appended.has(v));
+            continue;
+        }
+        entry.contested = true;
+    }
+    return byKey;
+}
+export function whoTouches(collection, query, limit = 50) {
+    const q = query.trim().toLowerCase();
+    const all = groupByKey(collection, () => true);
+    const pick = (matchedBy, keys) => {
+        keys.sort((a, b) => Number(b.contested) - Number(a.contested) || a.key.localeCompare(b.key));
+        const result = { query, matchedBy, keys: keys.slice(0, limit) };
+        if (keys.length > limit)
+            result.omittedKeys = keys.length - limit;
+        return result;
+    };
+    const exact = all.get(q);
+    if (exact) {
+        const under = [...all.entries()].filter(([k]) => k !== q && isUnder(k, q)).map(([, v]) => v);
+        return pick("exact", [exact, ...under]);
+    }
+    const prefixed = [...all.entries()].filter(([k]) => isUnder(k, q)).map(([, v]) => v);
+    if (prefixed.length > 0)
+        return pick("prefix", prefixed);
+    const containing = [...all.entries()].filter(([k]) => k.includes(q)).map(([, v]) => v);
+    if (containing.length > 0)
+        return pick("substring", containing);
+    return { query, matchedBy: "none", keys: [] };
+}
+function isUnder(key, parent) {
+    if (!key.startsWith(parent) || key.length === parent.length)
+        return false;
+    const next = key[parent.length];
+    return next === "." || next === "#" || next === "/";
+}
+export function whatTouches(collection, modQuery, limit = 100) {
+    const q = modQuery.trim().toLowerCase();
+    const exact = collection.writers.filter((w) => w.writerId.toLowerCase() === q || w.name.toLowerCase() === q);
+    const matches = exact.length > 0 ? exact : collection.writers.filter((w) => w.writerId.toLowerCase().includes(q) || w.name.toLowerCase().includes(q));
+    const byKey = groupByKey(collection, () => true);
+    return matches.map((writer) => {
+        const sharedWith = [];
+        const seen = new Set();
+        for (const write of writer.writes) {
+            const k = write.key.toLowerCase();
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            const entry = byKey.get(k);
+            if (!entry?.contested)
+                continue;
+            const others = [...new Set(entry.writers.filter((w) => w.writerId !== writer.writerId).map((w) => w.name))];
+            if (others.length > 0)
+                sharedWith.push({ key: entry.key, others });
+        }
+        const summary = {
+            writerId: writer.writerId,
+            name: writer.name,
+            rootId: writer.rootId,
+            writeCount: writer.writes.length,
+            sharedWith,
+            writes: writer.writes.slice(0, limit).map((w) => ({ ...w, value: shortValue(w.value) })),
+        };
+        if (writer.writes.length > limit)
+            summary.omittedWrites = writer.writes.length - limit;
+        return summary;
+    });
+}
+export function duplicateCopies(collection) {
+    const byIdentity = new Map();
+    for (const writer of collection.writers) {
+        if (!writer.identity || writer.inactive)
+            continue;
+        const names = byIdentity.get(writer.identity) ?? [];
+        names.push(writer.name);
+        byIdentity.set(writer.identity, names);
+    }
+    return [...byIdentity].filter(([, names]) => names.length > 1).map(([identity, writers]) => ({ identity, writers: writers.sort() }));
+}
+export function contestedKeys(collection, limit = 100) {
+    const keys = [...groupByKey(collection, () => true).values()].filter((k) => k.contested);
+    keys.sort((a, b) => new Set(b.writers.map((w) => w.writerId)).size - new Set(a.writers.map((w) => w.writerId)).size || a.key.localeCompare(b.key));
+    return { total: keys.length, keys: keys.slice(0, limit) };
+}