@lmzhen/dsh-evolution-core 0.26.15 → 0.27.0

package/lib/types/mutations.js

@@ -0,0 +1,95 @@
+/**
+ * Curator/author audit trail: `.mutations.json` records every skill mutation
+ * with before/after content hashes so any automated edit is reviewable and
+ * replayable. Best-effort persistence, mirroring the usage sidecar posture.
+ * @module @lmzhen/dsh-evolution-core
+ */
+import { createHash } from 'node:crypto';
+import { isRecord } from "./guards.js";
+import { join } from 'node:path';
+import { nodeEvolutionIo, transactIo } from "./io.js";
+export const DEFAULT_MUTATION_CAP = 500;
+/** Version of the `.mutations.json` file shape; writers always emit the current one. */
+export const MUTATIONS_FILE_VERSION = 1;
+export function mutationsFile(root) {
+    return join(root, '.mutations.json');
+}
+export function contentHash(content) {
+    // Content identity, not byte identity: Windows reads a file back with CRLF while the caller
+    // staged the in-memory LF, so hashing raw bytes reports `drift` for an unchanged skill.
+    return createHash('sha256').update(content.replaceAll('\r\n', '\n')).digest('hex');
+}
+/**
+ * Parse a raw mutations sidecar; malformed content reads as empty (auditing is
+ * best-effort). Versioned shape ({ version, records }) with legacy
+ * plain-array compat, plus a field-level guard for records without the
+ * required identity/timestamp fields (rc.42 audit P2-3).
+ */
+function parseMutationRecords(raw) {
+    if (raw === null)
+        return [];
+    try {
+        return recordsFromParsed(JSON.parse(raw));
+    }
+    catch {
+        return [];
+    }
+}
+/** Field-level shape guard shared by the parse and the recordMutation write
+ * path (P3/v15: the guard's JSON.parse and this parse used to run twice over
+ * the same bytes inside one transact). */
+function recordsFromParsed(parsed) {
+    const records = Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === 'object' && parsed !== null && Array.isArray(parsed.records)
+            ? parsed.records
+            : [];
+    return records.filter((entry) => typeof entry === 'object' && entry !== null && typeof entry.skillName === 'string'
+        && typeof entry.action === 'string'
+        && typeof entry.at === 'string');
+}
+export async function loadMutations(root, io = nodeEvolutionIo()) {
+    return parseMutationRecords(await io.readText(mutationsFile(root)));
+}
+/** Append one record, trim to `cap`, and write atomically (versioned shape). */
+export async function recordMutation(root, io, record, cap = DEFAULT_MUTATION_CAP) {
+    // The read-append-write runs as one atomic transact (rc.50 P2-2): a second
+    // process sharing DSH_HOME can no longer interleave its append between our
+    // read and write and lose an audit record.
+    await transactIo(io, mutationsFile(root), (current) => {
+        // P3 (v3 audit): never overwrite a malformed audit file with a re-serialized empty.
+        // P3 (v15): parse exactly ONCE — the malformed guard and the record
+        // extraction used to JSON.parse the same bytes twice inside one transact
+        // (the guard distinguishes malformed-JSON-preserve from
+        // valid-but-shapeless-migrate, which is why the two checks are separate
+        // even though the parse is shared).
+        let parsed = [];
+        if (current !== null) {
+            try {
+                parsed = JSON.parse(current);
+            }
+            catch {
+                // C-08: the drop is not silent — every append against the malformed
+                // file warns (the wording used to claim "warn once"; the guard has no
+                // once-guard and each dropped append is independently worth seeing).
+                // Still best-effort — no retry, and the mutation itself never fails
+                // on auditing.
+                console.warn(`mutation audit record dropped: ${mutationsFile(root)} is malformed and was not overwritten`);
+                return current;
+            }
+        }
+        // A2-11 (v18): a newer on-disk version is never downgraded by this writer.
+        if (isRecord(parsed)) {
+            const version = parsed.version;
+            if (typeof version === 'number' && version > MUTATIONS_FILE_VERSION) {
+                console.warn(`mutation audit record dropped: ${mutationsFile(root)} declares version ${version} (newer than ${MUTATIONS_FILE_VERSION}); not overwritten`);
+                return current;
+            }
+        }
+        const existing = recordsFromParsed(parsed);
+        existing.push(record);
+        const trimmed = existing.length > cap ? existing.slice(existing.length - cap) : existing;
+        return JSON.stringify({ version: MUTATIONS_FILE_VERSION, records: trimmed }, null, 2);
+    });
+}
+//# sourceMappingURL=mutations.js.map

package/lib/types/namespace-migration.js

@@ -0,0 +1,156 @@
+/**
+ * G3: the one-time move of the family's LEGACY settings sections into the row ids the
+ * platform keys settings by now.
+ *
+ * On 0.1.x each plugin registered a free-form namespace (`evolution-memory`, …) through the
+ * family's own seam. The platform derives a settings namespace from the Loader entry id
+ * today, so those old strings address nothing: the platform's own legacy import finds no
+ * such entry, warns, and leaves the values in the renamed document. This module reads that
+ * document, maps each legacy section (and each deprecated key spelling) onto its row, and
+ * merges the values into that row's user layer.
+ *
+ * Two halves, both testable without a host: {@link planNamespaceMigration} is pure (text in,
+ * plan out) and {@link applyNamespaceMigration} takes the few things it needs as
+ * dependencies, so the side-effecting half runs against a fake settings seat.
+ * @module @lmzhen/dsh-evolution-core
+ */
+import { parse as parseYaml } from 'yaml';
+import { isRecord as isSection } from "./guards.js";
+import { NAMESPACE_MIGRATIONS, PARAM_ALIASES, PARAM_EXPOSURE, resolveParamId } from "./params.js";
+/**
+ * The key names one row may be written with: its own E3 rows, plus the deprecated
+ * spellings that still resolve to them. An unknown key is refused instead of written —
+ * the platform validates a write against the row's schema, so writing it would fail the
+ * whole row's migration.
+ * @param rowId - the row's entry id.
+ * @returns every key name a legacy section may carry for that row.
+ */
+function writableKeys(rowId) {
+    const keys = new Set();
+    for (const entry of PARAM_EXPOSURE) {
+        if (entry.owner === rowId && entry.tier === 'E3')
+            keys.add(entry.id);
+    }
+    for (const [alias, canonical] of Object.entries(PARAM_ALIASES)) {
+        if (keys.has(canonical))
+            keys.add(alias);
+    }
+    return keys;
+}
+/**
+ * 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 function planNamespaceMigration(documentText) {
+    const parsed = parseYaml(documentText);
+    if (parsed === undefined || parsed === null)
+        return { entries: [], empty: [], foreign: [], skipped: [] };
+    if (!isSection(parsed))
+        throw new Error('the settings document is not a mapping; refusing to migrate it');
+    const legacy = new Map(NAMESPACE_MIGRATIONS.map(entry => [entry.namespace, entry.rowId]));
+    const entries = [];
+    const empty = [];
+    const skipped = [];
+    for (const [namespace, section] of Object.entries(parsed)) {
+        const rowId = legacy.get(namespace);
+        if (rowId === undefined)
+            continue;
+        if (!isSection(section))
+            throw new Error('settings section `' + namespace + '` is not a mapping; refusing to migrate it');
+        const allowed = writableKeys(rowId);
+        const values = [];
+        for (const [key, value] of Object.entries(section)) {
+            const canonical = resolveParamId(key);
+            if (!allowed.has(canonical)) {
+                skipped.push({ namespace, key, reason: 'row `' + rowId + '` 没有这个参数' });
+                continue;
+            }
+            values.push({ source: key, key: canonical, value });
+        }
+        if (values.length === 0)
+            empty.push(namespace);
+        else
+            entries.push({ namespace, rowId, values });
+    }
+    const foreign = Object.keys(parsed).filter(name => !legacy.has(name)).sort();
+    return { entries, empty, foreign, skipped };
+}
+/**
+ * Whether two JSON-shaped config values are the same value.
+ * @param left - one value.
+ * @param right - the other.
+ * @returns true when both serialize identically.
+ */
+function sameValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+ * 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 function classifyNamespaceMigration(plan, read) {
+    const write = [];
+    const conflicts = [];
+    const unchanged = [];
+    const skipped = [...plan.skipped];
+    for (const entry of plan.entries) {
+        // A row this composition does not serve (the `variant` install form keeps the model rows
+        // in an agent preset, so they are mounted per session, not here) has no section to write:
+        // reporting it keeps ONE unmounted row from aborting the rows that ARE mounted.
+        const view = read(entry.rowId);
+        if (view === undefined) {
+            for (const value of entry.values) {
+                skipped.push({ namespace: entry.namespace, key: value.source, reason: 'row `' + entry.rowId + '` 在本组合中不提供服务' });
+            }
+            continue;
+        }
+        const user = view.user ?? {};
+        const patch = {};
+        for (const value of entry.values) {
+            if (!Object.hasOwn(user, value.key)) {
+                patch[value.key] = value.value;
+                continue;
+            }
+            if (sameValue(user[value.key], value.value)) {
+                unchanged.push({ rowId: entry.rowId, key: value.key });
+                continue;
+            }
+            conflicts.push({ rowId: entry.rowId, key: value.key, current: user[value.key], legacy: value.value });
+        }
+        if (Object.keys(patch).length > 0)
+            write.push({ rowId: entry.rowId, patch });
+    }
+    return { write, conflicts, unchanged, skipped };
+}
+/**
+ * Report one kept value: the stored value is the newer decision, so it wins and the legacy
+ * one is named rather than dropped.
+ * @param conflict - the conflict the classification found.
+ * @returns the warning text.
+ */
+function conflictWarning(conflict) {
+    return 'evolution-migration: row `' + conflict.rowId + '` already sets `' + conflict.key +
+        '`; the stored value was kept and the legacy ' + JSON.stringify(conflict.legacy) + ' was not applied';
+}
+export async function applyNamespaceMigration(plan, deps) {
+    // An arrow keeps the dependency's own receiver contract intact (the platform's read binds a seat).
+    const decided = classifyNamespaceMigration(plan, rowId => deps.read(rowId));
+    for (const conflict of decided.conflicts)
+        deps.warn(conflictWarning(conflict));
+    const written = [];
+    for (const row of decided.write) {
+        await deps.update(row.rowId, row.patch);
+        written.push({ rowId: row.rowId, keys: Object.keys(row.patch) });
+    }
+    return { written, conflicts: decided.conflicts, unchanged: decided.unchanged, skipped: decided.skipped };
+}
+//# sourceMappingURL=namespace-migration.js.map

package/lib/types/numeric.js

@@ -0,0 +1,47 @@
+/**
+ * Numeric config clamping for the dsh-evolution plugin family.
+ *
+ * G3.1 (0.3.23): numeric configuration values are normalised through a single
+ * helper so 0 / negative / NaN / ±Infinity / out-of-range all fall back to the
+ * package default instead of silently becoming a "disabled" special value or
+ * folding as NaN into a computation. A non-finite value (NaN, ±Infinity) is
+ * never a legitimate config, so it always falls back. The schema layer (a
+ * `.min(1)` clamp on the number schema) is a first-line guard where it can
+ * reject invalid values; this helper is the mandatory assembly-time clamp that
+ * also catches what schemastery lets through (NaN and +Infinity both pass a
+ * bare number schema).
+ *
+ * The scope here is pure numeric conversion only (no schemastery import), so
+ * evolution-core stays free of a schemastery dependency. Per-package Config
+ * schemas keep their own `.min()`/`.default()` call sites.
+ * @module @lmzhen/dsh-evolution-core
+ */
+/**
+ * Clamp a numeric config to the `[min, max]` range.
+ *
+ * A non-finite value (NaN, ±Infinity), a non-number, or a value outside the
+ * inclusive range falls back to `fallback`. When `opts.min >= 1`, 0 and
+ * negative values also fall back to `fallback` — a 0 is never treated as a
+ * special "disabled" meaning (G3.1 decision). Callers that legitimately allow
+ * 0 (e.g. a threshold or a zero-cost weight) pass `{ min: 0 }` or omit the
+ * range.
+ *
+ * @param value - the raw numeric config, possibly `undefined` (absent).
+ * @param fallback - the default value to return when the value is invalid.
+ * @param opts - optional inclusive lower/upper bound.
+ * @returns `value` when it is a finite number within range, else `fallback`.
+ */
+export function clampedNumber(value, fallback, opts) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const { min, max } = opts ?? {};
+    if (min !== undefined && value < min)
+        return fallback;
+    if (max !== undefined && value > max)
+        return fallback;
+    return value;
+}
+// The clamp-AND-WARN helper (`clampOnce`) and the live/plain unwrap now live in
+// `live.ts` — one reader for all config shapes, still exported from the package barrel,
+// so importers keep working unchanged. This module owns the pure numeric conversion only.
+//# sourceMappingURL=numeric.js.map

package/lib/types/opt-in.js

@@ -0,0 +1,101 @@
+import { scopeOf } from '@deepseek-ai/dsh-scope';
+/**
+ * Tool names only a session that mounted the family's MODEL rows can see.
+ *
+ * Both are family packages (`tool-skill-manage`, `tool-memory`), so a session
+ * that merely carries the platform's own session-query tool is not mistaken for
+ * a family session. Two names, not one: a deployment may disable either row.
+ */
+export const FAMILY_SESSION_TOOL_NAMES = ['skill_manage', 'memory'];
+/**
+ * S0-4 (v43 J-1 / G-1): the process-wide witness behind the deployment
+ * diagnostic. A scoped false is the CORRECT answer for a session that did not
+ * opt in, so the miss alone proves nothing — "no session in this process ever
+ * matched" is the shape both real faults share, and only a witness that outlives
+ * one session can tell it from a healthy per-session skip.
+ *
+ * Module scope on purpose: the claim spans every session and every row of this
+ * process, so no single row's fiber owns it. Monotone scalars with no per-key
+ * lifecycle — the N12 registry covers module-scope Set/Map/WeakMap stores, which
+ * carry entries that do need one.
+ */
+let scopedProbeHits = 0;
+let scopedProbeMisses = 0;
+let scopedProbeWarned = false;
+/**
+ * Read the witness for a diagnostic surface (`/evolution doctor`). Read-only: it
+ * neither evaluates the probe nor consumes the one-time warn, so a report run
+ * cannot change what the next miss would have logged.
+ * @returns the verdict with both counts, zeroed in a process where the gate has
+ * not run.
+ */
+export function scopedProbeReport() {
+    const verdict = scopedProbeHits > 0 ? 'hit' : scopedProbeMisses > 0 ? 'never-hit' : 'idle';
+    return { verdict, hits: scopedProbeHits, misses: scopedProbeMisses };
+}
+/**
+ * Does this session's scope see the family's model tools?
+ *
+ * The scope is the live agent's — the platform's own addressing for "what does
+ * this session see" (`tools.get(name, scope)`, packages/core/tools/src/index.ts:1194).
+ * A session with no live agent (a finished or cold session) has no scope to ask
+ * in, so it resolves to false; the consumers this gate serves only run for live
+ * agents.
+ * @param ctx - a context of the runtime (any plane; the services are read from the global store).
+ * @param sessionId - the session to ask about.
+ * @returns true when at least one family model tool is visible to that session.
+ */
+export function sessionSeesFamilyTools(ctx, sessionId) {
+    const probe = ctx;
+    const tools = probe.get('tools');
+    if (tools === undefined)
+        return false;
+    const agent = probe.get('agents')?.get(sessionId);
+    const scope = agent?.ctx === undefined ? undefined : scopeOf(agent.ctx);
+    return FAMILY_SESSION_TOOL_NAMES.some(name => tools.get(name, scope) !== undefined);
+}
+/**
+ * S0-4 (v43 J-1 / G-1): record a scoped rejection and leave the one-time
+ * deployment diagnostic.
+ *
+ * Fires at most once per process, on the first miss, and only while nothing has
+ * ever matched. The message names the check rather than guessing the deployment
+ * form: a host-only install and a disabled model row are the two shapes that can
+ * never match, while the layered variant form legitimately waits for a session
+ * that selected the Evolution preset.
+ * @param ctx - the asking row's context; the warn rides that row's own logger.
+ */
+function noteScopedProbeMiss(ctx) {
+    scopedProbeMisses += 1;
+    if (scopedProbeHits > 0 || scopedProbeWarned)
+        return;
+    scopedProbeWarned = true;
+    ctx.logger.warn('dsh-evolution: sessionScoped is on but the family-tool probe has never matched a session in this process'
+        + ' — review injection and skill-usage telemetry are inert for every session seen so far.'
+        + ' Check whether the family\'s model rows are mounted at all: tool-memory / tool-skill-manage are devDependencies of'
+        + ' @lmzhen/dsh-evolution-host, so a HOST-ONLY install can never match, and a profile overlay that disables either row'
+        + ' has the same effect. Under the layered VARIANT form only a session on the Evolution preset matches, so a miss there'
+        + ' just means none has run yet. Next: /evolution doctor reports the scoped rows and this verdict (see INSTALL.md).');
+}
+/**
+ * The one decision every cross-session consumer calls before it acts.
+ * @param ctx - a context of the runtime.
+ * @param sessionId - the session the event belongs to.
+ * @param sessionScoped - the row's `sessionScoped` config.
+ * @returns true when the consumer may act on this session. A deployment that did
+ * not declare session scoping always answers true (the historical behavior);
+ * a scoped one answers true only for a session that carries the family's model
+ * tools. Each scoped answer updates the process witness, and the first miss with
+ * no match ever leaves one warn (see {@link noteScopedProbeMiss}).
+ */
+export function sessionAudited(ctx, sessionId, sessionScoped) {
+    if (sessionScoped !== true)
+        return true;
+    if (sessionSeesFamilyTools(ctx, sessionId)) {
+        scopedProbeHits += 1;
+        return true;
+    }
+    noteScopedProbeMiss(ctx);
+    return false;
+}
+//# sourceMappingURL=opt-in.js.map

package/lib/types/package-identity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The scope segment of the nearest `package.json` at or above `from`.
+ * @param from - the calling module URL (its own manifest is the answer).
+ * @returns the scope, e.g. `@deepseek-ai` or `@lmzhen`; an unscoped manifest yields an empty string.
+ */
+export declare function scopeOfNearestManifest(from: string | URL): string;
+/**
+ * One family/platform package name under the RUNNING scope.
+ * @param bareName - the name without any scope, e.g. `dsh-agent-preset`.
+ * @param from - the calling module URL.
+ * @returns `scope/bareName`, or `bareName` when the manifest carries no scope.
+ */
+export declare function scopedPackageName(bareName: string, from: string | URL): string;
+//# sourceMappingURL=package-identity.d.ts.map

package/lib/types/package-identity.js

@@ -0,0 +1,47 @@
+/**
+ * G1/1.8 (G-04): the SCOPE this build was published under, DERIVED from a manifest instead of written as a
+ * literal in running code.
+ *
+ * The family used to hard-code `@deepseek-ai/dsh-...` names and let `prepare-release.mjs --scope @lmzhen`
+ * patch the text afterwards. A published install therefore depended on a release-time string rewrite
+ * reaching every copy, and the copies had already drifted (doctor.ts, index.ts, preset-composition.ts and
+ * its .mjs mirror each spelled the identity). The scope is knowable at runtime: it is the scope segment of
+ * the nearest `package.json` above the calling module. Nothing to rewrite, one owner of the answer.
+ *
+ * @module @lmzhen/dsh-evolution-core/package-identity
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The scope segment of the nearest `package.json` at or above `from`.
+ * @param from - the calling module URL (its own manifest is the answer).
+ * @returns the scope, e.g. `@deepseek-ai` or `@lmzhen`; an unscoped manifest yields an empty string.
+ */
+export function scopeOfNearestManifest(from) {
+    let dir = dirname(from instanceof URL ? fileURLToPath(from) : fileURLToPath(new URL(from)));
+    for (let hops = 0; hops < 32; hops += 1) {
+        const manifest = join(dir, 'package.json');
+        if (existsSync(manifest)) {
+            const parsed = JSON.parse(readFileSync(manifest, 'utf8'));
+            const name = typeof parsed.name === 'string' ? parsed.name : '';
+            return name.startsWith('@') ? (name.split('/')[0] ?? '') : '';
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return '';
+}
+/**
+ * One family/platform package name under the RUNNING scope.
+ * @param bareName - the name without any scope, e.g. `dsh-agent-preset`.
+ * @param from - the calling module URL.
+ * @returns `scope/bareName`, or `bareName` when the manifest carries no scope.
+ */
+export function scopedPackageName(bareName, from) {
+    const scope = scopeOfNearestManifest(from);
+    return scope === '' ? bareName : scope + '/' + bareName;
+}
+//# sourceMappingURL=package-identity.js.map