@nowcrew/daemon 0.6.16 → 0.6.17

package/dist/project-skills/projection-state-store.js

@@ -0,0 +1,841 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, link, lstat, mkdir, open, opendir, rename, rmdir, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+import { durableDirectorySync } from "../atomic-private-write.js";
+import { parseAppliedProjectSkillManifest, ProjectSkillProjectionStateError, } from "./projection-state-domain.js";
+const MANIFEST_FILE_NAME = "project-skills-v2.json";
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_CONSISTENT_READ_ATTEMPTS = 6;
+const MAX_STATE_DIRECTORY_ENTRIES = 1_024;
+const MAX_OPERATION_ENTRIES = 4;
+const MAX_INTENT_BYTES = (MAX_MANIFEST_BYTES * 2) + (16 * 1024);
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ARTIFACT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const OPERATION_MANAGED_BY = "nowcrew-project-skills-v2-operation";
+const OPERATION_PREFIX = ".project-skills-v2.";
+const OPERATION_SUFFIX = ".op";
+const PREPARING_PREFIX = ".project-skills-v2.preparing-";
+const DISCARD_PREFIX = ".project-skills-v2.discard-";
+const STAGE_BASENAME = "stage.json";
+const PREVIOUS_BASENAME = "previous.json";
+const PUBLISHED_BASENAME = "published.json";
+const INTENT_BASENAME = "intent.json";
+/** Private WAL tombstone: it is never a valid public applied-manifest shape. */
+const ABSENCE_MARKER_RAW = `${JSON.stringify({
+    managedBy: "nowcrew-project-skills-v2-absence", version: 1,
+})}\n`;
+const corrupt = () => { throw new ProjectSkillProjectionStateError("skill_projection_state_corrupt"); };
+const pathUnmanaged = () => {
+    throw new ProjectSkillProjectionStateError("skill_projection_state_path_unmanaged");
+};
+const unmanaged = () => { throw new ProjectSkillProjectionStateError("skill_projection_state_unmanaged"); };
+export const appliedProjectSkillManifestPath = (agentRoot) => join(agentRoot, ".crew", MANIFEST_FILE_NAME);
+const isMissing = (error) => error.code === "ENOENT";
+const ownedByCurrentUser = (uid) => process.getuid === undefined || uid === BigInt(process.getuid());
+/**
+ * Node/libuv cannot open Windows directories with a handle suitable for FlushFileBuffers. Project
+ * Skill publication therefore keeps file fsync and ordering there, but directory durability is
+ * explicitly best-effort until the v2 capability passes native Windows smoke validation.
+ */
+const projectionDirectorySync = (options) => options.platform === "win32" || (options.platform === undefined && process.platform === "win32")
+    ? async () => undefined
+    : options.directorySync ?? durableDirectorySync;
+const SerializedFileIdentitySchema = z.object({
+    dev: z.string().regex(/^\d+$/u).max(40), ino: z.string().regex(/^\d+$/u).max(40),
+    uid: z.string().regex(/^\d+$/u).max(40), size: z.string().regex(/^\d+$/u).max(40),
+    mtimeNs: z.string().regex(/^\d+$/u).max(40), ctimeNs: z.string().regex(/^\d+$/u).max(40),
+}).strict();
+const StageBindingSchema = z.object({
+    basename: z.literal(STAGE_BASENAME), content: z.string(), digest: z.string().regex(DIGEST),
+    identity: SerializedFileIdentitySchema,
+}).strict();
+const PreviousBindingSchema = z.object({
+    basename: z.literal(PREVIOUS_BASENAME), content: z.string(), digest: z.string().regex(DIGEST),
+    identity: SerializedFileIdentitySchema,
+}).strict();
+const OperationIntentSchema = z.object({
+    managedBy: z.literal(OPERATION_MANAGED_BY), version: z.literal(2),
+    nonce: z.string().regex(ARTIFACT_ID), finalBasename: z.literal(MANIFEST_FILE_NAME),
+    stage: StageBindingSchema, previous: PreviousBindingSchema.nullable(),
+}).strict();
+const fileIdentity = (info) => Object.freeze({
+    dev: info.dev, ino: info.ino, uid: info.uid, size: info.size,
+    mtimeNs: info.mtimeNs, ctimeNs: info.ctimeNs,
+});
+const serializeIdentity = (identity) => ({
+    dev: identity.dev.toString(), ino: identity.ino.toString(), uid: identity.uid.toString(),
+    size: identity.size.toString(), mtimeNs: identity.mtimeNs.toString(),
+    ctimeNs: identity.ctimeNs.toString(),
+});
+const sameFileVersion = (left, right) => left.dev === right.dev
+    && left.ino === right.ino
+    && left.uid === right.uid
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs;
+const sameSnapshot = (left, right) => left.raw === right.raw && sameFileVersion(left.identity, right.identity);
+const digestRaw = (raw) => `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+const isExisting = (error) => error.code === "EEXIST";
+const realOwnedDirectory = async (path, absentIsAllowed) => {
+    try {
+        const info = await lstat(path, { bigint: true });
+        if (!info.isDirectory() || info.isSymbolicLink() || !ownedByCurrentUser(info.uid))
+            return pathUnmanaged();
+        return true;
+    }
+    catch (error) {
+        if (absentIsAllowed && isMissing(error))
+            return false;
+        return pathUnmanaged();
+    }
+};
+/**
+ * A real mode-0700 operation directory is the ownership boundary for internal cleanup. We fence
+ * exact bytes and bigint versions before unlinking within it. Same-UID code deliberately bypassing
+ * that private boundary is outside the supported (otherwise unbounded) TOCTOU threat model.
+ */
+const validatePrivateOperationDirectory = async (path) => {
+    try {
+        const info = await lstat(path, { bigint: true });
+        if (!info.isDirectory() || info.isSymbolicLink() || !ownedByCurrentUser(info.uid)) {
+            return pathUnmanaged();
+        }
+        if (process.getuid !== undefined && (Number(info.mode) & 0o777) !== 0o700)
+            return pathUnmanaged();
+    }
+    catch {
+        return pathUnmanaged();
+    }
+};
+const readAtMostBytes = async (handle, maximumBytes) => {
+    const buffer = Buffer.allocUnsafe(maximumBytes + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const result = await handle.read(buffer, offset, buffer.length - offset, offset);
+        if (result.bytesRead === 0)
+            break;
+        offset += result.bytesRead;
+    }
+    if (offset > maximumBytes)
+        return corrupt();
+    return buffer.subarray(0, offset);
+};
+const readStableFile = async (path, maximumBytes, options = {}) => {
+    for (let attempt = 0; attempt < MAX_CONSISTENT_READ_ATTEMPTS; attempt += 1) {
+        let before;
+        try {
+            before = await lstat(path, { bigint: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            return pathUnmanaged();
+        }
+        if (!before.isFile() || before.isSymbolicLink() || !ownedByCurrentUser(before.uid)) {
+            return pathUnmanaged();
+        }
+        if (before.size > BigInt(maximumBytes))
+            return corrupt();
+        await options.afterInitialStat?.(attempt);
+        let handle = null;
+        try {
+            handle = await open(path, "r");
+            const opened = await handle.stat({ bigint: true });
+            if (!opened.isFile() || opened.isSymbolicLink() || !ownedByCurrentUser(opened.uid)) {
+                return pathUnmanaged();
+            }
+            if (opened.size > BigInt(maximumBytes))
+                return corrupt();
+            if (!sameFileVersion(fileIdentity(before), fileIdentity(opened)))
+                continue;
+            await options.afterOpenStat?.(attempt);
+            const content = await readAtMostBytes(handle, maximumBytes);
+            const after = await handle.stat({ bigint: true });
+            if (!after.isFile() || after.isSymbolicLink() || !ownedByCurrentUser(after.uid)) {
+                return pathUnmanaged();
+            }
+            if (after.size > BigInt(maximumBytes))
+                return corrupt();
+            let pathAfter;
+            try {
+                pathAfter = await lstat(path, { bigint: true });
+            }
+            catch (error) {
+                if (isMissing(error))
+                    continue;
+                return pathUnmanaged();
+            }
+            if (!pathAfter.isFile() || pathAfter.isSymbolicLink() || !ownedByCurrentUser(pathAfter.uid)) {
+                return pathUnmanaged();
+            }
+            if (pathAfter.size > BigInt(maximumBytes))
+                return corrupt();
+            const initialIdentity = fileIdentity(before);
+            const afterIdentity = fileIdentity(after);
+            if (!sameFileVersion(initialIdentity, afterIdentity)
+                || !sameFileVersion(afterIdentity, fileIdentity(pathAfter))
+                || BigInt(content.byteLength) !== after.size)
+                continue;
+            return Object.freeze({ identity: afterIdentity, raw: content.toString("utf8") });
+        }
+        catch (error) {
+            if (error instanceof ProjectSkillProjectionStateError)
+                throw error;
+            if (isMissing(error))
+                continue;
+            return pathUnmanaged();
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+        }
+    }
+    return pathUnmanaged();
+};
+const parseManifestRaw = (raw) => {
+    let candidate;
+    try {
+        candidate = JSON.parse(raw);
+    }
+    catch {
+        return corrupt();
+    }
+    return parseAppliedProjectSkillManifest(candidate);
+};
+const boundedDirectoryNames = async (path, maximumEntries) => {
+    let directory;
+    try {
+        directory = await opendir(path);
+    }
+    catch {
+        return pathUnmanaged();
+    }
+    const names = [];
+    try {
+        for (;;) {
+            const entry = await directory.read();
+            if (entry === null)
+                break;
+            names.push(entry.name);
+            if (names.length > maximumEntries)
+                return pathUnmanaged();
+        }
+    }
+    catch {
+        return pathUnmanaged();
+    }
+    finally {
+        await directory.close().catch(() => undefined);
+    }
+    return Object.freeze(names.sort());
+};
+const operationNonce = (name) => {
+    if (!name.startsWith(OPERATION_PREFIX) || !name.endsWith(OPERATION_SUFFIX))
+        return null;
+    const nonce = name.slice(OPERATION_PREFIX.length, -OPERATION_SUFFIX.length);
+    return ARTIFACT_ID.test(nonce) ? nonce : null;
+};
+const lifecycleNonce = (name, prefix) => {
+    if (!name.startsWith(prefix))
+        return null;
+    const nonce = name.slice(prefix.length);
+    return ARTIFACT_ID.test(nonce) ? nonce : null;
+};
+const listStateArtifacts = async (stateDirectory) => {
+    const names = await boundedDirectoryNames(stateDirectory, MAX_STATE_DIRECTORY_ENTRIES);
+    const operations = names.filter((name) => name.startsWith(OPERATION_PREFIX) && name.endsWith(OPERATION_SUFFIX));
+    if (operations.some((name) => operationNonce(name) === null))
+        return pathUnmanaged();
+    const preparing = names.filter((name) => lifecycleNonce(name, PREPARING_PREFIX) !== null);
+    const discards = names.filter((name) => lifecycleNonce(name, DISCARD_PREFIX) !== null);
+    return Object.freeze({
+        operations: Object.freeze(operations.map((name) => join(stateDirectory, name))),
+        preparing: Object.freeze(preparing.map((name) => join(stateDirectory, name))),
+        discards: Object.freeze(discards.map((name) => join(stateDirectory, name))),
+    });
+};
+const identityMatchesBinding = (identity, expected, allowLinkOrRenameCtime) => identity.dev.toString() === expected.dev
+    && identity.ino.toString() === expected.ino
+    && identity.uid.toString() === expected.uid
+    && identity.size.toString() === expected.size
+    && identity.mtimeNs.toString() === expected.mtimeNs
+    && (allowLinkOrRenameCtime || identity.ctimeNs.toString() === expected.ctimeNs);
+const snapshotMatchesBinding = (snapshot, binding, allowLinkOrRenameCtime) => snapshot.raw === binding.content
+    && digestRaw(snapshot.raw) === binding.digest
+    && identityMatchesBinding(snapshot.identity, binding.identity, allowLinkOrRenameCtime);
+const isAbsenceMarkerRaw = (raw) => raw === ABSENCE_MARKER_RAW;
+const validateBindingDefinition = (binding, allowAbsence = false) => {
+    if (Buffer.byteLength(binding.content, "utf8") > MAX_MANIFEST_BYTES
+        || digestRaw(binding.content) !== binding.digest
+        || binding.identity.size !== Buffer.byteLength(binding.content, "utf8").toString())
+        return corrupt();
+    if (!allowAbsence || !isAbsenceMarkerRaw(binding.content))
+        parseManifestRaw(binding.content);
+};
+const parseOperationIntent = (snapshot) => {
+    let candidate;
+    try {
+        candidate = JSON.parse(snapshot.raw);
+    }
+    catch {
+        return corrupt();
+    }
+    if (candidate && typeof candidate === "object" && "managedBy" in candidate
+        && candidate.managedBy !== OPERATION_MANAGED_BY) {
+        return unmanaged();
+    }
+    const parsed = OperationIntentSchema.safeParse(candidate);
+    if (!parsed.success)
+        return corrupt();
+    validateBindingDefinition(parsed.data.stage, true);
+    if (parsed.data.previous !== null)
+        validateBindingDefinition(parsed.data.previous);
+    return parsed.data;
+};
+const loadOperation = async (operationPath, expectedNonce = operationNonce(basename(operationPath))) => {
+    await validatePrivateOperationDirectory(operationPath);
+    if (expectedNonce === null)
+        return pathUnmanaged();
+    const names = await boundedDirectoryNames(operationPath, MAX_OPERATION_ENTRIES);
+    if (names.some((name) => ![
+        INTENT_BASENAME, STAGE_BASENAME, PREVIOUS_BASENAME, PUBLISHED_BASENAME,
+    ].includes(name))) {
+        return pathUnmanaged();
+    }
+    if (!names.includes(INTENT_BASENAME))
+        return pathUnmanaged();
+    const intentSnapshot = await readStableFile(join(operationPath, INTENT_BASENAME), MAX_INTENT_BYTES);
+    if (intentSnapshot === null)
+        return pathUnmanaged();
+    const intent = parseOperationIntent(intentSnapshot);
+    if (intent.nonce !== expectedNonce)
+        return pathUnmanaged();
+    const stage = names.includes(STAGE_BASENAME)
+        ? await readStableFile(join(operationPath, STAGE_BASENAME), MAX_MANIFEST_BYTES)
+        : null;
+    if (stage !== null && !snapshotMatchesBinding(stage, intent.stage, true))
+        return corrupt();
+    const previous = names.includes(PREVIOUS_BASENAME)
+        ? await readStableFile(join(operationPath, PREVIOUS_BASENAME), MAX_MANIFEST_BYTES)
+        : null;
+    if (previous !== null && (intent.previous === null
+        || !snapshotMatchesBinding(previous, intent.previous, true)))
+        return corrupt();
+    if (intent.previous === null && names.includes(PREVIOUS_BASENAME))
+        return corrupt();
+    const published = names.includes(PUBLISHED_BASENAME)
+        ? await readStableFile(join(operationPath, PUBLISHED_BASENAME), MAX_MANIFEST_BYTES)
+        : null;
+    if (published !== null && !snapshotMatchesBinding(published, intent.stage, true))
+        return corrupt();
+    return Object.freeze({ path: operationPath, intent, intentSnapshot, stage, previous, published });
+};
+const createExclusiveDurableFile = async (path, content, maximumBytes) => {
+    if (Buffer.byteLength(content, "utf8") > maximumBytes)
+        return corrupt();
+    let handle = null;
+    try {
+        handle = await open(path, "wx", 0o600);
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        const snapshot = await readStableFile(path, maximumBytes);
+        if (snapshot === null || snapshot.raw !== content)
+            return pathUnmanaged();
+        return snapshot;
+    }
+    catch (error) {
+        if (error instanceof ProjectSkillProjectionStateError)
+            throw error;
+        return pathUnmanaged();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+const operationBinding = (basename, snapshot) => ({
+    basename, content: snapshot.raw, digest: digestRaw(snapshot.raw),
+    identity: serializeIdentity(snapshot.identity),
+});
+const createOperation = async (stateDirectory, current, content, randomId, syncDirectory, afterIntentDurableBeforeActivate) => {
+    const nonce = randomId();
+    if (!ARTIFACT_ID.test(nonce))
+        return pathUnmanaged();
+    const operationPath = join(stateDirectory, `${OPERATION_PREFIX}${nonce}${OPERATION_SUFFIX}`);
+    const preparingPath = join(stateDirectory, `${PREPARING_PREFIX}${nonce}`);
+    try {
+        await mkdir(preparingPath, { mode: 0o700 });
+        await chmod(preparingPath, 0o700);
+    }
+    catch {
+        return pathUnmanaged();
+    }
+    await syncDirectory(stateDirectory);
+    await validatePrivateOperationDirectory(preparingPath);
+    const stage = await createExclusiveDurableFile(join(preparingPath, STAGE_BASENAME), content, MAX_MANIFEST_BYTES);
+    await syncDirectory(preparingPath).catch(() => pathUnmanaged());
+    const intent = {
+        managedBy: OPERATION_MANAGED_BY,
+        version: 2,
+        nonce,
+        finalBasename: MANIFEST_FILE_NAME,
+        stage: operationBinding(STAGE_BASENAME, stage),
+        previous: current === null ? null : operationBinding(PREVIOUS_BASENAME, current),
+    };
+    await createExclusiveDurableFile(join(preparingPath, INTENT_BASENAME), `${JSON.stringify(intent)}\n`, MAX_INTENT_BYTES);
+    await syncDirectory(preparingPath).catch(() => pathUnmanaged());
+    await syncDirectory(stateDirectory).catch(() => pathUnmanaged());
+    await afterIntentDurableBeforeActivate?.(preparingPath);
+    try {
+        await lstat(operationPath);
+        return pathUnmanaged();
+    }
+    catch (error) {
+        if (!isMissing(error))
+            return pathUnmanaged();
+    }
+    try {
+        await rename(preparingPath, operationPath);
+        await syncDirectory(stateDirectory);
+    }
+    catch {
+        return pathUnmanaged();
+    }
+    return loadOperation(operationPath);
+};
+const revalidatePrivateFile = async (operationPath, basename, maximumBytes, expected) => {
+    await validatePrivateOperationDirectory(operationPath);
+    const fenced = await readStableFile(join(operationPath, basename), maximumBytes);
+    if (fenced === null || !sameSnapshot(fenced, expected))
+        return pathUnmanaged();
+};
+const removeBoundOperationFile = async (operation, basename, binding, syncDirectory) => {
+    const path = join(operation.path, basename);
+    const snapshot = await readStableFile(path, MAX_MANIFEST_BYTES);
+    if (snapshot === null)
+        return;
+    if (!snapshotMatchesBinding(snapshot, binding, true))
+        return corrupt();
+    await revalidatePrivateFile(operation.path, basename, MAX_MANIFEST_BYTES, snapshot);
+    try {
+        await unlink(path);
+        await syncDirectory(operation.path);
+    }
+    catch {
+        return pathUnmanaged();
+    }
+};
+const cleanupDiscard = async (discardPath, syncDirectory, hooks = {}) => {
+    await validatePrivateOperationDirectory(discardPath);
+    const nonce = lifecycleNonce(basename(discardPath), DISCARD_PREFIX);
+    if (nonce === null)
+        return pathUnmanaged();
+    const initialNames = await boundedDirectoryNames(discardPath, MAX_OPERATION_ENTRIES);
+    if (initialNames.some((name) => ![
+        INTENT_BASENAME, STAGE_BASENAME, PREVIOUS_BASENAME, PUBLISHED_BASENAME,
+    ].includes(name))) {
+        return pathUnmanaged();
+    }
+    if (!initialNames.includes(INTENT_BASENAME)) {
+        if (initialNames.length !== 0)
+            return pathUnmanaged();
+        try {
+            await rmdir(discardPath);
+            await syncDirectory(dirname(discardPath));
+            return;
+        }
+        catch {
+            return pathUnmanaged();
+        }
+    }
+    const operation = await loadOperation(discardPath, nonce);
+    const names = await boundedDirectoryNames(operation.path, MAX_OPERATION_ENTRIES);
+    if (names.includes(PREVIOUS_BASENAME)) {
+        if (operation.intent.previous === null)
+            return corrupt();
+        await removeBoundOperationFile(operation, PREVIOUS_BASENAME, operation.intent.previous, syncDirectory);
+    }
+    if (names.includes(STAGE_BASENAME)) {
+        await removeBoundOperationFile(operation, STAGE_BASENAME, operation.intent.stage, syncDirectory);
+    }
+    if (names.includes(PUBLISHED_BASENAME)) {
+        await removeBoundOperationFile(operation, PUBLISHED_BASENAME, operation.intent.stage, syncDirectory);
+    }
+    const intent = await readStableFile(join(operation.path, INTENT_BASENAME), MAX_INTENT_BYTES);
+    if (intent === null || !sameSnapshot(intent, operation.intentSnapshot))
+        return pathUnmanaged();
+    parseOperationIntent(intent);
+    await revalidatePrivateFile(operation.path, INTENT_BASENAME, MAX_INTENT_BYTES, intent);
+    try {
+        await unlink(join(operation.path, INTENT_BASENAME));
+        await syncDirectory(operation.path);
+    }
+    catch {
+        return pathUnmanaged();
+    }
+    await hooks.afterDiscardIntentRemoved?.(discardPath);
+    try {
+        await rmdir(operation.path);
+        await syncDirectory(dirname(operation.path));
+    }
+    catch {
+        return pathUnmanaged();
+    }
+};
+const cleanupOperation = async (operationPath, syncDirectory, hooks = {}) => {
+    const operation = await loadOperation(operationPath);
+    const discardPath = join(dirname(operationPath), `${DISCARD_PREFIX}${operation.intent.nonce}`);
+    try {
+        await lstat(discardPath);
+        return pathUnmanaged();
+    }
+    catch (error) {
+        if (!isMissing(error))
+            return pathUnmanaged();
+    }
+    try {
+        await rename(operationPath, discardPath);
+        await syncDirectory(dirname(operationPath));
+    }
+    catch {
+        return pathUnmanaged();
+    }
+    await hooks.afterOperationDiscarded?.(discardPath);
+    await cleanupDiscard(discardPath, syncDirectory, hooks);
+};
+const restorePreviousNoClobber = async (operation, manifestPath, stateDirectory, syncDirectory) => {
+    const binding = operation.intent.previous;
+    if (binding === null)
+        return pathUnmanaged();
+    const previousPath = join(operation.path, PREVIOUS_BASENAME);
+    const previous = await readStableFile(previousPath, MAX_MANIFEST_BYTES);
+    if (previous === null || !snapshotMatchesBinding(previous, binding, true))
+        return corrupt();
+    await revalidatePrivateFile(operation.path, PREVIOUS_BASENAME, MAX_MANIFEST_BYTES, previous);
+    try {
+        await link(previousPath, manifestPath);
+        await syncDirectory(stateDirectory);
+    }
+    catch (error) {
+        if (!isExisting(error))
+            return pathUnmanaged();
+    }
+    const restored = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+    if (restored === null)
+        return pathUnmanaged();
+    parseManifestRaw(restored.raw);
+    if (!snapshotMatchesBinding(restored, binding, true)
+        && (isAbsenceMarkerRaw(operation.intent.stage.content)
+            || !snapshotMatchesBinding(restored, operation.intent.stage, true)))
+        return pathUnmanaged();
+    return restored;
+};
+const recoverMissingFinalForReader = async (manifestPath, stateDirectory, syncDirectory) => {
+    const artifacts = await listStateArtifacts(stateDirectory);
+    if (artifacts.discards.length !== 0)
+        return pathUnmanaged();
+    const { inert, proven } = await classifyOperations(artifacts.operations);
+    if (proven.length === 0)
+        return inert === 0 ? null : pathUnmanaged();
+    if (proven.length !== 1)
+        return pathUnmanaged();
+    try {
+        const operation = proven[0];
+        if (isAbsenceMarkerRaw(operation.intent.stage.content) && operation.published !== null)
+            return null;
+        if (operation.intent.previous === null)
+            return null;
+        if (operation.previous === null)
+            return pathUnmanaged();
+        const restored = await restorePreviousNoClobber(operation, manifestPath, stateDirectory, syncDirectory);
+        return parseManifestRaw(restored.raw);
+    }
+    catch (error) {
+        const appeared = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+        if (appeared !== null)
+            return parseManifestRaw(appeared.raw);
+        throw error;
+    }
+};
+const classifyOperations = async (paths) => {
+    const proven = [];
+    let inert = 0;
+    for (const path of paths) {
+        await validatePrivateOperationDirectory(path);
+        const names = await boundedDirectoryNames(path, MAX_OPERATION_ENTRIES);
+        if (!names.includes(INTENT_BASENAME)) {
+            inert += 1;
+            continue;
+        }
+        proven.push(await loadOperation(path));
+    }
+    return Object.freeze({ inert, proven: Object.freeze(proven) });
+};
+const settleExistingOperation = async (operationPath, manifestPath, stateDirectory, syncDirectory) => {
+    const operation = await loadOperation(operationPath);
+    let final = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+    if (final === null) {
+        if (isAbsenceMarkerRaw(operation.intent.stage.content) && operation.published !== null) {
+            await cleanupOperation(operationPath, syncDirectory);
+            return;
+        }
+        if (operation.intent.previous === null) {
+            await cleanupOperation(operationPath, syncDirectory);
+            return;
+        }
+        if (operation.previous === null)
+            return pathUnmanaged();
+        final = await restorePreviousNoClobber(operation, manifestPath, stateDirectory, syncDirectory);
+    }
+    parseManifestRaw(final.raw);
+    const knownStage = snapshotMatchesBinding(final, operation.intent.stage, true);
+    const knownPrevious = operation.intent.previous !== null
+        && snapshotMatchesBinding(final, operation.intent.previous, true);
+    if (!knownStage && !knownPrevious)
+        return pathUnmanaged();
+    await cleanupOperation(operationPath, syncDirectory);
+};
+const settleAnyExistingOperation = async (manifestPath, stateDirectory, syncDirectory) => {
+    const { operations } = await listStateArtifacts(stateDirectory);
+    const { inert, proven } = await classifyOperations(operations);
+    if (proven.length > 1)
+        return pathUnmanaged();
+    if (proven.length === 1) {
+        await settleExistingOperation(proven[0].path, manifestPath, stateDirectory, syncDirectory);
+    }
+    else if (inert !== 0) {
+        const final = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+        if (final === null)
+            return pathUnmanaged();
+        parseManifestRaw(final.raw);
+    }
+};
+const settleDiscardResidues = async (stateDirectory, syncDirectory) => {
+    const { discards } = await listStateArtifacts(stateDirectory);
+    for (const discardPath of discards)
+        await cleanupDiscard(discardPath, syncDirectory);
+};
+const settlePreparingResidues = async (stateDirectory, syncDirectory) => {
+    const { preparing } = await listStateArtifacts(stateDirectory);
+    for (const preparingPath of preparing) {
+        const nonce = lifecycleNonce(basename(preparingPath), PREPARING_PREFIX);
+        if (nonce === null)
+            continue;
+        let operation;
+        try {
+            operation = await loadOperation(preparingPath, nonce);
+        }
+        catch {
+            // Without exact, complete provenance this unrecognized residue is preserved and ignored.
+            continue;
+        }
+        if (operation.stage === null || operation.previous !== null)
+            continue;
+        const discardPath = join(stateDirectory, `${DISCARD_PREFIX}${nonce}`);
+        try {
+            await lstat(discardPath);
+            return pathUnmanaged();
+        }
+        catch (error) {
+            if (!isMissing(error))
+                return pathUnmanaged();
+        }
+        try {
+            await rename(preparingPath, discardPath);
+            await syncDirectory(stateDirectory);
+        }
+        catch {
+            return pathUnmanaged();
+        }
+        await cleanupDiscard(discardPath, syncDirectory);
+    }
+};
+const currentStillMatches = (current, observed) => current === null ? observed === null : observed !== null && sameSnapshot(current, observed);
+export async function readAppliedProjectSkillManifest(agentRoot, options = {}) {
+    const syncDirectory = projectionDirectorySync(options);
+    await realOwnedDirectory(agentRoot, false);
+    const stateDirectory = join(agentRoot, ".crew");
+    if (!await realOwnedDirectory(stateDirectory, true))
+        return null;
+    const manifestPath = appliedProjectSkillManifestPath(agentRoot);
+    const snapshot = await readStableFile(manifestPath, MAX_MANIFEST_BYTES, options);
+    return snapshot === null
+        ? recoverMissingFinalForReader(manifestPath, stateDirectory, syncDirectory)
+        : parseManifestRaw(snapshot.raw);
+}
+export async function writeAppliedProjectSkillManifest(agentRoot, manifest, options = {}) {
+    const parsed = parseAppliedProjectSkillManifest(manifest);
+    const syncDirectory = projectionDirectorySync(options);
+    await realOwnedDirectory(agentRoot, false);
+    const stateDirectory = join(agentRoot, ".crew");
+    if (!await realOwnedDirectory(stateDirectory, true)) {
+        try {
+            await mkdir(stateDirectory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!isExisting(error))
+                return pathUnmanaged();
+        }
+        await realOwnedDirectory(stateDirectory, false);
+    }
+    await chmod(stateDirectory, 0o700).catch(() => pathUnmanaged());
+    const content = `${JSON.stringify(parsed)}\n`;
+    if (Buffer.byteLength(content, "utf8") > MAX_MANIFEST_BYTES)
+        return corrupt();
+    const manifestPath = appliedProjectSkillManifestPath(agentRoot);
+    await settleDiscardResidues(stateDirectory, syncDirectory);
+    await settlePreparingResidues(stateDirectory, syncDirectory);
+    await settleAnyExistingOperation(manifestPath, stateDirectory, syncDirectory);
+    for (let attempt = 0; attempt < MAX_CONSISTENT_READ_ATTEMPTS; attempt += 1) {
+        const current = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+        if (current !== null)
+            parseManifestRaw(current.raw);
+        const operation = await createOperation(stateDirectory, current, content, options.randomId ?? randomUUID, syncDirectory, options.afterIntentDurableBeforeActivate);
+        const stagePath = join(operation.path, STAGE_BASENAME);
+        await options.afterStageDurable?.(stagePath);
+        const stagedOperation = await loadOperation(operation.path);
+        if (!sameSnapshot(stagedOperation.intentSnapshot, operation.intentSnapshot)
+            || stagedOperation.stage === null
+            || !snapshotMatchesBinding(stagedOperation.stage, operation.intent.stage, false))
+            return corrupt();
+        let observed;
+        try {
+            observed = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+        }
+        catch (error) {
+            await cleanupOperation(operation.path, syncDirectory);
+            throw error;
+        }
+        if (!currentStillMatches(current, observed)) {
+            let observedError;
+            try {
+                if (observed !== null)
+                    parseManifestRaw(observed.raw);
+            }
+            catch (error) {
+                observedError = error;
+            }
+            await cleanupOperation(operation.path, syncDirectory);
+            if (observedError !== undefined)
+                throw observedError;
+            continue;
+        }
+        if (current !== null) {
+            const previousPath = join(operation.path, PREVIOUS_BASENAME);
+            try {
+                await rename(manifestPath, previousPath);
+                await syncDirectory(operation.path);
+                await syncDirectory(stateDirectory);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    return pathUnmanaged();
+                await cleanupOperation(operation.path, syncDirectory);
+                continue;
+            }
+            await options.afterCurrentClaimed?.(previousPath);
+            const previous = await readStableFile(previousPath, MAX_MANIFEST_BYTES);
+            const previousBinding = operation.intent.previous;
+            if (previous === null || previousBinding === null)
+                return pathUnmanaged();
+            if (!snapshotMatchesBinding(previous, previousBinding, true)) {
+                try {
+                    await link(previousPath, manifestPath);
+                    await syncDirectory(stateDirectory);
+                }
+                catch (error) {
+                    if (!isExisting(error))
+                        return pathUnmanaged();
+                }
+                return corrupt();
+            }
+        }
+        // This is the final source-of-publication fence, after every hook and previous-state move.
+        let publicationOperation;
+        try {
+            publicationOperation = await loadOperation(operation.path);
+        }
+        catch (error) {
+            if (operation.intent.previous !== null) {
+                await restorePreviousNoClobber(operation, manifestPath, stateDirectory, syncDirectory);
+            }
+            throw error;
+        }
+        if (!sameSnapshot(publicationOperation.intentSnapshot, operation.intentSnapshot)) {
+            if (operation.intent.previous !== null) {
+                await restorePreviousNoClobber(operation, manifestPath, stateDirectory, syncDirectory);
+            }
+            return corrupt();
+        }
+        const publishableStage = await readStableFile(stagePath, MAX_MANIFEST_BYTES);
+        if (publishableStage === null
+            || !snapshotMatchesBinding(publishableStage, operation.intent.stage, false)) {
+            if (operation.intent.previous !== null) {
+                await restorePreviousNoClobber(operation, manifestPath, stateDirectory, syncDirectory);
+            }
+            return corrupt();
+        }
+        parseManifestRaw(publishableStage.raw);
+        try {
+            await link(stagePath, manifestPath);
+            await syncDirectory(stateDirectory);
+        }
+        catch (error) {
+            if (!isExisting(error))
+                return pathUnmanaged();
+            const occupant = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+            if (occupant === null)
+                return pathUnmanaged();
+            parseManifestRaw(occupant.raw);
+            const isPrevious = operation.intent.previous !== null
+                && snapshotMatchesBinding(occupant, operation.intent.previous, true);
+            const isStage = snapshotMatchesBinding(occupant, operation.intent.stage, true);
+            if (!isPrevious && !isStage)
+                return pathUnmanaged();
+            await cleanupOperation(operation.path, syncDirectory, options);
+            if (isStage)
+                return;
+            continue;
+        }
+        const publishedStage = await readStableFile(stagePath, MAX_MANIFEST_BYTES);
+        const publishedFinal = await readStableFile(manifestPath, MAX_MANIFEST_BYTES);
+        if (publishedStage === null || publishedFinal === null
+            || !snapshotMatchesBinding(publishedStage, operation.intent.stage, true)
+            || !snapshotMatchesBinding(publishedFinal, operation.intent.stage, true)
+            || publishedStage.identity.dev !== publishedFinal.identity.dev
+            || publishedStage.identity.ino !== publishedFinal.identity.ino)
+            return pathUnmanaged();
+        await cleanupOperation(operation.path, syncDirectory, options);
+        return;
+    }
+    return pathUnmanaged();
+}
+/** Package-private primitives used by the crash-safe projection/state transaction owner. */
+export const projectSkillManifestStoreInternals = Object.freeze({
+    ABSENCE_MARKER_RAW,
+    ARTIFACT_ID,
+    MAX_MANIFEST_BYTES,
+    OPERATION_PREFIX,
+    OPERATION_SUFFIX,
+    PREVIOUS_BASENAME,
+    PUBLISHED_BASENAME,
+    STAGE_BASENAME,
+    cleanupOperation,
+    createOperation,
+    isExisting,
+    isAbsenceMarkerRaw,
+    loadOperation,
+    parseAppliedProjectSkillManifest,
+    parseManifestRaw,
+    pathUnmanaged,
+    projectionDirectorySync,
+    readStableFile,
+    realOwnedDirectory,
+    restorePreviousNoClobber,
+    sameSnapshot,
+    settleAnyExistingOperation,
+    settleDiscardResidues,
+    settlePreparingResidues,
+    snapshotMatchesBinding,
+});