Merge remote-tracking branch 'origin/main' into claude/merge-14036-round2

Author: claude

.changeset/approvals-inspector-sees-failed-mid-resume.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/plugin-approvals": patch
+---
+
+fix(plugin-approvals): the stranded-request inspection now sees a run that FAILED mid-resume (#13909)
+
+`ApprovalService.inspectStrandedRequests` was structurally blind to the shape
+#13909 owns, and reported `0` for it — the one shape an operator most needs to
+see.
+
+**The mechanism.** `AutomationEngine.resumeInternal` consumes the suspension
+*before* running the downstream nodes: `forgetSuspendedRun(run, 'resumed')`
+precedes `traverseNext`. A downstream node that merely THREW therefore threw
+with the pause already gone, the catch arm recorded the run `failed`, and
+nothing can resume it again (`resume` answers `RUN_NOT_FOUND`, `cancelRun` is a
+no-op). The decision is durable and the flow stopped half-way.
+
+**Why the inspection could not see it.** Its second oracle was
+`if (terminal) continue` — the existence of ANY run-history row ended the check,
+on the reading "the run ran to a terminal state, it is not dangling". But the
+terminal row here is written BY the failure that stranded the request, so the
+evidence of the defect was read as evidence of health. `releaseDeadRunRequests`
+cannot see it either: it scans `status: 'pending'`, and the decision is what
+took the row out of `pending`.
+
+**The widening, and its limits.** The second oracle now classifies the run
+instead of merely detecting it. A `failed` run is reported; `completed`,
+`cancelled` and `paused` are each still skipped, one named reason at a time, and
+a status this code does not recognise is skipped too — the spec's
+`ExecutionStatus` vocabulary is wider than the four statuses the engine writes,
+and a future status must not become a silent false positive. `paused` in
+particular stays skipped because "the suspension is gone but no terminal row is
+written yet" is exactly what a resume IN FLIGHT looks like. The first oracle is
+unchanged: a run the suspension store still holds is alive, and an unreadable
+store is still counted `undetermined`, never condemned.
+
+Reported rows now carry `runState: 'missing' | 'failed'` (new exported type
+`StrandedRunState`), because the two shapes need different remedies: a `missing`
+run has no history to read, a `failed` one has a step log and an error naming
+the node that threw. The sweep's own warning splits its counts the same way.
+`StrandedApprovalRequest` is an output-only reporting shape the service
+produces; the added field is not constructed by any caller in this repo.
+
+**Still read-only, and still not a census.** No status is changed and no run is
+cancelled — the decision genuinely happened. This makes the condition *visible*
+in a deployment; how many runs are already in it can only be answered against
+that deployment's own tables. Nothing here changes the resume ordering, which
+is #13909's own next slice.

.changeset/automation-context-flowname-attribution-prose.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): correct `AutomationContext.flowName`'s attribution prose — elevation decides authorization, not attribution (#14011)
+
+The published contract for `AutomationContext.flowName` (shipped in
+`dist/contracts/index.d.ts`) said a `runAs:'system'` run "resolves no user", so
+`resolveRunDataContext` labels its data operations `svc:flow:<flowName>` on
+`ExecutionContext.actor` "instead of leaving the audit row unattributed".
+
+That reads as **"system elevation costs you the operator in the audit trail"**,
+and it has not been true since #5494. What ships: `resolveRunDataContext`
+carries the triggering user through UNCHANGED under elevation — `isSystem`
+alone decides authorization, while the user drives the platform's attribution
+stamps. A write made with `{ ...callerCtx, isSystem: true }` leaves
+`created_by` / `updated_by` naming the caller, identical to the same write on
+the plain user path; the audit writer records `session.userId ?? session.actor`
+on `sys_audit_log.actor`, in that order, with no `isSystem` gate anywhere in
+either path.
+
+The `svc:flow:` labelling the sentence described is real, but it is the
+FALLBACK for a run that genuinely has no operator — a schedule, or a
+`runAs:'system'` flow fired by a write that itself carried no user. The
+sentence generalised it to every `runAs:'system'` run.
+
+Runtime behaviour is unchanged: this corrects the description of shipped
+behaviour, nothing else. The correction is now also pinned by
+`runas-attribution-contract.test.ts` in `@objectstack/service-automation`, which
+asserts both limbs against the real ObjectQL stack — so if the code ever
+becomes what the old prose described, a test goes red rather than a reader
+having to re-measure.
+
+Why it earned a card rather than a shrug: downstream, the stale sentence was
+written into an adjudication as the explicit stop-condition for a security
+design ("if elevation erases the operator, stop and report a fork"). The
+correct design was one measurement away from being abandoned on a false
+premise. Prose that talks a reader out of the right answer is worth more than a
+cosmetic fix.

.changeset/cli-hook-body-lowering-loud.md

@@ -0,0 +1,56 @@
+---
+'@objectstack/cli': minor
+---
+
+feat(cli): `os lint` refuses a hook body that silently stopped being metadata (#13651)
+
+An L2 hook handler is lowered to a metadata-only `body.source` and evaluated in
+QuickJS with no module scope. When the handler reaches out of that scope,
+`extractHookBody` refuses — and `lowerCallables` caught the refusal, recorded it,
+and shipped the callable through the back-compat `.mjs` bundle instead. `os build`
+exited 0. The hook kept working locally. What changed silently was the
+**deployment shape**: the app had stopped being shippable as pure metadata.
+
+The refusal was never the missing piece — `extractHookBody` had already computed
+the exact free-identifier list. What was missing is that nothing said no to the
+recorded array.
+
+**The refusal now carries its classification — and what that publishes rides
+on two CLI surfaces, not on new API exports.** Internally,
+`HookBodyExtractionError` (with `HookBodyRefusalKind`) names which rule
+refused — `free-identifiers` / `forbidden-token` / `unparseable` — and
+`lowerCallables` records it beside the identifier list on each
+`bodyExtractionWarnings` entry. Those types are module-internal: the package
+`exports` map exposes only `.` and `./console`, and `src/index.ts` re-exports
+none of them. What this release actually publishes is:
+
+- **`os lint`'s exit contract** — the new `hook-body/not-lowerable` rule is an
+  `error`, so `os lint` can now exit 1 where it previously exited 0.
+- **`os build --json`** — each `bodyExtractionWarnings` entry now carries
+  `kind` and `freeIdentifiers` fields beside the unchanged `origin`/`reason`.
+
+**`os lint` is the first consumer, and it tells the classes apart.** They
+used to share one catch, so they shared one fate:
+
+- **accidental** (`free-identifiers`) — the handler *is* expressible as a
+  metadata body; it merely names a module-scope const, helper or import. Now a
+  lint **`error`**, so a gate can fail on it. `os lint` exits 1.
+- **structural** (`forbidden-token`) — `fetch`/`require`/`process`/… are
+  capabilities the sandbox does not have, so writing one *is* choosing a bundled
+  closure and the bundle is the designed answer. Reported as a **`warning`**,
+  never fatal.
+- **instrument** (`unparseable`, or a failure of the extractor itself) — the
+  tool could not judge the body at all. Reported as a **`warning`** under its
+  own rule, with prose that names the instrument — never as if the author chose
+  a bundle, because an instrument failure is not a verdict about the author.
+
+An author who deliberately wants a bundled closure keeps two channels that
+already existed and are still silent: give the hook an explicit `body`, or move
+the function into the top-level `functions:` map and reference it by name.
+
+**What did NOT change: what `os build` accepts.** The catch in `lowerCallables`
+stays, both classes still fall back to bundling, and the build still exits 0 —
+verified over a real spawned `os build`. Flipping that default is a separate
+contract decision. The new rule runs the *same* `extractHookBody` the build
+runs, so the lint verdict cannot drift from what the build would do to the same
+handler.

.changeset/denial-door-carries-user-message.md

@@ -0,0 +1,45 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): carry the producer's `userMessage` at the dispatcher's PERMISSION_DENIED door (#13623)
+
+`HttpDispatcher.dispatch`'s foot catch is not a pure rethrow: it recognises
+`isPermissionDeniedError` — `name === 'PermissionDeniedError'`, **or**
+`code === 'PERMISSION_DENIED'`, **or** a message starting `[Security] Access
+denied` — and answers the refusal itself from
+`packages/runtime/src/http-dispatcher.ts`. A marked denial therefore never
+reached `dispatcher-plugin`'s throw-transparent exit, which is the door #13241
+taught to carry the author-facing text channel, and lost the mark at this one
+instead. `ApiErrorSchema.userMessage` has declared the slot all along and
+`contract.zod.ts` states the invariant directly — *"`userMessage` on the thrown
+error; the boundaries carry it to the wire"* — so this is `declared ≠ enforced`
+at one more boundary, not a new field.
+
+**Why this door matters more than its size.** #9934 made the mark
+status-agnostic precisely so a 403 could carry it, and a 403 is the refusal
+class most likely to carry deliberately-authored text ("You do not have access
+to this report; ask an admin for the Reporting role"). The one door that
+swallowed the mark was the one answering exactly those refusals.
+
+**Transport parity, which the same ruling already asked for.**
+`@objectstack/rest`'s `mapDataError` has carried the field on this identical
+denial since #9934 (`withDeclaredUserMessage` over `classifyDataError`, whose
+`PERMISSION_DENIED` branch is pinned in
+`packages/rest/src/rest-user-facing-refusal-marking.test.ts`). The 2026-08-11
+ruling on #7450 makes REST's shape the contract for both transports; until now
+the dispatcher's 403 was the one that differed.
+
+**⛔ #7450's disclosure withhold is untouched.** That ruling is about
+`error.details` — the gate's `positions` / `permissionSets` and the cascade
+child `object` the caller never addressed — and all of it is still dropped from
+the wire and still logged server-side. `userMessage` is the opposite by
+construction: it exists only because a producer wrote text *for* the caller,
+platform and driver code never set it, and it rides as a declared top-level
+sibling of `code`/`message`, never inside `details`. The read is
+`declaredUserMessage` (`@objectstack/types`), the one rule every boundary
+applies, so this door cannot fork its own answer to "what counts as marked".
+
+**No behaviour change for an unmarked denial.** Its envelope is byte-identical
+to before — key set `code` / `details` / `httpStatus` / `message`, pinned — and
+the mark never moves the status or the `code`.

.changeset/docs-nav-title-short-sidebar-label.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/docs": patch
+---
+
+feat(docs): give a doc page a short sidebar label (`navTitle`) distinct from its `title` (#12311)
+
+A doc page's frontmatter `title` was the only string the site had, so it served
+six consumers with different length budgets at once — measured on `origin/main`,
+405 pages under `content/docs`, whose only frontmatter keys are `title` (405) and
+`description` (405):
+
+| consumer | site |
+|---|---|
+| SERP `title`, OG and twitter metadata | `app/[lang]/docs/[[...slug]]/page.tsx:211,216,227,233` |
+| on-page `h1` | `page.tsx:150` |
+| JSON-LD `TechArticle` headline/name | `page.tsx:123,124` |
+| JSON-LD `BreadcrumbList` | `page.tsx:95` — via the page tree |
+| `llms.txt`, `llms-full.txt`, the `.mdx` endpoints | `app/llms.txt/route.ts:10`, `lib/source.ts` `getLLMText` |
+| Open Graph card image | `app/og/docs/[...slug]/route.tsx:18` |
+| sidebar / page tree | `lib/source.ts` — `loader()` |
+
+A 50–60 character title carrying search intent is right for the first six and
+unreadable in the last, which is why #12237's title rewrite stopped after the
+four pages that have no sidebar entry.
+
+`navTitle` is the page tree's own string. It is declared on the docs page schema
+(`docsSchema = pageSchema.extend({ navTitle: z.string().optional() })` in
+`apps/docs/source.config.ts`) and resolved in exactly one place —
+`apps/docs/lib/nav-title.ts`, whose header is the mechanism's documentation —
+through `fumadocs-core`'s own `PageTreeTransformer` hook, the same extension
+point its built-in icon plugin uses. **`title` is the declared fallback**, stated
+there and at no read site, so all 405 pages keep their present sidebar entry with
+no frontmatter change.
+
+`fumadocs-core@16.14.4` ships no first-class equivalent: its `pageSchema` is
+`{ title, description, icon, full, _openapi }`, its `metaSchema` carries no
+per-page label field, and its page-tree builder reads `{ title, description,
+icon }` off a page. `scripts/check-docs-nav-label.mjs` re-reads both schemas on
+every run, so the day an upgrade does ship one, the gate says migrate.
+
+The separation is pinned rather than described. That gate holds `navTitle` to two
+code sites, executes the resolver over its fallback cases, and keeps the JSON-LD
+breadcrumb's leaf crumb on `page.data.title`: `getBreadcrumbItems` is now called
+with `includePage: false`, so the leaf comes from the page's own title instead of
+its page-tree node — behaviour-identical today (the node's name *is* the title),
+and the one place the short label would otherwise have reached structured data a
+crawler reads.

.changeset/driver-registry-eviction.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/service-datasource": patch
+"@objectstack/spec": minor
+---
+
+Deleting a datasource now evicts its driver from the data-engine registry, so `/api/v1/ready` recovers without a process restart
+
+**BREAKING** `IObjectQLEngine` gains a REQUIRED member, shipped as `minor`
+under the repo's launch-window convention for breaking changes.
+
+`unregisterDriver(name: string): boolean` is additive for CONSUMERS — nothing
+they already call changes — but it breaks any third-party *implementer* of
+`IObjectQLEngine` at compile time, and the interface is on the published
+surface (`packages/spec/src/contracts/index.ts` re-exports it and `./contracts`
+is a published export path). Graded `minor` to match this contract's own
+precedent: the three prior changes to it all took `minor`, including one that
+added five members that were **all optional** and therefore broke nobody by
+construction. A required member grading below that would be inconsistent.
+
+The ObjectQL driver registry had a `registerDriver` door and no counterpart, so
+nothing could ever leave it. Deleting a datasource emptied the admin door while
+`GET /api/v1/ready` kept naming the deleted datasource's driver — the readiness
+probe reports whatever `checkDriversHealth()` finds in that registry — and on a
+multi-replica deployment the only recovery was restarting every process.
+
+`IObjectQLEngine` gains `unregisterDriver(name)`, the removal counterpart of
+`registerDriver`. The registry owns the invariant rather than each caller: an
+eviction has to drop the driver entry, clear the `defaultDriver` NAME when it
+pointed at the evicted driver (otherwise `getDefaultDriverName()` answers with a
+name nothing backs), and drop the datasource definition that has no removal door
+of its own. Evicting does not disconnect the pool — teardown belongs to whoever
+owns it.
+
+Three lifecycle paths now use it:
+
+- **Datasource delete / pool teardown** — `DatasourceConnectionService.disconnect()`
+  evicts after closing the pool, which is the path `DELETE /api/v1/datasources/:name`
+  reaches. The default driver is evicted under its natural registered name.
+- **Failed-start rollback** — a connect that throws after registering now rolls
+  that registration back, instead of leaving a driver the admin list reports as
+  failed and the readiness probe still pings.
+- **Engine teardown** — `destroy()` disconnects and then evicts, so a destroyed
+  engine no longer reports drivers whose pools it has already closed.
+
+Eviction is per-replica, matching how driver registration already works
+(each replica registers pools from the shared datasource records at boot);
+propagating it cluster-wide would need a broadcast channel the driver registry
+does not have today.
+
+<!-- adr-0087: not-required (no-migration-prescription) this change is purely ADDITIVE: `IObjectQLEngine` gains a member and nothing is renamed, retired or converted, so there is no authored metadata for `objectstack migrate meta` to rewrite and no migration to prescribe. The breaking half is compile-time only, against third-party IMPLEMENTERS of the interface; consumers are unaffected. Deliberately NOT claimed as runtime-interface-only: this gate classifies packages/spec/src/contracts/** as a metadata surface, so that category is false here even though the symbol is a TypeScript interface with no Zod schema behind it. -->