@deepseek-ai/dsh-app-boot 0.1.5-rc.2 → 0.1.6-alpha.2

package/lib/types/index.d.ts

@@ -5,18 +5,22 @@
  * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
  * @module @deepseek-ai/dsh-app-boot
  */
-import { Context } from '@deepseek-ai/cordis';
+import { Context, type FiberState } from '@deepseek-ai/cordis';
 import { type Entry } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
+export { readProfilePatches, resolveTelemetryPatch, type ProfileContext, type ProfilePnpmInvocation } from './profile-context.ts';
+export { sanitizeProfile } from './profile-sanitize.ts';
+export { readProfilePlugins, reconcileProfilePlugins, writeProfileBundles, type ProfilePluginLocation, type ProfilePluginDependency, type ProfilePluginInventory, type ProfilePluginReconciliation, } from './profile-plugins.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Harness-home path resolver available to Loader `!!js` config expressions. */
         dshHomePath?: typeof dshHomePath;
     }
 }
-export { composeEntries, DEFAULT_PROFILE_BUNDLES, DEFAULT_PROFILE_PATCH_RELOAD, healProfilesModuleFallback, initProfile, loadProfile, loadProfileDirectory, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type ProfileManifest, type ProfileModuleFallbackOptions, type ProfileTemplate, } from './profile.ts';
+export { composeEntries, createProfileResolutionGeneration, DEFAULT_PROFILE_BUNDLES, OPTIONAL_BUNDLES, healProfilesModuleFallback, healIsolatedProfileModuleFallback, unlinkProfileModuleFallback, initProfile, loadProfile, loadProfileDirectory, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type ProfileManifest, type ProfileModuleFallbackOptions, type ProfileResolutionEntry, type ProfileResolutionGeneration, type ProfileResolutionMode, type ProfileTemplate, } from './profile.ts';
+export { PluginPackages, type PluginPackage, type PluginPackagesConfig, } from './profile-resolution/service.ts';
 /**
  * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
  * `cordis.snapshot.yml` in the same directory; every other mode keeps the path.
@@ -47,29 +51,14 @@ export declare function loadEnv(binName: string, dir?: string, warn?: (line: str
  * @throws when either file declares a bootstrap-only variable, except {@link HOME_LAYER_PROXY_NAMES} in the Harness-home file.
  */
 export declare function loadLayeredEnv(binName: string, cwd?: string, warn?: (line: string) => void): LaunchEnvironmentSnapshot;
-/** Options for live user patch-layer reconciliation. */
-export interface UserPatchWatchOptions {
-    /** Diagnostic prefix used by {@link loadOptionalPatches}. */
-    binName: string;
-    /** Absolute path of the watched patch file (a profile's `cordis.patch.yml`). */
-    filename: string;
-    /**
-     * Compose the full patch list for a fresh user-layer generation —
-     * the same composition the app booted with, so a reload can interleave the
-     * new user patches between app-owned layers (bundle layers below,
-     * overlays above). Identity when omitted: the user layer
-     * is the whole patch list.
-     */
-    compose?: (userPatches: PatchOptions[]) => PatchOptions[];
-}
-/**
- * Watch the user patch layer through Cordis HMR and transactionally reapply it to the boot include.
- * @param ctx - settled app context containing the root Include and an active HMR service.
- * @param options - diagnostic, file, and patch-composition inputs.
- * @returns an asynchronous disposer after the exact-path watcher is ready.
- * @throws when HMR or the root Include is absent, watcher setup fails, or initial path resolution fails.
+/** Apply one complete patch generation and wait for Loader activation diagnostics.
+ * @param ctx Booted root context.
+ * @param patches Complete ordered patch list.
+ * @param binName Diagnostic prefix.
+ * @param requiredIds Explicit enablement targets whose existing failures also reject reconciliation.
+ * @returns Diagnostics for unchanged pre-existing inactive entries; new or changed failures reject.
  */
-export declare function watchUserPatches(ctx: Context, options: UserPatchWatchOptions): Promise<() => Promise<void>>;
+export declare function reconcileProfilePatches(ctx: Context, patches: PatchOptions[], binName: string, requiredIds?: readonly string[]): Promise<string[]>;
 /**
  * Load an optional patch-list file: a top-level YAML array of loader patch
  * entries (`@deepseek-ai/cordis-plugin-include`'s `PatchOptions`): id-targeted config
@@ -140,7 +129,7 @@ export declare function renderConfigDump(binName: string, absoluteConfigPath: st
  * names; relative names continue to resolve beside the configuration file.
  * @returns the created root Include entry, or `undefined` when a surface
  * disposed the whole tree (taking the Loader service with it) while the
- * transactional create was still settling entry lifecycle.
+ * entry creation was in flight.
  */
 export declare function mountRootInclude(ctx: Context, absoluteConfigPath: string, patches?: readonly PatchOptions[], bareModuleBaseUrl?: string): Promise<Entry | undefined>;
 /**
@@ -168,7 +157,7 @@ export declare const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2000;
 /**
  * Install before boot to turn a late unhandled plugin-init rejection into one
  * labelled stderr diagnostic and `exit(1)`. A rejection already included by
- * {@link assertEntriesActivated} is ignored during its process checkpoint;
+ * {@link auditStartupEntries} is ignored during its process checkpoint;
  * every other rejection remains fatal. Stdout remains untouched for ACP; the
  * returned function removes the handler.
  *
@@ -195,27 +184,65 @@ export declare const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2000;
  * @returns the uninstaller that removes the rejection handler.
  */
 export declare function installFailLoud(binName: string, proc?: FailLoudProcess, release?: () => Promise<void> | void): () => void;
+interface InactiveEntry {
+    /** Loader entry used to identify the bootstrap Include and required ids. */
+    entry: Entry;
+    /** Activation errors and missing services remain distinct for presentation. */
+    outcome: {
+        kind: 'failed';
+        error: unknown;
+        phase?: string;
+    } | {
+        kind: 'pending';
+        missing: string[];
+    };
+}
+/** Inactive plugin metadata without retaining its Context or Fiber. */
+interface StartupEntryDiagnostic {
+    id: string;
+    module: string;
+    required: boolean;
+    fiberState: FiberState | undefined;
+    outcome: InactiveEntry['outcome'];
+}
+/** Startup warning or error arguments, including import errors with no Fiber. */
+interface StartupLogRecord {
+    ts: number;
+    name: string;
+    type: string;
+    args: readonly unknown[];
+}
+/** Startup audit failure with non-enumerable metadata and original failures as its cause. */
+export declare class StartupError extends Error {
+    readonly entries: readonly StartupEntryDiagnostic[];
+    /** Root configuration and startup logs, attached by boot after disposal. */
+    startup?: {
+        configurationPath: string;
+        messages: readonly StartupLogRecord[];
+    };
+    /**
+     * @param message - concise terminal diagnostic.
+     * @param entries - inactive plugin metadata and original failure values.
+     */
+    constructor(message: string, entries: readonly StartupEntryDiagnostic[]);
+}
 /**
- * After the tree settles, reject entries with no fiber and name every plugin
- * whose module failed to resolve. Disabled entries are the only valid
- * fiber-less state.
- * @param ctx - the settled context whose loader entries to audit.
- * @param binName - the diagnostic prefix on the thrown error.
- */
-export declare function assertEntriesLoaded(ctx: Context, binName: string): void;
-/**
- * Reject a settled Loader tree when an enabled entry failed or remains inactive.
- * Plugin failures include the original thrown stack; pending entries name their
- * unresolved services because no plugin error exists for that state. Active
- * entries require no further wait; only failed fibers are awaited to recover
- * their private rejection reason.
+ * Apply DSH startup policy to a settled Loader tree.
+ *
+ * Inactive entries from the global required list reject startup. Other
+ * inactive entries join that failure diagnostic, or produce one warning when
+ * no required entry failed and leave successful siblings running.
+ * Required ids absent from the tree, and disabled required entries, are ignored.
+ * A throwing disabled expression is an entry failure, not a disabled entry.
+ * The bootstrap Include must activate so unreadable or invalid root config is fatal.
  * @param ctx - the settled context whose Loader entries to audit.
- * @param binName - the diagnostic prefix on the thrown error.
- * @returns nothing when every enabled entry is active.
- * @throws after one process rejection checkpoint when an entry failed to
- * import, rejected during activation, or did not become active.
+ * @param binName - the prefix on startup diagnostics.
+ * @param warn - sink for optional-entry warnings.
+ * @returns after optional warnings if required startup checks pass.
+ * @throws {@link StartupError} when the bootstrap Include or a required entry is inactive or its disabled expression throws;
+ * its message includes optional failures too.
  */
-export declare function assertEntriesActivated(ctx: Context, binName: string): Promise<void>;
+export declare function auditStartupEntries(ctx: Context, binName: string, warn?: (line: string) => void): Promise<void>;
 /**
  * Boot the Loader against `absoluteConfigPath` and return only after the whole
  * tree settles. Relative entry names resolve against the config directory;
@@ -224,12 +251,11 @@ export declare function assertEntriesActivated(ctx: Context, binName: string): P
  * is statically imported and mounted as the `cordis:include` builtin, loading
  * through the ambient module pipeline (vite/tsx/plain ESM). The package build
  * embeds Include while leaving Loader external, so the built include tree and
- * host share one Loader peer. Loader
- * settlement rejects startup failures, which `boot` wraps after disposing the
- * partial context; a missing fiber or never-activating entry is rejected by
- * the final audit, {@link assertEntriesActivated}, which rethrows a plugin's
- * init rejection with its original stack; later unhandled rejections remain
- * covered by {@link installFailLoud}. Built bins need the Loader's native
+ * host share one Loader peer. Loader settlement drains entry work without
+ * rejecting the whole tree. The final {@link auditStartupEntries} call rejects
+ * failures in the global required list and warns about other failed, missing,
+ * and pending entries while successful siblings remain active. Later unhandled
+ * rejections remain covered by {@link installFailLoud}. Built bins need the Loader's native
  * helper for bare plugin specifiers; relative specifiers do not.
  * @param binName - the diagnostic prefix for load-failure errors.
  * @param absoluteConfigPath - the config to include; must already be absolute
@@ -240,11 +266,13 @@ export declare function assertEntriesActivated(ctx: Context, binName: string): P
  * @param bareModuleBaseUrl - optional installed-host base for bare package
  * names; use it when the host, rather than the configuration project, owns the
  * complete plugin set.
- * @returns the root context once every entry has started, or as soon as a
+ * @returns the root context after the initial startup audit, or as soon as a
  * surface disposed the tree while startup was still in flight.
- * @throws a labelled error after disposing the partial context — `host
+ * @throws {@link StartupError} for an inactive required entry, including all inactive plugins in its message;
+ * otherwise a labelled error after disposing the partial context — `host
  * preparation failed` when `prepare` threw before any config-tree entry
- * mounted, `plugin tree failed to load` afterwards.
+ * mounted, `plugin tree failed to load` afterwards. Cyclic causes terminate
+ * diagnostic traversal without replacing the original cause.
  */
 export declare function boot(binName: string, absoluteConfigPath: string, patches?: PatchOptions[], prepare?: (ctx: Context) => Promise<void> | void, bareModuleBaseUrl?: string): Promise<Context>;
 /** Prompt-section name for the harness-source location line an app bin adds after boot. */

package/lib/types/profile-context.d.ts

@@ -0,0 +1,51 @@
+import { type Profile } from './profile.ts';
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include';
+/** Application-owned package manager executable; environment applies only to package operations. */
+export interface ProfilePnpmInvocation {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/** Current profile facts; scheduling and mutation belong to their callers. */
+export interface ProfileContext {
+    readonly name: string;
+    /** Packaged applications supply their bundled runtime instead of a PATH executable. */
+    readonly packageManager?: ProfilePnpmInvocation;
+    readonly dir: string;
+    readonly patchPath: string;
+    readonly installAnchor: string;
+    readonly cwd: string;
+    readonly home: string;
+    /** Bundle packages used to start this process, before any persisted edits. */
+    readonly startedBundles: readonly string[];
+    /** Parsed command-line overlays, applied above profile and home patches. */
+    readonly overlays: readonly PatchOptions[];
+    /** Launch-time DSH_TELEMETRY_DISABLED value; any non-empty value opts out. */
+    readonly telemetryDisabledEnv: string | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Present only in a profile launched by dsh. */
+        profileContext: ProfileContext;
+    }
+}
+/**
+ * Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
+ * value (including `'0'`/`'false'`) disables: a privacy switch prefers
+ * off-by-mistake over on-by-mistake. A composition without the telemetry row
+ * exports nothing, so the switch is then trivially satisfied and no patch is
+ * generated — custom profiles need not mount telemetry to run with the
+ * switch set.
+ * @param disabledEnv - the raw `DSH_TELEMETRY_DISABLED` value (`undefined` when unset).
+ * @param hasRow - whether the composition carries the telemetry row.
+ * @returns the disable patch, or `undefined` when no hard-disable patch is required.
+ */
+export declare function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: boolean): PatchOptions | undefined;
+/** Read current bundle and user layers with the launch-time overlays.
+ * @param binName Diagnostic prefix for malformed or missing configuration.
+ * @param context Data supplied by the profile launcher.
+ * @param initialProfile Already loaded startup profile; omitted reads the current files.
+ * @returns Detached ordered patches; this function does not update the Loader.
+ */
+export declare function readProfilePatches(binName: string, context: ProfileContext, initialProfile?: Profile): PatchOptions[];
+//# sourceMappingURL=profile-context.d.ts.map

package/lib/types/profile-plugins.d.ts

@@ -0,0 +1,60 @@
+/** Installed profile dependencies and their bundle activation after package-manager operations. */
+import { type ProfileManifest } from './profile.ts';
+/** Profile directory and installation used by the shared bundle resolver. */
+export interface ProfilePluginLocation {
+    /** Diagnostic prefix for profile manifest failures. */
+    readonly binName: string;
+    /** Profile package directory managed by pnpm. */
+    readonly profileDir: string;
+    /** Absolute package.json path of the owning dsh installation. */
+    readonly installAnchor: string;
+}
+/** One dependency under its package-manager key, including npm aliases. */
+export interface ProfilePluginDependency {
+    /** Dependency key used in package.json and the bundle list. */
+    readonly name: string;
+    /** Installed version, or the dependency spec when installed metadata is unavailable. */
+    readonly version: string;
+    /** Whether the package selected by the bundle resolver declares a patch. */
+    readonly bundle: boolean;
+    /** Whether the dependency appears in the profile's active bundle list. */
+    readonly enabled: boolean;
+}
+/** Profile manifest and dependencies in manifest order. */
+export interface ProfilePluginInventory {
+    readonly manifest: ProfileManifest;
+    readonly dependencies: readonly ProfilePluginDependency[];
+}
+/** Result of reconciling bundle activation after a successful package operation. */
+export interface ProfilePluginReconciliation {
+    readonly plugins: ProfilePluginInventory;
+    /** Newly added ordinary dependencies, for optional caller-owned diagnostics. */
+    readonly addedPlainDependencies: readonly string[];
+}
+/**
+ * Read installed versions and bundle declarations without requiring loadable plugin code.
+ * Missing or unreadable installed metadata leaves the dependency visible for repair or removal.
+ * @param location - profile and installation resolution inputs.
+ * @returns dependency records in package.json order and the profile manifest.
+ */
+export declare function readProfilePlugins(location: ProfilePluginLocation): ProfilePluginInventory;
+/**
+ * Write a bundle list while preserving the supplied profile's other metadata.
+ * @param profileDir - directory whose package.json is updated.
+ * @param manifest - current profile manifest, read after the package operation when applicable.
+ * @param bundles - ordered active bundle names, including any template entries.
+ * @returns the written manifest.
+ */
+export declare function writeProfileBundles(profileDir: string, manifest: ProfileManifest, bundles: readonly string[]): ProfileManifest;
+/**
+ * Reconcile installed bundle declarations after a successful package-manager operation.
+ * Dependency-managed entries disappear when removed or when their package loses its declaration;
+ * template entries retain their order and duplicates. New bundle dependencies activate automatically.
+ * @param options - location, inventory captured before pnpm, and whether explicitly disabled bundles remain disabled.
+ * @returns updated inventory and newly added ordinary dependencies for caller-owned warnings.
+ */
+export declare function reconcileProfilePlugins(options: ProfilePluginLocation & {
+    readonly before: ProfilePluginInventory;
+    readonly preserveDisabled: boolean;
+}): ProfilePluginReconciliation;
+//# sourceMappingURL=profile-plugins.d.ts.map

package/lib/types/profile-resolution/legacy-links.d.ts

@@ -0,0 +1,35 @@
+/** Legacy profile-link inspection shared by the disk materializer and runtime resolver. */
+/** Profile-private package links projected into its pnpm-managed node_modules. */
+export declare const PROFILE_MODULE_FALLBACK_DIR = ".dsh-module-fallback";
+/**
+ * Return whether the process reads application modules from pkg's virtual filesystem.
+ * @returns whether pkg owns the module filesystem.
+ */
+export declare function isPackagedExecutable(): boolean;
+/**
+ * Resolve a directory through the active carrier's filesystem implementation.
+ * @param path - directory path to canonicalize.
+ * @returns the canonical directory path.
+ */
+export declare function realModuleDirectory(path: string): string;
+/**
+ * Resolve a link target without following the final path component.
+ * @param path - candidate path whose parent is canonicalized.
+ * @returns the canonical candidate, or undefined when its parent is absent.
+ */
+export declare function canonicalLinkPath(path: string): string | undefined;
+/**
+ * Return whether a symlink or junction points at the same path as `target`.
+ * @param link - symlink or junction to inspect.
+ * @param target - expected target path.
+ * @returns whether both paths identify the same entry.
+ */
+export declare function symlinkPointsTo(link: string, target: string): boolean;
+/**
+ * Return whether an observed profile package must not claim local precedence.
+ * @param profileDir - profile directory containing the package projection.
+ * @param packageName - bare package name to inspect.
+ * @returns whether the entry is a managed fallback link or disappeared during inspection.
+ */
+export declare function isProfileModuleFallbackLink(profileDir: string, packageName: string): boolean;
+//# sourceMappingURL=legacy-links.d.ts.map

package/lib/types/profile-resolution/resolver.d.ts

@@ -0,0 +1,43 @@
+/** In-memory profile package routing for Node's default ESM and CommonJS loaders. */
+import type { ProfileResolutionGeneration } from '../profile.ts';
+/** Whether runtime resolution redirects requests or verifies the materialized backend. */
+export type ProfileResolutionBehavior = 'enforce' | 'verify';
+/** Active resolver registration in one Node isolate. */
+export interface ProfileResolutionRegistration {
+    /**
+     * Locate a bare package without requiring one of its exports.
+     * @param specifier - bare package or package-subpath specifier.
+     * @param parentURL - file URL whose lookup order applies.
+     * @returns selected package directory, or undefined when it is absent.
+     */
+    packageDir(specifier: string, parentURL: string): string | undefined;
+    /**
+     * Atomically publish an additive package table and fresh generation-owned caches.
+     * @param generation - fully constructed successor generation.
+     * @throws when the profile scope or an existing package mapping changes.
+     */
+    replace(generation: ProfileResolutionGeneration): void;
+    /** Restore the native resolver methods. Registrations dispose in reverse order. */
+    dispose(): void;
+}
+/**
+ * Split a bare request into its package name without allocating path segments.
+ * @param request - module specifier to classify.
+ * @returns the bare package name, or undefined for non-package requests.
+ */
+export declare function barePackageName(request: string): string | undefined;
+/**
+ * Install one profile generation on Node's default ESM and CommonJS resolvers.
+ * @param generation - complete package table and profile scope.
+ * @param behavior - enforce the generation, or verify a materialized generation.
+ * @returns a registration that replaces the generation or restores the native methods.
+ */
+export declare function installProfileResolution(generation: ProfileResolutionGeneration, behavior?: ProfileResolutionBehavior): ProfileResolutionRegistration;
+/**
+ * Publish one generation for Harness-owned Workers.
+ * @param generation - complete package table and profile scope.
+ * @param behavior - enforce or verify the generation in newly created Workers.
+ * @returns a disposer restoring the previous thread environment data.
+ */
+export declare function registerWorkerResolution(generation: ProfileResolutionGeneration, behavior?: ProfileResolutionBehavior): () => void;
+//# sourceMappingURL=resolver.d.ts.map

package/lib/types/profile-resolution/service.d.ts

@@ -0,0 +1,51 @@
+/** Package metadata resolved through one profile resolution registration. */
+import { Service, type Context } from '@deepseek-ai/cordis';
+import { type ProfileResolutionBehavior } from './resolver.ts';
+import type { ProfileResolutionGeneration } from '../profile.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Deterministic package lookup for configured plugin specifiers. */
+        pluginPackages: PluginPackages;
+    }
+}
+/** The package that owns a resolved module. */
+export interface PluginPackage {
+    /** Manifest package name. */
+    name: string;
+    /** Manifest version when declared. */
+    version: string | undefined;
+    /** Absolute package directory. */
+    dir: string;
+    /** Absolute package.json path. */
+    manifestPath: string;
+    /** Parsed manifest shared by metadata readers. */
+    manifest: Record<string, unknown>;
+}
+/** Optional runtime resolver installed and owned by {@link PluginPackages}. */
+export interface PluginPackagesConfig {
+    /** Complete package table; omit it to expose native package lookup only. */
+    generation?: ProfileResolutionGeneration;
+    /** Enforce the table or compare it with a materialized fallback. */
+    behavior?: ProfileResolutionBehavior;
+}
+/** Package lookup shared by metadata consumers in one profile process. */
+export declare class PluginPackages extends Service {
+    private packages;
+    private readonly resolver;
+    private readonly behavior;
+    private disposeWorkerResolution;
+    constructor(ctx: Context, config?: PluginPackagesConfig);
+    /**
+     * Publish an additive generation for this process and subsequently created Workers.
+     * @param generation - fully constructed successor generation.
+     */
+    replace(generation: ProfileResolutionGeneration): void;
+    /**
+     * Locate the package named by a specifier without requiring a package export.
+     * @param specifier - module specifier whose package owns the requested module.
+     * @param parentURL - URL whose Node lookup order applies.
+     * @returns the parsed package, or undefined when no package owns the request.
+     */
+    packageOf(specifier: string, parentURL: string): PluginPackage | undefined;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/profile-resolution/worker-bootstrap.d.ts

@@ -0,0 +1,3 @@
+/** Install an inherited profile resolution generation in one Harness-owned Worker. */
+export {};
+//# sourceMappingURL=worker-bootstrap.d.ts.map

package/lib/types/profile-sanitize.d.ts

@@ -0,0 +1,13 @@
+/** Filesystem recovery for callers that own profile shutdown and write exclusion. */
+/**
+ * Back up the profile patch and retain only the caller's recovery bundles.
+ * The caller must stop the profile and exclude concurrent profile writes.
+ * Installed packages and other manifest fields are preserved; patches are never parsed.
+ * Failures propagate and may leave completed changes in place for a retry.
+ * @param binName - Diagnostic prefix for invalid profile manifests.
+ * @param profileDir - Profile directory to recover without loading its plugins.
+ * @param bundles - Ordered bundles to enable after recovery.
+ * @returns Backup path with a Unix millisecond timestamp and optional collision ordinal, or undefined if absent.
+ */
+export declare function sanitizeProfile(binName: string, profileDir: string, bundles: readonly string[]): string | undefined;
+//# sourceMappingURL=profile-sanitize.d.ts.map

package/lib/types/profile.d.ts

@@ -24,7 +24,7 @@
  */
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
-import type { DshManifest, ProfilePatchReload } from '@deepseek-ai/dsh-package-manifest';
+import type { DshPackageManifest } from '@deepseek-ai/dsh-package-manifest';
 /** Directory under the Harness home holding every profile. */
 export declare const PROFILES_DIR = "profiles";
 /** The user patch layer inside a profile directory (hot-reloaded on long-lived surfaces). */
@@ -33,16 +33,9 @@ export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
 export interface ProfileTemplate {
     /** Ordered bundle layer list. */
     bundles: readonly string[];
-    /** User patch-file lifecycle for the generated profile. */
-    patchReload: ProfilePatchReload;
-}
-/** The slice of package.json both profiles and bundles use. */
-export interface ProfileManifest {
-    name?: string;
-    dependencies?: Record<string, string>;
-    peerDependencies?: Record<string, string>;
-    dsh?: DshManifest;
 }
+/** Package metadata accepted by the profile reader; local profiles need no published identity. */
+export type ProfileManifest = Partial<DshPackageManifest>;
 /** One resolved bundle layer of a profile. */
 export interface ProfileLayer {
     /** The bundle's package name, as listed in `dsh.profile.bundles`. */
@@ -66,9 +59,33 @@ export interface Profile {
     patchPath: string;
     /** The profile's own patches; empty when the file is absent. */
     patches: PatchOptions[];
-    /** Whether the launcher watches user patch files after boot. */
-    patchReload: ProfilePatchReload;
 }
+/** One package selected by the profile module-fallback rules. */
+export interface ProfileResolutionEntry {
+    /** Bare package name. */
+    readonly name: string;
+    /** Package directory selected by the existing dependency traversal. */
+    readonly packageDir: string;
+    /** Selected package version when its manifest declares one. */
+    readonly version: string | undefined;
+    /** Manifest whose dependency edge selected this package. */
+    readonly declarer: string;
+    /** Whether every profile or only the active profile receives this fallback. */
+    readonly scope: 'installation' | 'profile';
+}
+/** Complete immutable fallback table for one profile launch. */
+export interface ProfileResolutionGeneration {
+    /** Directory containing every profile and the shared fallback position. */
+    readonly profilesDir: string;
+    /** Active profile directory, when bundle-only fallbacks were included. */
+    readonly profileDir: string | undefined;
+    /** Profile-declared packages already installed before the fallback position. */
+    readonly localPackageNames: readonly string[];
+    /** Installation entries followed by bundle-only entries in precedence order. */
+    readonly entries: readonly ProfileResolutionEntry[];
+}
+/** Startup backend selection for one computed profile resolution generation. */
+export type ProfileResolutionMode = 'link' | 'dual' | 'runtime';
 /**
  * Resolve a profile's directory under the Harness home.
  * @param name - the profile name (`dsh --profile <name>`).
@@ -80,17 +97,21 @@ export declare function resolveProfileDir(name: string, home?: string): string;
 export declare const PROFILE_TEMPLATES: Record<string, ProfileTemplate>;
 /** The bundle list a `dsh plugin` init uses for a name with no shipped template. */
 export declare const DEFAULT_PROFILE_BUNDLES: readonly string[];
-/** Custom profiles retain the historical live patch-file behavior. */
-export declare const DEFAULT_PROFILE_PATCH_RELOAD: ProfilePatchReload;
+/**
+ * The bundles the dsh installation ships for a person to switch on: each a
+ * runtime dependency of the installation that declares `dsh.bundle.patch`,
+ * selected by no shipped template, and offered switched off by the plugin
+ * manager ([rationale](../../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md)).
+ */
+export declare const OPTIONAL_BUNDLES: readonly string[];
 /**
  * Initialize a profile directory: manifest, empty user patch layer, and the
  * pnpm settings out-of-tree plugins need. Existing files are never touched,
  * so re-running is a no-op on an initialized profile.
  * @param dir - the profile directory from {@link resolveProfileDir}.
  * @param bundles - the initial `dsh.profile.bundles` layer list.
- * @param patchReload - user patch-file lifecycle; custom profiles default to live reload.
  */
-export declare function initProfile(dir: string, bundles: readonly string[], patchReload?: ProfilePatchReload): void;
+export declare function initProfile(dir: string, bundles: readonly string[]): void;
 /** Inputs for {@link healProfilesModuleFallback}. */
 export interface ProfileModuleFallbackOptions {
     /** Absolute package.json path of the running dsh installation. */
@@ -99,6 +120,8 @@ export interface ProfileModuleFallbackOptions {
     profile?: Profile;
     /** Harness home; defaults to {@link resolveDshHome}. */
     home?: string;
+    /** Whether to materialize the computed generation; defaults to true. */
+    materialize?: boolean;
 }
 /**
  * Maintain module fallbacks for one profile launch. The shared
@@ -110,9 +133,31 @@ export interface ProfileModuleFallbackOptions {
  * `node_modules`; pnpm-managed entries remain authoritative, and another
  * profile's links cannot change its resolution.
  * @param options - installation anchor, optional loaded profile, and Harness home.
- * @returns settlement after the shared fallback and profile-local links are current.
+ * @returns the computed fallback generation after optional materialization.
+ */
+export declare function healProfilesModuleFallback(options: ProfileModuleFallbackOptions): Promise<ProfileResolutionGeneration>;
+/**
+ * Compute a profile resolution generation without materializing links or proxies.
+ * @param options - installation anchor, profile, and optional Harness home.
+ * @returns the complete immutable generation.
+ */
+export declare function createProfileResolutionGeneration(options: Omit<ProfileModuleFallbackOptions, 'materialize'>): Promise<ProfileResolutionGeneration>;
+/**
+ * Supply an application-owned profile with filesystem packages from its installation and selected bundles.
+ * All fallback links belong to the profile; no shared Harness-home directory is written.
+ * Existing pnpm-managed packages remain authoritative. The caller serializes profile mutations.
+ * @param options - owning installation package.json and the loaded application profile.
+ */
+export declare function healIsolatedProfileModuleFallback(options: {
+    installAnchor: string;
+    profile: Profile;
+}): void;
+/**
+ * Detach this profile's fallback links before a package-manager mutation.
+ * Installed packages and links replaced by pnpm remain untouched; the next profile launch restores fallbacks.
+ * @param profileDir - profile directory whose package mutation is serialized by the caller.
  */
-export declare function healProfilesModuleFallback(options: ProfileModuleFallbackOptions): Promise<void>;
+export declare function unlinkProfileModuleFallback(profileDir: string): void;
 /**
  * Read a profile's manifest.
  * @param binName - the diagnostic prefix on the thrown error.