@papillon6814/copi 0.1.0 → 0.2.0

package/dist/src/names.d.ts

@@ -0,0 +1,11 @@
+import type { StoredCatalog } from "./types.ts";
+export interface NameConflict {
+    namespace: "item" | "group";
+    key: string;
+    ids: string[];
+}
+export declare function nameKey(name: string): string;
+export declare function findNameConflicts(catalog: StoredCatalog): NameConflict[];
+export declare function assertNoNameConflicts(catalog: StoredCatalog): void;
+/** A rename during resolution may touch a conflict member only, and must use a free name. */
+export declare function assertNameAvailable(catalog: StoredCatalog, namespace: "item" | "group", name: string, id?: string): void;

package/dist/src/names.js

@@ -0,0 +1,40 @@
+import { foldCaseUnicode17 } from "./unicode-case-folding.js";
+export function nameKey(name) {
+    const key = foldCaseUnicode17(name.trim().normalize("NFKC")).normalize("NFKC");
+    if (key.length === 0)
+        throw new Error("Name must not be empty after normalization.");
+    return key;
+}
+export function findNameConflicts(catalog) {
+    const conflicts = [];
+    for (const namespace of ["item", "group"]) {
+        const keys = new Map();
+        for (const entry of namespace === "item" ? catalog.items : catalog.groups) {
+            const key = nameKey(entry.name);
+            const ids = keys.get(key) ?? [];
+            ids.push(entry.id);
+            keys.set(key, ids);
+        }
+        for (const [key, ids] of keys)
+            if (ids.length > 1)
+                conflicts.push({ namespace, key, ids });
+    }
+    return conflicts;
+}
+export function assertNoNameConflicts(catalog) {
+    if (findNameConflicts(catalog).length > 0) {
+        throw new Error("Duplicate names in the copi library. Only listing, masked viewing, and name conflict resolution are allowed; resolve the names interactively with copi groups.");
+    }
+}
+/** A rename during resolution may touch a conflict member only, and must use a free name. */
+export function assertNameAvailable(catalog, namespace, name, id) {
+    const key = nameKey(name);
+    const conflicts = findNameConflicts(catalog);
+    if (conflicts.length > 0 && !conflicts.some((conflict) => conflict.namespace === namespace && conflict.ids.includes(id ?? ""))) {
+        assertNoNameConflicts(catalog);
+    }
+    const entries = namespace === "item" ? catalog.items : catalog.groups;
+    if (entries.some((entry) => entry.id !== id && nameKey(entry.name) === key)) {
+        throw new Error(`Duplicate ${namespace} name; choose a unique display name.`);
+    }
+}

package/dist/src/native-placement.d.ts

@@ -0,0 +1,16 @@
+export interface RenameExclusiveReviewedSourceInput {
+    libraryDir: string;
+    stagePath: string;
+    targetPath: string;
+    expectedStage: {
+        dev: string;
+        ino: string;
+    };
+    expectedParent: {
+        dev: string;
+        ino: string;
+    };
+}
+/** @internal Read-only capability check that must precede native-placement transaction writes. */
+export declare function preflightNativeSourcePlacement(libraryDir: string): Promise<void>;
+export declare function renameExclusiveReviewedSource(input: RenameExclusiveReviewedSourceInput): Promise<void>;

package/dist/src/native-placement.js

@@ -0,0 +1,557 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { spawn } from "node:child_process";
+import { access, lstat, open, realpath } from "node:fs/promises";
+import { constants as osConstants } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const protocolVersion = 1;
+const helperName = "rename-exclusive-arm64";
+const maxRecordBytes = 64 * 1024;
+const maxHelperBytes = 16 * 1024 * 1024;
+const maxManifestBytes = 64 * 1024;
+const helperTimeoutMs = 30_000;
+const uint64Maximum = 18446744073709551615n;
+const arm64CpuType = 0x0100000c;
+const machO64Magic = 0xfeedfacf;
+const machOExecuteFileType = 2;
+const lcMain = 0x80000028;
+const lcUnixThread = 0x5;
+class NativePlacementError extends Error {
+    code;
+    errno;
+    constructor(code, message, errno) {
+        super(message);
+        this.name = "NativePlacementError";
+        this.code = code;
+        this.errno = errno;
+    }
+}
+const knownErrnos = new Set(Object.values(osConstants.errno).filter(Number.isInteger));
+function placementError(code, errno) {
+    const message = code === "filesystem-error" || code === "post-placement-identity-mismatch"
+        ? "Native source placement failed in the filesystem."
+        : code === "invalid-input"
+            ? "Native source-placement input is invalid."
+            : code === "unsupported-platform"
+                ? "Native source placement requires macOS arm64."
+                : code === "unsafe-path"
+                    ? "Native source-placement paths are unsafe."
+                    : code === "stage-identity-mismatch"
+                        ? "The reviewed stage identity no longer matches."
+                        : code === "parent-identity-mismatch"
+                            ? "The reviewed target parent identity no longer matches."
+                            : code === "helper-unavailable"
+                                ? "The required packaged native source-placement helper is unavailable."
+                                : code === "helper-invalid"
+                                    ? "The packaged native source-placement helper is invalid."
+                                    : code === "helper-spawn-failed"
+                                        ? "The native source-placement helper could not be started."
+                                        : code === "helper-timeout"
+                                            ? "The native source-placement helper timed out."
+                                            : code === "helper-output-limit"
+                                                ? "The native source-placement helper exceeded the output limit."
+                                                : code === "helper-protocol-invalid"
+                                                    ? "The native source-placement helper returned an invalid protocol response."
+                                                    : code === "helper-signal"
+                                                        ? "The native source-placement helper terminated by signal."
+                                                        : code === "destination-exists"
+                                                            ? "The source placement destination already exists."
+                                                            : code === "unsupported-volume"
+                                                                ? "The volume does not support exclusive native source placement."
+                                                                : "The native source-placement request was rejected.";
+    return new NativePlacementError(code, message, errno);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(record, keys) {
+    const actual = Object.keys(record).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+function hasRequiredKeys(record, keys) {
+    return keys.every((key) => Object.hasOwn(record, key));
+}
+function asNativePlacementError(error, fallback) {
+    if (error instanceof NativePlacementError)
+        return error;
+    return placementError(fallback, systemErrno(error));
+}
+function systemErrno(error) {
+    if (!isRecord(error))
+        return undefined;
+    const numericErrno = error.errno;
+    if (typeof numericErrno === "number" && Number.isInteger(numericErrno))
+        return Math.abs(numericErrno);
+    const code = error.code;
+    if (typeof code === "string") {
+        const errno = osConstants.errno[code];
+        if (typeof errno === "number")
+            return errno;
+    }
+    return undefined;
+}
+function parseIdentity(value) {
+    if (!isRecord(value) || !hasExactKeys(value, ["dev", "ino"]))
+        return undefined;
+    const parseValue = (part) => {
+        if (typeof part !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(part))
+            return undefined;
+        try {
+            const parsed = BigInt(part);
+            return parsed <= uint64Maximum ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const dev = parseValue(value.dev);
+    const ino = parseValue(value.ino);
+    if (dev === undefined || ino === undefined)
+        return undefined;
+    return { dev, ino };
+}
+function isCanonicalAbsolutePath(value) {
+    if (typeof value !== "string" || value.length === 0 || !path.isAbsolute(value) || value.includes("\0") || value.includes("\\")) {
+        return false;
+    }
+    if (path.resolve(value) !== value || Buffer.from(value, "utf8").toString("utf8") !== value)
+        return false;
+    return true;
+}
+function strictlyContains(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function isWithin(root, candidate) {
+    return root === candidate || strictlyContains(root, candidate);
+}
+function inputRequestBytes(input) {
+    const request = {
+        protocolVersion,
+        operation: "renameExclusiveReviewedSource",
+        libraryDir: input.libraryDir,
+        stagePath: input.stagePath,
+        targetPath: input.targetPath,
+        expectedStage: input.expectedStage,
+        expectedParent: input.expectedParent,
+    };
+    const bytes = Buffer.from(`${JSON.stringify(request)}\n`, "utf8");
+    if (bytes.length > maxRecordBytes)
+        throw placementError("invalid-input");
+    return bytes;
+}
+function validateInput(value) {
+    if (!isRecord(value) || !hasRequiredKeys(value, ["libraryDir", "stagePath", "targetPath", "expectedStage", "expectedParent"])) {
+        throw placementError("invalid-input");
+    }
+    if (!isCanonicalAbsolutePath(value.libraryDir) || value.libraryDir === path.parse(value.libraryDir).root ||
+        !isCanonicalAbsolutePath(value.stagePath) || !isCanonicalAbsolutePath(value.targetPath)) {
+        throw placementError("unsafe-path");
+    }
+    const stageIdentity = parseIdentity(value.expectedStage);
+    const parentIdentity = parseIdentity(value.expectedParent);
+    if (stageIdentity === undefined || parentIdentity === undefined)
+        throw placementError("invalid-input");
+    if (!strictlyContains(value.libraryDir, value.stagePath) || !strictlyContains(value.libraryDir, value.targetPath) ||
+        !isWithin(value.libraryDir, path.dirname(value.stagePath)) || !isWithin(value.libraryDir, path.dirname(value.targetPath)) ||
+        value.stagePath === value.targetPath || strictlyContains(value.stagePath, value.targetPath) ||
+        strictlyContains(value.targetPath, value.stagePath)) {
+        throw placementError("unsafe-path");
+    }
+    const validated = {
+        libraryDir: value.libraryDir,
+        stagePath: value.stagePath,
+        targetPath: value.targetPath,
+        expectedStage: { dev: stageIdentity.dev.toString(), ino: stageIdentity.ino.toString() },
+        expectedParent: { dev: parentIdentity.dev.toString(), ino: parentIdentity.ino.toString() },
+    };
+    return {
+        ...validated,
+        stageIdentity,
+        parentIdentity,
+        requestBytes: inputRequestBytes(validated),
+    };
+}
+function assertSupportedNativePlatform() {
+    if (process.platform !== "darwin" || process.arch !== "arm64")
+        throw placementError("unsupported-platform");
+}
+async function pathInfoWithoutSymlinks(pathname) {
+    const root = path.parse(pathname).root;
+    let current = root;
+    let info = await lstat(current, { bigint: true });
+    if (info.isSymbolicLink() || !info.isDirectory())
+        throw placementError("unsafe-path");
+    const components = pathname.slice(root.length).split(path.sep).filter((component) => component.length > 0);
+    for (const [index, component] of components.entries()) {
+        current = path.join(current, component);
+        info = await lstat(current, { bigint: true });
+        if (info.isSymbolicLink())
+            throw placementError("unsafe-path");
+        if (index < components.length - 1 && !info.isDirectory())
+            throw placementError("unsafe-path");
+    }
+    return info;
+}
+async function assertLibraryAndFilesystem(input) {
+    let rootInfo;
+    let stageInfo;
+    let stageParentInfo;
+    let targetParentInfo;
+    try {
+        rootInfo = await pathInfoWithoutSymlinks(input.libraryDir);
+        stageInfo = await pathInfoWithoutSymlinks(input.stagePath);
+        stageParentInfo = await pathInfoWithoutSymlinks(path.dirname(input.stagePath));
+        targetParentInfo = await pathInfoWithoutSymlinks(path.dirname(input.targetPath));
+    }
+    catch (error) {
+        if (error instanceof NativePlacementError)
+            throw error;
+        const errno = systemErrno(error);
+        const code = errno === osConstants.errno.ENOENT
+            ? (error instanceof Error && error.message.includes(input.stagePath) ? "stage-identity-mismatch" : "unsafe-path")
+            : "unsafe-path";
+        throw placementError(code, errno);
+    }
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+        throw placementError("unsafe-path");
+    if (await realpath(input.libraryDir).catch(() => "") !== input.libraryDir)
+        throw placementError("unsafe-path");
+    if (!stageInfo.isFile() && !stageInfo.isDirectory())
+        throw placementError("stage-identity-mismatch");
+    if (!stageParentInfo.isDirectory() || !targetParentInfo.isDirectory())
+        throw placementError("unsafe-path");
+    if (stageInfo.dev !== input.stageIdentity.dev || stageInfo.ino !== input.stageIdentity.ino) {
+        throw placementError("stage-identity-mismatch", osConstants.errno.ESTALE);
+    }
+    if (targetParentInfo.dev !== input.parentIdentity.dev || targetParentInfo.ino !== input.parentIdentity.ino) {
+        throw placementError("parent-identity-mismatch", osConstants.errno.ESTALE);
+    }
+    if (rootInfo.dev !== stageInfo.dev || rootInfo.dev !== stageParentInfo.dev || rootInfo.dev !== targetParentInfo.dev) {
+        throw placementError("filesystem-error", osConstants.errno.EXDEV);
+    }
+}
+function packagePaths() {
+    let modulePath;
+    try {
+        modulePath = fileURLToPath(import.meta.url);
+    }
+    catch {
+        throw placementError("helper-invalid");
+    }
+    const moduleDirectory = path.dirname(modulePath);
+    if (path.basename(moduleDirectory) !== "src")
+        throw placementError("helper-invalid");
+    const parentDirectory = path.dirname(moduleDirectory);
+    const packageRoot = path.basename(parentDirectory) === "dist" ? path.dirname(parentDirectory) : parentDirectory;
+    return {
+        packageRoot,
+        helperPath: path.join(packageRoot, "dist", "native", helperName),
+        manifestPath: path.join(packageRoot, "dist", "native", `${helperName}.manifest.json`),
+    };
+}
+function sameFileIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+async function readCheckedPackageFile(filePath, maxBytes) {
+    const before = await pathInfoWithoutSymlinks(filePath);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(maxBytes))
+        throw placementError("helper-invalid");
+    const handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile() || !sameFileIdentity(before, opened) || opened.size > BigInt(maxBytes)) {
+            throw placementError("helper-invalid");
+        }
+        const bytes = await handle.readFile();
+        const [afterHandle, afterPath] = await Promise.all([handle.stat({ bigint: true }), pathInfoWithoutSymlinks(filePath)]);
+        if (!sameFileIdentity(opened, afterHandle) || !sameFileIdentity(opened, afterPath) || !afterPath.isFile()) {
+            throw placementError("helper-invalid");
+        }
+        return { bytes, mode: Number(opened.mode & 511n) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function hasArm64ExecutableMachO(bytes) {
+    if (bytes.length < 32 || bytes.readUInt32LE(0) !== machO64Magic || bytes.readInt32LE(4) !== arm64CpuType ||
+        bytes.readUInt32LE(12) !== machOExecuteFileType)
+        return false;
+    const commandCount = bytes.readUInt32LE(16);
+    const commandBytes = bytes.readUInt32LE(20);
+    const commandEnd = 32 + commandBytes;
+    if (commandCount === 0 || commandCount > 65_536 || commandEnd > bytes.length)
+        return false;
+    let offset = 32;
+    let hasExecutableEntry = false;
+    for (let index = 0; index < commandCount; index += 1) {
+        if (offset + 8 > commandEnd)
+            return false;
+        const command = bytes.readUInt32LE(offset);
+        const size = bytes.readUInt32LE(offset + 4);
+        if (size < 8 || size % 4 !== 0 || offset + size > commandEnd)
+            return false;
+        if (command === lcMain || command === lcUnixThread)
+            hasExecutableEntry = true;
+        offset += size;
+    }
+    return offset === commandEnd && hasExecutableEntry;
+}
+async function loadPackagedHelper() {
+    const paths = packagePaths();
+    let artifact;
+    try {
+        artifact = await readCheckedPackageFile(paths.helperPath, maxHelperBytes);
+    }
+    catch (error) {
+        if (systemErrno(error) === osConstants.errno.ENOENT)
+            throw placementError("helper-unavailable");
+        throw placementError("helper-invalid");
+    }
+    if ((artifact.mode & 0o111) === 0 || !hasArm64ExecutableMachO(artifact.bytes))
+        throw placementError("helper-invalid");
+    try {
+        await access(paths.helperPath, fsConstants.X_OK);
+    }
+    catch {
+        throw placementError("helper-invalid");
+    }
+    let manifestFile;
+    try {
+        manifestFile = await readCheckedPackageFile(paths.manifestPath, maxManifestBytes);
+    }
+    catch {
+        throw placementError("helper-invalid");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestFile.bytes.toString("utf8"));
+    }
+    catch {
+        throw placementError("helper-invalid");
+    }
+    if (!isRecord(manifest) || manifest.artifact !== helperName || manifest.architecture !== "arm64" ||
+        manifest.platform !== "darwin" || manifest.protocolVersion !== protocolVersion ||
+        typeof manifest.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(manifest.sha256)) {
+        throw placementError("helper-invalid");
+    }
+    const digest = createHash("sha256").update(artifact.bytes).digest("hex");
+    if (digest !== manifest.sha256)
+        throw placementError("helper-invalid");
+    return paths;
+}
+async function nearestExistingVolumeDirectory(libraryDir) {
+    const requested = path.resolve(libraryDir);
+    if (requested === path.parse(requested).root)
+        throw placementError("unsafe-path");
+    let current = requested;
+    while (true) {
+        let info;
+        try {
+            info = await lstat(current, { bigint: true });
+        }
+        catch (error) {
+            if (systemErrno(error) === osConstants.errno.ENOENT) {
+                const parent = path.dirname(current);
+                if (parent === current)
+                    throw placementError("filesystem-error", osConstants.errno.ENOENT);
+                current = parent;
+                continue;
+            }
+            throw asNativePlacementError(error, "filesystem-error");
+        }
+        if (current === requested && info.isSymbolicLink())
+            throw placementError("unsafe-path");
+        if (!info.isDirectory() && !info.isSymbolicLink())
+            throw placementError("unsafe-path");
+        let canonical;
+        try {
+            canonical = await realpath(current);
+        }
+        catch (error) {
+            throw asNativePlacementError(error, "unsafe-path");
+        }
+        let canonicalInfo;
+        try {
+            canonicalInfo = await lstat(canonical, { bigint: true });
+        }
+        catch (error) {
+            throw asNativePlacementError(error, "filesystem-error");
+        }
+        if (!canonicalInfo.isDirectory() || canonicalInfo.isSymbolicLink() || await realpath(canonical).catch(() => "") !== canonical) {
+            throw placementError("unsafe-path");
+        }
+        return canonical;
+    }
+}
+function nativeErrnoMatches(code, errno) {
+    const errnos = osConstants.errno;
+    if (!Number.isInteger(errno) || errno <= 0 || !knownErrnos.has(errno))
+        return false;
+    switch (code) {
+        case "destination-exists":
+            return errno === errnos.EEXIST;
+        case "unsupported-volume":
+            return errno === errnos.ENOTSUP || errno === errnos.EOPNOTSUPP;
+        case "invalid-request":
+        case "unsupported-protocol":
+            return errno === errnos.EINVAL;
+        case "unsafe-path":
+            return errno === errnos.EINVAL || errno === errnos.ENOTDIR || errno === errnos.ELOOP;
+        case "parent-identity-mismatch":
+            return errno === errnos.ESTALE;
+        case "stage-identity-mismatch":
+            return errno === errnos.ENOENT || errno === errnos.ESTALE;
+        case "filesystem-error":
+        case "post-placement-identity-mismatch":
+            return true;
+    }
+}
+function parseNativeRecord(bytes) {
+    if (bytes.length === 0 || bytes.length > maxRecordBytes || bytes[bytes.length - 1] !== 0x0a ||
+        bytes.includes(0x0d) || bytes.indexOf(0x0a) !== bytes.length - 1) {
+        throw placementError("helper-protocol-invalid");
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(bytes.subarray(0, bytes.length - 1).toString("utf8"));
+    }
+    catch {
+        throw placementError("helper-protocol-invalid");
+    }
+    if (!isRecord(decoded) || decoded.protocolVersion !== protocolVersion || typeof decoded.ok !== "boolean") {
+        throw placementError("helper-protocol-invalid");
+    }
+    if (decoded.ok) {
+        if (!hasExactKeys(decoded, ["protocolVersion", "ok"]))
+            throw placementError("helper-protocol-invalid");
+        return { protocolVersion: 1, ok: true };
+    }
+    if (!hasExactKeys(decoded, ["protocolVersion", "ok", "error"]) || !isRecord(decoded.error) ||
+        !hasExactKeys(decoded.error, ["code", "errno"]) || typeof decoded.error.code !== "string" ||
+        typeof decoded.error.errno !== "number" || !Number.isInteger(decoded.error.errno) ||
+        !nativeErrnoMatches(decoded.error.code, decoded.error.errno)) {
+        throw placementError("helper-protocol-invalid");
+    }
+    const code = decoded.error.code;
+    return { protocolVersion: 1, ok: false, error: { code, errno: decoded.error.errno } };
+}
+function terminate(child) {
+    if (child === undefined)
+        return;
+    try {
+        child.kill("SIGKILL");
+    }
+    catch {
+        // The caller already has a stable failure to report; child runtime text is intentionally discarded.
+    }
+}
+function runNativeHelper(paths, requestBytes, args = ["--protocol-version", "1"]) {
+    return new Promise((resolve, reject) => {
+        let child;
+        let settled = false;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        const stdout = [];
+        const startedAt = Date.now();
+        let timer;
+        const clearDeadline = () => clearTimeout(timer);
+        const rejectOnce = (error, killChild) => {
+            if (settled)
+                return;
+            settled = true;
+            clearDeadline();
+            if (killChild)
+                terminate(child);
+            reject(error);
+        };
+        const deadline = () => rejectOnce(placementError("helper-timeout"), true);
+        timer = setTimeout(deadline, helperTimeoutMs);
+        try {
+            child = spawn(paths.helperPath, [...args], {
+                cwd: paths.packageRoot,
+                shell: false,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch {
+            rejectOnce(placementError("helper-spawn-failed"), false);
+            return;
+        }
+        child.on("error", () => rejectOnce(placementError("helper-spawn-failed"), false));
+        child.stdin.on("error", () => rejectOnce(placementError("helper-protocol-invalid"), true));
+        child.stdout.on("error", () => rejectOnce(placementError("helper-protocol-invalid"), true));
+        child.stderr.on("error", () => rejectOnce(placementError("helper-protocol-invalid"), true));
+        child.stdout.on("data", (chunk) => {
+            if (settled)
+                return;
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > maxRecordBytes) {
+                rejectOnce(placementError("helper-output-limit"), true);
+                return;
+            }
+            stdout.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            if (settled)
+                return;
+            stderrBytes += chunk.length;
+            if (stderrBytes > maxRecordBytes)
+                rejectOnce(placementError("helper-output-limit"), true);
+        });
+        child.on("close", (exitCode, signal) => {
+            if (settled)
+                return;
+            clearDeadline();
+            if (Date.now() - startedAt >= helperTimeoutMs) {
+                rejectOnce(placementError("helper-timeout"), false);
+                return;
+            }
+            if (signal !== null) {
+                rejectOnce(placementError("helper-signal"), false);
+                return;
+            }
+            let response;
+            try {
+                response = parseNativeRecord(Buffer.concat(stdout, stdoutBytes));
+            }
+            catch (error) {
+                rejectOnce(asNativePlacementError(error, "helper-protocol-invalid"), false);
+                return;
+            }
+            if (response.ok) {
+                if (exitCode !== 0)
+                    rejectOnce(placementError("helper-protocol-invalid"), false);
+                else {
+                    settled = true;
+                    resolve();
+                }
+                return;
+            }
+            if (exitCode !== 1) {
+                rejectOnce(placementError("helper-protocol-invalid"), false);
+                return;
+            }
+            rejectOnce(placementError(response.error.code, response.error.errno), false);
+        });
+        if (requestBytes.length > 0)
+            child.stdin.end(requestBytes);
+    });
+}
+/** @internal Read-only capability check that must precede native-placement transaction writes. */
+export async function preflightNativeSourcePlacement(libraryDir) {
+    assertSupportedNativePlatform();
+    const volumeRoot = await nearestExistingVolumeDirectory(libraryDir);
+    const paths = await loadPackagedHelper();
+    await runNativeHelper(paths, Buffer.alloc(0), ["--check-exclusive-rename", volumeRoot]);
+}
+export async function renameExclusiveReviewedSource(input) {
+    const validated = validateInput(input);
+    assertSupportedNativePlatform();
+    await assertLibraryAndFilesystem(validated);
+    const paths = await loadPackagedHelper();
+    await runNativeHelper(paths, validated.requestBytes);
+}

package/dist/src/refresh.d.ts

@@ -0,0 +1,20 @@
+import { type DiscoveryOptions } from "./discovery.ts";
+import { type ChangeApproval, type SavedChangeView } from "./resource-mutations.ts";
+import type { Catalog, ResourceCandidate, SavedItem } from "./types.ts";
+declare const refreshBrand: unique symbol;
+export interface PreparedRefresh {
+    readonly [refreshBrand]: true;
+    readonly reviewId: string;
+}
+export interface RefreshView extends SavedChangeView {
+    readonly originalCatalog: Catalog;
+    readonly source: ResourceCandidate;
+}
+/** Metadata checks only. Never follows arbitrary links, including links above the selected boundary. */
+export declare function resolveRefreshPath(requested: string): Promise<string>;
+/** Call only after explicit discovery-root/scope consent; no implicit HOME or parent search. */
+export declare function discoverRefreshOrigin(item: SavedItem, options: DiscoveryOptions): Promise<ResourceCandidate | undefined>;
+export declare function prepareRefresh(libraryDir: string, itemId: string, source: ResourceCandidate): Promise<PreparedRefresh>;
+export declare function readRefresh(prepared: PreparedRefresh): RefreshView;
+export declare function commitRefresh(prepared: PreparedRefresh, approval: ChangeApproval): Promise<SavedItem>;
+export {};