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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyku/para-sync",
-  "version": "0.0.1-pre.0",
+  "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"
@@ -8,8 +8,12 @@
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
   },
   "dependencies": {
     "@lyku/para-signals": "^0.0.1-pre.0"

package/src/client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Create a client replica for one synced key.
+ *
+ * @param {object} opts
+ * @param {string} opts.key                              synced key, e.g. "user:123"
+ * @param {SyncSchema} opts.schema                       the `parse` gate
+ * @param {SyncTransport} opts.transport                 change-envelope source
+ * @param {SyncEnvelope} [opts.seed]                     SSR-embedded initial envelope
+ * @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, schemaVersion, }: {
+    key: string;
+    schema: SyncSchema;
+    transport: SyncTransport;
+    seed?: SyncEnvelope;
+    refetch?: () => Promise<SyncEnvelope>;
+    cell?: Cell;
+    schemaVersion?: string;
+}): {
+    /** current value (tracked read) */
+    get: () => any;
+    /** current value (untracked) */
+    peek: () => any;
+    /** reconcile metadata (tracked): { schemaVersion, sequence, status } */
+    meta: () => any;
+    /** reconcile metadata (untracked) */
+    peekMeta: () => any;
+    /** observability counters — read directly */
+    stats: {
+        applied: number;
+        ignoredStale: number;
+        gaps: number;
+        parseErrors: number;
+        refetches: number;
+        schemaSkews: number;
+    };
+    /** resolves when no recovery refetch is in flight (test/await aid) */
+    whenIdle: () => Promise<void>;
+    /** stop listening; idempotent */
+    dispose: () => void;
+};
+export type SyncEnvelope = import("./transport.js").SyncEnvelope;
+export type SyncTransport = import("./transport.js").SyncTransport;
+/**
+ * A schema's parse result — matches para-schema's Result<T, string>.
+ */
+export type Result = {
+    tag: "Ok";
+    value: any;
+} | {
+    tag: "Err";
+    error: string;
+};
+/**
+ * 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).
+ */
+export type SyncSchema = {
+    parse(v: unknown): Result;
+};
+/**
+ * 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.
+ */
+export type Cell = {
+    get(): any;
+    peek(): any;
+    set(v: any): void;
+};
+/**
+ * - 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
+ */
+export type ReplicaStatus = "ok" | "stale" | "skew" | "refetching";
+export type ReplicaMeta = {
+    /**
+     * schema version of the applied value
+     */
+    schemaVersion: string | null;
+    /**
+     * sequence of the applied value (-1 if uninitialized)
+     */
+    sequence: number;
+    status: ReplicaStatus;
+};

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") {

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./transport.js";
+export * from "./client.js";

package/src/transport.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The change envelope. Delta/full-object model: the new value travels with
+ * the reconcile key, so steady-state replication is deliver → parse → apply,
+ * with no refetch round-trip (refetch is the Err/gap/skew fallback only).
+ *
+ * @typedef {object} SyncEnvelope
+ * @property {unknown} value          The full changed object. NOT validated by
+ *                                    the transport — `parse` gating is the
+ *                                    consumer's job at the apply boundary.
+ * @property {string} schema_version  Reconcile key, part 1: the model's schema
+ *                                    version (e.g. "3.1"). Distinguishes a
+ *                                    compatible-but-behind replica from a
+ *                                    different/breaking shape.
+ * @property {number} sequence        Reconcile key, part 2: the object's
+ *                                    monotonic Postgres-authoritative sequence.
+ *                                    Sole job is ordering + gap detection.
+ */
+/**
+ * A listener for a key's change envelopes.
+ * @callback SyncHandler
+ * @param {SyncEnvelope} envelope
+ * @returns {void}
+ */
+/**
+ * Returned by subscribe(); calling it removes the subscription. Idempotent.
+ * @callback Unsub
+ * @returns {void}
+ */
+/**
+ * The pluggable transport contract. `synced<T>` depends ONLY on this shape, not
+ * on any concrete transport — that decoupling is what lets the same primitive
+ * run on a single box (InProcessTransport) or across services (NatsTransport).
+ *
+ * Contract notes that every implementation must honor:
+ *   - publish(key, envelope) delivers `envelope` to every current subscriber of
+ *     `key`. Publishing to a key with no subscribers is a no-op (never throws).
+ *   - The transport is a dumb pipe: it does NOT retain the latest value, does
+ *     NOT validate the envelope, and does NOT dedupe by sequence. A subscriber
+ *     receives only publishes that happen AFTER it subscribes — initial state
+ *     arrives via the SSR seed, not the transport.
+ *   - subscribe(key, handler) returns an idempotent Unsub.
+ *
+ * @typedef {object} SyncTransport
+ * @property {(key: string, envelope: SyncEnvelope) => void} publish
+ * @property {(key: string, handler: SyncHandler) => Unsub} subscribe
+ */
+/**
+ * In-process implementation of {@link SyncTransport}. A keyed pub/sub emitter:
+ * `Map<key, Set<handler>>`. No bus, no network, no serialization — the write
+ * and the listen happen in the same process, so delivery is a synchronous call.
+ *
+ * Why a plain emitter and not a para-signal per key: the transport contract is
+ * notification semantics ("deliver future publishes to this handler"), not
+ * value-cell semantics ("hand me the current value on subscribe, then deltas").
+ * Initial state is the SSR seed's job; the transport only carries changes. A
+ * keyed emitter models that exactly, without the current-value-on-subscribe and
+ * Object.is-dedupe behavior a signal would impose.
+ *
+ * @implements {SyncTransport}
+ */
+export class InProcessTransport implements SyncTransport {
+    /**
+     * key → set of handlers. A key is present iff it has ≥1 live subscriber;
+     * the entry is deleted when its last subscriber unsubscribes (no key leak).
+     * @type {Map<string, Set<SyncHandler>>}
+     */
+    _subs: Map<string, Set<SyncHandler>>;
+    /**
+     * Deliver `envelope` to every current subscriber of `key`, in subscription
+     * order. No-op if `key` has no subscribers.
+     * @param {string} key
+     * @param {SyncEnvelope} envelope
+     */
+    publish(key: string, envelope: SyncEnvelope): void;
+    /**
+     * Subscribe `handler` to `key`'s change envelopes. Returns an idempotent
+     * Unsub; calling it more than once is safe and will not remove a handler that
+     * was re-subscribed in between.
+     * @param {string} key
+     * @param {SyncHandler} handler
+     * @returns {Unsub}
+     */
+    subscribe(key: string, handler: SyncHandler): Unsub;
+    /**
+     * Diagnostic: number of keys with at least one live subscriber. Useful for
+     * leak checks (a healthy server returns to a steady key count as sessions
+     * come and go).
+     * @returns {number}
+     */
+    keyCount(): number;
+}
+/**
+ * NATS implementation of {@link SyncTransport}, for multi-service deployments
+ * where a write in the writer's service must reach listeners in other services.
+ * Matches Lyku's existing full-object-over-NATS convention.
+ *
+ * Honors the same contract as InProcessTransport (deliver to current
+ * subscribers, no retention, dumb pipe, idempotent unsub). On top it adds:
+ *   - subject mapping (key → NATS subject),
+ *   - the wire codec (encode on publish, decode on receipt),
+ *   - LOCAL FANOUT: N local subscribers to one key share ONE bus subscription,
+ *     and that bus subscription is torn down when the last local subscriber
+ *     leaves (the cross-service analog of subscriber-set GC).
+ *
+ * @implements {SyncTransport}
+ */
+export class NatsTransport implements SyncTransport {
+    /**
+     * @param {object} opts
+     * @param {SyncNatsConnection} opts.connection
+     * @param {SyncCodec} [opts.codec]                     default: identity (tests only)
+     * @param {(key: string) => string} [opts.subjectOf]   default: `synced.${key}`
+     */
+    constructor({ connection, codec, subjectOf }: {
+        connection: SyncNatsConnection;
+        codec?: SyncCodec;
+        subjectOf?: (key: string) => string;
+    });
+    _nc: SyncNatsConnection;
+    _codec: SyncCodec;
+    _subjectOf: (key: string) => string;
+    /**
+     * key → { natsUnsub, handlers } — present iff the key has ≥1 local
+     * subscriber (and therefore one live bus subscription).
+     * @type {Map<string, { natsUnsub: () => void, handlers: Set<SyncHandler> }>}
+     */
+    _keys: Map<string, {
+        natsUnsub: () => void;
+        handlers: Set<SyncHandler>;
+    }>;
+    /**
+     * @param {string} key
+     * @param {SyncEnvelope} envelope
+     */
+    publish(key: string, envelope: SyncEnvelope): void;
+    /**
+     * @param {string} key
+     * @param {SyncHandler} handler
+     * @returns {Unsub}
+     */
+    subscribe(key: string, handler: SyncHandler): Unsub;
+    /**
+     * Diagnostic: number of keys with a live bus subscription.
+     * @returns {number}
+     */
+    keyCount(): number;
+}
+/**
+ * The change envelope. Delta/full-object model: the new value travels with
+ * the reconcile key, so steady-state replication is deliver → parse → apply,
+ * with no refetch round-trip (refetch is the Err/gap/skew fallback only).
+ */
+export type SyncEnvelope = {
+    /**
+     * The full changed object. NOT validated by
+     * the transport — `parse` gating is the
+     * consumer's job at the apply boundary.
+     */
+    value: unknown;
+    /**
+     * Reconcile key, part 1: the model's schema
+     * version (e.g. "3.1"). Distinguishes a
+     * compatible-but-behind replica from a
+     * different/breaking shape.
+     */
+    schema_version: string;
+    /**
+     * Reconcile key, part 2: the object's
+     * monotonic Postgres-authoritative sequence.
+     * Sole job is ordering + gap detection.
+     */
+    sequence: number;
+};
+/**
+ * A listener for a key's change envelopes.
+ */
+export type SyncHandler = (envelope: SyncEnvelope) => void;
+/**
+ * Returned by subscribe(); calling it removes the subscription. Idempotent.
+ */
+export type Unsub = () => void;
+/**
+ * The pluggable transport contract. `synced<T>` depends ONLY on this shape, not
+ * on any concrete transport — that decoupling is what lets the same primitive
+ * run on a single box (InProcessTransport) or across services (NatsTransport).
+ *
+ * Contract notes that every implementation must honor:
+ *   - publish(key, envelope) delivers `envelope` to every current subscriber of
+ *     `key`. Publishing to a key with no subscribers is a no-op (never throws).
+ *   - The transport is a dumb pipe: it does NOT retain the latest value, does
+ *     NOT validate the envelope, and does NOT dedupe by sequence. A subscriber
+ *     receives only publishes that happen AFTER it subscribes — initial state
+ *     arrives via the SSR seed, not the transport.
+ *   - subscribe(key, handler) returns an idempotent Unsub.
+ */
+export type SyncTransport = {
+    publish: (key: string, envelope: SyncEnvelope) => void;
+    subscribe: (key: string, handler: SyncHandler) => Unsub;
+};
+/**
+ * A NATS connection, callback-adapted. NatsTransport expects delivery as a
+ * callback + an unsubscribe, NOT nats.js's raw async-iterable subscription —
+ * the iterable→callback adaptation is a 3-line caller concern that Lyku already
+ * does (`const sub = nc.subscribe(subj); (async () => { for await (const m of
+ * sub) onMessage(m.data); })(); return () => sub.unsubscribe();`). Keeping that
+ * out of the transport makes delivery synchronous and deterministic to test.
+ */
+export type SyncNatsConnection = {
+    publish: (subject: string, payload: Uint8Array) => void;
+    /**
+     *   subscribe to `subject`; `onMessage` is called per message with the raw
+     *   payload; returns an unsubscribe function.
+     */
+    subscribe: (subject: string, onMessage: (payload: Uint8Array) => void) => (() => void);
+};
+/**
+ * Wire codec: envelope ⇄ bytes. NATS payloads are `Uint8Array`. In production
+ * inject a BON or msgpackr codec (envelopes carry bigint IDs, which JSON cannot
+ * represent — BON is the SSR/wire serializer for exactly this reason). Defaults
+ * to identity (object passthrough), which works for in-memory fakes/tests but
+ * NOT a real NATS connection.
+ */
+export type SyncCodec = {
+    encode: (envelope: SyncEnvelope) => any;
+    decode: (payload: any) => SyncEnvelope;
+};