@qlzt/dsh-app-boot 0.0.0-stage → 0.2.1-alpha.3

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

@@ -0,0 +1,50 @@
+/** Independent profile metadata; neither package manifests nor Cordis patches carry grants. */
+export declare const PROFILE_COMPATIBILITY_FILENAME = "compatibility.json";
+/** Test whether an exemption names a canonical exact SemVer, including build metadata.
+ * @param value Version supplied by a manifest or user.
+ * @returns False for ranges, prefixes, whitespace, and malformed versions.
+ */
+export declare function isExactPluginVersion(value: string): boolean;
+/** Validate one explicit exemption without granting it.
+ * @param packageVersion Exact npm package-name@version, never an installation spec or range.
+ * @param runtimeVersion Exact DSH version, including prerelease and build metadata.
+ * @throws When either identity is not canonical.
+ */
+export declare function validatePluginVersionExemption(packageVersion: string, runtimeVersion: string): void;
+/** What one profile's compatibility file currently authorizes, and what is wrong with it. */
+export interface ProfileCompatibility {
+    /** Accepted exact package-name@version keys mapped to their allowed DSH versions. */
+    readonly exemptions: Record<string, string[]>;
+    /** Human-readable problems; empty when every record was accepted. */
+    readonly warnings: string[];
+    /**
+     * Whether the file holds nothing this reader rejected, so a grant or revocation may rewrite it.
+     * A false value means writing would discard content the user must repair by hand.
+     */
+    readonly rewritable: boolean;
+}
+/** Read the profile's independent compatibility file without loading plugins.
+ * A missing file authorizes nothing. An unreadable or unparsable file authorizes nothing and is
+ * reported instead of failing, so a bad file can never make the profile unusable; rejected records
+ * are skipped while the remaining valid ones still apply.
+ * @param profileDir Absolute profile directory.
+ * @returns Accepted exemptions plus every problem found; no manifest fallback is used.
+ */
+export declare function readProfileCompatibility(profileDir: string): ProfileCompatibility;
+/** Read only the accepted exemptions of a profile.
+ * @param profileDir Absolute profile directory.
+ * @returns Exact package-name@version keys mapped to their allowed DSH versions.
+ */
+export declare function readProfileVersionExemptions(profileDir: string): Record<string, string[]>;
+/** Persist one informed grant or revocation under the compatibility file's own lock.
+ * @param profileDir Profile directory; no package manifest is created or modified.
+ * @param packageVersion Exact manifest package-name@version.
+ * @param runtimeVersion Exact DSH version; grants must name the current runtime, revocations may name historical ones.
+ * @param enabled Whether to grant rather than revoke.
+ * @param acceptRisk Required true for grants after explicit acknowledgement of possible crashes or data loss.
+ * @returns After the atomic write. Existing plugin instances are not reloaded by this operation.
+ * @throws For invalid identities, missing consent, a stale runtime, or a file the reader rejected,
+ * which the user must repair by hand because rewriting it would discard their content.
+ */
+export declare function setProfileVersionExemption(profileDir: string, packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk: boolean): Promise<void>;
+//# sourceMappingURL=profile-compatibility.d.ts.map

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,15 @@
+/** Package directory and resource canonicalization through the active runtime carrier's filesystem. */
+/**
+ * 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;
+/** Canonicalize a module resource, preserving physical file aliases.
+ * SEA archive files are symlink-free and support stat and reads, while their containing directories support realpath.
+ * @param path Existing module resource path.
+ * @returns Canonical resource path under the active carrier's filesystem.
+ * @throws When the resource or its directory cannot be inspected or resolved.
+ */
+export declare function realModuleFile(path: string): string;
+//# sourceMappingURL=legacy-links.d.ts.map

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

@@ -0,0 +1,45 @@
+/** In-memory profile package routing for Node's default ESM and CommonJS loaders. */
+import type { RuntimeResolution } from '../profile.ts';
+/** Active interception in one Node isolate. */
+export interface RuntimeInterception {
+    /**
+     * Locate a bare package without requiring one of its exports.
+     * A package subpath selects its package directory without resolving or validating the requested file.
+     * @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 a complete successor and fresh caches. Profile-scoped mappings, local names, and linked
+     * roots may be removed; removed roots stop intercepting uncovered directories. Existing modules and Node caches
+     * remain intact, so callers remove a package only after its plugins stop.
+     * A retained profile mapping may change its declarer if its normalized directory, version, and scope stay unchanged.
+     * @param successor - fully constructed generation retaining the installation mappings.
+     * @throws when the profile scope, a retained directory, version, scope, or installation declarer changes;
+     * an installation mapping is removed; a new local name overrides an existing mapping; or a previously published
+     * link name selects a different real directory.
+     */
+    replace(successor: RuntimeResolution): void;
+    /** Restore the native resolver methods. Interceptions 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 runtime resolution as the interception on Node's default ESM and CommonJS resolvers.
+ * @param resolution - complete package table and profile scope.
+ * @returns an interception that publishes a successor or restores the native methods.
+ */
+export declare function installRuntimeInterception(resolution: RuntimeResolution): RuntimeInterception;
+/**
+ * Publish one runtime resolution for Harness-owned Workers.
+ * @param resolution - complete package table and profile scope.
+ * @returns a disposer restoring the previous thread environment data.
+ */
+export declare function registerWorkerResolution(resolution: RuntimeResolution): () => void;
+//# sourceMappingURL=resolver.d.ts.map

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

@@ -0,0 +1,66 @@
+/** Package metadata resolved through one runtime interception. */
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { PluginLocalizedMeta } from '@qlzt/dsh-package-manifest';
+import { type RuntimeResolution } 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 interception installed and owned by {@link PluginPackages}. */
+export interface PluginPackagesConfig {
+    /** Complete package table; omit it to expose native package lookup only. */
+    resolution?: RuntimeResolution;
+}
+/** Package lookup shared by metadata consumers in one profile process. */
+export declare class PluginPackages extends Service {
+    private packages;
+    private readonly interception;
+    private disposeWorkerResolution;
+    private current;
+    constructor(ctx: Context, config?: PluginPackagesConfig);
+    /**
+     * Publish a complete successor generation for this process and subsequently created Workers.
+     * Profile mappings and local package names may be removed after their plugins stop; linked roots may also be removed.
+     * Retained profile mappings may change their declarer, but not their normalized directory, version, or scope;
+     * installation mappings must remain unchanged. Publication does not unload modules or clear Node caches.
+     * @param successor - fully constructed generation accepted by {@link RuntimeInterception.replace}.
+     */
+    replace(successor: RuntimeResolution): void;
+    /**
+     * Publish the latest generation computed by the installed resolution through {@link replace}. Package contents
+     * and loaded modules are not reloaded.
+     * @throws when no resolution is installed, it is plain data rather than a {@link ProfileRuntimeResolution},
+     * reading the latest files fails, or the successor is rejected. A computed resolution without a profile can refresh.
+     */
+    refresh(): Promise<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;
+    /**
+     * Read display metadata without loading or activating the target plugin.
+     * @param specifier - configured package module, including package subpaths.
+     * @param parentURL - owning Loader tree's resolution base.
+     * @returns local display metadata or its diagnostic; undefined for non-package requests or absent metadata.
+     */
+    metaOf(specifier: string, parentURL: string): PluginLocalizedMeta | undefined;
+}
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1,3 @@
+/** Install the inherited runtime resolution 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

@@ -0,0 +1,277 @@
+/**
+ * Profile discovery, initialization, and patch-layer composition for the
+ * `dsh --profile` launcher family.
+ *
+ * A profile is a directory under `$DSH_HOME/profiles/<name>` holding a
+ * `package.json` (out-of-tree plugin dependencies plus the profile manifest
+ * `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml`
+ * (the user's own patch layer, applied after every bundle layer). Bundles are
+ * npm packages whose manifest declares
+ * `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` (one file, or an
+ * ordered list of files); the tree is composed by applying each bundle's patch
+ * lists in `dsh.profile.bundles` order over an empty entry list, then the
+ * profile's own patches, then any launcher layers (`--patch` files and
+ * flag-derived patches).
+ *
+ * Module resolution is two-anchor by construction: a bundle name resolves
+ * first from the dsh installation (the launcher's own package), then from the
+ * profile directory. Pnpm-managed entries in the profile's `node_modules`
+ * resolve first. The runtime resolution supplies packages carried by the
+ * installation and selected bundles to Node's ESM and CommonJS resolvers.
+ * @module @qlzt/dsh-app-boot/profile
+ */
+import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
+import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
+import type { DshBundleManifest, DshPackageManifest } from '@qlzt/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). */
+export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
+/** Installation-owned defaults used when a shipped profile is first opened. */
+export interface ProfileTemplate {
+    /** Ordered bundle layer list. */
+    bundles: readonly string[];
+}
+/** Package metadata accepted by the profile reader; local profiles need no published identity. */
+export type ProfileManifest = Partial<DshPackageManifest>;
+/**
+ * The patch files a bundle declares, as written: one file for a string
+ * `patch`, the listed files in order for an array.
+ * @param bundle - the bundle's `dsh.bundle` declaration, as read from package.json.
+ * @returns the package-relative patch file paths in application order.
+ * @throws {Error} when `patch` is neither a string nor a list of strings.
+ */
+export declare function bundlePatchFiles(bundle: DshBundleManifest): string[];
+/**
+ * Resolve a bundle declaration to its ordered absolute patch files.
+ * @param packageDir - absolute directory of the bundle package.
+ * @param bundle - the bundle's `dsh.bundle` declaration, as read from package.json.
+ * @returns the absolute patch file paths in application order.
+ * @throws {Error} when `patch` is neither a string nor a list of strings.
+ */
+export declare function bundlePatchPaths(packageDir: string, bundle: DshBundleManifest): string[];
+/** One resolved bundle layer of a profile. */
+export interface ProfileLayer {
+    /** The bundle's package name, as listed in `dsh.profile.bundles`. */
+    packageName: string;
+    /** Absolute directory of the resolved bundle package. */
+    packageDir: string;
+    /** Absolute paths of the bundle's patch files, in application order. */
+    patchPaths: readonly string[];
+    /** The parsed patch lists of every file, concatenated in application order. */
+    patches: PatchOptions[];
+}
+/** A loaded profile: resolved bundle layers plus the user's own patch layer. */
+export interface Profile {
+    /** The profile name (its directory basename). */
+    name: string;
+    /** Absolute profile directory. */
+    dir: string;
+    /** Bundle layers in `dsh.profile.bundles` order. */
+    layers: ProfileLayer[];
+    /** Absolute path of the profile's own patch file. */
+    patchPath: string;
+    /** The profile's own patches; empty when the file is absent. */
+    patches: PatchOptions[];
+    /** Selected bundles that contributed no layer, in `dsh.profile.bundles` order, with why. */
+    skippedBundles: SkippedBundle[];
+}
+/** A selected bundle the profile could not load, or whose own DSH peers the profile does not exempt. */
+export interface SkippedBundle {
+    /** The bundle's package name from `dsh.profile.bundles`. */
+    packageName: string;
+    /** The resolution, manifest, compatibility, or patch-loading failure. */
+    reason: string;
+}
+/**
+ * Print each skipped bundle once; loading never prints, so launchers call this once per start.
+ * @param binName - the diagnostic prefix.
+ * @param profile - the loaded profile.
+ */
+export declare function reportSkippedBundles(binName: string, profile: Pick<Profile, 'skippedBundles'>): void;
+/** One package the runtime resolution supplies at the interception layer. */
+export interface RuntimeResolutionEntry {
+    /** 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 entry. */
+    readonly scope: 'installation' | 'profile';
+}
+/**
+ * A profile node_modules entry linked to a directory outside the shared profiles tree and the active profile.
+ * Importers below `realPath` use Node's real ancestor chain, with peer mappings read at each node_modules position.
+ */
+export interface LinkedRoot {
+    /** Package name of the profile `node_modules` entry, including its scope. */
+    readonly name: string;
+    /** Real directory outside the shared profiles tree and active profile; a package.json is optional. */
+    readonly realPath: string;
+}
+/** Complete immutable package table for one profile launch. */
+export interface RuntimeResolution {
+    /** Directory containing every profile; its node_modules is the interception layer. */
+    readonly profilesDir: string;
+    /** Active profile directory, when profile-scope entries were included. */
+    readonly profileDir: string | undefined;
+    /** Profile-declared packages installed in the profile's own node_modules. */
+    readonly localPackageNames: readonly string[];
+    /** Installation-scope entries followed by profile-scope entries in precedence order. */
+    readonly entries: readonly RuntimeResolutionEntry[];
+    /** Active profile links to external directories, sorted by name. */
+    readonly linkedRoots: readonly LinkedRoot[];
+}
+/**
+ * Resolve a profile's directory under the Harness home.
+ * @param name - the profile name (`dsh --profile <name>`).
+ * @param home - the Harness home; defaults to {@link resolveDshHome}.
+ * @returns the absolute profile directory (which may not exist yet).
+ */
+export declare function resolveProfileDir(name: string, home?: string): string;
+/** The shipped profile templates auto-initialized on first use, by name. */
+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[];
+/**
+ * The bundles the dsh installation ships for a person to switch on: each a
+ * runtime dependency of the installation that declares `dsh.bundle.patch`,
+ * an `icon`, and `./locale/*.json` display metadata, 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),
+ * [admission](../../../../.agents/notes/implemented/architecture/2026-09-21-experimental-capabilities-as-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.
+ */
+export declare function initProfile(dir: string, bundles: readonly string[]): void;
+/**
+ * Remove the package projections a link-backend launch left in a profile.
+ * Only symlinks under the profile's `node_modules` whose target lies inside
+ * `<profile>/.dsh-module-fallback/node_modules` are unlinked, then that directory is removed;
+ * pnpm-installed packages and every other symlink stay. A profile without the directory is untouched.
+ * @param dir - the profile directory.
+ */
+export declare function removeLinkProjections(dir: string): void;
+/** Inputs for {@link createRuntimeResolution}. */
+export interface RuntimeResolutionOptions {
+    /** Absolute package.json path of the running dsh installation. */
+    installAnchor: string;
+    /** Loaded profile whose selected bundles may carry profile-local plugins. */
+    profile?: Profile;
+    /** Harness home; defaults to {@link resolveDshHome}. */
+    home?: string;
+}
+/**
+ * Compute the runtime resolution without writing module-resolution files.
+ * @param options - installation anchor, optional loaded profile, and Harness home.
+ * @returns the complete immutable runtime resolution.
+ */
+export declare function createRuntimeResolution(options: RuntimeResolutionOptions): Promise<ProfileRuntimeResolution>;
+/** Inputs a {@link ProfileRuntimeResolution} reuses to compute its successor. */
+interface ResolutionSource {
+    installAnchor: string;
+    home: string;
+    profileDir: string | undefined;
+}
+/**
+ * A runtime resolution that remembers the inputs it was computed from. Worker environment data carries only its
+ * fields; the inputs stay private to the thread that computed it.
+ */
+export declare class ProfileRuntimeResolution implements RuntimeResolution {
+    #private;
+    readonly profilesDir: string;
+    readonly profileDir: string | undefined;
+    readonly localPackageNames: readonly string[];
+    readonly entries: readonly RuntimeResolutionEntry[];
+    readonly linkedRoots: readonly LinkedRoot[];
+    /**
+     * @param source - inputs of {@link createRuntimeResolution}, reused by {@link computeLatestResolution}.
+     * @param table - the computed package table.
+     */
+    constructor(source: ResolutionSource, table: RuntimeResolution);
+    /**
+     * Compute the latest generation from the same installation, profile directory, and Harness home, rereading the
+     * profile's manifest, bundle selection, and installed packages from disk, without retaining synthetic layers.
+     * With no profile directory, only installation packages are recomputed. This instance is unchanged.
+     * @returns a new resolution for the latest generation.
+     */
+    computeLatestResolution(): Promise<ProfileRuntimeResolution>;
+}
+/**
+ * Read a profile's manifest.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param dir - the profile directory.
+ * @returns the parsed manifest.
+ */
+export declare function readProfileManifest(binName: string, dir: string): ProfileManifest;
+/**
+ * Write a profile's manifest back (2-space JSON, trailing newline).
+ * @param dir - the profile directory.
+ * @param manifest - the manifest value to persist.
+ */
+export declare function writeProfileManifest(dir: string, manifest: ProfileManifest): void;
+/**
+ * Resolve one bundle package's directory: installation anchor first, then the
+ * profile directory. The installation-first order is the contract that
+ * `@qlzt/dsh-base` (and every other in-box bundle) always comes from
+ * the same installation as the running dsh, never from a profile-local copy.
+ * Resolution does not require the package to export `./package.json`.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param packageName - the bundle's package name from `dsh.profile.bundles`.
+ * @param installAnchor - absolute path of a file inside the dsh app package (its package.json).
+ * @param profileDir - the profile directory (second anchor).
+ * @returns the bundle package's absolute directory.
+ */
+export declare function resolveBundleDir(binName: string, packageName: string, installAnchor: string, profileDir: string): string;
+/**
+ * Load an already initialized profile directory without resolving it through
+ * the shared Harness home. This is used by application-owned profiles whose
+ * package project and lifecycle belong to that application.
+ * Retired bundles are removed from the stored bundle list first, rewriting the
+ * manifest when it listed one. Unreadable bundles, and bundles whose own dsh peers the profile does not exempt, are skipped
+ * without changing the manifest and listed in `skippedBundles`; nothing is printed.
+ * @param binName - the diagnostic prefix on thrown errors.
+ * @param dir - absolute profile package directory.
+ * @param installAnchor - absolute path of the owning dsh app's package.json.
+ * @param options - `userLayer: false` skips reading `cordis.patch.yml`.
+ * @returns the successfully loaded bundle layers and optional user patch layer.
+ */
+export declare function loadProfileDirectory(binName: string, dir: string, installAnchor: string, options?: {
+    userLayer?: boolean;
+}): Profile;
+/**
+ * Load a profile: resolve every `dsh.profile.bundles` entry to its patch
+ * layer and parse the profile's own patch file. Unreadable or incompatible bundles
+ * are skipped and listed in `skippedBundles`; profile manifest and user patch errors still throw.
+ * @param binName - the diagnostic prefix on thrown errors.
+ * @param name - the profile name.
+ * @param installAnchor - absolute path of the dsh app's package.json (first resolution anchor).
+ * @param home - the Harness home; defaults to {@link resolveDshHome}.
+ * @param options - `userLayer: false` skips reading `cordis.patch.yml`, so a
+ * bundles-only consumer (`--dump-default-config`, a recovery diagnostic)
+ * cannot fail on a broken user layer.
+ * @returns the loaded profile (empty `patches` when the user layer is skipped).
+ */
+export declare function loadProfile(binName: string, name: string, installAnchor: string, home?: string, options?: {
+    userLayer?: boolean;
+}): Profile;
+/**
+ * Compose patch layers into the effective entry list over an empty root —
+ * the same single `applyEntryPatches` call the boot include makes, so flag
+ * derivation and config dumps see exactly what mounts.
+ * @param layers - patch lists in application order.
+ * @param warn - sink for skipped-patch diagnostics; defaults to silent (boot repeats them).
+ * @returns the composed entry list.
+ */
+export declare function composeEntries(layers: readonly PatchOptions[][], warn?: (message: string) => void): EntryOptions[];
+export {};
+//# sourceMappingURL=profile.d.ts.map