Merge origin/main into claude/issue-23558-ceremony-dialect-resolver

Claude-Session: https://claude.ai/code/session_01Q9PZ5Pzqcus4woVvTZwWNU
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/23430-grant-permission-set-id-retired.md

@@ -18,13 +18,13 @@ FROM → TO:
 
 - `sys_user_permission_set.permission_set_id` → `permission_set`, the machine name of the set the grant holds. A seed row or data-door write that still carries `permission_set_id` is refused with `400 INVALID_FIELD`. Fix: delete the key and name the set, `{ user_id, permission_set: '<set name>', organization_id }`.
 - The unique index (`user_id`, `permission_set_id`, `organization_id`) and the (`permission_set_id`) index → one unique index on (`user_id`, `permission_set`, `organization_id`), declared `unique: 'organization'`: its organization key part is NULL-safe (ADR-0120 D3), so it refuses a second grant of one set to one user in one organization AND a second platform-wide grant (organization NULL), for every writer and every write path — batches, multi-row updates, concurrent writes and raw SQL included. The data doors answer `409 UNIQUE_VIOLATION` (the engine throws `DuplicateRecordError`, `DUPLICATE_RECORD`). Fix: keep the grant that exists; to change it, update that row.
-- The boot-time grant-name backfill (`runOneTimeGrantPermissionSetNameBackfill`, the `sys_migration` entry it recorded at `kernel:bootstrapped`) → `os migrate organization-ownership --apply`. Its verified rewrite names every grant from the physical `permission_set_id` column by raw SQL, verifies each name against the security catalog, and its `column-drops` step then drops the column through the schema-drift ceremony (schema sync is additive, so an undeclared column stays until it is dropped). Fix: run the ceremony on every database upgraded from a release before the `permission_set` column existed, then restart the server: the boot's organization-administrator sweep revokes, by name, a newly named grant whose pair no longer qualifies, and a server left running across `--apply` serves it until then.
+- The boot-time grant-name backfill (`runOneTimeGrantPermissionSetNameBackfill`, the `sys_migration` entry it recorded at `kernel:bootstrapped`) → the v18 ceremony: plan it with `os migrate organization-ownership --out plan.json`, review the file it writes, then run `os migrate organization-ownership --apply --backup-taken --plan-file plan.json`. Its verified rewrite names every grant from the physical `permission_set_id` column by raw SQL, verifies each name against the security catalog, and its `column-drops` step then drops the column through the schema-drift ceremony (schema sync is additive, so an undeclared column stays until it is dropped). Fix: run the ceremony on every database upgraded from a release before the `permission_set` column existed, then restart the server: the boot's organization-administrator sweep revokes, by name, a newly named grant whose pair no longer qualifies, and a server left running across `--apply` serves it until then.
 
 On a 17.x database every grant names nothing until `--apply` names it, so between the first v18 boot and `--apply` no grant confers anything, the platform administrator's included.
 
 What else changes:
 
-- `os migrate organization-ownership --plan` reports a `grants` block on `sys_user_permission_set`, keyed like the new index (a NULL organization keyed with NULL):
+- The plan run, `os migrate organization-ownership --out plan.json`, reports a `grants` block on `sys_user_permission_set`, keyed like the new index (a NULL organization keyed with NULL):
   - `duplicates`: groups of named grants holding one set for one user in one organization. `--apply`'s `column-drops` step does not drop `permission_set_id` while one group remains.
   - `rewriteCollisions`: legacy grants whose derived name their user already holds in the same organization. `--apply`'s rewrite names none of them and blocks, naming both ids.
   - On a database without the `permission_set` column it counts zero and names the remedy (boot this release once), instead of refusing the plan.

.changeset/23513-grant-remedy-plan-file.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/plugin-security': patch
+'@objectstack/spec': patch
+---
+
+fix(plugin-security,spec): the unnamed-grant boot line and the `ups-permission-set-id-column-retired` upgrade entry name the reviewed-plan ceremony, `--out plan.json` then `--apply --backup-taken --plan-file plan.json`, instead of a bare `--apply` the CLI refuses (ADR-0131 D10)
+
+Clause-②: no
+
+`os migrate organization-ownership --apply` refuses a run without `--plan-file`, the file a plan run wrote and the operator reviewed. Two remedy texts still told the operator to run `--apply` alone, which answers `plan-file-required` and writes nothing:
+
+- `@objectstack/plugin-security`: the `kernel:bootstrapped` catalog reference report's error line for grants that name no permission set (`permission_set` empty).
+- `@objectstack/spec`: the `replacement` of the ADR-0087 entry `ups-permission-set-id-column-retired`, the row the upgrade guide prints for the retired `sys_user_permission_set.permission_set_id`.
+
+Both now name the two steps: plan first, `os migrate organization-ownership --out plan.json`, review the file it writes, then `os migrate organization-ownership --apply --backup-taken --plan-file plan.json`, which executes that plan; restart afterwards. The ceremony itself is unchanged: its rewrite names each legacy grant from the retired id, and its column-drops step drops the two retired indexes and then the column. Only the text changes; the line's level, its fields and the entry's `id` are as they were.

.changeset/23573-serve-no-storage-loud.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): a production `os serve` of a host config that resolves no storage says so before any plugin starts, and refuses to boot when its auth service needs a driver
+
+Clause-②: no
+
+A host config (one whose `plugins` hold plugin instances) served in production with no recognized `OS_DATABASE_URL`, no `--dev` and no plugin named like a driver declares no default datasource. Nothing said so.
+
+- **Before.** The boot went on and died when `AuthPlugin` started: `✗ Plugin com.objectstack.auth failed to start - rollback complete: [ObjectQL] No driver available for object 'sys_organization'`. Before that line, objectql logged `ERROR sys_metadata could NOT be read at boot`, whose fix read `check the datasource behind sys_metadata — connection, credentials, and that the table exists`, for a datasource the operator never declared. No line named `OS_DATABASE_URL` or `--dev`. `examples/app-showcase` under a bare `os serve` took this path.
+- **After, when the auth service runs under the `single` tenancy posture (the default) and no plugin registered a driver by the end of plugin init.** The boot is refused before any plugin starts, exit 1, with `✖ This production serve has no storage: …` and three fixes: set `OS_DATABASE_URL` (for example `file:./data/app.db`, or a `postgres://` or `mysql://` URL), mount a storage driver in the stack's `plugins` (for example `new DriverPlugin(driver)` from `@objectstack/runtime`), or run with `--dev`. Neither of the two lines above prints. Every configuration refused here failed to boot before this change.
+- **After, when no driver is registered and the auth service does not need one at start** (no auth composed, as under `--no-server --preset minimal`, or a walled tenancy posture): one `⚠ No storage: …` line names the same fixes, and the boot goes on as before. A plugin that registers a driver in its `start()`, such as a module's `onEnable`, still works.
+- **When a plugin registers a driver during init**, under any name, nothing is printed and nothing changes.
+
+`os start`, a standalone (non-host) config, `--dev` and any recognized `OS_DATABASE_URL` take other paths and are unchanged.

.changeset/23618-approval-title-family-served-fields.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/plugin-approvals': patch
+---
+
+fix(plugin-approvals): the inbox's referenced-record titles (`payload_display`) and the record-lock refusal's title are served only from fields the caller may read
+
+Clause-②: no
+
+- **Referenced-record titles follow the reader's field-level security on the referenced object.** `listRequests` and `getRequest` now pick each `payload_display` title from the referenced record as served to the reading caller: the same answer the payload snapshot and `record_title` are narrowed by (readable, and not masked for that caller), asked for the referenced object, once per object per read. A display field the reader may not read on the referenced object, or is served masked, gives that key no display value, so the snapshot's stored id stands, as it already does for a deleted referenced record. A title-eligible field the reader may read still names the record, and a reader who may read the display field gets the same title as before.
+- **The `RECORD_LOCKED` refusal names the record only from what the writer may read.** The per-record refusal sentence takes its title from the record as served to the refused writer, asked with the writer's own execution context. When the writer may not read the display field, or is served it masked, the sentence names the object's label alone (`This Opportunity is locked …`), as it already does for a record with no title; it never names the id. A writer who may read the field is told the title as before. The code (`RECORD_LOCKED`) and status (409) are unchanged.
+
+A patch: a narrowing of served values only. Nothing is granted, and no schema, route, error code, translation key or export moves. With no field-visibility source wired, every title is served as before.

packages/cli/src/commands/serve.ts

@@ -3089,6 +3089,13 @@ export default class Serve extends Command {
       // discards as already-registered.
       // [#15006] Same seam, same reason — see the ObjectQL gate above. The
       // driver-provider duck-typing moved into it with the read it guards.
+      //
+      // [#23573] Whether this step declared NOTHING (production, no URL, no
+      // driver plugin by name). Only recorded here: this step cannot tell a
+      // boot that fails anyway from one whose own plugin registers a driver
+      // the name test misses, so the verdict waits for the no-storage boot
+      // guard at the end of Phase 1 (registered last, before runtime.start()).
+      let productionResolvedNoStorage = false;
       if (shouldAutoRegisterStorageDriver(config, plugins)) {
          const databaseUrl = process.env.OS_DATABASE_URL;
          const driverType = resolveDriverType(process.env.OS_DATABASE_DRIVER, databaseUrl);
@@ -3136,6 +3143,8 @@ export default class Serve extends Command {
              // every other kind AND the dev-default `:memory:` store). The ONE
              // provision, shared with the standalone boot below.
              await provisionTelemetry(resolution.sqliteFilePath);
+           } else {
+             productionResolvedNoStorage = true;
            }
          } catch (e: any) {
            // "declared ≠ enforced" guard (#3276-class): a selection the CLI
@@ -5108,6 +5117,68 @@ export default class Serve extends Command {
       // published banner surface on every boot to report a thing an operator
       // cannot act on.
 
+      // ── No-storage boot guard (#23573) ─────────────────────────────
+      // Step 2 recorded that this production boot declared no storage. Whether
+      // that is fatal is only known once every plugin's init() has run, since a
+      // stack plugin the name test missed may register a driver there. This is
+      // the LAST plugin registered, so its init() runs after every other init()
+      // and before any start() (resolvePluginOrder keeps insertion order; no
+      // plugin names this one as a dependency). It reads the one map ObjectQL
+      // adopts `driver.*` services from at its start(), plus any driver the
+      // engine already holds.
+      //   • a driver is there                ⇒ nothing to say.
+      //   • none, and the auth service runs under the 'single' posture ⇒ refuse
+      //     before any start(). AuthPlugin.start() creates the Default
+      //     Organization there, which needs a driver, and no driver can arrive
+      //     before it: AppPlugin orders ObjectQL and auth ahead of every stack
+      //     plugin, so a driver registered in any start() comes too late.
+      //     Without this, the boot died there with a driver error, after an
+      //     objectql ERROR naming a datasource nobody declared.
+      //   • none otherwise                   ⇒ ONE line, and the boot goes on.
+      //     Worded as of the end of init, because a start() (a module's
+      //     onEnable) may still register a driver and some such stacks boot.
+      // ⛔ Not `trackPlugin`ed, for the announcer's reason above.
+      if (productionResolvedNoStorage) {
+        // ONE list, rendered as the refusal's bullets and as the line's sentence.
+        const noStorageRemedies = [
+          'set OS_DATABASE_URL (e.g. file:./data/app.db, or a postgres:// or mysql:// URL)',
+          "mount a storage driver in the stack's plugins (e.g. new DriverPlugin(driver) from @objectstack/runtime)",
+          'run with --dev (an in-memory SQLite store, for development)',
+        ];
+        await kernel.use({
+          name: 'com.objectstack.cli.no-storage-boot-guard',
+          version: '1.0.0',
+          init: async (ctx: any) => {
+            const services: Map<string, any> = ctx.getServices();
+            const engine = services.get('objectql');
+            const hasDriver = [...services.keys()].some((name) => name.startsWith('driver.'))
+              || (typeof engine?.getDefaultDriverName === 'function'
+                && engine.getDefaultDriverName() !== undefined);
+            if (hasDriver) return;
+            if (services.has('auth') && services.get('tenancy')?.posture === 'single') {
+              restoreOutput();
+              console.error(chalk.red(
+                '\n  ✖ This production serve has no storage: no recognized OS_DATABASE_URL declared a\n'
+                + '    default datasource, and no plugin registered a storage driver by the end of plugin\n'
+                + "    init. The auth service runs under the 'single' tenancy posture, and its start()\n"
+                + '    creates the Default Organization, which needs a driver.\n\n'
+                + '    Fix one of:\n'
+                + noStorageRemedies.map((remedy) => `      • ${remedy}\n`).join(''),
+              ));
+              throw new Error(
+                'Refusing to boot: this production serve has no storage, and its auth service needs a '
+                + 'driver when it starts. Set OS_DATABASE_URL, mount a storage driver plugin, or run with --dev.',
+              );
+            }
+            console.warn(chalk.yellow(
+              '  ⚠ No storage: no recognized OS_DATABASE_URL, and no plugin registered a storage driver by '
+              + 'the end of plugin init, so objects have no store unless a plugin registers one when it '
+              + `starts. Fix: ${noStorageRemedies[0]}; ${noStorageRemedies[1]}; or ${noStorageRemedies[2]}.`,
+            ));
+          },
+        } as any);
+      }
+
       // Boot the runtime
       await runtime.start();
 

packages/cli/src/utils/organization-ownership-apply.test.ts

@@ -1980,7 +1980,7 @@ describe('ADR-0131 D10 --apply — the grant\'s retired id column (C7b, seat ans
     expect(idColumn()).toEqual([]);
   });
 
-  it('a second platform-wide grant (organization NULL) is a duplicate too: GROUP BY keys NULLs together, unlike the index', async () => {
+  it('a second platform-wide grant (organization NULL) is a duplicate too: GROUP BY keys NULLs together, as the index\'s NULL-safe organization key part does', async () => {
     await onlyTemplates(`('tpl_none', NULL, 'crm.none', 'en-US', 'x', 0, 'package')`, async () => {
       db.exec(`
         CREATE TABLE sys_user_permission_set (id TEXT PRIMARY KEY, organization_id TEXT, user_id TEXT,

packages/cli/src/utils/organization-ownership-grants.ts

@@ -59,7 +59,11 @@ export interface GrantRewritePlan {
   reasons: Record<UnnamedReason, string[]>;
 }
 
-/** The unique key of a grant; a NULL organization is one key, as the write door keys it. */
+/**
+ * The unique key of a grant; a NULL organization is one key, as the grant's
+ * `unique: 'organization'` index keys it (its organization key part is
+ * NULL-safe, ADR-0120 D3).
+ */
 export function grantKey(userId: string | null, name: string, organizationId: string | null): string {
   return JSON.stringify([userId, name, organizationId]);
 }

packages/cli/src/utils/organization-ownership-plan.ts

@@ -188,8 +188,9 @@ export interface MetadataConflict {
 /**
  * `sys_user_permission_set` (C7b): the populations the unique index on
  * (`user_id`, `permission_set`, `organization_id`) refuses, which the ceremony
- * reports and never deletes. A NULL organization is keyed with NULL, as the
- * write door keys it.
+ * reports and never deletes. A NULL organization is keyed with NULL, as that
+ * index keys it: it is declared `unique: 'organization'`, so its organization
+ * key part is NULL-safe (ADR-0120 D3).
  */
 export interface GrantKeyPlan {
   /** `absent` on a 17.x database this release has not booted against yet: nothing can be counted. */