@lmzhen/dsh-evolution-state-storage 0.3.67 → 0.3.69

package/lib/index.js

@@ -170,10 +170,66 @@ const PENDING_RESOLVED_CAP = 200;
 * interface change, no background sweeper).
 */
 const REVIEW_STATE_SESSION_CAP = 500;
+/**
+* V27 G2.2: WHICH pending records the audit cap evicts, as one pure rule both
+* providers apply (the two implementations had drifted into separate files and
+* only one of them was ever updated by a later fix).
+*
+* Eligible = resolved (`approved`/`rejected`) and NOT a capability approval:
+* v23 (AP-1) exempts those because the Creator-mode contract reads the LIVE
+* approved list and a capability cannot be re-submitted for the same package,
+* so eviction would make an approved capability permanently unactivatable.
+* Ordering = oldest `resolvedAt` first; a missing or unparseable timestamp sorts
+* LAST (json parity, v16), and pending/executing rows are live work that is
+* never trimmed. v28 G2.4 (STATE-03) — the previous wording promised "an
+* unknown time must never make a record the victim"; that is only true while
+* the overflow fits within the KNOWN-timestamp records. When the overflow
+* exceeds them (corruption-level data: most resolved rows with broken
+* timestamps), `slice` necessarily reaches into the unknown-timestamp tail —
+* the cap must be enforced, so there is no alternative. The guarantee is
+* therefore: unknown-timestamp records are evicted LAST, after every known
+* timestamp, in insertion order among themselves (Array#sort stability).
+*
+* @param records - every pending record currently in the live table.
+* @param cap - how many resolved records may be kept.
+* @returns the records to evict, oldest first (empty when within the cap).
+*/
+function selectPendingOverflow(records, cap = 200) {
+	const resolved = records.filter((record) => (record.status === "approved" || record.status === "rejected") && record.kind !== "capability");
+	const overflow = resolved.length - cap;
+	if (overflow <= 0) return [];
+	const resolvedAtMs = (record) => {
+		if (!record.resolvedAt) return Number.MAX_SAFE_INTEGER;
+		const parsed = Date.parse(record.resolvedAt);
+		return Number.isNaN(parsed) ? Number.MAX_SAFE_INTEGER : parsed;
+	};
+	return [...resolved].sort((a, b) => resolvedAtMs(a) - resolvedAtMs(b)).slice(0, overflow);
+}
+/**
+* V27 G2.2: which review-state session rows a save evicts, as one pure rule
+* both providers apply. The saving session is never a candidate (it is the most
+* recent write by definition); the rest are ordered by their provider stamp
+* ascending, with a missing stamp read as 0 = oldest, because an active session
+* re-stamps its row on its next save and an unknown stamp is stale by
+* construction. Exactly one row is dropped per over-cap save, which keeps the
+* table at the cap in steady state.
+*
+* @param rows - the other sessions' rows, with their stamps.
+* @param cap - how many session rows may exist.
+* @returns the keys to delete, oldest first.
+*/
+function selectSessionOverflow(rows, options, cap = 500) {
+	const overflow = rows.length - cap + 1;
+	if (overflow <= 0) return [];
+	return [...rows].sort((a, b) => options.stampOf(a) - options.stampOf(b)).slice(0, overflow).map((row) => options.keyOf(row));
+}
 var EvolutionStateStorageRegistry = class extends Service {
 	providers = /* @__PURE__ */ new Map();
 	/** C-7 (v18): per-name dispose, mirroring the evolution-io registry. */
 	disposals = /* @__PURE__ */ new Map();
+	/** v28 G3.1 (STATE-04): the multi-provider warn fires once per ambiguous
+	* period, not once per state op (provider() runs on every read/write). */
+	ambiguousWarned = false;
 	constructor(ctx) {
 		super(ctx, "evolutionStateStorage");
 	}
@@ -206,14 +262,21 @@ var EvolutionStateStorageRegistry = class extends Service {
 	}
 	provider(name) {
 		if (name) {
+			this.ambiguousWarned = false;
 			const provider = this.providers.get(name);
 			if (provider) return provider;
 			throw new Error(`evolution state storage provider "${name}" is not registered`);
 		}
 		const first = this.providers.values().next().value;
 		if (!first) throw new Error("no evolution state storage provider registered; mount @lmzhen/dsh-evolution-state-json or @lmzhen/dsh-evolution-state-domain");
+		if (this.providers.size > 1) {
+			if (!this.ambiguousWarned) {
+				this.ambiguousWarned = true;
+				this.ctx.logger.warn(`evolution state storage: ${this.providers.size} providers registered (${[...this.providers.keys()].join(", ")}), none pinned — the effective provider is "${first.name}" (registration order). Existing state under the other provider is now invisible. Pin config: { provider: json|domain } on the evolution-state row to make the choice explicit.`);
+			}
+		} else this.ambiguousWarned = false;
 		return first;
 	}
 };
 //#endregion
-export { CURATOR_STATE_FILE, CURATOR_STATE_KEY, CURATOR_STATE_TABLE, EvolutionStateStorageRegistry, EvolutionStateStorageRegistry as default, PENDING_ARCHIVE_BAK_FILE, PENDING_ARCHIVE_FILE, PENDING_LEGACY_FILE, PENDING_RESOLVED_CAP, PENDING_STATE_FILE, PENDING_TABLE, PROVIDER_DOMAIN, PROVIDER_JSON, REVIEW_STATE_FILE, REVIEW_STATE_SESSION_CAP, REVIEW_STATE_TABLE, UNKNOWN_FIELD_POLICY, assertCloneable, canClaimPending, canResolvePending, cloneRecord, recordIssue, releasedStatus };
+export { CURATOR_STATE_FILE, CURATOR_STATE_KEY, CURATOR_STATE_TABLE, EvolutionStateStorageRegistry, EvolutionStateStorageRegistry as default, PENDING_ARCHIVE_BAK_FILE, PENDING_ARCHIVE_FILE, PENDING_LEGACY_FILE, PENDING_RESOLVED_CAP, PENDING_STATE_FILE, PENDING_TABLE, PROVIDER_DOMAIN, PROVIDER_JSON, REVIEW_STATE_FILE, REVIEW_STATE_SESSION_CAP, REVIEW_STATE_TABLE, UNKNOWN_FIELD_POLICY, assertCloneable, canClaimPending, canResolvePending, cloneRecord, recordIssue, releasedStatus, selectPendingOverflow, selectSessionOverflow };

package/lib/types/index.d.ts

@@ -60,6 +60,48 @@ export declare const PENDING_RESOLVED_CAP = 200;
  * interface change, no background sweeper).
  */
 export declare const REVIEW_STATE_SESSION_CAP = 500;
+/**
+ * V27 G2.2: WHICH pending records the audit cap evicts, as one pure rule both
+ * providers apply (the two implementations had drifted into separate files and
+ * only one of them was ever updated by a later fix).
+ *
+ * Eligible = resolved (`approved`/`rejected`) and NOT a capability approval:
+ * v23 (AP-1) exempts those because the Creator-mode contract reads the LIVE
+ * approved list and a capability cannot be re-submitted for the same package,
+ * so eviction would make an approved capability permanently unactivatable.
+ * Ordering = oldest `resolvedAt` first; a missing or unparseable timestamp sorts
+ * LAST (json parity, v16), and pending/executing rows are live work that is
+ * never trimmed. v28 G2.4 (STATE-03) — the previous wording promised "an
+ * unknown time must never make a record the victim"; that is only true while
+ * the overflow fits within the KNOWN-timestamp records. When the overflow
+ * exceeds them (corruption-level data: most resolved rows with broken
+ * timestamps), `slice` necessarily reaches into the unknown-timestamp tail —
+ * the cap must be enforced, so there is no alternative. The guarantee is
+ * therefore: unknown-timestamp records are evicted LAST, after every known
+ * timestamp, in insertion order among themselves (Array#sort stability).
+ *
+ * @param records - every pending record currently in the live table.
+ * @param cap - how many resolved records may be kept.
+ * @returns the records to evict, oldest first (empty when within the cap).
+ */
+export declare function selectPendingOverflow(records: readonly PendingRecord[], cap?: number): PendingRecord[];
+/**
+ * V27 G2.2: which review-state session rows a save evicts, as one pure rule
+ * both providers apply. The saving session is never a candidate (it is the most
+ * recent write by definition); the rest are ordered by their provider stamp
+ * ascending, with a missing stamp read as 0 = oldest, because an active session
+ * re-stamps its row on its next save and an unknown stamp is stale by
+ * construction. Exactly one row is dropped per over-cap save, which keeps the
+ * table at the cap in steady state.
+ *
+ * @param rows - the other sessions' rows, with their stamps.
+ * @param cap - how many session rows may exist.
+ * @returns the keys to delete, oldest first.
+ */
+export declare function selectSessionOverflow<T>(rows: readonly T[], options: {
+    keyOf(row: T): string;
+    stampOf(row: T): number;
+}, cap?: number): string[];
 /**
  * Claim lifecycle (S3.3): pending →(claim)→ executing →(resolve)→ approved/rejected.
  * release() rolls executing back to pending (failure path). A crash between
@@ -113,6 +155,13 @@ export interface EvolutionStateStorage {
      * whole read → transform → write runs inside one provider transact, so a
      * setPaused racing the run-core bookkeeping write can never interleave a
      * stale load with a newer save.
+     *
+     * V27 S4: the record handed to `task` belongs to the task — a provider must
+     * NEVER pass the object it stores (both current providers hand out a copy:
+     * json re-parses its medium, the domain clones its record). Mutating the
+     * argument is not a supported way to write: a task that does so and then lets
+     * validation refuse the result would otherwise leave a mutated object in the
+     * provider's in-memory store.
      */
     transactCuratorState(task: (current: CuratorStateRecord | null) => CuratorStateRecord | null): Promise<void>;
     listPending(status?: PendingStatus): Promise<PendingRecord[]>;
@@ -139,6 +188,9 @@ export declare class EvolutionStateStorageRegistry extends Service {
     private readonly providers;
     /** C-7 (v18): per-name dispose, mirroring the evolution-io registry. */
     private readonly disposals;
+    /** v28 G3.1 (STATE-04): the multi-provider warn fires once per ambiguous
+     * period, not once per state op (provider() runs on every read/write). */
+    private ambiguousWarned;
     constructor(ctx: Context);
     /** C-7 (v18): re-registering the IDENTICAL provider object is idempotent and
      * returns the original dispose (HMR / re-mounted row); a DIFFERENT object

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-state-storage",
   "description": "Provider registry seam for durable evolution state (community build)",
-  "version": "0.3.67",
+  "version": "0.3.69",
   "publishConfig": {
     "access": "public"
   },