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

package/lib/index.js

@@ -180,8 +180,15 @@ const REVIEW_STATE_SESSION_CAP = 500;
 * 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) — an unknown time must never make a record the victim,
-* and pending/executing rows are live work that is never trimmed.
+* 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.
@@ -220,6 +227,9 @@ 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");
 	}
@@ -252,12 +262,19 @@ 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;
 	}
 };

package/lib/types/index.d.ts

@@ -70,8 +70,15 @@ export declare const REVIEW_STATE_SESSION_CAP = 500;
  * 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) — an unknown time must never make a record the victim,
- * and pending/executing rows are live work that is never trimmed.
+ * 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.
@@ -181,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.68",
+  "version": "0.3.69",
   "publishConfig": {
     "access": "public"
   },