@kyneta/yjs-schema 1.0.0 → 1.1.0

package/src/bind-yjs.ts

@@ -19,18 +19,23 @@
 //
 //   const doc = exchange.get("my-doc", TodoDoc)
 
-import { bind } from "@kyneta/schema"
-import type { BoundSchema } from "@kyneta/schema"
-import type { Schema as SchemaNode } from "@kyneta/schema"
 import type {
+  BoundSchema,
+  Replica,
+  Schema as SchemaNode,
   Substrate,
   SubstrateFactory,
   SubstratePayload,
 } from "@kyneta/schema"
+import { BACKING_DOC, bind, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
 import * as Y from "yjs"
-import { createYjsSubstrate } from "./substrate.js"
-import { YjsVersion } from "./version.js"
 import { ensureContainers } from "./populate.js"
+import {
+  createYjsReplica,
+  createYjsSubstrate,
+  yjsReplicaFactory,
+} from "./substrate.js"
+import { YjsVersion } from "./version.js"
 
 // ---------------------------------------------------------------------------
 // Peer ID hashing — deterministic string → numeric Yjs clientID
@@ -55,7 +60,9 @@ function hashPeerId(peerId: string): number {
     hash = Math.imul(hash, 0x01000193)
   }
   // Ensure unsigned 32-bit integer
-  return hash >>> 0
+  const result = hash >>> 0
+  // Reserve 0 for structural ops — real peers never collide
+  return result === STRUCTURAL_YJS_CLIENT_ID ? 1 : result
 }
 
 // ---------------------------------------------------------------------------
@@ -67,36 +74,50 @@ function hashPeerId(peerId: string): number {
  * on every new Y.Doc with a deterministic uint32 clientID derived
  * from the exchange's string peerId.
  */
-function createYjsFactory(
-  peerId: string,
-): SubstrateFactory<YjsVersion> {
+function createYjsFactory(peerId: string): SubstrateFactory<YjsVersion> {
   const numericClientId = hashPeerId(peerId)
 
   return {
+    replica: yjsReplicaFactory,
+
+    createReplica(): Replica<YjsVersion> {
+      // Default random clientID — safe for hydration (no local writes).
+      // Identity is set at upgrade() time, after hydration.
+      return createYjsReplica(new Y.Doc())
+    },
+
+    upgrade(
+      replica: Replica<YjsVersion>,
+      schema: SchemaNode,
+    ): Substrate<YjsVersion> {
+      const doc = (replica as any)[BACKING_DOC] as Y.Doc
+      // Set stable identity AFTER hydration — avoids Yjs clientID
+      // conflict detection that would reassign to a random value.
+      doc.clientID = numericClientId
+      // Conditional ensureContainers: skip fields that already exist
+      // from hydrated state (each set() is a CRDT write).
+      ensureContainers(doc, schema, true)
+      return createYjsSubstrate(doc, schema)
+    },
+
     create(schema: SchemaNode): Substrate<YjsVersion> {
+      // Fresh doc — set identity immediately, unconditional containers.
       const doc = new Y.Doc()
       doc.clientID = numericClientId
-
       ensureContainers(doc, schema)
       return createYjsSubstrate(doc, schema)
     },
 
-    fromSnapshot(
+    fromEntirety(
       payload: SubstratePayload,
       schema: SchemaNode,
     ): Substrate<YjsVersion> {
-      if (
-        payload.encoding !== "binary" ||
-        !(payload.data instanceof Uint8Array)
-      ) {
-        throw new Error(
-          "YjsSubstrateFactory.fromSnapshot only supports binary-encoded payloads",
-        )
-      }
-      const doc = new Y.Doc()
-      doc.clientID = numericClientId
-      Y.applyUpdate(doc, payload.data)
-      return createYjsSubstrate(doc, schema)
+      // Two-phase path: createReplica → merge → upgrade
+      // Identity is set at upgrade() time, after hydration —
+      // avoids Yjs clientID conflict detection.
+      const replica = this.createReplica()
+      replica.merge(payload)
+      return this.upgrade(replica, schema)
     },
 
     parseVersion(serialized: string): YjsVersion {
@@ -141,7 +162,7 @@ function createYjsFactory(
 export function bindYjs<S extends SchemaNode>(schema: S): BoundSchema<S> {
   return bind({
     schema,
-    factory: (ctx) => createYjsFactory(ctx.peerId),
+    factory: ctx => createYjsFactory(ctx.peerId),
     strategy: "causal",
   })
-}
+}

package/src/change-mapping.ts

@@ -16,7 +16,6 @@
 // This produces a single observeDeep event with the complete struct,
 // rather than a cascade of child MapChange events.
 
-import { advanceSchema, expandMapOpsToLeaves } from "@kyneta/schema"
 import type {
   ChangeBase,
   IncrementChange,
@@ -30,7 +29,7 @@ import type {
   TextChange,
   TextInstruction,
 } from "@kyneta/schema"
-import { RawPath } from "@kyneta/schema"
+import { advanceSchema, expandMapOpsToLeaves, RawPath } from "@kyneta/schema"
 import * as Y from "yjs"
 import { resolveYjsType } from "./yjs-resolve.js"
 
@@ -146,7 +145,7 @@ function applySequenceChange(
       // cursor stays — deleted items shift remaining items down
     } else if ("insert" in instruction) {
       const items = instruction.insert as readonly unknown[]
-      const yjsItems = items.map((item) =>
+      const yjsItems = items.map(item =>
         maybeCreateSharedType(item, itemSchema),
       )
       resolved.insert(cursor, yjsItems)
@@ -265,9 +264,7 @@ function maybeCreateSharedType(
 
   // Annotated counter/movable/tree → should not reach here (thrown earlier)
   if (tag === "counter" || tag === "movable" || tag === "tree") {
-    throw new Error(
-      `Yjs substrate does not support "${tag}" annotations.`,
-    )
+    throw new Error(`Yjs substrate does not support "${tag}" annotations.`)
   }
 
   switch (structural._kind) {
@@ -280,17 +277,14 @@ function maybeCreateSharedType(
       ) {
         return value
       }
-      return createStructuredMap(
-        value as Record<string, unknown>,
-        structural,
-      )
+      return createStructuredMap(value as Record<string, unknown>, structural)
     }
 
     case "sequence": {
       if (!Array.isArray(value)) return value
       const arr = new Y.Array()
       const itemSchema = structural.item
-      const items = (value as unknown[]).map((item) =>
+      const items = (value as unknown[]).map(item =>
         maybeCreateSharedType(item, itemSchema),
       )
       arr.insert(0, items)
@@ -308,9 +302,7 @@ function maybeCreateSharedType(
       }
       const map = new Y.Map()
       const valueSchema = structural.item
-      for (const [k, v] of Object.entries(
-        value as Record<string, unknown>,
-      )) {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
         map.set(k, maybeCreateSharedType(v, valueSchema))
       }
       return map
@@ -348,9 +340,7 @@ function createStructuredMap(
   for (const [key, val] of Object.entries(obj)) {
     if (val === undefined) continue
     const fieldSchema = structural.fields[key]
-    const yjsVal = fieldSchema
-      ? maybeCreateSharedType(val, fieldSchema)
-      : val
+    const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val
     map.set(key, yjsVal)
   }
 
@@ -362,8 +352,7 @@ function createStructuredMap(
     structural.fields as Record<string, SchemaNode>,
   )) {
     if (key in obj) continue // already processed above
-    const tag =
-      fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
+    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
     if (tag === "text") {
       map.set(key, new Y.Text())
     }
@@ -512,18 +501,16 @@ function mapEventToChange(event: Y.YEvent<any>): MapChange | null {
 
   const target = event.target as Y.Map<any>
 
-  event.changes.keys.forEach(
-    (change: { action: string }, key: string) => {
-      if (change.action === "add" || change.action === "update") {
-        const value = target.get(key)
-        set[key] = extractEventValue(value)
-        hasSet = true
-      } else if (change.action === "delete") {
-        deleteKeys.push(key)
-        hasDelete = true
-      }
-    },
-  )
+  event.changes.keys.forEach((change: { action: string }, key: string) => {
+    if (change.action === "add" || change.action === "update") {
+      const value = target.get(key)
+      set[key] = extractEventValue(value)
+      hasSet = true
+    } else if (change.action === "delete") {
+      deleteKeys.push(key)
+      hasDelete = true
+    }
+  })
 
   if (!hasSet && !hasDelete) return null
 
@@ -606,7 +593,5 @@ function getFieldSchema(
 // ---------------------------------------------------------------------------
 
 function pathToString(path: Path): string {
-  return path.segments
-    .map((seg) => String(seg.resolve()))
-    .join(".")
-}
+  return path.segments.map(seg => String(seg.resolve())).join(".")
+}

package/src/create.ts

@@ -1,10 +1,10 @@
 // create — batteries-included document construction backed by YjsSubstrate.
 //
-// Provides `createYjsDoc` and `createYjsDocFromSnapshot` functions that
+// Provides `createYjsDoc` and `createYjsDocFromEntirety` functions that
 // hide the interpret pipeline and layer composition behind a single call.
 //
 // Internally tracks substrates via a module-scoped WeakMap so that sync
-// primitives (`version`, `exportSnapshot`, `importDelta` in sync.ts)
+// primitives (`version`, `exportEntirety`, `merge` in sync.ts)
 // can retrieve the substrate from just a doc ref.
 //
 // `getSubstrate` is exported for use by `sync.ts` but is NOT re-exported
@@ -14,14 +14,22 @@
 //   createYjsDoc(schema, yjsDoc)    — "bring your own doc" (wrap existing)
 //   createYjsDoc(schema)            — create a fresh empty Y.Doc
 
-import { interpret, registerSubstrate } from "@kyneta/schema"
-import { changefeed, readable, writable } from "@kyneta/schema"
-import type { Ref } from "@kyneta/schema"
-import type { Schema as SchemaType } from "@kyneta/schema"
-import type { Substrate, SubstratePayload } from "@kyneta/schema"
-import * as Y from "yjs"
-import { YjsVersion } from "./version.js"
+import type {
+  Ref,
+  Schema as SchemaType,
+  Substrate,
+  SubstratePayload,
+} from "@kyneta/schema"
+import {
+  changefeed,
+  interpret,
+  readable,
+  registerSubstrate,
+  writable,
+} from "@kyneta/schema"
+import type * as Y from "yjs"
 import { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
+import type { YjsVersion } from "./version.js"
 
 // ---------------------------------------------------------------------------
 // Substrate tracking (module-scoped)
@@ -31,18 +39,18 @@ const substrates = new WeakMap<object, Substrate<YjsVersion>>()
 
 /**
  * Retrieve the substrate associated with a doc created by `createYjsDoc`
- * or `createYjsDocFromSnapshot`.
+ * or `createYjsDocFromEntirety`.
  *
  * Exported for `sync.ts` — NOT re-exported from the barrel.
  *
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
 export function getSubstrate(doc: object): Substrate<YjsVersion> {
   const s = substrates.get(doc)
   if (!s) {
     throw new Error(
-      "version/exportSnapshot/importDelta called on an object without a YjsSubstrate. " +
-        "Use a doc created by createYjsDoc() or createYjsDocFromSnapshot().",
+      "version/exportEntirety/merge called on an object without a YjsSubstrate. " +
+        "Use a doc created by createYjsDoc() or createYjsDocFromEntirety().",
     )
   }
   return s
@@ -58,7 +66,7 @@ function registerDoc(
 ): any {
   // The `as any` on the builder avoids TS2589 — interpret's fluent API
   // produces deeply recursive types when S is the abstract SchemaType.
-  // The public createYjsDoc/createYjsDocFromSnapshot signatures provide
+  // The public createYjsDoc/createYjsDocFromEntirety signatures provide
   // the correct Ref<S> return type via interface call signature patterns.
   const doc: any = (interpret as any)(schema, substrate.context())
     .with(readable)
@@ -123,17 +131,14 @@ function isYDoc(value: unknown): value is Y.Doc {
  * CRDT collaboration support.
  *
  * The returned ref observes **all** mutations to the underlying Y.Doc,
- * regardless of source (local kyneta writes, importDelta, external
+ * regardless of source (local kyneta writes, merge, external
  * `Y.applyUpdate()`, external raw Yjs API mutations).
  *
  * @param schema - The schema describing the document structure.
  * @param doc - Optional `Y.Doc` instance to wrap. If omitted, a fresh
  *   empty Y.Doc is created with containers matching the schema.
  */
-type CreateYjsDoc = <S extends SchemaType>(
-  schema: S,
-  doc?: Y.Doc,
-) => Ref<S>
+type CreateYjsDoc = <S extends SchemaType>(schema: S, doc?: Y.Doc) => Ref<S>
 
 export const createYjsDoc: CreateYjsDoc = (schema, doc) => {
   if (doc !== undefined && isYDoc(doc)) {
@@ -145,28 +150,28 @@ export const createYjsDoc: CreateYjsDoc = (schema, doc) => {
 }
 
 // ---------------------------------------------------------------------------
-// createYjsDocFromSnapshot
+// createYjsDocFromEntirety
 // ---------------------------------------------------------------------------
 
-type CreateYjsDocFromSnapshot = <S extends SchemaType>(
+type CreateYjsDocFromEntirety = <S extends SchemaType>(
   schema: S,
   payload: SubstratePayload,
 ) => Ref<S>
 
 /**
- * Reconstruct a live Yjs-backed document from a substrate snapshot payload.
+ * Reconstruct a live Yjs-backed document from a substrate entirety payload.
  *
- * The payload must have been produced by `exportSnapshot()` on a
+ * The payload must have been produced by `exportEntirety()` on a
  * compatible document. This is the entry point for SSR hydration
  * and reconnection past log compaction.
  *
  * ```ts
- * const payload = exportSnapshot(docA)
- * const docB = createYjsDocFromSnapshot(MySchema, payload)
+ * const payload = exportEntirety(docA)
+ * const docB = createYjsDocFromEntirety(MySchema, payload)
  * // docB has the same state as docA at the time of export
  * ```
  */
-export const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot = (
+export const createYjsDocFromEntirety: CreateYjsDocFromEntirety = (
   schema,
   payload,
-) => registerDoc(schema, yjsSubstrateFactory.fromSnapshot(payload, schema))
+) => registerDoc(schema, yjsSubstrateFactory.fromEntirety(payload, schema))

package/src/index.ts

@@ -4,35 +4,36 @@
 // with schema-aware typed reads, writes, versioning, and export/import.
 //
 // Batteries-included API (most users):
-//   createYjsDoc, createYjsDocFromSnapshot, version, exportSnapshot,
-//   exportSince, importDelta, change, subscribe, applyChanges
+//   createYjsDoc, createYjsDocFromEntirety, version, exportEntirety,
+//   exportSince, merge, change, subscribe, applyChanges
 //
 // Low-level primitives (power users):
-//   createYjsSubstrate, yjsSubstrateFactory, yjsStoreReader,
+//   createYjsSubstrate, yjsSubstrateFactory, yjsReader,
 //   resolveYjsType, stepIntoYjs, applyChangeToYjs, eventsToOps, YjsVersion
 
 // ---------------------------------------------------------------------------
 // Batteries-included API — one import, one createYjsDoc call, done
 // ---------------------------------------------------------------------------
 
+// Mutation & observation (re-exported from @kyneta/schema for convenience)
+// Schema definition (re-exported for convenience)
+export {
+  applyChanges,
+  change,
+  Schema,
+  subscribe,
+  subscribeNode,
+} from "@kyneta/schema"
 // Construction
-export { createYjsDoc, createYjsDocFromSnapshot } from "./create.js"
-
+export { createYjsDoc, createYjsDocFromEntirety } from "./create.js"
 // Sync primitives (Yjs-specific)
 export {
+  exportEntirety,
   exportSince,
-  exportSnapshot,
-  importDelta,
+  merge,
   version,
 } from "./sync.js"
 
-// Mutation & observation (re-exported from @kyneta/schema for convenience)
-export { applyChanges, change } from "@kyneta/schema"
-export { subscribe, subscribeNode } from "@kyneta/schema"
-
-// Schema definition (re-exported for convenience)
-export { Schema } from "@kyneta/schema"
-
 // Text annotation convenience — so users don't need LoroSchema just for text()
 import type { AnnotatedSchema } from "@kyneta/schema"
 import { Schema } from "@kyneta/schema"
@@ -58,26 +59,19 @@ export type { Changeset, Op, Ref, SubstratePayload } from "@kyneta/schema"
 // Low-level primitives — for power users and custom substrate compositions
 // ---------------------------------------------------------------------------
 
-// Version
-export { YjsVersion } from "./version.js"
-
-// Store reader
-export { yjsStoreReader } from "./store-reader.js"
-
-// Container resolution
-export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"
-
+// Bind — convenience wrapper for Yjs CRDT substrate
+export { bindYjs } from "./bind-yjs.js"
 // Change mapping
 export { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
-
 // Container creation
 export { ensureContainers } from "./populate.js"
-
+// Reader
+export { yjsReader } from "./reader.js"
 // Substrate
 export { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
-
-// Bind — convenience wrapper for Yjs CRDT substrate
-export { bindYjs } from "./bind-yjs.js"
-
+// Version
+export { YjsVersion } from "./version.js"
 // Escape hatch — access the underlying Y.Doc from a ref
-export { yjs } from "./yjs-escape.js"
+export { yjs } from "./yjs-escape.js"
+// Container resolution
+export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"

package/src/populate.ts

@@ -15,7 +15,7 @@
 // shared types (Y.Text, Y.Array, Y.Map) and plain value slots uniformly.
 
 import type { Schema as SchemaNode } from "@kyneta/schema"
-import { Zero } from "@kyneta/schema"
+import { STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -30,14 +30,30 @@ import * as Y from "yjs"
  * schema, and creates empty containers for each field within a single
  * `doc.transact()` call for atomicity.
  *
- * No values are written — the containers are empty after this call.
- * Initial content should be applied via `change()` after substrate
- * construction.
+ * When `conditional` is true, fields that already exist in the root map
+ * are skipped. This is the correct mode after hydration — containers
+ * present from stored state must not be overwritten (each `rootMap.set()`
+ * is a CRDT write that advances the version vector and may conflict
+ * with stored operations).
+ *
+ * When `conditional` is false (default), all fields are created
+ * unconditionally. This is the correct mode for fresh documents.
+ *
+ * **Structural identity:** This function temporarily sets `doc.clientID`
+ * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
+ * then restores the caller's clientID. This produces byte-identical
+ * structural ops across all peers, enabling Yjs deduplication on merge.
  *
  * @param doc - The Y.Doc to prepare
  * @param schema - The root document schema (typically annotated("doc", product))
+ * @param conditional - If true, skip fields that already exist in the root map.
+ *   Context: jj:smmulzkm (two-phase substrate construction)
  */
-export function ensureContainers(doc: Y.Doc, schema: SchemaNode): void {
+export function ensureContainers(
+  doc: Y.Doc,
+  schema: SchemaNode,
+  conditional = false,
+): void {
   const rootMap = doc.getMap("root")
 
   let rootProduct = schema
@@ -52,11 +68,24 @@ export function ensureContainers(doc: Y.Doc, schema: SchemaNode): void {
     return
   }
 
-  doc.transact(() => {
-    for (const [key, fieldSchema] of Object.entries(rootProduct.fields)) {
-      ensureRootField(rootMap, key, fieldSchema as SchemaNode)
-    }
-  })
+  // Switch to structural identity for deterministic container creation.
+  // All peers produce byte-identical structural ops at clientID 0.
+  const savedClientID = doc.clientID
+  doc.clientID = STRUCTURAL_YJS_CLIENT_ID
+
+  try {
+    doc.transact(() => {
+      for (const [key, fieldSchema] of Object.entries(rootProduct.fields).sort(
+        ([a], [b]) => a.localeCompare(b),
+      )) {
+        if (conditional && rootMap.has(key)) continue
+        ensureRootField(rootMap, key, fieldSchema as SchemaNode)
+      }
+    })
+  } finally {
+    // Restore the caller's identity for application writes.
+    doc.clientID = savedClientID
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -157,9 +186,8 @@ function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
 
   for (const [key, fieldSchema] of Object.entries(
     structural.fields as Record<string, SchemaNode>,
-  )) {
-    const tag =
-      fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
+  ).sort(([a], [b]) => a.localeCompare(b))) {
+    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
 
     if (tag === "text") {
       map.set(key, new Y.Text())
@@ -205,4 +233,4 @@ function unwrapAnnotations(schema: SchemaNode): SchemaNode {
     s = s.schema
   }
   return s
-}
+}

package/src/{store-reader.ts → reader.ts}

@@ -1,6 +1,6 @@
-// store-reader — YjsStoreReader implementation.
+// store-reader — YjsReader implementation.
 //
-// Implements StoreReader via schema-guided live navigation of the
+// Implements Reader via schema-guided live navigation of the
 // Yjs shared type tree. Each read operation resolves the shared type
 // at the given path using resolveYjsType, then extracts the
 // appropriate value based on `instanceof` discrimination.
@@ -8,9 +8,7 @@
 // Y.Text → .toJSON() (string), Y.Map → .toJSON() (plain object),
 // Y.Array → .toJSON() (plain array), plain values → as-is.
 
-import type { StoreReader } from "@kyneta/schema"
-import type { Path } from "@kyneta/schema"
-import type { Schema as SchemaNode } from "@kyneta/schema"
+import type { Path, Reader, Schema as SchemaNode } from "@kyneta/schema"
 import * as Y from "yjs"
 import { resolveYjsType } from "./yjs-resolve.js"
 
@@ -41,11 +39,11 @@ function extractValue(resolved: unknown): unknown {
 }
 
 // ---------------------------------------------------------------------------
-// yjsStoreReader
+// yjsReader
 // ---------------------------------------------------------------------------
 
 /**
- * Creates a StoreReader that navigates the Yjs shared type tree live,
+ * Creates a Reader that navigates the Yjs shared type tree live,
  * using the schema as a type witness to determine navigation at each
  * path segment.
  *
@@ -58,10 +56,7 @@ function extractValue(resolved: unknown): unknown {
  * @param doc - The Y.Doc to read from.
  * @param schema - The root schema for the document.
  */
-export function yjsStoreReader(
-  doc: Y.Doc,
-  schema: SchemaNode,
-): StoreReader {
+export function yjsReader(doc: Y.Doc, schema: SchemaNode): Reader {
   const rootMap = doc.getMap("root")
 
   return {
@@ -120,4 +115,4 @@ export function yjsStoreReader(
       return false
     },
   }
-}
+}