@jinn-network/jinn-layer 0.1.0

package/dist/ledger.js

@@ -0,0 +1,104 @@
+/**
+ * Contribution ledger — the operator's local receipt of what left their
+ * machine (plan Task 4, issue #1311).
+ *
+ * Append-only JSONL at `~/.jinn-client/harness-layer/ledger.jsonl` by
+ * default. Entries carry only persistence-safe fields (the task summary is
+ * already scrubbed by capture; redaction `before` values never reach here).
+ * The Task 5 fork renders this; Task 7 aggregates over it.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { VerifiabilityTierSchema } from './envelope.js';
+export const DEFAULT_LEDGER_PATH = join(homedir(), '.jinn-client', 'harness-layer', 'ledger.jsonl');
+export const LedgerEntrySchema = z.strictObject({
+    /** ISO-8601 time the entry was recorded. */
+    ts: z.iso.datetime(),
+    /** Scrubbed one-line task summary (from the envelope). */
+    taskSummary: z.string().min(1),
+    /** Published envelope ref (manifest CID) — null when vetoed. */
+    envelopeRef: z.string().min(1).nullable(),
+    /** ERC-8004 anchor tx hash — null when vetoed or the anchor returned none. */
+    anchorTx: z.string().min(1).nullable(),
+    verifiabilityTier: VerifiabilityTierSchema,
+    status: z.enum(['published', 'vetoed (local only)']),
+});
+/**
+ * Fork-shaped projection of a ledger entry — the row shape the TUI consumer
+ * (`apps/jinn-agent/plugins/jinn/ledger_view.py`, `rows_from_json`) reads.
+ * `state` is absent for published rows; the schema also accepts a `failed`
+ * state for forward-compat, even though `toLedgerRow` never emits it.
+ */
+export const LedgerRowSchema = z.strictObject({
+    time: z.string().min(1),
+    task: z.string().min(1),
+    env: z.string().min(1).nullable(),
+    anchor: z.string().min(1).nullable(),
+    tier: VerifiabilityTierSchema,
+    state: z.enum(['vetoed', 'failed']).optional(),
+});
+/** Project an internal ledger entry into the fork-consumed row shape. */
+export function toLedgerRow(entry) {
+    const base = {
+        time: entry.ts,
+        task: entry.taskSummary,
+        env: entry.envelopeRef,
+        anchor: entry.anchorTx,
+        tier: entry.verifiabilityTier,
+    };
+    switch (entry.status) {
+        case 'published':
+            return base;
+        case 'vetoed (local only)':
+            return { ...base, state: 'vetoed' };
+        default: {
+            // Exhaustiveness: a new status forces this branch to fail compilation.
+            const _never = entry.status;
+            return _never;
+        }
+    }
+}
+/** In-memory ledger (tests, embedders that persist elsewhere). */
+export function createMemoryLedger() {
+    const entries = [];
+    return {
+        append(entry) {
+            entries.push(LedgerEntrySchema.parse(entry));
+        },
+        list: () => entries,
+    };
+}
+function readEntries(path) {
+    if (!existsSync(path))
+        return [];
+    const entries = [];
+    for (const line of readFileSync(path, 'utf-8').split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            entries.push(LedgerEntrySchema.parse(JSON.parse(line)));
+        }
+        catch {
+            // A corrupt line must not sink the operator's whole receipt history.
+            console.warn(`[harness-layer] skipping malformed ledger line in ${path}`);
+        }
+    }
+    return entries;
+}
+/** Append-only JSONL file ledger. Creates parent directories on first write. */
+export function createFileLedger(path = DEFAULT_LEDGER_PATH) {
+    return {
+        append(entry) {
+            const parsed = LedgerEntrySchema.parse(entry);
+            mkdirSync(dirname(path), { recursive: true });
+            appendFileSync(path, JSON.stringify(parsed) + '\n', 'utf-8');
+        },
+        list: () => readEntries(path),
+    };
+}
+/** Read the ledger (plan Task 4's `ledger()` surface). Missing file ⇒ empty. */
+export function ledger(path = DEFAULT_LEDGER_PATH) {
+    return readEntries(path);
+}

package/dist/measurement.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Three-arm measurement — the §11 capability gate for distillation-v1
+ * (spec/2026-07-06-distillation-v1.md §11, D9/D11).
+ *
+ * REUSES the capability-eval rig — `comparePaired` / `mcnemarExact` (exact
+ * McNemar) from `client/src/eval/paired.ts`. This module is only the analysis
+ * layer that composes those into the three-arm gate; the actual per-arm run
+ * (executing the harness against the `cap-v0` slate with each corpus snapshot
+ * pre-installed, graded by the swe-rebench-v2 grader) is wired at run time and
+ * feeds this its per-instance results.
+ *
+ * NOTE: Wilson intervals (`wilson.ts`) are deliberately NOT used here. This is a
+ * matched (paired) design — the same slate under each arm — so exact McNemar on
+ * the discordant pairs is the correct test. Marginal Wilson intervals would
+ * reintroduce the between-instance variance that the paired design exists to
+ * remove (see `paired.ts`), so bolting one on would weaken, not strengthen, the
+ * comparison. Do not add it.
+ *
+ * NOTE (§11.1 — process gate, not code): the IUT composition below — capability
+ * = resolve-rate superiority AND cost non-inferiority — inverts cap-v0's
+ * quality/cost roles and MUST be confirmed with the capability-eval session
+ * before a `ship-distilled` verdict is treated as final. This module encodes the
+ * shape; it cannot ratify it.
+ *
+ * Arms: **seeds-only** (control), **raw-evidence** (the shipped v1 product
+ * baseline, D11), **distilled** (the bet). Two comparisons:
+ *   - distilled vs seeds — the capability claim: **resolve-rate superiority**
+ *     (trustworthy McNemar, distilled-favored) AND **cost non-inferior** on the
+ *     both-solve set.
+ *   - distilled vs raw-evidence — the **Bitter-Lesson test (D9)**: the distiller
+ *     earns its place only if it beats raw-evidence retrieval; otherwise the
+ *     retrieval baseline ships (D11).
+ *
+ * The first run is a **pilot** (§11): if the distilled-vs-seeds discordant count
+ * cannot reach significance, the verdict is `inconclusive`, not a false null.
+ */
+import { type PairedComparison } from '@jinn-network/core';
+export interface ArmResult {
+    instanceId: string;
+    /** null when unscorable (disk-skip / harness failure) — never coerced to a flip. */
+    passed: boolean | null;
+    unscorable: boolean;
+    /** Total cost of the run for this instance (USD). Optional; cost guard skips when absent. */
+    costUsd?: number;
+}
+export interface PilotPower {
+    discordant: number;
+    netEffect: number;
+    /** Smallest all-improve discordant count that can reach significance at alpha. */
+    minDiscordantForSignificance: number;
+    /**
+     * True ⇒ the discordant count is large enough that SOME split could reach
+     * significance. This is capability, NOT the result: `powered` says the run
+     * *could* have been decisive in either direction, not that distilled won.
+     * A powered run can still resolve to `within-noise` (e.g. an even split).
+     */
+    powered: boolean;
+}
+export interface ArmComparison {
+    paired: PairedComparison;
+    /** distilled mean cost ÷ baseline mean cost on the both-solve (concordant-pass) set; null when empty/absent. */
+    costRatio: number | null;
+    costNonInferior: boolean;
+}
+export type ShipVerdict = 'ship-distilled' | 'ship-retrieval-baseline' | 'inconclusive';
+export interface ThreeArmResult {
+    distilledVsSeeds: ArmComparison & {
+        capabilityPass: boolean;
+    };
+    distilledVsRaw: ArmComparison & {
+        bitterLessonPass: boolean;
+    };
+    pilot: PilotPower;
+    shipVerdict: ShipVerdict;
+}
+/**
+ * Pilot power for an exact McNemar run. A run can only be significant if its
+ * discordant count reaches `minDiscordantForSignificance` (the smallest n with
+ * `mcnemarExact(n, 0) < alpha`). Below that, no split is significant, so a null
+ * is uninformative (§11 — the first run is a pilot, a Haiku null uninformative).
+ */
+export declare function pilotPower(improved: number, regressed: number, alpha?: number): PilotPower;
+export declare function threeArmMeasurement(arms: {
+    seedsOnly: ArmResult[];
+    rawEvidence: ArmResult[];
+    distilled: ArmResult[];
+}, opts?: {
+    alpha?: number;
+    costMargin?: number;
+}): ThreeArmResult;

package/dist/measurement.js

@@ -0,0 +1,134 @@
+/**
+ * Three-arm measurement — the §11 capability gate for distillation-v1
+ * (spec/2026-07-06-distillation-v1.md §11, D9/D11).
+ *
+ * REUSES the capability-eval rig — `comparePaired` / `mcnemarExact` (exact
+ * McNemar) from `client/src/eval/paired.ts`. This module is only the analysis
+ * layer that composes those into the three-arm gate; the actual per-arm run
+ * (executing the harness against the `cap-v0` slate with each corpus snapshot
+ * pre-installed, graded by the swe-rebench-v2 grader) is wired at run time and
+ * feeds this its per-instance results.
+ *
+ * NOTE: Wilson intervals (`wilson.ts`) are deliberately NOT used here. This is a
+ * matched (paired) design — the same slate under each arm — so exact McNemar on
+ * the discordant pairs is the correct test. Marginal Wilson intervals would
+ * reintroduce the between-instance variance that the paired design exists to
+ * remove (see `paired.ts`), so bolting one on would weaken, not strengthen, the
+ * comparison. Do not add it.
+ *
+ * NOTE (§11.1 — process gate, not code): the IUT composition below — capability
+ * = resolve-rate superiority AND cost non-inferiority — inverts cap-v0's
+ * quality/cost roles and MUST be confirmed with the capability-eval session
+ * before a `ship-distilled` verdict is treated as final. This module encodes the
+ * shape; it cannot ratify it.
+ *
+ * Arms: **seeds-only** (control), **raw-evidence** (the shipped v1 product
+ * baseline, D11), **distilled** (the bet). Two comparisons:
+ *   - distilled vs seeds — the capability claim: **resolve-rate superiority**
+ *     (trustworthy McNemar, distilled-favored) AND **cost non-inferior** on the
+ *     both-solve set.
+ *   - distilled vs raw-evidence — the **Bitter-Lesson test (D9)**: the distiller
+ *     earns its place only if it beats raw-evidence retrieval; otherwise the
+ *     retrieval baseline ships (D11).
+ *
+ * The first run is a **pilot** (§11): if the distilled-vs-seeds discordant count
+ * cannot reach significance, the verdict is `inconclusive`, not a false null.
+ */
+import { comparePaired, mcnemarExact, } from '@jinn-network/core';
+const DEFAULT_ALPHA = 0.05;
+const DEFAULT_COST_MARGIN = 0.1;
+/**
+ * Pilot power for an exact McNemar run. A run can only be significant if its
+ * discordant count reaches `minDiscordantForSignificance` (the smallest n with
+ * `mcnemarExact(n, 0) < alpha`). Below that, no split is significant, so a null
+ * is uninformative (§11 — the first run is a pilot, a Haiku null uninformative).
+ */
+export function pilotPower(improved, regressed, alpha = DEFAULT_ALPHA) {
+    const discordant = improved + regressed;
+    let minN = 1;
+    while (mcnemarExact(minN, 0) >= alpha)
+        minN++;
+    return {
+        discordant,
+        netEffect: improved - regressed,
+        minDiscordantForSignificance: minN,
+        powered: discordant >= minN,
+    };
+}
+function toPaired(arm) {
+    return arm.map((r) => ({ instance_id: r.instanceId, passed: r.passed, unscorable: r.unscorable }));
+}
+/**
+ * Cost ratio (treatment ÷ baseline mean) on the set of instances BOTH arms
+ * scored as passed (the both-solve set). Returns:
+ *   - `null` when NO both-solve instance carries cost data on both arms — there
+ *     is no basis to compare, so the guard is SKIPPED (not "verified
+ *     non-inferior"; the caller must treat a null ratio on a ship verdict as
+ *     "cost unverified" and confirm cost tracking was on).
+ *   - `Infinity` when the baseline is free (baseSum === 0) but the treatment is
+ *     not — a paid treatment over a free baseline is infinitely worse, which
+ *     must FAIL the guard, not silently pass (the old `baseSum === 0 → null`
+ *     branch failed open on exactly the seeds-only control most likely to be
+ *     near-zero cost).
+ *   - `0` when both are free.
+ */
+function costOnBothSolve(baseline, treatment) {
+    const basePass = new Map(baseline.map((r) => [r.instanceId, r]));
+    let baseSum = 0;
+    let treatSum = 0;
+    let n = 0;
+    for (const t of treatment) {
+        const b = basePass.get(t.instanceId);
+        if (!b || b.passed !== true || t.passed !== true)
+            continue;
+        if (typeof b.costUsd !== 'number' || typeof t.costUsd !== 'number')
+            continue;
+        baseSum += b.costUsd;
+        treatSum += t.costUsd;
+        n++;
+    }
+    if (n === 0)
+        return null; // no both-solve cost data → no basis → guard skipped
+    if (baseSum === 0)
+        return treatSum === 0 ? 0 : Infinity; // free baseline: equal if treat free, else fails
+    return treatSum / baseSum;
+}
+function compareArm(baseline, treatment, alpha, costMargin) {
+    const paired = comparePaired(toPaired(baseline), toPaired(treatment), { alpha });
+    const costRatio = costOnBothSolve(baseline, treatment);
+    // Non-inferior when there is no cost basis (null → guard SKIPPED, cost
+    // UNVERIFIED — not verified-cheap) or the treatment is not materially more
+    // expensive on the both-solve set. Infinity (free baseline, paid treatment)
+    // fails the guard.
+    const costNonInferior = costRatio === null ? true : costRatio <= 1 + costMargin;
+    return { paired, costRatio, costNonInferior };
+}
+export function threeArmMeasurement(arms, opts = {}) {
+    const alpha = opts.alpha ?? DEFAULT_ALPHA;
+    const costMargin = opts.costMargin ?? DEFAULT_COST_MARGIN;
+    const vsSeeds = compareArm(arms.seedsOnly, arms.distilled, alpha, costMargin);
+    const vsRaw = compareArm(arms.rawEvidence, arms.distilled, alpha, costMargin);
+    const pilot = pilotPower(vsSeeds.paired.improved, vsSeeds.paired.regressed, alpha);
+    // Capability (the ship claim): resolve-rate superiority over seeds AND cost non-inferior.
+    const capabilityPass = vsSeeds.paired.verdict === 'trustworthy' && vsSeeds.costNonInferior;
+    // Bitter-Lesson (D9): the distiller earns its place only if it beats raw-evidence.
+    const bitterLessonPass = vsRaw.paired.verdict === 'trustworthy';
+    let shipVerdict;
+    if (!pilot.powered) {
+        shipVerdict = 'inconclusive';
+    }
+    else if (capabilityPass && bitterLessonPass) {
+        shipVerdict = 'ship-distilled';
+    }
+    else {
+        // Retrieval-over-evidence is the product baseline regardless (D11): the
+        // distiller either didn't beat raw-evidence or didn't clear the capability gate.
+        shipVerdict = 'ship-retrieval-baseline';
+    }
+    return {
+        distilledVsSeeds: { ...vsSeeds, capabilityPass },
+        distilledVsRaw: { ...vsRaw, bitterLessonPass },
+        pilot,
+        shipVerdict,
+    };
+}

package/dist/path-safety.d.ts

@@ -0,0 +1,19 @@
+/** True when `candidate` resolves to `root` or one of its descendants. */
+export declare function isInsidePackageDir(root: string, candidate: string): boolean;
+export interface PackageTreeFile {
+    /** Package-relative path below the selected output root. */
+    path: string;
+    content: string | Uint8Array;
+}
+/**
+ * Install a package tree without following pre-existing links below `root`.
+ *
+ * All content is first written beneath a private sibling directory. A missing
+ * destination is published by one directory rename. An existing destination
+ * retains merge/overwrite semantics: every output path is preflighted before
+ * the first mutation, existing regular files are moved to private backups,
+ * and staged files are atomically renamed into place. This replacement model
+ * leaves hardlinked outside inodes unchanged and works on Windows, where
+ * renaming directly over an existing file is not reliably supported.
+ */
+export declare function writePackageTreeSafely(root: string, files: PackageTreeFile[]): void;

package/dist/path-safety.js

@@ -0,0 +1,303 @@
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+function escapesPackageDir(relativePath) {
+    return relativePath === '..'
+        || relativePath.startsWith(`..${sep}`)
+        || isAbsolute(relativePath);
+}
+/** True when `candidate` resolves to `root` or one of its descendants. */
+export function isInsidePackageDir(root, candidate) {
+    const rel = relative(resolve(root), resolve(candidate));
+    return rel === '' || !escapesPackageDir(rel);
+}
+function nodeErrorCode(error) {
+    return error && typeof error === 'object' && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+function identity(stat) {
+    return { dev: stat.dev, ino: stat.ino };
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function lstatIfPresent(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (nodeErrorCode(error) === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function assertDirectory(path, label, expected) {
+    const before = lstatSync(path);
+    if (before.isSymbolicLink()) {
+        throw new Error(`${label} must not be a symlink: ${path}`);
+    }
+    if (!before.isDirectory()) {
+        throw new Error(`${label} must be a directory: ${path}`);
+    }
+    const beforeIdentity = identity(before);
+    if (expected && !sameIdentity(beforeIdentity, expected)) {
+        throw new Error(`${label} changed while the skill was being installed: ${path}`);
+    }
+    // Opening a directory is not portable on Windows. POSIX gets an additional
+    // lstat/open/fstat identity check and O_NOFOLLOW defence for the terminal
+    // component. Node does not expose openat/renameat, so callers also revalidate
+    // the full component chain immediately before every commit operation.
+    if (process.platform === 'win32')
+        return beforeIdentity;
+    const fd = openSync(path, constants.O_RDONLY
+        | (constants.O_NOFOLLOW ?? 0)
+        | (constants.O_DIRECTORY ?? 0));
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isDirectory()) {
+            throw new Error(`${label} changed while it was being opened: ${path}`);
+        }
+        const openedIdentity = identity(opened);
+        if (!sameIdentity(beforeIdentity, openedIdentity)) {
+            throw new Error(`${label} changed while it was being opened: ${path}`);
+        }
+        return openedIdentity;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function assertRegularTarget(path, label) {
+    const stat = lstatIfPresent(path);
+    if (!stat)
+        return undefined;
+    if (stat.isSymbolicLink()) {
+        throw new Error(`${label} must not be a symlink: ${path}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`${label} must be a regular file: ${path}`);
+    }
+    return stat;
+}
+function pathSegments(relativePath) {
+    return relativePath.split(sep).filter((part) => part !== '');
+}
+function assertOutputTreeSafe(root, files, expectedRoot) {
+    const rootStat = lstatIfPresent(root);
+    if (!rootStat)
+        return undefined;
+    const rootIdentity = assertDirectory(root, 'skill install directory', expectedRoot);
+    for (const file of files) {
+        const segments = pathSegments(file.relativePath);
+        let current = root;
+        let missingParent = false;
+        for (const segment of segments.slice(0, -1)) {
+            current = join(current, segment);
+            const stat = lstatIfPresent(current);
+            if (!stat) {
+                missingParent = true;
+                break;
+            }
+            assertDirectory(current, 'skill companion path component');
+        }
+        if (!missingParent)
+            assertRegularTarget(file.target, 'skill output target');
+    }
+    return rootIdentity;
+}
+function ensureTargetParent(root, relativePath, rootIdentity, created) {
+    const parents = [
+        { path: root, identity: assertDirectory(root, 'skill install directory', rootIdentity) },
+    ];
+    let current = root;
+    for (const segment of pathSegments(relativePath).slice(0, -1)) {
+        current = join(current, segment);
+        let stat = lstatIfPresent(current);
+        if (!stat) {
+            try {
+                mkdirSync(current);
+            }
+            catch (error) {
+                // A concurrent creator is acceptable only if it made the exact kind of
+                // entry we require; assertDirectory below rejects links and files.
+                if (nodeErrorCode(error) !== 'EEXIST')
+                    throw error;
+            }
+            stat = lstatIfPresent(current);
+            if (!stat)
+                throw new Error(`skill companion directory disappeared: ${current}`);
+            const directoryIdentity = assertDirectory(current, 'skill companion path component');
+            created.push({ path: current, identity: directoryIdentity });
+            parents.push({ path: current, identity: directoryIdentity });
+            continue;
+        }
+        parents.push({
+            path: current,
+            identity: assertDirectory(current, 'skill companion path component'),
+        });
+    }
+    // Close the check/use window as far as portable Node permits: every opened
+    // component must still name the same directory immediately before commit.
+    for (const parent of parents) {
+        assertDirectory(parent.path, parent.path === root ? 'skill install directory' : 'skill companion path component', parent.identity);
+    }
+    return parents;
+}
+function removeCreatedDirectories(created) {
+    for (const directory of [...created].reverse()) {
+        try {
+            const stat = lstatIfPresent(directory.path);
+            if (!stat || stat.isSymbolicLink() || !stat.isDirectory())
+                continue;
+            if (!sameIdentity(identity(stat), directory.identity))
+                continue;
+            rmdirSync(directory.path);
+        }
+        catch (error) {
+            // Non-empty means a prior directory already owns committed content or a
+            // concurrent writer used it. Either way, recursive cleanup is unsafe.
+            if (nodeErrorCode(error) !== 'ENOTEMPTY' && nodeErrorCode(error) !== 'EEXIST')
+                throw error;
+        }
+    }
+}
+function rollbackCommittedFiles(committed) {
+    const failures = [];
+    for (const file of [...committed].reverse()) {
+        try {
+            for (const parent of file.parents) {
+                assertDirectory(parent.path, 'skill output parent during rollback', parent.identity);
+            }
+            if (file.installed) {
+                const target = lstatIfPresent(file.target);
+                if (target
+                    && !target.isSymbolicLink()
+                    && target.isFile()
+                    && sameIdentity(identity(target), file.installed)) {
+                    unlinkSync(file.target);
+                }
+                else if (target) {
+                    failures.push(`installed target changed before rollback: ${file.target}`);
+                }
+            }
+            if (file.backup) {
+                if (lstatIfPresent(file.target)) {
+                    failures.push(`cannot restore occupied target: ${file.target}`);
+                }
+                else {
+                    renameSync(file.backup, file.target);
+                }
+            }
+        }
+        catch (error) {
+            failures.push(`${file.target}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(`skill install rollback incomplete — ${failures.join('; ')}`);
+    }
+}
+/**
+ * Install a package tree without following pre-existing links below `root`.
+ *
+ * All content is first written beneath a private sibling directory. A missing
+ * destination is published by one directory rename. An existing destination
+ * retains merge/overwrite semantics: every output path is preflighted before
+ * the first mutation, existing regular files are moved to private backups,
+ * and staged files are atomically renamed into place. This replacement model
+ * leaves hardlinked outside inodes unchanged and works on Windows, where
+ * renaming directly over an existing file is not reliably supported.
+ */
+export function writePackageTreeSafely(root, files) {
+    const absoluteRoot = resolve(root);
+    const normalized = new Map();
+    for (const file of files) {
+        const target = resolve(absoluteRoot, file.path);
+        const relativePath = relative(absoluteRoot, target);
+        if (relativePath === ''
+            || escapesPackageDir(relativePath)) {
+            throw new Error(`skill output path escapes the install directory: ${file.path}`);
+        }
+        if (normalized.has(relativePath)) {
+            throw new Error(`duplicate skill output path: ${file.path}`);
+        }
+        normalized.set(relativePath, { relativePath, target, content: file.content });
+    }
+    const outputs = [...normalized.values()];
+    // Reject a stable unsafe tree before even creating the private staging area.
+    const initialRootIdentity = assertOutputTreeSafe(absoluteRoot, outputs);
+    mkdirSync(dirname(absoluteRoot), { recursive: true });
+    const stagingRoot = mkdtempSync(join(dirname(absoluteRoot), '.jinn-skill-install-'));
+    const payloadRoot = join(stagingRoot, 'payload');
+    const backupRoot = join(stagingRoot, 'backup');
+    const committed = [];
+    const createdDirectories = [];
+    let cleanupStaging = true;
+    try {
+        mkdirSync(payloadRoot);
+        for (const file of outputs) {
+            const staged = join(payloadRoot, file.relativePath);
+            mkdirSync(dirname(staged), { recursive: true });
+            if (lstatIfPresent(staged)) {
+                throw new Error(`duplicate skill output path on this filesystem: ${file.relativePath}`);
+            }
+            writeFileSync(staged, file.content);
+        }
+        const rootIdentity = assertOutputTreeSafe(absoluteRoot, outputs, initialRootIdentity);
+        if (!rootIdentity) {
+            // rename(2) replaces a raced final symlink rather than following it on
+            // POSIX, and fails closed on Windows when the destination is occupied.
+            renameSync(payloadRoot, absoluteRoot);
+            assertDirectory(absoluteRoot, 'installed skill directory');
+            return;
+        }
+        mkdirSync(backupRoot, { mode: 0o700 });
+        for (let index = 0; index < outputs.length; index += 1) {
+            const file = outputs[index];
+            const parents = ensureTargetParent(absoluteRoot, file.relativePath, rootIdentity, createdDirectories);
+            const existing = assertRegularTarget(file.target, 'skill output target');
+            for (const parent of parents) {
+                assertDirectory(parent.path, parent.path === absoluteRoot ? 'skill install directory' : 'skill companion path component', parent.identity);
+            }
+            const commit = { target: file.target, parents };
+            committed.push(commit);
+            if (existing) {
+                const backup = join(backupRoot, String(index));
+                // Rename never follows the final component. A hardlink or a raced
+                // symlink is moved as a directory entry, not opened for writing.
+                renameSync(file.target, backup);
+                commit.backup = backup;
+            }
+            for (const parent of parents) {
+                assertDirectory(parent.path, 'skill output parent before commit', parent.identity);
+            }
+            renameSync(join(payloadRoot, file.relativePath), file.target);
+            const installed = assertRegularTarget(file.target, 'installed skill output');
+            if (!installed)
+                throw new Error(`installed skill output disappeared: ${file.target}`);
+            commit.installed = identity(installed);
+            for (const parent of parents) {
+                assertDirectory(parent.path, 'skill output parent after commit', parent.identity);
+            }
+        }
+    }
+    catch (error) {
+        try {
+            rollbackCommittedFiles(committed);
+            removeCreatedDirectories(createdDirectories);
+        }
+        catch (rollbackError) {
+            // Backups may be the only remaining copy of overwritten user files. Keep
+            // the private directory for manual recovery rather than deleting them.
+            cleanupStaging = false;
+            throw new Error(`${error instanceof Error ? error.message : String(error)}; `
+                + `${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}; `
+                + `recovery files retained at ${stagingRoot}`);
+        }
+        throw error;
+    }
+    finally {
+        if (cleanupStaging)
+            rmSync(stagingRoot, { recursive: true, force: true });
+    }
+}