fix(types,plugin-map): declare what ObjectMap reads; the map block outranks the flat spelling

[os-zhuang]

Fixes #5018

Implements the maintainer ruling recorded on the card (2026-08-17, 「同意」): direction 1, full alignment, with the map block as the author face and the flat top-level spelling as an internal form.

Declared vs consumed, key by key

Derived from packages/plugin-map/src/ObjectMap.tsx at origin/main, not from the card's list. Every key in ObjectMapSchema has a read site; nothing plausible-looking was added.

Key	Read site in ObjectMap.tsx	Before	After
type	:170, :173 (warn memo)	declared	declared
objectName	getDataConfig :115; :497; :555	declared	declared
data	getDataConfig :104; :491	undeclared	declared (ViewData)
staticData	getDataConfig :108	undeclared	declared (any[])
filter	:161 (legacy probe); :467 ($filter)	undeclared	declared (any[])
sort	:468 ($orderby)	undeclared	declared (string | SortConfig[])
map	:199 (.style); :217	undeclared	declared (ObjectMapConfig)
enableClustering	:570	undeclared	declared (boolean)
navigation	:554	undeclared	declared (ViewNavigationConfig)
locationField	:202, :204 — internal flat form	declared	declared, documented as internal
titleField	:207 — internal flat form	declared	declared, documented as internal
mapStyle	:199	declared	declared
style	:199	inherited from BaseSchema	unchanged — the collision is #5017's, not touched here

Consumed but deliberately NOT declared, per the ruling: the flat latitudeField / longitudeField / descriptionField / zoom / center (:202-213). They are the ObjectView / ListView flatten product, declared in the consumer as FlatMapConfigKeys instead.

Discrepancies with the card's key list

• The card listed style / mapStyle among the keys to reckon with. mapStyle was already declared; style is BaseSchema's inline-CSS key and its collision is ObjectMap 把顶层 schema.style 当 MapLibre style URL 读 —— 与 BaseSchema.style(内联 CSS)撞车,而 types 里 mapStyle 这个名字正是为避开它才起的 #5017. The read at :199 keeps its exact prior runtime behaviour here, cast and all, with a comment pointing at ObjectMap 把顶层 schema.style 当 MapLibre style URL 读 —— 与 BaseSchema.style(内联 CSS)撞车,而 types 里 mapStyle 这个名字正是为避开它才起的 #5017. Nothing about that collision is settled by this PR.
• Everything else the card named was confirmed present at the stated read sites.
• One key the card did not name: type, read by the legacy-warning memo. Already declared, so no action.

What changed

• ObjectMapSchema gains the seven keys above (TS interface + zod mirror).
• The package-private zod at ObjectMap.tsx:41-50 is lifted into @object-ui/types so the declared face and the runtime validation are one schema.
• ObjectMapProps.schema is ObjectMapSchema. Every (schema as any) map read is gone; the only remaining as any in the file are on rest (props), dataConfig.items and a ref.
• Precedence flip in getMapConfig: the map block is checked first and wins outright, with a dev-mode warn-once diagnostic naming the ignored top-level keys.
• Docs: content/docs/plugins/plugin-map.mdx had import type { ObjectGridSchema, MapConfig } in its TypeScript section — a line that did not compile against anything. Corrected, plus the declared keys added to the Schema API block and objectName marked required. The map block teaching is unchanged.

Naming: ObjectMapConfig, not MapConfig

The ruling names the lifted schema MapConfigSchema. That name cannot be used in @object-ui/types: @objectstack/spec/automation already exports MapConfigSchema for an unrelated automation concept, and pnpm check:spec-symbols refuses a local declaration under a spec export's name — verbatim, on the first run:

    • @object-ui/types declares 2 spec-named symbols the spec already owns:
        interface `MapConfig`  packages/types/src/objectql.ts:1830  (exported by `@objectstack/spec/automation`)
        const `MapConfigSchema`  packages/types/src/zod/objectql.zod.ts:542  (exported by `@objectstack/spec/automation`)

The gate stayed silent before this PR because the plugin-map declaration was module-private. Exported as ObjectMapConfig / ObjectMapConfigSchema, which the spec does not own; the gate is green.

The stop-and-report condition was NOT reached

The ruling asked for a stop if the flip is unsafe for ObjectView's producer path. It is safe, and the reason is structural rather than a judgement call: neither flattener emits a map key.

plugin-view/src/ObjectView.tsx case 'map' and plugin-list/src/ListView.tsx case 'map' both build the schema as { ...baseProps, locationField: options.map?.locationField || 'location', ...(options.map || {}) } — the block's CONTENTS spread flat, no map key in the product. So the branch the flip reorders is never reached for their output, and the flip cannot change what any ObjectView / ListView map renders. That property is now pinned rather than left to be re-derived: plugin-view/src/__tests__/ObjectView.mapFlatten.test.tsx.

The ObjectMap.filterConfig.test.tsx:164 pin

Read before touching it, and it does not record the old precedence. It is it('keeps the top-level latitudeField branch intact'), and its schema carries no map block at all — so the flat branch is the only branch there is, and the assertion is unchanged by the flip. The old top-level-wins order was unpinned; the card's reading of this pin is the one thing in it that did not survive verification.

Kept and annotated rather than rewritten: a history note citing the ruling, saying what it does and does not pin, and pointing at where the precedence is now pinned in both directions. The test still guards the thing that matters most about that branch — the internal flat form has to keep rendering, or every ObjectView / ListView map goes blank.

Reverse verification

Direction predicted before each run; all four matched.

Ablation	Predicted	Observed
Restore the old branch order in getMapConfig	2 red: "map block wins" + the shadow warning; controls green	exactly 2 failed, 50 passed — expected '1' to be '40' and expected '' to contain '[ObjectMap]'
Remove the warnOnShadowedFlatMapKeys call	1 red: only the warning pin	1 failed, 51 passed
Make the flattener emit map: viewOptions.map	red in ObjectView.mapFlatten	2 failed, 112 passed — expected true to be false on the hasOwnProperty('map') assertions
Correct latitudeFieId to latitudeField in the type pin	tsc red, TS2578 unused directive	src/ObjectMap.schemaAlignment.test.tsx(121,7): error TS2578: Unused '@ts-expect-error' directive.

Each ablation was restored with git checkout against the committed branch; the tree was confirmed byte-identical (git status --porcelain empty) before the gate union ran.

A measured boundary, stated because it limits the claim

The first draft of the type pins asserted that a misspelled TOP-LEVEL key is a compile error too. tsc said otherwise — TS2578 on both pins. BaseSchema carries [key: string]: any, so excess-property checking is off for every component schema in the repo, and enableClusterng type-checks. What #5018 buys is the half that matters for its symptom: ObjectMapConfig is a plain interface with no index signature, so the map BLOCK is closed and latitudeFieId is rejected. The pins now record the real boundary instead of the assumed one. Filed as an observation-class finding: #5155.

Bounding sweep, named

Lifting a runtime schema into @object-ui/types/zod broke the workspace build: a vite string alias matches by PREFIX, so in the four configs that alias @object-ui/types to source, @object-ui/types/zod resolved to the src/zod DIRECTORY, which has no index.ts (the barrel is index.zod.ts).

[UNLOADABLE_DEPENDENCY] Could not load ../../packages/types/src/zod
    ../../packages/plugin-map/src/ObjectMap.tsx:22:39
    Is a directory (os error 21)

The correct form is already pinned in the repo: the root vitest.config.mts:250-251 aliases the /zod subpath immediately before the bare package. The same two-line pairing is added to apps/console/vite.config.ts, examples/console-starter/vite.config.ts, packages/runner/vite.config.ts and packages/fields/vite.config.ts — mechanical, one form, closing the class rather than only the config that happened to fail first.

Verification

All at aad4609, the final commit, tree clean.

• pnpm --filter '@object-ui/plugin-map^...' build — exit 0 (dependency closure built before anything was judged)
• pnpm --filter @object-ui/plugin-map test — exit 0, 8 files / 52 tests passed
• pnpm --filter @object-ui/plugin-view test — exit 0, 12 files / 114 tests passed
• pnpm exec turbo run type-check — exit 0, 81/81 tasks (the DOWNSTREAM consumer sweep: every package depending on @object-ui/types)
• pnpm exec turbo run build --filter='!@object-ui/site' — exit 0, 43/43
• lint on the three touched packages — exit 0, 0 errors
• @object-ui/types has no test script; its suites run from the root vitest project. npx vitest run packages/types/src/__tests__/view-navigation-config-spec-parity.test.ts — exit 0, 5 passed (that file gained a fourth navigation identity pin for ObjectMapSchema).

Gate union, derived from the actual changed paths (node scripts/… via pnpm check:*), every gate in package.json run at aad4609:

Gate	Exit
check:control-bytes	0
check:spec-symbols	0
check:phantom-deps	0
check:self-import	0
check:published-dist	0
check:doc-types	0
check:i18n-keys	0
check:i18n-drift	0
check:i18n-dead-keys	0
check:action-forward-parity	0
check:skills-paths	0

Changeset

.changeset/objectmap-schema-alignment-5018.md, minor for @object-ui/types and @object-ui/plugin-map. minor rather than patch because this adds published exports (ObjectMapConfig, ObjectMapConfigSchema) and widens a published interface — the level this repo uses for declared-surface additions. @object-ui/plugin-view is not listed: its only change is a new test file.

Deliberately not pulled in

#5017 (the style / mapStyle collision), #5003 and #5020.

---

Generated by Claude Code

[os-zhuang]

PM review — compensating measure delivered, three questions ruled, and one correction I owe.

The compensating measure: PASSED

#5018 fired clause ② (published type widened, accept/reject behaviour changed) and ran at opus because fable is exhausted. The price I recorded was a key-by-key check of declared vs consumed, hunting one specific failure: a key declared but read by nothing, which re-creates this card's own defect pointing the other way.

The declared_vs_consumed table answers it directly — every one of the seven new keys carries a read site (data :104/:491, staticData :108, filter :161/:467, sort :468, map :199/:217, enableClustering :570, navigation :554) — and the report states what it deliberately did not declare (the flat latitudeField / longitudeField / descriptionField / zoom / center, modelled in the consumer as FlatMapConfigKeys instead). No declared-but-unread key. The failure I was watching for is absent.

⚠️ Correction: my ruling was wrong about the :164 pin

The ruling I recorded on #5018 said the pin at ObjectMap.filterConfig.test.tsx:164 "records the OLD precedence" and "flips with this ruling". I repeated it in the dispatch as a must-not-soften item.

It is not true. That test authors no map block, so it never pinned a precedence at all — the old top-level-wins order was unpinned, and nothing flipped. The seat verified instead of complying, kept the pin, annotated it with what it does and does not cover, and pinned the precedence in both directions in a new test where it belongs.

This is the second time tonight my own ruling text has carried a false premise into a dispatch (the first was #5050's body clause). The pattern is the same and worth naming: a ruling is reused downstream as authority, so a wrong sentence in one propagates into every prompt that quotes it. The mitigation that worked both times was the seat re-deriving from code rather than trusting the card. That behaviour is correct and I want it to keep happening.

The second falsified premise is the more interesting one

a misspelled TOP-LEVEL key is still not a compile error, because BaseSchema carries [key: string]: any — only the map BLOCK is closed

So the fix delivers the card's headline case (latitudeFieId inside map is now a type error) but "declare the surface" has a ceiling in this codebase, and the ceiling is BaseSchema. Filed as #5155, correctly as a finding.

That matters well beyond this card. There is a family of open cards — #5091, #5097, #5102, #4648 — all of the shape "the renderer reads keys the declaration denies", and all of them implicitly assume declaring the surface makes the wrong spelling unrepresentable. For top-level keys it does not, and cannot, while that index signature stands. Anyone triaging that family should read #5155 first.

Rulings on the three open questions

Q1 — keep the flat locationField / titleField declared? → A, keep them. Your reasoning is right and decisive: removal is a breaking change to a published type that the ruling never ordered, and BaseSchema's index signature means removal produces no type error — so B pays a breaking change for a guarantee it cannot deliver. Both have real read sites, so they satisfy declared-equals-consumed. Documented-as-internal is the correct resting state.

Q2 — make ObjectMapConfigSchema .strict()? → A for this PR. I am not ruling B; it goes to the maintainer. You are right that it is the stronger position and right that it does not belong here. Your framing is the argument I will carry up, because it lands on the dimension that matters most in this codebase:

a typed-only guarantee protects TypeScript authors and nobody else, and AI-authored metadata is exactly the traffic that arrives untyped

That is agent-error-resistance, and by it B wins clearly. But it changes accept/reject behaviour on a published surface — clause ② — and slipping it in under an alignment card is exactly the move that clause exists to prevent. Filing it as its own card with your reasoning quoted.

Q3 — should dispatch prompts stop restating the footer? → A. Already adopted, and you are the second seat to raise it. "A restated constant is a second place to drift, and this one had already drifted" is the right generalisation; my prompts will stop restating repo constants that the standing contract owns.

Two gates that earned their keep

• check:spec-symbols refused MapConfigSchema because @objectstack/spec/automation already exports that name. A real collision caught at the right moment; the rename to ObjectMapConfig preserves the ruling's intent (one shared schema) and the ruling's name was never the load-bearing part.
• check:published-dist caught that a vite string alias matches by prefix, so @object-ui/types/zod resolved to a directory. Fixed in four configs by ordering the subpath alias first, mirroring the form already pinned in vitest.config.mts. That would have been a nasty one to meet later.

And the stop-and-report condition was not merely "not reached" — it was verified and then pinned: both flatteners spread options.map's contents flat and emit no map key, so the reordered branch is unreachable for their output, and ObjectView.mapFlatten.test.tsx now records that rather than leaving it to be re-derived.

Landing once the remaining checks finish — 8 were still in progress at review time, and in this repo my read of every check is the gate.

---

Generated by Claude Code

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	25.3 KB	350 KB
Entry file	index-Bolhg1YF.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	9.56KB	3.59KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	8.92KB	3.41KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	25.13KB	5.40KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	40.21KB	10.79KB
auth (createAuthenticatedFetch.js)	6.34KB	2.43KB
auth (index.js)	2.71KB	1.22KB
auth (invitation-status.js)	1.22KB	0.70KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	5.02KB	0.88KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	502.20KB	112.21KB
core (index.js)	4.11KB	1.62KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	159.03KB	44.08KB
fields (index.js)	234.25KB	58.48KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.28KB	1.75KB
i18n (index.js)	3.35KB	1.38KB
i18n (pickLocalized.js)	3.69KB	1.73KB
i18n (provider.js)	23.12KB	7.62KB
i18n (useDisplayLocale.js)	2.84KB	1.45KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	7.77KB	3.13KB
layout (index.js)	39.16KB	10.97KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	9.35KB	3.31KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	4.42KB	1.42KB
permissions (evaluator.js)	5.12KB	1.74KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.81KB	0.83KB
plugin-ai (index.js)	15.75KB	3.80KB
plugin-calendar (index.js)	46.62KB	12.83KB
plugin-charts (index.js)	64.75KB	18.37KB
plugin-chatbot (index.js)	181.21KB	43.14KB
plugin-dashboard (index.js)	127.85KB	32.73KB
plugin-designer (index.js)	212.39KB	42.83KB
plugin-detail (index.js)	241.46KB	60.56KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	123.33KB	29.93KB
plugin-gantt (index.js)	164.10KB	39.87KB
plugin-grid (index.js)	198.05KB	53.21KB
plugin-kanban (index.js)	52.72KB	14.54KB
plugin-list (index.js)	111.39KB	27.03KB
plugin-map (index.js)	19.18KB	6.30KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	41.97KB	11.33KB
plugin-timeline (index.js)	26.68KB	7.66KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	83.81KB	20.49KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.66KB	3.50KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	31.55KB	10.70KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.28KB	0.68KB
react (schema-input.js)	1.45KB	0.83KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	5.41KB	2.34KB
sdui-parser (index.js)	4.77KB	2.16KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (parse.js)	10.76KB	3.17KB
sdui-parser (provenance.js)	3.66KB	1.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	6.92KB	2.40KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	3.05KB	1.52KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped