Merge remote-tracking branch 'origin/main' into claude/issue-16781-scoped-packages-dispatcher-door

Author: claude

.changeset/client-packages-get-single-true-type.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/client": minor
+---
+
+fix(client): `packages.get` binds the bare `InstalledPackage` row on both the global and the environment-scoped client, replacing a `{ package }` envelope no surface emits (#12034)
+
+`client.packages.get(id)` and `ScopedEnvironmentClient.packages.get(id)` now resolve to **`InstalledPackage`** — the row itself — instead of an object wrapping it.
+
+**Migration — read the row directly, not `.package`:**
+
+```ts
+// before
+const { package: pkg } = await client.packages.get('com.acme.crm');
+const pkg2 = (await scoped.packages.get('com.acme.crm')).package;
+
+// after
+const pkg = await client.packages.get('com.acme.crm');
+const pkg2 = await scoped.packages.get('com.acme.crm');
+```
+
+FROM `{ package: any }` (global) and `{ package: InstalledPackage }` (scoped) TO `InstalledPackage` on both.
+
+This is a **narrowing**: a `.package` read compiles today and stops compiling after this change. That is the point of the change rather than a side effect of it — the wrapper was never what the wire sent, so every one of those reads was already `undefined` at runtime, and on the global method the `any` member is what kept the falsehood invisible. Nothing about the request or the wire changes; only the declaration moves to match what the server has been sending.
+
+Why it can be bound now, when #11925 deliberately left it erased: this route used to be served by two implementations that disagreed — the runtime dispatcher sent the bare row, the `@objectstack/rest` registrar sent `{ package }` — so no declaration was true on both. The registrar's read routes were removed in #16628, leaving the dispatcher's `/packages` domain as the single implementation. It builds the detail body with the same expression it maps over every `list` row, which is why this type now agrees with the `InstalledPackage[]` that `packages.list` has already declared, and with `GetInstalledPackageResponseSchema` in `@objectstack/spec`, which has declared `data: InstalledPackageSchema` all along.
+
+The environment-scoped method is the sharper half of the change: its member was a real `InstalledPackage`, not `any`, so `.package` reads there looked type-safe while returning `undefined` against every surface that has served that path since #16628.

.changeset/discovery-services-route-follows-mount.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/rest": patch
+---
+
+fix(rest): `/discovery` no longer contradicts itself — `services.*.route` follows the mounted paths, like `routes.*` already did (#16674)
+
+The `/discovery` document states each service's address twice: once in `routes.X` (the flat convenience map) and once in `services.Y.route` (the per-slot entry). The REST discovery handler rewrote only the first half to the paths this server actually mounts, so any deployment that moved a prefix received a document that disagreed with itself — and the `services` half pointed at a path with nothing mounted on it.
+
+Measured on a boot with `crud: { dataPrefix: '/objects' }`, reading `GET /api/v1/discovery`:
+
+- before — `routes.data` = `/api/v1/objects` (the mounted path), `services.data.route` = `/api/v1/data` (unmounted)
+- after — both answer `/api/v1/objects`
+
+The same split opened on four keys at once for an `apiPath` deployment: `data`, `metadata`, `ui` and `auth`. All four now follow the mount. `services.*.route` is written as a projection of the finished `routes` map, so the two halves cannot state different answers whatever a future substitution does to `routes`.
+
+**A default deployment's document does not move by a byte.** With `crud.dataPrefix` at its `/data` default and `metadata.prefix` at `/meta`, the values the correction writes are the values that were already there; only a deployment that had moved a prefix sees a change, and there the old value addressed nothing. Route-less slots (`cache`, `queue`, `job`, and an in-process `realtime` bus) never gain a route, and no advertisement is withdrawn.
+
+If you have been reading `services.data.route` on a moved-prefix deployment and compensating for it — by re-deriving the path from `routes.data`, or by hard-coding the prefix — that workaround can go: the field now answers the mounted path directly.

.changeset/generate-name-charset-gate.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli)!: `os generate` refuses a metadata name outside the charset `packages/spec` declares for an object `name`, before it derives anything from it (#16726)
+
+Maintainer ruling, decision batch #82 (2026-09-08), option A — **a gate, not a sanitiser**. `os generate <type> <name>` used to accept any name at all; since #16724 it has refused names whose emitted TypeScript does not parse. It now also refuses, ahead of that check and ahead of every derivation, any name the object-`name` declaration in `@objectstack/spec` rejects. The refusal names the value and quotes the schema's own rule, and writes nothing.
+
+⛔ Nothing is rewritten. The rejected alternative was to derive a legal identifier the way `os create` does, which decouples the name the author wrote from the name that gets emitted with nothing announcing it — the failure mode that multiplies silently when metadata is written in bulk. So the name you author and the name that lands in the file are always the same string.
+
+**What this narrows:** kebab-case (`order-line`), uppercase (`Order`), dotted (`foo.bar`) and digit-initial (`2fast`) names were accepted before and are refused now — `order-line` used to generate `order_line.object.ts` binding `orderLine`. Write the snake_case name directly (`os g object order_line`). ⛔ No new charset was minted and no flag bypasses the gate; #16724's parse check is unchanged and stays as the backstop behind it (`class` passes the charset and is still refused for `object`, because `const class:` is not a declaration).
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable or stored moves. No `packages/spec` key, no Zod schema, no authored metadata property and no stored `sys_metadata` shape changes its spelling, type or legality — the charset this gate applies is the one spec ALREADY declares for an object `name`, read rather than redeclared — so `objectstack migrate meta` has nothing to visit, `spec-changes.json` has nothing to project and the upgrade guide has no row to gain. What moves is which ARGUMENT a scaffolding command accepts at authoring time; a name it now refuses was never a legal object `name` in the first place, so no metadata written from an accepted name needs conversion, and files already scaffolded from a refused name are untouched by this change. The remedy is to type a name spec accepts, delivered by the command's own loud refusal at the terminal and by this changelog — the source-code / invocation-side audience the ledger explicitly does not serve (ADR-0087 D8). The other four categories are closed on facts: `@objectstack/cli` publishes to npm (not `unpublished`); no ADR-0087 id is minted in this diff (not `registered`) and none pre-dates the base that would cover it (not `already-registered`); no exported declaration changes shape at all — the gate is a file-local function absent from the package entry — so neither `runtime-interface-only` nor `type-surface-only` has a subject. -->

.changeset/hono-adapter-declared-envelope-render.md

@@ -0,0 +1,55 @@
+---
+'@objectstack/plugin-hono-server': minor
+---
+
+fix(plugin-hono-server): an escaped throw that declares an ADR-0112 envelope is answered as that envelope, not as a bare `500 INTERNAL_ERROR "No response from handler"` (#16545)
+
+`HonoHttpServer.wrap()` is the seam **every direct-mount route passes** — `get` /
+`post` / `put` / `delete` / `patch` each register `this.wrap(handler)`, and
+`IHttpServer` is how `service-datasource`, `packages/rest` and the dispatcher
+bridge all mount. Until now a throw that escaped a route handler was answered
+there as `500 { code: 'INTERNAL_ERROR', message: 'No response from handler' }`,
+with the thrown value discarded — so a producer that had *declared* its refusal
+lost both halves of the declaration on the way to the caller.
+
+The measured case: `service-datasource`'s `requireDatasourceAdmin` re-raises
+`AuthzStoreUnavailableError` (declared `status: 503`, declared `code:
+SERVICE_UNAVAILABLE`) when the authorization store cannot be read — deliberately,
+per the #13279 ruling that an unreadable store licenses no verdict. The operator's
+outage reached the caller as a generic fault naming the wrong component: the
+declared code never arrived, and the message said "No response from handler".
+
+**What changed.** An escaped throw carrying **both** a declared ADR-0112 status
+(a key of `HttpStatusErrorCodeMap`) **and** a code registered in `ErrorCode`
+(`StandardErrorCode` ∪ `ERROR_CODE_LEDGER`) is now rendered as that envelope,
+with the producer's `details` and `userMessage` channels forwarded. The status
+and code are read through `resolveThrownHttpError` — the one rule the REST
+registrar and the dispatcher already share — so this seam agrees with the other
+doors by construction rather than by a second ladder.
+
+**What did NOT change**, pinned in the same PR:
+
+- an escaped throw that is **not** such an envelope answers exactly the bytes it
+  answered before — 500, no cause in the body. A partial declaration (status but
+  no code, code but no status), an unregistered code, and a status ADR-0112 does
+  not declare all take that arm;
+- a handler that simply wrote nothing is untouched;
+- a handler that **wrote and then threw** keeps what it wrote;
+- the `notFound` fallback seam still answers `Fallback handler failed` — a
+  fallback that threw is a broken consumer, not a refusal it declared;
+- ⛔ no error code is minted and no ledger row is added. A code on this path that
+  is not registered is a ledger gap under the #16404 ruling, and takes the
+  unchanged 500 arm rather than being registered in passing.
+
+The 5xx disclosure filter every door emitting a thrown message already runs
+(`looksLikeInternalErrorLeak`, #3867 / #8086) is applied here from this seam's
+first day: a driver dump on a declared 5xx is withheld, where the old bare 500
+disclosed nothing at all. The escaped-throw diagnosis (#5848) still fires exactly
+once at `error`, and now names the answer that was really sent instead of
+claiming an opaque 500.
+
+⚠️ **Known-unreached door, stated rather than left silent.** A route mounted
+through `getRawApp()` funnels through neither `wrap()` nor any registrar wrapper,
+so it is **not** repaired by this change and still answers a non-envelope
+`text/plain` 500. That is out of this card's scope by the `domain:cli` seat's
+ruling and is filed separately.

content/docs/deployment/cli.mdx

@@ -1259,14 +1259,21 @@ only.
 
 Generates properly typed metadata files with barrel index management.
 
+`<name>` is held to the charset `@objectstack/spec` declares for an object
+`name` — lowercase letters, digits and `_`, never starting with a digit. A name
+outside it is refused before anything is derived or written, naming the value
+and the rule; it is **never** rewritten into one that fits, so the name you
+write is the name that lands in the file (`os g object order_line`, not
+`order-line`).
+
 ```bash
 os g object customer        # Generate a Customer object
 os g view customer          # Generate a Customer list view
 os g action approve         # Generate an action
 os g flow customer          # Generate an automation flow
 os g dashboard sales        # Generate a dashboard
 os g app crm                # Generate an app definition
-os g skill lead-qual        # Generate an AI skill
+os g skill lead_qual        # Generate an AI skill
 
 os g object task -d lib/    # Override target directory
 os g object task --dry-run  # Preview without writing
@@ -1894,7 +1901,7 @@ os g object contact
 os g object opportunity
 
 # 3. Add business logic
-os g flow lead-qualification
+os g flow lead_qualification
 
 # 4. Validate everything
 os validate

packages/cli/src/commands/generate.ts

@@ -24,6 +24,10 @@ import {
   isTenancyDisabled,
   isUniqueDeclared,
   numericColumnFor,
+  // #16726 — the name gate below. IMPORTED for the same reason as the five
+  // above: it asks the schema whether a name is legal instead of restating
+  // the charset the schema declares.
+  ObjectSchema,
 } from '@objectstack/spec/data';
 import { printHeader, printSuccess, printError, printInfo, printStep, createTimer, isReportedError, CLI_ALIAS } from '../utils/format.js';
 import { metadataFileName } from '../utils/metadata-file-name.js';
@@ -472,6 +476,54 @@ function toSnakeCase(str: string): string {
   return str.replace(/[-]/g, '_').replace(/[A-Z]/g, c => `_${c.toLowerCase()}`).replace(/^_/, '');
 }
 
+/**
+ * Is this a name `os generate` accepts? (#16726)
+ *
+ * ## The declared answer, asked rather than restated
+ *
+ * The accepted set is the charset `packages/spec` ALREADY declares for an
+ * object `name` — maintainer ruling, decision batch #82 (2026-09-08, option
+ * A): a gate, ⛔ no sanitiser, and ⛔ no third charset. So the judge here is
+ * that declaration itself (`ObjectSchema.shape.name`), reached through the
+ * package's exported surface. Nothing in this file states what the charset
+ * IS: a transcription is a second declaration that can drift green while spec
+ * moves, and the ruling asks for the spec's rule, not for a copy of today's
+ * reading of it. The refusal even quotes the schema's own message, so the
+ * pattern the author is shown is the pattern that judged them.
+ *
+ * ## ⛔ Why it returns a REASON and never a repaired name
+ *
+ * The rejected option (B) was to derive a legal identifier the way
+ * `os create` has since #15892. It was refused because it decouples the name
+ * the author wrote from the name that gets emitted, silently: write
+ * `foo.bar`, get `fooBar` in the file, and every later reference the author
+ * types by hand is wrong with nothing announcing it. For metadata written in
+ * bulk that divergence multiplies unseen. So this answers only *may this name
+ * through*, and the caller refuses loudly — ⛔ it never rewrites, and no flag
+ * bypasses it.
+ *
+ * ## What it deliberately does NOT decide
+ *
+ * Whether the TypeScript the accepted name would produce actually PARSES.
+ * That is #16541's check (`findEmissionParseFailures`), it stays exactly where
+ * it landed, and it is a genuinely different question: `class` is inside this
+ * charset and is still refused by the compiler in a `const` binding position,
+ * while `order-line` emits a perfectly parseable `orderLine` and is refused
+ * here. Neither layer shadows the other — `generate-refuses-name-outside-charset.test.ts`
+ * measures both directions.
+ *
+ * @returns `null` when the name is accepted, or the schema's own reason when
+ *          it is not.
+ */
+function nameCharsetRefusal(name: string): string | null {
+  // Reached lazily, inside the call: `ObjectSchema` is a lazy schema, and a
+  // module-top `.shape` read would materialize it for every CLI command
+  // including the ones that never generate anything.
+  const verdict = ObjectSchema.shape.name.safeParse(name);
+  if (verdict.success) return null;
+  return verdict.error.issues[0]?.message ?? 'not a legal object name';
+}
+
 // ─── Field Type Mapping ─────────────────────────────────────────────
 
 /**
@@ -669,6 +721,58 @@ async function runMetadataGeneration(type: string, name: string, flags: { dir?:
       process.exit(1);
     }
 
+    // ⛔ REFUSE a name outside the declared charset, BEFORE anything is
+    // derived from it (#16726).
+    //
+    // Placed here on purpose, and the position is the ruling: every derivation
+    // this command performs — `toSnakeCase` for the metadata name and the
+    // filename, `toCamelCase` for the binding and the barrel alias,
+    // `toTitleCase` for the labels — happens BELOW this line, so a refused
+    // name is never folded into a legal-looking one on the way to a
+    // diagnostic. It sits after the type roster so that `os g <unknown-type>
+    // <name>` still answers about the type, which is the more useful answer.
+    //
+    // What it is NOT: a sanitiser (option B was refused — see
+    // `nameCharsetRefusal`), a charset of this command's own (the judge is
+    // spec's object-`name` declaration), and not a replacement for the parse
+    // check further down, which stays as the backstop it was built to be.
+    const charsetRefusal = nameCharsetRefusal(name);
+    if (charsetRefusal) {
+      printError(`Refusing to generate — \`${name}\` is not a name this command accepts`);
+      console.log('');
+      console.log(`  ${chalk.dim('Name:')} ${chalk.white(name)}`);
+      console.log(`  ${chalk.dim('Rule:')} ${chalk.white(charsetRefusal)}`);
+      console.log('');
+      console.log(chalk.dim(
+        `  That rule is not \`${CLI_ALIAS} g\`'s own: it is the charset \`@objectstack/spec\``,
+      ));
+      console.log(chalk.dim(
+        '  declares for an object `name`, asked of the schema itself. A metadata name',
+      ));
+      console.log(chalk.dim(
+        '  that is refused there has no business being scaffolded here.',
+      ));
+      console.log('');
+      console.log(chalk.dim(
+        '  It refuses instead of folding your name into one that fits, so the name you',
+      ));
+      console.log(chalk.dim(
+        '  write and the name that lands in the file are always the same string.',
+      ));
+      console.log(chalk.dim(
+        // ⛔ The examples are deliberately NOT built from what the author
+        // typed. A suggestion derived from the refused name is option (B)
+        // wearing a prompt: the author accepts it, and the divergence this
+        // gate exists to prevent arrives one keystroke later.
+        `  Nothing was written. Names like \`${CLI_ALIAS} g ${type} customer\` or`,
+      ));
+      console.log(chalk.dim(
+        `  \`${CLI_ALIAS} g ${type} sales_order\` are accepted.`,
+      ));
+      console.log('');
+      process.exit(1);
+    }
+
     const dir = flags.dir || generator.defaultDir;
     // The written name comes from the registry's `filePatterns` for this type
     // — see `metadataFileName`, which carries why it is derived rather than
@@ -774,10 +878,14 @@ async function runMetadataGeneration(type: string, name: string, flags: { dir?:
         '  which would decide in silence which names this command accepts. Pick a name',
       ));
       console.log(chalk.dim(
-        `  that survives as an identifier — \`${CLI_ALIAS} g ${type} order_line\` and`,
+        // ⛔ This line used to offer `order-line` as an equal alternative. The
+        // #16726 gate above refuses that spelling before this check is ever
+        // reached, so offering it here would send the author to a second
+        // refusal. The CHECK is untouched — only the advice it prints.
+        `  that survives as an identifier — \`${CLI_ALIAS} g ${type} order_line\` works,`,
       ));
       console.log(chalk.dim(
-        `  \`${CLI_ALIAS} g ${type} order-line\` both work, and both fold to \`orderLine\`.`,
+        '  and binds `orderLine`.',
       ));
       console.log('');
       process.exit(1);
@@ -2598,7 +2706,11 @@ export default class Generate extends Command {
 
   static override args = {
     type: Args.string({ description: 'Metadata type to generate (object, view, action, flow, dashboard, app)', required: true }),
-    name: Args.string({ description: 'Name for the metadata (use kebab-case)', required: false }),
+    // ⛔ NOT "use kebab-case" any more (#16726): a name outside the charset
+    // spec declares for an object `name` is refused at the door, and
+    // kebab-case is outside it. What this string advertises and what the
+    // command accepts have to be the same set.
+    name: Args.string({ description: 'Name for the metadata (snake_case)', required: false }),
   };
 
   static override flags = {