@lmzhen/dsh-evolution-state-storage 0.3.63 → 0.3.65

package/lib/index.js

@@ -33,6 +33,99 @@ const REVIEW_STATE_TABLE = "review_state";
 const CURATOR_STATE_TABLE = "curator_state";
 const PENDING_TABLE = "pending";
 //#endregion
+//#region lib/types/record-contract.js
+/**
+* Record contract of the three seam tables (P2-12/14/15/16/18, v19).
+*
+* The contract belongs to the SEAM, not to each provider: before this module
+* the json provider gated writes with plain field predicates while the domain
+* provider relied on its zod schemas, so the same consumer code behaved
+* differently per medium — `transactCuratorState` skipped validation entirely
+* on domain, unknown fields were stripped by zod but preserved by json,
+* `args` was shared by reference on domain, and a non-cloneable payload
+* poisoned every later read. Both providers now call these functions.
+*
+* UNKNOWN_FIELD_POLICY is `preserve`: a record written by a newer version must
+* survive a round-trip through an older provider, so unknown fields are kept
+* (json does this naturally; the domain schemas are `.loose()`).
+*
+* @module @lmzhen/dsh-evolution-state-storage/src/record-contract
+*/
+/** Unknown fields survive a provider round-trip (json preserves by
+* construction; the domain schemas are `.loose()`). */
+const UNKNOWN_FIELD_POLICY = "preserve";
+const isNonNegInt = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const optionalString = (value) => value === void 0 || typeof value === "string";
+const PENDING_KINDS = new Set([
+	"memory",
+	"skill",
+	"capability"
+]);
+const PENDING_STATUSES = new Set([
+	"pending",
+	"executing",
+	"approved",
+	"rejected"
+]);
+/**
+* The write gate for one record. Both providers call this before persisting,
+* so a record the other provider would refuse can never land.
+* @param table - the seam table the record belongs to.
+* @param record - the candidate record.
+* @returns a human-readable issue, or null when the record is well-formed.
+*/
+function recordIssue(table, record) {
+	if (record === null || typeof record !== "object" || Array.isArray(record)) return "record must be a plain object";
+	const value = record;
+	if (table === "review_state") {
+		if (!isNonNegInt(value.turnsSinceMemory)) return "turnsSinceMemory must be a non-negative integer";
+		if (!isNonNegInt(value.turnsSinceSkill)) return "turnsSinceSkill must be a non-negative integer";
+		if (!isNonNegInt(value.lastTurn)) return "lastTurn must be a non-negative integer";
+		return null;
+	}
+	if (table === "curator_state") {
+		if (value.schemaVersion !== void 0 && !isNonNegInt(value.schemaVersion)) return "schemaVersion must be a non-negative integer when present";
+		if (typeof value.lastRunAt !== "number" || !Number.isFinite(value.lastRunAt) || value.lastRunAt < 0) return "lastRunAt must be a finite non-negative number";
+		if (!isNonNegInt(value.runCount)) return "runCount must be a non-negative integer";
+		if (typeof value.lastSummary !== "string") return "lastSummary must be a string";
+		if (typeof value.paused !== "boolean") return "paused must be a boolean";
+		return null;
+	}
+	if (typeof value.id !== "string") return "id must be a string";
+	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 (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 [
+		"resolvedAt",
+		"claimedBy",
+		"claimedAt",
+		"origin",
+		"sessionId"
+	]) if (!optionalString(value[field])) return `${field} must be a string when present`;
+	return null;
+}
+/**
+* P2-15 (v19): the value must survive the seam's copy discipline. A payload
+* that cannot be structured-cloned (functions, symbols, class instances with
+* private state) would make every later read throw far away from the write.
+* @param record - the candidate record.
+* @returns a human-readable issue, or null when the value is cloneable.
+*/
+function assertCloneable(record) {
+	try {
+		structuredClone(record);
+		return null;
+	} catch (error) {
+		return `record is not structured-cloneable (${error instanceof Error ? error.message : String(error)})`;
+	}
+}
+/** Deep copy for every boundary crossing (read AND write). @param record - the value to copy. @returns an independent deep copy. */
+function cloneRecord(record) {
+	return structuredClone(record);
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Provider seam for durable evolution state.
@@ -50,24 +143,46 @@ 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 — both providers keep at
-* most this many resolved (approved/rejected) records, dropping the oldest by
-* `resolvedAt`. Single source (the v15 audit found the bound was json-only,
-* so domain deployments grew the table without bound). The audit ARCHIVE
-* sidecar that json maintains beyond the cap stays json-specific (domain has
-* no sidecar facility) — declared in both READMEs. */
+/** 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;
 var EvolutionStateStorageRegistry = class extends Service {
 	providers = /* @__PURE__ */ new Map();
+	/** C-7 (v18): per-name dispose, mirroring the evolution-io registry. */
+	disposals = /* @__PURE__ */ new Map();
 	constructor(ctx) {
 		super(ctx, "evolutionStateStorage");
 	}
+	/** C-7 (v18): re-registering the IDENTICAL provider object is idempotent and
+	* returns the original dispose (HMR / re-mounted row); a DIFFERENT object
+	* under a registered name still fails loud. The dispose carries a generation
+	* guard so a stale handle cannot remove a newer registration. */
 	registerProvider(provider) {
-		if (this.providers.has(provider.name)) throw new Error(`evolution state storage provider "${provider.name}" already registered`);
-		this.providers.set(provider.name, provider);
-		return () => {
-			if (this.providers.get(provider.name) === provider) this.providers.delete(provider.name);
+		const idempotent = this.providers.get(provider.name) === provider;
+		if (!idempotent && this.providers.has(provider.name)) throw new Error(`evolution state storage provider "${provider.name}" already registered`);
+		if (idempotent) {
+			const existing = this.disposals.get(provider.name);
+			if (existing !== void 0) return existing;
+		}
+		const dispose = () => {
+			if (this.disposals.get(provider.name) !== dispose) return;
+			this.providers.delete(provider.name);
+			this.disposals.delete(provider.name);
 		};
+		this.providers.set(provider.name, provider);
+		this.disposals.set(provider.name, dispose);
+		return dispose;
 	}
 	/** S-07: whether ANY provider is registered. Lets the state
 	* consumer precheck a pinned `provider` config at mount time (a typo fails
@@ -88,4 +203,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, canClaimPending, canResolvePending, 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_TABLE, UNKNOWN_FIELD_POLICY, assertCloneable, canClaimPending, canResolvePending, cloneRecord, recordIssue, releasedStatus };

package/lib/types/index.d.ts

@@ -8,6 +8,7 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 export * from './constants.ts';
+export * from './record-contract.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. */
@@ -24,12 +25,19 @@ 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 — both providers keep at
- * most this many resolved (approved/rejected) records, dropping the oldest by
- * `resolvedAt`. Single source (the v15 audit found the bound was json-only,
- * so domain deployments grew the table without bound). The audit ARCHIVE
- * sidecar that json maintains beyond the cap stays json-specific (domain has
- * no sidecar facility) — declared in both READMEs. */
+/** 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;
 /**
  * Claim lifecycle (S3.3): pending →(claim)→ executing →(resolve)→ approved/rejected.
@@ -108,7 +116,13 @@ declare module '@deepseek-ai/cordis' {
 }
 export declare class EvolutionStateStorageRegistry extends Service {
     private readonly providers;
+    /** C-7 (v18): per-name dispose, mirroring the evolution-io registry. */
+    private readonly disposals;
     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
+     * under a registered name still fails loud. The dispose carries a generation
+     * guard so a stale handle cannot remove a newer registration. */
     registerProvider(provider: EvolutionStateStorage): () => void;
     /** S-07: whether ANY provider is registered. Lets the state
      * consumer precheck a pinned `provider` config at mount time (a typo fails

package/lib/types/record-contract.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Record contract of the three seam tables (P2-12/14/15/16/18, v19).
+ *
+ * The contract belongs to the SEAM, not to each provider: before this module
+ * the json provider gated writes with plain field predicates while the domain
+ * provider relied on its zod schemas, so the same consumer code behaved
+ * differently per medium — `transactCuratorState` skipped validation entirely
+ * on domain, unknown fields were stripped by zod but preserved by json,
+ * `args` was shared by reference on domain, and a non-cloneable payload
+ * poisoned every later read. Both providers now call these functions.
+ *
+ * UNKNOWN_FIELD_POLICY is `preserve`: a record written by a newer version must
+ * survive a round-trip through an older provider, so unknown fields are kept
+ * (json does this naturally; the domain schemas are `.loose()`).
+ *
+ * @module @lmzhen/dsh-evolution-state-storage/src/record-contract
+ */
+import { CURATOR_STATE_TABLE, PENDING_TABLE, REVIEW_STATE_TABLE } from './constants.ts';
+/** The three seam tables a record can belong to. */
+export type SeamRecordTable = typeof REVIEW_STATE_TABLE | typeof CURATOR_STATE_TABLE | typeof PENDING_TABLE;
+/** Unknown fields survive a provider round-trip (json preserves by
+ * construction; the domain schemas are `.loose()`). */
+export declare const UNKNOWN_FIELD_POLICY: "preserve";
+/**
+ * The write gate for one record. Both providers call this before persisting,
+ * so a record the other provider would refuse can never land.
+ * @param table - the seam table the record belongs to.
+ * @param record - the candidate record.
+ * @returns a human-readable issue, or null when the record is well-formed.
+ */
+export declare function recordIssue(table: SeamRecordTable, record: unknown): string | null;
+/**
+ * P2-15 (v19): the value must survive the seam's copy discipline. A payload
+ * that cannot be structured-cloned (functions, symbols, class instances with
+ * private state) would make every later read throw far away from the write.
+ * @param record - the candidate record.
+ * @returns a human-readable issue, or null when the value is cloneable.
+ */
+export declare function assertCloneable(record: unknown): string | null;
+/** Deep copy for every boundary crossing (read AND write). @param record - the value to copy. @returns an independent deep copy. */
+export declare function cloneRecord<T>(record: T): T;
+//# sourceMappingURL=record-contract.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.3.63",
+  "version": "0.3.65",
   "publishConfig": {
     "access": "public"
   },