@phyzess/pappra 0.1.0-beta.14 → 0.1.0-beta.19

package/dist/infra/json-property.js

@@ -0,0 +1,69 @@
+/** Replace one top-level JSON property while retaining unrelated bytes and style. */
+export function updateJsonProperty(existing, key, value) {
+    if (existing === null)
+        return Buffer.from(`${JSON.stringify({ [key]: value }, null, 2)}\n`);
+    const text = existing.toString('utf8');
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error('json_object_required');
+    const newline = text.includes('\r\n') ? '\r\n' : '\n';
+    let indent = '';
+    const skipSpace = (at) => {
+        while (/\s/.test(text[at] ?? '') && at < text.length)
+            at += 1;
+        return at;
+    };
+    const stringEnd = (start) => {
+        let at = start + 1;
+        while (at < text.length) {
+            if (text[at] === '\\')
+                at += 2;
+            else if (text[at++] === '"')
+                return at;
+        }
+        throw new Error('json_string_unterminated');
+    };
+    const render = (prefix) => {
+        const unit = indent || (text.includes('\n') ? '  ' : undefined);
+        return (JSON.stringify(value, null, unit)?.replaceAll('\n', `${newline}${prefix}`) ?? 'null');
+    };
+    let at = skipSpace(text.indexOf('{') + 1);
+    while (text[at] !== '}') {
+        const endKey = stringEnd(at);
+        const property = JSON.parse(text.slice(at, endKey));
+        const line = text.slice(text.lastIndexOf('\n', at) + 1, at);
+        if (/^[ \t]+$/.test(line) && (!indent || line.length < indent.length))
+            indent = line;
+        const startValue = skipSpace(skipSpace(endKey) + 1);
+        let endValue = startValue;
+        let depth = 0;
+        while (endValue < text.length) {
+            const character = text[endValue];
+            if (character === '"') {
+                endValue = stringEnd(endValue);
+                continue;
+            }
+            if (depth === 0 && (character === ',' || character === '}'))
+                break;
+            if (character === '[' || character === '{')
+                depth += 1;
+            if (character === ']' || character === '}')
+                depth -= 1;
+            endValue += 1;
+        }
+        let contentEnd = endValue;
+        while (/\s/.test(text[contentEnd - 1] ?? '') && contentEnd > startValue)
+            contentEnd -= 1;
+        if (property === key)
+            return Buffer.from(text.slice(0, startValue) +
+                render(/^[ \t]*$/.test(line) ? line : '') +
+                text.slice(contentEnd));
+        at = skipSpace(endValue + (text[endValue] === ',' ? 1 : 0));
+    }
+    const prefix = text.slice(0, at).trimEnd();
+    const separator = Object.keys(parsed).length > 0 ? ',' : '';
+    const insertion = text.includes('\n')
+        ? `${separator}${newline}${indent || '  '}${JSON.stringify(key)}: ${render(indent || '  ')}${newline}`
+        : `${separator}${JSON.stringify(key)}:${JSON.stringify(value)}`;
+    return Buffer.from(prefix + insertion + text.slice(at));
+}

package/dist/infra/json.d.ts

@@ -0,0 +1,4 @@
+/** Canonicalize the value JSON actually persists, including omitted object keys and array holes. */
+export declare function canonicalJson(value: unknown): string;
+/** Raw SHA-256 hex for contracts that pin canonical JSON rather than insertion order. */
+export declare function canonicalJsonDigest(value: unknown): string;

package/dist/infra/json.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+/** Canonicalize the value JSON actually persists, including omitted object keys and array holes. */
+export function canonicalJson(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw new TypeError('Canonical JSON requires a JSON-serializable value');
+    const persisted = JSON.parse(serialized);
+    return encode(persisted);
+}
+function encode(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(encode).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${encode(record[key])}`)
+        .join(',')}}`;
+}
+/** Raw SHA-256 hex for contracts that pin canonical JSON rather than insertion order. */
+export function canonicalJsonDigest(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex');
+}

package/dist/infra/owned-process-group.js

@@ -1,4 +1,4 @@
-import { errorCode } from '../collab/validation.js';
+import { errorCode } from './validation.js';
 import { execFileSync, spawn } from 'node:child_process';
 // Scoped Unix process-group helper. It exists to extend a stop beyond the single owned parent
 // into the exact process group that parent created, and nothing else.

package/dist/infra/private-lock.d.ts

@@ -0,0 +1,16 @@
+/** Publish only a complete, fsynced lock; a crash cannot expose an empty owner record. */
+export declare function publishPrivateLock(file: string, bytes: Buffer, revalidate?: () => Promise<void>): Promise<void>;
+export interface PrivateLockObservation {
+    readonly file: string;
+    readonly state: 'missing' | 'alive' | 'dead' | 'unknown';
+    readonly token: string | null;
+    readonly digest: string | null;
+    readonly identity: {
+        readonly dev: number;
+        readonly ino: number;
+    } | null;
+}
+/** An old PID-only lock is reclaimable only after ESRCH, never by its age. */
+export declare function inspectPrivateLock(file: string): Promise<PrivateLockObservation>;
+/** One immutable claim wins a stale owner boundary; interrupted claimants can be succeeded. */
+export declare function reclaimDeadPrivateLock(file: string, revalidate: () => Promise<void>): Promise<boolean>;

package/dist/infra/private-lock.js

@@ -0,0 +1,148 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, unlink } from 'node:fs/promises';
+import { sha256Digest } from './fs.js';
+import { captureProcessIdentity, isLocalProcessIdentity, observeProcessIdentity, } from './process-identity.js';
+/** Publish only a complete, fsynced lock; a crash cannot expose an empty owner record. */
+export async function publishPrivateLock(file, bytes, revalidate) {
+    const temporary = `${file}.pending-${process.pid}-${randomUUID()}`;
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_WRONLY |
+            constants.O_CREAT |
+            constants.O_EXCL |
+            constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await revalidate?.();
+        await link(temporary, file);
+        await revalidate?.();
+        const published = await lstat(file);
+        const staged = await handle.stat();
+        if (!published.isFile() ||
+            published.dev !== staged.dev ||
+            published.ino !== staged.ino)
+            throw new Error(`Published lock identity changed: ${file}`);
+    }
+    finally {
+        await handle?.close();
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+/** An old PID-only lock is reclaimable only after ESRCH, never by its age. */
+export async function inspectPrivateLock(file) {
+    const empty = {
+        file,
+        state: 'unknown',
+        token: null,
+        digest: null,
+        identity: null,
+    };
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const stats = await handle.stat();
+        if (!stats.isFile() || stats.size > 64 * 1024)
+            return empty;
+        const bytes = Buffer.alloc(64 * 1024 + 1);
+        const read = await handle.read(bytes, 0, bytes.length, 0);
+        if (read.bytesRead > 64 * 1024)
+            return empty;
+        const content = bytes.subarray(0, read.bytesRead);
+        let value;
+        try {
+            value = JSON.parse(content.toString('utf8'));
+        }
+        catch {
+            return empty;
+        }
+        if (typeof value !== 'object' ||
+            value === null ||
+            !('pid' in value) ||
+            !('token' in value) ||
+            typeof value.pid !== 'number' ||
+            !Number.isSafeInteger(value.pid) ||
+            value.pid <= 0 ||
+            typeof value.token !== 'string' ||
+            !value.token)
+            return empty;
+        let state = 'unknown';
+        if ('process_identity' in value && value.process_identity !== undefined) {
+            state =
+                isLocalProcessIdentity(value.process_identity) &&
+                    value.process_identity.pid === value.pid
+                    ? observeProcessIdentity(value.process_identity)
+                    : 'unknown';
+        }
+        else {
+            try {
+                process.kill(value.pid, 0);
+                // PID existence alone cannot bind an imported lock to that process birth.
+                state = 'unknown';
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    state = 'dead';
+            }
+        }
+        return {
+            file,
+            state,
+            token: value.token,
+            digest: sha256Digest(content),
+            identity: { dev: stats.dev, ino: stats.ino },
+        };
+    }
+    catch (error) {
+        return error.code === 'ENOENT'
+            ? { ...empty, state: 'missing' }
+            : empty;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function sameLock(a, b) {
+    return (a.state === b.state &&
+        a.token === b.token &&
+        a.digest === b.digest &&
+        a.identity?.dev === b.identity?.dev &&
+        a.identity?.ino === b.identity?.ino);
+}
+/** One immutable claim wins a stale owner boundary; interrupted claimants can be succeeded. */
+export async function reclaimDeadPrivateLock(file, revalidate) {
+    await revalidate();
+    const original = await inspectPrivateLock(file);
+    if (original.state === 'missing')
+        return false;
+    if (original.state !== 'dead' || original.digest === null)
+        throw new Error(`Lock owner is alive or unverified; preserve ${file}`);
+    const base = `${file}.reclaim-${original.digest.slice(7)}`;
+    let claim = base;
+    for (let hop = 0; hop < 64; hop += 1) {
+        await revalidate();
+        const before = await inspectPrivateLock(file);
+        if (before.state === 'missing')
+            return false;
+        if (!sameLock(original, before))
+            throw new Error(`Lock changed during recovery: ${file}`);
+        try {
+            await publishPrivateLock(claim, Buffer.from(`${JSON.stringify({ token: randomUUID(), pid: process.pid, process_identity: captureProcessIdentity() ?? undefined })}\n`), revalidate);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const owner = await inspectPrivateLock(claim);
+            if (owner.state !== 'dead')
+                throw new Error(`Another or unverified repair owns ${file}`);
+            claim = `${base}.retry-${sha256Digest(JSON.stringify([owner.digest, owner.identity])).slice(7)}`;
+            continue;
+        }
+        await revalidate();
+        if (!sameLock(original, await inspectPrivateLock(file)))
+            throw new Error(`Lock changed after recovery reservation: ${file}`);
+        await unlink(file);
+        return true;
+    }
+    throw new Error(`Too many interrupted lock repairs; preserve ${file}`);
+}

package/dist/infra/private-state.d.ts

@@ -0,0 +1,7 @@
+import { type Outcome } from '../schemas/outcome.js';
+/**
+ * Prepare private state before its first write, independently of init. Existing
+ * ignore rules are preserved; an appended final wildcard prevents earlier
+ * negations from exposing machine paths, checkpoints, or task metadata.
+ */
+export declare function ensurePrivateState(root: string, directory?: 'local' | 'local-archive'): Promise<Outcome<null>>;

package/dist/infra/private-state.js

@@ -0,0 +1,146 @@
+import { constants } from 'node:fs';
+import { mkdir, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { errorMessage, failed, succeeded, } from '../schemas/outcome.js';
+import { observePath, resolveRealpath } from './fs.js';
+const MAX_IGNORE_BYTES = 64 * 1024;
+function hasFinalIgnoreAll(text) {
+    const rules = text
+        .split('\n')
+        .map((line) => line.replace(/\r$/, ''))
+        .filter((line) => line !== '' && !line.startsWith('#'));
+    return rules.at(-1) === '*';
+}
+/**
+ * Prepare private state before its first write, independently of init. Existing
+ * ignore rules are preserved; an appended final wildcard prevents earlier
+ * negations from exposing machine paths, checkpoints, or task metadata.
+ */
+export async function ensurePrivateState(root, directory = 'local') {
+    if (directory !== 'local' && directory !== 'local-archive')
+        return failed(diagnosticCodes.initTargetUnsafe, 'Unknown private-state namespace.', { nextAction: 'Use a supported private-state directory.' });
+    const canonical = await resolveRealpath(root);
+    if (canonical === null)
+        return failed(diagnosticCodes.initTargetUnsafe, `Cannot resolve the private-state workspace: ${root}`, { nextAction: 'Use an existing workspace root.' });
+    const pinned = [];
+    const assertCurrent = async () => {
+        for (const identity of pinned) {
+            const current = await observePath(identity.path);
+            if (current.kind !== 'directory' ||
+                current.stats?.dev !== identity.dev ||
+                current.stats.ino !== identity.ino) {
+                throw new Error(`Private-state namespace changed: ${identity.path}`);
+            }
+        }
+    };
+    const local = join(canonical, '.pappra', directory);
+    const ignore = join(local, '.gitignore');
+    try {
+        for (const path of [canonical, join(canonical, '.pappra'), local]) {
+            await assertCurrent();
+            let observation = await observePath(path);
+            if (observation.kind === 'missing' && path !== canonical) {
+                await mkdir(path, { mode: 0o700 }).catch(async (error) => {
+                    if ((await observePath(path)).kind !== 'directory')
+                        throw error;
+                });
+                observation = await observePath(path);
+            }
+            if (observation.kind !== 'directory' ||
+                observation.stats === null ||
+                (await resolveRealpath(path)) !== path) {
+                throw new Error(`Private-state namespace is redirected or not a directory: ${path}`);
+            }
+            pinned.push({
+                path,
+                dev: observation.stats.dev,
+                ino: observation.stats.ino,
+            });
+        }
+        await assertCurrent();
+        let observation = await observePath(ignore);
+        if (observation.kind === 'missing') {
+            let created;
+            try {
+                created = await open(ignore, constants.O_CREAT |
+                    constants.O_EXCL |
+                    constants.O_WRONLY |
+                    constants.O_APPEND |
+                    constants.O_NOFOLLOW, 0o600);
+            }
+            catch (error) {
+                if ((await observePath(ignore)).kind === 'missing')
+                    throw error;
+            }
+            if (created !== undefined) {
+                try {
+                    await assertCurrent();
+                    await created.writeFile('*\n');
+                    await created.sync();
+                    const stats = await created.stat();
+                    observation = await observePath(ignore);
+                    if (observation.kind !== 'file' ||
+                        observation.stats?.dev !== stats.dev ||
+                        observation.stats.ino !== stats.ino) {
+                        throw new Error(`Private-state ignore file changed during creation: ${ignore}`);
+                    }
+                    await assertCurrent();
+                }
+                finally {
+                    await created.close();
+                }
+            }
+            observation = await observePath(ignore);
+        }
+        if (observation.kind !== 'file' || observation.stats === null)
+            throw new Error(`Private-state ignore path is not a regular file: ${ignore}`);
+        const handle = await open(ignore, constants.O_RDWR | constants.O_APPEND | constants.O_NOFOLLOW);
+        try {
+            const stats = await handle.stat();
+            if (!stats.isFile() ||
+                stats.dev !== observation.stats.dev ||
+                stats.ino !== observation.stats.ino) {
+                throw new Error(`Private-state ignore identity changed: ${ignore}`);
+            }
+            const readText = async () => {
+                const bytes = Buffer.alloc(MAX_IGNORE_BYTES + 1);
+                let length = 0;
+                while (length < bytes.length) {
+                    const read = await handle.read(bytes, length, bytes.length - length, length);
+                    if (read.bytesRead === 0)
+                        break;
+                    length += read.bytesRead;
+                }
+                if (length > MAX_IGNORE_BYTES)
+                    throw new Error(`Private-state ignore file exceeds ${MAX_IGNORE_BYTES} bytes: ${ignore}`);
+                return new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length));
+            };
+            const text = await readText();
+            await assertCurrent();
+            if (!hasFinalIgnoreAll(text)) {
+                // O_APPEND preserves existing bytes even if another writer extends the
+                // file after it was read; no user file is replaced or truncated.
+                await handle.writeFile(`${text.endsWith('\n') || text === '' ? '' : '\n'}*\n`);
+                await handle.sync();
+            }
+            const current = await observePath(ignore);
+            if (current.kind !== 'file' ||
+                current.stats?.dev !== stats.dev ||
+                current.stats.ino !== stats.ino ||
+                !hasFinalIgnoreAll(await readText())) {
+                throw new Error(`Private-state ignore file changed during preparation: ${ignore}`);
+            }
+            await assertCurrent();
+            return succeeded(null);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        return failed(diagnosticCodes.initTargetUnsafe, `Cannot prepare private state: ${errorMessage(error)}`, {
+            nextAction: `Restore real .pappra/${directory} directories and a writable regular .gitignore; existing state and rules were preserved.`,
+        });
+    }
+}

package/dist/infra/process-identity.d.ts

@@ -0,0 +1,12 @@
+export interface LocalProcessIdentity {
+    readonly schema: 'pappra/local-process/1';
+    readonly pid: number;
+    readonly machine: string;
+    readonly boot: string;
+    readonly namespace: string;
+    readonly start: string;
+}
+export declare function captureProcessIdentity(pid?: number): LocalProcessIdentity | null;
+/** Identity mismatches prove replacement only on this exact physical machine. */
+export declare function isLocalProcessIdentity(value: unknown): value is LocalProcessIdentity;
+export declare function observeProcessIdentity(value: unknown): 'alive' | 'dead' | 'unknown';

package/dist/infra/process-identity.js

@@ -0,0 +1,142 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+let host;
+let self;
+const hash = (value) => `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+function command(file, args) {
+    const result = spawnSync(file, args, {
+        encoding: 'utf8',
+        env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+        timeout: 2000,
+        maxBuffer: 32 * 1024,
+        shell: false,
+    });
+    return !result.error && result.status === 0 ? result.stdout.trim() : null;
+}
+function hostIdentity() {
+    if (host !== undefined)
+        return host;
+    try {
+        if (process.platform === 'linux') {
+            const machine = fs.readFileSync('/etc/machine-id', 'utf8').trim();
+            const boot = fs
+                .readFileSync('/proc/sys/kernel/random/boot_id', 'utf8')
+                .trim();
+            const namespace = fs.readlinkSync('/proc/self/ns/pid');
+            if (!/^[a-f0-9]{32}$/i.test(machine) ||
+                !/^[a-f0-9-]{36}$/i.test(boot) ||
+                !/^pid:\[[0-9]+\]$/.test(namespace))
+                return (host = null);
+            return (host = {
+                machine: hash(machine.toLowerCase()),
+                boot: hash(boot.toLowerCase()),
+                namespace,
+            });
+        }
+        if (process.platform === 'darwin') {
+            const boot = command('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid']);
+            const platform = command('/usr/sbin/ioreg', [
+                '-rd1',
+                '-c',
+                'IOPlatformExpertDevice',
+            ]);
+            const machine = platform?.match(/"IOPlatformUUID"\s*=\s*"([a-f0-9-]{36})"/i)?.[1];
+            if (!boot || !/^[a-f0-9-]{36}$/i.test(boot) || !machine)
+                return (host = null);
+            return (host = {
+                machine: hash(machine.toLowerCase()),
+                boot: hash(boot.toLowerCase()),
+                namespace: 'native',
+            });
+        }
+    }
+    catch {
+        /* Missing OS identity is not evidence of a dead owner. */
+    }
+    return (host = null);
+}
+function processStart(pid) {
+    try {
+        if (process.platform === 'linux') {
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+            const close = stat.lastIndexOf(')');
+            const fields = stat
+                .slice(close + 2)
+                .trim()
+                .split(/\s+/);
+            const ticks = fields[19];
+            return close > 0 && ticks && /^[0-9]+$/.test(ticks) ? ticks : null;
+        }
+        if (process.platform === 'darwin') {
+            const start = command('/bin/ps', ['-p', String(pid), '-o', 'lstart=']);
+            return start &&
+                /^[A-Za-z]{3} [A-Za-z]{3}\s+[0-9]+ [0-9:]{8} [0-9]{4}$/.test(start)
+                ? start
+                : null;
+        }
+    }
+    catch {
+        /* The caller distinguishes exit from unavailable observation. */
+    }
+    return null;
+}
+export function captureProcessIdentity(pid = process.pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    if (pid === process.pid && self !== undefined)
+        return self;
+    const currentHost = hostIdentity();
+    const start = processStart(pid);
+    const identity = currentHost && start
+        ? {
+            schema: 'pappra/local-process/1',
+            pid,
+            ...currentHost,
+            start,
+        }
+        : null;
+    if (pid === process.pid)
+        self = identity;
+    return identity;
+}
+/** Identity mismatches prove replacement only on this exact physical machine. */
+export function isLocalProcessIdentity(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const row = value;
+    return !(row.schema !== 'pappra/local-process/1' ||
+        !Number.isSafeInteger(row.pid) ||
+        Number(row.pid) <= 0 ||
+        typeof row.machine !== 'string' ||
+        typeof row.boot !== 'string' ||
+        typeof row.namespace !== 'string' ||
+        typeof row.start !== 'string' ||
+        row.start.length === 0 ||
+        row.start.length > 128 ||
+        !/^sha256:[0-9a-f]{64}$/.test(String(row.machine)) ||
+        !/^sha256:[0-9a-f]{64}$/.test(String(row.boot)) ||
+        !/^(?:native|pid:\[[0-9]+\])$/.test(String(row.namespace)));
+}
+export function observeProcessIdentity(value) {
+    if (!isLocalProcessIdentity(value))
+        return 'unknown';
+    const row = value;
+    const currentHost = hostIdentity();
+    if (!currentHost || row.machine !== currentHost.machine)
+        return 'unknown';
+    if (row.boot !== currentHost.boot)
+        return 'dead';
+    if (row.namespace !== currentHost.namespace)
+        return 'unknown';
+    try {
+        process.kill(Number(row.pid), 0);
+    }
+    catch (error) {
+        return error.code === 'ESRCH'
+            ? 'dead'
+            : 'unknown';
+    }
+    const start = processStart(Number(row.pid));
+    return start === null ? 'unknown' : start === row.start ? 'alive' : 'dead';
+}

package/dist/infra/validation.d.ts

@@ -0,0 +1,5 @@
+/** Decode external JSON as unknown; domain validators establish usable shapes. */
+export declare function object(value: unknown): value is Record<string, unknown>;
+export declare function text(value: unknown): value is string;
+export declare function errorCode(error: unknown): string | undefined;
+export declare function parseJson(text: string): unknown;

package/dist/infra/validation.js

@@ -0,0 +1,15 @@
+/** Decode external JSON as unknown; domain validators establish usable shapes. */
+export function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function text(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function errorCode(error) {
+    return object(error) && typeof error['code'] === 'string'
+        ? error['code']
+        : undefined;
+}
+export function parseJson(text) {
+    return JSON.parse(text);
+}

package/dist/init.d.ts

@@ -0,0 +1 @@
+export * from './app/init.js';

package/dist/init.js

@@ -0,0 +1,6 @@
+// Core entrypoint for workspace initialization.
+//
+// The implementation lives in `src/app/init.ts`; this barrel keeps the
+// published `@phyzess/pappra/init` path independent of the internal `app/`
+// layout.
+export * from './app/init.js';

package/dist/install/apply.d.ts

@@ -2,6 +2,7 @@ import type { Diagnostic } from '../schemas/diagnostics.js';
 import { type InstallJournal, type ManagedFileEntry, type RuntimeManifest, type WorkspaceInstallManifest } from '../schemas/install.js';
 import type { InitPlan } from '../schemas/init.js';
 import type { PlannedFileContent } from './plan.js';
+import { type Outcome } from '../schemas/outcome.js';
 export interface FileIdentity {
     readonly dev: number;
     readonly ino: number;
@@ -28,7 +29,10 @@ export type ManagedApplyBegin = {
     readonly residualPaths: readonly string[];
 };
 export declare function beginManagedApply(root: string, plan: InitPlan, writes: readonly PlannedFileContent[], rootIdentity: FileIdentity): Promise<ManagedApplyBegin>;
-export declare function recordManagedFile(context: ManagedApplyContext, path: string, digest: string, identity: FileIdentity): Promise<{
+export declare function recordManagedFile(context: ManagedApplyContext, path: string, digest: string, identity: FileIdentity, replacement?: {
+    readonly backupRef: string;
+    readonly backupDigest: string;
+}): Promise<{
     readonly ok: true;
 } | {
     readonly ok: false;
@@ -56,6 +60,10 @@ export interface ManagedMachineUpdateResult {
     readonly updateInstallId?: string;
     readonly journalPath?: string;
 }
+/** Read-only gate shared by initial planning and every apply, including no-op plans. */
+export declare function inspectWorkspaceInstallReadiness(root: string, ownLock?: boolean): Promise<Outcome<null>>;
+/** Serialize a zero-file apply with installation and recovery, without adding an empty journal. */
+export declare function verifyWorkspaceInstallReady(root: string): Promise<Outcome<null>>;
 /** Updates the managed machine.json runtime location after a verified install. */
 export declare function updateMachineRuntime(root: string, runtime: RuntimeManifest, options?: UpdateMachineRuntimeOptions): Promise<ManagedMachineUpdateResult>;
 export interface ManagedWorkspaceState {