Merge branch 'main' into claude/plugin-ordering-convention-t9ylrz

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014DQuJBNpwStpJvo3owBw2B

Author: claude

.changeset/adr-0115-docs-tail-corrections.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(spec,kernel): #4093-series tail — the dev-plugin protocol header stops describing the retired stub design and points at #4149 (the enforce-or-remove evaluation for that declared-but-unconsumed schema family), and services-checklist.mdx gets a ten-fix accuracy pass (verified adversarially). Documentation only; releases nothing.

.changeset/agents-md-worktree-staleness.md

@@ -0,0 +1,28 @@
+---
+---
+
+Two additions to AGENTS.md's multi-agent discipline. Deliberately empty
+frontmatter: documentation, this releases nothing.
+
+**#9 — refresh a long-lived worktree's build state after merging `main`.** Four
+distinct stale artefacts each fail *as if your change broke something*, naming
+other people's exports, other packages' files, or config you never touched:
+`packages/spec/dist` (makes `check:api-surface` report someone else's exports as
+breaking, and `check:i18n-coverage` reject a valid example config), `node_modules`
+(a package cannot resolve a dependency it plainly declares), `packages/runtime/
+.objectstack/` (fixture rows accumulating across runs), and `.cache/objectui-*`
+(dozens of lint errors in files you have never opened). None is CI-visible — CI
+checks out fresh — so the cost lands entirely on whoever is debugging. Also notes
+that `OS_SKIP_DTS=1` leaves no `.d.ts`, which makes `gen:api-surface` impossible
+rather than merely slow.
+
+**#10 — a clean merge is not a working merge.** Git conflicts on overlapping
+lines; nothing warns when two changes are individually fine and jointly wrong.
+Both examples are real and recent: a test pinning a response body's exact shape
+landed while that shape was being changed elsewhere, and a domain file was deleted
+while another agent's guard still declared it. The first merged clean and failed
+CI; the second was caught only because the guard existed. Hence: pull `main` and
+re-run before opening a PR, and again before merging.
+
+Written from one branch's lifetime — every row is a failure that cost a debugging
+round, so the list is what was actually hit rather than what might happen.

.changeset/aggregation-vocabulary-lockstep.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(analytics): a new spec aggregate can no longer silently return a row count
+
+Track C item 4 of objectstack-ai/objectui#2945 — *"`AggregationFunction`: three
+places in lockstep"*. They agreed only by coincidence, and the failure mode when
+they stopped agreeing was silent wrong numbers.
+
+The three:
+
+1. `AggregationFunction` (`@objectstack/spec/data`) — eight members, what an
+   author may declare as a dataset measure's `aggregate`.
+2. `UNSUPPORTED_AGGREGATES` (`dataset-compiler.ts`) — `array_agg`/`string_agg`,
+   rejected at compile time with a clear error.
+3. The aggregate `switch` in `native-sql-strategy.ts` — six cases, then
+   `default: return 'COUNT(*)'`.
+
+8 − 2 = 6 = the six cases, today. Add a ninth member to the spec — `median`,
+`percentile`, anything — and it would:
+
+- pass the compiler's gate, since it is not in `UNSUPPORTED_AGGREGATES`;
+- be **advertised as supported** by that gate's error message, which listed
+  `count, sum, avg, min, max, count_distinct` as hand-written prose — a third
+  copy of the vocabulary;
+- reach the strategy's `switch`, match no case, and fall to
+  `default: COUNT(*)`.
+
+The author asks for a median and gets a row count. No error, no log, wrong
+figures on a dashboard — the same silent-wrong-answer shape as the filter
+operators in #3948, in the analytics SQL builder.
+
+**The fix is derivation plus a guard, with no behaviour change.** The `switch`
+becomes `AGGREGATE_SQL`, a table whose coverage is assertable; the error
+message's prose list becomes `SUPPORTED_AGGREGATES`, derived as
+`AggregationFunction.options` minus `UNSUPPORTED_AGGREGATES`; and
+`aggregation-lockstep.test.ts` asserts the arithmetic — the lowered set equals
+the admitted set, every spec member is either lowered or explicitly rejected,
+nothing is both, and the rejection list names only aggregates the spec has.
+
+Verified by adding a hypothetical `median` to the spec, which now fails three
+assertions naming it, including *"these would fall through to the COUNT(*)
+fallback and return a row count"*. Before this change the same edit was green.
+
+Nothing is narrowed and no SQL changes: the same six aggregates lower to the
+same six expressions, and the `COUNT(*)` fallback still catches everything else.
+
+**Reported, not fixed:** that fallback is also reached by a measure whose `type`
+is `number`/`string`/`boolean` — a custom SQL *expression*, per
+`AggregationMetricType` — whose expression is then replaced by a row count.
+Datasets cannot produce one (`aggregateToMetricType` only ever returns an
+`AggregationFunction` member), so it is reachable only from a hand-authored
+Cube. Emitting `col` instead is a behavioural change in an analytics SQL path
+and deserves its own change with its own tests; the strategy's doc comment now
+records it.

.changeset/app-runtime-hooks-artifact-boot.md

@@ -0,0 +1,53 @@
+---
+'@objectstack/cli': patch
+---
+
+**A config-booted app no longer loses its `onEnable` — every `script` action's
+handler reaches the engine again instead of 404'ing at dispatch (#4095).**
+
+`os serve <config>` calls `createStandaloneStack()`, which reads
+`dist/objectstack.json` and returns a ready-made `AppPlugin` for the app. That
+satisfied serve's "does the host already wrap itself with an AppPlugin?" guard,
+so the `new AppPlugin(config)` built from the LOADED MODULE — the only one
+carrying the module's `onEnable` — was skipped. A JSON artifact cannot hold a
+function, so the app booted with all of its metadata and none of its code.
+
+On `examples/app-todo` that meant eight declared `script` actions, zero
+registered handlers, and every button answering
+`404 Action 'complete_task' on object 'todo_task' not found`. The example is
+correctly authored: it declares `target: 'completeTask'`, registers
+`todo_task:completeTask`, and exports `onEnable`. serve carried that hook intact
+all the way to the branch that discarded it.
+
+Serve now grafts the module's executable members onto the app bundle already
+registered, rather than dropping them with the wrap:
+
+- Only members `AppPlugin` actually executes travel — `onEnable` and the
+  `functions` map that string-named hook/job handlers resolve against. (`onDisable`
+  is deliberately excluded: it is declared in `packages/spec` but no kernel,
+  runtime or service ever calls it, so grafting it would wire a hook nothing
+  runs.)
+- The artifact stays the metadata source of truth. Neither side is a superset —
+  the artifact carries compile-time enrichment the config never has (ADR-0046
+  packaged docs, which serve already grafts the other way) — so this moves code
+  only, and never metadata.
+- Targeting is by `manifest.id`, so a host composing several `AppPlugin`s can
+  never have one app's handlers attached to another. With no id to match, it
+  falls back to the single app bundle present and refuses when there are several.
+- A bundle's own value always wins, so a host that wrapped itself on purpose is
+  untouched.
+- Code that finds no bundle to land on is now reported with a boot warning naming
+  the consequence ("they 404 at dispatch") instead of vanishing. That silent drop
+  is what hid this.
+
+Verified end to end on `examples/app-todo`: `POST /api/v1/actions/todo_task/complete_task`
+went from `404 RESOURCE_NOT_FOUND` to `{"success":true}`, `export_csv` now returns
+real CSV, and the `[action-governance]` boot warning naming all eight actions is
+gone. 14 unit cases pin the graft and — as importantly — the cases where it must
+refuse; one end-to-end case boots a real stack through `bin/run-dev.js` and fails
+against the pre-fix command.
+
+Note that `os serve <config>` still cannot boot at all when `dist/objectstack.json`
+is absent (#4085, `Service 'manifest' is async - use await`). That was verified to
+be a **separate** defect on the other side of the same fork, not this one: the
+failure reproduces unchanged with this fix applied.

.changeset/ci-rerun-safety-and-timeouts.md

@@ -0,0 +1,38 @@
+---
+---
+
+chore(ci): a nightly rerun-safety gate, job timeouts, and a compiled-tests-in-dist guard
+
+Three CI changes, all of them lessons #4065 taught the hard way. No package
+changes — CI configuration only.
+
+**1. Nightly rerun-safety gate (`rerun-safety-nightly.yml`).** Every job in this
+repo runs on a fresh clone, which makes CI structurally incapable of seeing a
+suite that pollutes its own working tree and therefore passes exactly once. CI
+always runs pass #1, so it is always green. #4065 sat in the repo through every
+CI run it ever had and surfaced only because somebody ran the full suite twice in
+one checkout while doing unrelated work — where it looked like *their* change had
+broken something. The new job runs the full suite twice in one tree with
+`--force` (turbo would otherwise replay the cache and report green without
+executing anything) and fails if the second pass disagrees with the first. It
+also prints any `.objectstack/` directories left behind between passes, so a
+failure names a file instead of reading as flakiness.
+
+**2. `timeout-minutes` on all eight `ci.yml` jobs.** There were none, so every
+job inherited GitHub's 6-hour default. On PR #4100 the Test Core job hung with no
+output for 80 minutes and would have held a runner for six hours — and the whole
+time the PR read as "still running" rather than broken, which is the worst
+failure mode a gate can have. Ceilings are ~3-4× the healthy observed duration,
+so a genuinely slow run still passes.
+
+**3. A build-output guard against compiled test files.** A package built with
+plain `tsc` that does not exclude tests emits `dist/**/*.test.js`. `files:
+["dist"]` then publishes them to npm — and, worse, a package with no vitest
+config *collects* those compiled copies alongside its sources, so every
+`src/**/*.test.ts` also runs as a stale `dist/**/*.test.js` frozen at the last
+build. `@objectstack/cli` shipped exactly that (81 test files / 849 tests where
+its sources hold 58 / 581) until #4065 excluded them. That silently defeats
+edits: a fix to a source test appears not to work because the run is still
+executing the pre-fix duplicate. Everything else here builds with tsup, which
+emits only declared entry points — so this gate exists to stop the *next*
+tsc-built package repeating it, not to re-check the one already fixed.

.changeset/cli-stale-dist-tests-and-project-root.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/runtime": patch
+"@objectstack/cli": patch
+---
+
+fix(runtime,cli): `projectRoot` reaches the metadata repository; stop compiling tests into the CLI's dist (#4065)
+
+Two defects behind the last of #4065's stray `.objectstack/` directories — the
+one under `packages/cli/`. Neither is cosmetic.
+
+**1. `projectRoot` only got half the stack.** `createStandaloneStack`'s
+`projectRoot` is documented as scoping a boot's on-disk state to the project
+folder "so different examples / apps don't share a single database by accident",
+and it did redirect the default sqlite database. But it was never passed to
+`MetadataPlugin`, whose `FileSystemRepository` kept rooting at `process.cwd()`.
+So one "project root" meant two different directories: a boot pointed at project
+A wrote `A/.objectstack/data/` and `<cwd>/.objectstack/metadata/`. It now
+forwards `rootDir`, and `bootSchemaStack` accepts a `projectRoot` to pass down
+(defaulting to `process.cwd()`, which is right for every real `os migrate` — the
+CLI runs from the project directory). The two migrate integration suites, which
+build a fixture project in a tempdir, now scope their boots to it.
+
+**2. The CLI compiled its own tests into `dist/` — and vitest ran them.**
+`tsconfig.build.json` included all of `src` with no exclude, so every
+`src/**/*.test.ts` was emitted as `dist/**/*.test.js`. Two consequences:
+
+- `files: ["dist"]` **published** them.
+- This package has no vitest config, so `vitest run` collected the compiled
+  copies alongside the sources: **81 test files and 849 tests where the sources
+  hold 58 and 581**. Every `src/` test also ran as a stale `dist/` twin built
+  from whatever the source said at the last build.
+
+That is not just noise — it silently defeats edits. A fix to a source test
+appeared not to work, because the run was still executing the pre-fix compiled
+duplicate; that is exactly how the `.objectstack` residue survived a correct
+fix long enough to look like a different bug. It also means a source test could
+be edited to pass while its stale twin kept asserting the old behaviour, and
+neither would be obviously wrong. Test files are now excluded from the build.
+
+No other package is affected: the rest build with `tsup`, which emits only
+declared entry points. Verified by scanning every `packages/*/dist` for
+`*.test.js` — the CLI was the only hit.

.changeset/connector-descriptors-meet-their-contract.md

@@ -0,0 +1,62 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": patch
+"@objectstack/runtime": patch
+---
+
+fix(spec,runtime,service-automation): `IAutomationService` declares the connector registry it already serves (#4127)
+
+The fourth and last of the dispatcher call sites #4127 found calling a method its
+contract never declared. The first three shipped in #4143; this one was held back
+because the fix is a **type move**, not a type addition — `ConnectorDescriptor`
+was declared in `@objectstack/service-automation`'s engine, which is one
+*implementation* of `IAutomationService`. A contract cannot name a type that
+lives inside its own implementation, so `getConnectorDescriptors` could not be
+declared at all until the type had a home in the spec.
+
+**`IAutomationService` += `getConnectorDescriptors?()`.** It is the sibling of
+`getActionDescriptors`, which the contract has declared since ADR-0018: the two
+fill the flow designer's `connector_action` node together — node vocabulary from
+one, the connector → action → input pickers from the other. Only one of them was
+written down. `GET /api/v1/automation/connectors` has served the other since
+ADR-0022 by probing for the method and then re-typing its own result as `any` to
+filter on `?type=`, which is a filter on a field the type system did not know
+existed — one typo from silently matching nothing and answering an empty
+registry, which is also what this route legitimately returns when the method is
+absent, so the failure had no distinguishable symptom.
+
+Optional for the same reason `getActionDescriptors` is: a connector registry is a
+capability of the flow-engine implementation, not a property of every automation
+slot. A script-runner filling the slot has no connectors to describe, and the
+route answers an empty registry rather than a 404 — the `handlerReady` posture
+does not apply, since the slot is serveable and only this capability is absent.
+
+**`ConnectorDescriptor` / `ConnectorActionDescriptor` / `ConnectorOrigin` /
+`ConnectorState` move to `@objectstack/spec/integration`**, beside the ADR-0097
+provider contract, for the reason that file already states about itself: they are
+pure types, so a connector plugin — or a designer client, or the dispatcher —
+speaks about registered connectors depending only on the spec, with no runtime
+coupling to the engine. `ConnectorOrigin` is ADR-0097 §4 vocabulary and
+`ConnectorState` is #3017 vocabulary; neither was ever engine-private in meaning,
+only in location.
+
+Nothing is renamed and no shape changes. `@objectstack/service-automation`
+imports the four back and re-exports them from its index — the same names, from
+the same entry point — so every existing importer compiles unchanged.
+`ConnectorState` joins that re-export, which it should have been in all along: it
+is a required field of the descriptor the index has always exported.
+
+**The test fixture had already drifted, which is the concrete cost.** The
+dispatcher's connector mock declared `{ name, label, type, actions }` and omitted
+`origin` and `state` — both **required** on `ConnectorDescriptor`, and both the
+fields a designer reads to tell a live declarative instance from a plugin one
+(ADR-0097 §4), or a dispatchable connector from a degraded one that is listed
+honestly rather than hidden (#3017). Nothing caught it, because an undeclared
+return type cannot be checked against. The fixture is typed now, so it cannot
+drift again, and a new test pins that `origin` / `state` / `degradedReason`
+survive the hop through the route rather than only `name` and `type`.
+
+Verified: `@objectstack/spec` **7089 tests / 272 files** (2 new contract tests),
+`@objectstack/service-automation` **457 / 41**, `@objectstack/runtime`
+**218 http-dispatcher tests** (1 new), `tsc --noEmit`, `pnpm lint`, the liveness
+and empty-state gates, and the three generated-artifact gates — all clean.

.changeset/current-user-endpoints-kernel-resolver.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/plugin-hono-server": minor
+---
+
+fix(plugin-hono-server): the current-user endpoints answer from the kernel that OWNS the request (cloud#927)
+
+`/api/v1/auth/me/permissions`, `/auth/me/localization` and `/me/apps` resolved
+their answer from the service locator captured at REGISTRATION time. On a
+single-environment host that is the only kernel, so it is right. On a
+**multi-tenant** host it is the routing shell — and identity is not there.
+cloud's `ArtifactKernelFactory` mounts `AuthPlugin` per environment, and its host
+kernel deliberately has none ("AuthPlugin is intentionally NOT injected on the
+host"), so `getService('auth')` threw, the session resolver fell to its catch, and
+every authenticated tenant caller got `{authenticated:false}`.
+
+That is worse than an error: objectui's `MePermissionsProvider` reads
+`authenticated:false` as ANONYMOUS and keeps its permissive default
+(`return data.authenticated !== true`), because a guest surface has no resolvable
+permissions by design. So the console's FLS / `apiOperations` hints were
+systematically wrong — not a bypass (the server still enforces per request), but
+exactly the client/server divergence `foldWildcardSuperUser` and
+`clampManagedObjectWrites` exist to close, one layer up.
+
+These endpoints now consult the host's ADR-0006 **`kernel-resolver`** seam per
+request — the same seam the runtime dispatcher has used since Phase 5, so
+multi-tenant routing has one strategy rather than two:
+
+- **No `kernel-resolver` registered** → unchanged. Single-environment hosts,
+  `os serve`, and the QA conformance host see no difference.
+- **A kernel** → that kernel's `auth` / `objectql` / `metadata` /
+  `security.permissions` answer.
+- **`undefined`** → the registration-time locator, which is the seam's contract
+  for an unscoped / control-plane request.
+- **A throw** → no answer at all: the thrown status when it carries one (cloud's
+  `KernelWarmingError` is 503 + `Retry-After`), else 503
+  `environment_unavailable`. Falling back to the default kernel would hand back a
+  confidently-wrong `{authenticated:false}` that the client fails OPEN on.
+
+The seam is read **lazily, per request**, never captured at registration — a host
+may register these routes before `kernel.bootstrap()` (to outrank an
+`/api/v1/auth/*` wildcard), which is before the plugin that registers the
+resolver has run its `init()`.
+
+**FROM → TO for host adapters.** `CurrentUserEndpointsContext` gains an optional
+`getKernel(): unknown`, the `defaultKernel` argument the seam takes. A
+`PluginContext` already satisfies it, so hosts that mount `HonoServerPlugin` need
+no change. A host passing a hand-rolled locator to
+`registerCurrentUserEndpoints` should add it:
+
+```diff
+ registerCurrentUserEndpoints({
+   rawApp: httpServer.getRawApp(),
+-  ctx: { getService: (n) => kernel.getService(n) },
++  ctx: { getService: (n) => kernel.getService(n), getKernel: () => kernel },
+ });
+```
+
+Without it a multi-tenant host cannot be asked which kernel owns the request and
+keeps the old provenance — a silent downgrade, so it is worth adding even where
+the host is single-environment today.