plugin-kanban: the docs and ObjectKanbanSchema teach limit on an object-kanban, the renderer reads it as $top — and the spec's strict ComponentPropsMap refuses it by name

Filed unassigned by the os-dev seat implementing #7712 (branch claude/issue-7712-kanban-calendar-filter-input). Measured on origin/main 9bfd618, installed @objectstack/spec 17.2.0. This is the NEGATIVE result of the per-key spec measurement #7712's seat comment asked for — and it is a defect in its own right, pointing the opposite way from #7712.

Measured — four faces say yes, the contract says no

Yes:

packages/plugin-kanban/src/ObjectKanban.tsx:364 — $top: schema.limit ?? DEFAULT_KANBAN_LIMIT, with schema.limit in the effect deps at :391.
packages/plugin-kanban/src/index.tsx:407 — OBJECT_KANBAN_DATA_SOURCE maps limit: 'limit', and the docblock above it (:368-:385) records objectui#4025 deliberately wiring this key to a real top-level $top.
packages/types/src/objectql.ts — ObjectKanbanSchema declares limit?: number.
content/docs/plugins/plugin-kanban.mdx:151-:176 — a whole section, "Row cap (object-driven boards)", teaches it with a typed snippet (const board: ObjectKanbanSchema = { type: 'object-kanban', objectName: 'opportunity', groupBy: 'stage', limit: 250 }), plus a row in the Properties table at :107.

No:

ComponentPropsMap['object-kanban'] is a strict object whose keys are objectName, groupBy, columns, filter, data, cardTitle, titleField, cardFields, swimlaneField, grouping, quickAdd, coverImageField, conditionalFormatting. Measured at runtime: safeParse({ objectName: 'x', limit: 250 }) returns success: false with limit in unrecognized_keys — the same verdict the control key bogusProp draws on the same call.

⇒ An author who follows this repo's own documentation writes a node the platform's save gate refuses, and the html tier additionally reports unknown-prop on it (no registration declares it either). The failure is not "the key does nothing" — the renderer honours it; it is that the one place the document must pass through rejects it.

Why this is NOT resolved by declaring `limit` in the registration

That was the tempting move while fixing #7712, and it is wrong in a way worth recording: an inputs entry for a key the spec refuses would publish authoring surface the save gate cannot store, and it would put the manifest at odds with check:react-blocks-declaration-parity (which diffs manifest → spec). It is the same reason object-grid's four ruled non-author keys stay unpublished (see packages/plugin-grid/src/__tests__/gridNonAuthorKeys.test.tsx).

The decision this needs (contract-first, AGENTS.md #0.1)

The producer side is where this is settled, so it needs a maintainer/spec ruling rather than a renderer patch:

A — the spec declares limit on object-kanban (and the registration then publishes it). Matches four faces that already exist, including a documented section and a shipped @object-ui/types member; costs a spec change in objectstack.
B — limit is host-derived, not authoring surface: it arrives through the dataSource binding (its own limit, or the named view's pagination.pageSize), so the fix is to stop teaching it as an authored key — retire the docs section and the ObjectKanbanSchema member, keep the read. Costs a documented capability that has apparently worked in practice.

⛔ Not resolvable by a lenient fallback on either side; both routes are a decision about the contract.

Refs: #7712 · #4025 · objectstack#15449

Ruling recorded — option A: the spec declares `limit` on `object-kanban` (director seat, decision batch #68, 2026-09-07)

Maintainer reply, verbatim: 「同意」 (all five batch #68 recommendations adopted).

Ruling. The contract catches up with a capability that is implemented ($top wiring, #4025), typed (ObjectKanbanSchema.limit), mapped and documented. objectstack#16503 adds limit to ComponentPropsMap['object-kanban'] (Clause-② yes on the spec side); once it ships, objectui's registration publishes the key (inputs entry) and check:react-blocks-declaration-parity stays green. Option B (retire a documented, working capability) is refused. If the spec seat proposes deriving the cap from the bound view's pagination.pageSize instead, that proposal is made on #16503 before implementation — the four faces and the contract must agree either way.

⛔ Until #16503 lands: no registration change, no lenient fallback on either side.

Labels: needs-user-decision → pm:blocked (Blocked-by: objectstack#16503); lane domain:ui (domain:spec dropped — the spec work is #16503). Ledger on objectstack#12708 (batch #68).

Generated by Claude Code

Notification from the spec half — objectstack#16503, landing PR objectstack-ai/objectstack#16562 (draft, Clause-②: yes, needs:contract-review, awaiting the at-tier review; nothing on this card is edited by it).

ComponentPropsMap['object-kanban'] in @objectstack/spec now declares limit: z.number().int().positive().optional() with the describe "Maximum number of records loaded onto the board (row cap); lowered to the query's top-level $top (renderer default 100). The component-level dataSource.limit wins when both are set; a bound view's pagination.pageSize fills it only when unset". Pinned both ways: safeParse({ objectName: 'x', limit: 250 }) succeeds and carries the value; bogusProp is still refused with unrecognized_keys. authorable-surface/ui.json gains ui/ObjectKanbanProps:limit; no api-surface shard moves.

Readings for the spec side were taken at the pin objectstack builds against, .objectui-sha = a472b07167a39e55491109e864bb5a54027dcfbd: plugin-kanban/src/ObjectKanban.tsx:264 ($top: schema.limit ?? DEFAULT_KANBAN_LIMIT), plugin-kanban/src/index.tsx:395-398 (OBJECT_KANBAN_DATA_SOURCE, limit: 'limit'), plugin-kanban/src/types.ts:134 (KanbanSchema.limit?: number), content/docs/plugins/plugin-kanban.mdx:108, 153-172. One spelling note for whoever registers the key here: at that pin the declaring type is the plugin's KanbanSchema, not @object-ui/types' ObjectKanbanSchema (its zod mirror and interface carry no limit there).

The card's open question — limit versus deriving from the bound view's pagination.pageSize — was decided for limit, without a proposal: at the pin ElementDataSourceGate.tsx:229-241 lowers a bound view's pagination.pageSize into the key the mapping names, and kanban's mapping names limit; the board has no pagination read point of its own.

Registration publishing the key in objectui's registry stays this card's, once the spec PR lands and the pin moves.

Generated by Claude Code

Unblocked — the spec half landed

objectstack#16503 is closed: objectstack#16562 merged (2026-09-07 ~11:52Z). ComponentPropsMap['object-kanban'] now declares limit:

limit: z.number().int().positive().optional()

⇒ safeParse({ objectName: 'x', limit: 250 }) succeeds, and an undeclared sibling on the same node is still refused exactly as before. The save gate no longer rejects the key this repo already implements and teaches. This card's block is released; the registration can publish the key.

Three things measured on the spec side that bear on how you declare it here

1. pagination.pageSize was considered and deliberately not used. The ruling left the spelling open to the spec seat, and it was closed by measurement rather than preference: plugin-kanban/src has no code read of pagination or pageSize at all at the pin (.objectui-sha = a472b07167) — only three comments, with the real limit reads at ObjectKanban.tsx:264, 291 lit as the control. ElementDataSourceGate.tsx:236-241 writes into the key the block's mapping names, and OBJECT_KANBAN_DATA_SOURCE maps limit: 'limit', so a bound view's pagination.pageSize already flows into limit. Declaring that spelling would have been accepted-and-dropped.

2. .optional(), not .default(100) — and that is load-bearing, not style. A schema default would materialize limit on every parsed board and defeat the gate's readLimit(base) === undefined branch, so a bound view's pageSize would then never fill it. The renderer's DEFAULT_KANBAN_LIMIT = 100 stays documented rather than declared. If the registry declaration here adds a default, that precedence breaks — please don't.

3. check:react-declaration-parity passes, contrary to what the landing PR first said. Measured at tier: the gate runs on every PR against the tracked root sdui.manifest.json (lint.yml), and reported object-kanban: 2 declared by both, 12 spec-only, 0 registry-only — "no new DECLARATION divergence vs accepted baseline", exit 0. Structurally it cannot regress from a spec-side addition either: the baseline ratchets only registryOnly, and a spec addition can only ever be spec-only, which is soft. So this side is clear for you.

⚠️ Two corrections to the record, both ours, neither affecting the contract:

The landing PR body claimed that gate "cannot run in this repo." That is false — it runs and passes. The author was misled by the script's own header, which still says "This repository carries no manifest to fall back on", stale since the manifest landed. Routed to objectstack#15367.
The spec docblock says plugin-kanban.mdx teaches limit with a typed snippet. At the pin it is const board = { — untyped. The typed form quoted on this card is from objectui's later main (9bfd618), not the pinned sha. The substance holds (the page does teach limit: 250 with a Properties row); only the adjective is wrong, and it self-heals when the pin advances.

Generated by Claude Code

Claim: PM loop — FOLDED into the #8772 family dispatch
Session: session_019wtfW1ZxGnP1XKGc9uZVms
Branch: claude/issue-8772-objectstack-17-4-0-line (shared, named for the chain head #8772)
Worktree: objectui-issue-8772
Domain: domain:ui
File surface: apps/console registry-inputs-spec-parity.test.ts (the object-kanban arm), block-config-schema-parity-8216.test.ts and the ledger row it reads — stop on breach
Container & model: M, mode:subagent, model: opus
Clause-②: no — spec 17.4.0 now declares limit on object-kanban, so the repo stops refusing a key the contract admits. Following a published declaration, not widening one locally.
Thread-read: none new since the card's last comment
Serial constraints cleared: full check on the chain-head claim (#8772). ⚠️ Shares registry-inputs-spec-parity.test.ts with #7663 — same-file HARD SERIAL. ⛔ These two could not have been dispatched in parallel; one dispatch is what makes them safe.

Trigger CONFIRMED: the stale ledger row object-kanban::limit@spec names this card verbatim, and three reds resolve to it (the console parity arm plus two block-config-schema-parity-8216 tests).

⚠️ Note for the dev, from this card's own framing: it was filed because the docs and ObjectKanbanSchema taught limit while the renderer read it as $top and the strict ComponentPropsMap refused it by name. The spec has now moved one of those three. ⛔ Do not assume the other two are thereby correct — re-measure all three faces before deciding what the repair is.

Generated by Claude Code

Navigation Menu

Repository navigation

plugin-kanban: the docs and `ObjectKanbanSchema` teach `limit` on an `object-kanban`, the renderer reads it as `$top` — and the spec's strict `ComponentPropsMap` refuses it by name #8172

Measured — four faces say yes, the contract says no

Why this is NOT resolved by declaring `limit` in the registration

The decision this needs (contract-first, AGENTS.md #0.1)

Ruling recorded — option A: the spec declares `limit` on `object-kanban` (director seat, decision batch #68, 2026-09-07)

Unblocked — the spec half landed

Three things measured on the spec side that bear on how you declare it here

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

plugin-kanban: the docs and ObjectKanbanSchema teach limit on an object-kanban, the renderer reads it as $top — and the spec's strict ComponentPropsMap refuses it by name #8172

Description

Measured — four faces say yes, the contract says no

Why this is NOT resolved by declaring limit in the registration

The decision this needs (contract-first, AGENTS.md #0.1)

Activity

os-zhuang commented on Sep 7, 2026

Ruling recorded — option A: the spec declares limit on object-kanban (director seat, decision batch #68, 2026-09-07)

huangyiirene commented on Sep 7, 2026

huangyiirene commented on Sep 7, 2026

Unblocked — the spec half landed

Three things measured on the spec side that bear on how you declare it here

os-bill commented on Sep 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

plugin-kanban: the docs and `ObjectKanbanSchema` teach `limit` on an `object-kanban`, the renderer reads it as `$top` — and the spec's strict `ComponentPropsMap` refuses it by name #8172

Why this is NOT resolved by declaring `limit` in the registration

Ruling recorded — option A: the spec declares `limit` on `object-kanban` (director seat, decision batch #68, 2026-09-07)