grafeo-ogm 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 2.1.0 (2026-08-13) — 🧭 Writes now store what the schema declares
+
+> **Every write path now binds values as the Neo4j type the schema promises.** Until now the compilers bound raw JS values and left the rest to the driver — and the driver packs every JS `number` as a Bolt FLOAT64 and every string as a String. So `Int`/`BigInt` fields landed as **Doubles** ([#5](https://github.com/neomodular/grafeo-ogm/issues/5)), the six temporal types landed as **Strings**, and `BigInt`'s documented string input landed as a **String** — while reads converted every native value back to a JS primitive, so the corruption was invisible until something type-sensitive touched the property. `@default` rode along: parsed, documented in the README, and applied nowhere.
+>
+> **This is a minor version because behavior changes on inputs that previously "worked":** `position: 1.5` and `plays: 'abc'` now throw instead of silently storing the wrong type, schemas that declare `@default` now actually receive defaults on create, and the generated `BigInt` scalar changes shape. If your inputs already match the documented contract you can upgrade and regenerate directly — but read the **migration note** below if you have data written through the OGM before 2.1.0.
+
+### 🐛 `Int` / `BigInt` writes are bound as Neo4j Integer ([#5](https://github.com/neomodular/grafeo-ogm/issues/5))
+
+The driver packs every JS `number` as FLOAT64 — `disableLosslessIntegers` only affects reads — so every OGM-written `Int` property landed as a Double. Once a field held a mixed Long/Double population (OGM writes vs seed/raw-Cypher writes), Long-typed consumers crashed:
+
+```
+Failed to invoke function `apoc.coll.sortMulti`:
+java.lang.ClassCastException: class java.lang.Double cannot be cast to class java.lang.Long
+```
+
+Every mutation binding site — create, update, upsert (MERGE key, `ON CREATE SET`, `ON MATCH SET`), `createMany` items, and all edge-property paths through connect and nested updates (**14 sites** in total; the report named 5) — now binds `Int`/`BigInt` values through `neo4j.int()`. Numbers, bigints, integer strings, and pre-built `Integer` instances are all accepted; `null` clears as before.
+
+**Rejected, not truncated:** a non-integral number (`1.5`) or a non-integer string (`'abc'`) for an integer field now throws `OGMError`. Coercing would silently truncate; binding raw would silently store the wrong type — both are the defect class 2.0.0 exists to reject.
+
+### 🐛 Temporal writes are stored as native temporal types
+
+`DateTime`, `Date`, `Time`, `LocalTime`, `LocalDateTime`, and `Duration` fields were stored as **String** properties — the write path had no temporal conversion at all, while the README's scalar table promised native storage and reads converted native temporals to ISO strings. Against natively-typed rows (seed, APOC, raw Cypher), `WHERE n.createdAt > $param` with a string param is a cross-type comparison: Neo4j evaluates it to `NULL` and **silently drops the row**.
+
+ISO-string writes are now wrapped in the field's Cypher constructor — the parameter stays a string and Neo4j does the parsing, which preserves nanosecond precision and bracket timezones (`2024-01-15T10:30:00[America/New_York]`) that a JS `Date` round-trip would destroy:
+
+```cypher
+CREATE (n:`Event` { `startsAt`: datetime($create0_startsAt) })
+SET n.`day` = date($update_day)
+// list fields wrap element-wise:
+`slots`: [wc_t IN $create0_slots | datetime(wc_t)]
+```
+
+The same wrapping applies to WHERE params for comparison-shaped operators (`=`, `_NOT`, `_GT`/`_GTE`/`_LT`/`_LTE`, `_IN`/`_NOT_IN`) across the main where compiler and the connect/disconnect where paths, so filters keep matching the natively-stored values. String operators (`_CONTAINS`, `_MATCHES`, …) are untouched. Driver temporal objects still bind raw — only strings are wrapped. Batched paths (`createMany`, array connect) share one Cypher expression per field, so a column mixing ISO strings with driver objects throws instead of guessing.
+
+### 🐛 `BigInt` honours its generated contract in both directions
+
+The generated scalar declared `BigInt: { input: string; output: string }` — but a string input sailed through to a **String property**, and reads returned `number` (or `bigint` above 2⁵³), never `string`. Integer strings now coerce through `neo4j.int()` (for `Int` fields too), and the scalar tells the truth:
+
+```typescript
+BigInt: { input: string | number | bigint; output: number | bigint };
+```
+
+Regenerate your types to pick this up. If you annotated variables with the old `string` output type, those annotations were already wrong at runtime — the regen turns them into compile errors you can fix.
+
+### 🐛 `@default` is now applied on create
+
+`@default` was parsed into schema metadata and consumed by **nothing** — a documented silent no-op. It now applies wherever a node is created:
+
+- `create` (nested relationship creates included)
+- `upsert` — `ON CREATE SET` branch only, never `ON MATCH`, and never for MERGE-key fields
+- `createMany` — as a whole-column default when **no** item supplies the field (per-item gaps inside a provided column stay `null`: every batch shares one Cypher text, and `coalesce()` would also override explicit nulls)
+
+Defaults convert by declared type — `@default(value: "5")` on an `Int` binds an Integer, `Boolean` binds `true`/`false`, temporal defaults get their constructor wrapper. **A provided value always wins, and an explicit `null` stays `null`** — the user asked for null; a default overriding it would betray intent.
+
+### ⚠️ Migrating data written before 2.1.0
+
+Properties written through the OGM before this release carry the old storage types. New writes and filters use native types, so mixed populations should be migrated once, per affected field:
+
+```cypher
+// String-stored temporals → native (repeat per temporal field/label)
+MATCH (n:Event) WHERE valueType(n.startsAt) STARTS WITH 'STRING'
+SET n.startsAt = datetime(n.startsAt);
+
+// Double-stored Ints → Long (only needed for Long-sensitive consumers,
+// e.g. apoc.coll.sortMulti — Cypher numeric comparisons already match)
+MATCH (n:ShelfRow) WHERE valueType(n.position) = 'FLOAT'
+SET n.position = toInteger(n.position);
+```
+
+Until the temporal migration runs, WHERE filters on temporal fields will not match old String-stored rows (they compare as cross-type → `NULL`).
+
+### Tests
+
+- `tests/int-write-coercion.spec.ts` — 14 tests pinning Integer coercion across every mutation path.
+- `tests/type-faithful-writes.spec.ts` — 24 tests pinning temporal wrapping (writes + WHERE), integer-string coercion, and `@default` semantics.
+- 12 existing assertions that pinned the old behavior (raw-number edge params, unwrapped temporal comparisons, `DateTime` strings passed verbatim) updated to the corrected contract.
+
 ## 2.0.0 (2026-08-04) — 💥 Inputs that were silently truncated are now rejected
 
 > **A major release with one theme: grafeo used to read the first key of certain input objects and throw the rest away without a word.** `sort` entries, fulltext leaves, and fulltext logical operators all did it. Every one produced a *successful* query answering a different question than the caller asked — no exception, no log, nothing in the Cypher to suggest anything was missing.

package/dist/cjs/compilers/mutation.compiler.d.ts

@@ -120,6 +120,13 @@ export declare class MutationCompiler {
      * Returns count of created nodes.
      */
     compileCreateMany(data: Record<string, unknown>[], nodeDef: NodeDefinition, skipDuplicates?: boolean, labels?: string[]): MutationResult;
+    /**
+     * Resolve the PropertyDefinition of an edge (relationship) property so
+     * Int/BigInt edge writes get the same Integer coercion as node writes.
+     * Returns undefined when the relationship declares no properties type
+     * (the coercion then passes the value through untouched).
+     */
+    private getEdgePropDef;
     private buildCreateProperties;
     private buildCreateRelationships;
     /**

package/dist/cjs/compilers/mutation.compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutation.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/mutation.compiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mutation.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/mutation.compiler.ts"],"names":[],"mappings":"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"}

package/dist/cjs/compilers/mutation.compiler.js

@@ -4,6 +4,7 @@ exports.MutationCompiler = void 0;
 const errors_1 = require("../errors");
 const utils_1 = require("../schema/utils");
 const validation_1 = require("../utils/validation");
+const write_coercion_1 = require("../utils/write-coercion");
 const where_compiler_1 = require("./where.compiler");
 /**
  * Relationship filter suffixes that require EXISTS subquery patterns.
@@ -182,9 +183,11 @@ class MutationCompiler {
                 if (value === undefined)
                     continue;
                 (0, validation_1.assertSafePropertyName)(key, 'update property');
+                const propDef = nodeDef.properties.get(key);
                 const paramName = `update_${key}`;
-                setClauses.push(`n.${(0, validation_1.escapeIdentifier)(key)} = $${paramName}`);
-                params[paramName] = value;
+                const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, value, propDef);
+                setClauses.push(`n.${(0, validation_1.escapeIdentifier)(key)} = ${valueExpr}`);
+                params[paramName] = (0, write_coercion_1.coerceWriteValue)(value, propDef);
             }
             if (setClauses.length > 0)
                 lines.push(`SET ${setClauses.join(', ')}`);
@@ -262,10 +265,12 @@ class MutationCompiler {
             if (key.includes('_') && !nodeDef.properties.has(key))
                 continue;
             (0, validation_1.assertSafePropertyName)(key, 'merge key');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `merge_${key}`;
-            mergeProps.push(`${(0, validation_1.escapeIdentifier)(key)}: $${paramName}`);
+            const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, value, propDef);
+            mergeProps.push(`${(0, validation_1.escapeIdentifier)(key)}: ${valueExpr}`);
             mergeKeyNames.push(key);
-            params[paramName] = value;
+            params[paramName] = (0, write_coercion_1.coerceWriteValue)(value, propDef);
         }
         if (mergeProps.length === 0)
             throw new errors_1.OGMError('upsert requires at least one scalar property in "where" for MERGE key');
@@ -301,9 +306,29 @@ class MutationCompiler {
             if (nodeDef.relationships.has(key))
                 continue;
             (0, validation_1.assertSafePropertyName)(key, 'create property');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `onCreate_${key}`;
-            createSets.push(`n.${(0, validation_1.escapeIdentifier)(key)} = $${paramName}`);
-            params[paramName] = value;
+            const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, value, propDef);
+            createSets.push(`n.${(0, validation_1.escapeIdentifier)(key)} = ${valueExpr}`);
+            params[paramName] = (0, write_coercion_1.coerceWriteValue)(value, propDef);
+        }
+        // `@default` values apply to the ON CREATE branch — a defaulted
+        // property not supplied in `create` and not already fixed by the
+        // MERGE key gets its default, mirroring create().
+        for (const [, propDef] of nodeDef.properties) {
+            if (propDef.defaultValue === undefined)
+                continue;
+            if (propDef.isGenerated || propDef.isCypher)
+                continue;
+            if (create[propDef.name] !== undefined)
+                continue;
+            if (mergeKeyNames.includes(propDef.name))
+                continue;
+            const paramName = `onCreate_${propDef.name}`;
+            const bound = (0, write_coercion_1.resolveDefaultWriteValue)(propDef);
+            const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, bound, propDef);
+            createSets.push(`n.${(0, validation_1.escapeIdentifier)(propDef.name)} = ${valueExpr}`);
+            params[paramName] = bound;
         }
         if (createSets.length > 0)
             lines.push(`ON CREATE SET ${createSets.join(', ')}`);
@@ -315,9 +340,11 @@ class MutationCompiler {
             if (nodeDef.relationships.has(key))
                 continue;
             (0, validation_1.assertSafePropertyName)(key, 'update property');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `onMatch_${key}`;
-            updateSets.push(`n.${(0, validation_1.escapeIdentifier)(key)} = $${paramName}`);
-            params[paramName] = value;
+            const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, value, propDef);
+            updateSets.push(`n.${(0, validation_1.escapeIdentifier)(key)} = ${valueExpr}`);
+            params[paramName] = (0, write_coercion_1.coerceWriteValue)(value, propDef);
         }
         if (updateSets.length > 0)
             lines.push(`ON MATCH SET ${updateSets.join(', ')}`);
@@ -389,12 +416,24 @@ class MutationCompiler {
         for (const [, propDef] of nodeDef.properties)
             if (propDef.isGenerated && !scalarKeys.includes(propDef.name))
                 generatedFields.push(propDef.name);
+        // Whole-column `@default`s: applied only when NO item supplies the
+        // field. Per-item gaps inside a provided column stay null — one
+        // createMany batch shares a single Cypher text, and a per-item
+        // default would need coalesce(), which would also override explicit
+        // nulls.
+        const defaultedProps = [];
+        for (const [, propDef] of nodeDef.properties)
+            if (propDef.defaultValue !== undefined &&
+                !propDef.isGenerated &&
+                !propDef.isCypher &&
+                !scalarKeys.includes(propDef.name))
+                defaultedProps.push(propDef);
         // Build sanitized items (strip undefined values)
         const sanitizedItems = data.map((item) => {
             const sanitized = {};
             for (const key of scalarKeys)
                 if (item[key] !== undefined)
-                    sanitized[key] = item[key];
+                    sanitized[key] = (0, write_coercion_1.coerceWriteValue)(item[key], nodeDef.properties.get(key));
             return sanitized;
         });
         params.items = sanitizedItems;
@@ -411,16 +450,22 @@ class MutationCompiler {
                 throw new errors_1.OGMError('createMany with skipDuplicates requires at least one @id or @unique field in data');
             // MERGE on unique key(s)
             const mergeProps = mergeKeys
-                .map((k) => `${(0, validation_1.escapeIdentifier)(k)}: item.${(0, validation_1.escapeIdentifier)(k)}`)
+                .map((k) => `${(0, validation_1.escapeIdentifier)(k)}: ${(0, write_coercion_1.wrapTemporalListItemExpr)(`item.${(0, validation_1.escapeIdentifier)(k)}`, data.map((d) => d[k]), nodeDef.properties.get(k))}`)
                 .join(', ');
             lines.push(`MERGE (n:${labelStr} { ${mergeProps} })`);
             // ON CREATE SET — remaining fields + generated IDs
             const onCreateSets = [];
             for (const key of scalarKeys)
                 if (!mergeKeys.includes(key))
-                    onCreateSets.push(`n.${(0, validation_1.escapeIdentifier)(key)} = item.${(0, validation_1.escapeIdentifier)(key)}`);
+                    onCreateSets.push(`n.${(0, validation_1.escapeIdentifier)(key)} = ${(0, write_coercion_1.wrapTemporalListItemExpr)(`item.${(0, validation_1.escapeIdentifier)(key)}`, data.map((d) => d[key]), nodeDef.properties.get(key))}`);
             for (const field of generatedFields)
                 onCreateSets.push(`n.${(0, validation_1.escapeIdentifier)(field)} = randomUUID()`);
+            for (const propDef of defaultedProps) {
+                const paramName = `default_${propDef.name}`;
+                const bound = (0, write_coercion_1.resolveDefaultWriteValue)(propDef);
+                onCreateSets.push(`n.${(0, validation_1.escapeIdentifier)(propDef.name)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, bound, propDef)}`);
+                params[paramName] = bound;
+            }
             if (onCreateSets.length > 0)
                 lines.push(`ON CREATE SET ${onCreateSets.join(', ')}`);
         }
@@ -430,7 +475,13 @@ class MutationCompiler {
             for (const field of generatedFields)
                 propParts.push(`${(0, validation_1.escapeIdentifier)(field)}: randomUUID()`);
             for (const key of scalarKeys)
-                propParts.push(`${(0, validation_1.escapeIdentifier)(key)}: item.${(0, validation_1.escapeIdentifier)(key)}`);
+                propParts.push(`${(0, validation_1.escapeIdentifier)(key)}: ${(0, write_coercion_1.wrapTemporalListItemExpr)(`item.${(0, validation_1.escapeIdentifier)(key)}`, data.map((d) => d[key]), nodeDef.properties.get(key))}`);
+            for (const propDef of defaultedProps) {
+                const paramName = `default_${propDef.name}`;
+                const bound = (0, write_coercion_1.resolveDefaultWriteValue)(propDef);
+                propParts.push(`${(0, validation_1.escapeIdentifier)(propDef.name)}: ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, bound, propDef)}`);
+                params[paramName] = bound;
+            }
             lines.push(`CREATE (n:${labelStr} { ${propParts.join(', ')} })`);
         }
         // Extra labels
@@ -442,6 +493,19 @@ class MutationCompiler {
         return { cypher: lines.join('\n'), params };
     }
     // ─── Private helpers ──────────────────────────────────────────────
+    /**
+     * Resolve the PropertyDefinition of an edge (relationship) property so
+     * Int/BigInt edge writes get the same Integer coercion as node writes.
+     * Returns undefined when the relationship declares no properties type
+     * (the coercion then passes the value through untouched).
+     */
+    getEdgePropDef(relDef, propName) {
+        if (!relDef.properties)
+            return undefined;
+        return this.schema.relationshipProperties
+            .get(relDef.properties)
+            ?.properties.get(propName);
+    }
     buildCreateProperties(input, nodeDef, prefix) {
         const parts = [];
         const propParams = {};
@@ -456,9 +520,28 @@ class MutationCompiler {
             if (value === undefined)
                 continue;
             (0, validation_1.assertSafePropertyName)(key, 'create property');
+            const propDef = nodeDef.properties.get(key);
             const paramName = `${prefix}_${key}`;
-            parts.push(`${(0, validation_1.escapeIdentifier)(key)}: $${paramName}`);
-            propParams[paramName] = value;
+            const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, value, propDef);
+            parts.push(`${(0, validation_1.escapeIdentifier)(key)}: ${valueExpr}`);
+            propParams[paramName] = (0, write_coercion_1.coerceWriteValue)(value, propDef);
+        }
+        // `@default` values — applied for any property with a default that the
+        // input leaves undefined. Explicit null is respected as null: the user
+        // asked for null, a default would override intent. Generated (@id) and
+        // @cypher (computed, not stored) properties never take defaults.
+        for (const [, propDef] of nodeDef.properties) {
+            if (propDef.defaultValue === undefined)
+                continue;
+            if (propDef.isGenerated || propDef.isCypher)
+                continue;
+            if (input[propDef.name] !== undefined)
+                continue;
+            const paramName = `${prefix}_${propDef.name}`;
+            const bound = (0, write_coercion_1.resolveDefaultWriteValue)(propDef);
+            const valueExpr = (0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, bound, propDef);
+            parts.push(`${(0, validation_1.escapeIdentifier)(propDef.name)}: ${valueExpr}`);
+            propParams[paramName] = bound;
         }
         return { propString: parts.join(', '), propParams };
     }
@@ -563,9 +646,10 @@ class MutationCompiler {
                         if (val === undefined)
                             continue;
                         (0, validation_1.assertSafePropertyName)(prop, 'edge property');
+                        const edgePropDef = this.getEdgePropDef(relDef, prop);
                         const paramName = `${prefix}_create${ci}_edge_${prop}`;
-                        setItems.push(`${relVar}.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                        params[paramName] = val;
+                        setItems.push(`${relVar}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, edgePropDef)}`);
+                        params[paramName] = (0, write_coercion_1.coerceWriteValue)(val, edgePropDef);
                     }
                     if (setItems.length > 0)
                         lines.push(`SET ${setItems.join(', ')}`);
@@ -615,9 +699,10 @@ class MutationCompiler {
                         if (val === undefined)
                             continue;
                         (0, validation_1.assertSafePropertyName)(prop, 'edge property');
+                        const edgePropDef = this.getEdgePropDef(relDef, prop);
                         const paramName = `${prefix}_conn${ci}_edge_${prop}`;
-                        setItems.push(`r_conn_${startCounter + counter - 1}.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                        params[paramName] = val;
+                        setItems.push(`r_conn_${startCounter + counter - 1}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, edgePropDef)}`);
+                        params[paramName] = (0, write_coercion_1.coerceWriteValue)(val, edgePropDef);
                     }
                     if (setItems.length > 0)
                         lines.push(`SET ${setItems.join(', ')}`);
@@ -686,9 +771,10 @@ class MutationCompiler {
                                 if (val === undefined)
                                     continue;
                                 (0, validation_1.assertSafePropertyName)(prop, 'edge property');
+                                const edgePropDef = this.getEdgePropDef(relDef, prop);
                                 const paramName = `connect_${fieldName}_${ci}_edge_${prop}`;
-                                setItems.push(`${relVar}.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                                params[paramName] = val;
+                                setItems.push(`${relVar}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, edgePropDef)}`);
+                                params[paramName] = (0, write_coercion_1.coerceWriteValue)(val, edgePropDef);
                             }
                             if (setItems.length > 0)
                                 lines.push(`SET ${setItems.join(', ')}`);
@@ -716,7 +802,7 @@ class MutationCompiler {
                         const cleaned = {};
                         for (const [k, v] of Object.entries(edge))
                             if (v !== undefined)
-                                cleaned[k] = v;
+                                cleaned[k] = (0, write_coercion_1.coerceWriteValue)(v, this.getEdgePropDef(relDef, k));
                         return { ...item, edge: cleaned };
                     });
                     lines.push('WITH n');
@@ -740,7 +826,7 @@ class MutationCompiler {
                                 `silently dropped. Split into separate connect calls, or normalise the items ` +
                                 `to share the same shape.`);
                     }
-                    const whereConditions = this.extractConnectWhereConditions(firstItem, 'target', 'connItem');
+                    const whereConditions = this.extractConnectWhereConditions(firstItem, 'target', 'connItem', targetNodeDef);
                     const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, 'target', params, policyContext, paramCounter);
                     const unwindConditions = policyPredicate
                         ? [...whereConditions, policyPredicate]
@@ -765,7 +851,7 @@ class MutationCompiler {
                         // Replace MERGE line with one that has a variable
                         lines[lines.length - 1] = `MERGE ${mergeWithVar}`;
                         // r.prop is relationship property (escape), connItem.edge.prop is parameter map (no escape)
-                        const setItems = edgeProps.map((p) => `r.${(0, validation_1.escapeIdentifier)(p)} = connItem.edge.${p}`);
+                        const setItems = edgeProps.map((p) => `r.${(0, validation_1.escapeIdentifier)(p)} = ${(0, write_coercion_1.wrapTemporalListItemExpr)(`connItem.edge.${p}`, spec.map((it) => it.edge?.[p]), this.getEdgePropDef(relDef, p))}`);
                         lines.push(`SET ${setItems.join(', ')}`);
                     }
                 }
@@ -796,9 +882,10 @@ class MutationCompiler {
                     for (const [prop, val] of Object.entries(edgeInput)) {
                         if (val === undefined)
                             continue;
+                        const edgePropDef = this.getEdgePropDef(relDef, prop);
                         const paramName = `connect_${fieldName}_edge_${prop}`;
-                        setItems.push(`r.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                        params[paramName] = val;
+                        setItems.push(`r.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, edgePropDef)}`);
+                        params[paramName] = (0, write_coercion_1.coerceWriteValue)(val, edgePropDef);
                     }
                     if (setItems.length > 0)
                         lines.push(`SET ${setItems.join(', ')}`);
@@ -1111,9 +1198,10 @@ class MutationCompiler {
                                 if (val === undefined)
                                     continue;
                                 (0, validation_1.assertSafePropertyName)(prop, 'edge property');
+                                const edgePropDef = this.getEdgePropDef(relDef, prop);
                                 const paramName = `${itemPrefix}_conn${ci}_edge_${prop}`;
-                                setItems.push(`r_conn_${key}_${ci}.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                                params[paramName] = val;
+                                setItems.push(`r_conn_${key}_${ci}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, edgePropDef)}`);
+                                params[paramName] = (0, write_coercion_1.coerceWriteValue)(val, edgePropDef);
                             }
                             if (setItems.length > 0)
                                 lines.push(`SET ${setItems.join(', ')}`);
@@ -1149,9 +1237,10 @@ class MutationCompiler {
                         if (val === undefined)
                             continue;
                         (0, validation_1.assertSafePropertyName)(prop, 'nested update property');
+                        const nodePropDef = targetNodeDef.properties.get(prop);
                         const paramName = `${itemPrefix}_set_${prop}`;
-                        setClauses.push(`${updateVar}.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                        setParams[paramName] = val;
+                        setClauses.push(`${updateVar}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, nodePropDef)}`);
+                        setParams[paramName] = (0, write_coercion_1.coerceWriteValue)(val, nodePropDef);
                     }
                     // Pre-compute SET clauses for edge (relationship) properties
                     const edgeClauses = [];
@@ -1161,9 +1250,10 @@ class MutationCompiler {
                             if (val === undefined)
                                 continue;
                             (0, validation_1.assertSafePropertyName)(prop, 'edge update property');
+                            const edgePropDef = this.getEdgePropDef(relDef, prop);
                             const paramName = `${itemPrefix}_edge_${prop}`;
-                            edgeClauses.push(`${relVar}.${(0, validation_1.escapeIdentifier)(prop)} = $${paramName}`);
-                            edgeParams[paramName] = val;
+                            edgeClauses.push(`${relVar}.${(0, validation_1.escapeIdentifier)(prop)} = ${(0, write_coercion_1.wrapTemporalWriteExpr)(`$${paramName}`, val, edgePropDef)}`);
+                            edgeParams[paramName] = (0, write_coercion_1.coerceWriteValue)(val, edgePropDef);
                         }
                     // Pre-compute nested relationship operations
                     const nestedParams = {};
@@ -1249,15 +1339,16 @@ class MutationCompiler {
                     (0, validation_1.assertSafePropertyName)(baseProp, 'where property');
                     const paramName = `${prefix}_NOT_${notProp}`;
                     const escapedProp = (0, validation_1.escapeIdentifier)(baseProp);
+                    const paramRef = (0, write_coercion_1.wrapTemporalWhereParam)(`$${paramName}`, notVal, targetNodeDef?.properties.get(baseProp), notProp.slice(baseProp.length));
                     let expr;
                     if (template === '%v = $%p')
                         // Simple equality → negate to <>
-                        expr = `${targetVar}.${escapedProp} <> $${paramName}`;
+                        expr = `${targetVar}.${escapedProp} <> ${paramRef}`;
                     else {
                         // Operator suffix — wrap with NOT if not already negated
                         const resolved = template
                             .replace('%v', `${targetVar}.${escapedProp}`)
-                            .replace('$%p', `$${paramName}`);
+                            .replace('$%p', paramRef);
                         expr = resolved.startsWith('NOT ') ? resolved : `NOT ${resolved}`;
                     }
                     conditions.push(expr);
@@ -1274,9 +1365,10 @@ class MutationCompiler {
                 const { baseProp, template } = this.parseOperatorSuffix(prop);
                 (0, validation_1.assertSafePropertyName)(baseProp, 'where property');
                 const paramName = `${prefix}_${prop}`;
+                const paramRef = (0, write_coercion_1.wrapTemporalWhereParam)(`$${paramName}`, val, targetNodeDef?.properties.get(baseProp), prop.slice(baseProp.length));
                 conditions.push(template
                     .replace('%v', `${targetVar}.${(0, validation_1.escapeIdentifier)(baseProp)}`)
-                    .replace('$%p', `$${paramName}`));
+                    .replace('$%p', paramRef));
                 params[paramName] = val;
             }
         return conditions;
@@ -1441,7 +1533,7 @@ class MutationCompiler {
         }
         return false;
     }
-    extractConnectWhereConditions(item, targetVar, itemVar) {
+    extractConnectWhereConditions(item, targetVar, itemVar, targetNodeDef) {
         const conditions = [];
         const whereSpec = item.where;
         if (!whereSpec)
@@ -1452,7 +1544,9 @@ class MutationCompiler {
             (0, validation_1.assertSafePropertyName)(baseProp, 'connect where property');
             // Replace template placeholders with dynamic UNWIND references
             // Note: itemVar map access is NOT escaped (parameter map keys, not Cypher identifiers)
-            const valueRef = `${itemVar}.where.node.${key}`;
+            // Temporal wrap keys off the FIRST item's value type — the UNWIND
+            // fast path already requires shape-homogeneous items.
+            const valueRef = (0, write_coercion_1.wrapTemporalWhereParam)(`${itemVar}.where.node.${key}`, nodeWhere[key], targetNodeDef?.properties.get(baseProp), key.slice(baseProp.length));
             conditions.push(template
                 .replace('%v', `${targetVar}.${(0, validation_1.escapeIdentifier)(baseProp)}`)
                 .replace('$%p', valueRef));