[Decision] `schema.onNavigate` is a function value read off the grid schema — the fifth key #5091's ruling did not cover

[os-support-ai]

> ### ⛔ CORRECTED 2026-08-18 — read this first
> An earlier version of this body claimed onNavigate is absent from the ObjectGridSchema interface and only type-checks because of BaseSchema's index signature. That was false. It is explicitly declared at packages/types/src/objectql.ts:847, with a doc comment. The error came from a grep bounded to lines 532–760 of an interface that runs 532–888. The body below is corrected, the affected argument is withdrawn, and the PM recommendation is withdrawn with it — see the correction comment for what moved and why.

Split out of #5091 by the repo:objectui PM seat (round 6, session session_01RV6yuVCxymHYE16PL9vQkE) at dispatch time, and deliberately excluded from that card's dispatch.

Why this is a separate card

#5091 catalogued four keys ObjectGrid reads but GRID_QUERY_INPUTS does not declare. A later comment added a fifth — schema.onNavigate — on the reasoning that it belonged to the same decision, and it was attached to #5091 rather than filed separately so one decision would not be split across two cards.

The maintainer's 2026-08-18 ruling on #5091 (verbatim 「同意」) then enumerated only the original four: rowActionDefs → into the manifest; columnState / hideRowHeightToggle / maxInlineRowActions → non-author surface with exemption comments. onNavigate does not appear in it.

So the ruling and the card no longer cover the same key set. Rather than let a PM's reading close that gap, #5091 was dispatched for the four ruled keys with onNavigate explicitly out of scope, and the fifth comes here for its own answer.

Measured on origin/main

packages/plugin-grid/src/ObjectGrid.tsx:1187 onNavigate: schema.onNavigate,

read inside the useNavigationOverlay({ navigation, objectName, onNavigate, onRowClick }) call.

packages/types/src/objectql.ts:847 onNavigate?: (recordId: string | number, action?: string) => void;

declared on ObjectGridSchema (interface spans 532–888), with the doc comment "Callback for page-level navigation (used by 'page' mode). Called with recordId and action ('view' | 'edit')."

packages/plugin-grid/src/index.tsx no hit — absent from GRID_QUERY_INPUTS

It was invisible to #5091's original sweep because that sweep matched the cast form (schema as any).KEY, and this one is a plain read — the mirror image of the blind spot that produced the earlier misjudgement.

The actual shape of the problem

It is not an undeclared key absorbed by a loose index signature (the corrected reading). @object-ui/types declares it deliberately and documents it. The problem is narrower and now sits in exactly one place:

The renderer reads it and the TS type declares it, while the manifest surface — GRID_QUERY_INPUTS, the designer panel, the generated sdui-intrinsics.d.ts — denies it exists. That is the same "renderer reads it, manifest denies it" condition #4648 and #5091 exist to close.

In the same useNavigationOverlay call, schema.navigation and schema.objectName are both on the manifest surface; only onNavigate is not.

The argument that survives the correction, and is now the strongest one

A schema is a serialisable document, and a function cannot survive a metadata round-trip. Whatever declares it, onNavigate can never be written by an author in JSON or YAML, never round-trip through metadata, and never be produced by an AI writing a schema document. A (recordId, action) => void in a stored document is not expressible.

So the question is not whether it is declared — it is — but whether a callback that only a programmatic caller can supply belongs on the schema type at all, when nine sibling callbacks live on ObjectGridComponentProps for precisely that reason.

For contrast, verified key by key: onRowClick, onRowSelect, onCellChange, onRowSave, onBatchSave, onEdit, onDelete, onBulkDelete, onAddRecord exist only on ObjectGridComponentProps, with zero schema.on* read points. onNavigate is the one that is on both.

Four-prism

• Platform coherence — nine callbacks are props-only; one is on the schema with a doc comment. Either that tenth is a deliberate exception that should be stated as one, or it is inconsistent. It already cost a documentation claim: the README and docs page said "the grid never reads a callback off the schema", narrowed to "never reads any of these nine" because of this key.
• Measured business pull — none found for authoring it in metadata, and none is possible: JSON cannot carry a function. Programmatic callers are served by the props channel today.
• AI-agent error-resistance — an agent reading ObjectGrid.tsx sees a callback taken off schema, checks @object-ui/types, finds it declared and documented, and reasonably concludes callbacks may be authored on a schema. It then emits metadata that silently does nothing. The corrected facts make this worse, not better: before, only the read site suggested it; now the type and its doc comment appear to confirm it.
• Startup scope discipline — with the key explicitly declared, removing it is a breaking public type change plus a deprecation cycle, not the cheap tidy-up the earlier version of this card assumed.

The options

• A. Move it off the schema read point and remove the declaration — onNavigate joins its nine siblings on ObjectGridComponentProps. Ends with one clean rule and restores the docs sentence as a universal. Cost, corrected: a breaking public type change on @object-ui/types plus a deprecation cycle — the same profile that decided FormSchema.onChange is a declared public callback the form renderer never calls — authoring it is a silent no-op #4259 against removal. Requires checking for callers passing it through a schema object.
• B. Declare it in GRID_QUERY_INPUTS so all three surfaces agree. Cheapest to execute and makes the manifest match the type. But it publishes to the designer panel a key no author can express, which is the objection that started this card.
• C. Keep it as an explicit, documented exception — leave the type declaration and the read, add an exemption comment at the read site and a note on the type saying it is programmatic-only and deliberately outside the manifest. Cheapest that changes nothing observable; leaves the docs sentence narrowed.

PM recommendation: withdrawn. The earlier recommendation of A rested on the false premise that nothing declared the key. With the declaration real and deliberate, A's cost profile changes enough that I do not think a PM should be picking between these — it is a public-surface question with a real deprecation cost on one side and a published-but-unauthorable key on the other.

This is on the human floor: it moves a published surface, and #5091's ruling is the neighbouring decision it must stay consistent with.

Refs #5091 (the four ruled keys; its rowActionDefs line is also back with the maintainer, see PR5241), #5240 (userActions, a sixth key in the same family), #4648 (the prior round of this rule), #5065 / #5090 (same sweep).

[os-support-ai]

⛔ CORRECTION — this card's central premise was wrong, and it was mine

Posted before any decision is taken on it. The body has been corrected in place; this comment records what changed and why, because the error moved my recommendation.

What I wrote: that onNavigate is "absent from the ObjectGridSchema interface", and therefore that it "reads cleanly and tsc stays silent only because BaseSchema's [key: string]: any index signature absorbs it — the declaration surface is structurally unable to object."

What is true, verified by me on origin/main just now:

packages/types/src/objectql.ts:847 onNavigate?: (recordId: string | number, action?: string) => void;

ObjectGridSchema spans lines 532–888, and onNavigate is an explicitly declared member at :847, with its own doc comment ("Callback for page-level navigation (used by 'page' mode). Called with recordId and action"). Nothing is being absorbed by an index signature.

Root cause: the evidence I inherited came from a grep bounded to lines 532–760, which stops 128 lines short of the interface's end. I carried that reading into a decision card without re-running it against the file. Caught by the #5091 dev, who was measuring the same file for a different reason and reported it unprompted rather than treating a neighbouring card's premise as settled.

What this changes

The "structurally unable to object" argument is withdrawn entirely. The type declares this key on purpose and documents what it is for. That is the opposite of drift absorbed by a loose index signature, and it was the strongest single line in the card.

Option A is now materially more expensive than I priced it. I called moving onNavigate off the schema read point "cheap". It is not: with the key explicitly declared in @object-ui/types, removing it is a breaking public type change plus a deprecation cycle — the same cost profile that decided the #4259 ruling against removal and in favour of wiring. My recommendation of A was built on the belief that nothing declared it. I withdraw that recommendation and offer no replacement; this needs the maintainer, which is why it is here.

The "single breach in an otherwise clean line" framing is weakened. The other nine callbacks (onRowClick, onRowSelect, onCellChange, onRowSave, onBatchSave, onEdit, onDelete, onBulkDelete, onAddRecord) do live only on ObjectGridComponentProps — that part still holds. But onNavigate being on the schema interface with a doc comment reads as a deliberate decision by whoever wrote it, not as an accident. It may still be the wrong decision; it is not an oversight, and it should not be judged as one.

What survives, unchanged

• It is absent from GRID_QUERY_INPUTS, so the manifest, the designer panel and the generated sdui-intrinsics.d.ts still deny a key the renderer reads at ObjectGrid.tsx:1187. That is the original defect and it is intact.
• It is a function value, and a schema is a serialisable document — so it cannot survive a metadata round-trip regardless of what declares it. This is now the card's strongest remaining argument, and it is untouched by the correction.
• The documentation consequence is unchanged: the README/docs claim "the grid never reads a callback off the schema" was narrowed to "never reads any of these nine" because of this key.

The pattern, for the record

Three times today I have taken a document's word for the repository's state — a transferred card (#5217, already fixed), a maintainer ruling's premise (#5091's bulkActionDefs symmetry), and now a grep range I did not re-run. All three were caught by someone measuring rather than reading. The fix is not more care when reading; it is re-running the measurement at the moment of writing the card. Applied here: I re-ran it before posting this correction rather than accepting the dev's report.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. The seat's own recommendation was withdrawn after the premise correction above; the PM supplied the recommendation the maintainer accepted:

Ruling: Option C — keep onNavigate as an explicit, documented exception

• Exemption comment at the read site (ObjectGrid.tsx schema read), following the pattern PR test(plugin-grid): record the three grid keys ruled non-author surface, and stop at the fourth #5241 established for the other non-author keys; extend gridNonAuthorKeys.test.tsx accordingly.
• The @object-ui/types declaration (objectql.ts:847) gains a programmatic-only note: the key is a function value, inexpressible in JSON/YAML metadata — authors cannot use it; programmatic callers should prefer ObjectGridComponentProps like its nine siblings.
• The docs sentence stays narrowed accordingly.
• Why not A (remove): with the key explicitly declared, removal is a breaking public type change plus a deprecation cycle — for zero measured harm, in the launch window, that price fails scope discipline. A may be re-evaluated at the next major.
• Why not B (declare in GRID_QUERY_INPUTS): it would publish to the designer a key no author can ever express — the most AI-error-prone option.

State: needs-user-decision → pm:queue (zero-behaviour-change execution: comments, type note, doc sentence, test).

---

Generated by Claude Code