Merge remote-tracking branch 'origin/main' into claude/issue-15124-facade-query-envelope

Author: claude

.changeset/17393-view-row-ceiling.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/spec': minor
+---
+
+Gallery, kanban and timeline view configs declare an author-settable row ceiling.
+
+`GalleryConfigSchema`, `KanbanConfigSchema` and `TimelineConfigSchema` each gain a
+`limit` member — a positive integer, default **100** — saying how many records the
+view fetches. The default is APPLIED by the schema rather than only described, and
+the key's own text states the other half of the contract: when the ceiling applies,
+the renderer must show a visible truncation signal, because a bounded view that
+looks complete is worse than an unbounded one. `DEFAULT_VIEW_ROW_LIMIT` is exported
+so a consumer reads that number instead of re-declaring it.
+
+The knob belongs in the protocol because two renderers already cap by author choice
+off keys the protocol never declared: objectui's kanban board fetches
+`$top: schema.limit ?? DEFAULT_KANBAN_LIMIT` with `limit` declared in
+`@object-ui/types` alone, its timeline does the same off a component props
+interface, and its gallery caps not at all. `limit` is the name those consumers
+already read, so this declaration absorbs the consumer-local keys instead of
+introducing a second spelling of one concept.
+
+Nothing is removed, renamed or narrowed, and no document that parsed before is
+refused now. Two things to know when upgrading:
+
+- a parsed gallery / kanban / timeline config carries `limit: 100` where the author
+  wrote no ceiling, so code that compares a parsed config against a literal object
+  sees the new member;
+- `KanbanConfigParsed` is now declared (ADR-0122) because that schema has two shapes
+  for the first time; `KanbanConfig` is unchanged and remains the author state.
+
+The non-grid four — gantt, calendar, map and tree — are deliberately untouched:
+their rows stay bounded by a platform ceiling the renderer owns, because a gantt's
+range, a map's camera fit and a tree's parent chain are computed over the whole set.
+
+Clause-②: yes (widening)

.changeset/17487-confirmation-gate-prescriptions-present-tense.md

@@ -0,0 +1,72 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): the three shipped confirmation-gate prescriptions state the gate in the present tense — they were denying a door that exists (#17487)
+
+Clause-②: no
+
+No accept-set change and no export moves. `ToolSchema` still refuses
+`requiresConfirmation` with a located parse error, `ActionSchema` still accepts
+`ai.requiresConfirmation` in both directions, and `check:authorable-surface` /
+`check:api-surface` are byte-identical across this diff. What moves is text.
+
+Three customer-facing prescriptions were written while the runtime confirmation
+door was a separate, unlanded change, and each said so in the present tense. The
+door has since landed on `main` — `actionConfirmationRefusal`, called pre-dispatch
+by `invokeBusinessAction` in `@objectstack/runtime`, with the `confirm` member
+grown on the MCP `run_action` tool in the same change. From that moment the
+published prose DENIED a door that exists, and it denied it in the dangerous direction: an author who
+reads it concludes the safety flag stops nothing and either arranges a human in
+the loop some other way or stops setting the flag — losing the gate exactly when
+it starts working. That is the ADR-0049 false-compliance defect with the sign
+flipped.
+
+**The three carriers**, all of them shipped text rather than comments:
+
+1. the `requiresConfirmation` entry of `TOOL_RETIRED_KEY_GUIDANCE`
+   (`ai/tool.zod.ts`), which reaches consumers as the parse error on the
+   `.strict()` `ToolSchema` — the one channel every consumer bumping
+   `@objectstack/spec` is guaranteed to hit;
+2. the ADR-0087 D3 entry's `replacement`, and
+3. its `acceptanceCriteria` — what `spec-changes.json`,
+   `docs/protocol-upgrade-guide.md` and `os migrate meta` project to consumers.
+
+FROM → TO, on the sharpest of the three (the acceptance criterion):
+
+```
+was:  Do NOT try to "prove the gate" by invoking the operation without the
+      confirmation member: ... before that ships the call is not refused, it
+      RUNS the destructive operation.
+now:  ... that gate is PERFORMED: invoking the operation over an AI-exposed
+      door without the confirmation member is REFUSED with
+      ACTION_CONFIRMATION_REQUIRED (428) and nothing runs, so that call is a
+      real check you can make rather than a destructive experiment.
+```
+
+**The corrections carry the door's BOUNDS, because over-promising here is the
+same defect in the other direction.** Each prescription now states, as the door
+itself declares them: the refusal is `ACTION_CONFIRMATION_REQUIRED` / 428 naming
+the action and the member `confirm: true`; it is a GATE, not a queue — nothing
+is parked and a refused call did not run, no record read and none written; the
+enforced set is the doors that enforce the author's `ai.exposed` opt-in, today
+the action door reached from the MCP `run_action` tool, while REST `/actions` is
+not `ai.exposed`-gated and sits outside the gate; only the author's declared
+`ai.requiresConfirmation: true` refuses, while the wider listing heuristic
+advises and never refuses; and `confirm: true` is an unverifiable caller claim,
+so the gate makes FORGETTING loud without proving a human.
+
+`ai/tool-confirmation-prescription-tense.pin.test.ts` is the tie that was
+missing the first time: it reads the three shipped strings AND the runtime door,
+so a prescription that re-acquires a not-yet-shipped denial fails, and a door
+that is removed, narrowed off the DECLARED flag, unhooked from
+`invokeBusinessAction`, or widened onto REST `/actions` fails naming both files.
+The denial predicate is fed the three retired sentences verbatim, so it cannot
+pass by the prose merely falling silent.
+
+**On release ordering.** The door ships in the same release this correction
+does: the runtime changeset that carries it (`action-confirmation-gate-enforced`)
+is still pending alongside this one, and one `changeset version` run consumes
+both. A release cut before this lands is the failure this card exists to end —
+the runtime refusing calls while the published spec text tells authors the flag
+stops nothing.

.changeset/18639-related-list-columns-listcolumn-union.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": minor
+---
+
+`record:related_list.columns` now declares the SAME union the saved-view key declares — `z.union([z.array(z.string()), z.array(ListColumnSchema)])` — so a saved view's per-column decoration reaches the related list instead of being refused at the block door (#18639, the upstream half of objectui#9593).
+
+**Clause-②: yes (widening)** — one published accept set grows: the key admitted `string[]` and now also admits `ListColumn[]`. Nothing previously admitted is refused, no key is renamed or retired, and no producer is required to write the new arm. Contract-review tier.
+
+Two published declarations disagreed about one key. `RecordRelatedListProps.columns` (`ui/component.zod.ts`) was `z.array(z.string())`, while `listViews[].columns` (`ui/view.zod.ts`) was already the union — and objectui composes a saved view's `columns` onto this block **verbatim** (`dataSource.view` → `composeElementDataSource` → `savedViewColumns`). A view whose columns carried `label` / `width` / `hidden` / `summary` therefore arrived at a block that declared it could not carry them.
+
+- **The same union, by reference — not a lookalike.** `ListColumnSchema` is imported from the view face rather than re-spelled, so the object arm is one def with two carriers. The pin asserts reference identity on both sides and then asserts block and saved view return the same verdict for every fixture: two spellings of one key is the defect this closes, so a second spelling would not have fixed it.
+- **The arms are exclusive, and the description says so because the schema enforces it.** `['name', { field: 'amount' }]` matches neither arm and is refused. The decoration also survives the parse — a description promising keys a parse strips would be the same defect one layer up, so the pin asserts the parsed value, not merely `success`.
+- **Unchanged, by ruling and by measurement.** `field.relatedListColumns` stays child field-name STRINGS only and still refuses a column object with its derivation prescription, and the `field-column-lists-canonicalized` conversion still folds an object entry on that key to its identity string. Both are pinned next to the widening so the fences cannot erode quietly.
+
+No migration: authors writing `string[]` are unaffected, and the new arm is opt-in.

.changeset/18973-ragflow-reads-declared-adapter-config.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/knowledge-ragflow": patch
+---
+
+The RAGFlow adapter now reads the declared key: a source's RAGFlow binding comes from `adapterConfig.datasetId`, not `options.datasetId`.
+
+`KnowledgeSourceSchema` declares `adapterConfig` for adapter-specific configuration and is a plain `z.object` — it carries no `.passthrough()`, so any path that parses a source drops `options` before an adapter ever sees it. The adapter read `options` through a cast, which worked only because no path parses a source today. The cast is gone; there is no fallback that also reads `options` (Prime Directive #12 — one strict contract, no lenient consumer).
+
+Migration, `FROM` → `TO`, one line per source:
+
+```ts
+// FROM
+{ id: 'product_docs', adapter: 'ragflow', options: { datasetId: 'rgf_…' } }
+// TO
+{ id: 'product_docs', adapter: 'ragflow', adapterConfig: { datasetId: 'rgf_…' } }
+```
+
+The same move applies to `rerankModel`, `similarityThreshold` and `vectorSimilarityWeight`, which the adapter reads from the same bag. A source left on the old spelling is refused by name — `RAGFlow adapter requires source.adapterConfig.datasetId on source '<id>'` — rather than silently retrieving nothing, so the upgrade is self-describing at the first call. Nothing an author could declare is removed: `options` was never a key `KnowledgeSourceSchema` accepted, which is why this carries no ADR-0087 conversion.
+
+The package's published `README.md` moves with the adapter and now compiles against it — it was the one block of the 44 that #18915 could not repair, because correcting the spelling alone would have compiled and stopped working.
+
+Clause-②: no

content/docs/references/api/protocol.mdx

@@ -1674,7 +1674,7 @@ The published metadata item body, opaque by ruling (1C). Shape is the item's own
 | **selection** | `{ type?: Enum<'none' \| 'single' \| 'multiple'> }` | optional | Row selection configuration |
 | **navigation** | `{ mode?: Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>; preventNavigation?: boolean; openNewTab?: boolean; size?: Enum<'auto' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'>; … }` | optional | Configuration for item click navigation (page, drawer, modal, etc.) |
 | **pagination** | `{ pageSize?: integer; pageSizeOptions?: integer[] }` | optional | Pagination configuration |
-| **kanban** | `{ groupByField: string; summarizeField?: string; titleField?: string; columns: string[] }` | optional | Kanban-board configuration — applies when the view renders as a kanban layout |
+| **kanban** | `{ groupByField: string; summarizeField?: string; titleField?: string; columns: string[]; … }` | optional | Kanban-board configuration — applies when the view renders as a kanban layout |
 | **calendar** | `{ startDateField: string; endDateField?: string; titleField?: string; colorField?: string; … }` | optional | Calendar configuration — applies when the view renders as a calendar layout |
 | **gantt** | `{ startDateField: string; endDateField: string; titleField: string; progressField?: string; … }` | optional | Gantt-timeline configuration — applies when the view renders as a gantt layout |
 | **gallery** | `{ coverField?: string; coverFit?: Enum<'cover' \| 'contain'>; cardSize?: Enum<'small' \| 'medium' \| 'large'>; titleField?: string; … }` | optional | Gallery/card view configuration |
@@ -1759,7 +1759,7 @@ The published metadata item body, opaque by ruling (1C). Shape is the item's own
 | **selection** | `{ type?: Enum<'none' \| 'single' \| 'multiple'> }` | optional | Row selection configuration |
 | **navigation** | `{ mode?: Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>; preventNavigation?: boolean; openNewTab?: boolean; size?: Enum<'auto' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'>; … }` | optional | Configuration for item click navigation (page, drawer, modal, etc.) |
 | **pagination** | `{ pageSize?: integer; pageSizeOptions?: integer[] }` | optional | Pagination configuration |
-| **kanban** | `{ groupByField: string; summarizeField?: string; titleField?: string; columns: string[] }` | optional | Kanban-board configuration — applies when the view renders as a kanban layout |
+| **kanban** | `{ groupByField: string; summarizeField?: string; titleField?: string; columns: string[]; … }` | optional | Kanban-board configuration — applies when the view renders as a kanban layout |
 | **calendar** | `{ startDateField: string; endDateField?: string; titleField?: string; colorField?: string; … }` | optional | Calendar configuration — applies when the view renders as a calendar layout |
 | **gantt** | `{ startDateField: string; endDateField: string; titleField: string; progressField?: string; … }` | optional | Gantt-timeline configuration — applies when the view renders as a gantt layout |
 | **gallery** | `{ coverField?: string; coverFit?: Enum<'cover' \| 'contain'>; cardSize?: Enum<'small' \| 'medium' \| 'large'>; titleField?: string; … }` | optional | Gallery/card view configuration |

content/docs/references/data/object.mdx

@@ -374,7 +374,7 @@ const result = ApiMethod.parse(data);
 | **selection** | `{ type?: Enum<'none' \| 'single' \| 'multiple'> }` | optional | Row selection configuration |
 | **navigation** | `{ mode?: Enum<'page' \| 'drawer' \| 'modal' \| 'split' \| 'popover' \| 'new_window' \| 'none'>; preventNavigation?: boolean; openNewTab?: boolean; size?: Enum<'auto' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'>; … }` | optional | Configuration for item click navigation (page, drawer, modal, etc.) |
 | **pagination** | `{ pageSize?: integer; pageSizeOptions?: integer[] }` | optional | Pagination configuration |
-| **kanban** | `{ groupByField: string; summarizeField?: string; titleField?: string; columns: string[] }` | optional | Kanban-board configuration — applies when the view renders as a kanban layout |
+| **kanban** | `{ groupByField: string; summarizeField?: string; titleField?: string; columns: string[]; … }` | optional | Kanban-board configuration — applies when the view renders as a kanban layout |
 | **calendar** | `{ startDateField: string; endDateField?: string; titleField?: string; colorField?: string; … }` | optional | Calendar configuration — applies when the view renders as a calendar layout |
 | **gantt** | `{ startDateField: string; endDateField: string; titleField: string; progressField?: string; … }` | optional | Gantt-timeline configuration — applies when the view renders as a gantt layout |
 | **gallery** | `{ coverField?: string; coverFit?: Enum<'cover' \| 'contain'>; cardSize?: Enum<'small' \| 'medium' \| 'large'>; titleField?: string; … }` | optional | Gallery/card view configuration |