@kyneta/yjs-schema 1.7.0 → 1.8.0

package/src/__tests__/eager-write-coherence.test.ts

@@ -0,0 +1,321 @@
+// eager-write-coherence — pins the post-Phase-3 contract for the Yjs
+// substrate's write path:
+//
+//   1. Re-entry: subscriber callbacks may freely `change()` the doc.
+//      Substrate writes land synchronously; both reads (σ via the
+//      Reader) AND subsequent writes (λ via applyChangeToYjs) succeed
+//      against the new state.
+//   2. Projection law: `σ ≡ Π(λ)` holds at every prepare boundary
+//      (asserted via deep-equal between the substrate's reader view
+//      and a fresh `materializeYjsShadow` after a non-trivial
+//      mutation sequence).
+//   3. Json-boundary storage: `struct.json` / `record.json` subtrees
+//      round-trip as plain JSON values in the parent Y.Map entry, not
+//      as nested Y.Map containers.
+//
+// Yjs doesn't need a nested-commit semantics test (4.7) because its
+// native `Y.transact` already collapses re-entrant nesting for free.
+
+import {
+  change,
+  interpret,
+  observation,
+  readable,
+  Schema,
+  subscribe,
+  unwrap,
+  writable,
+} from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
+import * as Y from "yjs"
+import { materializeYjsShadow } from "../materialize.js"
+import { ensureContainers } from "../populate.js"
+import { createYjsSubstrate, yjsSubstrateFactory } from "../substrate.js"
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+function build<S extends ReturnType<typeof Schema.struct>>(schema: S) {
+  const substrate = yjsSubstrateFactory.create(schema)
+  const doc = interpret(schema, substrate.context())
+    .with(readable)
+    .with(writable)
+    .with(observation)
+    .done() as any
+  return { substrate, doc }
+}
+
+// Unbound variant — bypasses the trivialBinding that identity-keys
+// product fields, so raw-name `materializeYjsShadow(doc, schema)` /
+// `rootMap.get(name)` calls in tests round-trip with the substrate.
+function buildUnbound<S extends ReturnType<typeof Schema.struct>>(schema: S) {
+  const doc = new Y.Doc()
+  ensureContainers(doc, schema)
+  const substrate = createYjsSubstrate(doc, schema)
+  const view = interpret(schema, substrate.context())
+    .with(readable)
+    .with(writable)
+    .with(observation)
+    .done() as any
+  return { substrate, doc: view }
+}
+
+// ---------------------------------------------------------------------------
+// 1. Re-entry — subscriber writes after subscriber push
+// ---------------------------------------------------------------------------
+
+describe("Yjs re-entry: subscriber writes after subscriber push", () => {
+  it("substrate-write timing: push then set inside the just-pushed item", () => {
+    const schema = Schema.struct({
+      events: Schema.list(
+        Schema.struct({ kind: Schema.string(), body: Schema.string() }),
+      ),
+    })
+    const { doc } = build(schema)
+
+    subscribe(doc.events, () => {
+      if ((doc.events as any).length !== 1) return
+      change(doc, (d: any) => {
+        d.events.push({ kind: "assistant", body: "" })
+      })
+      change(doc, (d: any) => {
+        d.events.at(1).body.set("hello")
+      })
+    })
+
+    expect(() => {
+      change(doc, (d: any) => {
+        d.events.push({ kind: "user", body: "hi" })
+      })
+    }).not.toThrow()
+
+    expect((doc.events as any).length).toBe(2)
+    expect((doc.events as any).at(1).body()).toBe("hello")
+  })
+
+  it("read-your-writes: re-entrant read inside subscriber sees just-pushed item", () => {
+    const schema = Schema.struct({
+      items: Schema.list(Schema.struct({ name: Schema.string() })),
+    })
+    const { doc } = build(schema)
+
+    let observed: string | undefined
+    subscribe(doc.items, () => {
+      if ((doc.items as any).length !== 1) return
+      change(doc, (d: any) => {
+        d.items.push({ name: "synthesised" })
+      })
+      observed = (doc.items as any).at(1).name()
+    })
+
+    change(doc, (d: any) => {
+      d.items.push({ name: "user" })
+    })
+
+    expect(observed).toBe("synthesised")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 2. Projection law σ ≡ Π(λ)
+// ---------------------------------------------------------------------------
+
+describe("Yjs projection law", () => {
+  it("shadow equals materialized projection of native doc after a mixed mutation sequence", () => {
+    const schema = Schema.struct({
+      title: Schema.text(),
+      items: Schema.list(
+        Schema.struct({ name: Schema.string(), done: Schema.boolean() }),
+      ),
+      meta: Schema.struct.json({
+        tags: Schema.string(),
+        version: Schema.number(),
+      }),
+      peers: Schema.record(Schema.boolean()),
+    })
+    const { doc } = buildUnbound(schema)
+
+    change(doc, (d: any) => {
+      d.title.insert(0, "Hello")
+      d.items.push({ name: "a", done: false })
+    })
+    change(doc, (d: any) => {
+      d.items.at(0).done.set(true)
+      d.items.push({ name: "b", done: false })
+    })
+    change(doc, (d: any) => {
+      d.meta.set({ tags: "kyneta", version: 2 })
+      d.peers.set("alice", true)
+      d.peers.set("bob", false)
+    })
+
+    const nativeDoc = unwrap(doc) as Y.Doc
+    const projected = materializeYjsShadow(nativeDoc, schema)
+    expect(projected).toEqual({
+      title: "Hello",
+      items: [
+        { name: "a", done: true },
+        { name: "b", done: false },
+      ],
+      meta: { tags: "kyneta", version: 2 },
+      peers: { alice: true, bob: false },
+    })
+    expect((doc.title as any)()).toBe("Hello")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// 3. JSON boundary: plain JS values in the parent Y.Map entry
+// ---------------------------------------------------------------------------
+
+describe("Yjs json-boundary storage", () => {
+  it("struct.json field stores a plain JS value at the parent boundary key", () => {
+    const schema = Schema.struct({
+      config: Schema.struct.json({
+        tags: Schema.string(),
+        retries: Schema.number(),
+      }),
+    })
+    const { doc } = build(schema)
+
+    change(doc, (d: any) => {
+      d.config.set({ tags: "ci", retries: 3 })
+    })
+    expect(doc.config()).toEqual({ tags: "ci", retries: 3 })
+
+    change(doc, (d: any) => {
+      d.config.tags.set("prod")
+    })
+    expect(doc.config()).toEqual({ tags: "prod", retries: 3 })
+
+    // Direct CRDT inspection: the boundary slot in the root Y.Map
+    // holds a plain JS object — NOT a Y.Map. Yjs Y.Map instances
+    // would respond to `instanceof Y.Map`.
+    const native = unwrap(doc) as Y.Doc
+    const rootMap = native.getMap("root")
+    const rootKeys: string[] = []
+    rootMap.forEach((_v, k) => {
+      rootKeys.push(k)
+    })
+    expect(rootKeys.length).toBe(1)
+    const key = rootKeys[0]
+    if (key === undefined) throw new Error("rootKeys[0] missing")
+    const value = rootMap.get(key)
+    expect(value).toEqual({ tags: "prod", retries: 3 })
+    expect(value instanceof Y.Map).toBe(false)
+  })
+
+  it("list.json items round-trip and replace cleanly on field-inside-item writes", () => {
+    const schema = Schema.struct({
+      todos: Schema.list.json(
+        Schema.struct({ title: Schema.string(), done: Schema.boolean() }),
+      ),
+    })
+    const { doc } = build(schema)
+
+    change(doc, (d: any) => {
+      d.todos.push({ title: "first", done: false })
+    })
+    change(doc, (d: any) => {
+      d.todos.push({ title: "second", done: false })
+    })
+    expect(doc.todos()).toEqual([
+      { title: "first", done: false },
+      { title: "second", done: false },
+    ])
+
+    change(doc, (d: any) => {
+      d.todos.at(0).done.set(true)
+    })
+    expect(doc.todos()).toEqual([
+      { title: "first", done: true },
+      { title: "second", done: false },
+    ])
+  })
+
+  it("record.json entries round-trip through the json-boundary path", () => {
+    const schema = Schema.struct({
+      profiles: Schema.record.json(Schema.struct({ email: Schema.string() })),
+    })
+    const { doc } = build(schema)
+
+    change(doc, (d: any) => {
+      d.profiles.set("alice", { email: "alice@example.com" })
+      d.profiles.set("bob", { email: "bob@example.com" })
+    })
+    expect(doc.profiles()).toEqual({
+      alice: { email: "alice@example.com" },
+      bob: { email: "bob@example.com" },
+    })
+
+    change(doc, (d: any) => {
+      d.profiles.at("alice").email.set("alice@new.example.com")
+    })
+    expect(doc.profiles()).toEqual({
+      alice: { email: "alice@new.example.com" },
+      bob: { email: "bob@example.com" },
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Three-primitive-substrate (jj:ryquprut): read-your-writes carries through
+// to Yjs; abort produces one batched native event with net-zero delta.
+// ---------------------------------------------------------------------------
+
+describe("Yjs three-primitive substrate (jj:ryquprut)", () => {
+  it("multi-push in one change() block appends in order against the CRDT", () => {
+    const schema = Schema.struct({
+      todos: Schema.list(Schema.string()),
+    })
+    const { doc } = build(schema)
+
+    change(doc, (d: any) => {
+      d.todos.push("a")
+      d.todos.push("b")
+      d.todos.push("c")
+    })
+
+    expect((doc.todos as any)()).toEqual(["a", "b", "c"])
+  })
+
+  it("abort restores state on outermost throw", () => {
+    const schema = Schema.struct({
+      a: Schema.string(),
+      b: Schema.string(),
+    })
+    const { doc } = build(schema)
+
+    expect(() => {
+      change(doc, (d: any) => {
+        d.a.set("set-a")
+        d.b.set("set-b")
+        throw new Error("abort")
+      })
+    }).toThrow("abort")
+
+    expect((doc.a as any)()).toBe("")
+    expect((doc.b as any)()).toBe("")
+  })
+
+  it("abort fires one Changeset with aborted: true on the Yjs stack", () => {
+    const schema = Schema.struct({ a: Schema.string() })
+    const { doc } = build(schema)
+
+    let aborted = false
+    subscribe(doc.a, (cs: any) => {
+      if (cs.aborted) aborted = true
+    })
+
+    expect(() => {
+      change(doc, (d: any) => {
+        d.a.set("hello")
+        throw new Error("abort")
+      })
+    }).toThrow("abort")
+
+    expect(aborted).toBe(true)
+    expect((doc.a as any)()).toBe("")
+  })
+})

package/src/__tests__/substrate.test.ts

@@ -8,6 +8,7 @@ import {
   RawPath,
   Schema,
   subscribe,
+  unwrap,
   version,
 } from "@kyneta/schema"
 import { describe, expect, it } from "vitest"
@@ -652,4 +653,58 @@ describe("YjsSubstrate", () => {
       expect(writes).toBe(1)
     })
   })
+
+  // -------------------------------------------------------------------------
+  // Origin-free discriminator tests
+  // -------------------------------------------------------------------------
+
+  describe("origin-free discriminator", () => {
+    it("options.origin survives to transaction.origin", () => {
+      const doc = createDoc(yjs.bind(SimpleSchema))
+      const native = unwrap(doc) as Y.Doc
+
+      let capturedOrigin: string | undefined = "not-called"
+      native.on("afterTransaction", tr => {
+        capturedOrigin = tr.origin
+      })
+
+      change(doc, d => d.title.insert(0, "x"), { origin: "undo" })
+      expect(capturedOrigin).toBe("undo")
+    })
+
+    it("external wrapping kyneta is correctly classified as own", () => {
+      const doc = createDoc(yjs.bind(SimpleSchema))
+
+      let kynetaFires = 0
+      subscribe(doc, () => {
+        kynetaFires++
+      })
+
+      const native = unwrap(doc) as Y.Doc
+      native.transact(() => {
+        change(doc, d => d.title.insert(0, "x"))
+      }, "external")
+
+      // Should fire exactly once (captured via wrappedPrepare),
+      // and NOT twice (the bridge should skip the external transaction
+      // because the inner kyneta transact marked the transaction).
+      expect(kynetaFires).toBe(1)
+    })
+
+    it("external raw transact with any string origin is bridged", () => {
+      const doc = createDoc(yjs.bind(SimpleSchema))
+
+      let kynetaFires = 0
+      subscribe(doc, () => {
+        kynetaFires++
+      })
+
+      const native = unwrap(doc) as Y.Doc
+      native.transact(() => {
+        native.getMap("root").set("title", "ext")
+      }, "kyneta-prepare")
+
+      expect(kynetaFires).toBe(1)
+    })
+  })
 })

package/src/change-mapping.ts

@@ -35,6 +35,8 @@ import type {
 } from "@kyneta/schema"
 import {
   expandMapOpsToLeaves,
+  isJsonBoundary,
+  isPlainObject,
   KIND,
   pathSchema,
   RawPath,
@@ -299,7 +301,7 @@ function applyReplaceChange(
 ): void {
   if (path.length === 0) {
     throw new Error(
-      "applyChangeToYjs: ReplaceChange at root path is not supported",
+      "Cannot replace the root document struct in a CRDT backend. The root identity is fixed. Please mutate its properties individually (e.g., `doc.myField.set(value)` instead of `doc.set({ myField: value })`).",
     )
   }
 
@@ -366,6 +368,12 @@ function maybeCreateSharedType(
 ): unknown {
   if (schema === undefined) return value
 
+  // JSON-boundary schemas (struct.json/list.json/record.json) store
+  // their entire subtree as a plain JSON value in the parent Y.Map
+  // entry. Skip Y.Map/Y.Array materialisation and pass the value
+  // through unchanged — including nested objects/arrays underneath.
+  if (isJsonBoundary(schema)) return value
+
   switch (schema[KIND]) {
     // First-class text → Y.Text
     case "text": {
@@ -400,12 +408,7 @@ function maybeCreateSharedType(
     }
 
     case "product": {
-      if (
-        value === null ||
-        value === undefined ||
-        typeof value !== "object" ||
-        Array.isArray(value)
-      ) {
+      if (!isPlainObject(value)) {
         return value
       }
       return createStructuredMap(value as Record<string, unknown>, schema)
@@ -423,12 +426,7 @@ function maybeCreateSharedType(
     }
 
     case "map": {
-      if (
-        value === null ||
-        value === undefined ||
-        typeof value !== "object" ||
-        Array.isArray(value)
-      ) {
+      if (!isPlainObject(value)) {
         return value
       }
       const map = new Y.Map()

package/src/populate.ts

@@ -17,7 +17,7 @@
 // functions: ensureContainers, ensureRootField, ensureMapContainers.
 
 import type { SchemaBinding, Schema as SchemaNode } from "@kyneta/schema"
-import { KIND, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
+import { isJsonBoundary, KIND, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -123,6 +123,12 @@ function ensureRootField(
   // and necessary on hydrated docs (preserves existing data).
   if (rootMap.has(key)) return
 
+  // JSON-boundary fields (struct.json/list.json/record.json) store the
+  // subtree as a plain JSON value in the root Y.Map entry. We leave the
+  // entry absent at structural-init time; the first write materialises
+  // it with `rootMap.set(key, plainValue)`.
+  if (isJsonBoundary(fieldSchema)) return
+
   switch (fieldSchema[KIND]) {
     case "text":
     case "richtext":
@@ -196,6 +202,12 @@ function ensureMapContainers(
     const identity = binding?.forward.get(absPath) as string | undefined
     const mapKey = identity ?? key
 
+    // JSON-boundary nested field: leave the entry absent, the first
+    // write will set the plain JSON value at this key.
+    if (isJsonBoundary(fieldSchema)) {
+      continue
+    }
+
     switch (fieldSchema[KIND]) {
       case "text":
       case "richtext":