@lmzhen/dsh-evolution-core 0.19.2 → 0.19.3

package/lib/index.js

@@ -5927,7 +5927,7 @@ function sweepReviewChannelSessions(isAlive) {
 //#endregion
 //#region lib/types/run-registry.js
 /**
-* 0.19.0 (S2): the family's run-lifecycle owner.
+* 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:
@@ -5940,16 +5940,25 @@ function sweepReviewChannelSessions(isAlive) {
 * ended, and (c) WHERE its result lives (`resultRef` is a path, never the result
 * itself — the report file is the one result home).
 *
-* Two disciplines are structural, not stylistic:
-*
-*   - **No timer.** A run whose process died is converged at READ time: the index
-*     file can only carry `running` records written by a PREVIOUS process life,
-*     because the live ones are in memory. `load()` therefore rewrites every
-*     `running` record as `failed(orphan)` once — the same "converge when read"
-*     posture the approval window uses for its TTL.
-*   - **One terminal state.** `settle()` refuses to overwrite a record that is
-*     already terminal, so a cancel that raced a failure cannot flip the answer
-*     the operator already read.
+* 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
@@ -6046,43 +6055,69 @@ function newRunRegistry(options) {
 	const maxRecords = clampedNumber(options.maxRecords ?? 50, 50, { min: 1 });
 	const warn = options.warn ?? (() => {});
 	const path = runsFile(options.home);
-	const records = [];
+	/** Rows THIS process started: its memory is the only truth for them. */
+	const owned = /* @__PURE__ */ new Map();
+	/** Rows read from the shared index: the file is the only truth for them. */
+	const foreign = /* @__PURE__ */ new Map();
+	/** Cancellation handles — "can this still be stopped", NOT ownership (`settle` drops one). */
 	const controllers = /* @__PURE__ */ new Map();
-	const ordered = () => [...records].sort((a, b) => b.startedAt - a.startedAt);
-	/** The ONE wording of the orphan verdict — read-time convergence says it in two places. */
+	/** The ONE wording of the orphan verdict. */
 	const ORPHAN_FAILURE = "no live owner process — the run was interrupted before it settled (orphan)";
-	/** A `running` record whose owner is gone, as the index must show it. */
-	const orphanOf = (record) => ({
-		...record,
+	/** A row whose owner cannot be reached: `pid` absent (an older build) or not alive. */
+	const ownerIsGone = (row) => row.pid === void 0 || !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
 	});
-	/** Keep every RUNNING record plus the newest terminal ones: memory and the
-	* index share one cap, so the two can never disagree about the history. */
-	const trim = () => {
-		const terminal = records.filter((record) => TERMINAL.has(record.state)).sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt));
-		for (const stale of terminal.slice(maxRecords)) {
-			const index = records.indexOf(stale);
-			if (index >= 0) records.splice(index, 1);
-		}
+	/** 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 === void 0) {
+			foreign.set(row.id, row);
+			return false;
+		}
+		if (TERMINAL.has(existing.state) && !TERMINAL.has(row.state)) return true;
+		delete existing.endedAt;
+		delete existing.resultRef;
+		delete existing.failure;
+		Object.assign(existing, row);
+		return false;
 	};
 	const persist = async () => {
-		trim();
 		try {
 			await transactIo(options.io, path, (current) => {
 				const onDisk = parseIndex(current);
 				const merged = /* @__PURE__ */ new Map();
-				for (const record of onDisk.records) merged.set(record.id, record);
-				for (const record of records) {
-					const onDiskRow = merged.get(record.id);
-					const settledElsewhere = onDiskRow !== void 0 && TERMINAL.has(onDiskRow.state) && !TERMINAL.has(record.state);
-					if (!controllers.has(record.id) && settledElsewhere) continue;
-					merged.set(record.id, record);
+				for (const row of onDisk.records) merged.set(row.id, row);
+				for (const [id, row] of owned) merged.set(id, row);
+				for (const [id, row] of foreign) {
+					const onDiskRow = merged.get(id);
+					if (TERMINAL.has(row.state) && onDiskRow !== void 0 && !TERMINAL.has(onDiskRow.state)) merged.set(id, row);
 				}
-				const view = [...merged.values()].sort((a, b) => b.startedAt - a.startedAt);
-				const live = view.filter((record) => record.state === "running");
-				const done = view.filter((record) => TERMINAL.has(record.state)).slice(0, maxRecords);
+				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));
 				return JSON.stringify({
 					schemaVersion: 1,
 					runs: [
@@ -6112,45 +6147,36 @@ function newRunRegistry(options) {
 				ok: false,
 				note: "run index could not be read as an index (not JSON, or no runs array) — the previous run history is unknown (the reports are unaffected)"
 			};
+			const wasRunning = new Set([...foreign.values()].filter((row) => row.state === "running").map((row) => row.id));
+			const seen = /* @__PURE__ */ new Set();
 			let converged = 0;
 			let liveElsewhere = 0;
-			let healed = 0;
-			for (const record of parsed.records) {
-				const knownIndex = records.findIndex((item) => item.id === record.id);
-				if (knownIndex >= 0) {
-					const known = records[knownIndex];
-					if (!controllers.has(record.id) && !TERMINAL.has(known.state)) {
-						if (TERMINAL.has(record.state)) {
-							delete known.endedAt;
-							delete known.resultRef;
-							delete known.failure;
-							Object.assign(known, record);
-							healed++;
-						} else if (record.pid === void 0 || !isProcessAlive(record.pid)) {
-							records[knownIndex] = orphanOf(record);
-							converged++;
-						}
-					}
-					continue;
-				}
-				if (record.state !== "running") {
-					records.push(record);
+			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;
 				}
-				if (record.pid !== void 0 && isProcessAlive(record.pid)) {
-					liveElsewhere++;
-					records.push(record);
+				if (ownerIsGone(row)) {
+					converged++;
+					adopt(orphanOf(row));
 					continue;
 				}
-				converged++;
-				records.push(orphanOf(record));
+				liveElsewhere++;
+				if (adopt(row)) regressed++;
 			}
-			if (converged > 0 || healed > 0) await persist();
+			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)` : void 0,
 				liveElsewhere > 0 ? `${liveElsewhere} run(s) are in flight in another process sharing this home` : void 0,
-				healed > 0 ? `${healed} run(s) settled by their owner were re-read from the index` : void 0
+				followed > 0 ? `${followed} run(s) settled by their owner were re-read from the index` : void 0,
+				regressed > 0 ? `${regressed} settled run(s) stayed settled although the index claimed they were running` : void 0
 			].filter((note) => note !== void 0);
 			return {
 				ok: true,
@@ -6162,7 +6188,7 @@ function newRunRegistry(options) {
 			const startedAt = now();
 			const controller = new AbortController();
 			controllers.set(id, controller);
-			records.push({
+			owned.set(id, {
 				id,
 				kind,
 				state: "running",
@@ -6178,37 +6204,37 @@ function newRunRegistry(options) {
 			};
 		},
 		async settle(id, outcome) {
-			const record = records.find((item) => item.id === id);
-			if (!record || TERMINAL.has(record.state)) return;
-			record.state = outcome.state;
-			record.endedAt = now();
-			if (outcome.resultRef !== void 0) record.resultRef = outcome.resultRef;
-			if (outcome.failure !== void 0) record.failure = outcome.failure;
+			const row = owned.get(id);
+			if (row === void 0 || TERMINAL.has(row.state)) return;
+			row.state = outcome.state;
+			row.endedAt = now();
+			if (outcome.resultRef !== void 0) row.resultRef = outcome.resultRef;
+			if (outcome.failure !== void 0) row.failure = outcome.failure;
 			controllers.delete(id);
 			await persist();
 		},
 		inFlight() {
-			return ordered().find((record) => record.state === "running");
+			return view().find((row) => row.state === "running");
 		},
 		lastSettledAt() {
-			return ordered().find((record) => TERMINAL.has(record.state))?.endedAt;
+			return view().find((row) => TERMINAL.has(row.state))?.endedAt;
 		},
 		runs() {
-			return ordered();
+			return capped(view());
 		},
 		find(id) {
-			return records.find((record) => record.id === id);
+			return owned.get(id) ?? foreign.get(id);
 		},
 		cancel(id) {
 			const controller = controllers.get(id);
 			if (controller === void 0) return false;
-			const record = records.find((item) => item.id === id);
-			if (!record || record.state !== "running") return false;
+			const row = owned.get(id);
+			if (row === void 0 || row.state !== "running") return false;
 			controller.abort();
 			controllers.delete(id);
-			record.state = "cancelled";
-			record.endedAt = now();
-			record.failure = "cancelled by operator";
+			row.state = "cancelled";
+			row.endedAt = now();
+			row.failure = "cancelled by operator";
 			persist();
 			return true;
 		},

package/lib/types/run-registry.d.ts

@@ -1,5 +1,5 @@
 /**
- * 0.19.0 (S2): the family's run-lifecycle owner.
+ * 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:
@@ -12,16 +12,25 @@
  * ended, and (c) WHERE its result lives (`resultRef` is a path, never the result
  * itself — the report file is the one result home).
  *
- * Two disciplines are structural, not stylistic:
+ * Three disciplines are structural, not stylistic:
  *
- *   - **No timer.** A run whose process died is converged at READ time: the index
- *     file can only carry `running` records written by a PREVIOUS process life,
- *     because the live ones are in memory. `load()` therefore rewrites every
- *     `running` record as `failed(orphan)` once — the same "converge when read"
- *     posture the approval window uses for its TTL.
- *   - **One terminal state.** `settle()` refuses to overwrite a record that is
- *     already terminal, so a cancel that raced a failure cannot flip the answer
- *     the operator already read.
+ *   - **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
@@ -66,9 +75,9 @@ export interface RunOutcome {
 /** The registry surface the commands row drives. */
 export interface RunRegistry {
     /**
-     * Converge the persisted index; the commands row calls it before answering any read
-     * (0.19.1: it also re-reads a terminal state written by the run's OWNER — see the
-     * implementation note below).
+     * Converge the persisted index; the commands row calls it before answering any read.
+     * The foreign view is rebuilt wholesale (0.19.3), so a row another plane settled is
+     * re-read here instead of being frozen at whatever this process first saw.
      */
     load(): Promise<{
         ok: boolean;
@@ -88,7 +97,7 @@ export interface RunRegistry {
     inFlight(): RunRecord | undefined;
     /** When the newest terminal run ended (`undefined` when none). */
     lastSettledAt(): number | undefined;
-    /** Every tracked run, newest first. */
+    /** Every tracked run, newest first (retained history: cap applied). */
     runs(): readonly RunRecord[];
     /** One run by id, converged view included. */
     find(id: string): RunRecord | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-core",
   "description": "Shared stores, prompts, signals and lifecycle logic for the dsh-evolution plugin family (community build)",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "publishConfig": {
     "access": "public"
   },