@lmzhen/dsh-evolution-core 0.26.26 → 0.27.1

package/lib/types/run-registry.js

@@ -0,0 +1,345 @@
+/**
+ * 0.19.0 (S2) / 0.19.3 (restructure): the family's run-lifecycle owner.
+ *
+ * A "run" is work that can outlive one interaction — today the maintenance scan.
+ * Before this module the only record of such work was the requesting invocation:
+ * `lastMaintainAt` / `lastMaintainRunId` / `maintainInFlightSince` were
+ * module-scope globals in evolution-commands, and the plan text existed ONLY in
+ * the command's return string. An interaction that ended (measured: the desktop
+ * shell hangs up at ~305 s) therefore erased every trace of a still-running scan.
+ *
+ * This registry is the single owner of (a) what is in flight, (b) how a run
+ * ended, and (c) WHERE its result lives (`resultRef` is a path, never the result
+ * itself — the report file is the one result home).
+ *
+ * Three disciplines are structural, not stylistic:
+ *
+ *   - **One writer per row** (0.19.3). A run's row is authoritative in the memory of
+ *     the process that STARTED it (`owned`) and in the shared index for everyone else
+ *     (`foreign`, rebuilt from the file on every `load()`). The only write a non-owner
+ *     may make is the orphan verdict for a row whose owner is gone, judged inside the
+ *     very transaction that read the row. The two cross-plane bugs this family shipped
+ *     were projections of that one missing rule: 0.19.0 froze a foreign run as
+ *     `running` forever (a "known id" was never re-read), and 0.19.1 wrote a settled
+ *     foreign row back as `running` (memory overwrote every row it knew).
+ *   - **No timer.** A run whose process died is converged at READ time: the live rows
+ *     are in memory, so a `running` row in the file whose owner is not alive is an
+ *     orphan — the same "converge when read" posture the approval window uses.
+ *   - **One terminal state, and it is monotone.** `settle()` refuses to overwrite a row
+ *     that is already terminal (so a cancel that raced a failure cannot flip the answer
+ *     the operator already read), and a row that reached a terminal state never reads as
+ *     `running` again: only the owner that started it could make it running and
+ *     `settle()` is terminal-once, so a `running` claim for a settled row can only be a
+ *     stale writer's — refused on read, repaired on the next write.
+ *
+ * The store is PER INSTANCE (a factory, not module scope): one registry per
+ * mounted row, disposed with its fiber. There is no module-scope mutable state
+ * here to register under N12.
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { clampedNumber } from "./numeric.js";
+import { isProcessAlive, transactIo } from "./io.js";
+/** Current index schema. Bump only for a structural change. */
+export const RUNS_SCHEMA_VERSION = 1;
+/** Retained run records, newest first. */
+export const DEFAULT_RUN_RECORDS = 50;
+/** Index path for a home. */
+export function runsFile(home) {
+    return join(home, 'runs.json');
+}
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
+/**
+ * Parse an index body into records.
+ *
+ * `ok: false` means the body could not be read as an index at all — the caller
+ * decides what to say (`load()` reports it; `persist()` merges with what it can).
+ * @param raw - the file's text, or null when it does not exist.
+ * @returns the parsed records and whether the body was an index.
+ */
+function parseIndex(raw) {
+    if (raw === null)
+        return { ok: true, records: [], foreign: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, records: [], foreign: [] };
+    }
+    const rows = parsed.runs;
+    if (!Array.isArray(rows))
+        return { ok: false, records: [], foreign: [] };
+    const notes = [];
+    const version = parsed.schemaVersion;
+    if (typeof version === 'number' && version !== RUNS_SCHEMA_VERSION) {
+        notes.push(`the index declares schemaVersion ${version} while this build writes ${RUNS_SCHEMA_VERSION}`);
+    }
+    const records = [];
+    const foreign = [];
+    for (const row of rows) {
+        const record = row;
+        if (typeof record.id !== 'string' || typeof record.startedAt !== 'number') {
+            foreign.push(row);
+            continue;
+        }
+        if (typeof record.kind !== 'string' || typeof record.state !== 'string') {
+            foreign.push(row);
+            continue;
+        }
+        if (record.state !== 'running' && !TERMINAL.has(record.state)) {
+            // A state this build does not know (a newer writer, or a hand-edited file):
+            // it is KEPT as it is — dropping it would silently erase another writer's record.
+            foreign.push(row);
+            continue;
+        }
+        records.push({
+            id: record.id,
+            kind: record.kind,
+            state: record.state,
+            startedAt: record.startedAt,
+            ...(typeof record.pid === 'number' ? { pid: record.pid } : {}),
+            ...(typeof record.endedAt === 'number' ? { endedAt: record.endedAt } : {}),
+            ...(typeof record.resultRef === 'string' ? { resultRef: record.resultRef } : {}),
+            ...(typeof record.failure === 'string' ? { failure: record.failure } : {}),
+        });
+    }
+    return { ok: true, records, foreign, ...(notes.length > 0 ? { note: notes.join('; ') } : {}) };
+}
+/**
+ * Create the run registry for one mounted row.
+ * @param options - io seam, evolution home, warn channel, clock and record cap.
+ * @returns the registry; call {@link RunRegistry.load} once before answering reads.
+ */
+export function newRunRegistry(options) {
+    const now = options.now ?? (() => Date.now());
+    const maxRecords = clampedNumber(options.maxRecords ?? DEFAULT_RUN_RECORDS, DEFAULT_RUN_RECORDS, { min: 1 });
+    const warn = options.warn ?? (() => { });
+    const path = runsFile(options.home);
+    /** Rows THIS process started: its memory is the only truth for them. */
+    const owned = new Map();
+    /** Rows read from the shared index: the file is the only truth for them. */
+    const foreign = new Map();
+    /** Cancellation handles — "can this still be stopped", NOT ownership (`settle` drops one). */
+    const controllers = new Map();
+    /** The ONE wording of the orphan verdict. */
+    const ORPHAN_FAILURE = 'no live owner process — the run was interrupted before it settled (orphan)';
+    /** A row whose owner cannot be reached: `pid` absent (an older build) or not alive. */
+    const ownerIsGone = (row) => row.pid === undefined || !isProcessAlive(row.pid);
+    /** The verdict is materialized ONCE, so its `endedAt` (and the duration a reader sees) is stable. */
+    const orphanOf = (row) => ({ ...row, state: 'failed', endedAt: now(), failure: ORPHAN_FAILURE });
+    /** Every row this process knows, newest first. ALL reads go through here. */
+    const view = () => [...owned.values(), ...foreign.values()].sort((a, b) => b.startedAt - a.startedAt);
+    /** Retained history: every running row plus the newest terminal ones (one cap, both planes). */
+    const capped = (rows) => {
+        const live = rows.filter(row => row.state === 'running');
+        const done = rows
+            .filter(row => TERMINAL.has(row.state))
+            .sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt))
+            .slice(0, maxRecords);
+        return [...live, ...done].sort((a, b) => b.startedAt - a.startedAt);
+    };
+    /**
+     * Update a surviving foreign row in place (identity stable), or add it.
+     *
+     * Monotone states (0.19.3): a row already known TERMINAL is never shown as `running`
+     * again. Only the owner that started a run could make it running, and `settle()` is
+     * terminal-once — so a `running` claim for a settled row can only come from a stale
+     * writer (an older plane holding an outdated view), and adopting it would propagate the
+     * resurrection to every other plane.
+     * @returns true when the row was refused as exactly that regression.
+     */
+    const adopt = (row) => {
+        const existing = foreign.get(row.id);
+        if (existing === undefined) {
+            foreign.set(row.id, row);
+            return false;
+        }
+        if (TERMINAL.has(existing.state) && !TERMINAL.has(row.state))
+            return true;
+        // Clear what the new row dropped, so nothing is inherited from the previous view.
+        delete existing.endedAt;
+        delete existing.resultRef;
+        delete existing.failure;
+        Object.assign(existing, row);
+        return false;
+    };
+    const persist = async () => {
+        try {
+            // Read-modify-write under the io backend's cross-process lock. The file is the
+            // BASE and only THIS process's rows are laid over it ("one writer per row"); the
+            // single write a non-owner may make is the orphan verdict for a row whose owner is
+            // gone. The row read inside this transaction IS the compare-and-swap: if its owner
+            // settled it in between, it no longer reads as `running` and is left alone.
+            await transactIo(options.io, path, (current) => {
+                const onDisk = parseIndex(current);
+                const merged = new Map();
+                for (const row of onDisk.records)
+                    merged.set(row.id, row);
+                for (const [id, row] of owned)
+                    merged.set(id, row);
+                // Repair a stale writer's regression: this process READ the owner's terminal
+                // verdict, so re-asserting it is not authoring state — it refuses to propagate a
+                // stale overwrite. Without this, a fresh plane would see the resurrected `running`
+                // row and hold its in-flight guard (the 0.19.0 symptom, one plane later).
+                for (const [id, row] of foreign) {
+                    const onDiskRow = merged.get(id);
+                    if (TERMINAL.has(row.state) && onDiskRow !== undefined && !TERMINAL.has(onDiskRow.state))
+                        merged.set(id, row);
+                }
+                for (const [id, row] of merged) {
+                    if (row.state === 'running' && !owned.has(id) && ownerIsGone(row))
+                        merged.set(id, orphanOf(row));
+                }
+                const kept = capped([...merged.values()]);
+                const live = kept.filter(row => row.state === 'running');
+                const done = kept.filter(row => TERMINAL.has(row.state));
+                // Rows this build does not understand ride along untouched (P2-5): it cannot
+                // judge them, and dropping them would erase another writer's record.
+                return JSON.stringify({ schemaVersion: RUNS_SCHEMA_VERSION, runs: [...live, ...done, ...onDisk.foreign] }, null, 2);
+            });
+        }
+        catch (error) {
+            warn(`evolution-core: could not persist the run index (${error instanceof Error ? error.message : String(error)})`);
+        }
+    };
+    return {
+        async load() {
+            let raw;
+            try {
+                raw = await options.io.readText(path);
+            }
+            catch (error) {
+                // A read FAILURE is not "no runs": say so instead of presenting an empty
+                // registry as a clean history (the same three-state rule the probe files use).
+                return { ok: false, note: `run index unreadable: ${error instanceof Error ? error.message : String(error)}` };
+            }
+            const parsed = parseIndex(raw);
+            if (!parsed.ok) {
+                return { ok: false, note: '运行索引读不出来（不是 JSON，或没有 runs 数组）—— 上一次的运行历史未知（报告不受影响）' };
+            }
+            // The foreign view is REBUILT wholesale: a row this process does not own is whatever
+            // the index says it is, every time. (0.19.0 kept "known" ids frozen, which is how a
+            // settled foreign run answered `running` until the observing process restarted.)
+            // Surviving rows are updated in place so a reader that held one across the load
+            // keeps a live view; rows that vanished from the index are dropped.
+            const wasRunning = new Set([...foreign.values()].filter(row => row.state === 'running').map(row => row.id));
+            const seen = new Set();
+            let converged = 0;
+            let liveElsewhere = 0;
+            let followed = 0;
+            let regressed = 0;
+            for (const row of parsed.records) {
+                if (owned.has(row.id))
+                    continue;
+                seen.add(row.id);
+                if (row.state !== 'running') {
+                    if (wasRunning.has(row.id))
+                        followed++;
+                    if (adopt(row))
+                        regressed++;
+                    continue;
+                }
+                // A running row whose OWNER is alive belongs to another process sharing this home:
+                // genuinely in flight, never rewritten here (review P1-1). A row that cannot name
+                // its owner is treated as gone — the conservative side, and what a row written by
+                // an older build looks like.
+                if (ownerIsGone(row)) {
+                    converged++;
+                    adopt(orphanOf(row));
+                    continue;
+                }
+                liveElsewhere++;
+                if (adopt(row))
+                    regressed++;
+            }
+            for (const id of [...foreign.keys()]) {
+                if (!seen.has(id))
+                    foreign.delete(id);
+            }
+            if (converged > 0 || regressed > 0)
+                await persist();
+            const notes = [
+                parsed.note,
+                converged > 0 ? `${converged} run(s) with no live owner were recorded as failed(orphan)` : undefined,
+                liveElsewhere > 0 ? `${liveElsewhere} run(s) are in flight in another process sharing this home` : undefined,
+                followed > 0 ? `${followed} run(s) settled by their owner were re-read from the index` : undefined,
+                regressed > 0 ? `${regressed} settled run(s) stayed settled although the index claimed they were running` : undefined,
+            ].filter((note) => note !== undefined);
+            return { ok: true, ...(notes.length > 0 ? { note: notes.join('; ') } : {}) };
+        },
+        async begin(kind) {
+            const id = randomUUID();
+            const startedAt = now();
+            const controller = new AbortController();
+            controllers.set(id, controller);
+            // The pid is what lets ANOTHER process tell this live run from an orphan.
+            owned.set(id, { id, kind, state: 'running', startedAt, pid: process.pid });
+            // Write-through (0.19.1, review P2): answering "started" promises a run another
+            // plane can read, so the row reaches the index before this resolves. `persist()`
+            // warns instead of throwing, so an unwritable home cannot withhold the handle.
+            await persist();
+            return { id, kind, signal: controller.signal, startedAt };
+        },
+        async settle(id, outcome) {
+            const row = owned.get(id);
+            // Terminal-once: a cancel that raced the run's own failure must not flip the
+            // answer the operator already read.
+            if (row === undefined || TERMINAL.has(row.state))
+                return;
+            row.state = outcome.state;
+            row.endedAt = now();
+            if (outcome.resultRef !== undefined)
+                row.resultRef = outcome.resultRef;
+            if (outcome.failure !== undefined)
+                row.failure = outcome.failure;
+            controllers.delete(id);
+            await persist();
+        },
+        // The registry tracks ONE kind today (`RunKind` = 'maintain'), so these reads take no
+        // kind filter — a comparison the type system already knows is true. Re-add the
+        // parameter (and the filter) together with the second `RunKind` member.
+        inFlight() {
+            return view().find(row => row.state === 'running');
+        },
+        lastSettledAt() {
+            return view().find(row => TERMINAL.has(row.state))?.endedAt;
+        },
+        runs() {
+            return capped(view());
+        },
+        find(id) {
+            return owned.get(id) ?? foreign.get(id);
+        },
+        cancel(id) {
+            // Only work THIS process started can be stopped. A running row loaded from the
+            // index belongs to another process sharing this home (review P1-1), and marking it
+            // cancelled here would fabricate a terminal state for work that is still running
+            // there — so an unowned id is refused, not "cancelled". (`controllers` is the
+            // right test here precisely because it is about stopping, not about authority.)
+            const controller = controllers.get(id);
+            if (controller === undefined)
+                return false;
+            const row = owned.get(id);
+            if (row === undefined || row.state !== 'running')
+                return false;
+            controller.abort();
+            controllers.delete(id);
+            row.state = 'cancelled';
+            row.endedAt = now();
+            row.failure = 'cancelled by operator';
+            void persist();
+            return true;
+        },
+        cancelAll() {
+            let count = 0;
+            for (const id of [...controllers.keys()]) {
+                if (this.cancel(id))
+                    count++;
+            }
+            return count;
+        },
+    };
+}
+//# sourceMappingURL=run-registry.js.map

package/lib/types/scope.js

@@ -0,0 +1,7 @@
+import { scopeOf } from '@deepseek-ai/dsh-scope';
+export function callingScope(ctx, held) {
+    if (held !== undefined)
+        return held;
+    return scopeOf(ctx);
+}
+//# sourceMappingURL=scope.js.map

package/lib/types/serial.js

@@ -0,0 +1,17 @@
+/**
+ * A process-local serial task queue: each task starts only after the previous
+ * one settles (success or failure), so read-modify-write sequences that share
+ * one file never interleave inside this process. The durable cross-process
+ * serialization layer is the IO backend's transact lock; this chain is the
+ * second layer (0.3.17 S2.8, T-1: the shape was duplicated in state-json and
+ * memory-files — one factory now).
+ */
+export function makeSerialQueue() {
+    let chain = Promise.resolve();
+    return (task) => {
+        const run = chain.then(task, task);
+        chain = run.then(() => undefined, () => undefined);
+        return run;
+    };
+}
+//# sourceMappingURL=serial.js.map

package/lib/types/session-fold.d.ts

@@ -0,0 +1,15 @@
+export type SessionEventClass = 'model' | 'plugin-record' | 'unknown';
+/** Frames the model authored/saw (the only frames evidence, reads and usage accounting may consume). */
+import { MODEL_SESSION_EVENT_TYPES } from './tool-dispatch.ts';
+export { MODEL_SESSION_EVENT_TYPES as MODEL_SESSION_EVENTS };
+/** Classify one session event WITHOUT interpreting it (pure). */
+export declare function classifySessionEvent(event: {
+    readonly type?: unknown;
+    readonly ignorable?: unknown;
+}): SessionEventClass;
+/** True when the event must be skipped by evidence/usage readers (tolerant, never fatal). */
+export declare function isIgnorableEvent(event: {
+    readonly type?: unknown;
+    readonly ignorable?: unknown;
+}): boolean;
+//# sourceMappingURL=session-fold.d.ts.map

package/lib/types/session-fold.js

@@ -0,0 +1,28 @@
+// Session-event classification for EVERY family reader (G6-S1; C-03/C-05).
+//
+// Platform contract: native session events are the model-visible content frames; a plugin record is
+// an `ignorable: true` event whose type is `plugin:<name>` (session/src/index.ts pluginRecordOf).
+// Family readers must classify BEFORE they count or index: unknown frames are tolerated (never
+// interpreted, never written), plugin records are tolerated read-only. The family never appends
+// plugin records.
+// The platform rule is `pluginRecordOf(event) = ignorable && type startsWith('plugin:')`
+// (session/src/index.ts). Spelled structurally here: the preflight's machine-state resolution can
+// point at an older session closure than the platform line this build targets, so importing the
+// helper would make the contract depend on the bed rather than on the rule.
+/** Frames the model authored/saw (the only frames evidence, reads and usage accounting may consume). */
+import { MODEL_SESSION_EVENT_TYPES } from "./tool-dispatch.js";
+export { MODEL_SESSION_EVENT_TYPES as MODEL_SESSION_EVENTS };
+const MODEL_EVENT_TYPES = new Set(MODEL_SESSION_EVENT_TYPES);
+/** Classify one session event WITHOUT interpreting it (pure). */
+export function classifySessionEvent(event) {
+    const type = typeof event.type === 'string' ? event.type : '';
+    if (type.startsWith('plugin:')) {
+        return event.ignorable === true ? 'plugin-record' : 'unknown';
+    }
+    return MODEL_EVENT_TYPES.has(type) ? 'model' : 'unknown';
+}
+/** True when the event must be skipped by evidence/usage readers (tolerant, never fatal). */
+export function isIgnorableEvent(event) {
+    return classifySessionEvent(event) !== 'model';
+}
+//# sourceMappingURL=session-fold.js.map