javi-forge 1.29.0 → 1.30.0

package/dist/lib/claude-hook-settings.js

@@ -280,4 +280,137 @@ export function planManagedClaudeHookMerge(parsed, currentAssetSha, identities)
         action: "refuse",
     };
 }
+// Slice-3a write-plan helpers (Decision 8) — pure, reuse the module primitives.
+/** The managed timeout, matching the fixture handler shape. */
+const MANAGED_TIMEOUT = 30;
+function preToolUseArray(parsed) {
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    return isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+}
+function postToolUseArray(parsed) {
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    return isPlainObject(hooks) && Array.isArray(hooks.PostToolUse)
+        ? hooks.PostToolUse
+        : [];
+}
+/**
+ * Plan excision of the proven four-object legacy cohort from an embedded
+ * container. Reuses `LEGACY_COHORT` + `deepStructuralEqual` (the same primitives
+ * `classifyLegacy` uses) and never re-derives the classifier. Returns the exact
+ * ascending object indices to remove per event plus the append position for the
+ * freshly built managed group; every non-cohort sibling is preserved by index.
+ * Only an exact-legacy cohort is eligible — a partial/edited cohort refuses
+ * (the classifier already routes those to `foreign`).
+ */
+export function planLegacyCohortExcision(parsed) {
+    const cls = classifyLegacy(parsed);
+    if (cls.state !== "exact-legacy") {
+        return {
+            refused: true,
+            reason: `refuse cohort excision for state ${cls.state}`,
+            removePreIndices: [],
+            removePostIndices: [],
+            insertPreAt: 0,
+        };
+    }
+    const pre = preToolUseArray(parsed);
+    const post = postToolUseArray(parsed);
+    const removePreIndices = [];
+    for (const member of [LEGACY_COHORT.L1, LEGACY_COHORT.L2, LEGACY_COHORT.L3]) {
+        const index = pre.findIndex((item) => deepStructuralEqual(member, item));
+        if (index >= 0)
+            removePreIndices.push(index);
+    }
+    const removePostIndices = [];
+    const l4Index = post.findIndex((item) => deepStructuralEqual(LEGACY_COHORT.L4, item));
+    if (l4Index >= 0)
+        removePostIndices.push(l4Index);
+    removePreIndices.sort((a, b) => a - b);
+    removePostIndices.sort((a, b) => a - b);
+    return {
+        refused: false,
+        removePreIndices,
+        removePostIndices,
+        // The managed group appends after every surviving Pre sibling.
+        insertPreAt: pre.length - removePreIndices.length,
+    };
+}
+/**
+ * Plan an in-place force replacement of the single marker-proven managed
+ * handler for an `edited-managed` component. Eligibility (§324 / JD-A-001):
+ * - matcherExact === true  → eligible regardless of siblingHandlers.
+ * - matcherExact === false && siblingHandlers === 0 → eligible.
+ * - matcherExact === false && siblingHandlers  >  0 → refused even under force.
+ * A container without exactly one marker-proven handler in a valid matcher
+ * group also refuses.
+ */
+export function planForceReplace(parsed, currentAssetSha) {
+    // Empty identities force the marker-proven state to resolve as edited-managed
+    // while still exposing groupIndex/handlerIndex from the marker finder.
+    const cls = classifySettingsEntry(parsed, currentAssetSha, {
+        current: null,
+        historical: [],
+    });
+    if (cls.state !== "edited-managed" ||
+        cls.groupIndex === undefined ||
+        cls.handlerIndex === undefined) {
+        return {
+            refused: true,
+            reason: `refuse force replace for state ${cls.state}`,
+            state: cls.state,
+        };
+    }
+    const groups = preToolUseArray(parsed);
+    const group = groups[cls.groupIndex];
+    const matcherExact = isPlainObject(group) && group.matcher === MANAGED_MATCHER;
+    const handlerCount = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks.length : 0;
+    const siblingHandlers = Math.max(handlerCount - 1, 0);
+    if (!matcherExact && siblingHandlers > 0) {
+        return {
+            refused: true,
+            reason: "refuse force replace: edited matcher with unrelated sibling handlers (§324)",
+            state: cls.state,
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+            matcherExact,
+            siblingHandlers,
+        };
+    }
+    return {
+        refused: false,
+        state: cls.state,
+        groupIndex: cls.groupIndex,
+        handlerIndex: cls.handlerIndex,
+        matcherExact,
+        siblingHandlers,
+    };
+}
+/**
+ * Synthesize a fresh managed-only container for the two terminal states with no
+ * parsed value: fresh install (`absent`) and whole-file `exact-legacy`. Takes
+ * only the current asset SHA — not the whole Manifest — so this module never
+ * imports the manager's manifest reader at runtime (JD-A-002).
+ */
+export function buildManagedContainer(currentAssetSha) {
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: MANAGED_MATCHER,
+                    hooks: [
+                        {
+                            type: "command",
+                            command: "node",
+                            args: [MANAGED_ASSET_ARG],
+                            timeout: MANAGED_TIMEOUT,
+                            statusMessage: `${MANAGED_STATUS_PREFIX}${currentAssetSha}`,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
 //# sourceMappingURL=claude-hook-settings.js.map

package/dist/lib/secure-fs-posix.d.ts

@@ -0,0 +1,37 @@
+/**
+ * POSIX `PlatformSecureFs` adapters for the SkillGuard transactional installer
+ * (Slice 3a). This is the ONLY place a shell tool runs (`getfacl` on Linux,
+ * `/bin/ls -lde` on macOS) and the ONLY place `os`/`fs` ownership bits are
+ * interpreted. Everything fails closed: a missing/erroring/timed-out ACL tool,
+ * an extended/named/mask/default/inherited ACL entry, a foreign-owned or
+ * group/other-writable directory, or any inconclusive result refuses rather than
+ * degrading to a weaker mode-only write. It never strips an ACL.
+ */
+import type { PlatformSecureFs, SecureResult } from "./secure-fs-transaction.js";
+/** Outcome of a bounded, locale-C spawn of an ACL inspection tool. */
+export interface SpawnOutcome {
+    /** The executable could not be spawned (e.g. ENOENT). */
+    spawnError?: boolean;
+    /** The call exceeded the bounded timeout. */
+    timedOut?: boolean;
+    /** Exit code, or null when it never exited cleanly. */
+    code: number | null;
+    stdout: string;
+}
+export type SpawnFn = (cmd: string, args: string[]) => Promise<SpawnOutcome>;
+/** The bounded ACL prover behind each platform adapter. */
+export interface PosixAclAdapter {
+    /** Run the bounded, LC_ALL=C ACL tool and decide clean|extended|inconclusive. */
+    proveClean(target: string): Promise<SecureResult<void>>;
+}
+export declare function createLinuxAclAdapter(spawn?: SpawnFn): PosixAclAdapter;
+export declare function createMacosAclAdapter(spawn?: SpawnFn): PosixAclAdapter;
+export declare function createPosixSecureFs(acl: PosixAclAdapter): PlatformSecureFs;
+/**
+ * Select the POSIX secure filesystem for the host platform. Linux uses the
+ * `getfacl` adapter, macOS uses `/bin/ls -lde`; Windows and every other platform
+ * return `null` so the manager refuses with `windows-secure-object-unavailable`
+ * and mutates nothing (Slice 3b implements Windows).
+ */
+export declare function selectSecureFs(platform?: NodeJS.Platform): PlatformSecureFs | null;
+//# sourceMappingURL=secure-fs-posix.d.ts.map

package/dist/lib/secure-fs-posix.js

@@ -0,0 +1,302 @@
+/**
+ * POSIX `PlatformSecureFs` adapters for the SkillGuard transactional installer
+ * (Slice 3a). This is the ONLY place a shell tool runs (`getfacl` on Linux,
+ * `/bin/ls -lde` on macOS) and the ONLY place `os`/`fs` ownership bits are
+ * interpreted. Everything fails closed: a missing/erroring/timed-out ACL tool,
+ * an extended/named/mask/default/inherited ACL entry, a foreign-owned or
+ * group/other-writable directory, or any inconclusive result refuses rather than
+ * degrading to a weaker mode-only write. It never strips an ACL.
+ */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants as FS } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rmdir, unlink, } from "node:fs/promises";
+import path from "node:path";
+/** Bounded time budget for a single ACL inspection. */
+const ACL_TIMEOUT_MS = 2000;
+/** Read budget for the ACL tool output (defensive; ACLs are tiny). */
+const ACL_MAX_BUFFER = 1024 * 1024;
+// --- result constructors -----------------------------------------------------
+const ok = () => ({ ok: true });
+const okValue = (value) => ({ ok: true, value });
+const refuse = (refusal, detail) => ({ ok: false, refusal, detail });
+function errCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+}
+// --- default spawn (bounded, LC_ALL=C, argv never a shell string) ------------
+const defaultSpawn = (cmd, args) => new Promise((resolve) => {
+    execFile(cmd, args, {
+        timeout: ACL_TIMEOUT_MS,
+        maxBuffer: ACL_MAX_BUFFER,
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    }, (error, stdout) => {
+        if (!error)
+            return resolve({ code: 0, stdout: stdout ?? "" });
+        const e = error;
+        if (e.code === "ENOENT") {
+            return resolve({ spawnError: true, code: null, stdout: "" });
+        }
+        if (e.killed || e.signal === "SIGTERM") {
+            return resolve({ timedOut: true, code: null, stdout: stdout ?? "" });
+        }
+        const code = typeof e.code === "number" ? e.code : 1;
+        return resolve({ code, stdout: stdout ?? "" });
+    });
+});
+// --- Linux getfacl adapter (Algorithm D) -------------------------------------
+const LINUX_BASE_ENTRY = /^(user|group|other)::/;
+export function createLinuxAclAdapter(spawn = defaultSpawn) {
+    return {
+        async proveClean(target) {
+            const res = await spawn("getfacl", [
+                "--absolute-names",
+                "--numeric",
+                "--omit-header",
+                "--",
+                target,
+            ]);
+            if (res.spawnError)
+                return refuse("unsupported-posix-acl", "getfacl absent");
+            if (res.timedOut)
+                return refuse("unsupported-posix-acl", "getfacl timeout");
+            if (res.code !== 0) {
+                return refuse("unsupported-posix-acl", `getfacl exit ${res.code}`);
+            }
+            for (const raw of res.stdout.split("\n")) {
+                const line = raw.trim();
+                if (line === "" || line.startsWith("#"))
+                    continue;
+                if (LINUX_BASE_ENTRY.test(line))
+                    continue;
+                return refuse("unsupported-posix-acl", "extended ACL entry");
+            }
+            return ok();
+        },
+    };
+}
+// --- macOS /bin/ls -lde adapter (Algorithm E) --------------------------------
+const MACOS_ACE_LINE = /^\s*\d+:\s/;
+export function createMacosAclAdapter(spawn = defaultSpawn) {
+    return {
+        async proveClean(target) {
+            const res = await spawn("/bin/ls", ["-lde", "--", target]);
+            if (res.spawnError)
+                return refuse("unsupported-posix-acl", "/bin/ls absent");
+            if (res.timedOut)
+                return refuse("unsupported-posix-acl", "ls timeout");
+            if (res.code !== 0) {
+                return refuse("unsupported-posix-acl", `ls exit ${res.code}`);
+            }
+            const lines = res.stdout.split("\n");
+            const modeLine = lines[0] ?? "";
+            if (modeLine[10] === "+") {
+                return refuse("unsupported-posix-acl", "ACL present (+ flag)");
+            }
+            if (lines.some((line) => MACOS_ACE_LINE.test(line))) {
+                return refuse("unsupported-posix-acl", "ACE listed");
+            }
+            return ok();
+        },
+    };
+}
+// --- the POSIX secure filesystem --------------------------------------------
+const DIR_FLAGS = FS.O_DIRECTORY | FS.O_NOFOLLOW | FS.O_RDONLY;
+const CAPTURE_FLAGS = FS.O_NOFOLLOW | FS.O_RDONLY;
+const EXCLUSIVE_FLAGS = FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW;
+function identityOf(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+function ownershipTrusted(uid) {
+    const euid = typeof process.geteuid === "function" ? process.geteuid() : -1;
+    return uid === euid || uid === 0;
+}
+export function createPosixSecureFs(acl) {
+    async function fsyncDir(dirPath) {
+        const handle = await open(dirPath, DIR_FLAGS);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    const secureFs = {
+        async openDirNoFollow(dirPath) {
+            try {
+                const handle = await open(dirPath, DIR_FLAGS);
+                try {
+                    const stats = await handle.stat();
+                    const identity = identityOf(stats);
+                    return okValue({
+                        path: dirPath,
+                        identity,
+                        close: () => handle.close(),
+                    });
+                }
+                catch (error) {
+                    await handle.close();
+                    throw error;
+                }
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `openDir ${dirPath}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async revalidateIdentity(target, held) {
+            try {
+                const stats = await lstat(target);
+                if (stats.dev === held.dev && stats.ino === held.ino)
+                    return ok();
+                return refuse("unsafe-parent-chain", `identity drift at ${target}`);
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `revalidate ${target}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async proveOwnershipAndMode(dirPath) {
+            try {
+                const stats = await lstat(dirPath);
+                if (!ownershipTrusted(stats.uid)) {
+                    return refuse("unsafe-parent-chain", `foreign owner at ${dirPath}`);
+                }
+                if ((stats.mode & 0o022) !== 0) {
+                    return refuse("unsafe-parent-chain", `group/other-writable ${dirPath}`);
+                }
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `ownership ${dirPath}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        proveNoExtendedAcl(target) {
+            return acl.proveClean(target);
+        },
+        async createDirExclusive(parent, name, mode) {
+            const full = path.join(parent.path, name);
+            try {
+                await mkdir(full, { mode }); // fails EEXIST if it already exists
+                await chmod(full, mode); // defeat umask masking of mkdir mode
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `mkdir ${full}: ${errCode(error) ?? "error"}`);
+            }
+            const opened = await secureFs.openDirNoFollow(full);
+            if (!opened.ok || !opened.value)
+                return opened;
+            const owned = await secureFs.proveOwnershipAndMode(full);
+            if (!owned.ok) {
+                await opened.value.close();
+                return refuse("unsafe-parent-chain", owned.detail ?? full);
+            }
+            return opened;
+        },
+        async captureFile(target) {
+            try {
+                const handle = await open(target, CAPTURE_FLAGS);
+                try {
+                    const stats = await handle.stat();
+                    const bytes = await handle.readFile();
+                    const sha256 = createHash("sha256").update(bytes).digest("hex");
+                    return okValue({
+                        bytes,
+                        mode: stats.mode & 0o7777,
+                        identity: identityOf(stats),
+                        sha256,
+                    });
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `capture ${target}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async writeExclusive(dir, name, bytes, mode) {
+            const full = path.join(dir.path, name);
+            let handle;
+            try {
+                handle = await open(full, EXCLUSIVE_FLAGS, mode);
+                await handle.writeFile(bytes);
+                await handle.sync();
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `writeExclusive ${full}: ${errCode(error) ?? "error"}`);
+            }
+            finally {
+                await handle?.close().catch(() => { });
+            }
+        },
+        async applyExactMode(target, mode) {
+            try {
+                await chmod(target, mode);
+                const stats = await lstat(target);
+                if ((stats.mode & 0o7777) !== mode) {
+                    return refuse("unsafe-parent-chain", `mode mismatch ${target}`);
+                }
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `applyMode ${target}: ${errCode(error) ?? "error"}`);
+            }
+            return acl.proveClean(target);
+        },
+        async renameInDir(dir, from, to) {
+            try {
+                await rename(path.join(dir.path, from), path.join(dir.path, to));
+                await fsyncDir(dir.path);
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `rename ${from}->${to}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async unlinkIfIdentity(dir, name, held) {
+            const full = path.join(dir.path, name);
+            try {
+                const stats = await lstat(full);
+                if (stats.dev !== held.dev || stats.ino !== held.ino) {
+                    return refuse("unsafe-parent-chain", `identity mismatch ${full}`);
+                }
+                await unlink(full);
+                await fsyncDir(dir.path);
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `unlink ${full}: ${errCode(error) ?? "error"}`);
+            }
+        },
+        async rmdirIfIdentityEmpty(handle) {
+            try {
+                const stats = await lstat(handle.path);
+                if (stats.dev !== handle.identity.dev ||
+                    stats.ino !== handle.identity.ino) {
+                    return refuse("unsafe-parent-chain", `identity mismatch ${handle.path}`);
+                }
+                await rmdir(handle.path); // ENOTEMPTY if non-empty → refuse, no escalation
+                return ok();
+            }
+            catch (error) {
+                return refuse("unsafe-parent-chain", `rmdir ${handle.path}: ${errCode(error) ?? "error"}`);
+            }
+        },
+    };
+    return secureFs;
+}
+/**
+ * Select the POSIX secure filesystem for the host platform. Linux uses the
+ * `getfacl` adapter, macOS uses `/bin/ls -lde`; Windows and every other platform
+ * return `null` so the manager refuses with `windows-secure-object-unavailable`
+ * and mutates nothing (Slice 3b implements Windows).
+ */
+export function selectSecureFs(platform = process.platform) {
+    if (platform === "linux")
+        return createPosixSecureFs(createLinuxAclAdapter());
+    if (platform === "darwin")
+        return createPosixSecureFs(createMacosAclAdapter());
+    return null;
+}
+//# sourceMappingURL=secure-fs-posix.js.map

package/dist/lib/secure-fs-transaction.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Platform-agnostic transactional file-write core for the SkillGuard Claude
+ * PreToolUse installer (Slice 3a). This module owns all irreversible I/O behind
+ * a single `PlatformSecureFs` adapter interface: it NEVER spawns a process and
+ * NEVER branches on `process.platform`. Every ownership/identity/ACL/exclusive
+ * decision is delegated to the injected adapter, so the engine is reviewed once
+ * (platform-free) and exercised by a synchronous in-memory fake in tests.
+ *
+ * WU-2 defines the interface + result types here so the POSIX adapter can
+ * implement them; WU-3 grows this file with `runTransaction` + `TransactionDeps`.
+ */
+/** Identity of an opened directory/file, captured from its handle. */
+export interface SecureIdentity {
+    dev: number;
+    ino: number;
+}
+/** A held, no-follow directory handle plus its captured identity and path. */
+export interface SecureDirHandle {
+    readonly path: string;
+    readonly identity: SecureIdentity;
+    close(): Promise<void>;
+}
+/** Captured prior state of a target file, taken through the validated gate. */
+export interface CapturedFile {
+    bytes: Buffer;
+    mode: number;
+    identity: SecureIdentity;
+    sha256: string;
+}
+export type SecureRefusal = "unsafe-parent-chain" | "unsupported-posix-acl" | "windows-secure-object-unavailable";
+export interface SecureResult<T> {
+    ok: boolean;
+    value?: T;
+    refusal?: SecureRefusal;
+    detail?: string;
+}
+/**
+ * The whole platform boundary. Every host-dependent operation is a method here;
+ * the transaction core talks only to this interface. POSIX now, Windows stub in
+ * Slice 3b, a synchronous fake in tests.
+ */
+export interface PlatformSecureFs {
+    /** Open an existing directory no-follow (O_DIRECTORY|O_NOFOLLOW) and capture dev+ino. */
+    openDirNoFollow(dirPath: string): Promise<SecureResult<SecureDirHandle>>;
+    /** Reopen a path and confirm its identity equals a previously held one. */
+    revalidateIdentity(target: string, held: SecureIdentity): Promise<SecureResult<void>>;
+    /** Prove owner == effective uid or root AND no group/other write bits. */
+    proveOwnershipAndMode(dirPath: string): Promise<SecureResult<void>>;
+    /** Prove no extended/named/mask/default/inherited ACL on the path. */
+    proveNoExtendedAcl(target: string): Promise<SecureResult<void>>;
+    /** Create ONE child directory exclusively at mode, reopen+verify, return its handle. */
+    createDirExclusive(parent: SecureDirHandle, name: string, mode: number): Promise<SecureResult<SecureDirHandle>>;
+    /**
+     * Capture a regular file's bytes+mode+identity+sha through the validated gate.
+     * MUST open the target with `O_NOFOLLOW|O_RDONLY` (never a plain path read): a
+     * symlink swapped in at the target name must fail the open, not be
+     * dereferenced. This is a security boundary (JD-B-003) — the capture is the
+     * source of both the persistent backup and the in-memory rollback bytes.
+     */
+    captureFile(target: string): Promise<SecureResult<CapturedFile>>;
+    /**
+     * Create <name> in dir with O_CREAT|O_EXCL|O_WRONLY|O_NOFOLLOW at mode; write
+     * bytes; `handle.sync()` (fsync) the file before close. The write and the
+     * fsync are one method so an fsync fault is an injectable fault point of
+     * `writeExclusive` itself (JD-B-004): a fake can succeed the write and fail
+     * the sync to drive that branch.
+     */
+    writeExclusive(dir: SecureDirHandle, name: string, bytes: Buffer, mode: number): Promise<SecureResult<void>>;
+    /** Apply an exact mode to an existing staged file and re-verify mode + ACL absence. */
+    applyExactMode(target: string, mode: number): Promise<SecureResult<void>>;
+    /** Same-directory rename from -> to, then fsync the directory. */
+    renameInDir(dir: SecureDirHandle, from: string, to: string): Promise<SecureResult<void>>;
+    /** Unlink an identity-matched file (rollback of a newly created target). */
+    unlinkIfIdentity(dir: SecureDirHandle, name: string, held: SecureIdentity): Promise<SecureResult<void>>;
+    /** Remove an identity-matched EMPTY directory (rollback of a created segment). */
+    rmdirIfIdentityEmpty(handle: SecureDirHandle): Promise<SecureResult<void>>;
+}
+/** Injected seams making the engine deterministic and host-independent. */
+export interface TransactionDeps {
+    secureFs: PlatformSecureFs;
+    clock: () => Date;
+    nonce: () => string;
+}
+/**
+ * One target of the transaction (asset or settings). All Claude-specific state
+ * is collapsed to explicit flags so the engine stays agent-agnostic.
+ */
+export interface TransactionComponent {
+    /** Absolute target path. */
+    path: string;
+    /** Bytes to write, or null to skip this component (no-op / already current). */
+    desired: Buffer | null;
+    /** Capture prior bytes for in-memory rollback (existing managed/legacy content). */
+    capturePrior: boolean;
+    /** Create a persistent backup — forced edited-managed only (Decision 5). */
+    forceBackup: boolean;
+    /** True when the target did not exist before this op (rollback = unlink). */
+    wasAbsent: boolean;
+}
+export interface RunTransactionInput extends TransactionDeps {
+    /** Existing project directory; `.claude` / `.claude/hooks` are created under it. */
+    projectDir: string;
+    /** Committed first. */
+    asset: TransactionComponent;
+    /** Committed second. */
+    settings: TransactionComponent;
+}
+export interface TransactionOutcome {
+    ok: boolean;
+    committed: string[];
+    backups: string[];
+    errors: string[];
+}
+/**
+ * Run the staged, two-target transaction. Preflight gates the private parent
+ * chain, creates `.claude`/`.claude/hooks` one exclusive `0o700` segment at a
+ * time, captures prior bytes (+ a forced-only persistent backup), stages each
+ * new byte set into a same-directory `0o600` temp, re-proves the full gate
+ * immediately before the first rename (JD-007), then commits asset-first and
+ * settings-second via same-directory rename + parent fsync. A failure after a
+ * commit triggers guarded reverse-order rollback from the in-memory captured
+ * bytes; lost proof or a post-write hash drift STOPS cleanup and returns
+ * manual-recovery guidance (never clobbers a concurrent change).
+ */
+export declare function runTransaction(input: RunTransactionInput): Promise<TransactionOutcome>;
+//# sourceMappingURL=secure-fs-transaction.d.ts.map