Skip to content

Commit 834abfd

Browse files
committed
fix(lint)!: judge a roll-up's summaryOperations.filter keys against its child object
The engine runs `summaryOperations.filter` as the where of an aggregate on the child object, ANDed with the parent-FK match. A key the child lacks makes every child write answer SummaryRecomputeError while the summary keeps a stale value (measured on a real SqlDriver), and no authoring door judged the keys: one field's parse cannot see another object's field map. validateObjectFieldRefs gains the position: every filter key, walked by walkFilterFieldKeys ($and / $or / $not groups, operator objects, relationship paths), is resolved against the child that summaryOperations.object names, with the family's skips and its "Did you mean" verdict. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FEkQ5oEQNYg7j3ueo5t6pV
1 parent 11c1326 commit 834abfd

5 files changed

Lines changed: 145 additions & 1 deletion

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
'@objectstack/lint': minor
3+
---
4+
5+
fix(lint)!: a roll-up summary whose `summaryOperations.filter` names a key its child object lacks is refused at build and publish (`object-field-ref-unknown`), because every child write then fails its recompute
6+
7+
Clause-②: no (narrowing) — `os validate`, `os build`, `os lint` and the object save and publish doors refuse a summary field they accepted before. No export is added: the position joins the existing `object-field-ref-unknown` rule.
8+
Metadata-protocol: narrowed
9+
Skills-docs: none — `skills/**` and `content/docs/**` teach `summaryOperations.filter` keys that are fields of the child object, which this rule accepts. The reasoning ships in the `os explain object-field-ref-unknown` entry.
10+
11+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed or renamed: summaryOperations.filter keeps its shape and meaning, and lint now judges its keys against the child object the way lookupFilters[].field is judged against the referenced one. A refused key never filtered what the author meant (every child write answered a recompute failure and the summary stayed stale), so there is no rewrite that keeps the author's intent: the author names a real child field, and the verdict names the nearest one. -->
12+
13+
**BREAKING** accept-set narrowing in `os validate` / `os build` / `os lint` and at the object save and publish doors (`PUT /api/v1/meta/object/NAME` live save, the per-item and package publish; Studio, REST and MCP authors), through the `object-field-ref-unknown` rule.
14+
15+
- **Before.** A summary field with `summaryOperations: { object: 'invoice_line', function: 'sum', field: 'amount', filter: { stauts: 'paid' } }` parsed, built and published. The engine runs the filter as the `where` of an aggregate on the child, ANDed with the parent-FK match. Measured on a real `SqlDriver` (better-sqlite3): every insert of a child row then answered `SummaryRecomputeError` ("the triggering records WERE written"), and the summary kept a stale value.
16+
- **Now.** Each key the child lacks is refused `error` at `objects[i].fields.FIELD.summaryOperations.filter.KEY`, naming the key, the child object and the nearest field ("Did you mean"). Keys inside `$and` / `$or` / `$not` groups and past operator objects are judged too, and a relationship path is resolved through the child.
17+
- **Not judged.** A child object the stack does not define, a child with no readable field map, and a registry-injected system column (resolved per object), the same skips every position of this rule takes.
18+
19+
**What an author does.** Nothing for a filter whose keys are fields of the child object. For a refused key: name the child field you meant (the verdict suggests the nearest one), or drop the key.

‎packages/lint/src/rule-explanations.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4249,6 +4249,12 @@ const OBJECT_FIELD_REF_UNKNOWN_EXPLANATION: RuleExplanation = {
42494249
'(the picker scopes its candidates by that key). The referenced object is judged only on ' +
42504250
'`lookup`, `master_detail` and `user` fields, the types that render the picker, and a bare ' +
42514251
'`dependsOn` name that misses on the owning object is reported once, there.',
4252+
'A summary field\'s `summaryOperations.filter` is judged against the CHILD object ' +
4253+
'`summaryOperations.object` names: the engine ANDs it with the parent-FK match and runs it as the ' +
4254+
'query on that child, so every key (inside `$and` / `$or` / `$not` groups and operator objects, ' +
4255+
'or a relationship path) is a field of the child. A key the child lacks makes every child write ' +
4256+
'answer a roll-up recompute failure (the row is still written) while the summary keeps a stale ' +
4257+
'value.',
42524258
'`lookupColumns`, `dependsOn` and `indexes[].fields` are read verbatim (a picker column key, a ' +
42534259
'record key, a physical column), so a dotted name there is one name no field carries; the ' +
42544260
'other positions resolve a relationship path. Not judged: an object this stack does not ' +

‎packages/lint/src/validate-object-field-refs.test.ts‎

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -532,6 +532,64 @@ describe('validateObjectFieldRefs — lookupFilters[].field (addresses the REFER
532532
});
533533
});
534534

535+
describe('validateObjectFieldRefs — summaryOperations.filter (addresses the CHILD object, #31224)', () => {
536+
// `crm_account` is the parent; `crm_invoice` (with an FK to it) the child.
537+
const rollup = (filter: unknown, over: Record<string, unknown> = {}) => ({
538+
objects: [
539+
account({
540+
fields: {
541+
...account().fields,
542+
billed: { type: 'summary', summaryOperations: { object: 'crm_invoice', field: 'total', function: 'sum', filter, ...over } },
543+
},
544+
}),
545+
invoice({ account: lookup() }),
546+
],
547+
});
548+
549+
it('REFUSES a misspelt key against the child object, at its path, as an error', () => {
550+
const findings = validateObjectFieldRefs(rollup({ regoin: 'emea' }));
551+
expect(findings).toHaveLength(1);
552+
expect(findings[0]).toMatchObject({
553+
severity: 'error',
554+
rule: OBJECT_FIELD_REF_UNKNOWN,
555+
path: 'objects[0].fields.billed.summaryOperations.filter.regoin',
556+
});
557+
expect(findings[0]!.message).toContain('"regoin" is not a field on object "crm_invoice"');
558+
expect(findings[0]!.message).toContain('Did you mean "region"');
559+
expect(findings[0]!.hint).toContain('runs on the child object `summaryOperations.object` names');
560+
});
561+
562+
it('REFUSES a key only the PARENT (the object owning the summary) has', () => {
563+
const findings = validateObjectFieldRefs(rollup({ industry: 'saas' }));
564+
expect(findings.map((f) => f.path)).toEqual(['objects[0].fields.billed.summaryOperations.filter.industry']);
565+
});
566+
567+
it('walks $and / $or / $not groups and reads past operator objects', () => {
568+
const findings = validateObjectFieldRefs(rollup({
569+
$and: [{ total: { $gte: 100 } }, { $or: [{ region: 'emea' }, { stauts: 'paid' }] }],
570+
$not: { isssued_on: { $lt: '2026-01-01' } },
571+
}));
572+
expect(findings.map((f) => f.path)).toEqual([
573+
'objects[0].fields.billed.summaryOperations.filter.$and[1].$or[1].stauts',
574+
'objects[0].fields.billed.summaryOperations.filter.$not.isssued_on',
575+
]);
576+
});
577+
578+
it('passes child fields, operators, and a relationship path through the child', () => {
579+
expect(validateObjectFieldRefs(rollup({
580+
total: { $gt: 0 },
581+
issued_on: { $gte: '2026-01-01' },
582+
region: { $in: ['emea', 'apac'] },
583+
'account.status': 'active',
584+
}))).toEqual([]);
585+
});
586+
587+
it('does not judge a filter whose child the stack does not define, or a roll-up with no filter', () => {
588+
expect(validateObjectFieldRefs(rollup({ anything: 1 }, { object: 'elsewhere_line' }))).toEqual([]);
589+
expect(validateObjectFieldRefs(rollup(undefined))).toEqual([]);
590+
});
591+
});
592+
535593
describe('validateObjectFieldRefs — dependsOn (the gate on the OWNER, the filter on the REFERENCE)', () => {
536594
it('REFUSES a misspelt name in the string arm against the owning object — once, not twice', () => {
537595
const findings = validateObjectFieldRefs(twoObjects({
@@ -755,6 +813,7 @@ describe('[#22161] one-line verdicts — object-field-ref-unknown', () => {
755813
'.lookupColumns[',
756814
'.lookupFilters[',
757815
'.dependsOn[',
816+
'.summaryOperations.filter.',
758817
]) {
759818
expect(converted.some((f) => f.path.includes(position)), position).toBe(true);
760819
}
@@ -773,7 +832,7 @@ describe('[#22161] one-line fix — object-field-ref-unknown', () => {
773832
const converted = fired.filter((f) => f.rule === OBJECT_FIELD_REF_UNKNOWN);
774833
// Coverage control: every position fired (the verdict block above names
775834
// them), so the bound reads each prescription.
776-
for (const position of ['.highlightFields[', '.publicSharing.redactFields[', '.indexes[', '.relatedListColumns[', '.lookupColumns[', '.lookupFilters[', '.dependsOn[']) {
835+
for (const position of ['.highlightFields[', '.publicSharing.redactFields[', '.indexes[', '.relatedListColumns[', '.lookupColumns[', '.lookupFilters[', '.dependsOn[', '.summaryOperations.filter.']) {
777836
expect(converted.some((f) => f.path.includes(position)), position).toBe(true);
778837
}
779838
for (const f of converted) {

‎packages/lint/src/validate-object-field-refs.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,17 @@
103103
* - **`lookupFilters[].field`** — the picker's base filter.
104104
* - **`dependsOn[]`** (both arms: a name, or `{ field, param }`) — the fields
105105
* whose values gate this field and, on a picker, scope its candidates.
106+
* - **`summaryOperations.filter`** — every field key of a roll-up's child-row
107+
* predicate (#31224), walked by `walkFilterFieldKeys` (`$and` / `$or` /
108+
* `$not` groups, operator objects, nested relationship hops). Judged
109+
* against the CHILD object `summaryOperations.object` names, never the
110+
* object that owns the summary field: the engine ANDs the filter with the
111+
* parent-FK match and runs it as the `where` of an aggregate on the child
112+
* (`summary-aggregate.ts` `aggregateSummaryValue`). Measured on a real
113+
* `SqlDriver` (better-sqlite3): a key the child lacks makes every child
114+
* insert answer `SummaryRecomputeError` (the row IS written) and the
115+
* roll-up keeps its stale value; the parse cannot see it, because one
116+
* field's Zod parse has no view of another object's field map.
106117
*
107118
* ## Which object a field-level name addresses — measured on each reader
108119
*
@@ -218,6 +229,7 @@ import {
218229
type FieldPathVerdict,
219230
type ObjectGraph,
220231
} from './object-graph.js';
232+
import { walkFilterFieldKeys } from './filter-walk.js';
221233

222234
/**
223235
* A field-name list entry — object-level, or on one of the object's fields —
@@ -438,6 +450,14 @@ const FIELD_NAME_SLOTS: readonly FieldNameSlot[] = [
438450
},
439451
];
440452

453+
/**
454+
* The hint at a roll-up filter key (#31224): the position's remedy, one line.
455+
* The verdict's "Did you mean" names the nearest field of the child.
456+
*/
457+
const SUMMARY_FILTER_PRESCRIPTION =
458+
'Fix the key — `summaryOperations.filter` runs on the child object `summaryOperations.object` '
459+
+ 'names, so each key is a field of that child, not of the object that owns this summary.';
460+
441461
/**
442462
* {@link resolveFieldPath}, or — at a position whose reader takes the name
443463
* verbatim — the one-name verdict: a dotted name there is not a path to walk,
@@ -602,6 +622,24 @@ export function validateObjectFieldRefs(stack: AnyRec): ObjectFieldRefFinding[]
602622
if (hit) reported.add(`${at}=${read.name}`);
603623
});
604624
}
625+
626+
// ── fields.<f>.summaryOperations.filter — keys of the CHILD (#31224) ──
627+
const ops = isRec(field.summaryOperations) ? field.summaryOperations : undefined;
628+
const child = ops ? nameOf(ops.object) : undefined;
629+
if (ops && child && ops.filter !== undefined) {
630+
const filterPath = `${objPath}.fields.${fieldName}.summaryOperations.filter`;
631+
walkFilterFieldKeys(ops.filter, filterPath, (key) => {
632+
judge({
633+
against: child,
634+
name: key.field,
635+
verbatim: false,
636+
subject: key.path.slice(objPath.length + 1),
637+
where: `${label} › fields.${fieldName}.summaryOperations.filter`,
638+
path: key.path,
639+
prescription: SUMMARY_FILTER_PRESCRIPTION,
640+
});
641+
});
642+
}
605643
}
606644
}
607645

‎packages/metadata-protocol/src/protocol.draft-publish-verdict.test.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,28 @@ const CASES: Array<{ rule: string; type: string; item: { name: string } & Record
285285
},
286286
},
287287
},
288+
{
289+
// A roll-up whose child-row filter names a key the child lacks: it
290+
// saved and published, and every child write then answered a roll-up
291+
// recompute failure. Self-referential, so the child is this item.
292+
rule: 'object-field-ref-unknown',
293+
type: 'object',
294+
item: {
295+
name: 'task_tree',
296+
label: 'Task Tree',
297+
sharingModel: 'private',
298+
fields: {
299+
name: { type: 'text', label: 'Name' },
300+
status: { type: 'text', label: 'Status' },
301+
parent: { type: 'lookup', label: 'Parent', reference: 'task_tree' },
302+
open_children: {
303+
type: 'summary',
304+
label: 'Open Children',
305+
summaryOperations: { object: 'task_tree', function: 'count', filter: { stauts: 'open' } },
306+
},
307+
},
308+
},
309+
},
288310
{
289311
// [#29007] The card's reproduction: a `titleFormat` on an object that
290312
// authors no `nameField`. The stamped pointer outranks the template,

0 commit comments

Comments
 (0)