Merge remote-tracking branch 'origin/main' into claude/issue-16337-finddata-canonical-queryast

# Conflicts:
#	content/docs/permissions/system-context.mdx

Author: claude

.changeset/automation-resume-stranded-details.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": minor
+"@objectstack/runtime": minor
+"@objectstack/client": minor
+---
+
+The automation resume route's `400 FLOW_FAILED` now says whether the run is stranded.
+
+`POST /api/v1/automation/:name/runs/:runId/resume` answers a run that consumed its pause and then failed with `400 FLOW_FAILED`, and until now its `error.details` carried the run's two artefacts only (`errorMessage`, `summary`). The engine's own verdict was dropped at the door: `AutomationResult.status: 'stranded'` — a run that is terminally failed *but* repairable by an explicit operator verb, because the pause a durable decision was waiting on is gone with the failure — reached the wire as the same `400` a plain terminal failure does, so an HTTP-only caller could not tell "beyond reach" from "repair waiting".
+
+- **`@objectstack/spec`** declares `ResumeFailureDetailsSchema` (`@objectstack/spec/api`): `{ runId, status?: 'failed' | 'stranded', repairable }` — the machine-readable shape of a resume failure told to the caller, declared once so every carrier of the family ruling spells the same members.
+- **`@objectstack/runtime`**: the resume door's `400 FLOW_FAILED` details now carry that structure beside `errorMessage` / `summary`. `runId` is the run the resume was addressed to; `status` is the engine's own stamp, forwarded verbatim when it set one and never synthesised (the subflow-child-failed exit stamps none today); `repairable` is `status === 'stranded'` and is **always present on this arm** — present-and-false on a plain terminal failure, deliberately, so an absent member reads as an older server rather than as "not repairable". The code stays `FLOW_FAILED` (no `FLOW_STRANDED` sibling is minted), so a client that treats it as terminal keeps working and one that wants to offer a repair branches on `details.repairable`, never on the message text. The trigger door and `/actions` are unchanged: they never resume, so the member is absent there and absent means "not a resume".
+- **`@objectstack/client`**: `automation.resume` documents the new members.

.changeset/automation-service-operator-verbs-contract.md

@@ -0,0 +1,41 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare the two operator run-lifecycle verbs on `IAutomationService` — `cancelRun` and `restoreConsumedSuspension` (#16495, the contract half of #13953)
+
+`IAutomationService` (`contracts/automation-service.ts`) gains two OPTIONAL
+members, typed as the engine already implements them rather than as the
+ruling's `verb(runId)` shorthand, so a door calling through the contract can
+say who asked and why:
+
+- `cancelRun?(runId: string, reason?: string): Promise<boolean>` — end a
+  suspended run (ADR-0044's run-cancel primitive): `true` only when this call
+  consumed a suspension, `false` when none exists under the id (idempotent
+  success — and the answer an unreadable store lands on too, which the
+  implementation reports at `error`).
+- `restoreConsumedSuspension?(runId: string, options?: { requestedBy?: string; reason?: string })`
+  answering `{ restored: boolean; runId: string; refusal?: string; reason: string }`
+  — the operator exit from a run a resume left terminally unresumable
+  (`AutomationResult.status: 'stranded'`, #13909 / #13937): puts the consumed
+  suspension back verbatim, replays no signal, undoes nothing, never resumes,
+  never throws.
+
+Both docblocks carry the #13953 ruling's persistent-face statement (maintainer
+2026-09-05, decision batch #42): "listing and acting go through
+`sys_automation_run` (the persistent face), never engine memory" — and its
+permission posture: platform-operator verbs gated on the existing
+`platform_admin` position, no new permission type, no per-run ownership.
+
+Additive. Both members are optional, so every existing implementation —
+including the `{ execute, listFlows }` minimum the contract's own test pins —
+still conforms, and the one non-test implementor (`AutomationEngine` in
+`@objectstack/service-automation`) already satisfies both under `implements`.
+The result of `restoreConsumedSuspension` is a deliberately NARROWER
+structural shape than the engine's `SuspensionRestoreResult`: the engine's
+eight-member refusal vocabulary stays with the engine, so `refusal` is typed
+`string` on the contract (route (i); a second consumer that needs the
+vocabulary is a spec card). No REST route, CLI command, lister or engine
+behaviour moves in this change — #13953's services half owns the doors. A
+service that does not declare a verb has no operator door for it, and a door
+must probe for presence and refuse fail-closed when it is absent.

.changeset/lint-validate-expressions-non-record-field-entry.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/lint": patch
+---
+
+`validateStackExpressions` no longer throws on a non-record entry in an object's `fields:` list.
+
+An empty item in a YAML `fields:` list deserialises to `null`, and `buildFieldIndex` cast each member of the list inline (`fields.map(f => (f as AnyRec).name)`) before the `.filter` two calls later could drop it. `Array.isArray` proves the LIST, never its MEMBERS, so linting such a stack failed with `TypeError: Cannot read properties of null (reading 'name')` out of the whole rule instead of reporting anything about the file.
+
+The list is now read through `recordsOf` — the one place that coercion is decided — which drops a non-record member of the array shape whole and in **silence**: it carries no author-written name, so there is nothing to report about it. That matches what the two sibling field readers in the same module (`buildFieldTypeIndex`, `fieldEntries`) already did with the same member, so the three readers now agree. The readable siblings of the junk member are still indexed, so unknown-field findings on that object continue to be reported.
+
+The map shape (`fields: { amount: { … } }`) is unchanged: there the author's key is the field name, which is what this index needs.

.changeset/page-header-page-name-route-canonical.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/spec": minor
+---
+
+`translatePage` now reads a region-level `page:header` by **page name only**. The id route
+(`pages.<page>.components.<headerId>.*`) is no longer read for that component, even when it carries an `id`.
+
+**Behaviour change, stated plainly:** a bundle that overrode a region-level header's title through
+`pages.<page>.components.<headerId>.title` now falls back to `pages.<page>.title` (which itself falls back to
+`pages.<page>.label`). The components key still parses — nothing is removed from `TranslationBundleSchema` — it is
+simply no longer the address for this one component.
+
+```
+FROM  pages.<page>.components.<headerId>.title   # region-level page:header — no longer read
+TO    pages.<page>.title                         # …and .subtitle for the subtitle
+```
+
+Fix in one line: move the string from the components entry up to the page's own `title` key, and delete the
+components entry for that header id. `os i18n extract` has always offered exactly the `TO` key, so a bundle
+generated or checked by the CLI already writes it.
+
+**Blast radius, as measured on the card (inherited, not re-measured here):** HotCRM found **zero** such overrides —
+all five of its region-level headers carry ids and none writes the components key.
+
+**Why.** Both sides were deliberate and they disagreed. The extractor skips a region-level `page:header` on purpose
+(its copy is offered under `pages.<page>.title` / `.subtitle`, and emitting it twice would put one string under two
+keys); the resolver read the id route on purpose (the more specific route wins). Together they produced the exact
+failure `walkAddressedPageComponents` was extracted to prevent — the resolver reading an id the extractor omits — so
+the key an author reached for won silently while the key the tooling reported as translated lost. The maintainer
+ruled (2026-09-06, decision batch #58, verbatim 「同意」) that the page-name route is canonical: one component, one
+address. `title` and `subtitle` now follow the same rule, closing the asymmetry where `title` had two addresses and
+`subtitle` — never in `PAGE_COMPONENT_COPY_KEYS` — had one.
+
+Unchanged: a `page:header` **nested** inside a container is reached by the id route only, as it always has been; and
+a region-level header's id still claims its bundle entry and still blocks a nested namesake, which is what the
+extractor does too.
+
+Not `major`: nothing an author can write is removed or renamed. `pages.<page>.components.<id>` remains a declared,
+parsing, resolving address for every other component — including a nested `page:header` — so there is no key to
+tombstone and no ADR-0087 conversion to register. Recorded here so the choice is checkable rather than assumed.

.changeset/plugin-schema-ui-required-keys.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/spec": minor
+"@objectstack/core": minor
+---
+
+`PluginSchema` now REQUIRES `staticPath` and `slug` when `type` is `'ui'`, and core's `Plugin` interface inherits every `PluginSchema` key from `PluginDefinition` instead of restating two of them.
+
+**BREAKING** accept-set narrowing on a published schema, shipped as `minor` under the repo's launch-window convention for breaking changes (`scripts/check-changeset-no-major.mjs`). `packages/spec/src/kernel/plugin.zod.ts` described `staticPath` and `slug` as *"Required for type=\"ui\""* while declaring both `.optional()`, with nothing behind the prose; since `kernel.use()` runs the schema on the boot path (#16049), that was a promise the runtime visibly did not keep. This is the spec half of #16049, split by director ruling (decision batch #58, 2026-09-06).
+
+**Exactly what is newly refused.** A plugin object with `type: 'ui'` that omits `staticPath`, omits `slug`, or spells either as `undefined`. Nothing else: every other declared type (`standard`, `driver`, `server`, `app`, `theme`, `agent`, `objectql`), and a plugin declaring no `type` at all, still parses with neither key. A PRESENT value is judged exactly as before — `slug` keeps its `/^[a-z0-9-_]+$/` regex, `staticPath` stays any string, and the empty string is not refused by this change.
+
+**What a refusal looks like.** One zod issue per missing key, `path` naming the key, the new stable code `PLUGIN_UI_REQUIRED_KEY_MISSING` (exported from `@objectstack/spec/kernel`) at the head of the issue `message` and on the issue's `params.code`. At `kernel.use()` it rides the existing `PLUGIN_CONTRACT_VIOLATION` envelope unchanged, because the loader surfaces the first issue's `path` and `message` and reads nothing else:
+
+```
+PLUGIN_CONTRACT_VIOLATION: plugin '@acme/console' is refused by the declared
+plugin contract at 'staticPath': PLUGIN_UI_REQUIRED_KEY_MISSING: a `type: 'ui'`
+plugin must declare `staticPath` — the absolute path of the static assets it
+serves. Declare it, or drop `type: 'ui'` if this plugin serves no assets.
+```
+
+**The fix for an affected plugin** is the one the message names: declare both keys (`staticPath`: the absolute path of the assets it serves; `slug`: the URL segment it is mounted under), or drop `type: 'ui'` if the plugin serves no assets. There is no fallback to lean on: the Hono server's `slug || name.split('/').pop()` derivation is no longer reachable through the kernel, because the object is refused before it is stored.
+
+**`@objectstack/core` — `Plugin` derives its metadata keys.** `Plugin` now `extends PluginDefinition` (`z.input<typeof PluginSchema>`), so `id`, `type`, `staticPath`, `slug`, `default`, `version`, `description`, `author` and `homepage` are ONE declaration shared with the schema the kernel enforces. Additive for every existing implementer: `type` and `version` keep the shapes they had (`type` is still `PluginType | undefined`, pinned type-equal in `packages/rest`; `version` still `string | undefined`), and the seven other keys are new optional members. A `ui` plugin can now carry `staticPath` / `slug` without widening its own type. Runtime-only members (`name`, `dependencies`, `optionalDependencies`, `requiresServices`, `providesServices`, `init`, `start`, `destroy`) stay declared on the interface.
+
+**Blast radius, measured.** No in-repo plugin object outside test fixtures declares `type: 'ui'` (searched `packages/`, `apps/`, `examples/` non-dist sources for a `type` key or class field holding the literal `'ui'`: three test files, nothing shipped), so no in-repo composition changes behaviour. Externally authored `ui` plugins that relied on the slug derivation, or declared no assets, are the population this reaches — and they are refused at boot, by name, with the key to add.
+
+<!-- adr-0087: not-required (no-migration-prescription) An accept-set narrowing on plugin OBJECTS, which are never stored metadata: `PluginSchema` gains a refinement and one exported constant; no metadata key, object definition or stored representation is added, removed or renamed, so `objectstack migrate meta` has nothing to visit and there is no tombstone to mint. The channel that reaches an affected plugin author is the refusal itself, which names the missing key at `kernel.use()`; which value that key should carry is authoring intent no ledger entry can decide. -->

.changeset/prompt-template-experimental-marking.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): mark `PromptTemplate.system` / `.user` `[EXPERIMENTAL — not enforced]` (#15954, #16321)
+
+Prose only. `Clause-②: no` — no accept-set change, no new/narrowed authorable
+key, no matrix declaration. Every value that parsed before parses now, and
+every value refused before is refused identically.
+
+Under the #15954 ruling (decision batch #56, option B) the template-typed pair
+is **marked, not retired**. Both `.describe()` strings on
+`ai/PromptTemplateSchema` now carry the repo's existing
+`[EXPERIMENTAL — not enforced]` prefix and state that no runtime renders or
+executes the template today:
+
+```ts
+system: TemplateExpressionInputSchema.optional().describe('[EXPERIMENTAL — not enforced] System prompt — supports {{var}} interpolation. No runtime renders or executes the template today.'),
+user:   TemplateExpressionInputSchema.describe('[EXPERIMENTAL — not enforced] User prompt template — supports {{var}} interpolation. No runtime renders or executes the template today.'),
+```
+
+**Why an author sees this.** `PromptTemplateSchema` has no consumer outside
+`packages/spec`, so the `{{var}}` holes are never interpolated and the declared
+`variables` are never checked against them. The ADR-0058 D7 conformance ledger
+already recorded that verdict (`template-prompt`, `state: 'experimental'`,
+`PARSE ONLY — NO EVALUATOR FOUND`); until now nothing said it at the
+declaration, so the generated reference page advertised a capability the
+runtime does not deliver.
+
+**What does NOT change.** `.user` remains **required** and `.system` remains
+optional — the schema shape is untouched. Optionalising or retiring a required
+key is a parse-breaking change and is deliberately left to its own card. No
+tombstone and no ADR-0087 entry is owed: nothing is renamed, retired or
+re-typed.

.changeset/schedule-flow-dispatch-claim-ledger.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/trigger-schedule": minor
+"@objectstack/service-automation": minor
+"@objectstack/service-job": minor
+---
+
+A scheduled (cron) flow is now delivered once per tick window, and replaying a window that was already delivered is refused instead of silently sent again.
+
+A `time_relative` flow has taken a persisted dispatch claim per `(flow, window, record)` since #10220, so per-record once-only delivery is free for it. A `schedule` flow runs once per tick with no record and had no claim surface at all, so "this batch already went out" fell back to whatever each app remembered for itself. A scheduled digest that was replayed by an operator, or whose process restarted inside its window, delivered twice.
+
+Scheduled flows now claim `(flow, tick-window)` in the same `sys_flow_dispatch` ledger, and settle that claim with what the run turned into:
+
+- **A second fire inside one window does nothing.** The window key is a pure function of the schedule descriptor and the clock — the previous occurrence of the very same cron expression in the very same timezone, computed with the same library the job adapter schedules with — so a restart inside the window computes the same key and hits the same claim.
+- **`IJobService.replay()` refuses a delivered window**, with the ADR-0112 envelope its contract declares: `code: 'RESOURCE_CONFLICT'`, `status: 409`, and a message naming the window and the claim that refused it. The promise rejects — an operator who presses replay and sees nothing happen is exactly the outcome this replaces.
+- **`replay(name, data, { force: true })` sends anyway.** The duplicate is the operator's, taken knowingly.
+- **A window whose claim is absent, failed or unsettled re-runs** on a plain `replay()`, with no force needed. A job that takes no claim at all — every job that is not a scheduled flow — is the absent row and behaves exactly as before.
+- **`succeeded` is absorbing.** A replay that repairs a failed window records `succeeded`, so the next unforced replay is refused. A *forced* replay that throws leaves the window recorded delivered rather than rewriting it to `failed` — otherwise a failed re-send would silently reopen the unforced re-delivery door. An operator whose forced replay failed forces again.
+- **A `once` schedule now has a tick window too** — the single instant it is due, which is one window for the job's whole life. The visible consequence is on replay: an operator who replays a one-shot job *before* its due instant claims that single window, so the real fire then finds the claim and does nothing. Previously both ran.
+
+The error-isolation `catch` that keeps a throwing flow from crashing the ticker is unchanged and still swallows. What it no longer does is leave the run indistinguishable from a delivered one: the throw settles the window's claim as `failed`, so a replay repairs it.
+
+`sys_flow_dispatch` gains two optional columns, `outcome` and `settled_at`. Rows written before this release read as unsettled, which reads as not delivered — the safe direction, since a replay of one re-runs rather than being refused. Only `schedule:` claims are ever settled; a `time_relative` sweep's rows stay `null` by design.
+
+⚠️ **If you manage this table's DDL out of band** — anything other than letting the platform sync `sys_flow_dispatch` from its object definition — add `outcome` (text) and `settled_at` (datetime) yourself before upgrading. Without them every `settle()` throws against the driver. Dispatch dedup still works and no flow fails (the settle is best-effort and logged), but no claim ever records an outcome, so the replay refusal never fires and this release's headline change is silently absent.
+
+Interface changes for hosts that implement the ledger themselves:
+
+- `FlowDispatchStore` gains **optional** `settle()` and `read()`. A store without them still deduplicates; it announces once that the refusal cannot fire.
+- `FlowDispatchStoreEngine` — the narrow ObjectQL slice the bundled store demands — now **requires** `update` alongside `find` and `insert`. A custom engine adapter typed against it must add the method.
+- New exported types: `FlowDispatchClaim` and `FlowDispatchOutcome` from `@objectstack/service-automation`; `ReplayGuard` and `ReplayGuardDecision` from `@objectstack/service-job` (the parameter type of `DbJobAdapter.setReplayGuard`, exported so it can be named); `ScheduleDispatchLedger`, `ScheduleDispatchClaim`, `ScheduleDispatchOutcome`, `ReplayGuard` and `ReplayGuardDecision` from `@objectstack/trigger-schedule`.
+- `croner` moves from a devDependency to a **dependency** of `@objectstack/trigger-schedule`, which now imports it at runtime to compute the cron tick window. It is already a runtime dependency of `@objectstack/service-job` at the same range, so the platform's dependency set does not grow.