Merge remote-tracking branch 'origin/main' into claude/issue-9567-flow-conversion-conflict-ledger

Author: claude

.changeset/actions-flow-dispatch-status-table.md

@@ -0,0 +1,22 @@
+---
+'@objectstack/runtime': minor
+---
+
+`POST /api/v1/actions/:object/:action` answers the flow-dispatch status table instead of one blanket `400 FLOW_FAILED` (#9446).
+
+**What a caller sees differently.** A `type: 'flow'` action whose dispatch is REFUSED no longer reports a failed run. Three answers changed:
+
+| the flow behind the action | before | now |
+|---|---|---|
+| is not registered | `400` `FLOW_FAILED` | `404` `RESOURCE_NOT_FOUND` |
+| is switched off | `400` `FLOW_FAILED` | `409` `FLOW_DISABLED` |
+| has no `start` node | `400` `FLOW_FAILED` | `422` `FLOW_NO_START_NODE` |
+| ran and was rejected | `400` `FLOW_FAILED` | `400` `FLOW_FAILED` (unchanged) |
+
+These are the same four rows `POST /api/v1/automation/:name/trigger` has answered since #9378 + #9415, and they now come from one shared definition both doors read, so the two cannot drift apart again.
+
+**Behaviourally breaking for a caller that branches on the status or the code.** Every one of these was a `400` before, so a caller treating `400` as "the run failed" was being told something false in three of the four cases: nothing had dispatched and no node had executed. A client that lumps all four together keeps working — they are all still refusals, all still `success: false` with no inner envelope — but one that reports "the flow failed" on a `400` should now distinguish. **Retry semantics differ per row**, which is the practical reason to: `409 FLOW_DISABLED` is reversible operational state (enable the flow and the identical request succeeds), while `404` and `422 FLOW_NO_START_NODE` are authoring defects that no retry fixes. `400 FLOW_FAILED` remains terminal, exactly as the console already treats it.
+
+**Unchanged on purpose.** A successful run still answers `200` with the single `data` wrap (#3962). The `400 FLOW_FAILED` message keeps its existing wording (`Flow '<target>' failed: …`), which names the flow the action dispatches — the trigger route's URL carries that name and this route's does not. A `success: false` result the automation engine did not classify still refuses with `400 FLOW_FAILED` rather than falling back to `200 {success:true,data:{success:false}}` — the double envelope #3962 removed from this route.
+
+**Not in scope.** Declared endpoints (`type: 'flow'` endpoints, `endpoint-executor.ts`) still answer `200` for every outcome. That door converges in its own change (#9462), where the envelope flip is a breaking change for consumers of the current double envelope and is sequenced against them.

.changeset/boot-widening-bounded-lock-wait.md

@@ -0,0 +1,41 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+fix(driver-sql): boot schema-sync's MySQL widening ALTER bounds its metadata-lock wait too — a blocked boot warns and carries on instead of hanging for a year (#9542)
+
+#9354 bounded `lock_wait_timeout` to 120s on the widening `ALTER TABLE … MODIFY
+COLUMN` and made a blocked `os migrate apply` refuse loudly — but only while
+`flushDeferredSchemaDdl` was running. The same two widenings
+(`migrateMysqlDatetimeColumns` / `migrateMysqlTimeColumns`, #3942 / #3994) are
+reached from **boot schema-sync** through the same `initObjects` lines, and on
+that path the `runWideningAlters` seam returned early: the ALTER ran through the
+pool inheriting MySQL's own default `lock_wait_timeout` of **31,536,000 seconds
+— one year**.
+
+So a single other session holding a metadata lock on the table parked boot at
+schema-sync for that long, printing nothing — indistinguishable from a crash.
+The widening's own `logger.warn` could not help, because it lives in a `catch`
+and an ALTER that never returns is never caught.
+
+The bound is now armed **unconditionally** in that seam. What stays gated on the
+flush is the **refusal**, and only it: boot still swallows. Correctness never
+depends on the widening having run and a migration must never take boot down, so
+throwing there would trade a silent hang for a failed boot — a different answer,
+not the same one.
+
+**What changes for a deployment.** On MySQL, a boot whose widening ALTER is
+blocked on a metadata lock now waits at most 120s, then logs
+`[sql-driver] could not widen MySQL datetime columns on …` (or its `TIME(3)`
+twin) naming the table, with the server's own `Lock wait timeout exceeded` as
+the `error` field — and boot carries on. The widening is idempotent, so the
+first boot after the blocker is gone completes it. Nothing changes on any other
+dialect, on an ALTER that is not blocked, or for `os migrate apply`, which keeps
+#9354's `DATABASE_ERROR` / 500 refusal.
+
+120s is #9354's number, kept for boot deliberately rather than lengthened: the
+reasoning behind it is about how long a legitimate metadata-lock holder can
+plausibly hold the lock, which is a property of the lock and not of who is
+waiting on it. Boot's difference from the flush is what happens when the bound
+fires, never how long it waits. No retry logic and no configurability — the
+2026-08-17 ruling's minimality, unchanged.

.changeset/dispatcher-error-vocabulary-lowercase-and-helper-shapes.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/runtime": patch
+---
+
+fix(tooling): `check:dispatcher-error-vocabulary` reports lowercase codes and the two stamp positions it could not see — a live 403 had been invisible to both vocabulary gates (#9460)
+
+The gate's published bound said it scanned "only SCREAMING_SNAKE literals", and
+handed lowercase to `check:error-code-casing`. Half of that delegation was real
+and half was a hole, and the hole is where `plugin-security`'s live 403
+`owd_widening_forbidden` sat through two ADR-0112 sweeps: both gates read the
+file, both reported nothing, each leaving it to the other.
+
+**The card's premise was that the scan's patterns are case-sensitive. They are
+not** — the literal shapes already matched `[A-Za-z]`. Two explicit filters
+dropped the value after the match, and the producer was invisible for a
+different reason entirely, so the prescribed one-line widening would not have
+found it. Measured before changing anything: reporting every lowercase stamp
+took the scan from 12 sites to 94, and **all 82 new findings were D6/D6b/D6c
+neighbours or Zod's own issue codes** — it would have called
+`ctx.addIssue({ code: 'custom' })` an unregistered ObjectStack error code.
+
+So lowercase is now reported **except** in the two positions where
+`check:error-code-casing` reads the identical characters (`code: 'x'`,
+`.code = 'x'`). There the delegation is genuine: that gate carries the
+D6/D6b/D6c discrimination this one does not have. Everywhere else — a constant,
+a template, a helper parameter — there is no quoted literal at the stamp site
+for a `code`-anchored pattern to match, that gate is structurally blind, and
+dropping the value reported it to nobody. What is measured is now "outside the
+vocabulary **and** unowned by the gate we delegate lowercase to", never "is it
+SCREAMING_SNAKE".
+
+Three stamp positions the scan could not see, all of them widenings:
+
+- **`codehelper`** — a file declares one factory and throws through it
+  everywhere (`postureError(code, message)`, `makeError(status, code, message)`,
+  a `constructor(code, message)`). The stamp `(err as any).code = code` knows
+  the token `code` but not the value; the call site knows the value and never
+  writes the token. Every pattern in **both** gates anchors on that token. The
+  join is the parameter, so its **index** names the argument to read — derived,
+  never assumed to be zero, because two live helpers put `code` second and a
+  first-argument rule reads a number and an English sentence as error codes.
+- **`assignconst`** — `err.code = DENY_CODE`, the assign position's constant
+  sibling. #9223 closed exactly this gap for object literals; the assign
+  position kept it.
+- **`assign`** with a cast on the left. The old anchor demanded a bare
+  identifier where `(err as any).code = 'X'` puts a `)`.
+
+The scan goes from 12 classified sites to 18, and from 0 to 2 codes awaiting a
+ledger entry — the ratchet moving in the direction it exists to move.
+`FLOW_CONVERSION_CONFLICT` (a live 409 from the metadata write path) and
+`owd_widening_forbidden` are recorded as `pending-registration`; four
+`MigrationJournalRefusal` codes are `boot-refusal` (their only consumers are two
+CLI commands, no HTTP boundary). ⛔ No allowlist entry, no narrowed pattern, no
+raised ceiling: **registering or renaming a code stays the `packages/spec`
+lane's call**, and these rows record the measurement rather than prescribing the
+remedy.

.changeset/flat-door-declared-code.md

@@ -0,0 +1,41 @@
+---
+'@objectstack/rest': minor
+---
+
+fix(rest): the flat error responder narrows a thrown `code` to the declared ADR-0112 vocabulary, demoting an unregistered spelling to `declaredCode` (#9232)
+
+**If you read `error.code` off a `packages/rest` flat error body today, read this.**
+
+`packages/rest` answers errors in the flat dialect — `{ error: 'message', code: 'X' }`,
+with `code` at the body's top level. Until now, when that body came from a *caught*
+error, whatever string the producer had put on `.code` was copied to the wire verbatim,
+including spellings that are not members of the ADR-0112 error vocabulary
+(`StandardErrorCode` plus the registered ledger). Every other HTTP door in the platform
+had already stopped doing that.
+
+It stops here too. A thrown `code` is now resolved exactly as the dispatcher door
+resolves it, by the same shared `resolveThrownHttpError` / `demotedDeclaredCode` pair:
+
+- **A registered code is unchanged.** It still arrives in `code`, verbatim, with nothing
+  added beside it. If your branches read registered codes — and every consumer branch
+  measured in this repo, the SDK and the console does — nothing about your code changes.
+- **An unregistered code is demoted.** `code` now carries the vocabulary member the HTTP
+  status derives (a 403 gives `PERMISSION_DENIED`, a 409 `RESOURCE_CONFLICT`, and so on),
+  and the producer's own spelling moves, unchanged, to a new top-level `declaredCode`
+  field beside it. Nothing is lost — but a branch written against an *unregistered*
+  spelling in `code` will stop matching, and must read `declaredCode` instead.
+  Presence of `declaredCode` means demotion: it is absent whenever the producer's code
+  was recognised.
+- **A throw that declared no code still carries none.** Narrowing the vocabulary does not
+  start inventing codes for bodies that had none.
+- **A non-string `code` no longer reaches the body at all.** A numeric driver errno could
+  previously land in `code`; it was never a legal value there and is now treated as
+  context, as it already was at every other door.
+
+The observable case in this repo: the object-posture gate's `403 owd_widening_forbidden`
+now answers `{ code: 'PERMISSION_DENIED', declaredCode: 'owd_widening_forbidden' }`. That
+body could not previously satisfy the schema it claimed to satisfy.
+
+The error body's **position** is unchanged — this dialect still puts `code` at the top
+level rather than in `error.code`. Converging the position is a separate, still-open line
+held by the `check:route-envelope` ratchet, and was explicitly not a precondition here.

.changeset/serve-unknown-hostname-guard-test-seam.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/cli": patch
+---
+
+test(cli): `os serve`'s unknown-hostname guard gets a test seam — the middleware, refusal included, is now reachable without booting a server (#9442)
+
+The `OS_ROOT_DOMAIN` guard was a plugin object literal built inside
+`Serve.run()`, closing over its locals and installing itself on a `http.server`
+service resolved from the plugin context. Nothing about it was exported or
+constructible, so every branch — the health/readiness bypass whose own comment
+says a 404 there "would kill the container", the reserved-subdomain and
+`/_console` redirect branches, the `/_admin` and `/.well-known` pass-throughs,
+the lazy env-registry read whose every failure mode falls through — had zero
+regression coverage.
+
+It is now `createUnknownHostnameGuardPlugin()`, exported from `serve.ts` the way
+its sibling helpers are, with `run()` calling it. Behaviour is unchanged: same
+branches in the same order, same bodies, and `OS_CLOUD_URL` is still read per
+request rather than captured at install time. What is new is a suite that mounts
+the real middleware on a real Hono app and pins BOTH directions — every bypass
+as an explicit pass-through, and the refusal by `error.code` **and** HTTP status
+together.