Skip to content

Commit d850be1

Browse files
committed
test(objectql): red pins for an extension's fieldPatches on every object read; the field-patch target judge
Claude-Session: https://claude.ai/code/session_01FEkQ5nSMgkteiemkoN31vf Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2678600 commit d850be1

3 files changed

Lines changed: 412 additions & 0 deletions

File tree

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [ADR-0146 D10, second rule] The TARGET CHECK of an object extension's
5+
* `fieldPatches`: does the object it extends have every field it patches, and
6+
* every option value it patches under `options`?
7+
*
8+
* The slot's SHAPE is the spec's (`ObjectExtensionSchema.fieldPatches`, keys
9+
* derived from `BASE_FIELD_DISPLAY_WHITELIST`); whether the names it uses exist
10+
* is a question about the target, so it is answered where the target is known.
11+
* One judge, three readers:
12+
*
13+
* - the marketplace install door (`POST /api/v1/marketplace/install-local`)
14+
* REFUSES a package whose patch names what its installed target lacks —
15+
* ADR-0141 D2 admitted the base first, so the target is in the registry;
16+
* - `os validate` REFUSES the same patch when the target is in the composed
17+
* stack;
18+
* - the registry fold (`@objectstack/objectql`, `SchemaRegistry`) does not
19+
* apply such a patch and NAMES it once in the log. ⛔ Never a boot refusal:
20+
* a boot is still filling the registry when the fold first runs (AGENTS.md
21+
* *Startup registry reads*), and the patch applies the moment the field
22+
* arrives.
23+
*
24+
* A patch that names a field the target does not have would otherwise change
25+
* nothing, and say nothing: the author reads "Sector" in their package and the
26+
* screen keeps "Industry".
27+
*
28+
* Pure: reads plain bodies and returns findings, so each reader decides what a
29+
* finding means at its door.
30+
*/
31+
32+
/** One name a field patch uses that its target object does not have. */
33+
export interface FieldPatchTargetMiss {
34+
/** The extended object, as the extension names it (`extend`). */
35+
object: string;
36+
/** The patched field — the key under `fieldPatches`. */
37+
field: string;
38+
/** The patched option's stored value — the key under the patch's `options` — when the miss is an option. */
39+
option?: string;
40+
/**
41+
* What is missing: `field` (no such field), `option` (no option with that
42+
* stored value), or `picklist-option` (the field takes its options from a
43+
* picklist, which no field patch reaches).
44+
*/
45+
reason: 'field' | 'option' | 'picklist-option';
46+
/** The sentence an author is shown: what is missing, and what to write instead. */
47+
message: string;
48+
}
49+
50+
/** A {@link FieldPatchTargetMiss} located in the manifest that declares it. */
51+
export interface FieldPatchTargetRefusal extends FieldPatchTargetMiss {
52+
/** Where the patch sits, e.g. `objectExtensions[0].fieldPatches.industry.options.tech`. */
53+
path: string;
54+
}
55+
56+
const isRecord = (v: unknown): v is Record<string, unknown> =>
57+
v !== null && typeof v === 'object' && !Array.isArray(v);
58+
59+
/** A field of an object body, by name — a name-keyed record or a `name`-bearing array, the two spellings a body carries. */
60+
function fieldOf(target: unknown, name: string): Record<string, unknown> | undefined {
61+
if (!isRecord(target)) return undefined;
62+
const fields = target.fields;
63+
if (Array.isArray(fields)) {
64+
const found = fields.find((f) => isRecord(f) && f.name === name);
65+
return isRecord(found) ? found : undefined;
66+
}
67+
if (!isRecord(fields) || !Object.prototype.hasOwnProperty.call(fields, name)) return undefined;
68+
const field = fields[name];
69+
return isRecord(field) ? field : undefined;
70+
}
71+
72+
/** The stored values of a field's own `options`, in order. */
73+
function optionValuesOf(field: Record<string, unknown>): string[] {
74+
const options = field.options;
75+
if (!Array.isArray(options)) return [];
76+
return options
77+
.map((o) => (isRecord(o) ? o.value : undefined))
78+
.filter((v): v is string => typeof v === 'string');
79+
}
80+
81+
/**
82+
* Every name `fieldPatches` uses that `target` does not have. `[]` when the
83+
* patch is absent, malformed (the schema's parse reports that), or fully
84+
* matched.
85+
*
86+
* `target` is the extended object as the reader sees it: the registry's
87+
* resolved object at the install door and in the fold, the composed stack's
88+
* declaration at `os validate`.
89+
*/
90+
export function fieldPatchTargetMisses(object: string, fieldPatches: unknown, target: unknown): FieldPatchTargetMiss[] {
91+
if (!isRecord(fieldPatches)) return [];
92+
const misses: FieldPatchTargetMiss[] = [];
93+
for (const [fieldName, patch] of Object.entries(fieldPatches)) {
94+
const field = fieldOf(target, fieldName);
95+
if (!field) {
96+
misses.push({
97+
object,
98+
field: fieldName,
99+
reason: 'field',
100+
message:
101+
`\`fieldPatches.${fieldName}\` names a field object \`${object}\` does not have, so the patch would ` +
102+
`change nothing. A field patch changes the display of one of the extended object's own fields: ` +
103+
`use the name of a field \`${object}\` declares, or declare a field of your own in \`fields\`.`,
104+
});
105+
continue;
106+
}
107+
const options = isRecord(patch) ? patch.options : undefined;
108+
if (!isRecord(options)) continue;
109+
const picklist = typeof field.picklist === 'string' && field.picklist !== '' ? field.picklist : undefined;
110+
const values = optionValuesOf(field);
111+
for (const value of Object.keys(options)) {
112+
if (picklist !== undefined) {
113+
misses.push({
114+
object,
115+
field: fieldName,
116+
option: value,
117+
reason: 'picklist-option',
118+
message:
119+
`\`fieldPatches.${fieldName}.options.${value}\` patches an option of \`${object}.${fieldName}\`, ` +
120+
`which takes its options from the picklist \`${picklist}\`: the option labels are the picklist's, ` +
121+
`and a field patch never reaches them. Remove \`options\` from this patch.`,
122+
});
123+
continue;
124+
}
125+
if (values.includes(value)) continue;
126+
misses.push({
127+
object,
128+
field: fieldName,
129+
option: value,
130+
reason: 'option',
131+
message:
132+
`\`fieldPatches.${fieldName}.options.${value}\` names an option \`${object}.${fieldName}\` does not ` +
133+
`have: an option is addressed by its stored \`value\`, and this field's are ` +
134+
`${values.length > 0 ? values.map((v) => `\`${v}\``).join(', ') : 'none'}. ` +
135+
'Which options exist stays the vendor\'s, so a patch can only relabel one of them.',
136+
});
137+
}
138+
}
139+
return misses;
140+
}
141+
142+
/**
143+
* Every patch in a manifest's `objectExtensions` that names what its target
144+
* lacks, located. An entry whose target `getTarget` does not know is not
145+
* judged: at the install door that target is ADR-0141 D2's to answer, and at
146+
* `os validate` a target outside the composed stack is judged at install.
147+
*
148+
* `pathPrefix` locates the entries for a multi-package artifact
149+
* (`packages[1].manifest.`); empty for a single stack.
150+
*/
151+
export function fieldPatchTargetRefusals(
152+
objectExtensions: unknown,
153+
getTarget: (name: string) => unknown,
154+
pathPrefix = '',
155+
): FieldPatchTargetRefusal[] {
156+
if (!Array.isArray(objectExtensions)) return [];
157+
const refusals: FieldPatchTargetRefusal[] = [];
158+
objectExtensions.forEach((entry, index) => {
159+
if (!isRecord(entry) || typeof entry.extend !== 'string' || !isRecord(entry.fieldPatches)) return;
160+
const target = getTarget(entry.extend);
161+
if (target === undefined || target === null) return;
162+
for (const miss of fieldPatchTargetMisses(entry.extend, entry.fieldPatches, target)) {
163+
const at = `${pathPrefix}objectExtensions[${index}].fieldPatches.${miss.field}`;
164+
refusals.push({ ...miss, path: miss.option === undefined ? at : `${at}.options.${miss.option}` });
165+
}
166+
});
167+
return refusals;
168+
}
169+
170+
/**
171+
* The install door's refusal sentence for a non-empty
172+
* {@link fieldPatchTargetRefusals} answer: how many, the first one whole, and
173+
* that nothing was installed. Every refusal is listed in the answer's
174+
* `details.refusals`.
175+
*/
176+
export function fieldPatchTargetRefusalMessage(packageId: string, refusals: readonly FieldPatchTargetRefusal[]): string {
177+
const n = refusals.length;
178+
return (
179+
`Package '${packageId}' cannot be installed: ${n} field patch${n > 1 ? 'es name' : ' names'} a field or option ` +
180+
`the extended object does not have (ADR-0146 D10). ${refusals[0]?.path}: ${refusals[0]?.message}` +
181+
(n > 1 ? ` (${n - 1} more in \`details.refusals\`.)` : '') +
182+
' Nothing was installed or written.'
183+
);
184+
}

‎packages/metadata-core/src/index.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,3 +144,9 @@ export * from './anonymous-form-intake.js';
144144
// load-time diagnostics (`@objectstack/metadata-protocol`), so the diagnostics
145145
// judge a field as its author wrote it.
146146
export * from './resolved-picklist-options.js';
147+
148+
// [ADR-0146 D10, second rule] The target check of an object extension's
149+
// `fieldPatches` — one judge for the marketplace install door, `os validate`
150+
// and the registry fold's boot log, so the three cannot disagree about which
151+
// patch names a field or option its target lacks.
152+
export * from './extension-field-patch-targets.js';

0 commit comments

Comments
 (0)