Skip to content

Commit e367968

Browse files
committed
fix(objectql): the fold names a field two contributors declare in fields, with the definition served
The registry fold spreads each extension's fields, so a field name two extensions declare, or an extension redeclaring an owner field, serves the last contribution the fold applies. The fold now writes one warning per object, field and set of packages, naming every declaring package and the one served. The served definition is unchanged. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FEkQ5nbGTknnd7qupVJNmN
1 parent 2cba2eb commit e367968

4 files changed

Lines changed: 301 additions & 4 deletions

File tree

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
'@objectstack/objectql': patch
3+
---
4+
5+
fix(objectql): the object fold names, once, a field that two contributors declare in `fields`, and which definition it serves (#28835)
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The registry fold every object read serves (`getObject`, the by-name and layered reads through `foldObjectExtendersOnto`, the code layer) merges each extension's `fields` by spreading them. So when two extensions of one object both declare a field name, or an extension's `fields` redeclares a field the owner declares, the last contribution the fold applies is served: extensions fold in ascending `priority`, and at equal priority the one registered last wins. Nothing said so. This is reachable from two vendor dependents, from two `.custom` pairs where one base depends on the other, and, since the `object_extension` item door, from Studio.
11+
12+
- **Now.** The first time a fold sees such a field, it writes one `console.warn` line per object, field and set of declaring packages. The line names the object, the field, every declaring package in fold order (the owner first when it declares the field), and the package whose definition is served. Repeated reads in one registry do not repeat it; a second registry says it again. It sits beside the existing line for a field patch that misses its target, in the same style.
13+
- **Unchanged.** The served definition, byte for byte: the same winner as before. No door refuses anything new, and `os validate` and the save and publish doors are not touched.
14+
- **Not counted.** `fieldPatches` entries (they are patches, not declarations, and a patch that misses is already named). A `.custom` pair's `__c` field never shares a name with a dependent's plain field, so the two never meet here.
15+
- **Docs.** `content/docs/data-modeling/object-extensions.mdx` no longer says nothing warns.
16+
- **Measured.** No shipped package or example declares the same field from two extensions, or redeclares an owner field in an extension's `fields`: the two shipped `objectExtensions` entries (`examples/app-showcase` on `showcase_account`, `plugin-auth` on `sys_sso_provider`) each add fields the owner does not declare, and HotCRM declares none.

‎content/docs/data-modeling/object-extensions.mdx‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -152,9 +152,12 @@ it does not walk `objectExtensions`, and it could not — the target's name belo
152152
its owner, not to you.
153153

154154
Nothing therefore stops two packages from contributing the same field name to the same
155-
object, and nothing warns when they do: the merge is last-writer-wins by `priority`, so
156-
one of the two silently disappears. Name defensively — prefix added fields with
157-
something specific to your package when the name is at all generic.
155+
object: the merge is last-writer-wins by `priority`, so one of the two definitions is
156+
not served. The same goes for an extension whose `fields` redeclares a field the owner
157+
declares. Neither is refused; at boot the registry names each such field once in the log,
158+
with every package that declares it and the one whose definition is served. Name
159+
defensively — prefix added fields with something specific to your package when the
160+
name is at all generic.
158161

159162
---
160163

@@ -166,7 +169,7 @@ something specific to your package when the name is at all generic.
166169
last-writer-wins, validations and indexes accumulate.
167170

168171
So a **higher `priority` is applied later and wins** a conflict. Two extensions with the
169-
same priority are folded in registration order, which is not a guarantee to build on —
172+
same priority are folded in registration order (the one registered last wins), which is not a guarantee to build on —
170173
give competing extensions distinct priorities.
171174

172175
Merging is idempotent: re-registering a package (a metadata rebuild, a dev-server
Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#28835] A field name that two contributors of one object both declare in
5+
* `fields` is named once at the fold, with the definition it serves.
6+
*
7+
* `mergeObjectDefinitions` spreads `fields`, so when two extensions of one
8+
* object both add `x`, or an extension's `fields` redeclares a field the owner
9+
* declares, the last contribution the fold applies wins: ascending `priority`,
10+
* and at equal priority the one registered last. That stays the answer (the
11+
* served definition is not changed here); the fold now says so, once per
12+
* object, field and set of packages, in the style of the field-patch miss
13+
* report. `fieldPatches` is not a declaration, and a `.custom` pair's `__c`
14+
* field never shares a name with a dependent's plain one.
15+
*/
16+
17+
import { describe, it, expect, vi, afterEach } from 'vitest';
18+
import { SchemaRegistry } from './registry.js';
19+
20+
const OWNER_PKG = 'com.vendor.crm';
21+
const DEP_A = 'com.acme.crm-territory';
22+
const DEP_B = 'com.globex.crm-regions';
23+
const OBJ = 'crm_account';
24+
25+
function vendorAccount(): any {
26+
return {
27+
name: OBJ,
28+
label: 'Account',
29+
fields: {
30+
name: { name: 'name', type: 'text', label: 'Name' },
31+
industry: {
32+
name: 'industry',
33+
type: 'select',
34+
label: 'Industry',
35+
options: [
36+
{ value: 'tech', label: 'Tech' },
37+
{ value: 'retail', label: 'Retail' },
38+
],
39+
},
40+
},
41+
};
42+
}
43+
44+
function withVendor(): SchemaRegistry {
45+
const reg = new SchemaRegistry({ multiTenant: false, searchCompanion: false } as never);
46+
reg.logLevel = 'silent';
47+
reg.registerObject(vendorAccount(), OWNER_PKG, undefined, 'own');
48+
return reg;
49+
}
50+
51+
function extendWith(reg: SchemaRegistry, pkg: string, body: Record<string, unknown>, priority = 200): void {
52+
reg.registerObject({ name: OBJ, ...body } as any, pkg, undefined, 'extend', priority);
53+
}
54+
55+
const regionOf = (pkg: string) => ({ name: 'region', type: 'text', label: `Region (${pkg})` });
56+
57+
/** The fold's lines about a field declared more than once. */
58+
function redeclaredLines(warn: { mock: { calls: unknown[][] } }): string[] {
59+
return warn.mock.calls.map((c) => String(c[0])).filter((l) => l.includes('is declared in `fields` by'));
60+
}
61+
62+
/** Every read the fold serves, three times over, with the cache dropped between. */
63+
function readEverywhere(reg: SchemaRegistry): void {
64+
for (let i = 0; i < 3; i += 1) {
65+
reg.invalidateAll();
66+
reg.getObject(OBJ);
67+
reg.foldObjectExtendersOnto(OBJ, vendorAccount());
68+
reg.getArtifactItem('object', OBJ);
69+
}
70+
}
71+
72+
afterEach(() => {
73+
vi.restoreAllMocks();
74+
});
75+
76+
describe('#28835 — a field two contributors declare in `fields` is named once at the fold, with the definition served', () => {
77+
it('two dependents both add `region` at equal priority: the one registered last is served, and one line names both and the served one', () => {
78+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
79+
const reg = withVendor();
80+
extendWith(reg, DEP_A, { fields: { region: regionOf(DEP_A) } });
81+
extendWith(reg, DEP_B, { fields: { region: regionOf(DEP_B) } });
82+
83+
const served = reg.getObject(OBJ) as any;
84+
expect(served.fields.region).toEqual(regionOf(DEP_B));
85+
readEverywhere(reg);
86+
87+
const lines = redeclaredLines(warn);
88+
expect(lines).toHaveLength(1);
89+
expect(lines[0]).toContain(`Field "region" of object "${OBJ}"`);
90+
expect(lines[0]).toContain(`extensions from "${DEP_A}", "${DEP_B}"`);
91+
expect(lines[0]).toContain(`the definition served is the one from "${DEP_B}"`);
92+
expect(lines[0]).not.toContain(OWNER_PKG);
93+
});
94+
95+
it('…by priority, not registration order: the higher-priority dependent registered first is the one served and named', () => {
96+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
97+
const reg = withVendor();
98+
extendWith(reg, DEP_A, { fields: { region: regionOf(DEP_A) } }, 300);
99+
extendWith(reg, DEP_B, { fields: { region: regionOf(DEP_B) } }, 200);
100+
101+
expect((reg.getObject(OBJ) as any).fields.region).toEqual(regionOf(DEP_A));
102+
const lines = redeclaredLines(warn);
103+
expect(lines).toHaveLength(1);
104+
expect(lines[0]).toContain(`extensions from "${DEP_B}", "${DEP_A}"`);
105+
expect(lines[0]).toContain(`the definition served is the one from "${DEP_A}"`);
106+
});
107+
108+
it('an extension redeclaring a field the owner declares: the extension\'s definition is served, and one line names the owner, the extension and the served one', () => {
109+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
110+
const reg = withVendor();
111+
const takeover = { name: 'industry', type: 'text', label: 'Industry (free text)' };
112+
extendWith(reg, DEP_A, { fields: { industry: takeover } });
113+
114+
expect((reg.getObject(OBJ) as any).fields.industry).toEqual(takeover);
115+
readEverywhere(reg);
116+
117+
const lines = redeclaredLines(warn);
118+
expect(lines).toHaveLength(1);
119+
expect(lines[0]).toContain(`Field "industry" of object "${OBJ}"`);
120+
expect(lines[0]).toContain(`the owner "${OWNER_PKG}" and by extensions from "${DEP_A}"`);
121+
expect(lines[0]).toContain(`the definition served is the one from "${DEP_A}"`);
122+
});
123+
124+
it('the owner and two extensions on one field: one line naming all three in fold order', () => {
125+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
126+
const reg = withVendor();
127+
extendWith(reg, DEP_A, { fields: { industry: { name: 'industry', type: 'text', label: 'A' } } });
128+
extendWith(reg, DEP_B, { fields: { industry: { name: 'industry', type: 'text', label: 'B' } } });
129+
130+
expect((reg.getObject(OBJ) as any).fields.industry.label).toBe('B');
131+
const lines = redeclaredLines(warn);
132+
expect(lines).toHaveLength(1);
133+
expect(lines[0]).toContain(`the owner "${OWNER_PKG}" and by extensions from "${DEP_A}", "${DEP_B}"`);
134+
expect(lines[0]).toContain(`the definition served is the one from "${DEP_B}"`);
135+
});
136+
137+
it('two `.custom` pairs (one base depending on the other) both adding `region__c`: named like any two extensions', () => {
138+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
139+
const reg = withVendor();
140+
extendWith(reg, `${OWNER_PKG}.custom`, { fields: { region__c: { name: 'region__c', type: 'text', label: 'One' } } });
141+
extendWith(reg, `${DEP_A}.custom`, { fields: { region__c: { name: 'region__c', type: 'text', label: 'Two' } } });
142+
143+
expect((reg.getObject(OBJ) as any).fields.region__c.label).toBe('Two');
144+
const lines = redeclaredLines(warn);
145+
expect(lines).toHaveLength(1);
146+
expect(lines[0]).toContain(`the definition served is the one from "${DEP_A}.custom"`);
147+
});
148+
149+
it('a second registry names the same collision again', () => {
150+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
151+
for (let i = 0; i < 2; i += 1) {
152+
const reg = withVendor();
153+
extendWith(reg, DEP_A, { fields: { region: regionOf(DEP_A) } });
154+
extendWith(reg, DEP_B, { fields: { region: regionOf(DEP_B) } });
155+
readEverywhere(reg);
156+
}
157+
expect(redeclaredLines(warn)).toHaveLength(2);
158+
});
159+
160+
describe('controls: nothing is named', () => {
161+
it('one extension adding a field of its own', () => {
162+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
163+
const reg = withVendor();
164+
extendWith(reg, DEP_A, { fields: { region: regionOf(DEP_A) } });
165+
readEverywhere(reg);
166+
expect((reg.getObject(OBJ) as any).fields.region).toEqual(regionOf(DEP_A));
167+
expect(redeclaredLines(warn)).toEqual([]);
168+
});
169+
170+
it('a pair\'s `__c` field beside a dependent\'s plain field of the same stem', () => {
171+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
172+
const reg = withVendor();
173+
extendWith(reg, `${OWNER_PKG}.custom`, { fields: { region__c: { name: 'region__c', type: 'text', label: 'Mine' } } });
174+
extendWith(reg, DEP_A, { fields: { region: regionOf(DEP_A) } });
175+
readEverywhere(reg);
176+
const served = reg.getObject(OBJ) as any;
177+
expect(served.fields.region__c.label).toBe('Mine');
178+
expect(served.fields.region).toEqual(regionOf(DEP_A));
179+
expect(redeclaredLines(warn)).toEqual([]);
180+
});
181+
182+
it('a `fieldPatches` entry of an owner field, beside an extension adding a field', () => {
183+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
184+
const reg = withVendor();
185+
extendWith(reg, DEP_A, { fieldPatches: { industry: { label: 'Sector' } } });
186+
extendWith(reg, DEP_B, { fields: { region: regionOf(DEP_B) }, fieldPatches: { industry: { label: 'Market' } } });
187+
readEverywhere(reg);
188+
expect((reg.getObject(OBJ) as any).fields.industry.label).toBe('Market');
189+
expect(redeclaredLines(warn)).toEqual([]);
190+
});
191+
192+
it('a base that already carries the extensions\' fields (a folded body handed back to the fold)', () => {
193+
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
194+
const reg = withVendor();
195+
extendWith(reg, DEP_A, { fields: { region: regionOf(DEP_A) } });
196+
const folded = reg.getObject(OBJ) as any;
197+
reg.foldObjectExtendersOnto(OBJ, structuredClone(folded));
198+
reg.foldObjectExtendersOnto(OBJ, structuredClone(folded));
199+
expect(redeclaredLines(warn)).toEqual([]);
200+
});
201+
});
202+
});

‎packages/objectql/src/registry.ts‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -512,6 +512,9 @@ type ObjectFieldPatches = NonNullable<ObjectExtensionParsed['fieldPatches']>;
512512
/** An `extend` contributor's body: a partial object that may carry {@link ObjectFieldPatches}. */
513513
type ObjectExtensionBody = Partial<ServiceObject> & { fieldPatches?: ObjectFieldPatches };
514514

515+
/** [#28835] One extension's `fields` as the fold merged them, with the package that declared them. */
516+
type FoldedExtensionFields = { packageId: string | undefined; fields: unknown };
517+
515518
const isPlainRecord = (v: unknown): v is Record<string, unknown> =>
516519
v !== null && typeof v === 'object' && !Array.isArray(v);
517520

@@ -4581,14 +4584,18 @@ export class SchemaRegistry {
45814584
let merged = tenantRules
45824585
? this.withPackagedOwnerRules(contributors, baseDefinition, tenantRules)
45834586
: { ...baseDefinition };
4587+
// [#28835] Each extension's `fields` as the merge took them, in fold order.
4588+
const folded: FoldedExtensionFields[] = [];
45844589
for (const contrib of contributors) {
45854590
if (contrib.ownership === 'extend') {
45864591
let extension = governAudit ? applyAuditFieldGovernance(contrib.definition) : contrib.definition;
45874592
if (governQueue) extension = this.withoutExtensionQueueField(extension, contrib.packageId);
45884593
merged = mergeObjectDefinitions(merged, extension, tenantAuthored, tenantRules, tenantPatched, ownFields);
45894594
this.reportFieldPatchMisses(merged, extension, contrib.packageId, ownFields);
4595+
folded.push({ packageId: contrib.packageId, fields: extension.fields });
45904596
}
45914597
}
4598+
this.reportRedeclaredFields(String(merged.name ?? baseDefinition.name ?? ''), contributors, ownFields, folded);
45924599
if (tenantRules) this.reportChangedRuleCopies(contributors, baseDefinition);
45934600
// A picklist-bound field is served with its list's options resolved onto
45944601
// it — here, in the fold every object read and the write door share, so
@@ -4603,6 +4610,75 @@ export class SchemaRegistry {
46034610
*/
46044611
private fieldPatchMissesWarned = new Set<string>();
46054612

4613+
/**
4614+
* [#28835] Field names already named as declared by more than one
4615+
* contributor, keyed `object|field|packages` (the packages in fold order).
4616+
* Per registry, for the reason {@link shadowedExtensionQueueWarned} gives.
4617+
*/
4618+
private redeclaredFieldsWarned = new Set<string>();
4619+
4620+
/**
4621+
* [#28835] Name, once, each field name of the object that more than one
4622+
* contributor declares in `fields`: two extensions both adding it, or an
4623+
* extension redeclaring a field the owner declares (one of `ownFields`). The
4624+
* merge spreads `fields`, so the definition served is the last one the fold
4625+
* applied: contributions fold in ascending `priority`, and at equal priority
4626+
* in the order they registered, so the one registered last. The line names
4627+
* the object, the field, every declaring package in that order, and the one
4628+
* whose definition is served.
4629+
*
4630+
* Judged from the contributors' own declarations (`folded`, as the merge
4631+
* took them), never from the running body, so a base that already carries
4632+
* the extensions' fields (a folded body handed to
4633+
* {@link foldObjectExtendersOnto}, a stored overlay row) is not read as a
4634+
* redeclaration. `fieldPatches` is not a declaration and is not counted
4635+
* ({@link reportFieldPatchMisses} names a patch that misses). A `.custom`
4636+
* pair's `__c` field and a dependent's plain one never share a name.
4637+
*
4638+
* ⛔ Never a refusal, and the served definition is unchanged: the same
4639+
* reasons as {@link reportFieldPatchMisses} (the fold runs on every read
4640+
* while a boot is still registering packages). At `warn`: one package's
4641+
* definition of the field is not served.
4642+
*/
4643+
private reportRedeclaredFields(
4644+
object: string,
4645+
contributors: readonly ObjectContributor[],
4646+
ownFields: ReadonlySet<string> | undefined,
4647+
folded: readonly FoldedExtensionFields[],
4648+
): void {
4649+
if (folded.length === 0) return;
4650+
const owner = contributors.find((c) => c.ownership === 'own');
4651+
const declarers = new Map<string, Array<{ packageId: string | undefined; owner: boolean }>>();
4652+
for (const { packageId, fields } of folded) {
4653+
if (!isPlainRecord(fields)) continue;
4654+
for (const name of Object.keys(fields)) {
4655+
let list = declarers.get(name);
4656+
if (!list) {
4657+
list = owner && ownFields?.has(name) ? [{ packageId: owner.packageId, owner: true }] : [];
4658+
declarers.set(name, list);
4659+
}
4660+
list.push({ packageId, owner: false });
4661+
}
4662+
}
4663+
const named = (packageId: string | undefined) => (packageId ? `"${packageId}"` : 'a contribution with no package');
4664+
for (const [field, list] of declarers) {
4665+
if (list.length < 2) continue;
4666+
const key = `${object}|${field}|${list.map((d) => d.packageId ?? '').join(',')}`;
4667+
if (this.redeclaredFieldsWarned.has(key)) continue;
4668+
this.redeclaredFieldsWarned.add(key);
4669+
const extenders = list.filter((d) => !d.owner).map((d) => named(d.packageId));
4670+
const declaredBy = list[0]!.owner
4671+
? `the owner ${named(list[0]!.packageId)} and by extensions from ${extenders.join(', ')}`
4672+
: `extensions from ${extenders.join(', ')}`;
4673+
console.warn(
4674+
`[Registry] Field "${field}" of object "${object}" is declared in \`fields\` by ${declaredBy}; ` +
4675+
`the definition served is the one from ${named(list[list.length - 1]!.packageId)}, the last the fold applies ` +
4676+
'(ascending `priority`; at equal priority, the one registered last). Rename the field in one extension, ' +
4677+
'or change an owner field\'s display properties through `fieldPatches` instead of redeclaring it.',
4678+
);
4679+
}
4680+
}
4681+
46064682
/**
46074683
* [ADR-0146 D10, second rule] Name, once, each patch of `extension` the fold
46084684
* could not apply: a field that is not one of the owner's own (absent, or

0 commit comments

Comments
 (0)