Merge remote-tracking branch 'origin/main' into claude/app-crm-decision-routing-bug-aufqaj

Author: claude

.changeset/approval-decision-survives-restart.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/rest": patch
+"@objectstack/runtime": patch
+---
+
+fix(automation,approvals): an approval decision can no longer succeed while its flow stays parked (#4420)
+
+A flow paused at an `approval` node, a deploy, then an approver clicking
+Approve: the request row flipped to `approved`, the UI toasted success — and
+the flow never moved. No next-stage request, no error, the record's mirrored
+status frozen mid-workflow. Approval flows pause for days by design, so a
+restart mid-flight is the normal case: every release could quietly zombify
+every in-flight approval, with the approvers none the wiser.
+
+Durable suspended runs (#1518) had shipped and were not the missing piece. Two
+other things were.
+
+**The wiring could enable a store over a table nobody had created.** Object
+registration and store activation resolve different services in different
+phases — `manifest` at `init()`, `objectql` at `start()` — and the plugin
+declared no ordering. Composed ahead of ObjectQL, `init()` found no `manifest`,
+warned, and continued; `start()` then attached the DB-backed store anyway. Every
+suspend failed with `no such table: sys_automation_run` into a log line nobody
+read, pauses silently stayed in memory, and the next restart lost them all.
+Now: `AutomationServicePlugin` declares `optionalDependencies:
+['com.objectstack.engine.objectql']` (order-if-present, per ADR-0116 — an
+engine-less kernel must still boot); a registration missed at `init()` is
+retried at `start()`, which still lands before ObjectQL's schema sync; the
+store is never attached when registration did not happen, and says so at
+**error** level instead of warning; the table is probed once at boot so a
+broken setup surfaces there rather than one failed write at a time; and a
+failed durable write of a paused run is logged at error — it is data loss in
+waiting, not a warning.
+
+**A reported resume failure read as success.** `AutomationEngine.resume()`
+answers a lost run by *returning* `{ success: false }`, never by throwing.
+`ApprovalService` discarded that return value, and `decide()` counted only a
+thrown error as failure — so a decision against a dead run came back
+`resumed: true`, HTTP 200. Resume failures are now classified
+(`RUN_NOT_FOUND`, `STORE_UNAVAILABLE`, `RESUME_IN_PROGRESS`, joining
+`PERMISSION_DENIED` / `INVALID_SIGNAL`), so a run that is gone for good is
+distinguishable from a store that is merely unreachable, and the raw resume
+route maps them to 404 / 503 / 409.
+
+Approvals acts on them. A new `AutomationEngine.hasSuspendedRun(runId)` — which
+reads the suspension store, unlike `getRun()`, and throws rather than answering
+`false` when the store is unreadable — pre-flights every flow-advancing
+operation (`decide`, `sendBack`, `resubmit`) **before its first write**, so the
+zombie half-state is never created rather than merely reported: the decision
+fails with `RESUME_TARGET_LOST` (HTTP 409) and the request stays actionable. A
+resume that fails after the decision is durable can no longer be undone, but it
+now throws `RESUME_FAILED` (HTTP 500) naming the stranded run instead of
+reporting success. A concurrent duplicate resume stays benign — the engine's
+idempotency guard is doing its job — and reports through the new optional
+`resumeError` field. Recall and revise-window cancellation stay non-fatal by
+design (they abandon the request), but log at error with the reason instead of
+swallowing it. Compositions with no automation engine attached are unaffected.
+
+Existing zombie requests from affected deployments (already `approved`, run
+stranded) are not repaired by this change — `releaseDeadRunRequests` only
+sweeps requests that are still `pending`.

.changeset/datasource-config-driver-contract.md

@@ -13,7 +13,7 @@ package. So `config: { hostname: 'db.internal' }` (the key is `host`) was
 accepted in silence and the datasource connected to `localhost` while the parse,
 the save and the connection probe all reported success.
 
-`DatasourceSchema` now parses `config` — and each `readReplicas` entry — against
+`DatasourceSchema` now parses `config` against
 the contract for the declared driver, and `DatasourceAdminService`
 (create/update/test, the Setup wizard's path) applies the same check. Both read
 one registry in `@objectstack/spec/data`, which also projects each contract to

.changeset/datasource-read-replicas-removed.md

@@ -0,0 +1,49 @@
+---
+'@objectstack/spec': major
+---
+
+`datasource.readReplicas` is removed (#4468, ADR-0049 enforce-or-remove)
+
+It described replica connections nothing ever opened. `ConnectableDatasource`
+and `DatasourceConnectionSpec` carry no replicas field, the driver factory never
+reads the key, and no query path distinguishes a read from a write — the
+platform has no read/write splitting at all, so every statement always went to
+the primary no matter what was declared here.
+
+**Migration.**
+
+| Wrote | Write instead |
+| --- | --- |
+| `readReplicas: [{ host: 'replica-a', … }]` | delete the key |
+| `replicas: [ … ]` (the alias) | delete the key |
+
+There is no target to move to, because there is no read-replica routing to move
+to. If you need replica reads today, front them behind a single endpoint —
+pgpool, ProxySQL, an RDS reader endpoint — and point `config` at that endpoint.
+That is the one read-scaling path that works, and it worked before this key was
+removed too.
+
+Run `os migrate meta --from 16` to strip it from your sources; the
+`datasource-read-replicas-removed` conversion emits one notice per datasource.
+Authoring it now fails the parse with the same prescription.
+
+**Why this one is worth reading about.** #4410 closed the `datasource.config`
+gap and, in passing, extended the new per-driver validation over each
+`readReplicas` entry — reasonably, since replicas carry the same shape. The
+result was a slot that had every marker of a working feature: declared with a
+doc comment, `.strict()`-guarded against typos at the top level, and
+field-by-field validated against the driver's contract underneath. A replica
+block with a misspelt `hostname` was rejected by index, naming the canonical
+key.
+
+None of that is evidence of a consumer, and all of it reads like one. That is
+the specific trap ADR-0049 exists for: rigor is cheap to add to a dead slot and
+expensive to distinguish from life. Two independent surfaces had drawn the
+wrong conclusion — this validation, and objectui's datasource preview, which
+rendered a "2 read replicas" pill confirming the config to the author while
+nothing routed a single read. The preview goes with the key (objectui side,
+same change); `packages/spec/liveness/README.md` has the standing rule it
+violated ("an authoring/preview renderer is NOT a runtime consumer").
+
+Read-replica routing remains unbuilt. It is tracked as a feature request rather
+than left as a schema key that looks like one.

.changeset/unknown-key-strictness-data-step.md

@@ -26,8 +26,12 @@ Deliberately still tolerant:
   runtime shape the engine hands a handler. Strictness there would turn an
   engine-internal enrichment (as `provenance` was in #3712) into a breaking
   change for anyone parsing a context they were given.
-- `datasource.config` and `readReplicas` — per-driver by construction; the
-  driver's own `configSchema` validates them.
+- `datasource.config` — per-driver by construction (a sqlite `filename` and a
+  postgres `host`/`port` share no shape). Left open here and closed one level
+  down instead: #4410 parses it against the contract for the declared driver.
+  This bullet used to say "the driver's own `configSchema` validates them",
+  which was not true when it was written — the field existed and nothing read
+  it.
 
 Errors are self-fixing: connection keys written one level too high (`host`,
 `port`, `filename`, `url`, …) are prescribed into `config`; a top-level

.changeset/workflow-slot-retired.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/spec": major
+"@objectstack/client": major
+"@objectstack/metadata-protocol": minor
+"@objectstack/runtime": minor
+---
+
+refactor(spec,client,metadata-protocol,runtime)!: retire the workflow service slot — declared end to end, implemented nowhere (#4451)
+
+The `workflow` slot was ADR-0078's silently-inert declaration at every layer at
+once: a `CoreServiceName` nothing ever registered or resolved (ADR-0115
+Evidence 5 — "no code in this repository resolves either slot", verified across
+both repositories), an `IWorkflowService` contract with zero implementations, a
+`WorkflowProtocol` whose three methods no code ever provided, a discovery
+`routes.workflow` field no builder could truthfully populate, and a
+`/api/v1/workflow` advertisement for a path no host ever mounted (the
+pre-#3586 `DEFAULT_DISPATCHER_ROUTES` already listed it among routes that
+never existed). The capability it promised is live elsewhere and has been for
+majors: record state machines are enforced by the `state_machine` validation
+rule, approvals are first-class flow nodes on the approvals runtime
+(ADR-0019), and record-triggered automation is lifecycle hooks +
+`record_change` flows (`service-automation`).
+
+FROM → TO:
+
+- `CoreServiceName 'workflow'` / `ServiceRequirementDef.workflow` /
+  `CORE_SERVICE_PROVIDER['workflow']` → removed; there is no slot to fill.
+- `IWorkflowService` (`@objectstack/spec/contracts`) → removed; no
+  implementation ever existed. Register nothing — use the mechanisms above.
+- `WorkflowProtocol` + `GetWorkflowConfigRequest/Response`,
+  `WorkflowState`, `GetWorkflowStateRequest/Response`,
+  `WorkflowTransitionRequest/Response` (`@objectstack/spec/api`) → removed,
+  along with the seven published JSON schemas. Delete the import; nothing
+  ever answered these shapes.
+- Discovery `routes.workflow` / `services.workflow` / `features.workflow`
+  (metadata-protocol + runtime builders) → absent. A reader keying on them
+  only ever saw `unavailable` / `false`; delete the read.
+- `RouterConfig.mounts.workflow` → removed; there was never a surface to
+  mount at it.
+- `RestApiRouteCategory 'workflow'` → removed; categorize automation-adjacent
+  routes as `'automation'`.
+- `@objectstack/client` re-exports of the four workflow types → removed with
+  their source. (The `client.workflow.*` methods were already removed earlier
+  in the v17 cycle — this retires the types they returned.)
+- Also removed: the stray `graphql` entry in `CORE_SERVICE_PROVIDER` and the
+  `graphql: { route: '/graphql' }` discovery entry — `graphql` was never a
+  `CoreServiceName`, and the dispatcher had already dropped `/graphql` as out
+  of the product plan (#2462 follow-on).
+
+The retirement kit: the `workflow-service-slot-retired` semantic migration
+(major 17) carries this prescription into `spec-changes.json`, the generated
+upgrade guide and the `spec_changes` MCP tool. These are TS/API surfaces and a
+discovery response field — never stored in stack metadata — so there is no
+load-path conversion and nothing for `os migrate meta` to rewrite; the
+21 `authorable-surface.json` baseline lines and 7 `json-schema.manifest.json`
+entries for the deleted schemas are dropped deliberately in the same change
+(the plugin-runtime precedent: a prescription nobody can receive is noise —
+nothing parses these shapes any more).

AGENTS.md

@@ -106,8 +106,24 @@ this is mandatory, not a preference (Prime Directive #11), and a PreToolUse hook
 blocks edits made while on the shared `main` branch. Working in the shared `main`
 checkout is *not* a supported fallback: branches get switched and shared files —
 including ones you just wrote — get reset *under you* mid-task (a full session's
-work was silently reverted twice before this rule was enforced). Even inside your
-own worktree, operate defensively:
+work was silently reverted twice before this rule was enforced).
+
+**Claim the issue BEFORE you write any code.** Assign it to yourself
+(`gh issue edit <n> --add-assignee @me`, or the `issue_write` MCP tool with
+`assignees`) as the *first* action of the task — before the worktree, before the
+first read. An unassigned issue reads as an open invitation, and several agents
+work this repo at once: two that both start on it burn the same hours twice and
+then race to land conflicting shapes for the same problem, which is worse than
+either one alone. If it is already assigned to someone else it is taken — pick
+another, or say so and ask; never reassign it to yourself.
+
+The claim is also what makes the *finding* rule (Prime Directive #10) safe to
+follow. Once out-of-scope discoveries become issues, the issue list is a real
+queue other agents read, and a claim is the only thing separating "someone is on
+this" from "nobody has looked yet". File it unassigned when you are merely
+recording a finding; assign it at the moment you actually start.
+
+Even inside your own worktree, operate defensively:
 
 1. **Only touch the files your task needs.** Don't "fix" unrelated diffs,
    reverts, or other agents' in-flight edits, and don't try to manage the whole

CLAUDE.md

@@ -1,8 +1,19 @@
 # CLAUDE.md
 
 **[AGENTS.md](./AGENTS.md) is the source of truth for working in this repo — read it.**
-Its Prime Directives are binding. Do not rely on this file alone; the one rule that must
-never be missed is inlined here because missing it corrupts other agents' work.
+Its Prime Directives are binding. Do not rely on this file alone; the two rules that must
+never be missed are inlined here because missing either one wastes or corrupts other
+agents' work.
+
+## ⛔ Claim the issue before you write any code
+
+Assign the issue to yourself (`gh issue edit <n> --add-assignee @me`, or `issue_write`
+with `assignees`) as the **first action of the task** — before the worktree, before the
+first read. Several agents work this repo at once and an unassigned issue reads as an
+open invitation: two that both start on it burn the same hours twice, then race to land
+conflicting shapes for one problem. Already assigned to someone else? It is taken — pick
+another or ask; never reassign it to yourself. File findings unassigned when you are only
+recording them; assign at the moment you start.
 
 ## ⛔ Worktree-first — before your FIRST file edit (AGENTS.md Prime Directive #11)
 

content/docs/api/plugin-endpoints.mdx

@@ -26,19 +26,21 @@ Authenticate with email and password (better-auth's email sign-in route, mounted
 
 The following endpoints become available when the corresponding plugin is installed and registered with the kernel. Use the discovery `services` map to check availability.
 
-### Workflow (`/workflow`) — Plugin Required
+### Workflow (`/workflow`) — removed in v17
 
 <Callout type="warn">
-Not yet mounted. These routes are declared in the API protocol but the core dispatcher registers no `/workflow` handler and no bundled plugin provides a `workflow` service (only an in-memory dev stub), so they return **404** today. `discovery.services.workflow` reports `unavailable` in a standard install.
+There is no workflow endpoint, and there is no `workflow` service slot. The
+three routes documented here were declared in the API protocol and served by
+nothing — no dispatcher handler, no plugin — so they 404'd for the whole life
+of the declaration. The slot, the `WorkflowProtocol` methods behind it and the
+discovery fields that reported it were all retired in v17 ([#4451](https://github.com/objectstack-ai/objectstack/issues/4451)).
+Use the live mechanisms instead: an object validation rule of type
+`state_machine` for lifecycle transitions, an `approval` flow node for human
+approval pauses (ADR-0019), and lifecycle hooks / `record_change` flows for
+record-triggered automation.
 </Callout>
 
-| Method | Endpoint | Description |
-|:-------|:---------|:------------|
-| GET | `/workflow/:object/config` | Get workflow configuration |
-| GET | `/workflow/:object/:recordId/state` | Get record's workflow state |
-| POST | `/workflow/:object/:recordId/transition` | Execute state transition |
-
-Approve/reject are **not** workflow routes (ADR-0019): approval is a flow node, and decisions are recorded on the approvals runtime via `POST /approvals/requests/:id/approve` and `POST /approvals/requests/:id/reject`.
+Approve/reject were never workflow routes (ADR-0019): approval is a flow node, and decisions are recorded on the approvals runtime via `POST /approvals/requests/:id/approve` and `POST /approvals/requests/:id/reject`.
 
 ### Automation (`/automation`) — Plugin Required