@kyneta/yjs-schema 1.0.0 → 1.1.0

package/src/substrate.ts

@@ -8,25 +8,26 @@
 // The event bridge contract: wrapping a Y.Doc in a kyneta substrate
 // means subscribing to the kyneta doc observes ALL mutations to the
 // underlying Y.Doc, regardless of source (local kyneta writes,
-// importDelta, external Y.applyUpdate, external raw Yjs API mutations).
+// merge, external Y.applyUpdate, external raw Yjs API mutations).
 
 import type {
   ChangeBase,
   Path,
+  Reader,
+  Replica,
+  ReplicaFactory,
   Schema as SchemaNode,
-  StoreReader,
   Substrate,
   SubstrateFactory,
   SubstratePayload,
   WritableContext,
 } from "@kyneta/schema"
-import { buildWritableContext, executeBatch } from "@kyneta/schema"
+import { BACKING_DOC, buildWritableContext, executeBatch } from "@kyneta/schema"
 import * as Y from "yjs"
 import { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
 import { ensureContainers } from "./populate.js"
-import { yjsStoreReader } from "./store-reader.js"
+import { yjsReader } from "./reader.js"
 import { YjsVersion } from "./version.js"
-import { registerYjsSubstrate } from "./yjs-escape.js"
 
 // ---------------------------------------------------------------------------
 // Origin tag — used to suppress echo from our own transactions
@@ -44,11 +45,11 @@ const KYNETA_ORIGIN = "kyneta-prepare"
  * This is the "bring your own doc" entry point. The user creates and
  * manages the Y.Doc (possibly via a Yjs provider); this function wraps
  * it with a schema-aware overlay providing typed reads, writes,
- * versioning, and export/import through the standard Substrate interface.
+ * versioning, and export/merge through the standard Substrate interface.
  *
  * **Event bridge contract:** A persistent `observeDeep` handler is
  * registered on the root Y.Map at construction time. All non-kyneta
- * mutations to the Y.Doc (imports, external local writes) are bridged
+ * mutations to the Y.Doc (merges, external local writes) are bridged
  * to the kyneta changefeed. Subscribing to the kyneta doc observes all
  * mutations regardless of source.
  *
@@ -71,8 +72,8 @@ export function createYjsSubstrate(
   // to be), and onFlush() skips transact/commit.
   let inOurTransaction = false
 
-  // Stashed origin from importDelta for the event bridge to pick up.
-  let pendingImportOrigin: string | undefined
+  // Stashed origin from merge for the event bridge to pick up.
+  let pendingMergeOrigin: string | undefined
 
   // Lazy-built WritableContext (same pattern as PlainSubstrate / LoroSubstrate).
   let cachedCtx: WritableContext | undefined
@@ -80,13 +81,15 @@ export function createYjsSubstrate(
   // The root Y.Map — all schema fields are children of this single map.
   const rootMap = doc.getMap("root")
 
-  // The StoreReader — live view over the Yjs shared type tree.
-  const reader: StoreReader = yjsStoreReader(doc, schema)
+  // The Reader — live view over the Yjs shared type tree.
+  const reader: Reader = yjsReader(doc, schema)
 
   // --- Substrate object ---
 
-  const substrate: Substrate<YjsVersion> = {
-    store: reader,
+  const substrate = {
+    [BACKING_DOC]: doc,
+
+    reader: reader,
 
     prepare(path: Path, change: ChangeBase): void {
       if (!inOurTransaction) {
@@ -129,8 +132,9 @@ export function createYjsSubstrate(
       return new YjsVersion(Y.encodeStateVector(doc))
     },
 
-    exportSnapshot(): SubstratePayload {
+    exportEntirety(): SubstratePayload {
       return {
+        kind: "entirety",
         encoding: "binary",
         data: Y.encodeStateAsUpdate(doc),
       }
@@ -139,27 +143,28 @@ export function createYjsSubstrate(
     exportSince(since: YjsVersion): SubstratePayload | null {
       try {
         const bytes = Y.encodeStateAsUpdate(doc, since.sv)
-        return { encoding: "binary", data: bytes }
+        return { kind: "since", encoding: "binary", data: bytes }
       } catch {
         return null
       }
     },
 
-    importDelta(payload: SubstratePayload, origin?: string): void {
+    merge(payload: SubstratePayload, origin?: string): void {
       if (
         payload.encoding !== "binary" ||
         !(payload.data instanceof Uint8Array)
       ) {
         throw new Error(
-          "YjsSubstrate.importDelta only supports binary-encoded payloads",
+          "YjsSubstrate.merge expects binary-encoded payloads. " +
+            "If you recently switched CRDT backends, stale clients may be sending incompatible data.",
         )
       }
       // Stash origin for the event bridge to pick up
-      pendingImportOrigin = origin
+      pendingMergeOrigin = origin
       try {
         Y.applyUpdate(doc, payload.data, origin ?? "remote")
       } finally {
-        pendingImportOrigin = undefined
+        pendingMergeOrigin = undefined
       }
       // That's it — the observeDeep handler bridges events to the
       // changefeed via executeBatch.
@@ -180,13 +185,11 @@ export function createYjsSubstrate(
       return
     }
 
-    // Determine origin: prefer stashed kyneta origin (from importDelta),
+    // Determine origin: prefer stashed kyneta origin (from merge),
     // fall back to the transaction's origin if it's a string.
     const origin =
-      pendingImportOrigin ??
-      (typeof transaction.origin === "string"
-        ? transaction.origin
-        : undefined)
+      pendingMergeOrigin ??
+      (typeof transaction.origin === "string" ? transaction.origin : undefined)
 
     // Lazily ensure the context is built
     const ctx = substrate.context()
@@ -202,10 +205,7 @@ export function createYjsSubstrate(
     }
   })
 
-  // Register for the yjs() escape hatch
-  registerYjsSubstrate(substrate, doc)
-
-  return substrate
+  return substrate as Substrate<YjsVersion>
 }
 
 // ---------------------------------------------------------------------------
@@ -218,35 +218,134 @@ export function createYjsSubstrate(
  * - `create(schema)` — creates a fresh Y.Doc with empty containers
  *   matching the schema structure. No seed data — initial content
  *   should be applied via `change()` after construction.
- * - `fromSnapshot(payload, schema)` — creates a Y.Doc from a snapshot
+ * - `fromEntirety(payload, schema)` — creates a Y.Doc from an entirety
  *   payload, returns a substrate.
  * - `parseVersion(serialized)` — deserializes a YjsVersion.
  */
-export const yjsSubstrateFactory: SubstrateFactory<YjsVersion> = {
-  create(schema: SchemaNode): Substrate<YjsVersion> {
-    const doc = new Y.Doc()
-    ensureContainers(doc, schema)
-    return createYjsSubstrate(doc, schema)
+// ---------------------------------------------------------------------------
+// yjsReplicaFactory — ReplicaFactory<YjsVersion>
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema-free replica factory for Yjs substrates.
+ *
+ * Constructs headless `Replica<YjsVersion>` instances backed by bare
+ * `Y.Doc`s — no schema walking, no container initialization, no
+ * Reader, no event bridge, no changefeed. Just the CRDT runtime
+ * with version tracking and export/merge.
+ *
+ * Used by conduit participants (stores, routing servers)
+ * that need to accumulate state, compute per-peer deltas, and compact
+ * storage without ever interpreting document fields.
+ */
+export function createYjsReplica(doc: Y.Doc): Replica<YjsVersion> {
+  return {
+    [BACKING_DOC]: doc,
+
+    version(): YjsVersion {
+      return new YjsVersion(Y.encodeStateVector(doc))
+    },
+
+    exportEntirety(): SubstratePayload {
+      return {
+        kind: "entirety",
+        encoding: "binary",
+        data: Y.encodeStateAsUpdate(doc),
+      }
+    },
+
+    exportSince(since: YjsVersion): SubstratePayload | null {
+      try {
+        const bytes = Y.encodeStateAsUpdate(doc, since.sv)
+        return { kind: "since", encoding: "binary", data: bytes }
+      } catch {
+        return null
+      }
+    },
+
+    merge(payload: SubstratePayload, _origin?: string): void {
+      if (
+        payload.encoding !== "binary" ||
+        !(payload.data instanceof Uint8Array)
+      ) {
+        throw new Error(
+          "YjsReplica.merge expects binary-encoded payloads. " +
+            "If you recently switched CRDT backends, stale clients may be sending incompatible data.",
+        )
+      }
+      Y.applyUpdate(doc, payload.data)
+    },
+  } as Replica<YjsVersion>
+}
+
+export const yjsReplicaFactory: ReplicaFactory<YjsVersion> = {
+  replicaType: ["yjs", 1, 0] as const,
+
+  createEmpty(): Replica<YjsVersion> {
+    return createYjsReplica(new Y.Doc())
   },
 
-  fromSnapshot(
-    payload: SubstratePayload,
-    schema: SchemaNode,
-  ): Substrate<YjsVersion> {
+  fromEntirety(payload: SubstratePayload): Replica<YjsVersion> {
     if (
       payload.encoding !== "binary" ||
       !(payload.data instanceof Uint8Array)
     ) {
       throw new Error(
-        "YjsSubstrateFactory.fromSnapshot only supports binary-encoded payloads",
+        "YjsReplicaFactory.fromEntirety only supports binary-encoded payloads",
       )
     }
     const doc = new Y.Doc()
     Y.applyUpdate(doc, payload.data)
+    return createYjsReplica(doc)
+  },
+
+  parseVersion(serialized: string): YjsVersion {
+    return YjsVersion.parse(serialized)
+  },
+}
+
+// ---------------------------------------------------------------------------
+// yjsSubstrateFactory — SubstrateFactory<YjsVersion>
+// ---------------------------------------------------------------------------
+
+export const yjsSubstrateFactory: SubstrateFactory<YjsVersion> = {
+  replica: yjsReplicaFactory,
+
+  createReplica(): Replica<YjsVersion> {
+    // Default random clientID — safe for hydration (no local writes).
+    return createYjsReplica(new Y.Doc())
+  },
+
+  upgrade(
+    replica: Replica<YjsVersion>,
+    schema: SchemaNode,
+  ): Substrate<YjsVersion> {
+    const doc = (replica as any)[BACKING_DOC] as Y.Doc
+    // No identity injection for the standalone factory (no peerId).
+    // Conditional ensureContainers: skip fields that already exist
+    // from hydrated state.
+    ensureContainers(doc, schema, true)
     return createYjsSubstrate(doc, schema)
   },
 
+  create(schema: SchemaNode): Substrate<YjsVersion> {
+    // Fresh doc — unconditional ensureContainers (nothing to conflict with).
+    const doc = new Y.Doc()
+    ensureContainers(doc, schema)
+    return createYjsSubstrate(doc, schema)
+  },
+
+  fromEntirety(
+    payload: SubstratePayload,
+    schema: SchemaNode,
+  ): Substrate<YjsVersion> {
+    // Two-phase path: createReplica → merge → upgrade
+    const replica = this.createReplica()
+    replica.merge(payload)
+    return this.upgrade(replica, schema)
+  },
+
   parseVersion(serialized: string): YjsVersion {
     return YjsVersion.parse(serialized)
   },
-}
+}

package/src/sync.ts

@@ -1,17 +1,17 @@
 // sync — sync primitives for YjsSubstrate-backed documents.
 //
-// These functions provide version tracking, snapshot export, and delta
-// import for documents created via `createYjsDoc` or
-// `createYjsDocFromSnapshot`. They discover the substrate via the
+// These functions provide version tracking, entirety export, and merge
+// for documents created via `createYjsDoc` or
+// `createYjsDocFromEntirety`. They discover the substrate via the
 // module-scoped WeakMap in `create.ts`.
 //
 // Unlike PlainSubstrate's sync (which returns Op[] for deltas),
-// YjsSubstrate's sync uses binary SubstratePayload for both snapshots
+// YjsSubstrate's sync uses binary SubstratePayload for both entireties
 // and deltas — these are Yjs's native state-as-update bytes.
 
 import type { SubstratePayload } from "@kyneta/schema"
-import { YjsVersion } from "./version.js"
 import { getSubstrate } from "./create.js"
+import type { YjsVersion } from "./version.js"
 
 // ---------------------------------------------------------------------------
 // version — current YjsVersion
@@ -23,28 +23,28 @@ import { getSubstrate } from "./create.js"
  * Use `.serialize()` to get a text-safe string for embedding in HTML
  * meta tags, URL parameters, etc.
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
 export function version(doc: object): YjsVersion {
   return getSubstrate(doc).version()
 }
 
 // ---------------------------------------------------------------------------
-// exportSnapshot — full state for reconstruction
+// exportEntirety — full state for reconstruction
 // ---------------------------------------------------------------------------
 
 /**
- * Export the full substrate snapshot — sufficient for a new peer to
- * reconstruct an equivalent document via `createYjsDocFromSnapshot()`.
+ * Export the full substrate entirety — sufficient for a new peer to
+ * reconstruct an equivalent document via `createYjsDocFromEntirety()`.
  *
  * Returns a binary `SubstratePayload` (Yjs state-as-update bytes).
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
-export function exportSnapshot(doc: object): SubstratePayload {
-  return getSubstrate(doc).exportSnapshot()
+export function exportEntirety(doc: object): SubstratePayload {
+  return getSubstrate(doc).exportEntirety()
 }
 
 // ---------------------------------------------------------------------------
@@ -61,12 +61,12 @@ export function exportSnapshot(doc: object): SubstratePayload {
  * const v0 = version(docA)
  * change(docA, d => d.title.insert(0, "Hi"))
  * const delta = exportSince(docA, v0)
- * importDelta(docB, delta!)
+ * merge(docB, delta!)
  * ```
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
  * @param since - The version to diff from.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
 export function exportSince(
   doc: object,
@@ -76,32 +76,32 @@ export function exportSince(
 }
 
 // ---------------------------------------------------------------------------
-// importDelta — apply a delta from another peer
+// merge — apply a delta from another peer
 // ---------------------------------------------------------------------------
 
 /**
  * Import a delta payload into a live document.
  *
  * The payload must have been produced by `exportSince()` or
- * `exportSnapshot()` on a compatible document.
+ * `exportEntirety()` on a compatible document.
  *
  * After import, the changefeed fires for all subscribers — the event
  * bridge handles this automatically.
  *
  * ```ts
  * const delta = exportSince(docA, sinceVersion)
- * importDelta(docB, delta!, "sync")
+ * merge(docB, delta!, "sync")
  * ```
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @param payload - The delta or snapshot payload to import.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @param payload - The delta or entirety payload to merge.
  * @param origin - Optional provenance tag for the changeset.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
-export function importDelta(
+export function merge(
   doc: object,
   payload: SubstratePayload,
   origin?: string,
 ): void {
-  getSubstrate(doc).importDelta(payload, origin)
-}
+  getSubstrate(doc).merge(payload, origin)
+}

package/src/version.ts

@@ -85,9 +85,7 @@ export class YjsVersion implements Version {
    */
   compare(other: Version): "behind" | "equal" | "ahead" | "concurrent" {
     if (!(other instanceof YjsVersion)) {
-      throw new Error(
-        "YjsVersion can only be compared with another YjsVersion",
-      )
+      throw new Error("YjsVersion can only be compared with another YjsVersion")
     }
 
     const thisMap = decodeStateVector(this.sv)
@@ -135,4 +133,4 @@ export class YjsVersion implements Version {
     const bytes = base64ToUint8Array(serialized)
     return new YjsVersion(bytes)
   }
-}
+}

package/src/yjs-escape.ts

@@ -3,15 +3,16 @@
 //
 // `yjs(ref)` returns the `Y.Doc` backing a root document ref.
 //
-// The mapping is maintained via a WeakMap from Substrate → Y.Doc,
-// populated by `registerYjsSubstrate()` (called during substrate
-// creation). The `yjs()` function uses `unwrap()` from `@kyneta/schema`
-// to get the substrate, then looks up the Y.Doc.
+// The substrate exposes its backing Y.Doc via the `BACKING_DOC` symbol
+// (from `@kyneta/schema`). The `yjs()` function uses `unwrap()` to get
+// the substrate, then reads `[BACKING_DOC]` to get the Y.Doc.
 //
 // This two-step approach (ref → substrate → Y.Doc) avoids duplicating
 // the ref-tracking WeakMap and composes cleanly with the general
 // `unwrap()` escape hatch.
 //
+// Context: jj:smmulzkm (BACKING_DOC replaces WeakMap + registerYjsSubstrate)
+//
 // Usage:
 //   import { yjs } from "@kyneta/yjs-schema"
 //
@@ -19,33 +20,8 @@
 //   const yjsDoc = yjs(doc)  // Y.Doc
 //   yjsDoc.getMap("root").toJSON()  // raw Yjs inspection
 
+import { BACKING_DOC, unwrap } from "@kyneta/schema"
 import type { Doc as YDoc } from "yjs"
-import type { Substrate } from "@kyneta/schema"
-import { unwrap } from "@kyneta/schema"
-
-// ---------------------------------------------------------------------------
-// Substrate → Y.Doc mapping
-// ---------------------------------------------------------------------------
-
-const substrateToYjsDoc = new WeakMap<Substrate<any>, YDoc>()
-
-// ---------------------------------------------------------------------------
-// registerYjsSubstrate — called during substrate creation
-// ---------------------------------------------------------------------------
-
-/**
- * Register the Y.Doc backing a Yjs substrate.
- *
- * Called by `createYjsSubstrate()` and by `bindYjs`'s factory builder
- * to enable the `yjs()` escape hatch. Must be called once per substrate
- * at construction time.
- */
-export function registerYjsSubstrate(
-  substrate: Substrate<any>,
-  doc: YDoc,
-): void {
-  substrateToYjsDoc.set(substrate, doc)
-}
 
 // ---------------------------------------------------------------------------
 // yjs — Yjs-specific escape hatch
@@ -77,7 +53,7 @@ export function registerYjsSubstrate(
  * ```
  */
 export function yjs(ref: object): YDoc {
-  let substrate: Substrate<any>
+  let substrate: any
   try {
     substrate = unwrap(ref)
   } catch {
@@ -88,13 +64,21 @@ export function yjs(ref: object): YDoc {
     )
   }
 
-  const doc = substrateToYjsDoc.get(substrate)
-  if (!doc) {
+  const doc = substrate[BACKING_DOC]
+  // Duck-type check: Y.Doc has getMap, encodeStateVector-compatible API,
+  // and a numeric clientID. A PlainState (plain object) or LoroDoc would
+  // not have getMap as a function.
+  if (
+    !doc ||
+    typeof doc !== "object" ||
+    typeof (doc as any).getMap !== "function" ||
+    typeof (doc as any).clientID !== "number"
+  ) {
     throw new Error(
       "yjs() requires a ref backed by a Yjs substrate. " +
         "The ref has a substrate but it is not a Yjs substrate. " +
         "Use a doc created with a bindYjs() schema or createYjsDoc().",
     )
   }
-  return doc
-}
+  return doc as YDoc
+}

package/src/yjs-resolve.ts

@@ -14,9 +14,8 @@
 // Using a single root Y.Map enables one `observeDeep` call that
 // captures all mutations with correct relative paths.
 
+import type { Path, Schema as SchemaNode, Segment } from "@kyneta/schema"
 import { advanceSchema } from "@kyneta/schema"
-import type { Path, Segment } from "@kyneta/schema"
-import type { Schema as SchemaNode } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -35,10 +34,7 @@ import * as Y from "yjs"
  * @param current - The current position (a Yjs shared type or plain value)
  * @param segment - The path segment to follow
  */
-export function stepIntoYjs(
-  current: unknown,
-  segment: Segment,
-): unknown {
+export function stepIntoYjs(current: unknown, segment: Segment): unknown {
   const resolved = segment.resolve()
 
   if (current instanceof Y.Map) {
@@ -50,9 +46,7 @@ export function stepIntoYjs(
   }
 
   if (current instanceof Y.Text) {
-    throw new Error(
-      `yjs-resolve: cannot step into Y.Text`,
-    )
+    throw new Error(`yjs-resolve: cannot step into Y.Text`)
   }
 
   // Plain value — terminal, cannot step further
@@ -105,4 +99,4 @@ export function resolveYjsType(
   }
 
   return current
-}
+}