@lmzhen/dsh-evolution-state-storage 0.3.80 → 0.3.82

package/README.md

@@ -19,6 +19,19 @@ Zero direct token effect from this package; consumers add any model-visible toke
 
 Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
 
+## Conformance suite (S3-2 / J-5)
+
+The package publishes `runStateProviderConsistency(provider, assert)` — the whole seam contract as one call: field-complete pending round-trips, claim/resolve rollback, refusals at the write boundary, clone/alias independence, unknown-field preservation, and the two caps (resolved pending tail, review-state session rows). A third-party provider checks itself by running the suite against its own instance:
+
+```ts
+import { runStateProviderConsistency } from '@deepseek-ai/dsh-evolution-state-storage'
+import { expect } from 'vitest' // or any runner wrapped into `ConformanceAssert`
+
+await runStateProviderConsistency(myProvider, expect)
+```
+
+The assertion surface is INJECTED rather than imported, which is what lets this module ship: it carries no test-runner dependency, so loading the package never loads vitest. Both shipped providers run the same suite (`evolution-state-json` / `evolution-state-domain` `tests/provider-consistency.spec.ts`), and `consistency-forge.spec.ts` proves the suite fails when a single field is forged.
+
 ## Known Limitations and Deferred Work
 
 

package/lib/index.js

@@ -32,6 +32,32 @@ const PROVIDER_DOMAIN = "domain";
 const REVIEW_STATE_TABLE = "review_state";
 const CURATOR_STATE_TABLE = "curator_state";
 const PENDING_TABLE = "pending";
+/** P2-4 (v15): the live pending map/table is BOUNDED on the RESOLVE path —
+* `tryResolvePending` drops the oldest resolved (approved/rejected) records by
+* `resolvedAt` once more than this many exist. Single source (the v15 audit
+* found the bound was json-only, so domain deployments grew the table without
+* bound).
+*
+* C-6 (v18) contract precision: a direct `savePending` of an already-resolved
+* record does NOT trigger eviction (the cap is maintained by the resolve
+* operation, not by the writer), and pending/executing records are never
+* trimmed. Callers that write resolved audit records themselves own that
+* growth; the seam's resolve path is what keeps the table bounded.
+* 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;
 //#endregion
 //#region lib/types/record-contract.js
 /**
@@ -127,6 +153,234 @@ function cloneRecord(record) {
 	return structuredClone(record);
 }
 //#endregion
+//#region lib/types/conformance.js
+/**
+* Published conformance suite for `EvolutionStateStorage` providers (J-5 / S3-2).
+*
+* A third-party provider (or a new medium inside this family) runs ONE call to
+* check the seam contract end to end: field-complete round-trips, claim/resolve
+* rollback, refusal at the write boundary, clone/alias independence, unknown-field
+* preservation, and the two seam caps (the resolved pending tail and the
+* review-state session rows).
+*
+* The assertion surface is INJECTED ({@link ConformanceAssert}) rather than
+* imported: vitest satisfies it in-tree, and a host that only has node:assert can
+* wrap it in a few lines. That keeps this module free of any test-runner import,
+* so it ships inside the published package.
+*/
+/**
+* Cross-provider consistency harness (G7.4, 0.3.22; V4-07 0.3.28).
+*
+* Runs the SAME observable operation sequence against an
+* `EvolutionStateStorage` provider (json or domain) and asserts both yield the
+* same field-complete result. Every pending-record field that is carried
+* through a round-trip is compared field by field: id, kind, status, summary,
+* args, createdAt, origin, sessionId, claimedBy. The wall-clock holder stamps
+* (claimedAt, resolvedAt) are generated by each provider at its own transact
+* time and legitimately differ in value between the two claims, so they are
+* asserted only for presence/type (a string), never for equality — and
+* claimedAt is asserted to be cleared on release. Status filtering / release
+* rollback must agree. S2-4 (v29): the two seam caps — the resolved pending
+* tail (P2-4) and the review-state session rows (V24-08) — are exercised through
+* the same public operations on both providers, so neither medium can keep the
+* bound to itself.
+*/
+/** Build a fixture pending record, optionally carrying origin/sessionId. */
+const pendingOf = (id, kind = "memory", attribution = {}) => ({
+	id,
+	kind,
+	summary: `${kind}:${id}`,
+	args: {},
+	createdAt: "now",
+	status: "pending",
+	...attribution
+});
+/** Every non-holder pending field must equal the input, field by field. */
+const expectPendingCarried = (assert, actual, input) => {
+	assert(actual).toBeDefined();
+	const carried = actual;
+	assert(carried.id).toBe(input.id);
+	assert(carried.kind).toBe(input.kind);
+	assert(carried.summary).toBe(input.summary);
+	assert(carried.args).toEqual(input.args);
+	assert(carried.createdAt).toBe(input.createdAt);
+	assert(carried.origin).toBe(input.origin);
+	assert(carried.sessionId).toBe(input.sessionId);
+};
+/** The listing must contain `id`; a missing row fails the SUITE, not the runner. */
+const findRecord = (records, id) => {
+	const found = records.find((record) => record.id === id);
+	if (found === void 0) throw new Error(`conformance: pending record "${id}" missing from the listing`);
+	return found;
+};
+async function runStateProviderConsistency(provider, assert) {
+	await provider.saveReviewState("s-consistent", {
+		turnsSinceMemory: 1,
+		turnsSinceSkill: 2,
+		lastTurn: 3
+	});
+	assert(await provider.loadReviewState("s-consistent")).toEqual({
+		turnsSinceMemory: 1,
+		turnsSinceSkill: 2,
+		lastTurn: 3
+	});
+	assert(await provider.loadCuratorState()).toBeNull();
+	await provider.transactCuratorState(() => ({
+		lastRunAt: 10,
+		runCount: 0,
+		lastSummary: "seed",
+		paused: false
+	}));
+	assert(await provider.loadCuratorState()).toEqual({
+		lastRunAt: 10,
+		runCount: 0,
+		lastSummary: "seed",
+		paused: false
+	});
+	await provider.transactCuratorState(() => null);
+	assert(await provider.loadCuratorState()).toEqual({
+		lastRunAt: 10,
+		runCount: 0,
+		lastSummary: "seed",
+		paused: false
+	});
+	await provider.transactCuratorState((current) => ({
+		...current,
+		lastSummary: "updated"
+	}));
+	assert(await provider.loadCuratorState()).toEqual({
+		lastRunAt: 10,
+		runCount: 0,
+		lastSummary: "updated",
+		paused: false
+	});
+	const live = pendingOf("c-live");
+	await provider.savePending(live);
+	assert((await provider.listPending("pending")).map((record) => record.id)).toContain("c-live");
+	const claimed = await provider.claimPending("c-live", "claim-a");
+	assert(claimed?.status).toBe("executing");
+	assert(claimed?.claimedBy).toBe("claim-a");
+	expectPendingCarried(assert, claimed, live);
+	assert(typeof claimed?.claimedAt).toBe("string");
+	const resolved = await provider.tryResolvePending("c-live", "approved");
+	assert(resolved.applied).toBe(true);
+	assert(resolved.record?.id).toBe("c-live");
+	assert(resolved.record?.status).toBe("approved");
+	expectPendingCarried(assert, resolved.record, live);
+	assert(resolved.record?.claimedBy).toBe("claim-a");
+	assert(typeof resolved.record?.claimedAt).toBe("string");
+	assert(typeof resolved.record?.resolvedAt).toBe("string");
+	assert((await provider.listPending("approved")).map((record) => record.id)).toContain("c-live");
+	assert((await provider.listPending("pending")).map((record) => record.id)).not.toContain("c-live");
+	const attrib = pendingOf("c-attrib", "memory", {
+		origin: "background_review",
+		sessionId: "sess-attrib"
+	});
+	await provider.savePending(attrib);
+	expectPendingCarried(assert, await provider.claimPending("c-attrib", "claim-a"), attrib);
+	const attribResolved = await provider.tryResolvePending("c-attrib", "approved");
+	expectPendingCarried(assert, attribResolved.record, attrib);
+	assert(attribResolved.record?.origin).toBe("background_review");
+	assert(attribResolved.record?.sessionId).toBe("sess-attrib");
+	assert(typeof attribResolved.record?.resolvedAt).toBe("string");
+	const rel = pendingOf("c-release", "skill");
+	await provider.savePending(rel);
+	assert((await provider.claimPending("c-release", "claim-b"))?.status).toBe("executing");
+	await provider.releasePendingClaim("c-release", "claim-b");
+	const released = (await provider.listPending("pending")).find((record) => record.id === "c-release");
+	assert(released?.status).toBe("pending");
+	expectPendingCarried(assert, released, rel);
+	assert(released?.claimedBy).toBeUndefined();
+	assert(released?.claimedAt).toBeUndefined();
+	const scoped = pendingOf("c-scoped");
+	await provider.savePending(scoped);
+	await provider.claimPending("c-scoped", "claim-owner");
+	assert((await provider.tryResolvePending("c-scoped", "approved", "claim-foreign")).applied).toBe(false);
+	assert((await provider.listPending("executing")).map((record) => record.id)).toContain("c-scoped");
+	const ownerScope = await provider.tryResolvePending("c-scoped", "approved", "claim-owner");
+	assert(ownerScope.applied).toBe(true);
+	assert(ownerScope.record?.status).toBe("approved");
+	const filt = pendingOf("c-filter");
+	await provider.savePending(filt);
+	assert((await provider.listPending("pending")).map((record) => record.id)).toContain("c-filter");
+	assert((await provider.listPending("approved")).map((record) => record.id)).not.toContain("c-filter");
+	const post = pendingOf("c-post-resolve", "memory");
+	await provider.savePending(post);
+	await provider.claimPending("c-post-resolve", "claim-c");
+	await provider.tryResolvePending("c-post-resolve", "rejected");
+	await provider.releasePendingClaim("c-post-resolve", "claim-c");
+	const postResolved = (await provider.listPending("rejected")).find((record) => record.id === "c-post-resolve");
+	assert(postResolved?.status).toBe("rejected");
+	assert(postResolved?.claimedBy).toBe("claim-c");
+	assert(typeof postResolved?.claimedAt).toBe("string");
+	assert(typeof postResolved?.resolvedAt).toBe("string");
+	await assert(provider.savePending({
+		id: "c-bad",
+		kind: "memory",
+		summary: "bad",
+		createdAt: "now",
+		status: "pending"
+	})).rejects.toThrow();
+	const poison = pendingOf("c-poison");
+	poison.args = { nested: { value: 1 } };
+	await provider.savePending(poison);
+	const returned = findRecord(await provider.listPending("pending"), "c-poison");
+	returned.summary = "poisoned";
+	returned.args.nested.value = 99;
+	const reread = findRecord(await provider.listPending("pending"), "c-poison");
+	assert(reread.summary).toBe("memory:c-poison");
+	assert(reread.args.nested.value).toBe(1);
+	const uncloneable = {
+		...pendingOf("c-uncloneable"),
+		args: { fn: () => {} }
+	};
+	await assert(provider.savePending(uncloneable)).rejects.toThrow();
+	const aliased = pendingOf("c-alias");
+	aliased.args = { nested: { value: 1 } };
+	await provider.savePending(aliased);
+	aliased.args.nested.value = 99;
+	assert(findRecord(await provider.listPending("pending"), "c-alias").args.nested.value).toBe(1);
+	await assert(provider.saveCuratorState({
+		lastRunAt: 1,
+		runCount: 0,
+		lastSummary: "x",
+		paused: false,
+		schemaVersion: -1
+	})).rejects.toThrow();
+	await provider.savePending({
+		...pendingOf("c-extra"),
+		extraField: "kept"
+	});
+	assert((await provider.listPending("pending")).find((record) => record.id === "c-extra").extraField).toBe("kept");
+	const capPrefix = "c-cap-";
+	await provider.savePending(pendingOf("c-cap-live", "skill"));
+	for (let index = 0; index <= 201; index += 1) {
+		const id = capPrefix + String(index).padStart(3, "0");
+		await provider.savePending(pendingOf(id));
+		await provider.claimPending(id, "claim-cap");
+		await provider.tryResolvePending(id, "approved");
+	}
+	const resolvedNow = (await provider.listPending("approved")).concat(await provider.listPending("rejected")).filter((record) => record.kind !== "capability");
+	assert(resolvedNow).toHaveLength(200);
+	const resolvedIds = resolvedNow.map((record) => record.id);
+	assert(resolvedIds).not.toContain("c-cap-000");
+	assert(resolvedIds).not.toContain("c-cap-001");
+	assert(resolvedIds).toContain(capPrefix + String(201).padStart(3, "0"));
+	assert((await provider.listPending("pending")).map((record) => record.id)).toContain("c-cap-live");
+	const sessionPrefix = "s-cap-";
+	const reviewStateOf = (turns) => ({
+		turnsSinceMemory: turns,
+		turnsSinceSkill: 0,
+		lastTurn: turns
+	});
+	for (let index = 0; index <= 500; index += 1) await provider.saveReviewState(sessionPrefix + String(index), reviewStateOf(index));
+	assert(await provider.loadReviewState("s-cap-0")).toBeNull();
+	assert(await provider.loadReviewState("s-cap-1")).toEqual(reviewStateOf(1));
+	assert(await provider.loadReviewState(sessionPrefix + String(500))).toEqual(reviewStateOf(500));
+	await provider.saveReviewState("s-cap-0", reviewStateOf(999));
+	assert(await provider.loadReviewState("s-cap-0")).toEqual(reviewStateOf(999));
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Provider seam for durable evolution state.
@@ -144,32 +398,6 @@ const canResolvePending = (status) => status === "pending" || status === "execut
 /** Releasing a claim on an executing record rolls it back to pending (a
 * runner FAILURE is retryable); other statuses pass through unchanged. */
 const releasedStatus = (status) => status === "executing" ? "pending" : status;
-/** P2-4 (v15): the live pending map/table is BOUNDED on the RESOLVE path —
-* `tryResolvePending` drops the oldest resolved (approved/rejected) records by
-* `resolvedAt` once more than this many exist. Single source (the v15 audit
-* found the bound was json-only, so domain deployments grew the table without
-* bound).
-*
-* C-6 (v18) contract precision: a direct `savePending` of an already-resolved
-* record does NOT trigger eviction (the cap is maintained by the resolve
-* operation, not by the writer), and pending/executing records are never
-* trimmed. Callers that write resolved audit records themselves own that
-* growth; the seam's resolve path is what keeps the table bounded.
-* 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
@@ -279,4 +507,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_SESSION_CAP, REVIEW_STATE_TABLE, UNKNOWN_FIELD_POLICY, assertCloneable, canClaimPending, canResolvePending, cloneRecord, recordIssue, releasedStatus, selectPendingOverflow, selectSessionOverflow };
+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, runStateProviderConsistency, selectPendingOverflow, selectSessionOverflow };

package/lib/types/conformance.d.ts

@@ -0,0 +1,27 @@
+import type { EvolutionStateStorage } from './index.ts';
+/**
+ * The assertion surface this suite needs. Vitest's `expect` satisfies it in-tree;
+ * a host with any other runner wraps its own in a few lines. Deliberately
+ * structural and minimal — the suite must not import a test runner.
+ */
+export interface ConformanceAssert {
+    (actual: unknown): {
+        toBe(expected: unknown): void;
+        toEqual(expected: unknown): void;
+        toBeDefined(): void;
+        toBeUndefined(): void;
+        toBeNull(): void;
+        toContain(expected: unknown): void;
+        toHaveLength(length: number): void;
+        toBeGreaterThan(expected: number): void;
+        not: {
+            toBe(expected: unknown): void;
+            toContain(expected: unknown): void;
+        };
+        rejects: {
+            toThrow(expected?: unknown): Promise<void>;
+        };
+    };
+}
+export declare function runStateProviderConsistency(provider: EvolutionStateStorage, assert: ConformanceAssert): Promise<void>;
+//# sourceMappingURL=conformance.d.ts.map

package/lib/types/constants.d.ts

@@ -30,4 +30,30 @@ export declare const PROVIDER_DOMAIN = "domain";
 export declare const REVIEW_STATE_TABLE = "review_state";
 export declare const CURATOR_STATE_TABLE = "curator_state";
 export declare const PENDING_TABLE = "pending";
+/** P2-4 (v15): the live pending map/table is BOUNDED on the RESOLVE path —
+ * `tryResolvePending` drops the oldest resolved (approved/rejected) records by
+ * `resolvedAt` once more than this many exist. Single source (the v15 audit
+ * found the bound was json-only, so domain deployments grew the table without
+ * bound).
+ *
+ * C-6 (v18) contract precision: a direct `savePending` of an already-resolved
+ * record does NOT trigger eviction (the cap is maintained by the resolve
+ * operation, not by the writer), and pending/executing records are never
+ * trimmed. Callers that write resolved audit records themselves own that
+ * growth; the seam's resolve path is what keeps the table bounded.
+ * 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;
 //# sourceMappingURL=constants.d.ts.map

package/lib/types/index.d.ts

@@ -9,6 +9,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 export * from './constants.ts';
 export * from './record-contract.ts';
+export * from './conformance.ts';
 /** 0.3.17 (S3.5, D-4): 'skill_batch' removed — nothing ever created one
  * (dead enum member); the historic value, if it ever reached disk, is read as
  * an unknown kind by consumers rather than minted here.
@@ -34,32 +35,6 @@ export declare const canResolvePending: (status: PendingStatus) => boolean;
 /** Releasing a claim on an executing record rolls it back to pending (a
  * runner FAILURE is retryable); other statuses pass through unchanged. */
 export declare const releasedStatus: (status: PendingStatus) => PendingStatus;
-/** P2-4 (v15): the live pending map/table is BOUNDED on the RESOLVE path —
- * `tryResolvePending` drops the oldest resolved (approved/rejected) records by
- * `resolvedAt` once more than this many exist. Single source (the v15 audit
- * found the bound was json-only, so domain deployments grew the table without
- * bound).
- *
- * C-6 (v18) contract precision: a direct `savePending` of an already-resolved
- * record does NOT trigger eviction (the cap is maintained by the resolve
- * operation, not by the writer), and pending/executing records are never
- * trimmed. Callers that write resolved audit records themselves own that
- * growth; the seam's resolve path is what keeps the table bounded.
- * 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

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