@nowcrew/daemon 0.6.19 → 0.6.21

package/dist/project-skills/runtime-root-store.js

@@ -0,0 +1,722 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, opendir, readFile, readlink, readdir, rm, stat, } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { durableDirectorySync } from "../atomic-private-write.js";
+import { AtomicNoReplaceRenameError, atomicRenameNoReplace, probeAtomicNoReplaceRenameReadiness, } from "../atomic-no-replace-rename.js";
+import { DirectoryProjectionError, isManagedDirectoryProjectionCopy, projectDirectory, } from "../directory-projection.js";
+import { DirectoryProjectionPublicationError, mapDirectoryProjectionFinalTarget, } from "../directory-projection-publication.js";
+import { readExactDirectoryIdentity, sameExactDirectoryIdentity, } from "../directory-projection-identity.js";
+import { ProjectSkillRuntimeStoreError, createProjectSkillRuntimeRootManifest, createProjectSkillRuntimeRootRecord, isCanonicalProjectSkillRuntimeRootId, parseProjectSkillRuntimeRootManifest, } from "./runtime-root-domain.js";
+import { ProjectSkillProjectionStateError, normalizeProjectSkillResolutionRecords, } from "./projection-state-domain.js";
+import { checkpointRuntimeRootNextSequence, reconstructRuntimeRootState, } from "./runtime-root-state-index.js";
+import { captureResolvedProjectSkillSourceIdentity, sameResolvedProjectSkillSourceIdentity, } from "./runtime-root-source-identity.js";
+const STORE_DIRECTORY_NAME = "project-skill-runtime";
+const ROOTS_DIRECTORY_NAME = "runtime-roots";
+const LEASES_DIRECTORY_NAME = "leases";
+const STATE_INDEX_DIRECTORY_NAME = "state-index";
+const STATE_FILE_NAME = "state.json";
+const MANIFEST_FILE_NAME = "MANIFEST.json";
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_RUNTIME_ROOT_ENTRIES = 2_048;
+const STAGING_NAME = /^\.([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})-next-([A-Za-z0-9-]{1,128})$/u;
+const GC_QUARANTINE_NAME = /^\.gc-[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+/** Stable path owner seam shared by the Runtime-root store and its garbage collector. */
+export const projectSkillRuntimeRootDirectory = (agentRoot, platform = process.platform) => (platform === "win32" ? win32 : posix).join(agentRoot, ".crew", STORE_DIRECTORY_NAME, ROOTS_DIRECTORY_NAME);
+const codeOf = (error) => error.code;
+const isMissing = (error) => codeOf(error) === "ENOENT";
+const isExisting = (error) => codeOf(error) === "EEXIST";
+const fail = (code) => { throw new ProjectSkillRuntimeStoreError(code); };
+const ownedByCurrentUser = (uid) => process.getuid === undefined || uid === BigInt(process.getuid());
+const mapStoreError = (error) => {
+    if (error instanceof ProjectSkillRuntimeStoreError)
+        throw error;
+    if (error instanceof DirectoryProjectionError) {
+        if (error.code === "directory_projection_limit_exceeded") {
+            return fail("skill_projection_runtime_store_limit_exceeded");
+        }
+        if (error.code === "directory_projection_artifact_unmanaged"
+            || error.code === "directory_projection_target_unmanaged") {
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+        return fail("skill_projection_failed");
+    }
+    if (error instanceof DirectoryProjectionPublicationError) {
+        return fail("skill_projection_failed");
+    }
+    if (error instanceof AtomicNoReplaceRenameError) {
+        return fail("skill_projection_failed");
+    }
+    if (error instanceof ProjectSkillProjectionStateError) {
+        return fail("skill_projection_snapshot_corrupt");
+    }
+    return fail("skill_projection_failed");
+};
+const immutableDescriptor = (rootId, rootDirectory, path) => Object.freeze({
+    rootId,
+    rootDirectory,
+    codexSkillRoot: path.join(rootDirectory, "runtime", ".claude", "skills"),
+    claudeAdditionalDirectory: path.join(rootDirectory, "runtime"),
+});
+const sameRecord = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const recordFromManifest = (manifest) => createProjectSkillRuntimeRootRecord({
+    rootId: manifest.rootId,
+    publishedSequence: manifest.publishedSequence,
+    materializationRevision: manifest.materializationRevision,
+    directoryIdentity: manifest.directoryIdentity,
+    bindingDigest: manifest.bindingDigest,
+    resolutionDigest: manifest.resolutionDigest,
+});
+const realOwnedDirectory = async (directory) => {
+    let info;
+    try {
+        info = await lstat(directory, { bigint: true });
+    }
+    catch {
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    if (!info.isDirectory() || info.isSymbolicLink() || !ownedByCurrentUser(info.uid)) {
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    return Object.freeze({
+        dev: String(info.dev),
+        ino: String(info.ino),
+        birthtimeNs: String(info.birthtimeNs),
+    });
+};
+const ensurePrivateDirectory = async (directory, parent, syncDirectory) => {
+    let created = false;
+    try {
+        await mkdir(directory, { mode: 0o700 });
+        created = true;
+    }
+    catch (error) {
+        if (!isExisting(error))
+            throw error;
+    }
+    await realOwnedDirectory(directory);
+    await chmod(directory, 0o700).catch(() => fail("skill_projection_runtime_root_unmanaged"));
+    if (created)
+        await syncDirectory(parent);
+};
+const boundedNames = async (directory) => {
+    let handle;
+    try {
+        handle = await opendir(directory);
+    }
+    catch {
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    const names = [];
+    try {
+        for (;;) {
+            const entry = await handle.read();
+            if (entry === null)
+                break;
+            names.push(entry.name);
+            if (names.length > MAX_RUNTIME_ROOT_ENTRIES) {
+                return fail("skill_projection_runtime_store_limit_exceeded");
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ProjectSkillRuntimeStoreError)
+            throw error;
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    return Object.freeze(names.sort());
+};
+const readBoundedOwnedFileSnapshot = async (filePath, maximumBytes) => {
+    let before;
+    try {
+        before = await lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    if (!before.isFile() || before.isSymbolicLink() || !ownedByCurrentUser(before.uid)
+        || before.size > BigInt(maximumBytes)) {
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    let handle = null;
+    try {
+        handle = await open(filePath, "r");
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile() || opened.isSymbolicLink() || !ownedByCurrentUser(opened.uid)
+            || opened.size > BigInt(maximumBytes)
+            || opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size) {
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+        const raw = await handle.readFile("utf8");
+        const after = await handle.stat({ bigint: true });
+        const pathAfter = await lstat(filePath, { bigint: true });
+        if (Buffer.byteLength(raw, "utf8") !== Number(after.size)
+            || after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size
+            || pathAfter.dev !== after.dev || pathAfter.ino !== after.ino || pathAfter.size !== after.size) {
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+        return Object.freeze({
+            identity: Object.freeze({
+                dev: after.dev,
+                ino: after.ino,
+                size: after.size,
+                mtimeNs: after.mtimeNs,
+            }),
+            raw,
+        });
+    }
+    catch (error) {
+        if (error instanceof ProjectSkillRuntimeStoreError)
+            throw error;
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+const readBoundedOwnedFile = async (filePath, maximumBytes) => (await readBoundedOwnedFileSnapshot(filePath, maximumBytes))?.raw ?? null;
+const writeNewDurableFile = async (filePath, raw, parent, syncDirectory) => {
+    let handle = null;
+    try {
+        handle = await open(filePath, "wx", 0o600);
+        await handle.writeFile(raw, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        await syncDirectory(parent);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+const sameDirectoryIdentity = (left, right) => left.dev === right.dev && left.ino === right.ino && left.birthtimeNs === right.birthtimeNs;
+const exactNames = async (directory, expected) => {
+    const actual = (await readdir(directory)).sort();
+    if (actual.length !== expected.length || actual.some((name, index) => name !== expected[index])) {
+        return fail("skill_projection_runtime_root_unmanaged");
+    }
+};
+const syncTree = async (root, path, syncDirectory) => {
+    const pending = [{ path: root, visited: false }];
+    let entries = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const info = await lstat(current.path);
+        if (info.isSymbolicLink())
+            continue;
+        if (info.isDirectory() && !current.visited) {
+            pending.push({ path: current.path, visited: true });
+            for (const name of await readdir(current.path)) {
+                entries += 1;
+                if (entries > MAX_RUNTIME_ROOT_ENTRIES * 100) {
+                    return fail("skill_projection_runtime_store_limit_exceeded");
+                }
+                pending.push({ path: path.join(current.path, name), visited: false });
+            }
+        }
+        else if (info.isDirectory()) {
+            await syncDirectory(current.path);
+        }
+        else if (info.isFile()) {
+            const handle = await open(current.path, "r");
+            try {
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        else {
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+    }
+};
+const makeTreeWritable = async (root, path) => {
+    const pending = [root];
+    let entries = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            continue;
+        if (!info.isDirectory()) {
+            if (!info.isFile())
+                return fail("skill_projection_runtime_root_unmanaged");
+            await chmod(current, 0o600);
+            continue;
+        }
+        await chmod(current, 0o700);
+        for (const name of await readdir(current)) {
+            entries += 1;
+            if (entries > MAX_RUNTIME_ROOT_ENTRIES * 100) {
+                return fail("skill_projection_runtime_store_limit_exceeded");
+            }
+            pending.push(path.join(current, name));
+        }
+    }
+};
+export function createProjectSkillRuntimeRootStore(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const path = platform === "win32" ? win32 : posix;
+    const syncDirectory = platform === "win32"
+        ? options.directorySync ?? (async () => undefined)
+        : options.directorySync ?? durableDirectorySync;
+    const project = options.project ?? projectDirectory;
+    const atomicRename = options.atomicRename ?? atomicRenameNoReplace;
+    const atomicRenamePrimitiveReadinessProbe = options.atomicRenamePrimitiveReadinessProbe
+        ?? probeAtomicNoReplaceRenameReadiness;
+    const stateIndexContext = (context) => Object.freeze({
+        indexDirectory: context.stateIndexDirectory,
+        statePath: context.statePath,
+        path,
+        syncDirectory,
+        atomicRename,
+        ...(options.stateIndexRandomId === undefined ? {} : { randomId: options.stateIndexRandomId }),
+        hooks: Object.freeze({
+            ...(options.afterLegacyStateValidatedBeforeImport === undefined ? {} : {
+                afterLegacyStateValidatedBeforeImport: options.afterLegacyStateValidatedBeforeImport,
+            }),
+            ...(options.afterStateIndexStagingDurableBeforeRename === undefined ? {} : {
+                afterStagingDurableBeforeRename: options.afterStateIndexStagingDurableBeforeRename,
+            }),
+            ...(options.afterStateIndexRenamedBeforeParentSync === undefined ? {} : {
+                afterRenamedBeforeParentSync: options.afterStateIndexRenamedBeforeParentSync,
+            }),
+            ...(options.afterStateIndexParentSyncedBeforeRevalidate === undefined ? {} : {
+                afterParentSyncedBeforeRevalidate: options.afterStateIndexParentSyncedBeforeRevalidate,
+            }),
+        }),
+    });
+    const contextFor = async (agentRoot) => {
+        await realOwnedDirectory(agentRoot);
+        const crewDirectory = path.join(agentRoot, ".crew");
+        const storeDirectory = path.join(crewDirectory, STORE_DIRECTORY_NAME);
+        const rootsDirectory = path.join(storeDirectory, ROOTS_DIRECTORY_NAME);
+        const leasesDirectory = path.join(storeDirectory, LEASES_DIRECTORY_NAME);
+        const stateIndexDirectory = path.join(storeDirectory, STATE_INDEX_DIRECTORY_NAME);
+        await ensurePrivateDirectory(crewDirectory, agentRoot, syncDirectory);
+        await ensurePrivateDirectory(storeDirectory, crewDirectory, syncDirectory);
+        await ensurePrivateDirectory(rootsDirectory, storeDirectory, syncDirectory);
+        await ensurePrivateDirectory(leasesDirectory, storeDirectory, syncDirectory);
+        await ensurePrivateDirectory(stateIndexDirectory, storeDirectory, syncDirectory);
+        const allowedStoreEntries = new Set([
+            ROOTS_DIRECTORY_NAME,
+            LEASES_DIRECTORY_NAME,
+            STATE_INDEX_DIRECTORY_NAME,
+            STATE_FILE_NAME,
+        ]);
+        for (const name of await boundedNames(storeDirectory)) {
+            if (!allowedStoreEntries.has(name)) {
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+        }
+        return Object.freeze({
+            storeDirectory,
+            rootsDirectory,
+            leasesDirectory,
+            stateIndexDirectory,
+            statePath: path.join(storeDirectory, STATE_FILE_NAME),
+        });
+    };
+    const validateProjectedChildren = async (rootDirectory, manifest, location) => {
+        await exactNames(rootDirectory, [MANIFEST_FILE_NAME, "runtime"]);
+        const runtime = path.join(rootDirectory, "runtime");
+        const claude = path.join(runtime, ".claude");
+        const skills = path.join(claude, "skills");
+        await realOwnedDirectory(runtime);
+        await realOwnedDirectory(claude);
+        await realOwnedDirectory(skills);
+        await exactNames(runtime, [".claude"]);
+        await exactNames(claude, ["skills"]);
+        const materialized = manifest.projectionModes.filter(({ mode }) => mode !== "missing");
+        const uniqueSkillNames = new Set(materialized.map(({ skillName }) => skillName));
+        if (uniqueSkillNames.size !== materialized.length)
+            return fail("skill_projection_snapshot_corrupt");
+        await exactNames(skills, [...uniqueSkillNames].sort());
+        for (const projection of manifest.projectionModes) {
+            const child = path.join(skills, projection.skillName);
+            if (projection.mode === "missing") {
+                try {
+                    await lstat(child);
+                    return fail("skill_projection_runtime_root_unmanaged");
+                }
+                catch (error) {
+                    if (error instanceof ProjectSkillRuntimeStoreError)
+                        throw error;
+                    if (!isMissing(error))
+                        return fail("skill_projection_runtime_root_unmanaged");
+                }
+                continue;
+            }
+            const info = await lstat(child, { bigint: true }).catch(() => fail("skill_projection_runtime_root_unmanaged"));
+            if (!ownedByCurrentUser(info.uid))
+                return fail("skill_projection_runtime_root_unmanaged");
+            if (projection.mode === "symlink" || projection.mode === "junction") {
+                if (!info.isSymbolicLink())
+                    return fail("skill_projection_runtime_root_unmanaged");
+                await readlink(child).catch(() => fail("skill_projection_runtime_root_unmanaged"));
+            }
+            else {
+                if (!info.isDirectory() || info.isSymbolicLink()) {
+                    return fail("skill_projection_runtime_root_unmanaged");
+                }
+                if (platform === "win32" || options.validateCopy !== undefined) {
+                    const finalChild = location === "final"
+                        ? child
+                        : mapDirectoryProjectionFinalTarget(child, {
+                            stagingRoot: rootDirectory,
+                            finalRoot: path.join(path.dirname(rootDirectory), manifest.rootId),
+                        }, platform);
+                    const managed = options.validateCopy === undefined
+                        ? location === "final"
+                            ? await isManagedDirectoryProjectionCopy(child, platform, options.projectionOptions)
+                            : await isManagedDirectoryProjectionCopy(child, platform, {
+                                ...options.projectionOptions,
+                                finalTarget: finalChild,
+                            })
+                        : await options.validateCopy(child, location === "final" ? undefined : finalChild);
+                    if (!managed)
+                        return fail("skill_projection_runtime_root_unmanaged");
+                }
+            }
+        }
+    };
+    const validateRoot = async (rootDirectory, expectedRootId, location) => {
+        const identity = await realOwnedDirectory(rootDirectory);
+        const raw = await readBoundedOwnedFile(path.join(rootDirectory, MANIFEST_FILE_NAME), MAX_MANIFEST_BYTES);
+        if (raw === null)
+            return fail("skill_projection_runtime_root_unmanaged");
+        let candidate;
+        try {
+            candidate = JSON.parse(raw);
+        }
+        catch {
+            return fail("skill_projection_snapshot_corrupt");
+        }
+        const manifest = parseProjectSkillRuntimeRootManifest(candidate);
+        if (manifest.rootId !== expectedRootId || !sameDirectoryIdentity(manifest.directoryIdentity, identity)) {
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+        await validateProjectedChildren(rootDirectory, manifest, location);
+        return Object.freeze({ path: rootDirectory, manifest, record: recordFromManifest(manifest) });
+    };
+    const scanRoots = async (context) => {
+        const finals = [];
+        const staging = [];
+        for (const name of await boundedNames(context.rootsDirectory)) {
+            const rootPath = path.join(context.rootsDirectory, name);
+            if (isCanonicalProjectSkillRuntimeRootId(name)) {
+                finals.push(await validateRoot(rootPath, name, "final"));
+                continue;
+            }
+            if (GC_QUARANTINE_NAME.test(name))
+                continue;
+            const match = STAGING_NAME.exec(name);
+            if (match !== null) {
+                staging.push(await validateRoot(rootPath, match[1], "staging"));
+                continue;
+            }
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+        return Object.freeze({ finals: Object.freeze(finals), staging: Object.freeze(staging) });
+    };
+    const recoverInternal = async (agentRoot) => {
+        const context = await contextFor(agentRoot);
+        const initial = await scanRoots(context);
+        const preflightRootIds = new Set();
+        const preflightSequences = new Set();
+        for (const root of [...initial.finals, ...initial.staging]) {
+            if (preflightRootIds.has(root.record.rootId)
+                || preflightSequences.has(root.record.publishedSequence)) {
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            preflightRootIds.add(root.record.rootId);
+            preflightSequences.add(root.record.publishedSequence);
+        }
+        const occupied = new Set(initial.finals.map(({ manifest }) => manifest.rootId));
+        for (const staged of [...initial.staging].sort((left, right) => left.record.publishedSequence - right.record.publishedSequence)) {
+            if (occupied.has(staged.manifest.rootId))
+                return fail("skill_projection_runtime_root_unmanaged");
+            const finalRoot = path.join(context.rootsDirectory, staged.manifest.rootId);
+            try {
+                await lstat(finalRoot);
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            catch (error) {
+                if (error instanceof ProjectSkillRuntimeStoreError)
+                    throw error;
+                if (!isMissing(error))
+                    return fail("skill_projection_runtime_root_unmanaged");
+            }
+            await options.beforeRecoveryRootRename?.(staged.path, finalRoot);
+            const publication = await atomicRename(staged.path, finalRoot);
+            if (publication !== "published")
+                return fail("skill_projection_runtime_root_unmanaged");
+            await syncDirectory(context.rootsDirectory);
+            await validateRoot(finalRoot, staged.manifest.rootId, "final");
+            occupied.add(staged.manifest.rootId);
+        }
+        const complete = await scanRoots(context);
+        if (complete.staging.length !== 0)
+            return fail("skill_projection_runtime_root_unmanaged");
+        const state = await reconstructRuntimeRootState(stateIndexContext(context), complete.finals.map(({ record }) => record));
+        return Object.freeze({ context, state });
+    };
+    const cleanupCreatedStaging = async (stagingRoot, expectedIdentity, rootsDirectory) => {
+        const current = await readExactDirectoryIdentity(stagingRoot);
+        if (current === null)
+            return;
+        if (!sameExactDirectoryIdentity(current, expectedIdentity)) {
+            return fail("skill_projection_runtime_root_unmanaged");
+        }
+        await makeTreeWritable(stagingRoot, path);
+        await rm(stagingRoot, { recursive: true, force: true });
+        await syncDirectory(rootsDirectory);
+    };
+    const recoverPublic = async (agentRoot) => {
+        try {
+            await recoverInternal(agentRoot);
+        }
+        catch (error) {
+            mapStoreError(error);
+        }
+    };
+    const probeNativePublicationPrimitiveReadiness = async () => {
+        if (platform !== "darwin" && platform !== "linux" && platform !== "win32")
+            return false;
+        try {
+            return await atomicRenamePrimitiveReadinessProbe() === true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const publish = async (input) => {
+        let injectedCrash;
+        let stagingRoot = null;
+        let stagingIdentity = null;
+        let renamed = false;
+        let preserveStaging = false;
+        try {
+            const { context, state } = await recoverInternal(input.agentRoot);
+            await options.afterInventoryLoadedBeforeRootStaging?.();
+            if (state.nextSequence >= Number.MAX_SAFE_INTEGER
+                || state.roots.length >= MAX_RUNTIME_ROOT_ENTRIES) {
+                return fail("skill_projection_runtime_store_limit_exceeded");
+            }
+            const resolutions = normalizeProjectSkillResolutionRecords(input.resolutions, platform);
+            const materializedNames = resolutions
+                .filter(({ mode }) => mode === "resolved")
+                .map(({ skillName }) => skillName);
+            if (new Set(materializedNames).size !== materializedNames.length) {
+                return fail("skill_projection_snapshot_corrupt");
+            }
+            const sourceIdentities = await Promise.all(resolutions.map((resolution) => resolution.mode === "missing"
+                ? null
+                : captureResolvedProjectSkillSourceIdentity(resolution.sourcePath, path)));
+            const randomId = options.randomId ?? randomUUID;
+            const rootId = randomId();
+            const operationNonce = randomId();
+            if (!isCanonicalProjectSkillRuntimeRootId(rootId)
+                || !/^[A-Za-z0-9-]{1,128}$/u.test(operationNonce)) {
+                return fail("skill_projection_snapshot_corrupt");
+            }
+            const finalRoot = path.join(context.rootsDirectory, rootId);
+            stagingRoot = path.join(context.rootsDirectory, `.${rootId}-next-${operationNonce}`);
+            for (const candidate of [finalRoot, stagingRoot]) {
+                try {
+                    await lstat(candidate);
+                    return fail("skill_projection_runtime_root_unmanaged");
+                }
+                catch (error) {
+                    if (error instanceof ProjectSkillRuntimeStoreError)
+                        throw error;
+                    if (!isMissing(error))
+                        return fail("skill_projection_runtime_root_unmanaged");
+                }
+            }
+            await mkdir(stagingRoot, { mode: 0o700 });
+            await chmod(stagingRoot, 0o700);
+            stagingIdentity = await realOwnedDirectory(stagingRoot);
+            await syncDirectory(context.rootsDirectory);
+            const runtime = path.join(stagingRoot, "runtime");
+            const claude = path.join(runtime, ".claude");
+            const skills = path.join(claude, "skills");
+            await mkdir(skills, { recursive: true, mode: 0o700 });
+            await chmod(runtime, 0o700);
+            await chmod(claude, 0o700);
+            await chmod(skills, 0o700);
+            const projectionModes = [];
+            for (const [index, resolution] of resolutions.entries()) {
+                if (resolution.mode === "missing") {
+                    projectionModes.push(Object.freeze({
+                        projectId: resolution.projectId,
+                        skillName: resolution.skillName,
+                        mode: "missing",
+                    }));
+                    continue;
+                }
+                const sourceIdentity = sourceIdentities[index];
+                if (sourceIdentity === null || sourceIdentity === undefined
+                    || !sameResolvedProjectSkillSourceIdentity(sourceIdentity, await captureResolvedProjectSkillSourceIdentity(resolution.sourcePath, path))) {
+                    return fail("skill_projection_failed");
+                }
+                const target = path.join(skills, resolution.skillName);
+                const finalTarget = mapDirectoryProjectionFinalTarget(target, { stagingRoot, finalRoot }, platform);
+                const result = await project(resolution.sourcePath, target, platform, {
+                    ...options.projectionOptions,
+                    finalTarget,
+                    ...(options.projectionRandomId === undefined
+                        ? {}
+                        : { randomId: options.projectionRandomId }),
+                    syncDirectory,
+                });
+                if (!sameResolvedProjectSkillSourceIdentity(sourceIdentity, await captureResolvedProjectSkillSourceIdentity(resolution.sourcePath, path))) {
+                    return fail("skill_projection_failed");
+                }
+                if ((result.mode === "symlink" || result.mode === "junction")
+                    && !(await stat(target)).isDirectory()) {
+                    return fail("skill_projection_failed");
+                }
+                if (!(await stat(path.join(target, "SKILL.md"))).isFile()) {
+                    return fail("skill_projection_failed");
+                }
+                projectionModes.push(Object.freeze({
+                    projectId: resolution.projectId,
+                    skillName: resolution.skillName,
+                    mode: result.mode,
+                }));
+            }
+            await syncTree(runtime, path, syncDirectory);
+            await options.beforeManifestWrite?.(stagingRoot);
+            const manifest = createProjectSkillRuntimeRootManifest({
+                rootId,
+                publishedSequence: state.nextSequence,
+                directoryIdentity: stagingIdentity,
+                bindingDigest: input.bindingDigest,
+                resolutionDigest: input.resolutionDigest,
+                projectionModes,
+            });
+            await writeNewDurableFile(path.join(stagingRoot, MANIFEST_FILE_NAME), `${JSON.stringify(manifest)}\n`, stagingRoot, syncDirectory);
+            await validateRoot(stagingRoot, rootId, "staging");
+            try {
+                await options.afterStagingDurableBeforeRename?.(Object.freeze({ stagingRoot, finalRoot }));
+            }
+            catch (error) {
+                injectedCrash = error;
+                throw error;
+            }
+            try {
+                await lstat(finalRoot);
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            catch (error) {
+                if (error instanceof ProjectSkillRuntimeStoreError)
+                    throw error;
+                if (!isMissing(error))
+                    return fail("skill_projection_runtime_root_unmanaged");
+            }
+            await options.beforeRootRename?.(stagingRoot, finalRoot);
+            const publication = await atomicRename(stagingRoot, finalRoot);
+            if (publication !== "published") {
+                preserveStaging = true;
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            renamed = true;
+            await syncDirectory(context.rootsDirectory);
+            const published = await validateRoot(finalRoot, rootId, "final");
+            try {
+                await options.afterRootRenamedBeforeInventoryRescan?.(Object.freeze({ stagingRoot, finalRoot }));
+            }
+            catch (error) {
+                injectedCrash = error;
+                throw error;
+            }
+            const complete = await scanRoots(context);
+            if (complete.staging.length !== 0) {
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            const rescanned = await reconstructRuntimeRootState(stateIndexContext(context), complete.finals.map(({ record }) => record));
+            const committed = rescanned.roots.find((record) => record.rootId === rootId);
+            if (committed === undefined || !sameRecord(committed, published.record)
+                || committed.publishedSequence !== state.nextSequence) {
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            return immutableDescriptor(rootId, finalRoot, path);
+        }
+        catch (error) {
+            if (!renamed && !preserveStaging
+                && stagingRoot !== null && stagingIdentity !== null && injectedCrash === undefined) {
+                await cleanupCreatedStaging(stagingRoot, stagingIdentity, path.dirname(stagingRoot)).catch(() => fail("skill_projection_runtime_root_unmanaged"));
+            }
+            if (error === injectedCrash)
+                throw error;
+            return mapStoreError(error);
+        }
+    };
+    const list = async (agentRoot) => {
+        try {
+            return (await recoverInternal(agentRoot)).state.roots;
+        }
+        catch (error) {
+            return mapStoreError(error);
+        }
+    };
+    const inspect = async (agentRoot, rootId) => {
+        try {
+            if (!isCanonicalProjectSkillRuntimeRootId(rootId)) {
+                return fail("skill_projection_snapshot_corrupt");
+            }
+            const { context, state } = await recoverInternal(agentRoot);
+            const rootDirectory = path.join(context.rootsDirectory, rootId);
+            const validated = await validateRoot(rootDirectory, rootId, "final");
+            const stateRecord = state.roots.find((record) => record.rootId === rootId);
+            if (stateRecord === undefined || !sameRecord(stateRecord, validated.record)) {
+                return fail("skill_projection_runtime_root_unmanaged");
+            }
+            return Object.freeze({
+                descriptor: immutableDescriptor(rootId, rootDirectory, path),
+                record: validated.record,
+                containsCopyProjection: validated.manifest.projectionModes.some(({ mode }) => mode === "copy"),
+            });
+        }
+        catch (error) {
+            return mapStoreError(error);
+        }
+    };
+    const load = async (agentRoot, rootId) => (await inspect(agentRoot, rootId)).descriptor;
+    const checkpointNextSequence = async (agentRoot) => {
+        try {
+            const { context, state } = await recoverInternal(agentRoot);
+            return await checkpointRuntimeRootNextSequence(stateIndexContext(context), state);
+        }
+        catch (error) {
+            return mapStoreError(error);
+        }
+    };
+    const checkpointNextSequenceForGc = async (agentRoot) => {
+        try {
+            const { context, state } = await recoverInternal(agentRoot);
+            return await checkpointRuntimeRootNextSequence(stateIndexContext(context), state, {
+                allowCapacityCompaction: true,
+            });
+        }
+        catch (error) {
+            return mapStoreError(error);
+        }
+    };
+    return Object.freeze({
+        probeNativePublicationPrimitiveReadiness,
+        recover: recoverPublic,
+        publish,
+        load,
+        inspect,
+        list,
+        checkpointNextSequence,
+        checkpointNextSequenceForGc,
+    });
+}