@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/dist/install/ownership.js

@@ -7,6 +7,9 @@ import { errorMessage, failed, succeeded } from '../schemas/outcome.js';
 import { fileIdentitySchema, installJournalSchema, installLockSchema, workspaceInstallManifestSchema, } from '../schemas/install.js';
 import { isPathInside, samePath } from '../schemas/paths.js';
 import { observePath, readTextFileBounded, resolveRealpath, sha256Digest, } from '../infra/fs.js';
+import { ensurePrivateState } from '../infra/private-state.js';
+import { publishPrivateLock } from '../infra/private-lock.js';
+import { captureProcessIdentity } from '../infra/process-identity.js';
 export function workspaceInstallPaths(root) {
     const localDir = join(root, '.pappra', 'local');
     return {
@@ -143,6 +146,11 @@ export async function writeBytesAtomic(path, bytes, boundaryRoot) {
         const boundary = await ensureStatePathBoundary(boundaryRoot, path);
         if (!boundary.ok)
             return boundary;
+        if (isPathInside(workspaceInstallPaths(boundaryRoot).localDir, path)) {
+            const prepared = await ensurePrivateState(boundaryRoot);
+            if (!prepared.ok)
+                return prepared;
+        }
     }
     const temporary = `${path}.tmp-${randomUUID()}`;
     try {
@@ -182,6 +190,18 @@ export async function acquireInstallLock(path, operation, target, boundaryRoot)
                 existing: null,
             };
         }
+        if (isPathInside(workspaceInstallPaths(boundaryRoot).localDir, path)) {
+            const prepared = await ensurePrivateState(boundaryRoot);
+            if (!prepared.ok)
+                return {
+                    ok: false,
+                    status: 'failed',
+                    lock: null,
+                    path,
+                    message: prepared.message,
+                    existing: null,
+                };
+        }
     }
     try {
         await mkdir(dirname(path), { recursive: true });
@@ -202,10 +222,19 @@ export async function acquireInstallLock(path, operation, target, boundaryRoot)
         operation,
         target,
         pid: process.pid,
+        ...(captureProcessIdentity() === null
+            ? {}
+            : { process_identity: captureProcessIdentity() }),
         createdAt: new Date().toISOString(),
     };
     try {
-        await writeNewFile(path, Buffer.from(`${JSON.stringify(lock, null, 2)}\n`));
+        await publishPrivateLock(path, Buffer.from(`${JSON.stringify(lock, null, 2)}\n`), async () => {
+            if (boundaryRoot !== undefined) {
+                const boundary = await ensureStatePathBoundary(boundaryRoot, path);
+                if (!boundary.ok)
+                    throw new Error(boundary.message);
+            }
+        });
         return {
             ok: true,
             status: 'acquired',

package/dist/install/references.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeManifest } from '../schemas/install.js';
+import { type Outcome } from '../schemas/outcome.js';
+export interface RuntimeReferenceReport {
+    readonly coverage: 'registered-workspaces-only';
+    readonly active: readonly {
+        workspaceRoot: string;
+        workspaceId: string;
+        executable: string;
+    }[];
+    readonly unknown: readonly string[];
+    /** A registry never proves that no unregistered workspace exists. */
+    readonly unregisteredCoverage: 'unknown';
+}
+export declare function runtimeReferencesDirectory(dataDir: string): string;
+/** Lexical and real-path aliases of the same global data directory are one runtime. */
+export declare function runtimeBindingMatches(dataDir: string, version: string, binding: {
+    readonly version: string;
+    readonly executable: string;
+} | null | undefined): Promise<boolean>;
+/** Reads only explicitly registered roots. No home-directory discovery occurs. */
+export declare function inspectRuntimeReferences(dataDir: string, version: string): Promise<RuntimeReferenceReport>;
+export interface RuntimeReferenceLease {
+    readonly path: string;
+    readonly lockPath: string;
+    readonly release: () => Promise<Outcome<null>>;
+}
+/**
+ * Publish before machine binding while holding the runtime's deletion/install
+ * lock. A crash cannot create a new binding absent from the explicit registry.
+ */
+export declare function beginRuntimeReference(root: string, runtime: RuntimeManifest): Promise<Outcome<RuntimeReferenceLease>>;

package/dist/install/references.js

@@ -0,0 +1,208 @@
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { z } from 'zod';
+import { observePath, resolveRealpath, sha256Digest } from '../infra/fs.js';
+import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
+import { isPathInside } from '../schemas/paths.js';
+import { failed, succeeded } from '../schemas/outcome.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { acquireInstallLock, ensureStatePathBoundary, readJsonDocument, releaseInstallLock, writeJsonAtomic, } from './ownership.js';
+const referenceSchema = z.strictObject({
+    schema: z.literal('pappra/runtime-reference/1'),
+    workspaceRoot: z.string().min(1).max(4096).refine(isAbsolute),
+    workspaceId: z.uuid(),
+    rootIdentity: z.strictObject({
+        dev: z.number().int().nonnegative(),
+        ino: z.number().int().nonnegative(),
+    }),
+    intendedRuntime: z.strictObject({
+        version: z.string().min(1).max(128),
+        executable: z.string().min(1).max(4096),
+        runtimeRoot: z.string().min(1).max(4096),
+    }),
+    registeredAt: z.iso.datetime({ offset: true }),
+});
+export function runtimeReferencesDirectory(dataDir) {
+    return join(resolve(dataDir), 'runtime-references');
+}
+/** Lexical and real-path aliases of the same global data directory are one runtime. */
+export async function runtimeBindingMatches(dataDir, version, binding) {
+    if (binding?.version !== version)
+        return false;
+    const target = join(resolve(dataDir), 'runtimes', version);
+    const executable = resolve(binding.executable);
+    if (isPathInside(target, executable))
+        return true;
+    const realTarget = await resolveRealpath(target);
+    const realExecutable = await resolveRealpath(executable);
+    return (realTarget !== null &&
+        realExecutable !== null &&
+        isPathInside(realTarget, realExecutable));
+}
+/** Reads only explicitly registered roots. No home-directory discovery occurs. */
+export async function inspectRuntimeReferences(dataDir, version) {
+    const active = [];
+    const unknown = [];
+    const canonicalDataDir = (await resolveRealpath(dataDir)) ?? resolve(dataDir);
+    const directory = runtimeReferencesDirectory(canonicalDataDir);
+    const report = () => ({
+        coverage: 'registered-workspaces-only',
+        active,
+        unknown,
+        unregisteredCoverage: 'unknown',
+    });
+    const boundary = await ensureStatePathBoundary(canonicalDataDir, directory);
+    if (!boundary.ok) {
+        unknown.push('registry_path_unsafe');
+        return report();
+    }
+    const presence = await observePath(directory).catch(() => null);
+    if (presence?.kind === 'missing') {
+        unknown.push('registry_missing');
+        return report();
+    }
+    if (presence?.kind !== 'directory') {
+        unknown.push('registry_unreadable_or_redirected');
+        return report();
+    }
+    let names;
+    try {
+        names = (await readdir(directory)).sort();
+    }
+    catch {
+        unknown.push('registry_unreadable');
+        return report();
+    }
+    if (names.length > 4096) {
+        unknown.push('registry_entry_limit');
+        return report();
+    }
+    for (const name of names) {
+        if (!/^sha256-[0-9a-f]{64}\.json$/.test(name)) {
+            unknown.push('unexpected_registry_entry');
+            continue;
+        }
+        const read = await readJsonDocument(join(directory, name), referenceSchema);
+        if (!read.value) {
+            unknown.push(`reference_unreadable:${name}`);
+            continue;
+        }
+        const entry = read.value;
+        const root = await observePath(entry.workspaceRoot).catch(() => null);
+        const canonical = await resolveRealpath(entry.workspaceRoot);
+        if (root?.kind !== 'directory' ||
+            !root.stats ||
+            canonical !== entry.workspaceRoot ||
+            root.stats.dev !== entry.rootIdentity.dev ||
+            root.stats.ino !== entry.rootIdentity.ino) {
+            unknown.push(`workspace_missing_or_replaced:${name}`);
+            continue;
+        }
+        const workspace = await inspectWorkspaceConfig(entry.workspaceRoot);
+        if (workspace.value?.workspaceId !== entry.workspaceId) {
+            unknown.push(`workspace_identity_unknown:${name}`);
+            continue;
+        }
+        const machine = await inspectMachineConfig(entry.workspaceRoot);
+        if (!machine.value) {
+            unknown.push(`machine_binding_unknown:${name}`);
+            continue;
+        }
+        const binding = machine.value.runtime;
+        if (binding && (await runtimeBindingMatches(dataDir, version, binding)))
+            active.push({
+                workspaceRoot: entry.workspaceRoot,
+                workspaceId: entry.workspaceId,
+                executable: binding.executable,
+            });
+    }
+    return report();
+}
+/**
+ * Publish before machine binding while holding the runtime's deletion/install
+ * lock. A crash cannot create a new binding absent from the explicit registry.
+ */
+export async function beginRuntimeReference(root, runtime) {
+    const canonical = await resolveRealpath(root);
+    const observation = canonical === null ? null : await observePath(canonical).catch(() => null);
+    const workspace = canonical === null ? null : await inspectWorkspaceConfig(canonical);
+    if (!canonical ||
+        observation?.kind !== 'directory' ||
+        !observation.stats ||
+        !workspace?.value)
+        return failed(diagnosticCodes.initPlanStale, 'Cannot register a runtime reference for an unverified workspace root.');
+    const selectedDataDir = dirname(dirname(resolve(runtime.runtimeRoot)));
+    if (join(selectedDataDir, 'runtimes', runtime.runtimeVersion) !==
+        resolve(runtime.runtimeRoot) ||
+        !isPathInside(runtime.runtimeRoot, runtime.executable))
+        return failed(diagnosticCodes.initTargetUnsafe, 'Runtime reference is not inside its exact version directory.');
+    const dataDir = (await resolveRealpath(selectedDataDir)) ?? selectedDataDir;
+    const lockPath = join(dataDir, 'runtimes', '.locks', `${runtime.runtimeVersion}.lock`);
+    const entry = {
+        schema: 'pappra/runtime-reference/1',
+        workspaceRoot: canonical,
+        workspaceId: workspace.value.workspaceId,
+        rootIdentity: { dev: observation.stats.dev, ino: observation.stats.ino },
+        intendedRuntime: {
+            version: runtime.runtimeVersion,
+            executable: runtime.executable,
+            runtimeRoot: runtime.runtimeRoot,
+        },
+        registeredAt: new Date().toISOString(),
+    };
+    const key = sha256Digest(JSON.stringify([
+        canonical,
+        entry.workspaceId,
+        entry.rootIdentity.dev,
+        entry.rootIdentity.ino,
+    ])).replace(':', '-');
+    const path = join(runtimeReferencesDirectory(dataDir), `${key}.json`);
+    const boundary = await ensureStatePathBoundary(dataDir, path);
+    if (!boundary.ok)
+        return boundary;
+    let existing = await readJsonDocument(path, referenceSchema);
+    const unchanged = existing.value &&
+        existing.value.workspaceRoot === canonical &&
+        existing.value.workspaceId === entry.workspaceId &&
+        existing.value.rootIdentity.dev === entry.rootIdentity.dev &&
+        existing.value.rootIdentity.ino === entry.rootIdentity.ino &&
+        JSON.stringify(existing.value.intendedRuntime) ===
+            JSON.stringify(entry.intendedRuntime);
+    if (unchanged && (await observePath(lockPath)).kind === 'missing') {
+        const machine = await inspectMachineConfig(canonical);
+        if (machine.value?.runtime?.version === runtime.runtimeVersion &&
+            machine.value.runtime.executable === runtime.executable) {
+            // This binding is already published and protected from deletion by its
+            // verified registry entry. A read-only repeat needs no registration lease.
+            return succeeded({
+                path,
+                lockPath,
+                release: async () => succeeded(null),
+            });
+        }
+    }
+    const lock = await acquireInstallLock(lockPath, 'update-machine-runtime', runtime.runtimeRoot, dataDir);
+    if (!lock.ok || !lock.lock)
+        return failed(diagnosticCodes.initApplyResidual, lock.message ?? 'Runtime reference registration is locked.');
+    const release = () => releaseInstallLock(lockPath, lock.lock.token);
+    existing = await readJsonDocument(path, referenceSchema);
+    if (existing.exists &&
+        (!existing.value ||
+            existing.value.workspaceRoot !== canonical ||
+            existing.value.workspaceId !== entry.workspaceId ||
+            existing.value.rootIdentity.dev !== entry.rootIdentity.dev ||
+            existing.value.rootIdentity.ino !== entry.rootIdentity.ino)) {
+        await release();
+        return failed(diagnosticCodes.initApplyResidual, 'Existing runtime reference is unreadable or belongs to another workspace identity; it was preserved.');
+    }
+    if (existing.value &&
+        JSON.stringify(existing.value.intendedRuntime) ===
+            JSON.stringify(entry.intendedRuntime))
+        return succeeded({ path, lockPath, release });
+    const written = await writeJsonAtomic(path, entry, dataDir);
+    if (!written.ok) {
+        await release();
+        return written;
+    }
+    return succeeded({ path, lockPath, release });
+}

package/dist/install/repair.d.ts

@@ -0,0 +1,37 @@
+import { type PrivateLockObservation } from '../infra/private-lock.js';
+import { type LocalResetResult } from './reset-local.js';
+export interface RepairOptions {
+    readonly root: string;
+    readonly runtimeVersion?: string;
+    readonly installId?: string;
+    readonly dataDir?: string;
+    readonly apply?: boolean;
+    /** Explicit operator assertion that every potentially affected writer has stopped. */
+    readonly quarantineUnownedLocks?: boolean;
+    readonly resetLocal?: boolean;
+    readonly allWritersStopped?: boolean;
+    /** Test-only dependency seam; never supplied by the CLI. */
+    readonly afterLocalArchive?: () => Promise<void> | void;
+}
+export interface RepairEntry {
+    readonly journal: string;
+    readonly installId: string;
+    readonly operation: string;
+    readonly status: string;
+}
+export interface RepairResult {
+    readonly ok: boolean;
+    readonly mode: 'plan' | 'apply';
+    readonly entries: readonly RepairEntry[];
+    readonly repaired: readonly string[];
+    readonly locks: readonly string[];
+    readonly errors: readonly string[];
+    readonly lockStates: readonly Pick<PrivateLockObservation, 'file' | 'state'>[];
+    readonly preserved: readonly string[];
+    readonly quarantined: readonly string[];
+    readonly reset: LocalResetResult | null;
+}
+/** Bounded private lock inventory shared by doctor and explicit repair. */
+export declare function inspectWorkspaceLocks(root: string): Promise<readonly PrivateLockObservation[]>;
+/** Explicit, bounded journal recovery. Preview never removes a lock or changes state. */
+export declare function repairInstall(options: RepairOptions): Promise<RepairResult>;