Skip to content

Commit 5395b22

Browse files
committed
fix(spec): read a stored object_extension row as an objectExtensions entry, and list its refused fieldPatches keys
The stored pass returned an object_extension row untouched because its type mapped to no stack collection, so no conversion or refused-shape detector ran over a stored extension. Map it in the stored-only map, add the REFUSED_STORED_SHAPES detector for object-extension-field-patch-key-grammar-refused, and correct that entry and the #29366 changeset, which said --stored does not list such a row. Claude-Session: https://claude.ai/code/session_01JQwxbXpawDQBhgKU2ssyrw Co-authored-by: Claude <noreply@anthropic.com>
1 parent ff827bc commit 5395b22

7 files changed

Lines changed: 199 additions & 14 deletions

File tree

‎.changeset/29366-field-patches-key-grammar.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,6 @@ Skills-docs: updated here — `content/docs/data-modeling/object-extensions.mdx`
1919
- **Before.** `fieldPatches: { Industry: { label: 'Sector' } }` parsed in `defineStack`, was stored by the save door and booted: the registry fold named the patch once in the log and applied nothing, and `os validate` refused it only when the target object was in the same stack.
2020
- **Now.** One `invalid_key` issue at `fieldPatches.Industry`, naming the grammar and an example. The key schema is the one `ObjectSchema.fields` reads, hoisted to one constant, so the two cannot drift.
2121
- **Unchanged.** A snake_case key parses as before, and a `__c` key is still refused by the `__c` rule with its own prescription.
22-
- **Who sees it.** No extension in this repository's examples, skills, docs or templates writes such a key. A stored `object_extension` row that carries one no longer parses, so the sync names the row (`INVALID_METADATA`) and registers none of it, its `fields` included; its next save is refused until the key is renamed. `os migrate meta --stored` does not list such a row beforehand: the stored pass has no stack collection for an `object_extension` row and hands it back untouched, so check each stored extension's `fieldPatches` keys against the grammar before upgrading.
22+
- **Who sees it.** No extension in this repository's examples, skills, docs or templates writes such a key. A stored `object_extension` row that carries one no longer parses, so the sync names the row (`INVALID_METADATA`) and registers none of it, its `fields` included; its next save is refused until the key is renamed. `os migrate meta --stored` lists such a row beforehand, one TODO for each refused key at `fieldPatches.KEY`, and leaves it as stored for its owner to rename.
2323

2424
**FROM → TO.** `fieldPatches: { Industry: { label: 'Sector' } }` → `fieldPatches: { industry: { label: 'Sector' } }`: key each patch by the name of the field the extended object declares (the key of its `fields` entry), never by its label. The upgrade guide entry is `object-extension-field-patch-key-grammar-refused`.
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
fix(spec): the stored pass reads a stored `object_extension` row as an `objectExtensions` entry, so conversions replay over it and `os migrate meta --stored` lists a `fieldPatches` key no field name can be
6+
7+
Clause-②: no (no accept set moves; the stored pass and the `--stored` listing widen)
8+
9+
Metadata-protocol: none
10+
11+
`applyConversionsToStoredItem` wraps a stored row in the stack collection its type maps to, and returned a row untouched when its type mapped to none. `object_extension` (ADR-0146 D10) mapped to none, so no conversion that walks `objectExtensions` ever ran over a stored extension row at a rehydration seam, and no refused-shape detector could list one: `os migrate meta --stored` read every stored extension as already on protocol.
12+
13+
- **Now.** A stored `object_extension` row is read as one `objectExtensions` entry, beside `translation` in the stored-only map; the manifest-collection maps still carry no `objectExtensions`, because a stack's extensions merge into their targets rather than registering as named items. A stored extension with a `time` default written with a `Z` suffix, for example, is now served without it, with the conversion's notice, as an object row already was.
14+
- **Listed.** `os migrate meta --stored` lists each `fieldPatches` key the extension's own parse refuses as no field name (`Industry`, `Annual Revenue`, `annual-revenue`): one TODO at `fieldPatches.KEY` under the row, naming the extended object, leaving the row as stored. Rename each listed key to the field it meant before upgrading. The upgrade guide entry `object-extension-field-patch-key-grammar-refused` says so instead of naming a manual check.
15+
- **Unchanged.** A canonical extension row passes through by reference, every other row type converts exactly as before, and no schema accepts or refuses anything it did not.

‎packages/spec/src/conversions/refused-shapes.test.ts‎

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest';
44

55
import { FLOW_NODE_SIBLING_EXPRESSION_BLOCKS } from '../automation/flow-node-expression-paths.js';
66
import { flowNodeValueTemplateRefusals } from '../automation/flow-value-slot-template.js';
7-
import { ObjectSchema } from '../data/object.zod.js';
7+
import { ObjectExtensionSchema, ObjectSchema } from '../data/object.zod.js';
88
import { MIGRATIONS_BY_MAJOR } from '../migrations/registry.js';
99
import { ComponentPropsMap } from '../ui/component.zod.js';
1010
import { DashboardSchema } from '../ui/dashboard.zod.js';
@@ -73,6 +73,7 @@ describe('the refused-shape list — registered against the migration chain', ()
7373
'visibility-predicate-has-argument-refused',
7474
'object-duplicate-action-name-refused',
7575
'ui-dashboard-global-filter-duplicate-name-refused',
76+
'object-extension-field-patch-key-grammar-refused',
7677
]);
7778
});
7879

@@ -853,3 +854,58 @@ describe('#29212 — a stored dashboard that declares one global filter key twic
853854
}
854855
});
855856
});
857+
858+
// ── #29554 (the #29366 refusal) ───────────────────────────────────────────
859+
860+
const patchRow = (fieldPatches: Record<string, unknown>) => ({ extend: 'crm_account', fieldPatches });
861+
/** The `invalid_key` issues the extension parse locates at `fieldPatches.KEY`, as `[path, message]`. */
862+
const patchKeyIssues = (row: unknown) => {
863+
const parsed = ObjectExtensionSchema.safeParse(row);
864+
return parsed.success
865+
? []
866+
: parsed.error.issues
867+
.filter((i) => i.code === 'invalid_key' && i.path[0] === 'fieldPatches')
868+
.map((i) => [i.path.join('.'), i.message]);
869+
};
870+
871+
describe('#29554 — a stored object extension whose fieldPatches key cannot be a field name is listed by extension', () => {
872+
it('one TODO per refused key, at fieldPatches.KEY, naming the target; the row is not rewritten', () => {
873+
const row = patchRow({
874+
Industry: { label: 'Sector' },
875+
'annual-revenue': { label: 'Revenue' },
876+
region: { label: 'Territory' },
877+
});
878+
const { item, todos } = storedTodos('object_extension', row);
879+
expect(item).toEqual(row);
880+
expect(todos.map((t) => [t.code, t.conversionId, t.path])).toEqual([
881+
[CONVERSION_TODO_CODE, 'object-extension-field-patch-key-grammar-refused', 'objectExtensions[0].fieldPatches.Industry'],
882+
[CONVERSION_TODO_CODE, 'object-extension-field-patch-key-grammar-refused', 'objectExtensions[0].fieldPatches.annual-revenue'],
883+
]);
884+
const todo = todos[0]!;
885+
expect(todo.reason).toMatch(/^The extension of `crm_account` keys a field patch by `Industry`\. No lossless rewrite:/);
886+
expect(todo.reason).not.toMatch(/#\d{3,}/);
887+
expect(JSON.parse(todo.from)).toEqual({ Industry: { label: 'Sector' } });
888+
});
889+
890+
it('agrees with the refusing door: each listed key is one the extension parse refuses as a key, and no other', () => {
891+
const row = patchRow({ Industry: { label: 'Sector' }, 'Annual Revenue': { label: 'Revenue' }, region: { label: 'R' } });
892+
const { todos } = storedTodos('object_extension', row);
893+
const issues = patchKeyIssues(row);
894+
expect(issues.map(([path]) => path)).toEqual(['fieldPatches.Industry', 'fieldPatches.Annual Revenue']);
895+
expect(todos.map((t) => t.path)).toEqual(issues.map(([path]) => `objectExtensions[0].${path}`));
896+
// The door's own message closes each reason, so the listing says what the parse says.
897+
todos.forEach((t, i) => expect(t.reason.endsWith(issues[i]![1]!)).toBe(true));
898+
});
899+
900+
it('snake_case keys are not listed, and the parse accepts them', () => {
901+
const row = patchRow({ industry: { label: 'Sector' }, annual_revenue: { label: 'Revenue' } });
902+
expect(storedTodos('object_extension', row).todos).toEqual([]);
903+
expect(ObjectExtensionSchema.safeParse(row).success).toBe(true);
904+
});
905+
906+
it('a key on another arm — a customer extension field spelled `__c` — is not listed by this detector', () => {
907+
const row = patchRow({ region__c: { label: 'Territory' } });
908+
expect(storedTodos('object_extension', row).todos).toEqual([]);
909+
expect(patchKeyIssues(row)).toEqual([]);
910+
});
911+
});

‎packages/spec/src/conversions/refused-shapes.ts‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,9 @@
4545
* ({@link externalBindingDatasourceRefusal}), and the one-name-per-action
4646
* judge of the object refinement ({@link duplicateActionNames}), and the
4747
* one-key-per-global-filter judge of the dashboard refinement
48-
* ({@link duplicateGlobalFilterNames}). A site is listed here exactly
48+
* ({@link duplicateGlobalFilterNames}), and the `fieldPatches` key
49+
* grammar of `ObjectExtensionSchema`'s own parse
50+
* ({@link refusedFieldPatchKeys}). A site is listed here exactly
4951
* when that door refuses it. One door lives outside this package: the
5052
* page/view `visibleWhen` rule in `@objectstack/lint` judges a `has()`
5153
* argument on the engine's AST, which this package cannot parse, so its
@@ -69,6 +71,7 @@ import {
6971
} from '../data/controlled-by-parent-master.js';
7072
import { duplicateActionNames } from '../data/duplicate-action-names.js';
7173
import { externalBindingDatasourceRefusal } from '../data/external-binding-datasource.js';
74+
import { ObjectExtensionSchema } from '../data/object.zod.js';
7275
import { ComponentPropsMap } from '../ui/component.zod.js';
7376
import { duplicateGlobalFilterNames } from '../ui/duplicate-global-filter-names.js';
7477
import { ViewDataSchema } from '../ui/view.zod.js';
@@ -584,6 +587,53 @@ const dashboardDuplicateGlobalFilterName: RefusedStoredShape = {
584587
},
585588
};
586589

590+
// ── #29554: an object extension whose `fieldPatches` key cannot be a field name (the #29366 refusal) ──
591+
592+
/**
593+
* The `fieldPatches` keys `ObjectExtensionSchema` refuses as no field name:
594+
* each `invalid_key` issue the extension's own parse locates at
595+
* `fieldPatches.KEY`, with that issue's message. The parse is the door's own,
596+
* the one the save door and the sync that registers stored extensions run, so
597+
* a key is listed here exactly when that parse refuses it as a key.
598+
*/
599+
function refusedFieldPatchKeys(extension: Dict): Array<{ key: string; message: string }> {
600+
if (!isDict(extension.fieldPatches)) return [];
601+
const parsed = ObjectExtensionSchema.safeParse(extension);
602+
if (parsed.success) return [];
603+
const refused: Array<{ key: string; message: string }> = [];
604+
for (const issue of parsed.error.issues) {
605+
if (issue.code !== 'invalid_key' || issue.path.length !== 2 || issue.path[0] !== 'fieldPatches') continue;
606+
const key = issue.path[1];
607+
if (typeof key === 'string') refused.push({ key, message: issue.message });
608+
}
609+
return refused;
610+
}
611+
612+
const objectExtensionFieldPatchKeyGrammar: RefusedStoredShape = {
613+
id: 'object-extension-field-patch-key-grammar-refused',
614+
toMajor: 18,
615+
surface: 'objectExtensions[].fieldPatches — a key outside the snake_case grammar of an object\'s `fields` keys',
616+
detect(stack, report) {
617+
mapCollection(stack, 'objectExtensions', (extension, path) => {
618+
const target = typeof extension.extend === 'string' ? `\`${extension.extend}\`` : 'its target';
619+
for (const { key, message } of refusedFieldPatchKeys(extension)) {
620+
report({
621+
path: `${path}.fieldPatches.${key}`,
622+
from: JSON.stringify({ [key]: (extension.fieldPatches as Dict)[key] }),
623+
reason: `The extension of ${target} keys a field patch by \`${key}\`. `
624+
+ 'No lossless rewrite: re-spelling the key (lower-casing it, turning `-` or a space into `_`) can land '
625+
+ 'on a different field or on none, so which field the patch meant is the author\'s to name. Left as '
626+
+ 'stored, the row no longer parses: the sync that registers stored extensions names it '
627+
+ '(INVALID_METADATA) and registers none of it, its `fields` included, and its next save is refused '
628+
+ 'until the key is renamed to the field it meant. '
629+
+ message,
630+
});
631+
}
632+
return extension;
633+
});
634+
},
635+
};
636+
587637
/**
588638
* Every refused stored shape, in report order. A new entry is a reviewed edit:
589639
* `refused-shapes.test.ts` pins each one.
@@ -597,6 +647,7 @@ export const REFUSED_STORED_SHAPES: readonly RefusedStoredShape[] = [
597647
visibilityHasArgument,
598648
objectDuplicateActionName,
599649
dashboardDuplicateGlobalFilterName,
650+
objectExtensionFieldPatchKeyGrammar,
600651
];
601652

602653
/**

‎packages/spec/src/conversions/stored.test.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,56 @@ describe('applyConversionsToStoredItem (stored sys_metadata rows)', () => {
181181
});
182182
});
183183

184+
// #29554 — a stored `object_extension` row is one `objectExtensions` entry,
185+
// and until this the stored pass had no collection to wrap it in: every
186+
// conversion that reaches an extension, and every refused-shape detector,
187+
// skipped it, so the row read as already on protocol.
188+
describe('stored object_extension rows (wrapped as objectExtensions)', () => {
189+
const storedExtension = () => ({
190+
extend: 'crm_account',
191+
fields: { opens_at: { type: 'time', defaultValue: '12:00Z' } },
192+
fieldPatches: { industry: { label: 'Sector' } },
193+
});
194+
195+
it('replays a conversion that walks objectExtensions over a stored extension row, loudly', () => {
196+
const notices: ConversionNotice[] = [];
197+
const row = storedExtension();
198+
const out = applyConversionsToStoredItem('object_extension', row, { onNotice: (n) => notices.push(n) });
199+
expect(out).toEqual({
200+
extend: 'crm_account',
201+
fields: { opens_at: { type: 'time', defaultValue: '12:00' } },
202+
fieldPatches: { industry: { label: 'Sector' } },
203+
});
204+
expect(notices.map((n) => [n.conversionId, n.path])).toEqual([
205+
['time-default-utc-suffix-dropped', 'objectExtensions[0].fields.opens_at.defaultValue'],
206+
]);
207+
expect(row).toEqual(storedExtension());
208+
});
209+
210+
it('CONTROL — a canonical extension row passes through by reference', () => {
211+
const row = { extend: 'crm_account', fields: { opens_at: { type: 'time', defaultValue: '12:00' } } };
212+
expect(applyConversionsToStoredItem('object_extension', row)).toBe(row);
213+
});
214+
215+
it('CONTROL — the same body under an object row converts exactly as before', () => {
216+
const notices: ConversionNotice[] = [];
217+
const row = { name: 'shift', fields: { opens_at: { type: 'time', defaultValue: '12:00Z' } } };
218+
const out = applyConversionsToStoredItem('object', row, { onNotice: (n) => notices.push(n) });
219+
expect(out).toEqual({ name: 'shift', fields: { opens_at: { type: 'time', defaultValue: '12:00' } } });
220+
expect(notices.map((n) => [n.conversionId, n.path])).toEqual([
221+
['time-default-utc-suffix-dropped', 'objects[0].fields.opens_at.defaultValue'],
222+
]);
223+
});
224+
225+
// No plural row spelling is mapped: the read fallback finds none for this
226+
// type, and the stored-metadata pass skips a row stored under one before
227+
// reading its body. So neither spelling manufactures a collection.
228+
it.each(['object_extensions', 'objectExtensions'])('CONTROL — a `%s` row type is not mapped and passes through by reference', (type) => {
229+
const row = storedExtension();
230+
expect(applyConversionsToStoredItem(type, row)).toBe(row);
231+
});
232+
});
233+
184234
// [#23543 F5-http] A stored flow row written with a retired callout name
185235
// still loads, as `http`: the rename left the authoring funnel, not this
186236
// seam. Until 18 a caller's live-name set naming the old token made it a

‎packages/spec/src/conversions/stored.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from '../shared/metadata-colle
4646
* Stored row types whose conversions walk a stack collection the
4747
* MANIFEST-COLLECTION maps deliberately do not carry (#19620).
4848
*
49-
* `translation` is the one: `PLURAL_TO_SINGULAR` has no `translations`
49+
* `translation` is the first: `PLURAL_TO_SINGULAR` has no `translations`
5050
* spelling because a stack's `translations` entries are locale-keyed BUNDLES,
5151
* not named metadata items (`manifest-collection-spelling.ts` says why, and
5252
* `check:stack-collection-maps` holds that map to the stack schema). But the
@@ -59,12 +59,27 @@ import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from '../shared/metadata-colle
5959
* reaching the runtime from rows stored before. Kept HERE rather than added to
6060
* the shared maps, which would advertise `translations` as a named-item stack
6161
* collection to every other reader of them.
62+
*
63+
* `object_extension` is the second (ADR-0146 D10), for the same reason. A
64+
* stored extension row is exactly one `objectExtensions` entry (a body that
65+
* carries `extend` and no `name`), and every conversion that reaches an
66+
* extension walks that collection. But a stack's `objectExtensions` are not
67+
* named items either: the registry merges each one into its target, and
68+
* `check:stack-collection-maps` records the manifest map's omission of the key
69+
* as deliberate. Without this entry the stored pass returned every stored
70+
* extension row untouched, so no conversion and no refused-shape detector ever
71+
* ran over one, and `os migrate meta --stored` read each such row as already
72+
* on protocol. There is no plural row spelling to add: the protocol's
73+
* singular/plural read fallback finds none for `object_extension`, and the
74+
* stored-metadata pass reports a row stored under any other spelling of it as
75+
* `skipped` before its body is read.
6276
*/
6377
const STORED_ONLY_COLLECTIONS: Readonly<Record<string, string>> = {
6478
translation: 'translations',
6579
// The legacy plural row spelling, as the protocol's singular/plural read
6680
// fallback still finds it.
6781
translations: 'translations',
82+
object_extension: 'objectExtensions',
6883
};
6984

7085
/**

‎packages/spec/src/migrations/entries/semantic/18.object-extension-field-patch-key-grammar-refused.ts‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,11 @@ import type { SemanticMigration } from '../../types.js';
88
// the spelling (lower-casing, `-` to `_`) can land on a different field or on
99
// none, so which field is the author's to name.
1010
//
11-
// No `REFUSED_STORED_SHAPES` detector lists a stored row in this shape, because
12-
// none could be reached: `applyConversionsToStoredItem` maps a row type onto a
13-
// stack collection, and `object_extension` has none (it is in neither
14-
// `SINGULAR_TO_PLURAL` nor the stored-only map), so the stored pass hands the
15-
// row back untouched and runs no conversion or detector over it. The criteria
16-
// below say so, and name the query that finds such a row instead.
11+
// A stored row in this shape is listed, not rewritten: the stored pass wraps an
12+
// `object_extension` row as an `objectExtensions` entry (the stored-only map in
13+
// `conversions/stored.ts`), and the `REFUSED_STORED_SHAPES` detector of this id
14+
// (`conversions/refused-shapes.ts`) lists each key the extension's own parse
15+
// refuses as a key, under its row, through `os migrate meta --stored`.
1716
export const entry: SemanticMigration = {
1817
id: 'object-extension-field-patch-key-grammar-refused',
1918
surface:
@@ -37,8 +36,7 @@ export const entry: SemanticMigration = {
3736
+ 'at `fieldPatches.KEY` that names the grammar and an example. A stored `object_extension` row whose '
3837
+ 'body still carries such a key no longer parses, so the sync that registers stored extensions names '
3938
+ 'the row (`INVALID_METADATA`) and registers none of it, its `fields` included, and its next save is '
40-
+ 'refused until the key is renamed to the field it meant. `os migrate meta --stored` does not list such '
41-
+ 'a row: the stored pass maps no `object_extension` row onto a stack collection, so it reads the row as '
42-
+ 'already on protocol. Find one before upgrading by reading each stored `object_extension` row\'s '
43-
+ '`fieldPatches` keys against the snake_case grammar of `fields` keys.',
39+
+ 'refused until the key is renamed to the field it meant. `os migrate meta --stored` lists such a row '
40+
+ 'before the upgrade, one TODO for each refused key at `fieldPatches.KEY` naming the extended object, '
41+
+ 'and leaves it as stored: rename each listed key to the field it meant and save the extension.',
4442
};

0 commit comments

Comments
 (0)