@kyneta/yjs-schema 1.6.0 → 1.7.0

package/src/change-mapping.ts

@@ -22,6 +22,7 @@ import type {
   MapChange,
   Op,
   Path,
+  ProductSchema,
   ReplaceChange,
   RichTextChange,
   RichTextInstruction,
@@ -33,9 +34,9 @@ import type {
   TextInstruction,
 } from "@kyneta/schema"
 import {
-  advanceSchema,
   expandMapOpsToLeaves,
   KIND,
+  pathSchema,
   RawPath,
   richTextChange,
 } from "@kyneta/schema"
@@ -118,6 +119,17 @@ export function applyChangeToYjs(
           `Attempted TreeChange at path [${pathToString(path)}].`,
       )
 
+    case "set-op":
+      // Sets (`Schema.set`) are rejected by `yjs.bind` at compile time
+      // (`"add-wins-per-key"` is not in `YjsLaws`). Unreachable from any
+      // bound Yjs substrate today; kept against the new `SetChange`
+      // vocabulary so future law-set expansion has a clear extension point.
+      throw new Error(
+        `Yjs substrate does not support "${change.type}" changes. ` +
+          `Schema.set requires "add-wins-per-key" which is not in YjsLaws. ` +
+          `Attempted SetChange at path [${pathToString(path)}].`,
+      )
+
     default:
       throw new Error(
         `applyChangeToYjs: unsupported change type "${change.type}"`,
@@ -201,7 +213,7 @@ function applySequenceChange(
   }
 
   // Resolve the item schema for structured insert detection
-  const targetSchema = resolveSchemaAtPath(rootSchema, path)
+  const targetSchema = pathSchema(rootSchema, path)
   const itemSchema = getItemSchema(targetSchema)
 
   let cursor = 0
@@ -241,7 +253,7 @@ function applyMapChange(
   }
 
   // Resolve the schema at this path for structured value detection
-  const targetSchema = resolveSchemaAtPath(rootSchema, path)
+  const targetSchema = pathSchema(rootSchema, path)
 
   // Apply deletes first
   if (change.delete) {
@@ -259,9 +271,10 @@ function applyMapChange(
       // For map schemas (records), use the key as-is (no identity-keying).
       let mapKey = key
       if (binding && targetSchema[KIND] === "product") {
-        // Compute absolute schema path for this field.
+        // Compute absolute schema path for this field — only product-field
+        // segments contribute (entry segments are runtime keys).
         const parentAbsPath = path.segments
-          .filter(s => s.role === "key")
+          .filter(s => s.role === "field")
           .map(s => s.resolve() as string)
           .join(".")
         const absPath = parentAbsPath ? `${parentAbsPath}.${key}` : key
@@ -303,15 +316,19 @@ function applyReplaceChange(
   )
 
   const resolved = lastSeg.resolve()
-  if (parent instanceof Y.Map && lastSeg.role === "key") {
+  if (
+    parent instanceof Y.Map &&
+    (lastSeg.role === "field" || lastSeg.role === "entry")
+  ) {
     // Resolve schema for the target field for structured value detection
-    const targetSchema = resolveSchemaAtPath(rootSchema, path)
+    const targetSchema = pathSchema(rootSchema, path)
     const yjsValue = maybeCreateSharedType(change.value, targetSchema)
-    // Use identity hash for product-field boundaries.
+    // Identity-keying applies only at product-field boundaries; entry
+    // segments use the runtime key as-is.
     let mapKey = resolved as string
-    if (binding) {
+    if (binding && lastSeg.role === "field") {
       const absPath = path.segments
-        .filter(s => s.role === "key")
+        .filter(s => s.role === "field")
         .map(s => s.resolve() as string)
         .join(".")
       const identity = binding.forward.get(absPath) as string | undefined
@@ -319,7 +336,7 @@ function applyReplaceChange(
     }
     parent.set(mapKey, yjsValue)
   } else if (parent instanceof Y.Array && lastSeg.role === "index") {
-    const targetSchema = resolveSchemaAtPath(rootSchema, path)
+    const targetSchema = pathSchema(rootSchema, path)
     const yjsValue = maybeCreateSharedType(change.value, targetSchema)
     parent.delete(resolved as number, 1)
     parent.insert(resolved as number, [yjsValue])
@@ -509,7 +526,7 @@ export function eventsToOps(
   const ops: Op[] = []
 
   for (const event of events) {
-    const kynetaPath = yjsPathToKynetaPath(event.path, binding)
+    const kynetaPath = yjsPathToKynetaPath(event.path, schema, binding)
     const change = eventToChange(event, schema, kynetaPath, binding)
     if (change) {
       ops.push({ path: kynetaPath, change })
@@ -524,31 +541,55 @@ export function eventsToOps(
 // ---------------------------------------------------------------------------
 
 /**
- * Convert a Yjs event path (array of string | number) to a kyneta Path.
+ * Convert a Yjs event path to a kyneta `RawPath`, walking the schema
+ * alongside so each segment is classified as field / entry / index by
+ * the current schema kind.
  *
- * `event.path` from `observeDeep` is relative to the observed type.
- * Strings become key segments, numbers become index segments.
+ * Why schema-aware and not "did the inverse lookup hit?": the binding's
+ * inverse map only covers declared product-field positions reachable
+ * without crossing a runtime-keyed container. A declared struct field
+ * nested under a `record(...)` value type is reachable via Yjs but
+ * absent from `binding.inverse` — without the schema walk it would be
+ * misclassified as an entry and then rejected by `advanceSchema`.
  */
 function yjsPathToKynetaPath(
   yjsPath: (string | number)[],
+  rootSchema: SchemaNode,
   binding?: SchemaBinding,
 ): RawPath {
   let path = RawPath.empty
+  let schema: SchemaNode | undefined = rootSchema
   for (const segment of yjsPath) {
     if (typeof segment === "string") {
-      // Reverse-map identity hash → absolute schema path → leaf field name.
-      // Yjs events emit identity-keyed strings at product-field positions;
-      // we need to recover the original field name for kyneta schema paths.
+      // Inverse-lookup recovers the original declared field name when
+      // the segment IS an identity hash; otherwise we keep the string.
+      let leaf = segment
       const absPath = binding?.inverse.get(segment as any)
       if (absPath) {
         const lastDot = absPath.lastIndexOf(".")
-        const leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath
+        leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath
+      }
+      const kind = schema?.[KIND]
+      if (kind === "product") {
         path = path.field(leaf)
+        schema = (schema as ProductSchema | undefined)?.fields[leaf]
+      } else if (kind === "map" || kind === "set" || kind === "tree") {
+        path = path.entry(leaf)
+        schema = (schema as any)?.item
       } else {
-        path = path.field(segment)
+        // Unknown / sum / unrecognized — fall back to entry. Subsequent
+        // segments are likely walking plain JSON inside a sum variant.
+        path = path.entry(leaf)
+        schema = undefined
       }
     } else if (typeof segment === "number") {
       path = path.item(segment)
+      const kind = schema?.[KIND]
+      if (kind === "sequence" || kind === "movable") {
+        schema = (schema as any).item
+      } else {
+        schema = undefined
+      }
     }
   }
   return path
@@ -576,7 +617,7 @@ function eventToChange(
 ): ChangeBase | null {
   if (event.target instanceof Y.Text) {
     // Both text and richtext use Y.Text — resolve the schema to dispatch.
-    const schemaAtPath = resolveSchemaAtPath(rootSchema, kynetaPath)
+    const schemaAtPath = pathSchema(rootSchema, kynetaPath)
     if (schemaAtPath[KIND] === "richtext") {
       return richTextEventToChange(event)
     }
@@ -739,20 +780,6 @@ function extractEventValue(value: unknown): unknown {
 // Schema helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Resolve the schema at a given path by walking through advanceSchema.
- */
-function resolveSchemaAtPath(rootSchema: SchemaNode, path: Path): SchemaNode {
-  let schema = rootSchema
-  for (const seg of path.segments) {
-    schema = advanceSchema(schema, seg)
-    // Sum variants are always PlainSchema — cannot advance further.
-    // Return early; remaining segments address plain JSON values.
-    if (schema[KIND] === "sum") return schema
-  }
-  return schema
-}
-
 /**
  * Get the item schema from a sequence schema, if available.
  */

package/src/index.ts

@@ -50,8 +50,7 @@ export type { YjsNativeMap } from "./native-map.js"
 export { ensureContainers } from "./populate.js"
 // Position conformance
 export { fromYjsAssoc, toYjsAssoc, YjsPosition } from "./position.js"
-// Reader
-export { yjsReader } from "./reader.js"
+
 // Substrate
 export {
   createYjsSubstrate,

package/src/materialize.ts

@@ -0,0 +1,109 @@
+// materialize — Yjs→PlainState materialization via generic resolver.
+//
+// Implements `createYjsResolver`, a closure-based `MaterializeResolver`
+// that navigates the Yjs shared type tree via `resolveYjsType`. The
+// generic `createMaterializeInterpreter` drives the catamorphism; the
+// resolver handles only the CRDT-specific value extraction.
+//
+// Unsupported types (counter, tree, movable) return `undefined` from
+// the resolver, triggering the generic interpreter's zero fallback.
+//
+// Zero fallback for missing values is handled canonically by the
+// generic interpreter — not inlined here.
+
+import type {
+  MaterializeResolver,
+  Path,
+  PlainState,
+  RichTextDelta,
+  SchemaBinding,
+  Schema as SchemaNode,
+} from "@kyneta/schema"
+import {
+  createMaterializeInterpreter,
+  interpret,
+  isNonNullObject,
+  materializeContextFromResolver,
+} from "@kyneta/schema"
+import * as Y from "yjs"
+import { extractValue, yTextToRichTextDelta } from "./yjs-extract.js"
+import { resolveYjsType } from "./yjs-resolve.js"
+
+// ---------------------------------------------------------------------------
+// Yjs resolver
+// ---------------------------------------------------------------------------
+
+function createYjsResolver(
+  rootMap: Y.Map<any>,
+  rootSchema: SchemaNode,
+  binding?: SchemaBinding,
+): MaterializeResolver {
+  return {
+    resolveValue(path: Path): unknown {
+      const result = resolveYjsType(rootMap, rootSchema, path, binding)
+      return extractValue(result.resolved)
+    },
+
+    resolveText(path: Path): string | undefined {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Text) {
+        return resolved.toJSON()
+      }
+      const value = extractValue(resolved)
+      return typeof value === "string" ? value : undefined
+    },
+
+    // Yjs does not support counters — schemas with counter types are
+    // rejected at bind time. Return undefined to trigger zero fallback.
+    resolveCounter(_path: Path): number | undefined {
+      return undefined
+    },
+
+    resolveRichText(path: Path): RichTextDelta | undefined {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Text) {
+        return yTextToRichTextDelta(resolved)
+      }
+      return undefined
+    },
+
+    resolveLength(path: Path): number {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Array) {
+        return resolved.length
+      }
+      return Array.isArray(resolved) ? resolved.length : 0
+    },
+
+    resolveKeys(path: Path): string[] {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Map) {
+        return Array.from(resolved.keys())
+      }
+      return isNonNullObject(resolved) ? Object.keys(resolved) : []
+    },
+
+    // Yjs has no tree primitive — schemas with `Schema.tree` are rejected
+    // at bind time. Defensive [] for any caller that reaches here.
+    resolveForest(_path: Path): readonly never[] {
+      return []
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function materializeYjsShadow(
+  doc: Y.Doc,
+  schema: SchemaNode,
+  binding?: SchemaBinding,
+): PlainState {
+  const rootMap = doc.getMap("root")
+  const resolver = createYjsResolver(rootMap, schema, binding)
+  const interp = createMaterializeInterpreter(resolver)
+  const ctx = materializeContextFromResolver(resolver)
+  const result = interpret(schema, interp, ctx)
+  return result as PlainState
+}

package/src/populate.ts

@@ -1,14 +1,11 @@
 // populate — Yjs container creation from schema structure.
 //
 // Ensures that the correct Yjs shared types (Y.Text, Y.Array, Y.Map)
-// exist in a Y.Doc's root map to match the schema structure, and that
-// scalar/sum fields are initialized with Zero.structural defaults.
+// exist in a Y.Doc's root map to match the schema structure.
 //
-// This is NOT seed data — it's structural completeness, matching what
-// PlainSubstrate does when it initializes its store with Zero.structural.
-// The Yjs store reader expects to find values at every schema path;
-// without this, unset scalars would return undefined instead of their
-// type-correct zero ("", 0, false).
+// Only container types (text, product, sequence, map) require CRDT
+// writes here. Scalar and sum fields are handled by the materializer's
+// zero fallback — no Yjs writes are needed for non-container types.
 //
 // Root container strategy: All schema fields are children of a single
 // root `Y.Map` obtained via `doc.getMap("root")`. This root map holds
@@ -20,7 +17,7 @@
 // functions: ensureContainers, ensureRootField, ensureMapContainers.
 
 import type { SchemaBinding, Schema as SchemaNode } from "@kyneta/schema"
-import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
+import { KIND, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -35,14 +32,10 @@ import * as Y from "yjs"
  * schema's fields, and creates empty containers for each field within a
  * single `doc.transact()` call for atomicity.
  *
- * 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.
+ * Container fields (text, product, sequence, map) are created if absent;
+ * existing containers are preserved (calling `rootMap.set()` on a field
+ * that already exists would be a destructive CRDT write). Scalar and sum
+ * fields are no-ops — the materializer handles zeros.
  *
  * **Structural identity:** This function temporarily sets `doc.clientID`
  * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
@@ -56,14 +49,11 @@ import * as Y from "yjs"
  *
  * @param doc - The Y.Doc to prepare
  * @param schema - The root document schema (a ProductSchema)
- * @param conditional - If true, skip fields that already exist in the root map.
- *   Context: jj:smmulzkm (two-phase substrate construction)
  * @param binding - Optional SchemaBinding for identity-keyed containers.
  */
 export function ensureContainers(
   doc: Y.Doc,
   schema: SchemaNode,
-  conditional = false,
   binding?: SchemaBinding,
 ): void {
   const rootMap = doc.getMap("root")
@@ -84,7 +74,6 @@ export function ensureContainers(
       )) {
         const identity = binding?.forward.get(key) as string | undefined
         const mapKey = identity ?? key
-        if (conditional && rootMap.has(mapKey)) continue
         ensureRootField(
           rootMap,
           mapKey,
@@ -112,7 +101,7 @@ export function ensureContainers(
  * - `"product"` → empty Y.Map (recursive for nested products)
  * - `"sequence"` → empty Y.Array
  * - `"map"` → empty Y.Map
- * - `"scalar"` / `"sum"` → Zero.structural default
+ * - `"scalar"` / `"sum"` → no-op (materializer zero fallback)
  * - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
  *
  * @param rootMap - The root Y.Map to set the field on.
@@ -128,6 +117,12 @@ function ensureRootField(
   binding?: SchemaBinding,
   prefix?: string,
 ): void {
+  // Skip fields that already exist — calling rootMap.set() on an existing
+  // shared type would replace it (a destructive CRDT write), and scalars
+  // are no-ops regardless. This is safe on fresh docs (nothing to skip)
+  // and necessary on hydrated docs (preserves existing data).
+  if (rootMap.has(key)) return
+
   switch (fieldSchema[KIND]) {
     case "text":
     case "richtext":
@@ -147,16 +142,10 @@ function ensureRootField(
       return
 
     case "scalar":
-    case "sum": {
-      // Plain values don't need shared type containers, but they DO
-      // need structural zero defaults so the store reader returns
-      // type-correct values (e.g. "" not undefined for strings).
-      const zero = Zero.structural(fieldSchema)
-      if (zero !== undefined) {
-        rootMap.set(key, zero)
-      }
+    case "sum":
+      // Value concerns are handled by the materializer's zero fallback.
+      // No CRDT writes needed for non-container types.
       return
-    }
 
     case "counter":
     case "set":
@@ -180,7 +169,7 @@ function ensureRootField(
  *
  * Only creates containers for fields that require Yjs shared types
  * (text → Y.Text, product → Y.Map, sequence → Y.Array, map → Y.Map).
- * Scalar and sum fields are set to their structural zero defaults.
+ * Scalar and sum fields are skipped (materializer zero fallback).
  *
  * **Identity-keying:** When a `binding` is provided, computes the
  * absolute schema path for each nested field (`prefix.fieldName`) and
@@ -226,13 +215,10 @@ function ensureMapContainers(
         break
 
       case "scalar":
-      case "sum": {
-        const zero = Zero.structural(fieldSchema)
-        if (zero !== undefined) {
-          map.set(mapKey, zero)
-        }
+      case "sum":
+        // Value concerns are handled by the materializer's zero fallback.
+        // No CRDT writes needed for non-container types.
         break
-      }
 
       case "counter":
       case "set":