@lyku/para-sync 0.0.1-pre.1 → 0.0.1-pre.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyku/para-sync",
-  "version": "0.0.1-pre.1",
+  "version": "0.0.1-pre.2",
   "description": "synced<T> distributed object sync for the para:* suite — server-authoritative records with live, version-reconciled client replicas. Pre-release: API may change before 0.1.0. Currently provides the pluggable SyncTransport interface and the InProcessTransport implementation (monolith/edge/no-bus deployments); NatsTransport and the synced<T> primitive land on top.",
   "publishConfig": {
     "access": "public"

package/src/client.d.ts

@@ -1,36 +1,3 @@
-/** @typedef {import('./transport.js').SyncEnvelope} SyncEnvelope */
-/** @typedef {import('./transport.js').SyncTransport} SyncTransport */
-/**
- * A schema's parse result — matches para-schema's Result<T, string>.
- * @typedef {{ tag: 'Ok', value: any } | { tag: 'Err', error: string }} Result
- */
-/**
- * Anything with a `parse` returning {@link Result}. In production this is a
- * para-schema `SchemaValue`; in tests it can be a hand-rolled gate. The replica
- * depends only on this shape, never on para-schema directly — which is also why
- * the client gates branch on `.tag` instead of using the throw-on-Err `::`
- * convention (a malformed delta must trigger recovery, not crash the apply).
- * @typedef {{ parse(v: unknown): Result }} SyncSchema
- */
-/**
- * A minimal reactive value cell: get / peek / set. A para-signals `signal()`
- * satisfies it exactly and is the default. Injectable for testing and for the
- * fork-backed cell on the para-svelte side.
- * @typedef {{ get(): any, peek(): any, set(v: any): void }} Cell
- */
-/**
- * @typedef {'ok' | 'stale' | 'skew' | 'refetching'} ReplicaStatus
- *  - ok          last apply succeeded; replica is current
- *  - stale       uninitialized, or a refetch failed / none available
- *  - skew        an inbound value failed `parse` (malformed or schema-skew)
- *  - refetching  a recovery refetch is in flight
- */
-/**
- * @typedef {object} ReplicaMeta
- * @property {string | null} schemaVersion  schema version of the applied value
- * @property {number} sequence              sequence of the applied value (-1 if uninitialized)
- * @property {ReplicaStatus} status
- */
 /**
  * Create a client replica for one synced key.
  *
@@ -42,14 +9,19 @@
  * @param {() => Promise<SyncEnvelope>} [opts.refetch]   Err/skew/gap fallback: fetch the
  *        current authoritative snapshot. Omit → no recovery (status goes 'stale').
  * @param {Cell} [opts.cell]                             reactive cell (default: a para signal)
+ * @param {string} [opts.schemaVersion]                  the client's expected schema
+ *        version ("major.minor"). When set, an inbound envelope whose MAJOR
+ *        differs is treated as a breaking skew: not applied, recovery refetched.
+ *        A minor difference is compatible and falls through to the parse gate.
  */
-export function createClientReplica({ key, schema, transport, seed, refetch, cell }: {
+export function createClientReplica({ key, schema, transport, seed, refetch, cell, schemaVersion, }: {
     key: string;
     schema: SyncSchema;
     transport: SyncTransport;
     seed?: SyncEnvelope;
     refetch?: () => Promise<SyncEnvelope>;
     cell?: Cell;
+    schemaVersion?: string;
 }): {
     /** current value (tracked read) */
     get: () => any;
@@ -66,6 +38,7 @@ export function createClientReplica({ key, schema, transport, seed, refetch, cel
         gaps: number;
         parseErrors: number;
         refetches: number;
+        schemaSkews: number;
     };
     /** resolves when no recovery refetch is in flight (test/await aid) */
     whenIdle: () => Promise<void>;

package/src/client.js

@@ -50,6 +50,21 @@ import { signal } from "@lyku/para-signals";
  * @property {ReplicaStatus} status
  */
 
+/**
+ * Compare two "major.minor" version strings by MAJOR only. Returns true iff both
+ * are well-formed and their majors differ (a breaking change). Missing/malformed
+ * versions return false — let the parse gate be the backstop rather than block on
+ * a version-format quirk.
+ * @param {string | undefined} a
+ * @param {string | undefined} b
+ */
+function majorMismatch(a, b) {
+  const ma = /^(\d+)\./.exec(a == null ? "" : String(a));
+  const mb = /^(\d+)\./.exec(b == null ? "" : String(b));
+  if (ma === null || mb === null) return false;
+  return ma[1] !== mb[1];
+}
+
 /**
  * Create a client replica for one synced key.
  *
@@ -61,8 +76,20 @@ import { signal } from "@lyku/para-signals";
  * @param {() => Promise<SyncEnvelope>} [opts.refetch]   Err/skew/gap fallback: fetch the
  *        current authoritative snapshot. Omit → no recovery (status goes 'stale').
  * @param {Cell} [opts.cell]                             reactive cell (default: a para signal)
+ * @param {string} [opts.schemaVersion]                  the client's expected schema
+ *        version ("major.minor"). When set, an inbound envelope whose MAJOR
+ *        differs is treated as a breaking skew: not applied, recovery refetched.
+ *        A minor difference is compatible and falls through to the parse gate.
  */
-export function createClientReplica({ key, schema, transport, seed, refetch, cell }) {
+export function createClientReplica({
+  key,
+  schema,
+  transport,
+  seed,
+  refetch,
+  cell,
+  schemaVersion,
+}) {
   const value = cell ?? signal(undefined);
   /** @type {Cell} */
   const meta = signal(
@@ -73,7 +100,14 @@ export function createClientReplica({ key, schema, transport, seed, refetch, cel
   let disposed = false;
   let pending = Promise.resolve();
 
-  const stats = { applied: 0, ignoredStale: 0, gaps: 0, parseErrors: 0, refetches: 0 };
+  const stats = {
+    applied: 0,
+    ignoredStale: 0,
+    gaps: 0,
+    parseErrors: 0,
+    refetches: 0,
+    schemaSkews: 0,
+  };
 
   /** @param {Partial<ReplicaMeta>} patch */
   const setMeta = (patch) => meta.set({ ...meta.peek(), ...patch });
@@ -110,6 +144,22 @@ export function createClientReplica({ key, schema, transport, seed, refetch, cel
   function ingest(envelope, source) {
     if (disposed) return;
 
+    // ── schema-version gate ──
+    // A breaking (major) schema-version difference means the value was produced
+    // against an incompatible shape. Don't apply it — the parse gate would
+    // likely reject it too, but the version is the explicit, earlier signal and
+    // tells us this is "different shape" (refetch), not "behind but compatible".
+    // A minor difference (same major) is compatible and falls through to parse.
+    if (
+      schemaVersion !== undefined &&
+      majorMismatch(schemaVersion, envelope.schema_version)
+    ) {
+      stats.schemaSkews++;
+      setMeta({ status: "skew" });
+      if (source !== "refetch") startRefetch();
+      return;
+    }
+
     // ── parse gate (every inbound value crosses a trust boundary) ──
     const res = schema.parse(envelope.value);
     if (res.tag !== "Ok") {