Merge origin/main into claude/issue-20783-groupby-json-refused

Claude-Session: https://claude.ai/code/session_01DEvba2nBuD4tWzfq8r8NFY
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/20234-liveness-ledger-provenance-anchors-2.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/spec': patch
+---
+
+Notes in seven more liveness ledgers cite the commit that decided them, or say the decision in words, instead of a tracker number that no longer resolves
+
+Clause-②: no
+
+Notes in the `datasource`, `api`, `query`, `object`, `email_template`, `mapping` and
+`webhook` ledgers named GitHub issues that no longer exist, so a reader could not tell why
+a row carries its verdict. Each such note now either names the commit that made the
+decision or, where the number alone carried the meaning, says what was decided. The
+`manifest` ledger's `permissions` note also names the commit that recorded its structured
+arm's zero apart. The `liveness/` ledgers ship in this package's tarball, which is why
+this is a release note at all. Note text only: no row's status, evidence, proof or date
+changes, and no schema, export or runtime behaviour changes.

.changeset/20596-trigger-record-change-provenance-anchors.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/trigger-record-change': patch
+---
+
+Provenance comments in `trigger-record-change` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the commit in this repository's history that
+decided the matter, and say in their own words what was decided. Comments
+only: no type, schema, export, log or refusal text, or runtime behaviour changes.

.changeset/20676-mount-flow-clone.md

@@ -0,0 +1,20 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): `POST /api/v1/automation/:name/clone` is served over HTTP
+
+Clause-②: no
+
+Cloning a flow under a new machine name (ADR-0126 §7.1) is how an admin customizes a packaged
+flow whose base is locked. The runtime implemented the clone, but the dispatcher never mounted
+its route, so every clone answered `404 ENDPOINT_NOT_FOUND` before the request reached it: from
+the API, and from the Clone dialog on Setup's packaged-automation page, for every caller and
+every body.
+
+The route is now mounted beside `POST /automation/:name/toggle`, at `/api/v1/automation/:name/clone`
+and, when environment scoping is enabled, at `/api/v1/environments/:environmentId/automation/:name/clone`.
+It answers what the clone implementation already answered: `200 { flow, notice }` for a legal
+clone, `400` for a missing or illegal `name` or `label`, `404` for an unknown source flow,
+`409 RESOURCE_CONFLICT` for a name already in use, `401` for an anonymous caller and `403` for a
+caller without `manage_metadata`. No request or response shape changed.

.changeset/20678-subflow-disable-sequence.md

@@ -18,7 +18,7 @@ Clause-②: no (narrowing)
 **Not refused:**
 
 - Enabling a flow that is already enabled. Nothing is re-armed.
-- A flow the customer authored, or a subflow the customer authored.
+- A subflow the customer authored. A flow the customer authored is not this switch's to enable at all: the activation switch switches packaged flows only, and it refuses a customer-authored flow for that reason before this guard is asked (see the entry "the toggle door refuses a flow no package ships, naming its status switch").
 - A subflow in a cycle of switched-off flows with the flow being enabled, including a flow that calls itself. Each flow in such a cycle would refuse the others, so no order could complete. A subflow in such a cycle whose definition's `status` also disables it is still named, with its publish remedy: no enable order changes a status.
 
 The disable direction of the same guard is described in its own entry, "disabling a packaged subflow completes once its packaged callers are switched off and hold no parked run".

.changeset/20726-clone-notice-status-switch.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): the clone door's notice names the clone's own off-switch, its status (#20726)
+
+`POST /api/v1/automation/:name/clone` answers a `notice` saying the clone is armed. It told the admin to switch the clone off through `POST /api/v1/automation/NAME/toggle`. A clone carries no package envelope, so it is a flow authored in the deployment, and that switch refuses it: the switch turns packaged flows on and off only. The notice now names the clone's own switch: send its complete definition with `status: 'obsolete'` to `PUT /api/v1/automation/NAME`. It also says that the toggle switches packaged flows only and refuses the clone, whatever flow the clone was copied from. The response shape is unchanged; only the notice text moves.

.changeset/20726-toggle-door-docs-client.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/client': patch
+---
+
+docs(client): `automation.toggle` says it switches packaged flows only, and names a customer flow's switch (#20726)
+
+`client.automation.toggle` had no docblock of its own: its one line had drifted above an unrelated member. It now says that it switches packaged flows only, and that a flow authored in the deployment is refused with 409 `RESOURCE_CONFLICT`. Such a flow's switch is its `status`, sent with the complete definition through `automation.update`. This is prose only: the method's signature and behaviour are unchanged.

.changeset/20726-toggle-door-docs-spec.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the Automation API docblock says the toggle door switches packaged flows only, and names a customer flow's switch (#20726)
+
+The module docblock of `api/automation-api.zod.ts` listed `POST /api/v1/automation/:name/toggle` as "Enable/disable flow". That file ships as source, and its docblock is also the source of the Automation API reference page. The line now reads "Enable/disable a packaged flow". A new paragraph says what a flow authored in the deployment uses instead: its `status`, published with the complete definition through `PUT /api/v1/automation/:name`. The toggle door refuses such a flow with 409 `RESOURCE_CONFLICT`. The `IAutomationService.toggleFlow` docblock, which read "Enable or disable a flow", says the same. This is prose only: no schema, type or export changes.

.changeset/20726-toggle-door-packaged-only.md

@@ -0,0 +1,23 @@
+---
+'@objectstack/service-automation': minor
+---
+
+fix(service-automation)!: the toggle door refuses a flow no package ships, naming its status switch (#20726)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata changes shape and nothing an author wrote is renamed or removed, so `objectstack migrate meta` has nothing to rewrite. What moves is which flows the activation switch accepts: a flow without package provenance is refused, and its own `status`, which it always had, is its switch. -->
+
+**BREAKING**: shipped as `minor` under the launch-window convention. `toggleFlow(name, enabled)` on the automation service, and so `POST /api/v1/automation/:name/toggle` and `client.automation.toggle`, now switches packaged flows only: a flow a code package ships.
+
+**What was wrong.** The switch records an installation's choice in the packaged-metadata activation ledger (`sys_metadata_activation`, ADR-0126 §7.2), whose rows name the package that ships the flow. For a flow authored in the deployment it wrote a row anyway:
+
+- A flow with no package id, such as one created through `POST /api/v1/automation` or the clone door, was refused with 400 `VALIDATION_FAILED` "Package is required", naming a field the caller never sent.
+- A flow carrying the runtime-row package sentinel or an app package id was accepted, and a ledger row was written for it. That gave it a second off-switch beside its own `status`.
+- With no ledger attached, the flip was accepted in process only.
+
+**What changed.** A flow without package provenance is now refused with `RESOURCE_CONFLICT` / `409`, in both directions and with or without a ledger. The refusal comes before anything is written or changed. The message says the switch turns packaged flows on and off. It names the flow's own switch: its definition's `status`, published with the complete definition through `PUT /api/v1/automation/:name`. `obsolete` switches it off and `active` arms it. The switch never rewrites a definition itself. Packaged flows toggle exactly as before.
+
+**Migration.** To switch a customer-authored flow off, stop sending `POST /api/v1/automation/NAME/toggle` with `{"enabled": false}`. Instead, send `PUT /api/v1/automation/NAME` with the flow's complete definition and `status: 'obsolete'`, and `status: 'active'` to arm it again. In the SDK, `client.automation.toggle(name, false)` becomes `client.automation.update(name, { ...definition, status: 'obsolete' })`.
+
+**A customer flow that a ledger row already holds off.** If this switch turned a customer flow off before this release, its ledger row still holds the flow off after the upgrade, and no `status` clears that row. The refusal says so and names the step that completes: clone the flow under a new name through `POST /api/v1/automation/NAME/clone`, which arms the copy, then remove the old one.

content/docs/references/api/automation-api.mdx

@@ -25,14 +25,22 @@ the former `GET /api/v1/automation` list route, its request/response schemas
 and `client.automation.list` are retired (ADR-0087 semantic entry
 `automation-flow-list-route-retired`).
 
+The toggle door switches PACKAGED flows only: a flow a code package ships.
+It records the installation's choice in the packaged-metadata activation
+ledger (ADR-0126 §7.2). A flow authored in the deployment is not switched
+there. Its switch is its own `status`: `'obsolete'` disarms it and
+`'active'` arms it, published with the complete definition through
+`PUT /api/v1/automation/:name`. The toggle door refuses such a flow with
+409 `RESOURCE_CONFLICT`, names that switch, and changes nothing.
+
 **Endpoints**
 ```
 GET    /api/v1/automation/:name                — Get flow
 POST   /api/v1/automation                      — Create flow
 PUT    /api/v1/automation/:name                — Update flow
 DELETE /api/v1/automation/:name                — Delete flow
 POST   /api/v1/automation/:name/trigger        — Trigger flow execution
-POST   /api/v1/automation/:name/toggle         — Enable/disable flow
+POST   /api/v1/automation/:name/toggle         — Enable/disable a packaged flow
 GET    /api/v1/automation/:name/runs           — List execution runs
 GET    /api/v1/automation/:name/runs/:runId    — Get single execution run
 ```

packages/client/src/index.ts

@@ -5483,9 +5483,6 @@ export class ObjectStackClient {
           return this.unwrapResponse(res);
       },
 
-      /**
-       * Enable or disable a flow
-       */
       /* [#3563 PR-5] The three descriptor/status routes that had no SDK
        * expression — they back the Studio designer's pickers and badges. */
 
@@ -5525,6 +5522,17 @@ export class ObjectStackClient {
           return this.unwrapResponse(res);
       },
 
+      /**
+       * Enable or disable a PACKAGED flow — one a code package ships.
+       *
+       * [#20726, ADR-0126 §7.2] `POST /automation/:name/toggle` records the
+       * installation's choice in the packaged-metadata activation ledger, so
+       * it switches packaged flows only. A flow authored in the deployment is
+       * refused with 409 `RESOURCE_CONFLICT` and nothing changes. Its switch
+       * is its own `status`: send its complete definition through
+       * `automation.update(name, definition)` (`PUT /automation/:name`) with
+       * `status: 'obsolete'` to disarm it, or `status: 'active'` to arm it.
+       */
       toggle: async (name: string, enabled: boolean): Promise<{ name: string; enabled: boolean }> => {
           const route = this.getRoute('automation');
           const res = await this.fetch(`${this.baseUrl}${route}/${name}/toggle`, {