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

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.
@@ -110,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,9 +8,19 @@
  */
 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. */
+ * an unknown kind by consumers rather than minted here.
+ *
+ * 0.3.66: 'capability' is retained with NO producer — the evolution-capability
+ * adapter was removed. It is a read-compatibility member: state written by an
+ * install that used that adapter (≤0.3.65) still holds such records, and they
+ * must keep loading, listing in `/evolution pending`, and answering approve or
+ * reject. Dropping it would strand them two ways: json quarantines the row to
+ * `<file>.corrupt` and refuses the resolving write, while the domain provider
+ * validates every stored record at mount, so one such row fails the whole domain
+ * with `invalid-record`. */
 export type PendingKind = 'memory' | 'skill' | 'capability';
 /** 0.3.17 (S3.3, E-24): 'executing' = claimed, runner in flight — a fresh
  * claim only takes 'pending', and resolve accepts 'pending'/'executing', so a

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