@lmzhen/dsh-memory 0.43.2-rc.1 → 0.45.0

package/lib/types/files/index.js

@@ -0,0 +1,261 @@
+/**
+ * Local layered memory provider for `ctx.memory`.
+ * @module @lmzhen/dsh-memory-files
+ */
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { DEFAULT_CONSOLIDATION_FAILURES, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_USER_CHAR_LIMIT, paramRowId, payloadText, userSetKeys, evolutionIoAdapter, makeSerialQueue, MemoryStore, clampOnce, liveBool, unwrapLive } from '@lmzhen/dsh-evolution-core';
+export const name = 'memory-files';
+export const inject = ['memory', 'evolutionIo'];
+// G1: the four E3 keys of this row carry `.volatile()`, so the platform hands the
+// plugin a stable reference it updates in place and the settings surface can edit
+// them live. The schema keeps NO annotation: a volatile field's output is a
+// reference, which the annotated `z<Config>` reading cannot express (TS2375) — the
+// platform's own volatile rows are unannotated for the same reason.
+export const Config = z.object({
+    providerName: z.string().default('files'),
+    // The canonical registry ids. No .default() on either one: a schema default would
+    // fill the canonical key and make the deprecated alias below unreachable through
+    // the store's alias fallback (DEFAULT_MEMORY_CHAR_LIMIT /
+    // DEFAULT_USER_CHAR_LIMIT are resolved there).
+    memoryChars: z.number().min(1).volatile(),
+    userChars: z.number().min(1).volatile(),
+    memoryCharLimit: z.number().min(1).default(DEFAULT_MEMORY_CHAR_LIMIT),
+    userCharLimit: z.number().min(1).default(DEFAULT_USER_CHAR_LIMIT),
+    addDatePrefix: z.boolean().default(false).volatile(),
+    root: z.string().default(''),
+    maxConsolidationFailures: z.number().min(1).default(DEFAULT_CONSOLIDATION_FAILURES).volatile(),
+    threatExemptLabels: z.array(z.string()).default([]),
+});
+export function apply(ctx, rawConfig = {}) {
+    // G1: suppress the platform's auto-generated settings page for this row (the
+    // family renders its own card from the registry). Probed, not assumed: a host
+    // without the capability still loads.
+    ctx.inject(['settings'], (injected) => {
+        const settings = injected.settings;
+        if (typeof settings?.configure !== 'function')
+            return;
+        // v46 S1.12b (finding 6-1): the owner argument is what the platform looks the presentation up by.
+        // Omitting it registers the suppression on the settings service's own fiber, so a row that
+        // re-mounts keeps a dead key and the auto form can return (platform precedent:
+        // settings.configure({ auto: false }, plugin.fiber) — settings/src/index.ts:266).
+        const disposer = settings.configure({ auto: false }, ctx.fiber);
+        if (typeof disposer === 'function')
+            ctx.effect(() => disposer, 'memory-files: settings presentation');
+    });
+    // G3.1 (0.3.23): clamp the numeric memory limit so a 0/negative/NaN/±Infinity
+    // value falls back to the package default. A 0 limit is never an "unbounded"
+    // meaning (MemoryStore keeps its own internal defense); the schema `.min(1)`
+    // rejects 0/negative at load, this clamp also covers NaN/±Infinity (which
+    // schemastery lets a bare number schema through) and direct construction.
+    // G1 §8.3: every read happens at USE time, so the correction warns once per KEY
+    // per mount instead of once at assembly.
+    const clampedKeys = new Set();
+    /**
+     * Clamp one supplied numeric value, warning once per key.
+     * @param name - the config key, for the warning.
+     * @param value - the value as supplied by the deployment or the user.
+     * @param fallback - the package default a corrected value falls back to.
+     * @returns the value the store may use.
+     */
+    const field = (name, value, fallback) => clampOnce(clampedKeys, (message) => { ctx.logger.warn(message); }, `memory-files: ${name}`, value, fallback, 1);
+    // P2-23 (v37): a fractional char limit reached the store unchanged, and the
+    // tool surface declares `limit` as an integer — every memory call then failed
+    // platform output validation AFTER the write had landed. The char limit is a
+    // counted quantity, so it is floored at the one point where it enters the store
+    // (floor, not round: a limit must never grow past what the operator configured).
+    const floorLimit = (value) => Math.floor(value);
+    // S2-12③ (FLOW5-4): the memory budget has TWO configuration surfaces — this
+    // package's `memoryCharLimit`/`userCharLimit` (what the STORE enforces) and
+    // `evolution-policy`'s `memoryChars`/`userChars` (what the review pipeline
+    // PLANS against). They used to default independently, so moving one left the
+    // other behind: the reviewer planned ops for a budget the store then refused.
+    // Explicit config still wins (the operator said so); an UNSET limit follows the
+    // policy when that service is already mounted, and otherwise keeps the default
+    // (row order is not something this plugin can force — doctor compares the two
+    // surfaces again at run time and flags a disagreement, including the
+    // order-induced one).
+    const policyBudget = () => {
+        const policy = ctx.get('evolutionPolicy');
+        const snapshot = policy?.get?.();
+        return { memory: snapshot?.memoryChars, user: snapshot?.userChars };
+    };
+    // The row fills SCHEMA DEFAULTS into the deprecated alias, so "the operator set
+    // the alias" is read as "differs from that default" — the same test the review
+    // row uses for shadowed fields. A row that pins the alias default is therefore
+    // indistinguishable from one that omits it, and follows the policy like the
+    // latter.
+    const aliasDefaults = Config['~standard'].validate({}).value;
+    const ALIAS_OF = { memoryChars: 'memoryCharLimit', userChars: 'userCharLimit' };
+    const DEFAULTS = { memoryChars: DEFAULT_MEMORY_CHAR_LIMIT, userChars: DEFAULT_USER_CHAR_LIMIT };
+    /**
+     * The live value of one canonical budget key (G1 §8.3).
+     * @param id - the canonical registry id.
+     * @returns the value the platform resolved (user layer included), or undefined.
+     */
+    const canonicalBudget = (id) => unwrapLive(id === 'memoryChars' ? rawConfig.memoryChars : rawConfig.userChars);
+    /**
+     * Whether the OPERATOR set this budget on THIS ROW (G0/S0.4 + G1).
+     *
+     * The canonical key answers through its live reference — a user-layer value
+     * arrives the same way, which is what keeps a user choice ahead of the policy —
+     * and the deprecated alias through the default comparison above. The pair is
+     * documented in the Config JSDoc and reported by /evolution doctor (budgetIssues).
+     * @param id - the canonical registry id.
+     * @returns whether the row or the user supplied a value.
+     */
+    const explicitBudget = (id) => {
+        if (canonicalBudget(id) !== undefined)
+            return true;
+        const alias = rawConfig[ALIAS_OF[id]];
+        return alias !== undefined && alias !== aliasDefaults[ALIAS_OF[id]];
+    };
+    /**
+     * The budget one key resolves to (G1 §8.4-A): the row's own value — canonical or
+     * alias — over the mounted policy, over the package default.
+     * @param id - the canonical registry id.
+     * @returns the resolved, unclamped budget.
+     */
+    const budget = (id) => {
+        const explicit = canonicalBudget(id) ?? (explicitBudget(id) ? rawConfig[ALIAS_OF[id]] : undefined);
+        if (explicit !== undefined)
+            return explicit;
+        const policy = policyBudget();
+        return (id === 'memoryChars' ? policy.memory : policy.user) ?? DEFAULTS[id];
+    };
+    // BOTH spellings carry the RESOLVED value downstream, so the store, the budget
+    // view and the doctor read one number whichever name the deployment wrote.
+    const memoryChars = () => floorLimit(field('memoryCharLimit', budget('memoryChars'), DEFAULT_MEMORY_CHAR_LIMIT));
+    const userChars = () => floorLimit(field('userCharLimit', budget('userChars'), DEFAULT_USER_CHAR_LIMIT));
+    const consolidationFailures = () => field('maxConsolidationFailures', rawConfig.maxConsolidationFailures, DEFAULT_CONSOLIDATION_FAILURES);
+    const addDatePrefix = () => liveBool(rawConfig.addDatePrefix);
+    // The one disagreement this plugin can see at load: an EXPLICIT row value that
+    // contradicts the mounted policy. Doctor re-checks the same pair at run time (it
+    // can see the policy mount that happened after this row).
+    const policyAtMount = policyBudget();
+    if (explicitBudget('memoryChars') && policyAtMount.memory !== undefined && memoryChars() !== policyAtMount.memory) {
+        ctx.logger.warn(`memory-files: the row's memoryChars=${memoryChars()} contradicts evolution-policy memoryChars=${policyAtMount.memory} — the store enforces the row value while the review plans against the policy value; align them or leave the row unset`);
+    }
+    if (explicitBudget('userChars') && policyAtMount.user !== undefined && userChars() !== policyAtMount.user) {
+        ctx.logger.warn(`memory-files: the row's userChars=${userChars()} contradicts evolution-policy userChars=${policyAtMount.user} — same divergence as memoryChars`);
+    }
+    // The IO provider is resolved lazily so `memory-files` does not depend on
+    // row order: the first write happens only after the preset has fully mounted.
+    const io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
+    const authority = ctx.get('evolutionMutationAuthority');
+    // In-process write serialization: applyBatch is read-modify-write, so two
+    // concurrent callers (multi-session host) can otherwise compute on the same
+    // old entries and the last rename wins, silently dropping the other's ops.
+    // 0.3.17 (S2.8, T-1): the queue factory is shared with state-json now.
+    const serializedWrite = makeSerialQueue();
+    // V5-11 (0.3.32): a whitespace-only `root` was truthy and resolved to a
+    // CWD-relative path — trim like resolveSkillsRoot/state-json (V4-09 third
+    // occurrence); empty/whitespace both fall through to the default root.
+    // PLAN S2.2-adjacent P2-31 (2026-09-16): an EXPLICIT non-empty root is now
+    // run through resolve() — the same standard as core's evolutionRoot
+    // (state-store.ts) — so the store root is pinned to an absolute path at
+    // mount instead of staying CWD-relative and letting every io call land
+    // wherever the process CWD points at that moment. Empty/whitespace keeps
+    // the memoryRoot() default unchanged.
+    const trimmedRoot = (rawConfig.root || '').trim();
+    const resolvedRoot = trimmedRoot === '' ? '' : resolve(trimmedRoot);
+    // G3/S3.2 + G1: the user layer and the deployment carriers both land in the four
+    // live values above, so the store is DERIVED from them rather than kept in step
+    // by a settings hook. `MemoryStore` reads its limits in its CONSTRUCTOR, so an
+    // option set that changed since the last operation rebuilds it — registration-
+    // level facts, the one thing the platform's `onChange` hook existed for. A
+    // rebuild resets the store's consolidation-failure counter; the previous hook
+    // rebuilt on ANY committed change, so this fires strictly less often. One
+    // operation takes one store (the read/write pair inside `snapshot` must not
+    // straddle a rebuild), and the write queue lives outside the store either way.
+    let store;
+    let storeKey = '';
+    /**
+     * The store for the configuration as it stands right now.
+     * @returns the current store, rebuilt when a resolved limit changed.
+     */
+    const currentStore = () => {
+        const options = {
+            memoryCharLimit: memoryChars(),
+            userCharLimit: userChars(),
+            addDatePrefix: addDatePrefix(),
+            maxConsolidationFailures: consolidationFailures(),
+        };
+        const key = `${options.memoryCharLimit}|${options.userCharLimit}|${options.addDatePrefix}|${options.maxConsolidationFailures}`;
+        if (store !== undefined && key === storeKey)
+            return store;
+        store = new MemoryStore({
+            ...options,
+            // F-2 (v18): the memory store's own exemption list, now configurable.
+            ...rawConfig.threatExemptLabels !== undefined ? { threatExemptLabels: rawConfig.threatExemptLabels } : {},
+            ...resolvedRoot !== '' ? { root: resolvedRoot } : {},
+            io,
+            ...(authority?.homeFence === undefined ? {} : { fence: authority.homeFence }),
+        });
+        storeKey = key;
+        return store;
+    };
+    const provider = {
+        name: rawConfig.providerName ?? 'files',
+        read: (target) => currentStore().read(target),
+        applyBatch: async (target, operations) => {
+            // T3-06/A34: the payload alias is resolved by core's ONE rule, so this
+            // provider cannot disagree with the validator or the store about a blank
+            // `facts` sitting next to a real `content`.
+            const normalized = operations.map(op => ({ action: op.action, facts: payloadText(op), old_text: op.old_text }));
+            return await serializedWrite(() => currentStore().applyBatch(target, normalized));
+        },
+        snapshot: async () => {
+            // 0.3.17 (E-73): serial reads — a concurrent write between the two
+            // Promise.all reads used to produce a mixed-generation snapshot. V4-12:
+            // reading memory and user as two separate awaited reads still lets a
+            // serializedWrite (an applyBatch) yield BETWEEN them, so the two reads
+            // now run inside one serializedWrite task: no write can interleave, the
+            // snapshot is a single generation, and the sha256 pins a state that truly
+            // existed. (The cross-process window is documented as accepted — the
+            // single-process chain is this family's second layer.)
+            const [memory, user] = await serializedWrite(async () => {
+                const current = currentStore();
+                return [await current.read('memory'), await current.read('user')];
+            });
+            const text = JSON.stringify([memory, user]);
+            return { version: 1, sha256: createHash('sha256').update(text).digest('hex'), memory, user };
+        },
+        // P2-3 (v14): the SAME single-generation rule as `snapshot` — this is the
+        // path the model actually reads (tool-memory injects `renderContext`), and
+        // it read memory and user as two independent awaits, so a concurrent
+        // applyBatch could land between them and produce a mixed-generation
+        // context. Queue both reads as one serialized step.
+        renderContext: () => serializedWrite(() => currentStore().renderContext()),
+    };
+    // S2.9 (T3-10): the settings user-layer KEY read is ONE core function (`userSetKeys`); this row
+    // only names its own namespace. The review, curator and skill rows call the same reader.
+    /**
+     * Which surface supplied one budget.
+     * @param id - the canonical registry id.
+     * @returns 'user', 'config', 'policy' or 'default'.
+     */
+    const limitSource = (id) => {
+        if (userSetKeys(ctx, paramRowId('memory-files')).has(id))
+            return 'user';
+        if (explicitBudget(id))
+            return 'config';
+        return (id === 'memoryChars' ? policyBudget().memory : policyBudget().user) === undefined ? 'default' : 'policy';
+    };
+    // S2-12③: publish the EFFECTIVE budget so doctor can compare the two surfaces
+    // at run time (the same one-writer/one-reader contract as evolutionFeedback /
+    // evolutionReplay). Every member is a LIVE VIEW (G1 §8.3): the user layer can
+    // change at run time, and a policy mounted after this row is visible too.
+    // `source` names the winning surface; 'user' is the highest-priority one.
+    ctx.provide('evolutionMemoryBudget', {
+        get memoryCharLimit() { return memoryChars(); },
+        get userCharLimit() { return userChars(); },
+        get memorySource() { return limitSource('memoryChars'); },
+        get userSource() { return limitSource('userChars'); },
+        get policyMemoryChars() { return policyBudget().memory; },
+        get policyUserChars() { return policyBudget().user; },
+    });
+    ctx.effect(() => ctx.memory.registerProvider(provider), 'memory-files.provider');
+}
+//# sourceMappingURL=index.js.map

package/lib/types/index.js

@@ -0,0 +1,117 @@
+/**
+ * Memory provider registry for the evolution family.
+ * Service Definition role; concrete providers register here.
+ * @module @lmzhen/dsh-memory
+ */
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export class MemoryRegistry extends Service {
+    /**
+     * V27 G6.3: the same provider-pin contract the io/state seams use. Before
+     * this, every delegation called `provider()` with no name, so with two
+     * providers mounted the session-visible store was decided by ROW ORDER while
+     * `memory-files.providerName` renamed a registration nothing selected — a
+     * config no consumer read. Empty keeps the old behavior (first registered).
+     */
+    static Config = z.object({
+        provider: z.string().default(''),
+    });
+    providers = new Map();
+    /** Dispose handles by provider name, so a stale handle cannot remove a newer registration. */
+    disposals = new Map();
+    providerName;
+    pinWarned = false;
+    constructor(ctx, config = {}) {
+        super(ctx, 'memory');
+        this.providerName = config.provider ?? '';
+        // A mount-time check like evolution-state's S-07 is not available here: the
+        // registry and the provider-registration API are the SAME service, so a
+        // provider can only register after this constructor and the registry is
+        // always empty at mount. The pin is therefore verified at the two points
+        // that exist — a warning when a differently-named provider registers (the
+        // earliest visible signal), and the hard `provider(name)` throw on the first
+        // read or write, which names the pin.
+    }
+    registerProvider(provider) {
+        // 1-8/A11: parity with the io and state-storage registries. The three registries serve ONE role
+        // (a provider table on the Service Definition side), and both siblings treat re-registering the
+        // IDENTICAL object as idempotent — they return the original dispose and do not throw, which is
+        // what lets a backend re-apply on HMR (a re-mounted row) without a crash. Memory threw
+        // `already registered` for the same sequence. A DIFFERENT object under a registered name still
+        // throws in all three.
+        const idempotent = this.providers.get(provider.name) === provider;
+        if (!idempotent && this.providers.has(provider.name))
+            throw new Error(`memory provider "${provider.name}" already registered`);
+        if (idempotent) {
+            const existing = this.disposals.get(provider.name);
+            if (existing !== undefined)
+                return existing;
+        }
+        this.providers.set(provider.name, provider);
+        this.ctx.emit('evolution/memory-provider-registered', { name: provider.name });
+        if (this.providerName && provider.name !== this.providerName && !this.providers.has(this.providerName) && !this.pinWarned) {
+            this.pinWarned = true;
+            this.ctx.logger.warn(`memory: config.provider="${this.providerName}" is not registered (mounted: "${provider.name}"); memory reads and writes fail until that provider mounts`);
+        }
+        const dispose = () => {
+            // P3 (v16) parity with the io registry: a handle acts only while it is
+            // still the CURRENT one for this name. An object-identity check cannot
+            // tell generations apart, so after dispose → re-register(same object) a
+            // stale handle used to delete the LIVE registration.
+            if (this.disposals.get(provider.name) !== dispose)
+                return;
+            this.providers.delete(provider.name);
+            this.disposals.delete(provider.name);
+        };
+        this.disposals.set(provider.name, dispose);
+        return dispose;
+    }
+    /** Configured provider: the pinned name, or the first registered one. */
+    selected() {
+        return this.provider(this.providerName || undefined);
+    }
+    /** 0.3.17 (E-73): named lookup like the io/state-storage registries; no
+     * name = first registered (backward compatible). A named miss throws (F-333,
+     * 0.3.23) instead of silently falling back to the first provider, so a wrong
+     * name surfaces rather than writing to the wrong memory store. */
+    provider(name) {
+        if (name) {
+            const byName = this.providers.get(name);
+            if (!byName)
+                throw new Error(`memory provider "${name}" is not registered`);
+            return byName;
+        }
+        const first = this.providers.values().next().value;
+        if (!first)
+            throw new Error('memory: no provider registered');
+        return first;
+    }
+    read(target) {
+        return this.selected().read(target);
+    }
+    async applyBatch(target, operations) {
+        const result = await this.selected().applyBatch(target, operations);
+        // P2 fix: every successful write refreshes whatever listens — the snapshot
+        // subscriber (tool-memory) re-renders the model-visible context. This is
+        // the single write sink, so bypass paths are covered without per-path fixes.
+        if (result.ok)
+            this.ctx.emit('evolution/memory-applied', {
+                target,
+                chars: result.chars,
+                entries: result.entries.length,
+            });
+        return result;
+    }
+    /** V6-44 (0.3.37): test-support API — production consumers read the
+     * model-visible context via `renderContext()`; snapshot() has no production
+     * consumer (tests inspect the raw snapshot, kept by declaration).
+     * @internal Exported for this package's own tests only. */
+    snapshot() {
+        return this.selected().snapshot();
+    }
+    renderContext() {
+        return this.selected().renderContext();
+    }
+}
+export default MemoryRegistry;
+//# sourceMappingURL=index.js.map

package/lib/types/tools/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Model-facing memory tool and runtime-context memory snapshot.
+ * @module @deepseek-ai/dsh-tool-memory
+ */
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-memory";
+export declare const inject: string[];
+/**
+ * System-prompt memory guidance, aligned with Hermes `MEMORY_GUIDANCE`.
+ * Reached by the model every turn, so it is the place to steer behavior: what
+ * to save durably, what not to save, and how to phrase an entry. The tool
+ * schema description (`MEMORY_TOOL_DESCRIPTION`) carries the complementary
+ * operation-level guidance (add/replace/remove, batch, targets, when).
+ */
+export declare const MEMORY_GUIDANCE: string;
+/**
+ * Tool-schema description for `memory`, aligned with Hermes `MEMORY_SCHEMA`.
+ * Carries the operation-level guidance: how to batch, when to save, the
+ * priority order, the target semantics, and what to skip. Reached only when
+ * the model is choosing/using the tool, so it complements the always-on
+ * `MEMORY_GUIDANCE` system prompt.
+ */
+export declare const MEMORY_TOOL_DESCRIPTION: string;
+/** G3/S3.2: `memoryEnabled` stays a deployment switch on purpose — it decides whether the
+ * tool and its prompt section are REGISTERED at all, so making it live would mean dynamic
+ * registration with catalog-visible effects (registry tier E2). The display knob the user
+ * may tune (`entryPreviewChars`) is a volatile row field instead (G1 §8.1). */
+export interface Config {
+    memoryEnabled?: boolean;
+    /** Maximum characters of each memory entry echoed back in tool results (live reference). */
+    entryPreviewChars?: Volatile<number>;
+}
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    memoryEnabled: z<boolean, boolean, "defined">;
+    entryPreviewChars: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    memoryEnabled: z<boolean, boolean, "defined">;
+    entryPreviewChars: z<number, number, "volatile-defined">;
+}>>, "plain">;
+export declare function apply(ctx: Context, rawConfig?: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map