Merge remote-tracking branch 'origin/main' into claude/issue-16233-agents-return-propagating-seams

Author: claude

.changeset/15124-action-engine-facade-find-query-envelope.md

@@ -0,0 +1,93 @@
+---
+'@objectstack/spec': minor
+'@objectstack/runtime': minor
+---
+
+**BREAKING for action handlers** — `ActionEngineFacade.find` takes the engine's query ENVELOPE; the bare-filter parameter shape is withdrawn (#15124)
+
+Clause-②: yes (narrowing)
+
+`ctx.engine.find(object, query)` now takes `EngineQueryOptions` — the same
+options bag `IDataEngine.find` and ObjectQL's own `engine.find` take, named by
+identity rather than restated. **One platform, one query shape.**
+
+### Migration — FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `ctx.engine.find('task', { status: 'open' })` | `ctx.engine.find('task', { where: { status: 'open' } })` |
+| `ctx.engine.find('task', { amount: { $gt: 100 } })` | `ctx.engine.find('task', { where: { amount: { $gt: 100 } } })` |
+| `ctx.engine.find('task', {})` | unchanged — an empty envelope is still the unfiltered read |
+
+The rewrite is lossless and mechanical: the filter moves under `where`, verbatim.
+`tsc --noEmit` over your handlers finds every unmigrated call — see below.
+
+### Why the shape was withdrawn rather than the bar closed
+
+Until now this parameter was the `where` HALF of a query while every other
+`find` on the platform took the whole envelope, and the runtime wrapped what it
+was given. That made the most natural spelling the wrong one, silently: an
+author who passed the engine's own envelope reached the engine as
+`{ where: { where: … } }` — a filter on a field named `where` — which matches no
+row and resolves to `[]` with **no error at all**. A handler that made the
+mistake ran to completion over zero rows for as long as it shipped, and its own
+hand-written test double, written to the same belief, passed every assertion.
+Because an empty `{}` skipped the wrap, one unfiltered read kept working under
+either belief, so a dead handler looked partially alive.
+
+Refusing `where` at the top level instead — intersecting the old parameter with
+`{ where?: never }` — was rejected: it asserts a vocabulary fact the spec
+declares nowhere, reserving the field name `where` across every customer's data
+model to buy one parameter's compile-time check. Aligning the parameter removes
+the ambiguity at its root and reserves nothing.
+
+### What the new declaration refuses, measured
+
+If your handler is typed with the published `ActionHandlerContext`, a bare filter
+no longer type-checks on **either** path you can reach it by:
+
+- an object literal (`{ status: 'completed' }`) fails the excess-property check —
+  a field name is not an envelope key;
+- a filter held in a `FilterCondition` variable fails **TS2559** — every envelope
+  key is optional, so a bag of field names has no property in common with it.
+
+The envelope's own keys are typed too: `where: 'a = b'`, `fields: 'id,subject'`
+and `limit: '50'` are each refused.
+
+**If your handler is NOT typed with it** — a handler in an `objectstack.config.js`
+/ `.mjs`, one annotated with your own copy of the context type, or a `(ctx: any)`
+handler — nothing above reaches you, so the facade refuses the withdrawn shape at
+**runtime** instead, before the engine, with the same prescription:
+
+```
+find('task') was given a key 'status' the query envelope does not carry.
+ctx.engine.find(object, query) takes the engine QUERY ENVELOPE, not a bare
+filter — move the filter under `where`: find(object, { where: { … } }).
+Envelope keys: context, cursor, distinct, expand, fields, limit, offset,
+orderBy, search, searchFields, top, where.
+```
+
+⚠️ **That refusal matters most for a filter whose value is `null`.** The engine's
+own unknown-option check exempts a `null` value, because on an option bag a
+`null` is a withdrawal. On a filter it is the "rows with no X" idiom, so
+`{ deleted_at: null }` would have been dropped unexecuted and the read would have
+widened to **every row** — including the ones you were excluding — with no error
+at all. It is refused instead.
+
+### What this opens
+
+`fields`, `orderBy`, `limit`, `offset` and `expand` are reachable from an action
+handler for the first time — under the old parameter there was nowhere to carry
+them. A caller-supplied `context` is **ignored**: this facade is trusted and
+context-less by design, and the runtime stamps its own elevated
+`ExecutionContext` last. Do not write one — it reads as authorization and is
+none.
+
+### Checking a migrated handler
+
+Do not settle for "it still resolves". A handler that had been passing the
+envelope was returning `[]` on **every** call, so a suite written against the
+mistake passes and the row count is the only witness. Re-run each migrated
+handler against seeded data and assert it returns the rows its filter selects.
+
+<!-- adr-0087: registered action-engine-facade-find-query-envelope -->

.changeset/16045-spec-declaration-text-snapshots.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/17393-view-row-ceiling.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/17487-confirmation-gate-prescriptions-present-tense.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+---
+
+`SelectOptionSchema`'s six row properties carry a JSON Schema `title`, so Studio's property panel stops printing raw machine keys as the column headers of a field's `options` table (#17506).
+
+Clause-②: no
+
+Studio renders a `type: 'repeater'` form field as a table whose column headers read `items.properties[k].title ?? k` off the JSON Schema derived from the metadata type schema. `SelectOptionSchema` carried no `title` on any row property, so the fallback arm ran and the maker saw `label` / `value` / `description` / `color` / `default` / `visibleWhen` inside an otherwise translated panel — **in every locale, English included**. Titles are hard-coded English by design: `system/translation.zod.ts` states that a row property renders from `items.properties[k].title`, and `resolveMetadataFormSchemaTitles` only ever REPLACES a title that is already there, so an untitled property has no layer for a translation to overlay.
+
+- **One edit clears two carriers.** `field:options` and `object:fields.options` resolve to the *same* `SelectOptionSchema` object — `FieldSchema.options` is `z.array(SelectOptionSchema)` and `object.fields` is a `z.record(..., FieldSchema)` of that same `FieldSchema` — verified by object identity (`===`) against the schemas `getMetadataTypeSchema('field')` and `getMetadataTypeSchema('object')` actually return, with `FormSelectOptionSchema` as the firing control that the probe can tell two schemas apart. Both entries are deleted from the shrink-only `repeater-item-titles` ledger in the same change; `object.zod.ts` needed no edit.
+- **Nothing the schema accepts or refuses moved.** `.meta({ title })` is presentation metadata: the generated `authorable-surface/` artifacts are byte-identical, and the pinned accept/refuse suites for this shape (`editability-boundary`, `visible-when-alias-guidance`, `form-select-option`, `evaluated-slot-population`) pass unchanged.
+- **The form-view face inherits the titles for free.** `FormSelectOptionSchema` is a shape-level Omit that reuses the same property schema instances, so the five keys it keeps arrive titled too, and its `default`-refusal is untouched.