Merge remote-tracking branch 'origin/main' into claude/issue-15298-declared-permission-sets-docblock

Author: claude

.changeset/cli-option-b-config-load-boundaries.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os serve` / `os dev` / `os build` / `os migrate` resolve `packages[]` when a stack carries no flattened top level
+
+The CLI holds four independent config-load boundaries, and every read of a
+package-owned collection behind them was an inline expression against the
+FLATTENED top level. A multi-package stack that carries each definition once
+under `packages[]` — the shape ADR-0130 D4's option B produces — reached those
+expressions with the key simply absent, and nothing threw:
+
+- `os serve` / `os dev` auto-register the ObjectQL engine and the storage driver
+  when the stack declares objects. Both gates read `config.objects`, so the app
+  booted with **no query engine and no storage driver** and reported healthy.
+  Nothing between the artifact and the gate could notice: the standalone stack
+  omits the `objects` key entirely when the array is absent rather than setting
+  `[]`, and the boot-config merge is a plain spread.
+- `os serve` auto-registers the i18n service plugin when the stack carries
+  translations. `translations` is package-owned while `i18n` is an envelope key a
+  translations-only stack never sets, so the REST i18n routes silently did not
+  exist.
+- `os dev` diffs the artifact's object inventory across recompiles to name a
+  newly added `*.object.ts`. It went permanently empty, so every recompile read
+  as all-green.
+- `os build` runs the author-time rule table twice — once over the union, once
+  per package. The per-package run already read `packages[]`; the union run,
+  which is the only one of the two that can see a finding spanning packages,
+  judged an empty stack and published green.
+
+All of them now resolve through one seam, in the dependency-topological order
+`resolveArtifactPackageOrder` gives. Each answer starts from the expression it
+replaced, so every stack that boots or builds today takes the identical branch —
+including a stack declaring an empty `objects: []`, which stays a stack that gets
+an engine — and `packages[]` is consulted only where the old read returned
+nothing. A malformed `packages` list is refused with its ADR-0112 envelope on
+that leg instead of resolving to the silent empty.
+
+The predicate `os serve` and `os migrate` each carried their own copy of — "does
+this config carry app metadata that needs an `AppPlugin` wrap" — is now one
+function. Measured, it does not lose under the new shape; it is folded in because
+it is the master gate for everything `AppPlugin` then reads.
+
+No command emits anything different: the compiled artifact still carries both
+copies, and the folded stack is a rule INPUT that reaches no writer.

.changeset/driver-sql-update-declared-null.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/driver-sql': minor
+---
+
+feat(driver-sql): `update()` publishes its honest type — the contract's `Record<string, unknown> | null`, not `any` (#14438)
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing, shipped as `minor` under the launch-window convention (the one PR #14434 used for the same door on `@objectstack/driver-memory`). `SqlDriver.update()` was written out with an explicit `Promise<any>` while it has always answered a missing id with `null` (`formatOutput(...) || null` on the un-rotated path, `null` once every rotation shard has been probed). `IDataDriver.update()` declares `Promise<Record<string, unknown> | null>`, and an explicit `any` satisfies that structurally — so the emitted `.d.ts` read `Promise<any>` and no caller holding a `SqlDriver`, or a `SqliteWasmDriver` (which inherits the door unchanged), was ever asked to narrow. It is now declared as the contract declares it, and the protected rotation-path producer `rotatedUpdateById()` carries the same type. A caller that read fields off `update()`'s result through the `any` now narrows the `null` arm first; a caller that leaned on `any` to read undeclared members now types them. No runtime behaviour changes.
+
+`@objectstack/driver-sqlite-wasm` re-declares no `update` member of its own (measured on its emitted `.d.ts`), so it carries no entry: the narrowing reaches its consumers through this package's `.d.ts`. `@objectstack/driver-turso` overrides the door and carries its own entry.
+
+<!-- adr-0087: not-required (type-surface-only packages/drivers/driver-sql/src/sql-driver.ts#update) A published driver method's declared return moves off an explicit `any` onto the contract's own shape. No metadata key is removed, renamed or re-shaped, `packages/spec` is untouched, and nothing exists for `objectstack migrate meta`, `spec-changes.json` or the upgrade guide to rewrite; the obligation is a TypeScript narrowing at the consumer's own call site, delivered by the compiler. -->

.changeset/driver-turso-update-declared-null.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/driver-turso': minor
+---
+
+feat(driver-turso): the `update()` override publishes its honest type — `Record<string, unknown> | null`, not `any` (#14438)
+
+**BREAKING** for TypeScript consumers — a published TYPE-surface narrowing, shipped as `minor` under the launch-window convention. `TursoDriver` overrides `update()` rather than inheriting it, and the override was written out with its own explicit `Promise<any>` — so this package's emitted `.d.ts` re-declared the door as `any` on its own and would not have picked up the `@objectstack/driver-sql` narrowing. Both of its branches already answered the contract's type: the local branch forwards to `SqlDriver.update()` (narrowed alongside, #14438) and the remote branch passes `RemoteTransport.update()`'s `Record<string, unknown> | null` (#14428) through the generic `formatRemoteRow`. The override now declares what it answers. A caller that read fields off the result through the `any` now narrows the `null` arm first. No runtime behaviour changes.
+
+<!-- adr-0087: not-required (type-surface-only packages/drivers/driver-turso/src/turso-driver.ts#update) A published driver method's declared return moves off an explicit `any` onto the contract's own shape; no metadata key moves, `packages/spec` is untouched, and the obligation is a TypeScript narrowing at the consumer's own call site, delivered by the compiler. -->

.changeset/service-storage-test-tsc-program.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/service-storage": patch
+---
+
+fix(service-storage): put the test layer in front of tsc, and repair what it was hiding (#15050)
+
+`packages/services/service-storage` had **no `typecheck` script at all** — its
+scripts were `build` and `test` — so no tsc program anywhere read this
+package's test layer, and its errors were carried instead as a 51-error DEBT
+entry in `scripts/check-type-check-coverage.mjs`. Gives it the #14062 /
+#14181 "checked test zone" shape: a sibling `tsconfig.test.json` (module
+semantics only — `esnext` / `bundler` / `lib: ES2022` — matching how vitest
+actually executes these files; strictness inherited and untouched) plus a
+`tsconfig.scripts.json` for `scripts/i18n-extract.config.ts` (the ninth
+instance of #11351, previously excluded from that ledger only because this
+package had no `typecheck` script to hang it on), both named by a new
+`typecheck` script.
+
+Measured before repair: 51 errors under BUILD semantics (`tsc --noEmit -p
+tsconfig.json`, which already includes the tests — matching the DEBT entry's
+recorded number exactly), 10 under the split. Unlike `service-cluster`
+(#14181), this package's BUILD reading was *not* already clean, so both
+programs needed genuine repair, not just the test-only split: 23 `TS2835`
+(relative imports missing their `.js` extension, required under BUILD's
+NodeNext resolution) were fixed by *adding* the extension — which resolves
+correctly under both NodeNext and the split's bundler mode — and clearing
+that also cleared all 15 `TS7006` "implicitly any" as a downstream cascade
+from the same unresolved imports (the shape `@objectstack/core` reported at
+98 → 4). The remaining 3 `TS2550` (`Array.prototype.at` needing `lib`
+es2022) are rewritten to indexed access rather than widening the shared
+BUILD `tsconfig.json`. The 8 code-tier errors (`TS2339` × 4 — a test
+helper's object-spread dropped its `Record<string, unknown>` index
+signature, fixed with an explicit return-shape annotation; `TS2347` × 4 — a
+fake `ctx: any`'s `getService<T>(...)` calls converted to `getService(...)
+as T`, the pattern one call site in the same file had already adopted for
+exactly this reason) are genuine test-file fixes. Both readings now agree at
+0/0 — the same result `service-cluster` reported, reached by a longer road.
+
+The package's DEBT entry (51 errors) is **deleted**, not lowered — the
+graduation this ratchet's invariant requires. No `test-typecheck-debt.json`
+is added: residue is 0, so none is owed (#5286, maintainer-only to open).
+`check:type-source-resolution` went red from onboarding the two new
+programs (the documented onboarding-limb case): a registry entry is added
+rather than `paths`, measured both ways — `paths` takes this package's test
+layer from 0 errors to 306, all in other packages' source.
+
+No runtime code changes: `src/**` excluding tests is byte-identical, so no
+shipped behaviour moves. The `patch` level reflects the published
+`package.json` gaining `typecheck` / `check:test-typecheck` scripts and a
+`tsx` devDependency.

.changeset/sys-email-error-description-widen.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/platform-objects": patch
+---
+
+fix(platform-objects): `sys_email.error` field help now covers pre-delivery rejections, not only transport failures
+
+`sys_email.error` was declared as *"Transport error message when status=failed"*.
+Since `EmailService.recordRejectedMessage` landed, the same column also carries
+the reason a message was rejected by `normalizeMessage` **before** it reached a
+transport (an unsendable `from`, no recipient, no subject, no body) — those rows
+are written with `status: 'failed'` too, prefixed `rejected before delivery: `.
+
+Nothing was misleading in the *data*: the row prefixes its own reason, so an
+operator reading a failed row is never sent chasing an SMTP host for a message
+that never reached one. What was stale was the field's declared `description`,
+which Studio surfaces as the field's help text — it named only the transport
+case, narrower than what the column has held since that change landed.
+
+The description now reads: *"Why the message failed — a transport error, or the
+validation that rejected it before delivery."* It stays true under both row
+shapes and deliberately does not name the row's own `rejected before delivery:`
+prefix, so it will not go stale again if that prefix's wording changes.

packages/adapters/hono/src/index.ts

@@ -159,8 +159,9 @@ export function createHonoApp(options: ObjectStackHonoOptions): Hono {
       // use a matcher function — Hono's cors() middleware does exact-string matching only and
       // treats '*' in patterns as a literal character, so passing wildcard strings straight
       // through would silently drop the Access-Control-Allow-Origin header on every real
-      // request (preflight can still succeed via apps/objectos's short-circuit, but the
-      // subsequent POST/GET would be blocked by the browser).
+      // request (preflight can still succeed via the short-circuit in `apps/objectos`,
+      // which lives in the separate `objectstack-ai/cloud` repo and is NOT a path in
+      // this one, but the subsequent POST/GET would be blocked by the browser).
       //
       // This mirrors `plugin-hono-server`'s CORS wiring and uses the shared pattern matcher
       // from `@objectstack/plugin-hono-server` so all Hono-based code paths stay in sync.

packages/cli/src/commands/compile.ts

@@ -15,6 +15,7 @@ import {
 } from '@objectstack/spec';
 import { loadConfig } from '../utils/config.js';
 import { lowerCallables } from '../utils/lower-callables.js';
+import { authoringRuleUnionStack } from '../utils/stack-collections.js';
 import { buildAccessMatrix, diffAccessMatrix } from '@objectstack/lint';
 import { runAuthoringRules, splitBySeverity, authoringRulesFor } from '@objectstack/lint';
 import { resolveSduiManifest } from '../utils/sdui-manifest.js';
@@ -356,9 +357,24 @@ export default class Compile extends Command {
       //     is declared in `lint/authoring-rules.ts`. Do not add a call site here.
       const registered = authoringRulesFor('build');
       if (!flags.json) printStep(`Running author-time rules (${registered.length})...`);
+      //     [ADR-0130 D4 / option B, #15006] The UNION run judges the flattened
+      //     top level. Under option B that top level is gone — `packages[]`
+      //     carries every definition once — so this run's input would be an
+      //     EMPTY stack and `os build` would publish green having judged
+      //     nothing. `authoringRuleUnionStack` folds each absent collection
+      //     back in from `packages[]`, in `resolveArtifactPackageOrder`'s
+      //     dependency order. It changes what the rules JUDGE and nothing this
+      //     command EMITS: the artifact is written from `lowering.lowered` /
+      //     `result.data`, which this does not touch, and a stack that still
+      //     carries its collections is returned by identity.
+      //
+      //     The per-package run below needs no such fold — it already reads
+      //     `packages[]`. The union run is the only one of the two that can see
+      //     a finding spanning packages, which is exactly what an empty input
+      //     silently stops reporting.
       const findings = runAuthoringRules('build', {
-        normalized: normalized as Record<string, unknown>,
-        parsed: result.data as Record<string, unknown>,
+        normalized: authoringRuleUnionStack(normalized as Record<string, unknown>),
+        parsed: authoringRuleUnionStack(result.data as Record<string, unknown>),
         sduiManifest: resolveSduiManifest(),
       });
       const { errors: ruleErrors, advisories } = splitBySeverity(findings);

packages/cli/src/commands/dev.ts

@@ -17,6 +17,7 @@ import {
   formatMtimeGap,
 } from '../utils/dev-restart.js';
 import { childEnvWithResolvedArtifact } from '../utils/internal-artifact-channel.js';
+import { artifactObjectNames } from '../utils/stack-collections.js';
 import { readEnvWithDeprecation, isMcpServerEnabled } from '@objectstack/types';
 // The ONE port contract, shared with `start` and with the `serve` child this
 // command spawns (#12673). ⛔ Nothing about ports is declared in this file —
@@ -650,16 +651,16 @@ export default class Dev extends Command {
       // newly added *.object.ts is called out explicitly (15.1 third-party
       // eval: "recompiled" alone read as all-green while the new object's
       // table/seed sync was invisible to the user).
+      // [ADR-0130 D4 / option B, #15006] The envelope unwrap and the object
+      // read are `artifactObjectNames` — one of this package's four reads of a
+      // PACKAGE-OWNED collection, and the only one whose loss is non-fatal: with
+      // the flattened top level gone this inventory went permanently EMPTY, so
+      // `os dev` stopped naming a newly added *.object.ts and every recompile
+      // read as all-green. The file read and the `null`-on-failure contract stay
+      // here; the seam is what the acceptance probe can call.
       const readArtifactObjects = (): Set<string> | null => {
         try {
-          const raw = JSON.parse(fs.readFileSync(opts.artifactPath, 'utf8'));
-          const meta = raw?.metadata ?? raw?.data?.metadata ?? raw;
-          const objects = Array.isArray(meta?.objects) ? meta.objects : [];
-          return new Set(
-            objects
-              .map((o: any) => o?.name)
-              .filter((n: any): n is string => typeof n === 'string'),
-          );
+          return new Set(artifactObjectNames(JSON.parse(fs.readFileSync(opts.artifactPath, 'utf8'))));
         } catch {
           return null;
         }