fix: propagate includeUnchanged into nested keyed array diffs (v0.17.1)

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@maxjay/patchwork",
- "version": "0.17.0",
+ "version": "0.17.1",
  "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
  "type": "module",
  "main": "dist/index.js",

src/engine.array-semantics.test.ts

@@ -489,3 +489,88 @@ describe('edge cases', () => {
  expect(ops.some(op => op.op === OpType.Remove && (op as any).identity === 'us')).toBe(true);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// diff — includeUnchanged propagation into nested keyed arrays
+//
+// Schema anatomy: orders (keyed by ref) → each order has lineItems (keyed by sku).
+// When diff() is called with includeUnchanged: true for a specific lineItems path,
+// it should return Unchanged ops for every unmodified line item.
+// Bug: diffArrayByKey hard-coded includeUnchanged: false when recursing into
+// matched element pairs, so nested Unchanged ops were never emitted.
+// ---------------------------------------------------------------------------
+
+const ordersSchema = makeNestedSchema('ref', 'sku');
+
+// Convenience: build an engine with one order that has three line items.
+function makeOrdersEngine() {
+	return new Engine<any>(
+ {
+ items: [
+ {
+ ref: 'ORD-1',
+ label: 'First order',
+ children: [
+ { sku: 'ALPHA', qty: 1 },
+ { sku: 'BETA', qty: 2 },
+ { sku: 'GAMMA', qty: 5 },
+ ],
+ },
+ {
+ ref: 'ORD-2',
+ label: 'Second order',
+ children: [
+ { sku: 'DELTA', qty: 3 },
+ ],
+ },
+ ],
+ },
+ { schema: ordersSchema },
+	);
+}
+
+describe('diff — includeUnchanged propagation into nested keyed arrays', () => {
+	it('no changes: diff on child path with includeUnchanged returns Unchanged for every child', () => {
+ const e = makeOrdersEngine();
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+ expect(ops.map((o: any) => o.identity).sort()).toEqual(['ALPHA', 'BETA', 'GAMMA']);
+	});
+
+	it('one child removed: diff returns Remove + Unchanged for remaining children', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // remove ALPHA
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Remove && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+ expect(ops).toHaveLength(3);
+	});
+
+	it('one child added: diff returns Add + Unchanged for existing children', () => {
+ const e = makeOrdersEngine();
+ e.add('$.items[0].children[3]', { sku: 'DELTA-NEW', qty: 9 });
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops.some(o => o.op === OpType.Add && (o as any).identity === 'DELTA-NEW')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'ALPHA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'BETA')).toBe(true);
+ expect(ops.some(o => o.op === OpType.Unchanged && (o as any).identity === 'GAMMA')).toBe(true);
+	});
+
+	it('parent field changed (not the child array): child diff still returns Unchanged for children', () => {
+ const e = makeOrdersEngine();
+ e.replace('$.items[0].label', 'Updated label'); // change parent, not children
+ const ops = e.diff("$.items[0].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(3);
+ expect(ops.every(o => o.op === OpType.Unchanged)).toBe(true);
+	});
+
+	it('second order children are unaffected when only first order changes', () => {
+ const e = makeOrdersEngine();
+ e.delete('$.items[0].children[0]'); // mutate ORD-1 only
+ const ops = e.diff("$.items[1].children", { includeUnchanged: true });
+ expect(ops).toHaveLength(1);
+ expect(ops[0]).toMatchObject({ op: OpType.Unchanged, identity: 'DELTA' });
+	});
+});

src/engine.ts

@@ -447,7 +447,19 @@ export class Engine<T extends JsonValue = JsonValue> {
  this.diffNode(this.base, this.draft, '$', ops, includeUnchanged, cascade, false);
  if (!path) return ops;
  const prefixes = [...new Set([...paths(this.draft, path), ...paths(this.base, path)])];
- return ops.filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+ // Flatten Replace.changes recursively so path filters can reach ops nested inside
+ // changed parent elements (e.g. querying a child keyed array when its parent changed).
+ return this.flattenOpsForFilter(ops).filter(op => prefixes.some(p => isUnderPrefix(opPath(op), p)));
+	}
+
+	private flattenOpsForFilter(ops: DiffOp[]): DiffOp[] {
+ const flat: DiffOp[] = [];
+ for (const op of ops) {
+ flat.push(op);
+ if (op.op === OpType.Replace && op.changes?.length)
+ flat.push(...this.flattenOpsForFilter(op.changes));
+ }
+ return flat;
 	}
 
 	private moveOrCopy(from: string, to: string, isMove: boolean): void {
@@ -635,9 +647,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  const displacement = ordered ? bIndex - aIndex : 0;
 
  const fieldOps: DiffOp[] = [];
- this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, false, cascade, true);
+ this.diffNode(aItem, bItem, `${path}[${bIndex}]`, fieldOps, includeUnchanged, cascade, true);
 
- const fieldsChanged = fieldOps.length > 0;
+ const fieldsChanged = fieldOps.some(op => op.op !== OpType.Unchanged);
  const displaced = displacement !== 0;
 
  if (fieldsChanged) {
@@ -654,6 +666,9 @@ export class Engine<T extends JsonValue = JsonValue> {
  ops.push({ op: OpType.Move, from: `${path}[${aIndex}]`, to: `${path}[${bIndex}]`, identity: id });
  } else if (includeUnchanged) {
  ops.push({ op: OpType.Unchanged, path: `${path}[${bIndex}]`, identity: id, value: bItem, displacement: 0 });
+ // Push nested ops directly so path-filtered queries can reach children
+ // (e.g. diff('$.orders[0].lineItems', {includeUnchanged:true}) when the order itself is unchanged)
+ if (fieldOps.length > 0) ops.push(...fieldOps);
  }
  }
 	}