Merge origin/main into claude/issue-21411-approval-actor-person (brings #21458's ApprovalActionRow.acted_as)

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

Author: claude

.changeset/20751-services-strings-stage4-state-the-decision.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/service-automation': patch
+'@objectstack/plugin-audit': patch
+---
+
+Automation refusals, prescriptions, log lines and run-object field help, and the activity type help, no longer cite tracker numbers; each one states the decision behind it in words
+
+Clause-②: no
+
+Some strings these two packages show to flow authors, operators and administrators pointed at an issue-tracker number for the reason behind them. The number goes; where the sentence did not already say what was decided, it now does.
+
+- `@objectstack/service-automation`: the refusal for a `fieldValues` write map says a runtime alias for it was rejected by design, so the node keeps one strict `fields` key; the refusal for a screen field's `visibleIf` says a predicate under any other key is never read, so the field always shows, and a `required` field meant to stay hidden then blocks the screen from ever being submitted; the undeclared-config-key refusal says the built-in node types were reconciled so that every key their executors read is declared; the unknown-function error in a flow value expression says such a name is refused rather than evaluated to null, which would write the field as undefined; the inert-connector warning says entries without a `provider` are catalog descriptors, while an entry that names a `provider` is a connector instance that provider's installed executor materializes; the `sys_automation_run` field help says the paused node's type decides who may continue a run (an approval pause only through its owning service), that rows written before run history recorded its trigger were not backfilled, and that a finished run's bounded step log keeps its per-node detail across a restart; three bridge debug lines say what each bridge provides. The bulk-intent guidance, the degraded-connector dispatch error and retry lines, the user-less `runAs` warning and refusal, the unclaimed-branch warning, the script-function and node-config refusals and the `sys_flow_dispatch` description drop their citations.
+- `@objectstack/plugin-audit`: the `sys_activity` `type` help, whose English text all four shipped locale bundles carry, says the vocabulary is open by decision, not a gap awaiting enforcement.
+
+Text only: no status, error code, field, route or control flow moves. A client or log filter that matches the old text (for example a tracker-number suffix) needs the new spelling.

.changeset/21320-agent-lifecycle-retired.md

@@ -0,0 +1,77 @@
+---
+'@objectstack/spec': minor
+'@objectstack/platform-objects': patch
+---
+
+feat(spec)!: retire `agent.lifecycle`, the agent conversation state machine, and with it the XState `StateMachineSchema` family — a conversation phase is a skill with `triggerConditions`, orchestration is Flow, record transitions are the `state_machine` validation rule (#21320)
+
+**BREAKING** — `agent.lifecycle` was parsed and never read. No runtime, in this
+repository or in the cloud AI runtime that executes agents, moved an agent through a
+declared state or refused an undeclared transition, so an authored machine changed
+nothing an agent did (ADR-0049 enforce-or-remove). Enforcing it would have meant a
+statechart interpreter beside Flow, the two-engine shape ADR-0020 rejected. Authoring
+now refuses the key by name, with a prescription, and TypeScript rejects it.
+
+Its value schema had no other authorable door: ADR-0020 had already retired the XState
+shape as a record-lifecycle declaration and kept the file only for this key. So the
+family leaves the package with it.
+
+### FROM → TO
+
+| before | what to write instead |
+| --- | --- |
+| `agent.lifecycle` — any value | delete the key. |
+| a conversation phase in the machine (its own instructions and tools) | a skill with its own `instructions` and `tools`, selected by its `triggerConditions`, listed in the agent's `skills`. |
+| a multi-step process in the machine | a Flow. |
+| a record's status transitions in the machine | a `state_machine` validation rule in the object's `validations`: `{ type: 'state_machine', field, transitions: { from: [to, …] } }`. |
+| `StateMachineSchema`, `StateNodeSchema`, `TransitionSchema`, `ActionRefSchema`, `GuardRefSchema` and the types `StateMachineConfig`, `StateNode`, `StateNodeConfig`, `Transition`, `ActionRef`, `GuardRef` from `@objectstack/spec/automation` | no replacement: declare the shape your code needs itself, or drop it. For record transitions, `StateMachineValidationSchema` in `@objectstack/spec/data` is the enforced shape. |
+| `StateNodeConfig` from `@objectstack/spec` or `@objectstack/spec/ai` | removed with the family; nothing in those entries mentions it any more. |
+
+**The one-line fix: delete `lifecycle`; put phase-scoped instructions and tools in
+skills with `triggerConditions`, and orchestration in Flow.** `os migrate meta --from 17`
+lists the mechanical edits for existing sources (the `lifecycle` deletion). Where each
+deleted machine's intent goes is the author's judgement.
+
+The refusal is a parse error at `lifecycle` naming the key and the fix, and the key
+fails `tsc` (its input type is `never`).
+
+### The retirement kit
+
+- **Tombstone.** `lifecycle` is a `retiredKey()` on `AgentSchema` carrying the
+  prescription; the agent metadata form no longer offers it.
+- **D2 conversion `agent-lifecycle-removed`** (step 18, retired from the load path):
+  it deletes `lifecycle` from every agent, whatever it holds. The delete is lossless,
+  because no value of it ever changed what an agent did. Stored `sys_metadata` agent
+  rows and built artifacts replay it; one notice per agent. An object's ADR-0057
+  `lifecycle` block shares the name and is not touched.
+- **D3 entry `agent-lifecycle-retired`** carries the judgement the conversion cannot
+  make: which of the three destinations each deleted machine meant.
+- **`RETIRED_KEYS_BY_MAJOR[18]`** registers `ai/Agent:lifecycle`, and
+  **`RETIRED_DEFS_BY_MAJOR[18]`** registers the five published defs
+  `automation/StateMachine`, `automation/StateNode`, `automation/Transition`,
+  `automation/ActionRef` and `automation/GuardRef`. Their reference page
+  (`references/automation/state-machine`) is gone.
+- **No deprecation window**, per the project's startup-stage posture.
+
+### The liveness ledger
+
+The `agent.lifecycle` row moves `experimental` → `dead` with a REMOVED note
+(`verifiedAt` 2026-10-02); the tombstone keeps it in the walked shape. No `agent` row is
+`experimental` any more. `os validate` and every other parsing door refuse the key at
+parse, before any advisory runs. `os lint` reads the unparsed stack, so it now grades the
+key `liveness-dead-property` where it used to say `liveness-experimental-property`.
+
+### `@objectstack/platform-objects`
+
+The agent metadata-form catalogs drop the `lifecycle` row's label and help text in all
+four locales.
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec` is
+published: tenant-authored agents, and code outside this repository importing the
+family's exports, were not measured. This repository authors no `agent.lifecycle`
+outside `packages/spec` and imports none of the family outside it; the pinned objectui
+checkout imports none of the family and reads no `agent.lifecycle`.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered agent-lifecycle-removed, agent-lifecycle-retired -->

.changeset/21326-secret-rewrap.md

@@ -0,0 +1,47 @@
+---
+'@objectstack/cli': minor
+'@objectstack/service-settings': minor
+---
+
+feat(cli): `os secret rewrap` re-wraps version-1 `sys_secret` ciphertext under the current AAD derivation, each row under its holder's producer scope (ADR-0128 §4.2, #21326 stage 2)
+
+Clause-②: yes (widening)
+
+A ciphertext sealed before ADR-0128 D1–D3 carries the older binding over
+`(namespace, key)` alone, and still opens in this release. `os secret rewrap` moves
+the stored values to the current binding through `rotateKey`, the seam ADR-0128 §4
+names. It is an operator command: a dry run by default, `--apply` to write, and
+nothing on any boot or upgrade path invokes it. It has no HTTP surface.
+
+- **The scope comes from the holder.** `sys_secret` records no producer, and a
+  version-1 ciphertext binds no scope, so each row is re-sealed under the scope of
+  the producer whose holder references it: `settings` for a `sys_setting.value_enc`
+  handle, `object_secret_field` for a `secret:` ref on a business row,
+  `datasource_credential` for a `sys_secret:` `credentialsRef`. The holders come from
+  the same cross-producer reference union `os secret orphans` reads. A row nothing
+  references, a row whose holders belong to different producers, and every row while
+  a holder family could not be read are left as they are and counted, never re-sealed
+  under a guessed scope. `--apply` refuses an incomplete union and names the family.
+- **Resumable.** A row already sealed under the current derivation is skipped as
+  done, so a stopped run finishes the rest when re-run and a finished run writes
+  nothing.
+- **Safe against a live deployment.** Each row is written by one conditional update,
+  keyed on its id and the ciphertext the run read. A row a producer changed in
+  between is not overwritten, and a re-run picks it up. A driver with no
+  `updateMany` is refused before any row is opened.
+- **Fails closed.** A row that does not open, or whose re-seal does not open to the
+  same plaintext under the same scope, is not written. The run finishes the rest and
+  exits 1. The check happens before the write.
+- **Output is classes and counts only.** It never prints a plaintext, a ciphertext
+  or a row id.
+
+The command resolves its data key from `OS_SECRET_KEY`, `OS_DEV_CRYPTO_KEY` or the
+persisted key file, in the strict posture: it never mints a key, and it hands the
+settings service it boots the same provider so that service does not mint one
+either. With no key it refuses before opening any row.
+
+`@objectstack/service-settings` publishes `ciphertextDerivationStatus` (and its
+`CiphertextDerivationStatus` type). It is `LocalCryptoProvider`'s own reading of
+which derivation sealed a stored ciphertext, read off its marker without opening it:
+`current`, `superseded` or `unknown`. The re-wrap classifies rows with it rather than
+restating the marker grammar.

.changeset/21437-analytics-measure-names-no-field.md

@@ -0,0 +1,27 @@
+---
+'@objectstack/service-analytics': minor
+---
+
+fix(service-analytics)!: a caller-named analytics measure whose inferred source names no field (`_sum`, `*`, `*_sum`, an empty spelling) is refused with `INVALID_FIELD` / 400 at the analytics door, naming the spelling sent, on both strategies, before any statement is built (#21437)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a refusal at the analytics door of a caller-named measure spelling whose inferred source names no field. No authorable key, spelling, export type or stored shape moves: AnalyticsQuerySchema still parses every measures list it parsed (the refusal is a runtime rule on the request, not a schema change), CubeSchema and DatasetSchema are untouched, a member a cube declares is never minted and is served as before, the package index exports the same names with the same types, and no stored row is read or rewritten. A refused spelling had no answer to preserve: both strategies answered 500 for it, and which column a caller meant by an empty prefix is not something a ledger entry can rewrite. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id covers a caller-named measure spelling, and this diff adds none (not registered / already-registered); and the change is runtime behaviour, not a declaration (not runtime-interface-only / type-surface-only). -->
+
+**BREAKING**: this narrows what `POST /api/v1/analytics/query` and its dry run `POST /api/v1/analytics/sql` accept in `measures`, on both strategies and every driver. It ships as `minor` under the launch-window convention for accept-set narrowings. No export, published type or error code changes.
+
+**The rule.** A `measures` entry the cube does not declare is inferred: the bare `count` counts rows (`COUNT(*)`), and any other spelling aggregates one of the object's own fields, named before an aggregation suffix (`_sum`, `_avg`, `_average`, `_min`, `_max`, `_count_distinct`) or, with no suffix, by the whole spelling. The bare `count` is now the only spelling that reads the row wildcard `'*'`. A spelling whose source is empty or is `'*'` names no field, and it is refused with `400 INVALID_FIELD` before anything is executed. The error names the spelling as it was sent (`member`, with `param: 'measures'` and `cube`); a `<cube>.` qualifier is kept in the name.
+
+**Before**, measured through `POST /api/v1/analytics/query` on SQLite, on the native-SQL and the ObjectQL strategy, on an ad-hoc cube and on an authored cube that does not declare the member:
+
+- `_sum`, `_avg`, `_average`, `_min`, `_max`, their `<cube>.`-qualified forms, `*`, `*_sum`, `*_avg` and the empty spelling `''` answered `500 DATABASE_ERROR`, after a statement reached the database (`SUM(*)`, `AVG(*)`, `SUM()`).
+- `_count_distinct` and `*_count_distinct` answered `500 DATABASE_ERROR` on the native-SQL strategy (`COUNT(DISTINCT *)`). On the ObjectQL strategy the engine answered `400 INVALID_QUERY` after the aggregate was called.
+- The qualifier alone (`<cube>.`) answered `403 PERMISSION_DENIED` from the member-shape gate. It now answers the same `400 INVALID_FIELD`, because it names no field either.
+
+**Now** each of those answers `400 INVALID_FIELD`, and no statement and no engine aggregate runs. `POST /api/v1/analytics/sql` refuses the same spellings instead of returning a statement that cannot run.
+
+**What to write instead.** Ask for `count` to count rows, or put the field's name before the suffix: the sum of `amount` is `amount_sum`.
+
+**Who is affected.** A caller that sent a measure spelling with nothing before the suffix, or the row wildcard itself. Every such request was already a 500. No example app, shipped dashboard, report, dataset, cube, doc or skill in this repository sends one. The console's analytics adapter composes a measure as the value field, an underscore and the aggregate function, so a widget whose value field is empty posts `_sum`. At the pinned `.objectui-sha` that adapter reads a 500 as an unknown failure and answers with its own client-side aggregation; it reads the 400 as a rejected request and surfaces it as an error.
+
+**Unchanged.** The bare `count`; a field-prefixed spelling such as `amount_sum`; the no-suffix spelling of a field (`amount`); a measure a cube declares, including one declared under a key such as `_sum`, which is the cube's own vocabulary and is never inferred; and the authored-position twin of this rule, the `@objectstack/spec` parse refusal of `'*'` outside a `count` on a cube or dataset measure (#21409).

.changeset/21458-spec-approval-action-acted-as.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `ApprovalActionRow` declares `acted_as`, the pending-approver slot an approval action was taken as, beside the person in `actor_id`
+
+Clause-②: yes
+
+**What it declares.** One optional string member on `ApprovalActionRow` in `@objectstack/spec/contracts`, the row type of an approval request's action log (`IApprovalService.listActions`, served at `GET /api/v1/approvals/requests/:id/actions` and typed by the client SDK):
+
+- `acted_as?: string` is the slot the action was admitted under, in the slot's stored spelling as it stood in the request's `pending_approvers`: a `position:<name>` address (or `role:<name>`, the deprecated pre-rename spelling), an email, or a user id.
+- It is never a person. The person who acted is `actor_id`, which under ADR-0118 D1 holds a `sys_user` id or nothing. A slot addressed by a user id carries that id in `acted_as` as the slot's address, which makes no claim about who acted.
+- Absent means the action was not admitted through a slot (a submitter's own action, a system action, or an admin override, which `via_override` marks), or the row was written before the slot was recorded. So absent alone never proves that no slot was involved.
+
+**What moves for consumers.** Nothing in this package writes the member, and every existing export and member is unchanged: a row without `acted_as` conforms exactly as before. The approvals service is its producer, and that package's own changeset states when `listActions` starts returning it. Until then every row omits it, which is the member's declared absent case. A client that renders the action log can show `acted_as` beside the actor's name as the capacity the actor acted in.

content/docs/automation/workflows.mdx

@@ -8,7 +8,7 @@ ObjectStack no longer has a standalone Salesforce-style Workflow Rule authoring
 type. Use:
 
 - **Flow** for event-triggered or scheduled automation.
-- **State machine metadata** for strict lifecycle transitions.
+- **A `state_machine` validation rule** for strict lifecycle transitions.
 - **Approval nodes** inside Flow for human approval pauses.
 
 This page keeps the historical route but documents the current split.
@@ -60,42 +60,51 @@ registration/runtime.
 
 ## State machines for lifecycle constraints
 
-Use `StateMachineSchema` when the core requirement is "this object can only move
-through these states by these events."
+Use a `state_machine` validation rule when the core requirement is "this record
+can only move through these states." It is one of the object's `validations`: a
+flat table of each state's allowed next states, enforced by the write path (see
+[State Machine](/docs/protocol/objectql/state-machine)).
 
 {/* os:check */}
 ```typescript
-import type { StateMachineConfig } from '@objectstack/spec/automation';
-
-export const caseLifecycle: StateMachineConfig = {
-  id: 'case_lifecycle',
-  initial: 'new',
-  states: {
-    new: {
-      on: {
-        ASSIGN: { target: 'assigned' },
-      },
-    },
-    assigned: {
-      on: {
-        RESOLVE: { target: 'resolved', cond: 'has_resolution' },
-        ESCALATE: { target: 'escalated' },
-      },
-    },
-    escalated: {
-      on: {
-        RESOLVE: { target: 'resolved', cond: 'has_resolution' },
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+export const SupportCase = ObjectSchema.create({
+  name: 'support_case',
+  label: 'Support Case',
+  sharingModel: 'private',
+  fields: {
+    status: Field.select({
+      label: 'Status',
+      required: true,
+      options: [
+        { label: 'New', value: 'new' },
+        { label: 'Assigned', value: 'assigned' },
+        { label: 'Escalated', value: 'escalated' },
+        { label: 'Resolved', value: 'resolved' },
+      ],
+    }),
+  },
+  validations: [
+    {
+      type: 'state_machine',
+      name: 'case_status_flow',
+      field: 'status',
+      events: ['update'],
+      message: 'Invalid case status transition.',
+      transitions: {
+        new: ['assigned'],
+        assigned: ['resolved', 'escalated'],
+        escalated: ['resolved'],
+        resolved: [],
       },
     },
-    resolved: {
-      type: 'final',
-    },
-  },
-};
+  ],
+});
 ```
 
-State machines describe valid transitions and guards. Use Flow nodes for side
-effects around those transitions when you need notifications, record updates, or
+The rule declares which transitions are legal. Use Flow nodes for side effects
+around those transitions when you need notifications, record updates, or
 external calls.
 
 ---