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

package/dist/install/runtime.js

@@ -7,11 +7,14 @@ import { homedir, tmpdir } from 'node:os';
 import { getPackageInfo } from '../package-info.js';
 import { createDiagnostic } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
-import { installJournalSchema, runtimeManifestSchema, runtimePackageManifestSchema, runtimeSourceSchema, } from '../schemas/install.js';
+import { installJournalSchema, installLockSchema, runtimeManifestSchema, runtimePackageManifestSchema, runtimeSourceSchema, RUNTIME_MANIFEST_SCHEMA, RUNTIME_DIGEST_SCHEME, } from '../schemas/install.js';
 import { isPathInside } from '../schemas/paths.js';
 import { errorMessage } from '../schemas/outcome.js';
+import { fingerprintSelfSource } from './source-fingerprint.js';
+import { inspectRuntimeReferences } from './references.js';
 import { observePath, readFileBounded, readTextFileBounded, resolveRealpath, sha256Digest, } from '../infra/fs.js';
-import { acquireInstallLock, readJsonDocument, releaseInstallLock, scanJournalDirectory, writeInstallJournal, } from './ownership.js';
+import { materializeInstalledDependencies, readPackageDependencyManifest, } from './dependencies.js';
+import { acquireInstallLock, ensureStatePathBoundary, readJsonDocument, releaseInstallLock, scanJournalDirectory, writeInstallJournal, } from './ownership.js';
 export function resolveUserDataDir(environment = process.env, platform = process.platform, home = homedir()) {
     if (environment['PAPPRA_DATA_HOME'] !== undefined) {
         return resolve(environment['PAPPRA_DATA_HOME']);
@@ -69,7 +72,7 @@ function isoNow() {
 async function hashPackageDirectory(directory) {
     const parts = [];
     const visit = async (current) => {
-        const entries = (await readdir(current, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+        const entries = (await readdir(current, { withFileTypes: true })).sort((left, right) => Buffer.compare(Buffer.from(left.name), Buffer.from(right.name)));
         for (const entry of entries) {
             const path = join(current, entry.name);
             const rel = relative(directory, path).split(sep).join('/');
@@ -175,6 +178,7 @@ async function packSelfPackage(packageRoot, packageName, version) {
     if (manifest.name !== packageName || manifest.version !== version) {
         throw new Error(`Running package ${String(manifest.name)}@${String(manifest.version)} does not match ${packageName}@${version}.`);
     }
+    const dependenciesAvailable = (await readPackageDependencyManifest(packageRoot)) !== null;
     const directory = await mkdtemp(join(tmpdir(), 'pappra-self-'));
     // Pack a staging copy: npm refuses to pack reliably from inside a dependency
     // tree (a known "Exit handler never called!" failure on Linux CI).
@@ -198,6 +202,16 @@ async function packSelfPackage(packageRoot, packageName, version) {
             force: true,
         });
     }
+    let hasInstalledDependencies = dependenciesAvailable;
+    if (hasInstalledDependencies) {
+        // Reuse the exact installed dependency closure instead of packing a copy
+        // from the registry: payloads are copied without nested node_modules and
+        // shared exact versions are hoisted once under the staging root.
+        hasInstalledDependencies = (await materializeInstalledDependencies({
+            sourceRoot: packageRoot,
+            targetRoot: staging,
+        })).ok;
+    }
     const npm = npmCommand();
     const packed = await runCommand(npm.executable, [
         ...npm.args,
@@ -230,7 +244,13 @@ async function packSelfPackage(packageRoot, packageName, version) {
     }
     const tarball = join(directory, filename);
     const bytes = await readFile(tarball);
-    return { directory, tarball, digest: sha256Digest(bytes) };
+    return {
+        directory,
+        packageDirectory: staging,
+        dependenciesAvailable: hasInstalledDependencies,
+        tarball,
+        digest: sha256Digest(bytes),
+    };
 }
 async function readPackageManifest(directory, boundaryRoot) {
     const manifestPath = join(directory, 'package.json');
@@ -256,7 +276,7 @@ function binPath(packageManifest, packageName) {
         return packageManifest.bin;
     return (packageManifest.bin[packageName] ?? packageManifest.bin['pappra'] ?? null);
 }
-async function verifyInstalledRuntime(runtimeRoot, expectedVersion, expectedPackageName, timeoutMs) {
+async function verifyInstalledRuntime(runtimeRoot, expectedVersion, expectedPackageName, timeoutMs, verifiedDigest) {
     const packageRoot = join(runtimeRoot, 'node_modules', ...expectedPackageName.split('/'));
     const runtimeReal = await resolveRealpath(runtimeRoot);
     const packageManifest = runtimeReal === null
@@ -294,7 +314,7 @@ async function verifyInstalledRuntime(runtimeRoot, expectedVersion, expectedPack
     }
     return {
         manifest: packageManifest,
-        digest: await packageDigest(packageRoot),
+        digest: verifiedDigest ?? (await packageDigest(packageRoot)),
         executableRelative: relative(runtimeRoot, executablePath)
             .split(sep)
             .join('/'),
@@ -309,6 +329,66 @@ async function readRuntimeManifest(runtimeRoot) {
     const read = await readJsonDocument(join(runtimeRoot, 'install-manifest.json'), runtimeManifestSchema);
     return read.value;
 }
+/** Recognize an unsupported format without adopting or executing its content. */
+async function incompatibleRuntimeDiagnostic(runtimeRoot) {
+    const file = join(runtimeRoot, 'install-manifest.json');
+    if ((await observePath(file)).kind !== 'file')
+        return null;
+    const read = await readTextFileBounded(file);
+    if (!read.ok)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(read.value.text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' ||
+        raw === null ||
+        !('schema' in raw) ||
+        typeof raw.schema !== 'string' ||
+        !raw.schema.startsWith('pappra/runtime-manifest/') ||
+        (raw.schema === RUNTIME_MANIFEST_SCHEMA &&
+            'digestScheme' in raw &&
+            raw.digestScheme === RUNTIME_DIGEST_SCHEME))
+        return null;
+    return createDiagnostic({
+        code: diagnosticCodes.runtimeStateIncompatible,
+        severity: 'error',
+        message: `Unsupported runtime state format at ${file}; this is not a content-corruption diagnosis.`,
+        source: file,
+        hint: 'This beta does not migrate old state. Use the current package and run pappra init --reconfigure --apply to initialize its runtime; preserve any old data you still need. Nothing was removed.',
+    });
+}
+/** Repair verifies published content without executing it or ignoring its journal. */
+export async function verifyRuntimeForRepair(runtimeRoot, version, packageName, installId) {
+    const manifest = await readRuntimeManifest(runtimeRoot);
+    if (manifest === null ||
+        manifest.installId !== installId ||
+        manifest.runtimeRoot !== runtimeRoot ||
+        manifest.runtimeVersion !== version ||
+        manifest.packageName !== packageName ||
+        !isPathInside(runtimeRoot, manifest.executable))
+        return false;
+    const packageRoot = join(runtimeRoot, 'node_modules', ...packageName.split('/'));
+    const manifestObservation = await observePath(join(runtimeRoot, 'install-manifest.json'));
+    const packageObservation = await observePath(packageRoot);
+    if (manifestObservation.kind !== 'file' ||
+        packageObservation.kind !== 'directory')
+        return false;
+    for (const file of [packageRoot, manifest.executable]) {
+        if (!(await ensureStatePathBoundary(runtimeRoot, file)).ok)
+            return false;
+        const real = await resolveRealpath(file);
+        if (real === null || !isPathInside(runtimeRoot, real))
+            return false;
+    }
+    const executable = await observePath(manifest.executable);
+    return (executable.kind === 'file' &&
+        (await packageDigest(packageRoot).catch(() => null)) ===
+            manifest.packageDigest);
+}
 async function scanRuntimeJournals(version, paths) {
     const directory = await scanJournalDirectory(paths.journalsDir);
     if (directory.kind === 'missing') {
@@ -340,7 +420,7 @@ async function scanRuntimeJournals(version, paths) {
     }
     return { journal, unreadable, directoryUnreadable: false };
 }
-async function completeExistingRuntime(version, paths, packageName, timeoutMs) {
+async function completeExistingRuntime(version, paths, packageName, timeoutMs, expectedSelfFingerprint) {
     const observation = await observePath(paths.runtimeRoot);
     if (observation.kind === 'missing')
         return null;
@@ -354,6 +434,19 @@ async function completeExistingRuntime(version, paths, packageName, timeoutMs) {
     }
     const manifest = await readRuntimeManifest(paths.runtimeRoot);
     if (manifest === null) {
+        const incompatible = await incompatibleRuntimeDiagnostic(paths.runtimeRoot);
+        if (incompatible !== null) {
+            return {
+                ok: false,
+                status: 'incompatible',
+                version,
+                runtimeRoot: paths.runtimeRoot,
+                manifest: null,
+                journal: null,
+                diagnostics: [incompatible],
+                residualPaths: [],
+            };
+        }
         return failureResult('corrupt', `Runtime has no valid manifest: ${paths.runtimeRoot}`, {
             version,
             runtimeRoot: paths.runtimeRoot,
@@ -371,6 +464,15 @@ async function completeExistingRuntime(version, paths, packageName, timeoutMs) {
             source: paths.runtimeRoot,
         });
     }
+    if (expectedSelfFingerprint !== undefined &&
+        manifest.sourceFingerprint !== expectedSelfFingerprint)
+        return failureResult('failed', 'This version already contains a different self package payload or resolved dependency identity.', {
+            version,
+            runtimeRoot: paths.runtimeRoot,
+            manifest,
+            hint: 'Bump the package version before installing a rebuilt self runtime; an existing version is never silently reused or overwritten for different source bytes.',
+            source: paths.runtimeRoot,
+        });
     const packageRoot = join(paths.runtimeRoot, 'node_modules', ...packageName.split('/'));
     const digest = await packageDigest(packageRoot).catch(() => null);
     const executableObservation = await observePath(manifest.executable);
@@ -385,7 +487,10 @@ async function completeExistingRuntime(version, paths, packageName, timeoutMs) {
             source: paths.runtimeRoot,
         });
     }
-    const verified = await verifyInstalledRuntime(paths.runtimeRoot, version, packageName, timeoutMs);
+    const verified = await verifyInstalledRuntime(paths.runtimeRoot, version, packageName, timeoutMs, 
+    // Content was checked before executing the smoke command. Reuse does not
+    // publish a new manifest, so hashing it again would discard the result.
+    digest);
     if (verified === null) {
         return failureResult('corrupt', `Runtime smoke check failed: ${paths.runtimeRoot}`, {
             version,
@@ -467,7 +572,42 @@ export async function installRuntime(options) {
             source: paths.lockPath,
         });
     }
-    const existing = await completeExistingRuntime(version, paths, packageName, timeoutMs);
+    let expectedSelfFingerprint;
+    if (options.source.kind === 'self') {
+        try {
+            const sourceRead = await readTextFileBounded(join(resolve(options.source.path ?? ''), 'package.json'));
+            const sourceManifest = sourceRead.ok
+                ? JSON.parse(sourceRead.value.text)
+                : null;
+            if (typeof sourceManifest === 'object' &&
+                sourceManifest !== null &&
+                'name' in sourceManifest &&
+                sourceManifest.name === packageName &&
+                'version' in sourceManifest &&
+                typeof sourceManifest.version === 'string' &&
+                sourceManifest.version !== version) {
+                // A newer CLI may verify and reuse an older workspace target. It cannot
+                // replace that target with its own differently versioned payload.
+                const older = await completeExistingRuntime(version, paths, packageName, timeoutMs);
+                if (older !== null)
+                    return older;
+                return failureResult('failed', 'The running package version does not match the requested runtime and no verified target is available.', {
+                    version,
+                    runtimeRoot: paths.runtimeRoot,
+                    hint: 'Install the exact workspace runtime version from a versioned package or tarball.',
+                });
+            }
+            expectedSelfFingerprint = await fingerprintSelfSource(resolve(options.source.path ?? ''), packageName, version);
+        }
+        catch (error) {
+            return failureResult('failed', `Cannot identify the running package source: ${errorMessage(error)}`, {
+                version,
+                runtimeRoot: paths.runtimeRoot,
+                hint: 'Review the package payload and resolved dependencies; bump the package version for rebuilt source.',
+            });
+        }
+    }
+    const existing = await completeExistingRuntime(version, paths, packageName, timeoutMs, expectedSelfFingerprint);
     if (existing !== null)
         return existing;
     const lock = await acquireInstallLock(paths.lockPath, 'install-runtime', paths.runtimeRoot, dataDir);
@@ -479,7 +619,7 @@ export async function installRuntime(options) {
             source: paths.lockPath,
         });
     }
-    const afterLock = await completeExistingRuntime(version, paths, packageName, timeoutMs);
+    const afterLock = await completeExistingRuntime(version, paths, packageName, timeoutMs, expectedSelfFingerprint);
     if (afterLock !== null) {
         await releaseInstallLock(paths.lockPath, lock.lock.token);
         return afterLock;
@@ -505,6 +645,9 @@ export async function installRuntime(options) {
         else if (options.source.kind === 'self') {
             const packageRoot = resolve(options.source.path ?? '');
             selfPackage = await packSelfPackage(packageRoot, packageName, version);
+            if ((await fingerprintSelfSource(packageRoot, packageName, version)) !==
+                expectedSelfFingerprint)
+                throw new Error('Self source changed while packing; no runtime will be published. Rebuild with a new version and retry.');
             source = {
                 kind: 'self',
                 packageName,
@@ -608,30 +751,37 @@ export async function installRuntime(options) {
         if (!(await writeJournal())) {
             throw new Error(`Cannot update install journal: ${journalFile}`);
         }
-        const npm = npmCommand();
-        const installArgs = [
-            ...npm.args,
-            'install',
-            '--prefix',
-            stage,
-            '--ignore-scripts',
-            '--no-audit',
-            '--no-fund',
-            '--no-package-lock',
-            '--save-exact',
-            ...(options.offline === true ? ['--offline'] : []),
-            source.kind === 'tarball' || source.kind === 'self'
-                ? source.kind === 'tarball'
-                    ? source.path
-                    : source.tarball
-                : `${source.packageName}@${source.version}`,
-        ];
-        const installed = await runCommand(npm.executable, installArgs, {
-            cwd: stage,
-            timeoutMs,
-        });
-        if (installed.timedOut || installed.code !== 0) {
-            throw new Error(`Package manager install failed (${installed.timedOut ? 'timeout' : `exit ${String(installed.code)}`}): ${installed.stderr.slice(0, 1000)}`);
+        // Reuse installed versions when available so self installs do not depend on npm registry/cache.
+        if (options.source.kind === 'self' &&
+            selfPackage?.dependenciesAvailable === true) {
+            await cp(selfPackage.packageDirectory, join(stage, 'node_modules', ...packageName.split('/')), { recursive: true, dereference: true, force: true });
+        }
+        else {
+            const npm = npmCommand();
+            const installArgs = [
+                ...npm.args,
+                'install',
+                '--prefix',
+                stage,
+                '--ignore-scripts',
+                '--no-audit',
+                '--no-fund',
+                '--no-package-lock',
+                '--save-exact',
+                ...(options.offline === true ? ['--offline'] : []),
+                source.kind === 'tarball' || source.kind === 'self'
+                    ? source.kind === 'tarball'
+                        ? source.path
+                        : source.tarball
+                    : `${source.packageName}@${source.version}`,
+            ];
+            const installed = await runCommand(npm.executable, installArgs, {
+                cwd: stage,
+                timeoutMs,
+            });
+            if (installed.timedOut || installed.code !== 0) {
+                throw new Error(`Package manager install failed (${installed.timedOut ? 'timeout' : `exit ${String(installed.code)}`}): ${installed.stderr.slice(0, 1000)}`);
+            }
         }
         if (selfPackage !== null) {
             await rm(selfPackage.directory, { recursive: true, force: true }).catch(() => undefined);
@@ -647,7 +797,7 @@ export async function installRuntime(options) {
         if (!(await writeJournal()))
             throw new Error('Cannot update install journal.');
         const manifest = {
-            schema: 'pappra/runtime-manifest/1',
+            schema: RUNTIME_MANIFEST_SCHEMA,
             installId,
             packageName,
             runtimeVersion: version,
@@ -655,6 +805,8 @@ export async function installRuntime(options) {
             executable: join(paths.runtimeRoot, ...verification.executableRelative.split('/')),
             source,
             packageDigest: verification.digest,
+            digestScheme: RUNTIME_DIGEST_SCHEME,
+            sourceFingerprint: await fingerprintSelfSource(join(stage, 'node_modules', ...packageName.split('/')), packageName, version),
             smoke: verification.smoke,
             verifiedAt: isoNow(),
         };
@@ -744,7 +896,7 @@ async function runtimePackageName(runtimeRoot) {
     const read = await readJsonDocument(join(runtimeRoot, 'install-manifest.json'), runtimeManifestSchema);
     return read.value?.packageName ?? getPackageInfo().name;
 }
-export async function inspectRuntimeState(version, dataDir = resolveUserDataDir()) {
+export async function inspectRuntimeState(version, dataDir = resolveUserDataDir(), heldLockToken) {
     const paths = runtimePaths(version, dataDir);
     if (!validVersion(version)) {
         return {
@@ -803,7 +955,11 @@ export async function inspectRuntimeState(version, dataDir = resolveUserDataDir(
             ],
         };
     }
-    if (lockObservation.kind !== 'missing') {
+    const ownLock = heldLockToken === undefined
+        ? null
+        : await readJsonDocument(paths.lockPath, installLockSchema);
+    if (lockObservation.kind !== 'missing' &&
+        (heldLockToken === undefined || ownLock?.value?.token !== heldLockToken)) {
         return {
             version,
             status: 'locked',
@@ -835,7 +991,11 @@ export async function inspectRuntimeState(version, dataDir = resolveUserDataDir(
     }
     return {
         version,
-        status: complete.status === 'reused' ? 'complete' : 'corrupt',
+        status: complete.status === 'reused'
+            ? 'complete'
+            : complete.status === 'incompatible'
+                ? 'incompatible'
+                : 'corrupt',
         runtimeRoot: paths.runtimeRoot,
         manifest: complete.manifest,
         journal: complete.journal,
@@ -843,6 +1003,66 @@ export async function inspectRuntimeState(version, dataDir = resolveUserDataDir(
     };
 }
 export async function removeRuntime(options) {
+    if (!validVersion(options.version))
+        return removeRuntimeAt(options);
+    const dataDir = resolve(options.dataDir ?? resolveUserDataDir());
+    const paths = runtimePaths(options.version, dataDir);
+    const lock = await acquireInstallLock(paths.lockPath, 'remove-runtime', paths.runtimeRoot, dataDir);
+    if (!lock.ok || !lock.lock)
+        return {
+            ok: false,
+            status: 'locked',
+            runtimeRoot: paths.runtimeRoot,
+            residualPaths: [paths.lockPath],
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.initApplyResidual,
+                    severity: 'error',
+                    message: lock.message ?? 'Runtime removal is locked.',
+                    source: paths.lockPath,
+                }),
+            ],
+        };
+    let result;
+    try {
+        result = await removeRuntimeAt(options, lock.lock.token);
+    }
+    catch (error) {
+        result = {
+            ok: false,
+            status: 'failed',
+            runtimeRoot: paths.runtimeRoot,
+            residualPaths: [],
+            diagnostics: [
+                createDiagnostic({
+                    code: diagnosticCodes.initApplyFailed,
+                    severity: 'error',
+                    message: errorMessage(error),
+                    source: paths.runtimeRoot,
+                }),
+            ],
+        };
+    }
+    const released = await releaseInstallLock(paths.lockPath, lock.lock.token);
+    return released.ok
+        ? result
+        : {
+            ...result,
+            ok: false,
+            status: 'failed',
+            residualPaths: [...result.residualPaths, paths.lockPath],
+            diagnostics: [
+                ...result.diagnostics,
+                createDiagnostic({
+                    code: released.code,
+                    severity: 'error',
+                    message: released.message,
+                    source: paths.lockPath,
+                }),
+            ],
+        };
+}
+async function removeRuntimeAt(options, heldLockToken) {
     const dataDir = resolve(options.dataDir ?? resolveUserDataDir());
     const paths = runtimePaths(options.version, dataDir);
     if (!validVersion(options.version)) {
@@ -862,27 +1082,38 @@ export async function removeRuntime(options) {
             residualPaths: [],
         };
     }
-    const references = options.activeReferences ?? [];
-    if (references.length > 0 || options.activeReferences === undefined) {
+    if ((await observePath(paths.runtimeRoot)).kind === 'missing')
+        return {
+            ok: true,
+            status: 'missing',
+            runtimeRoot: paths.runtimeRoot,
+            diagnostics: [],
+            residualPaths: [],
+        };
+    const references = await inspectRuntimeReferences(dataDir, options.version);
+    const activeCount = references.active.length + (options.activeReferences?.length ?? 0);
+    if (activeCount > 0 || options.forceUnknownReferences !== true) {
         return {
             ok: false,
-            status: 'in-use',
+            status: activeCount > 0 ? 'in-use' : 'unknown',
             runtimeRoot: paths.runtimeRoot,
             diagnostics: [
                 createDiagnostic({
                     code: diagnosticCodes.initApplyResidual,
                     severity: 'error',
-                    message: options.activeReferences === undefined
-                        ? 'Runtime removal requires an explicit active-reference check.'
-                        : `Runtime is referenced by ${references.length} active workspace(s).`,
+                    message: activeCount > 0
+                        ? `Runtime is referenced by ${activeCount} verified or explicitly reported active workspace(s).`
+                        : 'Global reference coverage is unknown: only explicitly registered workspace roots were checked. An empty caller list is not proof of no references.',
                     source: paths.runtimeRoot,
-                    hint: 'Resolve active references and retry; Pappra does not guess that a runtime is unused.',
+                    hint: activeCount > 0
+                        ? 'Rebind or explicitly retire those workspace bindings; --force never bypasses a verified reference.'
+                        : 'Review registered and unregistered workspace usage, then use the explicit CLI --force policy only to accept unknown coverage.',
                 }),
             ],
             residualPaths: [],
         };
     }
-    const state = await inspectRuntimeState(options.version, dataDir);
+    const state = await inspectRuntimeState(options.version, dataDir, heldLockToken);
     if (state.status === 'missing') {
         return {
             ok: true,
@@ -904,7 +1135,7 @@ export async function removeRuntime(options) {
     if (state.status !== 'complete' || state.manifest === null) {
         return {
             ok: false,
-            status: 'corrupt',
+            status: state.status === 'incompatible' ? 'incompatible' : 'corrupt',
             runtimeRoot: paths.runtimeRoot,
             diagnostics: state.diagnostics,
             residualPaths: [],
@@ -1098,9 +1329,16 @@ export async function inspectRuntimeStatePassive(version, dataDir = resolveUserD
     }
     const manifestRead = await readJsonDocument(manifestPath, runtimeManifestSchema);
     if (!manifestRead.exists || manifestRead.value === null) {
+        const incompatible = manifestRead.exists
+            ? await incompatibleRuntimeDiagnostic(paths.runtimeRoot)
+            : null;
         return {
             version,
-            status: manifestRead.exists ? 'unreadable' : 'corrupt',
+            status: incompatible !== null
+                ? 'incompatible'
+                : manifestRead.exists
+                    ? 'unreadable'
+                    : 'corrupt',
             runtimeRoot: paths.runtimeRoot,
             manifest: null,
             journal: null,
@@ -1108,17 +1346,19 @@ export async function inspectRuntimeStatePassive(version, dataDir = resolveUserD
             lockPresent,
             packageDigestMatch: false,
             executableExists: false,
-            diagnostics: manifestRead.diagnostics.length > 0
-                ? manifestRead.diagnostics
-                : [
-                    createDiagnostic({
-                        code: diagnosticCodes.initApplyFailed,
-                        severity: 'error',
-                        message: `Runtime manifest is missing: ${paths.runtimeRoot}`,
-                        source: paths.runtimeRoot,
-                        hint: 'Inspect the partial runtime; doctor does not overwrite it.',
-                    }),
-                ],
+            diagnostics: incompatible !== null
+                ? [incompatible]
+                : manifestRead.diagnostics.length > 0
+                    ? manifestRead.diagnostics
+                    : [
+                        createDiagnostic({
+                            code: diagnosticCodes.initApplyFailed,
+                            severity: 'error',
+                            message: `Runtime manifest is missing: ${paths.runtimeRoot}`,
+                            source: paths.runtimeRoot,
+                            hint: 'Inspect the partial runtime; doctor does not overwrite it.',
+                        }),
+                    ],
         };
     }
     const manifest = manifestRead.value;

package/dist/install/source-fingerprint.d.ts

@@ -0,0 +1,2 @@
+/** Payload bytes plus actual resolved package-manifest/edge identities; no absolute paths. */
+export declare function fingerprintSelfSource(packageRoot: string, packageName: string, version: string): Promise<string>;

package/dist/install/source-fingerprint.js

@@ -0,0 +1,103 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { observePath, readFileBounded, readTextFileBounded, resolveRealpath, sha256Digest, } from '../infra/fs.js';
+import { isPathInside } from '../schemas/paths.js';
+import { readPackageDependencyManifest, resolveInstalledDependency, } from './dependencies.js';
+/** Exactly the payload entries staged by the self-package installer. */
+const SELF_PAYLOAD = [
+    'package.json',
+    'README.md',
+    'LICENSE',
+    'THIRD_PARTY_NOTICES.md',
+    'dist',
+    'assets',
+    'skills',
+];
+/** Payload bytes plus actual resolved package-manifest/edge identities; no absolute paths. */
+export async function fingerprintSelfSource(packageRoot, packageName, version) {
+    const canonical = await resolveRealpath(packageRoot);
+    if (!canonical)
+        throw new Error('Running package root cannot be resolved.');
+    const parts = [];
+    let files = 0;
+    let bytes = 0;
+    const active = new Set();
+    const visit = async (relative) => {
+        const path = join(canonical, relative);
+        const presence = await observePath(path);
+        if (presence.kind === 'missing') {
+            parts.push(`missing:${relative}`);
+            return;
+        }
+        const real = await resolveRealpath(path);
+        if (!real || !isPathInside(canonical, real))
+            throw new Error(`Self payload escapes its package root: ${relative}`);
+        const target = await observePath(real);
+        if (target.kind === 'directory') {
+            if (active.has(real))
+                throw new Error('Self payload contains a directory cycle.');
+            active.add(real);
+            parts.push(`dir:${relative}`);
+            for (const entry of (await readdir(real)).sort())
+                await visit(`${relative}/${entry}`);
+            active.delete(real);
+        }
+        else if (target.kind === 'file') {
+            if (++files > 8192)
+                throw new Error('Self payload exceeds the fingerprint file budget.');
+            const read = await readFileBounded(real, 64 * 1024 * 1024);
+            if (!read.ok)
+                throw new Error(`Cannot fingerprint self payload: ${relative}`);
+            bytes += read.value.size;
+            if (bytes > 256 * 1024 * 1024)
+                throw new Error('Self payload exceeds the fingerprint byte budget.');
+            parts.push(`file:${relative}:${read.value.digest}`);
+        }
+        else
+            throw new Error(`Unsupported self payload entry: ${relative}`);
+    };
+    const manifest = await readTextFileBounded(join(canonical, 'package.json'));
+    if (!manifest.ok)
+        throw new Error('Running package manifest is unreadable.');
+    const decoded = JSON.parse(manifest.value.text);
+    if (decoded.name !== packageName || decoded.version !== version)
+        throw new Error('Running package name/version differs from the requested runtime; bump the package version before reinstalling.');
+    for (const entry of SELF_PAYLOAD)
+        await visit(entry);
+    const visited = new Set();
+    const graph = new Set();
+    const dependencies = async (directory) => {
+        const real = await resolveRealpath(directory);
+        if (!real || visited.has(real))
+            return;
+        visited.add(real);
+        if (visited.size > 512)
+            throw new Error('Resolved dependency identity budget exceeded.');
+        const read = await readTextFileBounded(join(real, 'package.json'));
+        const declared = await readPackageDependencyManifest(real);
+        if (!read.ok || !declared)
+            throw new Error('Cannot read a resolved dependency manifest.');
+        const value = JSON.parse(read.value.text);
+        const edges = [];
+        for (const [kind, names] of [
+            ['required', declared.required],
+            ['optional', declared.optional],
+        ]) {
+            for (const name of [...names].sort()) {
+                const resolved = await resolveInstalledDependency(real, name);
+                if (!resolved) {
+                    edges.push(`${kind}:${name}:missing`);
+                    continue;
+                }
+                const resolvedManifest = await readTextFileBounded(join(resolved, 'package.json'));
+                if (!resolvedManifest.ok)
+                    throw new Error('Cannot read a resolved dependency identity.');
+                edges.push(`${kind}:${name}:${resolvedManifest.value.digest}`);
+                await dependencies(resolved);
+            }
+        }
+        graph.add(`${String(value.name)}@${String(value.version)}:${read.value.digest}:${edges.join('|')}`);
+    };
+    await dependencies(canonical);
+    return sha256Digest([...parts, ...[...graph].sort().map((entry) => `dependency:${entry}`)].join('\n'));
+}

package/dist/knowledge/catalog.d.ts

@@ -13,6 +13,7 @@ export interface CatalogFileState {
     readonly catalog: DocumentCatalog | null;
     readonly diagnostics: readonly Diagnostic[];
     readonly valid: boolean;
+    readonly recordDigests?: ReadonlyMap<string, string>;
 }
 export interface KnowledgeCatalogs {
     readonly paths: KnowledgePaths;