@lmzhen/dsh-evolution-state-storage 0.25.9 → 0.26.26

package/lib/index.js

@@ -427,6 +427,93 @@ async function runStateProviderConsistency(provider, assert, options = {}) {
 	assert(await provider.loadReviewState(sessionPrefix + "0")).toEqual(reviewStateOf(999));
 }
 //#endregion
+//#region lib/types/medium-comparison.js
+/**
+* Compare the pending state as two media read it.
+* @param left - the provider currently in use.
+* @param right - the provider the deployment would switch to.
+* @returns whether the readings agree, and every disagreement, ordered by id.
+*/
+async function comparePendingReadings(left, right) {
+	const [leftRecords, rightRecords] = await Promise.all([left.listPending(), right.listPending()]);
+	const statusOf = (records) => new Map(records.map((record) => [record.id, record.status]));
+	const leftStatus = statusOf(leftRecords);
+	const rightStatus = statusOf(rightRecords);
+	const ids = [...new Set([...leftStatus.keys(), ...rightStatus.keys()])].sort();
+	const differences = [];
+	for (const id of ids) {
+		const leftValue = leftStatus.get(id);
+		const rightValue = rightStatus.get(id);
+		if (leftValue === rightValue) continue;
+		const verdict = leftValue === void 0 ? "right-only" : rightValue === void 0 ? "left-only" : "status-differs";
+		differences.push({
+			id,
+			left: leftValue,
+			right: rightValue,
+			verdict
+		});
+	}
+	return {
+		consistent: differences.length === 0,
+		differences
+	};
+}
+//#endregion
+//#region lib/types/medium-declaration.js
+/**
+* G2b/2b.3: which medium carries each record type, and what PROCESS SCOPE that medium actually gives.
+*
+* The family has two serialization layers and only ever wrote one of them down, for the json provider: the
+* IO backend cross-process transact lock (first layer) and the caller own in-process chain (second). The
+* domain medium inherits its answer from whatever backend the platform storage facility routes, and nothing
+* stated it. So this file states it - and the criterion is the family one: a CLAIM must be produced by a
+* capability that can be DISPROVED. processScopeViolations takes the io the provider writes through and
+* reports every claim of cross-process that the io cannot back up.
+*
+* MIGRATION NOTE: the plan allows naming storage-sqlite for a cross-process record type. That package does
+* not exist in this tree (0 hits), so today every entry is either backed by the IO transact lock or
+* declares single-process. When a backend carrying its own cross-process guarantee lands, it is named here
+* and the reasoning moves with it - one declaration, not two.
+*
+* @module @lmzhen/dsh-evolution-state-storage/medium-declaration
+*/
+/** The declaration. */
+const MEDIUM_PROCESS_DECLARATION = [
+	{
+		record: "review_state",
+		medium: "json",
+		scope: "cross-process",
+		because: "the json provider serializes through the IO backend transact lock, as its README states"
+	},
+	{
+		record: "curator_state",
+		medium: "json",
+		scope: "cross-process",
+		because: "same provider and same lock as review_state; the run bookkeeping rides the same write path"
+	},
+	{
+		record: "pending",
+		medium: "json",
+		scope: "cross-process",
+		because: "a staged write is claimed by name across processes, so it needs the lock more than the other two"
+	},
+	{
+		record: "evolution-domain",
+		medium: "domain",
+		scope: "single-process",
+		because: "no backend in this tree carries its own cross-process guarantee and none is named, so the domain facility lock semantics stay the backend business and this declares the weaker truth"
+	}
+];
+/**
+* Falsify the declaration against a capability reading.
+* @param io - the io backend the medium writes through, or undefined when none is mounted.
+* @returns one message per claim the capability cannot back up; empty when every claim holds.
+*/
+function processScopeViolations(io) {
+	const backed = typeof io?.transact === "function";
+	return MEDIUM_PROCESS_DECLARATION.filter((claim) => claim.scope === "cross-process" && !backed).map((claim) => claim.record + " claims cross-process (" + claim.because + ") but the mounted io exposes no transact lock");
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Provider seam for durable evolution state.
@@ -534,6 +621,17 @@ var EvolutionStateStorageRegistry = class extends Service {
 	hasProviders() {
 		return this.providers.size > 0;
 	}
+	/**
+	* G2b/2b.1: the registered provider names, in registration order.
+	*
+	* A consumer needs the COUNT to refuse an unpinned choice while more than one medium is mounted:
+	* this registry cannot make that call itself, because the pin lives in the consumer's config and the
+	* registry never sees it. Read-only, and it exists so the refusal can happen at mount instead of at the
+	* first read (where the state is already half-consumed and the message arrives too late to act on).
+	*/
+	providerNames() {
+		return [...this.providers.keys()];
+	}
 	provider(name) {
 		if (name) {
 			this.ambiguousWarned = false;
@@ -553,4 +651,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_KINDS, PENDING_LEGACY_FILE, PENDING_RESOLVED_CAP, PENDING_STATE_FILE, PENDING_STATUSES, 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, runStateProviderConsistency, selectPendingOverflow, selectSessionOverflow };
+export { CURATOR_STATE_FILE, CURATOR_STATE_KEY, CURATOR_STATE_TABLE, EvolutionStateStorageRegistry, EvolutionStateStorageRegistry as default, MEDIUM_PROCESS_DECLARATION, PENDING_ARCHIVE_BAK_FILE, PENDING_ARCHIVE_FILE, PENDING_KINDS, PENDING_LEGACY_FILE, PENDING_RESOLVED_CAP, PENDING_STATE_FILE, PENDING_STATUSES, PENDING_TABLE, PROVIDER_DOMAIN, PROVIDER_JSON, REVIEW_STATE_FILE, REVIEW_STATE_SESSION_CAP, REVIEW_STATE_TABLE, UNKNOWN_FIELD_POLICY, assertCloneable, canClaimPending, canResolvePending, cloneRecord, comparePendingReadings, processScopeViolations, recordIssue, releasedStatus, runStateProviderConsistency, selectPendingOverflow, selectSessionOverflow };

package/lib/types/index.d.ts

@@ -11,6 +11,8 @@ import type { PendingKind, PendingStatus } from './record-contract.ts';
 export * from './constants.ts';
 export * from './record-contract.ts';
 export * from './conformance.ts';
+export * from './medium-comparison.ts';
+export * from './medium-declaration.ts';
 /** 0.3.17 (S3.3): the claim lifecycle as ONE transition table — BOTH
  * providers (json/domain) must use these, never a hand-written copy (a second
  * copy is exactly the E-10 drift class). */
@@ -163,6 +165,15 @@ export declare class EvolutionStateStorageRegistry extends Service {
      * at start with the registry's precise message) while staying lazy when no
      * provider has registered yet (mount order not settled). */
     hasProviders(): boolean;
+    /**
+     * G2b/2b.1: the registered provider names, in registration order.
+     *
+     * A consumer needs the COUNT to refuse an unpinned choice while more than one medium is mounted:
+     * this registry cannot make that call itself, because the pin lives in the consumer's config and the
+     * registry never sees it. Read-only, and it exists so the refusal can happen at mount instead of at the
+     * first read (where the state is already half-consumed and the message arrives too late to act on).
+     */
+    providerNames(): readonly string[];
     provider(name?: string): EvolutionStateStorage;
 }
 export default EvolutionStateStorageRegistry;

package/lib/types/medium-comparison.d.ts

@@ -0,0 +1,36 @@
+/**
+ * G2a/2a.2: the two-medium read comparison.
+ *
+ * Audit S1-B02: switching back to the json medium revives staged records the other medium never had
+ * (the json read face merges a legacy `pending.json`, which re-introduces an evicted record), and the
+ * default TTL of 0 makes age no threshold at all. The fix is not a third store - it is being able to SEE
+ * the disagreement: the SAME logical state read through both providers must agree.
+ *
+ * This lives in the seam package because that is the layer the two providers share. Comparing the
+ * packages' own file reads would bypass the seam and stop working the moment a provider is swapped.
+ *
+ * Read-only: it reports, it never writes and never repairs.
+ */
+import type { EvolutionStateStorage, PendingStatus } from './index.ts';
+/** One record that the two readings do not agree on. */
+export interface MediumDifference {
+    readonly id: string;
+    readonly left: PendingStatus | undefined;
+    readonly right: PendingStatus | undefined;
+    /** `left-only` is the revival shape: the json side holds a record the other medium never had. */
+    readonly verdict: 'left-only' | 'right-only' | 'status-differs';
+}
+/** The comparison result. `consistent: false` is the red signal S1-B02 asks for. */
+export interface MediumComparison {
+    readonly consistent: boolean;
+    /** One entry per record the readings disagree on, ordered by id. */
+    readonly differences: readonly MediumDifference[];
+}
+/**
+ * Compare the pending state as two media read it.
+ * @param left - the provider currently in use.
+ * @param right - the provider the deployment would switch to.
+ * @returns whether the readings agree, and every disagreement, ordered by id.
+ */
+export declare function comparePendingReadings(left: Pick<EvolutionStateStorage, 'listPending'>, right: Pick<EvolutionStateStorage, 'listPending'>): Promise<MediumComparison>;
+//# sourceMappingURL=medium-comparison.d.ts.map

package/lib/types/medium-declaration.d.ts

@@ -0,0 +1,40 @@
+/**
+ * G2b/2b.3: which medium carries each record type, and what PROCESS SCOPE that medium actually gives.
+ *
+ * The family has two serialization layers and only ever wrote one of them down, for the json provider: the
+ * IO backend cross-process transact lock (first layer) and the caller own in-process chain (second). The
+ * domain medium inherits its answer from whatever backend the platform storage facility routes, and nothing
+ * stated it. So this file states it - and the criterion is the family one: a CLAIM must be produced by a
+ * capability that can be DISPROVED. processScopeViolations takes the io the provider writes through and
+ * reports every claim of cross-process that the io cannot back up.
+ *
+ * MIGRATION NOTE: the plan allows naming storage-sqlite for a cross-process record type. That package does
+ * not exist in this tree (0 hits), so today every entry is either backed by the IO transact lock or
+ * declares single-process. When a backend carrying its own cross-process guarantee lands, it is named here
+ * and the reasoning moves with it - one declaration, not two.
+ *
+ * @module @lmzhen/dsh-evolution-state-storage/medium-declaration
+ */
+/** One record type: its medium, the process scope claimed for it, and why that is true. */
+export interface MediumProcessClaim {
+    /** The record family, named as the domain declares it. */
+    readonly record: string;
+    readonly medium: 'json' | 'domain';
+    /** cross-process is a CLAIM: processScopeViolations refuses it without a backing transact. */
+    readonly scope: 'cross-process' | 'single-process';
+    readonly because: string;
+}
+/** The declaration. */
+export declare const MEDIUM_PROCESS_DECLARATION: readonly MediumProcessClaim[];
+/** The capability the claims are checked against: the io the medium writes through. */
+export interface ProcessScopeProbe {
+    /** The IO backend transact entry point, when it has one. */
+    readonly transact?: unknown;
+}
+/**
+ * Falsify the declaration against a capability reading.
+ * @param io - the io backend the medium writes through, or undefined when none is mounted.
+ * @returns one message per claim the capability cannot back up; empty when every claim holds.
+ */
+export declare function processScopeViolations(io: ProcessScopeProbe | undefined): readonly string[];
+//# sourceMappingURL=medium-declaration.d.ts.map

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