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

package/lib/index.js

@@ -95,6 +95,7 @@ function recordIssue(table, record) {
 	if (typeof value.kind !== "string" || !PENDING_KINDS.has(value.kind)) return "kind must be memory|skill|capability";
 	if (typeof value.summary !== "string") return "summary must be a string";
 	if (!Object.prototype.hasOwnProperty.call(value, "args")) return "args key is required (may be any cloneable value)";
+	if (value.args === void 0) return "args must be a cloneable value — `undefined` is dropped by the json medium and the record would be unreadable after a restart (pass {} instead)";
 	if (typeof value.createdAt !== "string") return "createdAt must be a string";
 	if (typeof value.status !== "string" || !PENDING_STATUSES.has(value.status)) return "status must be pending|executing|approved|rejected";
 	for (const field of [
@@ -157,6 +158,64 @@ const releasedStatus = (status) => status === "executing" ? "pending" : status;
 * The audit ARCHIVE sidecar that json maintains beyond the cap stays
 * json-specific (domain has no sidecar facility) — declared in both READMEs. */
 const PENDING_RESOLVED_CAP = 200;
+/**
+* V24-08 (v24): session rows in the review-state table, per session id. The
+* review pipeline saves on EVERY turn/end of EVERY session and nothing ever
+* deleted rows, so the file grew (and was fully rewritten) with the deploy's
+* whole session history — the same unbounded-growth class the pending cap
+* above already fixed for approvals. A review row is advisory cadence state:
+* evicting the least-recently-active session merely lets that session's next
+* review fire from a fresh counter, so a generous cap is loss-less in
+* practice. Enforced by BOTH providers inside their save path (no seam
+* 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) — an unknown time must never make a record the victim,
+* and pending/executing rows are live work that is never trimmed.
+*
+* @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. */
@@ -203,4 +262,4 @@ var EvolutionStateStorageRegistry = class extends Service {
 	}
 };
 //#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_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

@@ -48,6 +48,53 @@ export declare const releasedStatus: (status: PendingStatus) => PendingStatus;
  * The audit ARCHIVE sidecar that json maintains beyond the cap stays
  * json-specific (domain has no sidecar facility) — declared in both READMEs. */
 export declare const PENDING_RESOLVED_CAP = 200;
+/**
+ * V24-08 (v24): session rows in the review-state table, per session id. The
+ * review pipeline saves on EVERY turn/end of EVERY session and nothing ever
+ * deleted rows, so the file grew (and was fully rewritten) with the deploy's
+ * whole session history — the same unbounded-growth class the pending cap
+ * above already fixed for approvals. A review row is advisory cadence state:
+ * evicting the least-recently-active session merely lets that session's next
+ * review fire from a fresh counter, so a generous cap is loss-less in
+ * practice. Enforced by BOTH providers inside their save path (no seam
+ * 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) — an unknown time must never make a record the victim,
+ * and pending/executing rows are live work that is never trimmed.
+ *
+ * @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
@@ -101,6 +148,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[]>;

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.66",
+  "version": "0.3.68",
   "publishConfig": {
     "access": "public"
   },