Merge remote-tracking branch 'origin/main' into claude/fieldnode-nested-select-form-tygnzg

Author: claude

.changeset/document-weak-pass-variants.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(ui,protocol): document the six navigation / knowledge-source variants that the #4177 variant/doc gate was only ever name-checking. `apps.mdx` enumerated nine navigation item types but gave `report`, `action` and `component` a single shared sentence instead of sections; `knowledge.mdx` named `object` / `file` / `http` in a table with no example of any, leaving the per-kind keys undocumented. Each example was parsed against the real schema (`NavigationItemSchema`, `KnowledgeSourceKindSchema`) before landing. Documentation only; releases nothing.

.changeset/flow-max-retries-single-default.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": major
+"@objectstack/service-automation": major
+---
+
+fix(spec,service-automation)!: `errorHandling.maxRetries` has one default, and `strategy: 'retry'` states its count (#4247)
+
+`flow.errorHandling.maxRetries` was declared twice, with different values:
+
+- **spec** — `FlowSchema` (`automation/flow.zod.ts`): `.default(0)`
+- **engine** — `retryExecution` (`service-automation/src/engine.ts`):
+  `errorHandling.maxRetries ?? 3`
+
+`??` fires only on `undefined`, so the winner was decided by the ROUTE a flow
+took into the engine, not by what its author wrote:
+
+| Path | `errorHandling.maxRetries` | Retries |
+|:---|:---|---:|
+| parsed by `FlowSchema` (`.default(0)` fills it) | `0` | **0** |
+| object built by hand and fed to the engine | `undefined` | **3** |
+
+One authored intent — "I didn't write a count" — two behaviors. The neighbouring
+`retryDelayMs ?? 1000` / `backoffMultiplier ?? 1` agreed with their `.default()`s;
+only `maxRetries` disagreed, which reads as a schema default changed from 3 to 0
+without the engine following, not as a deliberate two-track design.
+
+**The engine keeps no defaults of its own.** `retryExecution` now takes the
+parsed `NonNullable<FlowParsed['errorHandling']>` and destructures all five
+knobs — no `??`. This is safe because `AutomationEngine.flows` only ever holds
+`FlowSchema.parse` output (`registerFlow` parses; the version-history rollback
+re-seats an already-parsed snapshot), and it is what keeps a second set of
+defaults from growing back: a knob the spec stops defaulting becomes a compile
+error rather than a silent engine-side guess. Per Prime Directive #12 the spec
+is the one contract; a consumer-side fallback is a second de-facto one.
+
+**BREAKING — `strategy: 'retry'` now requires `maxRetries` >= 1.** With the
+engine's copy gone, an unstated count is unambiguously `0`, and `'retry'` with 0
+attempts runs the flow once and stops — i.e. `strategy: 'fail'` wearing another
+label, a declared capability the runtime does not deliver (Prime Directive #10
+corollary). Rather than pick 0 or 3 on the author's behalf, `FlowSchema` refuses
+the combination in both spellings (omitted → defaulted 0, and an explicit 0),
+with the prescription in the message. A retry re-runs the **whole flow from the
+start** — records created again, callouts fired again — which is not a number to
+guess for someone.
+
+FROM → TO:
+
+- `errorHandling: { strategy: 'retry' }` → `errorHandling: { strategy: 'retry', maxRetries: 3 }`
+  (or `strategy: 'fail'` if no retry was intended — that is what it did).
+- `errorHandling: { strategy: 'retry', maxRetries: 0 }` → same choice, spelled out.
+
+Unaffected: `maxRetries: 0` under `strategy: 'fail'` / `'continue'` (neither
+reads it, and a fully spelled-out block stays legal), flows with no
+`errorHandling` at all, and every flow that already states a count — including
+the `try_catch` node's own `config.retry`, which is a separate per-region policy
+(`control-flow.zod.ts`) and is unchanged.

.changeset/recursive-schema-input-pins.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": patch
+---
+
+test(spec): pin the input half of every recursive schema, so the third omission fails instead of shipping (#3786)
+
+A recursive Zod schema cannot infer its own type, so it carries a hand-written
+`z.ZodType<...>` annotation. `z.ZodType` takes **two** type parameters,
+`<Output, Input>`, and `Input` defaults to `unknown`. Naming only the first
+compiles, validates correctly at runtime, and silently un-types every authoring
+path through the schema — `unknown` accepts everything.
+
+This package has made that mistake twice:
+
+1. **#4171** replaced `z.ZodType<any>` on the nav union with
+   `z.ZodType<NavigationItem>`, fixing the output half. `check-exported-any.ts`
+   was built to hold that fix and reads output only, so it reported green over
+   the half that was still broken.
+2. **#4221** found the consequence — `defineApp`, the documented authoring entry
+   point, compiled `navigation: [{ totally: 'made up' }, 42, 'nonsense']` clean —
+   and **#4227** then named both parameters on the six remaining recursive
+   schemas.
+
+Both fixes are correct and both are currently unpinned. #4227 considered a
+`.d.ts`-level scanner and declined it for a good reason: separating a deliberate
+single-parameter `z.ZodType<T>` (the generic in `contracts/llm-adapter.ts` takes
+a caller-supplied schema, where the input side is nobody's business) from an
+omission needs heuristics on emitted type names, and `check-exported-any.ts`'s
+own rule is zero false positives so red keeps meaning broken. Its commit
+nominated #4221's assertion-file pattern instead. This is that pattern, applied
+to the eight schemas #4221 did not cover: `QuerySchema`, `JoinNodeSchema`,
+`FieldNodeSchema`, `FilterConditionSchema`, `NormalizedFilterSchema`,
+`StateNodeSchema`, `ValidationRuleSchema`, `FormFieldSchema`.
+
+`src/recursive-schema-input-assertions.ts` gives each one a positive probe (the
+authoring shape still compiles — guarding an input type drawn too tight) and a
+negative probe reached **through `z.input<typeof Schema>`**, the way a consumer
+gets there. The negative is load-bearing: it is a value `unknown` would accept
+and the real type rejects, so dropping a type parameter turns the suppression
+unused and `tsc --noEmit` fails on that line, by name.
+
+Verified by mutation in both shapes a regression can take:
+
+- `QuerySchema` back to one parameter → the pin fires **and** `JoinNodeSchema`
+  cascades a type error, because `JoinNodeInput.subquery` is `QueryInput`.
+- `StateNodeSchema` back to one parameter → **only** the pin fires. Nothing else
+  in the package references its input, so without this file that regression is
+  completely silent. That is the case the file exists for.
+
+No runtime change, no new public export (`check:api-surface` reports no diff);
+the module is referenced by no tsup entry and re-exported by no barrel.
+
+Also classifies `check:strictness-ledger` in `check-generated.ts`'s ledger. It
+landed in #4232 without an entry, so `check:generated` was failing on `main`
+itself — the same cross-PR race the `check:variant-docs` entry above it already
+documents, now on its second occurrence.

.changeset/standard-endpoints-parity-correction.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/runtime": patch
+---
+
+test(runtime): correct the #4073 evidence — the `registerStandardEndpoints` flip IS a no-op for a composed host
+
+#4192 added a test concluding that turning the flag off makes `/api/v1/data/:object`
+a 404, and blocked the #4073 retirement on it. That conclusion was wrong.
+
+It mounted `createRestApiPlugin({})` against a STUB `objectql` service. REST
+generates CRUD from the object registry, so it needs a real engine — driver plus
+registered objects — and its own `api.api` config. Under-provisioned it serves
+nothing, which says nothing about REST.
+
+Provisioned the way `client.environment-scoping.test.ts` does it (that suite runs
+`registerStandardEndpoints: false` and asserts `GET /api/v1/data/task` → 200 from
+REST), `/data/:object`, `/discovery` and `/.well-known/objectstack` all return
+byte-identical responses with the flag on and off.
+
+The test now asserts that parity directly rather than a status code, because a
+status was what misled it: `/data/task` answers 404 `OBJECT_NOT_FOUND` here — the
+engine's answer, i.e. a route that WORKS — where a routing miss would be
+`{"error":"Not found"}`. A separate assertion pins that the compared routes are
+live, so parity cannot be satisfied by two identical misses.
+
+No production code changes. The default is untouched: flipping it is still a real
+change for a BARE host mounting neither REST nor the dispatcher, and that is an
+API decision, not one this test makes.

.changeset/sys-migration-ledger-platform-infra.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/platform-objects": minor
+"@objectstack/service-storage": patch
+"@objectstack/cli": patch
+---
+
+feat(platform-objects,service-storage,cli): `sys_migration` is platform infrastructure — registered by `PlatformObjectsPlugin`, not by the storage service (#4243)
+
+The deployment-level data-migration flag ledger (`sys_migration`, #3617) was
+registered by `@objectstack/service-storage` as its first consumer. That was
+deliberate while the file migration was the only consumer, but the ledger now
+gates storage-independent behaviour too — `os migrate value-shapes` (#4235)
+and the fresh-datastore attestation (#4215) — and a non-file migration had to
+boot the whole storage plugin just so the kernel carried the table. Any kernel
+assembled without storage silently had no ledger at all, which read exactly
+like "migration not run" (both answer false) while actually meaning "ledger
+not installed".
+
+The registration now lives in `PlatformObjectsPlugin`
+(`@objectstack/platform-objects/plugin`) — the plugin `os serve` already
+auto-injects into every served kernel — so the ledger exists with the
+platform, independent of which optional services are composed. The
+fresh-datastore attestation (#3438, ADR-0104) moves with it: it is ledger
+bookkeeping, and its old home justified itself as "the service that registers
+`sys_migration`". Definition ownership is unchanged (`sys_migration` stays in
+`@objectstack/platform-objects` and in `PLATFORM_OBJECTS_BY_PACKAGE`); the
+flag helpers and readers are untouched.
+
+Consequences:
+
+- `@objectstack/service-storage` no longer contributes `sys_migration` to the
+  manifest and no longer performs the fresh-datastore attestation. An embedder
+  composing `StorageServicePlugin` on a hand-built kernel that relied on it
+  for the ledger must compose `PlatformObjectsPlugin` (the plugin every
+  supported assembly path already includes).
+- The CLI's `buildDataMigrationPlugins()` no longer boots storage for every
+  gated migration — it registers `PlatformObjectsPlugin` always, and settings
+  + storage only for `os migrate files-to-references` (`{ storage: true }`),
+  the one migration that actually reconciles against the storage adapter.

.changeset/vacuous-filter-carveouts.md

@@ -0,0 +1,6 @@
+---
+---
+
+test(objectql): pin the two vacuous-filter carve-outs (#4121, #4181)
+
+Test-only; no package behavior changes, so this changeset releases nothing.

content/docs/automation/flows.mdx

@@ -665,7 +665,7 @@ The two recovery mechanisms operate at different scopes and do not compound:
 | | Scope | On failure |
 | :--- | :--- | :--- |
 | `fault` edge | one node | traversal continues from the handler; the run completes |
-| `errorHandling: { strategy: 'retry' }` | the whole flow | the flow re-runs **from the start** |
+| `errorHandling: { strategy: 'retry', maxRetries: n }` | the whole flow | the flow re-runs **from the start**, up to `n` more times |
 
 A failure a fault edge handled is not a flow failure, so it does **not** consume
 a retry. That matters because flow-level retry replays every node that already
@@ -707,13 +707,46 @@ errorHandling: {
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `strategy` | `enum` | `'fail'` (stop) or `'retry'` (re-run the whole flow). `'continue'` parses but the engine branches only on `'retry'`, so it behaves exactly like `'fail'` — use a `fault` edge to keep going past a failed node |
-| `maxRetries` | `number` | Maximum retry attempts (0-10) |
-| `retryDelayMs` | `number` | Delay between retries (ms) |
+| `strategy` | `enum` | `'fail'` (stop) or `'retry'` (re-run the whole flow). `'continue'` parses but the engine branches only on `'retry'`, so it behaves exactly like `'fail'` — use a `fault` edge to keep going past a failed node (default `'fail'`) |
+| `maxRetries` | `number` | Retry attempts **after** the initial one, `0`–`10`. Under `strategy: 'retry'` it must be at least `1` and there is no default — see below (default `0`, i.e. no retries, for the strategies that never retry) |
+| `retryDelayMs` | `number` | Delay between retries (ms) (default `1000`) |
 | `backoffMultiplier` | `number` | Exponential backoff multiplier (default `1`) |
 | `maxRetryDelayMs` | `number` | Ceiling on the backed-off delay (default `30000`) |
 | `jitter` | `boolean` | Randomize the delay to avoid a thundering herd (default `false`) |
 
+`maxRetries` counts the **re-runs**, not the total attempts: `maxRetries: 2`
+runs the flow up to three times.
+
+### `strategy: 'retry'` has to say how many times
+
+There is no default retry count. `strategy: 'retry'` without `maxRetries` — or
+with `maxRetries: 0` — is refused when the flow is registered:
+
+```typescript
+// ❌ rejected: "retry" that retries zero times is just "fail"
+errorHandling: { strategy: 'retry' }
+
+// ✅ state the attempts
+errorHandling: { strategy: 'retry', maxRetries: 3, retryDelayMs: 5000 }
+```
+
+A retry re-runs the **whole flow from the start**, so every node that already
+succeeded runs again — records get created again, callouts fire again. That is
+too consequential a number to pick on the author's behalf, and picking `0`
+would make opting into `'retry'` do nothing at all. The knobs above are read
+only under `'retry'`; a fully spelled-out block under `'fail'` or `'continue'`
+is fine and simply ignored.
+
+<Callout type="info">
+  Before ObjectStack 17 the count depended on how the flow reached the engine:
+  a flow parsed by `FlowSchema` retried `0` times when the count was unstated,
+  while a hand-built definition passed straight to the engine retried `3` — the
+  schema and the engine each carried a default and they disagreed
+  ([#4247](https://github.com/objectstack-ai/objectstack/issues/4247)). The
+  engine's copy is gone; the schema is the only source, and the case that was
+  ambiguous is now rejected instead of guessed.
+</Callout>
+
 ## Discovery & Registration
 
 You almost never call `engine.registerFlow()` directly. The

content/docs/protocol/knowledge.mdx

@@ -119,6 +119,34 @@ Three source kinds:
 | `file`   | A folder in `IStorageService`                       | Onboarded PDFs, uploads         |
 | `http`   | A list of remote URLs                               | External docs, RSS, sitemaps    |
 
+`kind` is the discriminator, and each kind carries its own keys — a key from one
+kind is rejected on another:
+
+```typescript
+// object — content comes from the named fields of each matching record
+source: {
+  kind: 'object',
+  object: 'kb_article',
+  contentFields: ['title', 'body'],       // at least one, required
+  metadataFields: ['category', 'author'], // optional, carried onto the document
+  where: { status: 'published' },         // optional ObjectQL filter
+}
+
+// file — every object under a storage prefix
+source: {
+  kind: 'file',
+  prefix: 'knowledge/handbook/',
+  mimeTypes: ['application/pdf', 'text/markdown'], // optional; omit to take all
+}
+
+// http — an explicit URL list (each must be a valid URL)
+source: {
+  kind: 'http',
+  urls: ['https://docs.example.com/guide', 'https://docs.example.com/faq'],
+  userAgent: 'ObjectStack-KnowledgeBot/1.0', // optional
+}
+```
+
 Every source binds to a named **adapter id** (e.g. `'ragflow'`,
 `'memory'`). The adapter id is resolved at runtime by the plugin that
 registers itself with that name. Adapter config (endpoint, dataset id,

content/docs/releases/v17.mdx

@@ -930,6 +930,17 @@ from `@objectstack/spec` directly.
 - **`sys_view_definition`'s all-six `apiMethods` whitelist is dropped** (#3026).
 - **`os migrate plan` shows index drift** — index DDL is no longer applied
   silently at boot (#3728).
+- **A flow's `errorHandling.strategy: 'retry'` must state `maxRetries` (>= 1)**
+  (#4247). `maxRetries` had two defaults — `.default(0)` in `FlowSchema` and
+  `?? 3` in the engine's `retryExecution` — so an unstated count retried 0 times
+  for a flow that had been through the schema and 3 times for a definition
+  handed to the engine directly. The engine's copy is gone (it reads the parsed
+  block with no fallback), and the case that was ambiguous is rejected rather
+  than guessed: retrying zero times is `strategy: 'fail'` under another name,
+  and a retry re-runs the *whole* flow, so the count is the author's to state.
+  Fix: write `{ strategy: 'retry', maxRetries: 3 }`, or `strategy: 'fail'` if no
+  retry was intended. `maxRetries: 0` stays legal under `'fail'` / `'continue'`,
+  which never read it.
 
 ## New capabilities in 17.0.0
 

content/docs/ui/apps.mdx

@@ -57,7 +57,11 @@ const crmApp = {
 
 ## Navigation Items
 
-The navigation tree supports nine item types, combined to create rich menu structures. The most common are shown below (`object`, `dashboard`, `page`, `url`, `group`, `separator`); the spec also defines `report`, `action`, and `component` items.
+The navigation tree supports nine item types, combined to create rich menu structures: `object`, `dashboard`, `page`, `url`, `report`, `action`, `component`, `group` and `separator`. Each is documented below.
+
+`type` is the discriminator: a value outside that list is rejected with the full
+set of valid ones, and every other key is checked against the branch you picked
+rather than against all nine.
 
 ### Object Navigation
 
@@ -121,6 +125,48 @@ Groups items into collapsible sections with children:
 }
 ```
 
+### Report Navigation
+
+Links to a saved report:
+
+```typescript
+{ id: 'nav_pipeline', type: 'report', label: 'Pipeline Report', reportName: 'sales_pipeline', icon: 'file-bar-chart' }
+```
+
+### Action Navigation
+
+Runs an action instead of navigating to a surface. The reference lives in a
+nested `actionDef` block — `actionName` is **not** a top-level key on the item:
+
+```typescript
+{
+  id: 'nav_import',
+  type: 'action',
+  label: 'Import Records',
+  icon: 'upload',
+  actionDef: {
+    actionName: 'bulk_import',
+    params: { objectName: 'account', mode: 'upsert' },
+  },
+}
+```
+
+`actionDef` accepts only `actionName` and `params`. `params` itself is **open by
+design** — the action owns its own parameter contract, so the app schema does
+not validate what goes inside it.
+
+### Component Navigation
+
+Renders a registered component. `componentRef` is a component-registry key, not
+a file path:
+
+```typescript
+{ id: 'nav_directory', type: 'component', label: 'Directory', componentRef: 'metadata:directory', icon: 'contact' }
+```
+
+`params` is handed to the component as props and is **open by design** — the
+props are the component's own contract.
+
 ### Separator
 
 A visual divider in the navigation list. It renders no target and carries no