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

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 {

package/dist/install/apply.js

@@ -1,13 +1,14 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 import { createDiagnostic } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
 import { managedFileEntrySchema, } from '../schemas/install.js';
 import { machineConfigSchema } from '../schemas/machine.js';
 import { acquireInstallLock, backupPath, createManifest, ensureStatePathBoundary, ensureWorkspaceStateBoundary, inspectOwnedFile, journalPath, readInstallJournal, readWorkspaceManifest, releaseInstallLock, rootIdentityOf, scanJournalDirectory, workspaceInstallPaths, writeInstallJournal, writeJsonAtomic, writeWorkspaceManifest, } from './ownership.js';
 import { observePath, sha256Digest } from '../infra/fs.js';
-import { errorMessage } from '../schemas/outcome.js';
+import { beginRuntimeReference } from './references.js';
+import { errorMessage, failed, succeeded, } from '../schemas/outcome.js';
 function diagnostic(code, message, hint, source) {
     return createDiagnostic({
         code,
@@ -71,12 +72,12 @@ export async function beginManagedApply(root, plan, writes, rootIdentity) {
         };
     }
     if (writes.length !== plan.files.length ||
-        plan.files.some((file) => file.operation !== 'create')) {
+        plan.files.some((file) => !['create', 'replace-managed'].includes(file.operation))) {
         return {
             ok: false,
             status: 'invalid',
             diagnostics: [
-                diagnostic(diagnosticCodes.initApplyUnsupported, 'P04 managed apply currently supports create-only plans.', 'Regenerate the plan; managed replacement is not silently emulated.', root),
+                diagnostic(diagnosticCodes.initApplyUnsupported, 'Managed apply supports only create and managed replacement plans.', 'Regenerate the plan with supported file operations.', root),
             ],
             residualPaths: [],
         };
@@ -105,12 +106,12 @@ export async function beginManagedApply(root, plan, writes, rootIdentity) {
     }
     const existingPaths = new Set(manifest.entries.map((entry) => entry.path));
     for (const file of plan.files) {
-        if (existingPaths.has(file.path)) {
+        if ((file.operation === 'create') === existingPaths.has(file.path)) {
             return {
                 ok: false,
                 status: 'invalid',
                 diagnostics: [
-                    diagnostic(diagnosticCodes.initTargetExists, `A managed file entry already exists for ${file.path}.`, 'Inspect ownership state; Pappra does not overwrite managed files as create.', workspaceInstallPaths(root).manifestPath),
+                    diagnostic(diagnosticCodes.initTargetExists, `Managed ownership does not match the planned operation for ${file.path}.`, 'Inspect ownership state; replacements require an existing managed entry.', workspaceInstallPaths(root).manifestPath),
                 ],
                 residualPaths: [],
             };
@@ -127,8 +128,59 @@ export async function beginManagedApply(root, plan, writes, rootIdentity) {
             residualPaths: [],
         };
     }
+    const currentManifest = await readWorkspaceManifest(root);
+    const priorJournal = await findIncompleteWorkspaceJournal(root);
+    if (currentManifest.digest !== manifestRead.digest ||
+        priorJournal.incomplete !== null ||
+        priorJournal.unreadable.length > 0) {
+        await releaseInstallLock(lock.path, lock.lock.token);
+        return {
+            ok: false,
+            status: 'invalid',
+            residualPaths: [],
+            diagnostics: [
+                diagnostic(diagnosticCodes.initPlanStale, 'Managed ownership changed or an incomplete journal requires recovery.', 'Run pappra repair to inspect interrupted installs, then regenerate the plan.', priorJournal.incomplete ?? workspaceInstallPaths(root).manifestPath),
+            ],
+        };
+    }
     const installId = randomUUID();
     const journalFile = journalPath(root, installId);
+    const manifestBackupSteps = [];
+    if (plan.files.some((file) => file.operation === 'replace-managed')) {
+        const backup = backupPath(root, installId, 'install-manifest.json');
+        try {
+            const boundary = await ensureStatePathBoundary(root, backup);
+            if (!boundary.ok)
+                throw new Error(boundary.message);
+            const bytes = await readFile(workspaceInstallPaths(root).manifestPath);
+            if (sha256Digest(bytes) !== manifestRead.digest)
+                throw new Error('Ownership changed before backup.');
+            await mkdir(dirname(backup), { recursive: true });
+            await writeFile(backup, bytes, { flag: 'wx', mode: 0o600 });
+            manifestBackupSteps.push({
+                name: 'manifest-backup',
+                status: 'ok',
+                at: now(),
+                detail: relative(root, backup).split(sep).join('/'),
+            }, {
+                name: 'manifest-backup-digest',
+                status: 'ok',
+                at: now(),
+                detail: sha256Digest(bytes),
+            });
+        }
+        catch (error) {
+            await releaseInstallLock(lock.path, lock.lock.token);
+            return {
+                ok: false,
+                status: 'failed',
+                residualPaths: [],
+                diagnostics: [
+                    diagnostic(diagnosticCodes.initApplyFailed, `Cannot back up managed ownership: ${errorMessage(error)}`, 'Inspect the workspace state; no target was changed.', journalFile),
+                ],
+            };
+        }
+    }
     let journal = {
         schema: 'pappra/install-journal/1',
         installId,
@@ -141,6 +193,7 @@ export async function beginManagedApply(root, plan, writes, rootIdentity) {
         updatedAt: now(),
         steps: [
             { name: 'lock-acquired', status: 'ok', at: now(), detail: lock.path },
+            ...manifestBackupSteps,
             ...writes.map((write) => ({
                 name: `pending:${write.path}`,
                 status: 'ok',
@@ -148,13 +201,19 @@ export async function beginManagedApply(root, plan, writes, rootIdentity) {
                 detail: write.digest,
             })),
         ],
-        entries: writes.map((write) => ({
+        entries: writes.map((write, index) => ({
             path: write.path,
             status: 'pending',
             digest: write.digest,
             identity: null,
-            backupRef: null,
-            backupDigest: null,
+            backupRef: plan.files[index]?.operation === 'replace-managed'
+                ? relative(root, backupPath(root, installId, write.path))
+                    .split(sep)
+                    .join('/')
+                : null,
+            backupDigest: plan.files[index]?.operation === 'replace-managed'
+                ? plan.files[index].expectedBeforeDigest
+                : null,
             detail: null,
         })),
         residuals: [],
@@ -190,7 +249,7 @@ export async function beginManagedApply(root, plan, writes, rootIdentity) {
         },
     };
 }
-export async function recordManagedFile(context, path, digest, identity) {
+export async function recordManagedFile(context, path, digest, identity, replacement) {
     if (!context.plannedPaths.includes(path)) {
         return {
             ok: false,
@@ -204,6 +263,8 @@ export async function recordManagedFile(context, path, digest, identity) {
             ...entry,
             status: 'created',
             identity,
+            backupRef: replacement?.backupRef ?? null,
+            backupDigest: replacement?.backupDigest ?? null,
             detail: null,
         }
         : entry);
@@ -222,14 +283,28 @@ export async function recordManagedFile(context, path, digest, identity) {
         };
     }
     context.journal = journal;
-    context.entries.push(manifestEntry(context.installId, path, digest, identity));
+    context.entries.push({
+        ...manifestEntry(context.installId, path, digest, identity),
+        ...(replacement === undefined
+            ? {}
+            : {
+                operation: 'replace-managed',
+                beforeDigest: replacement.backupDigest,
+                backupRef: replacement.backupRef,
+                backupDigest: replacement.backupDigest,
+            }),
+    });
     return { ok: true };
 }
 export async function completeManagedApply(context) {
     const appliedJournal = appendStep({ ...context.journal, status: 'applied', updatedAt: now() }, 'files-created', context.entries.map((entry) => entry.path).join(', '));
     await writeInstallJournal(context.journalFile, appliedJournal, context.root);
     context.journal = appliedJournal;
-    const entries = [...context.manifest.entries, ...context.entries];
+    const changedPaths = new Set(context.entries.map((entry) => entry.path));
+    const entries = [
+        ...context.manifest.entries.filter((entry) => !changedPaths.has(entry.path)),
+        ...context.entries,
+    ];
     const manifest = {
         ...context.manifest,
         entries,
@@ -349,8 +424,97 @@ async function findIncompleteWorkspaceJournal(root) {
     }
     return { incomplete, unreadable };
 }
+/** Read-only gate shared by initial planning and every apply, including no-op plans. */
+export async function inspectWorkspaceInstallReadiness(root, ownLock = false) {
+    const paths = workspaceInstallPaths(root);
+    const boundary = await ensureStatePathBoundary(root, paths.lockPath);
+    if (!boundary.ok)
+        return boundary;
+    if (!ownLock && (await observePath(paths.lockPath)).kind !== 'missing') {
+        return failed(diagnosticCodes.initApplyFailed, 'Workspace installation is locked.', {
+            nextAction: 'Wait for the active init, or run pappra repair to inspect an interrupted install.',
+        });
+    }
+    const scan = await findIncompleteWorkspaceJournal(root);
+    if (scan.incomplete !== null || scan.unreadable.length > 0) {
+        return failed(diagnosticCodes.initPlanStale, `Workspace installation requires recovery: ${scan.incomplete ?? scan.unreadable[0]}`, {
+            nextAction: 'Run pappra repair for this workspace, then regenerate the init plan.',
+        });
+    }
+    const manifest = await readWorkspaceManifest(root);
+    if (manifest.diagnostics.length > 0)
+        return failed(diagnosticCodes.initPlanStale, manifest.diagnostics[0].message, { nextAction: 'Inspect install-manifest.json before retrying init.' });
+    if (manifest.value !== null) {
+        const identity = await rootIdentityOf(root);
+        if (manifest.value.workspaceRoot !== root ||
+            identity === null ||
+            manifest.value.rootIdentity.dev !== identity.dev ||
+            manifest.value.rootIdentity.ino !== identity.ino) {
+            return failed(diagnosticCodes.initPlanStale, 'Workspace installation belongs to another root identity.', {
+                nextAction: 'Inspect the local install manifest; it was not adopted or rewritten.',
+            });
+        }
+    }
+    return succeeded(null);
+}
+/** Serialize a zero-file apply with installation and recovery, without adding an empty journal. */
+export async function verifyWorkspaceInstallReady(root) {
+    const paths = workspaceInstallPaths(root);
+    const lock = await acquireInstallLock(paths.lockPath, 'apply-workspace-files', root, root);
+    if (!lock.ok || lock.lock === null)
+        return failed(diagnosticCodes.initApplyFailed, lock.message ?? 'Workspace installation is locked.', { nextAction: 'Run pappra repair to inspect the install lock.' });
+    let result;
+    try {
+        result = await inspectWorkspaceInstallReadiness(root, true);
+    }
+    finally {
+        const released = await releaseInstallLock(lock.path, lock.lock.token);
+        if (!released.ok)
+            result = released;
+    }
+    return result;
+}
 /** Updates the managed machine.json runtime location after a verified install. */
 export async function updateMachineRuntime(root, runtime, options = {}) {
+    const lease = await beginRuntimeReference(root, runtime);
+    if (!lease.ok)
+        return {
+            ok: false,
+            status: 'failed',
+            residualPaths: [],
+            diagnostics: [
+                diagnostic(lease.code, lease.message, lease.nextAction ?? 'Inspect the runtime reference state.', runtime.runtimeRoot),
+            ],
+        };
+    let result;
+    try {
+        result = await updateMachineRuntimeAt(root, runtime, options);
+    }
+    catch (error) {
+        result = {
+            ok: false,
+            status: 'failed',
+            residualPaths: [],
+            diagnostics: [
+                diagnostic(diagnosticCodes.initApplyFailed, errorMessage(error), 'Inspect the workspace binding journal before retrying.', root),
+            ],
+        };
+    }
+    const released = await lease.value.release();
+    return released.ok
+        ? result
+        : {
+            ...result,
+            ok: false,
+            status: result.ok ? 'partial' : result.status,
+            residualPaths: [...result.residualPaths, lease.value.lockPath],
+            diagnostics: [
+                ...result.diagnostics,
+                diagnostic(released.code, released.message, 'Inspect the retained runtime lock before retrying.', lease.value.lockPath),
+            ],
+        };
+}
+async function updateMachineRuntimeAt(root, runtime, options) {
     const stateBoundary = await ensureWorkspaceStateBoundary(root);
     if (!stateBoundary.ok) {
         return {

package/dist/install/dependencies.d.ts

@@ -0,0 +1,38 @@
+export interface PackageDependencyManifest {
+    readonly required: readonly string[];
+    readonly optional: readonly string[];
+}
+/** Reads the declared dependency names of one package without guessing ranges. */
+export declare function readPackageDependencyManifest(packageRoot: string): Promise<PackageDependencyManifest | null>;
+/**
+ * Resolves the exact installed copy that Node would load for `name` from
+ * `packageRoot`, walking the same ancestor chain Node resolves through. Every
+ * candidate is realpath-resolved and name-checked so a symlinked store entry or
+ * a mismatched directory is never mistaken for the requested dependency.
+ */
+export declare function resolveInstalledDependency(packageRoot: string, name: string): Promise<string | null>;
+export interface DependencyMaterialization {
+    readonly ok: boolean;
+    /** Destination directories created by this run, in copy order. */
+    readonly copied: readonly string[];
+    /** Destination slots satisfied by an already-materialized exact copy. */
+    readonly reused: readonly string[];
+    /** Optional dependencies that are absent from the installed tree. */
+    readonly skippedOptional: readonly string[];
+    /** Problems that make the materialized tree unsafe to publish. */
+    readonly problems: readonly string[];
+}
+export interface MaterializeDependenciesOptions {
+    readonly sourceRoot: string;
+    readonly targetRoot: string;
+    /** Upper bound on visited packages; guards against pathological trees. */
+    readonly maxPackages?: number;
+}
+/**
+ * Materializes the installed dependency closure of `sourceRoot` under
+ * `targetRoot/node_modules`, reusing exact resolved copies at the highest
+ * non-shadowed ancestor. Required dependencies must resolve; absent optional
+ * dependencies are skipped. The result is a plain report: callers decide whether
+ * an incomplete closure is fatal or a reason to fall back to a package manager.
+ */
+export declare function materializeInstalledDependencies(options: MaterializeDependenciesOptions): Promise<DependencyMaterialization>;

package/dist/install/dependencies.js

@@ -0,0 +1,282 @@
+import { cp, mkdir } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { observePath, readTextFileBounded, resolveRealpath, } from '../infra/fs.js';
+import { isPathInside, samePath } from '../schemas/paths.js';
+const NODE_MODULES = 'node_modules';
+const DEFAULT_MAX_PACKAGES = 512;
+function packageDependencyNames(value) {
+    if (value === undefined)
+        return [];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const entries = Object.entries(value);
+    if (entries.some(([name, range]) => !/^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/.test(name) ||
+        typeof range !== 'string')) {
+        return null;
+    }
+    return entries.map(([name]) => name);
+}
+/** Reads the declared dependency names of one package without guessing ranges. */
+export async function readPackageDependencyManifest(packageRoot) {
+    const manifestRead = await readTextFileBounded(join(packageRoot, 'package.json'));
+    if (!manifestRead.ok)
+        return null;
+    let decoded;
+    try {
+        decoded = JSON.parse(manifestRead.value.text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof decoded !== 'object' || decoded === null)
+        return null;
+    const manifest = decoded;
+    const required = packageDependencyNames(manifest.dependencies);
+    const optional = packageDependencyNames(manifest.optionalDependencies);
+    if (required === null || optional === null)
+        return null;
+    return { required, optional };
+}
+/**
+ * Resolves the exact installed copy that Node would load for `name` from
+ * `packageRoot`, walking the same ancestor chain Node resolves through. Every
+ * candidate is realpath-resolved and name-checked so a symlinked store entry or
+ * a mismatched directory is never mistaken for the requested dependency.
+ */
+export async function resolveInstalledDependency(packageRoot, name) {
+    let current = packageRoot;
+    while (true) {
+        const candidate = join(current, NODE_MODULES, ...name.split('/'));
+        const realPath = await resolveRealpath(candidate);
+        if (realPath !== null &&
+            (await observePath(realPath)).kind === 'directory') {
+            const manifestRead = await readTextFileBounded(join(realPath, 'package.json'));
+            if (manifestRead.ok) {
+                try {
+                    const decoded = JSON.parse(manifestRead.value.text);
+                    if (typeof decoded === 'object' &&
+                        decoded !== null &&
+                        'name' in decoded &&
+                        decoded.name === name) {
+                        return realPath;
+                    }
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Chooses where one exact dependency belongs inside the destination tree.
+ *
+ * The slot must sit at the highest ancestor that is not shadowed by a different
+ * exact source: Node resolves `node_modules/<name>` from the nearest ancestor
+ * outwards, so a nearer conflicting placement forces a nested copy, while a free
+ * chain up to the target root allows one shared copy at the highest ancestor.
+ */
+function choosePlacement(input) {
+    let candidate = null;
+    for (const slot of resolutionSlots(input.destination, input.targetRoot, input.name)) {
+        const reserved = input.reservations.get(slot);
+        if (reserved &&
+            [...reserved].some((source) => source !== input.dependencyRoot))
+            break;
+        const placed = input.placements.get(slot);
+        if (placed === input.dependencyRoot)
+            return { kind: 'reused', slot };
+        if (placed !== undefined)
+            break;
+        candidate = slot;
+    }
+    return candidate === null
+        ? { kind: 'conflict' }
+        : { kind: 'placed', slot: candidate };
+}
+function resolutionSlots(destination, targetRoot, name) {
+    const slots = [];
+    let directory = destination;
+    while (true) {
+        // Node never appends `node_modules` to a directory that already is one, so
+        // such an ancestor is walked through but never offered as a placement slot.
+        if (basename(directory) !== NODE_MODULES)
+            slots.push(join(directory, NODE_MODULES, ...name.split('/')));
+        if (samePath(directory, targetRoot))
+            break;
+        const parent = dirname(directory);
+        if (parent === directory || !isPathInside(targetRoot, parent))
+            break;
+        directory = parent;
+    }
+    return slots;
+}
+/** Empty nearer slots must not later shadow a consumer's already chosen copy. */
+function reserveResolution(reservations, slots, source, resolvedSlot) {
+    for (const slot of slots) {
+        const expected = reservations.get(slot) ?? new Set();
+        expected.add(source);
+        reservations.set(slot, expected);
+        if (slot === resolvedSlot)
+            break;
+    }
+}
+/**
+ * Payload paths never include a nested `node_modules`: that subtree belongs to
+ * another resolver and is materialized explicitly from its own exact source.
+ */
+function isPayloadPath(sourceRoot, candidate) {
+    const path = relative(sourceRoot, candidate);
+    if (path === '')
+        return true;
+    return !path.split(sep).includes(NODE_MODULES);
+}
+/**
+ * Copies a regular package payload without nested dependency trees. Published
+ * runtime manifests forbid links, so reject them before publication rather than
+ * copying a store/absolute target or silently producing an unusable runtime.
+ */
+async function copyPackagePayload(sourceRoot, destination) {
+    const existing = await observePath(destination);
+    if (existing.kind !== 'missing')
+        return false;
+    try {
+        await cp(sourceRoot, destination, {
+            recursive: true,
+            dereference: false,
+            verbatimSymlinks: true,
+            force: false,
+            errorOnExist: false,
+            filter: async (candidate) => {
+                if (!isPayloadPath(sourceRoot, candidate))
+                    return false;
+                const entry = await observePath(candidate);
+                if (entry.kind !== 'file' && entry.kind !== 'directory')
+                    throw new Error('Dependency payload contains a link or special file');
+                return true;
+            },
+        });
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/**
+ * Materializes the installed dependency closure of `sourceRoot` under
+ * `targetRoot/node_modules`, reusing exact resolved copies at the highest
+ * non-shadowed ancestor. Required dependencies must resolve; absent optional
+ * dependencies are skipped. The result is a plain report: callers decide whether
+ * an incomplete closure is fatal or a reason to fall back to a package manager.
+ */
+export async function materializeInstalledDependencies(options) {
+    const copied = [];
+    const reused = [];
+    const skippedOptional = [];
+    const problems = [];
+    const placements = new Map();
+    const reservations = new Map();
+    const sourceRoot = (await resolveRealpath(options.sourceRoot)) ?? resolve(options.sourceRoot);
+    const targetRoot = resolve(options.targetRoot);
+    const limit = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 4096)
+        return {
+            ok: false,
+            copied,
+            reused,
+            skippedOptional,
+            problems: ['invalid_package_limit'],
+        };
+    const pending = [
+        { packageRoot: sourceRoot, destination: targetRoot },
+    ];
+    let index = 0;
+    while (index < pending.length) {
+        if (index >= limit) {
+            problems.push(`package_limit:${String(limit)}`);
+            break;
+        }
+        const current = pending[index];
+        index += 1;
+        if (current === undefined)
+            break;
+        const manifest = await readPackageDependencyManifest(current.packageRoot);
+        if (manifest === null) {
+            problems.push(`manifest_unreadable:${current.packageRoot}`);
+            continue;
+        }
+        const declared = [];
+        for (const name of manifest.required) {
+            if (declared.some((entry) => entry.name === name))
+                continue;
+            declared.push({ name, optional: false });
+        }
+        for (const name of manifest.optional) {
+            if (declared.some((entry) => entry.name === name))
+                continue;
+            declared.push({ name, optional: true });
+        }
+        for (const entry of declared) {
+            const name = entry.name;
+            const optional = entry.optional;
+            const dependencyRoot = await resolveInstalledDependency(current.packageRoot, name);
+            if (dependencyRoot === null) {
+                const slots = resolutionSlots(current.destination, targetRoot, name);
+                if (slots.some((slot) => placements.has(slot)))
+                    problems.push(`missing_dependency_shadowed:${name}`);
+                reserveResolution(reservations, slots, null);
+                if (optional) {
+                    skippedOptional.push(name);
+                    continue;
+                }
+                problems.push(`dependency_missing:${name}`);
+                continue;
+            }
+            const placement = choosePlacement({
+                placements,
+                reservations,
+                targetRoot,
+                destination: current.destination,
+                name,
+                dependencyRoot,
+            });
+            if (placement.kind === 'reused') {
+                reserveResolution(reservations, resolutionSlots(current.destination, targetRoot, name), dependencyRoot, placement.slot);
+                reused.push(placement.slot);
+                continue;
+            }
+            if (placement.kind === 'conflict') {
+                problems.push(`dependency_slot_conflict:${name}`);
+                continue;
+            }
+            if (!isPathInside(targetRoot, placement.slot)) {
+                problems.push(`dependency_placement_escape:${name}`);
+                continue;
+            }
+            await mkdir(dirname(placement.slot), { recursive: true });
+            if (!(await copyPackagePayload(dependencyRoot, placement.slot))) {
+                problems.push(`dependency_copy_failed:${name}`);
+                continue;
+            }
+            placements.set(placement.slot, dependencyRoot);
+            reserveResolution(reservations, resolutionSlots(current.destination, targetRoot, name), dependencyRoot, placement.slot);
+            copied.push(placement.slot);
+            pending.push({
+                packageRoot: dependencyRoot,
+                destination: placement.slot,
+            });
+        }
+    }
+    return {
+        ok: problems.length === 0,
+        copied,
+        reused,
+        skippedOptional,
+        problems,
+    };
+}