@lmzhen/dsh-evolution-core 0.16.1 → 0.17.0

package/lib/types/errors.d.ts

@@ -36,6 +36,8 @@ export declare const EVOLUTION_ERRORS: Readonly<{
     readonly 'e-305-this-invocation-carries-no-2': "E-305: this invocation carries no agent — `%a1%` needs a session-backed call (run it from a session in the GUI or the CLI).";
     readonly 'e-317-skill-write-not-confirmed': "E-317: skill \"%a1%\" was not %a2% — the confirmation prompt was declined or dismissed, so nothing was written. The prompt appears on every create and bare delete; repeat the call only if the operator asks for it.";
     readonly 'e-318-skill-write-without-a-read': "E-318: skill \"%a1%\" was not read in this session, so this write is refused. Read it with the `skill` tool first (a read that failed does not count), then repeat the write.";
+    readonly 'e-320-the-profile-home-is-not': "E-320: the profile home is not reported by this host, so the legacy settings document cannot be located. /evolution migrate reads `<profile home>/settings.yaml.imported`; run it from a profile-launched session.";
+    readonly 'e-321-no-io-provider-is': "E-321: no evolution-io provider is mounted, so the legacy settings document cannot be read. Mount the evolution-io row (evolution-host/evolution-all) and retry.";
     readonly 'e-319-skill-write-confirm-timed-out': "E-319: skill \"%a1%\" was not %a2% — the confirmation prompt went unanswered for %a3% second(s), so the write was cancelled. Nobody was there to decide: set `skillWriteConfirm` to `auto` to write without a prompt, keep `ask` to wait until someone answers, or raise `skillWriteConfirmTimeoutSeconds`.";
 }>;
 /** One table key. */

package/lib/types/evidence.d.ts

@@ -19,6 +19,27 @@
  * vocabulary — changes this table and nothing else (`evidenceKindIndex` is the only reader).
  * @module @lmzhen/dsh-evolution-core
  */
+/**
+ * Whether one frame type records a boundary and carries no content.
+ *
+ * The classification table's SECOND reader: the live projection unit
+ * (`session-projection.ts`) folds the same answer per event, so the rule stays one table.
+ * @param type - a platform session-event type.
+ * @returns true for the turn/step bookends.
+ */
+export declare function isBookkeepingFrame(type: string): boolean;
+/**
+ * The one question an evidence index answers: does this seq carry content?
+ *
+ * Structural on purpose — {@link evidenceKindIndex} materializes the dense set of content seqs,
+ * while the projection answers by complement over the sparse boundary seqs
+ * (`session-projection.ts`). Both satisfy this interface, and it is all the plan path reads
+ * (`evolution-plan-validator/src/index.ts:164`).
+ */
+export interface EvidenceIndex {
+    /** @param seq - a cited evidence seq. @returns true when that frame carries content. */
+    has(seq: number): boolean;
+}
 /** One session frame, as far as the classification reads it. A platform `SessionEvent` is
  * assignable: both fields are optional here so a stub log can be classified without pretending
  * to be a full event. */

package/lib/types/index.d.ts

@@ -24,7 +24,9 @@
  *   tool path and the review's plan path), `drift-signals.ts`, `skill-health.ts`,
  *   `preset-composition.ts`, `prompts.ts`, `learn-prompt.ts`,
  *   `evolution-events.ts`, `evidence.ts` (which session frames count as content, for the plan
- *   path's evidence-class report), `io.ts` (the ctx.evolutionIo seam itself).
+ *   path's evidence-class report), `session-projection.ts` (the live per-session units the family's
+ *   log-shaped readers read instead of re-reading the session log), `io.ts` (the ctx.evolutionIo
+ *   seam itself).
  * @module @lmzhen/dsh-evolution-core
  */
 export * from './citations.ts';
@@ -58,6 +60,7 @@ export * from './skill-reads.ts';
 export * from './skill-row-cells.ts';
 export * from './document-body.ts';
 export * from './evidence.ts';
+export * from './session-projection.ts';
 export * from './drift-signals.ts';
 export * from './skill-history.ts';
 export * from './skill-store.ts';
@@ -67,6 +70,7 @@ export * from './tool-dispatch.ts';
 export * from './usage.ts';
 export * from './constants.ts';
 export * from './params.ts';
+export * from './namespace-migration.ts';
 export * from './numeric.ts';
 export * from './opt-in.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/types/namespace-migration.d.ts

@@ -0,0 +1,133 @@
+/** One value a legacy section carried, with the spelling it used. */
+export interface NamespaceMigrationValue {
+    /** The key as the legacy document spelled it (canonical or deprecated alias). */
+    readonly source: string;
+    /** The canonical registry id the value is written under. */
+    readonly key: string;
+    /** The parsed value. */
+    readonly value: unknown;
+}
+/** One row's migration target. */
+export interface NamespaceMigrationEntry {
+    /** The legacy section the values sit in. */
+    readonly namespace: string;
+    /** The row id the platform keys the settings by now. */
+    readonly rowId: string;
+    /** The values to merge into that row, in document order. */
+    readonly values: readonly NamespaceMigrationValue[];
+}
+/** One legacy key no row may take. */
+export interface NamespaceMigrationSkip {
+    /** The legacy section it sat in. */
+    readonly namespace: string;
+    /** The key as spelled. */
+    readonly key: string;
+    /** Why it is not migrated. */
+    readonly reason: string;
+}
+/** What a legacy document asks for. */
+export interface NamespaceMigrationPlan {
+    /** One entry per legacy section that carried values a row can take. */
+    readonly entries: readonly NamespaceMigrationEntry[];
+    /** Legacy sections the family knows but that carried nothing mappable. */
+    readonly empty: readonly string[];
+    /** Top-level sections that are not family legacy sections (the platform's own). */
+    readonly foreign: readonly string[];
+    /** Keys that were found but not migrated. */
+    readonly skipped: readonly NamespaceMigrationSkip[];
+}
+/**
+ * Read one legacy settings document into a migration plan.
+ *
+ * Pure: the caller reads the file (the platform's renamed `settings.yaml.imported` first,
+ * then a `settings.yaml` the platform has not imported yet) and hands the text over.
+ * @param documentText - the YAML document text.
+ * @returns what to write, what the family knows but need not touch, and what it refused.
+ * @throws {Error} when the document is not a mapping, or a family section is not one.
+ */
+export declare function planNamespaceMigration(documentText: string): NamespaceMigrationPlan;
+/** One key the target row already carried. */
+export interface NamespaceMigrationConflict {
+    /** The row id. */
+    readonly rowId: string;
+    /** The canonical key. */
+    readonly key: string;
+    /** The value the stored row already holds — it wins. */
+    readonly current: unknown;
+    /** The legacy value that was NOT applied. */
+    readonly legacy: unknown;
+}
+/** What one run did. */
+export interface NamespaceMigrationReport {
+    /** Rows the run wrote, with the keys it merged. */
+    readonly written: readonly {
+        readonly rowId: string;
+        readonly keys: readonly string[];
+    }[];
+    /** Keys whose stored value won over the legacy one. */
+    readonly conflicts: readonly NamespaceMigrationConflict[];
+    /** Keys the target row already held the same value for: no write was needed. */
+    readonly unchanged: readonly {
+        readonly rowId: string;
+        readonly key: string;
+    }[];
+    /** Keys the plan refused (see {@link NamespaceMigrationSkip}). */
+    readonly skipped: readonly NamespaceMigrationSkip[];
+}
+/** Everything {@link applyNamespaceMigration} needs from its caller. */
+export interface NamespaceMigrationDeps {
+    /**
+     * The row's CURRENT user layer, as `settings.describe()` reports it — the raw user
+     * section, not the resolved value: presence of a key is what marks an override.
+     * @param rowId - the row id.
+     * @returns the describe view, or undefined when the platform serves no such row.
+     */
+    read(rowId: string): {
+        readonly user?: Record<string, unknown> | undefined;
+    } | undefined;
+    /**
+     * Merge one row's values (the platform's `settings.update` — merge semantics).
+     * @param rowId - the row id.
+     * @param patch - canonical key to value, the keys the row does not already carry.
+     * @returns settlement after the write is accepted.
+     */
+    update(rowId: string, patch: Readonly<Record<string, unknown>>): Promise<void>;
+    /**
+     * Report one value that was found and not applied.
+     * @param message - the warning text.
+     */
+    warn(message: string): void;
+}
+/**
+/** One row's pending write: the keys that row does not carry yet. */
+export interface NamespaceMigrationWrite {
+    /** The row id. */
+    readonly rowId: string;
+    /** Canonical key to legacy value, for the keys the row does not already hold. */
+    readonly patch: Readonly<Record<string, unknown>>;
+}
+/** What a plan would do against the live document, decided without writing anything. */
+export interface NamespaceMigrationClassification {
+    /** The rows to write, one entry per row. */
+    readonly write: readonly NamespaceMigrationWrite[];
+    /** Keys whose stored value won over the legacy one. */
+    readonly conflicts: readonly NamespaceMigrationConflict[];
+    /** Keys the row already held the same value for. */
+    readonly unchanged: readonly {
+        readonly rowId: string;
+        readonly key: string;
+    }[];
+    /** The plan's refusals, plus the keys of a row this composition does not serve. */
+    readonly skipped: readonly NamespaceMigrationSkip[];
+}
+/**
+ * Decide what a plan would do: the rows it would write, the keys already equal, the stored
+ * values that win, and the refusals. The write half and the read-only doctor read the SAME
+ * decision here — one rule, two consumers, so a report can never disagree with a run.
+ * @param plan - the plan from {@link planNamespaceMigration}.
+ * @param read - the row's current user layer (see {@link NamespaceMigrationDeps.read}).
+ * @returns the decision; nothing is written.
+ */
+export declare function classifyNamespaceMigration(plan: NamespaceMigrationPlan, read: NamespaceMigrationDeps['read']): NamespaceMigrationClassification;
+export declare function applyNamespaceMigration(plan: NamespaceMigrationPlan, deps: NamespaceMigrationDeps): Promise<NamespaceMigrationReport>;
+//# sourceMappingURL=namespace-migration.d.ts.map

package/lib/types/opt-in.d.ts

@@ -15,8 +15,9 @@
  * model tools are visible in its scope. Mounted at profile root they are visible
  * to every session; mounted inside a variant preset they are visible only to the
  * agents that joined that preset's standing scope — every registration inside a
- * preset files into that agent's layer
- * (packages/preset/agent-presets/src/mount.ts:4-13).
+ * preset files into that agent's layer — in 0.2.x the preset is an ordinary row and its
+ * child rows stay in that agent's own layer (`packages/preset/agent-preset/src/index.ts`,
+ * `static [EntryGroup.key] = true`).
  *
  * `sessionScoped` is what a deployment declares: true means "act only on a
  * session that carries the family's model tools", which is the right question in

package/lib/types/params.d.ts

@@ -119,32 +119,62 @@ export declare const PARAM_EXPOSURE: readonly ParamExposure[];
  * user layer (its knobs stay deployment-only). */
 export declare const PARAM_NAMESPACES: Readonly<Record<string, string>>;
 /**
- * The settings namespace one owner package registers. The registry's map is the only
- * place a namespace is spelled: a package without an entry has no user layer, so a
- * missing entry must fail loud here instead of letting a package fall back to a
- * private constant that the registry never sees.
+ * The rows whose settings namespace CHANGED with the platform-line move (G3): the
+ * platform keys a settings section by the Loader entry id now, while 0.1.x let each
+ * plugin register a free-form namespace — this table is the difference, DERIVED from
+ * {@link PARAM_NAMESPACES} so freezing a row id renames it in one place.
+ *
+ * It is the migration's TARGET (`rowId`) and its SOURCE (`namespace`, the section a
+ * stored value sits in). Rows whose two names already agree are absent: there is
+ * nothing to move for them.
+ */
+export declare const NAMESPACE_MIGRATIONS: readonly {
+    readonly namespace: string;
+    readonly rowId: string;
+}[];
+/**
+ * The LEGACY settings namespace one owner package used to register through the family's
+ * own seam (0.1.x). It is no longer what the platform calls the section: the platform
+ * derives a settings namespace from the Loader entry id, and this registry's `owner` field
+ * IS that row id, so a live lookup uses {@link paramRowId}. What remains here is the
+ * migration SOURCE (G3 moves a user layer out of this string and into the row id).
  * @param owner - owner package directory name (the map's key).
- * @returns the namespace that owner registers.
+ * @returns the legacy namespace that owner registered.
  * @throws when the owner has no entry in {@link PARAM_NAMESPACES}.
  */
 export declare function paramNamespace(owner: string): string;
-/** Structural view of one registered settings scope (platform Service Definition).
- * Declared locally so this module keeps its zero-import, zero-dependency shape. */
-interface SettingsScopeLike {
-    get(): unknown;
-    watch(callback: (next: unknown, prev: unknown) => void): () => void;
-}
-/** Structural view of the platform settings provider; only the members the
- * family uses are named. A missing `describe` disables the user layer loudly
- * (see {@link paramSectionOverrides}) instead of reading as 'no overrides'. */
+/**
+ * The settings id one row's user layer lives under, or undefined when the owner publishes
+ * no user layer at all (a deployment-only row: its knobs are E2 and never reach a settings
+ * section). The platform derives a settings namespace from the Loader entry id and reports
+ * it in `settings.describe()` / `configForms.get(entryId)`, and an owner package's row id is
+ * its own name — spelled the same in every bundle patch.
+ *
+ * This is the id to LOOK UP with; {@link paramNamespace} keeps the legacy string the 0.1.x
+ * seam registered, which is the G3 migration source and never a live lookup key.
+ * @param owner - owner package directory name (the row id).
+ * @returns the entry id the platform reports for that row, or undefined for a row without
+ *   a user layer.
+ */
+export declare function paramSettingsId(owner: string): string | undefined;
+/**
+ * The settings id of a row that MUST have a user layer (an owner reading its own section).
+ * @param owner - owner package directory name (the row id).
+ * @returns the entry id the platform reports for that row.
+ * @throws when the owner publishes no user layer.
+ */
+export declare function paramRowId(owner: string): string;
+/**
+ * Structural view of the platform settings provider: only the members the family
+ * still uses are named.
+ *
+ * G1 removed the family's own settings seam (`installParamSection`): a volatile row
+ * field carries the user layer by itself, so what remains is the WRITE face
+ * (`update`) and the one read the precedence rule needs — `describe()`, for the KEY
+ * NAMES the user set. A value is never read from here. Declared locally so this module
+ * keeps its zero-import, zero-dependency shape.
+ */
 export interface SettingsProviderLike {
-    register(namespace: string, schema: unknown, options: {
-        base: unknown;
-        applies?: 'live' | 'restart';
-        /** Owner-side refusal of a resolved section (cross-field rules the schema
-         * cannot express); throwing refuses the WRITE that produced the value. */
-        validate?: (value: unknown) => void;
-    }): SettingsScopeLike;
     /** Merge a patch into one namespace's user layer. A stale `expectedRevision`
      * rejects with the platform's SETTINGS_CONFLICT error. */
     update?(namespace: string, patch: object, expectedRevision?: number): Promise<void>;
@@ -162,69 +192,6 @@ export interface SettingsProviderLike {
         applies?: 'live' | 'restart';
     }[];
 }
-/** Hooks a caller may supply when a section attaches to the settings service.
- * @typeParam T - the section's value type (what `validate` inspects). */
-export interface ParamSectionOptions<T extends object = object> {
-    /** Called once when the user layer turns unreadable (a warning, never silent). */
-    warn?: (message: string) => void;
-    /** Called after every committed change that the reader can observe — the place
-     * to REBUILD registration-level facts (the platform's own `installSection`
-     * documents the same hook shape). Consumers that read at use time pass nothing. */
-    onChange?: () => void;
-    /** Refuse a resolved section the owner could not act on: a cross-field rule the
-     * schema cannot express (the platform applies this hook to the RESOLVED section,
-     * so a user value is judged together with the deployment layer beneath it).
-     * Throwing refuses the write that produced the value. */
-    validate?: (value: T) => void;
-}
-/** Reader for one parameter section: presence-aware user overrides. */
-export interface ParamOverrides<T extends object> {
-    /** The namespace this reader is bound to. */
-    readonly namespace: string;
-    /** The user-set value for one key, or undefined when the user never set it. */
-    get<K extends keyof T & string>(key: K): T[K] | undefined;
-    /** The resolved section (defaults < base < user) — display and tests. */
-    resolved(): T;
-}
-/**
- * G3: expose one parameter section to the user layer.
- *
- * Precedence stays 'user > deployment > default': the caller keeps reading its
- * deployment carriers (policy snapshot, then the plugin row) and consults
- * {@link ParamOverrides.get} FIRST — an unset key returns undefined, so the
- * deployment value keeps winning and the family's shadowing rules survive.
- *
- * Failure posture: a provider without `describe` (or one whose describe throws)
- * leaves the user layer UNAVAILABLE and warns once — deployment values then
- * apply. Treating an unreadable user layer as 'no overrides' would silently
- * ignore a setting the user did write, so the warning names it.
- * @typeParam T - the section's value type.
- * @param provider - the platform settings provider, or undefined when absent.
- * @param namespace - namespace to register.
- * @param schema - schemastery schema the platform validates against.
- * @param base - composition base layer (the plugin row's values).
- * @param options - warning sink and the change hook.
- * @returns a reader bound to the namespace.
- */
-export declare function paramSectionOverrides<T extends object>(provider: SettingsProviderLike | undefined, namespace: string, schema: unknown, base: T, options?: ParamSectionOptions<T>): ParamOverrides<T>;
-/** Minimal structural view of the cordis context used to attach a section.
- * The callback takes `unknown` on purpose: cordis's own `inject` declares a
- * `Context` parameter, and a callback accepting `unknown` is assignable to it
- * (parameter contravariance) while a narrower shape is not. */
-export interface SettingsHostLike {
-    inject(names: string[], callback: (ctx: unknown) => void): unknown;
-}
-/**
- * Attach a parameter section through the optional settings service.
- * @typeParam T - the section's value type.
- * @param host - the plugin context (structurally typed).
- * @param namespace - namespace to register.
- * @param schema - schemastery schema the platform validates against.
- * @param base - composition base layer (the plugin row's values).
- * @param options - warning sink and the change hook.
- * @returns a reader that follows the provider when it appears.
- */
-export declare function installParamSection<T extends object>(host: SettingsHostLike, namespace: string, schema: unknown, base: T, options?: ParamSectionOptions<T>): ParamOverrides<T>;
 /**
  * Number-typed read over {@link readParam}: the family's tunables are numbers,
  * and a value of another type reads as absent so the caller's default applies
@@ -234,5 +201,4 @@ export declare function installParamSection<T extends object>(host: SettingsHost
  * @returns the resolved number, or undefined when absent or not a number.
  */
 export declare function readNumberParam(carrier: object | undefined, id: string): number | undefined;
-export {};
 //# sourceMappingURL=params.d.ts.map

package/lib/types/preset-composition.d.ts

@@ -63,5 +63,162 @@ interface RowOverride {
  * default while nothing downstream reported it.
  */
 export declare function loadRowOverrides(): RowOverride[];
+/** The platform package a DECLARATIVE preset row names (0.2.x replaced preset directories with it). */
+export declare const AGENT_PRESET_PACKAGE = "@deepseek-ai/dsh-agent-preset";
+/** Identity and display metadata of one generated preset row. */
+export interface PresetRowIdentity {
+    /** The composition row id (`- id:`); what {@link mergePresetRow} replaces by. */
+    readonly rowId: string;
+    /** The preset id the platform registry keys on (`evolution` / `evolution-ptc`). */
+    readonly id: string;
+    /** Display name in the preset picker. */
+    readonly name: string;
+    /** One-line description in the preset picker. */
+    readonly description: string;
+    /** Sort order among the registered presets. */
+    readonly order: number;
+}
+export declare function composePresetRow(baseComposition: string, deltaComposition: string, identity: PresetRowIdentity): string;
+/**
+ * Wrap a composed row as the patch entry a profile patch needs.
+ *
+ * The row {@link composePresetRow} returns starts at column 0; a patch entry's list nests it four
+ * spaces deeper. Wrapping is a separate step because the same row text is also what
+ * {@link mergePresetRow} matches by id, and because the composer's override anchors are defined
+ * against column-0 rows.
+ * @param row - the row text, as {@link composePresetRow} returns it.
+ * @returns the patch entry text, newline-terminated.
+ */
+export declare function composePresetInsert(row: string): string;
+/**
+ * The row list a platform base preset patch carries under `config.plugins`, dedented to column 0.
+ *
+ * A base preset arrives as a whole patch entry — `- insert:` / `- id: preset-standard` /
+ * `config:` / `plugins:` — because that is how the platform ships it
+ * (`packages/bundle/web-app/presets/standard.patch.yml`). The preset's own list is the
+ * SHALLOWEST `plugins:` line: a child row may carry a key by that name far deeper.
+ * @param patchText - the base preset patch file's text.
+ * @returns the plugin rows, dedented and newline-terminated.
+ * @throws {Error} when the patch carries no `plugins:` list.
+ */
+export declare function basePresetPlugins(patchText: string): string;
+/** The row id a family preset occupies: the platform ships \`preset-standard\` for id `standard`
+ * (`packages/bundle/web-app/presets/standard.patch.yml`), so a family preset id mirrors it. */
+export declare function presetRowId(id: string): string;
+/**
+ * The patch entry a profile patch receives for one preset: base rows plus the family delta, wrapped
+ * as \`- insert:\`.
+ *
+ * The two halves are also exposed on their own — {@link composePresetRow} for the row, so
+ * {@link mergePresetRow} can match it by id, and {@link basePresetPlugins} to read the platform
+ * base out of a shipped patch.
+ * @param basePatchText - the platform base preset patch's text.
+ * @param deltaComposition - the family delta rows.
+ * @param identity - row id, preset id, display fields and order.
+ * @returns the patch entry text, newline-terminated.
+ */
+export declare function composePresetEntry(basePatchText: string, deltaComposition: string, identity: PresetRowIdentity): string;
+/**
+ * The text of one row's own patch item, or null when the patch carries no such row.
+ *
+ * The comparison unit for a freshness check: this is byte-for-byte what {@link composePresetEntry}
+ * writes for the same row id, whether the row sits inside an \`- insert:\` entry (installer-written)
+ * or at column 0 (saved by the Web editor).
+ * @param patchText - the patch text.
+ * @param rowId - the row id to read.
+ * @returns the item's text, newline-terminated, or null.
+ */
+export declare function presetRowBody(block: string): string;
+/**
+ * The row BODY of a patch block, whichever form it is in.
+ *
+ * {@link presetRowBlock} returns the enclosing item verbatim: an installer-written row sits inside
+ * `- insert:` while a row the platform's Web editor saved IS that column-0 item. A comparison must
+ * compare like with like — comparing the raw block against `composePresetEntry()` (which always
+ * starts with `- insert:`) reported DIFFERS for every editor-saved row, forever (G6 review, P2), and
+ * the remedy it printed (`re-run the installer`) was refused by the `exists; use --force` guard.
+ * @param block - a block as {@link presetRowBlock} returns it.
+ * @returns the row text, `- insert:` unwrapped and its four-space indent stripped.
+ */
+export declare function presetRowBlock(patchText: string, rowId: string): string | null;
+/**
+ * What `DSH_AGENT_PRESET_ROOT` must name: a directory holding the platform base preset patches
+ * under their shipped file names (`<base>.patch.yml`) — e.g. a copy of a same-version platform
+ * tree's `packages/bundle/web-app/presets/`. The desktop application is the shape that needs it:
+ * its platform packages live inside `resources/app.asar`, so there is no plain
+ * `node_modules/@deepseek-ai/dsh-web-app/presets/` on disk for a source installer to read.
+ */
+export declare const AGENT_PRESET_ROOT_HINT = "point DSH_AGENT_PRESET_ROOT at a directory holding <base>.patch.yml (copy it out of a same-version dsh tree: packages/bundle/web-app/presets/)";
+/** Where {@link resolveBasePresetPatch} looks, in order. */
+export interface BasePresetPatchSources {
+    /** Explicit preset root (`DSH_AGENT_PRESET_ROOT`); an ANSWER, never a fallback head. */
+    readonly root?: string | undefined;
+    /** Module-graph probe for the bundle package — the only candidate that reaches inside an Electron
+     * `app.asar`. Receives `@deepseek-ai/dsh-web-app/package.json` and returns its path. */
+    readonly resolve?: ((specifier: string) => string) | undefined;
+    /** Target profile directory; its `node_modules` holds the bundles it mounts. */
+    readonly profileDir?: string | undefined;
+    /** Bundle package names to probe under `<profileDir>/node_modules`. */
+    readonly bundles?: readonly string[] | undefined;
+    /** Directory the ancestor walk starts from — the caller's own file location. */
+    readonly fromDir: string;
+}
+/**
+ * Resolve the platform patch file one `--base` names.
+ *
+ * 0.2.x ships each base preset as a bundle patch layer
+ * (`packages/bundle/web-app/presets/<base>.patch.yml`, declared in that package's
+ * `dsh.bundle.patch`), so the FILE — not a preset directory — is the base a family row is composed
+ * from. Candidates, in order: an explicit `DSH_AGENT_PRESET_ROOT`; a module-graph probe when the
+ * caller supplies one (a desktop/Electron host resolves the bundle inside `app.asar`, where no file
+ * walk can reach); the target profile's own `node_modules`; then, walking up from the caller,
+ * every `presets/` directory of a checkout's bundle packages, then every
+ * `@deepseek-ai/dsh-<name>/presets/` directory of an installed tree.
+ *
+ * A base with no patch file is REFUSED with every probed candidate listed: composing a family preset
+ * from another base's rows would mount rows the user did not ask for, with nothing saying so.
+ * @param base - the base name, already validated against `evolution-agent/bases.json`.
+ * @param sources - the roots to probe.
+ * @returns the patch file's absolute path.
+ * @throws {Error} when no candidate exists.
+ */
+export declare function resolveBasePresetPatch(base: string, sources: BasePresetPatchSources): string;
+/**
+ * Remove one row from a patch, taking its `- insert:` item with it when that item holds nothing
+ * else (an empty insert entry is left-over structure the platform would keep parsing).
+ * @param patchText - the patch text to edit.
+ * @param rowId - the row id to remove.
+ * @returns the patch text, newline-terminated; byte-identical when the id is absent.
+ */
+export declare function removePresetRow(patchText: string, rowId: string): string;
+/**
+ * Merge one generated row into a composition (a profile patch) by row id.
+ *
+ * Idempotent by construction: an existing row with the same `- id:` is REPLACED whole — its block
+ * is the enclosing column-0 list item, so an installer-written row inside `- insert:` and a
+ * Web-editor-saved row at column 0 are both matched by {@link rowBlockSpan} — and anything else in
+ * the patch stays byte-identical, because the patch usually carries rows this installer knows
+ * nothing about. A missing row is appended.
+ *
+ * The platform seeds a fresh profile patch with the empty list `[]`
+ * (`packages/boot/app-boot/src/profile.ts`, `PROFILE_PATCH_FILENAME`), which is a COMPLETE YAML
+ * document: a block sequence appended after it is not parsable. That seed is therefore replaced, not
+ * extended.
+ * @param patchText - the current patch text (`''` for a fresh one).
+ * @param row - the row text, as {@link composePresetRow} returns it.
+ * @param rowId - the row id to replace or append.
+ * @returns the merged patch text, newline-terminated.
+ */
+export declare function mergePresetRow(patchText: string, row: string, rowId: string): string;
+/** The empty patch list the platform seeds a profile patch with; see {@link mergePresetRow}. */
+export declare const EMPTY_PATCH_SEED = "[]";
+/**
+ * The text to write when a patch is left with no entries.
+ *
+ * A zero-byte patch file is not what the platform writes or parses; its own seed is the empty list.
+ * @param patchText - the text {@link removePresetRow} returned.
+ * @returns the platform's empty-list seed when nothing is left, the text otherwise.
+ */
+export declare function presetPatchText(patchText: string): string;
 export {};
 //# sourceMappingURL=preset-composition.d.ts.map