Merge remote-tracking branch 'origin/main' into claude/issue-14195-workspace-cycle-gate

Author: claude

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

.changeset/email-sender-validated-at-configuration-time.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/plugin-email": patch
+---
+
+fix(plugin-email): judge the default sender where it is configured, and record a send rejected before delivery (#14318)
+
+Measured on a local rig with `OS_EMAIL_FROM="ObjectOS Local <noreply@localhost>"`,
+`OS_EMAIL_PROVIDER=log` and `OS_AUTH_REQUIRE_EMAIL_VERIFICATION=true`: the server
+booted clean, the first sign-up answered `200`, the UI said a verification email
+had been sent, and nothing had been. `EMAIL_REGEX` requires a dotted domain and
+correctly refuses `noreply@localhost` — but it refused it inside
+`normalizeMessage`, on the **first send**, which for a fresh deployment is the
+first user's sign-up. better-auth runs `sendVerificationEmail` through
+`runInBackgroundOrAwait`, which logs `Failed to run background task` and returns
+normally, so the account was created and the user was parked on a verify screen
+whose Resend repeated the whole sequence. `sys_email` held no row for any of it:
+the throw happened *before* the row insert, and every other failure shape in the
+service is a row at `status:'failed'`.
+
+Two changes, one per half.
+
+**The address is judged where it is configured.** `EmailServicePlugin.init()`
+now refuses a declared `defaultFrom` that no message could ever be sent from, so
+a deployment that names an unsendable sender fails its boot instead of failing
+every send — the same trade `resolveTransport` already makes for an SMTP
+provider with no host, and the error names the consequence and the fix
+(`OS_EMAIL_FROM` / `config.email.defaultFrom`). An **absent** sender is still
+accepted: callers that always pass `input.from` are a complete configuration,
+and `normalizeMessage` already refuses a send that has neither.
+
+The `mail` settings channel takes that method's opposite, stated trade — a save
+must not kill a running server — so an unsendable saved From address is
+**refused, the previous sender kept**, and the consequence stated at `error`.
+`error` and not `warn` because nothing looks broken afterwards: the save
+succeeds and the settings page shows the address the operator typed.
+
+**A send rejected before delivery now leaves a `sys_email` row.** The
+`normalizeMessage` window was the one path on which a send produced no record at
+all. It now writes `status:'failed'` with the reason, prefixed
+`rejected before delivery:` so the column distinguishes a message that never
+reached a transport from one an SMTP host refused. The envelope columns carry
+what the caller actually passed (never re-canonicalised — canonicalisation is
+what threw), `(none)` where the input named nothing, since `from_address` /
+`to_addresses` / `subject` are required. The row is safe by construction: both
+re-delivery paths — the `afterInsert` outbox drain hook and the boot outbox
+sweep — gate on `status === 'queued'`, so a rejection record can never be
+mistaken for an outbox entry. Persisting it is best-effort and never replaces
+the caller's error.
+
+Unchanged: `formatAddress`, `EMAIL_REGEX` and `normalizeMessage` keep their
+exact verdicts (the new `isSendableAddress` predicate shares the one regex, so a
+boot cannot pass a check the send path then fails), `send()` still throws on
+validation failure rather than answering `failed`, and the auth layer's
+propagation is as it was — `sendVerificationEmail` already rejects on both a
+throw and a returned `status:'failed'`, which is now pinned by a test.

.changeset/filesystem-loader-keyed-items.md

@@ -0,0 +1,29 @@
+---
+'@objectstack/metadata': patch
+---
+
+`FilesystemLoader` now implements `loadManyKeyed()`, so a metadata file whose
+body has no top-level `name` is no longer invisible to `MetadataManager.list()`.
+`loadMany()` globbed files and pushed bodies, discarding the path it had just
+read; the manager then fell back to keying by `body.name`, which drops every
+nameless body — an aggregated `defineView` container has none by design. That is
+the #14205 defect, unrepaired for this loader until now.
+
+The key is this loader's own name-to-path derivation — the basename minus
+extension, the same one `list()` reports — but only where that derivation is a
+bijection for the file: it sits directly under `ROOT/TYPE/` and carries an
+extension `findFile()` tries, so `findFile(type, key)` resolves back to that same
+file. Every other shape (a nested path, an extension-less file) keeps the
+previous behaviour verbatim: keyed by `body.name` when it has one, dropped when
+it has none. `list()` and `findFile()` disagree outside the flat shape — `list()`
+reports the bare basename for a nested file and `findFile()` cannot resolve it —
+so keying those by the basename would mint names `get()` and `exists()` cannot
+open, and two directories holding one basename would collide silently. Repairing
+the derivation itself is tracked separately.
+
+One deliberate consequence: a flat file whose `body.name` disagrees with its
+basename is now keyed by the basename. That is #14205's rule (identity is the
+key the store holds an item under, not `body.name`) applied to this loader, and
+it aligns `list()` with `listNames()` for that shape. `loadMany()`'s own
+signature and answer are unchanged; both methods now share one file walk so
+their bodies cannot drift.

.changeset/lint-test-typecheck-wiring.md

@@ -0,0 +1,32 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): wire `packages/lint`'s test layer into `check:test-typecheck`, so its 2,700-line rule pin file is actually type-checked (#14173)
+
+`packages/lint/tsconfig.json` excluded `**/*.test.ts` and `**/*.spec.ts`, and
+the package's `typecheck` script was a bare `tsc --noEmit` against that very
+config — so no gate anywhere read a lint test file with a type checker.
+`src/validate-expressions.test.ts` alone is ~2,700 lines built almost entirely
+out of compile-time and meta pins (the #5017 receiver scan, the
+`TRACKED_UNDECLARED_READS` shrink-only list, the residual-root table), and none
+of it was type-checked by anything: vitest transpiles through esbuild (types
+stripped, never resolved), so a wrong key or a signature drift in a pin's own
+scaffolding was caught by nobody.
+
+Onboarded by *wiring* to the mechanism #14062 (PR #14420) landed on
+(`scripts/check-test-typecheck.mts`), per the triage ruling on this card: a
+sibling `tsconfig.test.json` matching vitest's real module semantics
+(`module: esnext`, `moduleResolution: bundler`, `lib: ["ES2022"]`; strictness
+and `rootDir` untouched, inherited), named by `typecheck`. Measured (workspace
+closure built first): 6 residual errors over 2 files, all TS6059 (imports from
+`examples/app-showcase`, outside this package's `rootDir` — pre-existing,
+config-tier, not a lint defect), recorded EXACT and shrink-only in the new
+`test-typecheck-debt.json`.
+
+This is a CONVERSION of the coverage gate's existing `@objectstack/lint`
+TEST_DEBT entry (`errors: 16`), not a new debt-opening decision: the same
+authority that recorded the 16 now holds the residue one level finer, per file
+and per signature, and the coverage-gate entry is deleted as the graduation
+that pairing forces. No test file is edited — opening the ratchet is not the
+same job as paying it down.

.github/workflows/publish-smoke.yml

@@ -47,9 +47,18 @@
 # check (branch protection on main requires TypeScript Type Check, Build Core,
 # Test Core and Dogfood Regression Gate), so an absent one blocks nothing and is
 # simply invisible. resolve-guard turns that silence into an explicit red.
+#
+# "How long was publish broken?" is answered by walking the `publish-smoke /
+# packed-tarballs` commit-status history on the release-branch head, never by
+# scanning this workflow's run list, because the list interleaves the weekly
+# registry canary (schedule-triggered, unrelated to any release candidate)
+# with release-candidate smokes, and an unlabeled canary green reads as "the
+# RC smoke passed" (#14190 — a six-day outage misread from exactly that).
 
 name: Publish Smoke
 
+run-name: ${{ github.event_name == 'schedule' && 'Registry canary (published latest) — scheduled' || github.event_name == 'workflow_dispatch' && format('Publish smoke — manual dispatch on {0}', github.ref_name) || format('Packed-tarball smoke (release candidate) — after Release run {0}', github.event.workflow_run.head_sha) }}
+
 on:
   workflow_run:
     workflows: [Release]

docs/qa/platform-checklist/areas/cli.json

@@ -39,7 +39,7 @@
         {
           "clause": "--seed-admin provisions the FIXED well-known dev admin (admin@objectos.ai / admin123) loginable via the real auth endpoint, and the seed is idempotent — a later boot with a different --admin-password does NOT overwrite the existing account",
           "oracle": "api",
-          "verify": "login succeeds with the original credentials after the changed-password restart (flag contract: 'only acts on a zero-user DB, never overwrites an existing account')",
+          "verify": "login succeeds with the original credentials after the changed-password restart (flag contract: 'it acts only while no account holds the seed address and no local password login exists anywhere, never overwrites an existing account')",
           "evidence": "the two auth responses"
         },
         {
@@ -794,7 +794,7 @@
         ],
         "knownGaps": [
           "This item deliberately does NOT re-prove what two existing items already cover. The scaffold→install→validate→build→artifact-boot chain belongs to cli.scaffold-first-run (automated by .github/workflows/scaffold-e2e.yml); the console-on-a-populated-app half belongs to cli.dev-boot-contract, which drives examples/app-showcase. What is untested is the SEAM: the Console rendering against a freshly scaffolded BLANK project — one object and no seed data. Score only the seam; cite the two siblings for the halves.",
-          "A blank scaffold DOES have a loginable identity out of the box: `seed-admin` is default-ON in dev (commands/dev.ts: flags['seed-admin'] ?? true, 'Default: on (idempotent — only acts on a zero-user DB, never overwrites an existing account)'), so bare `objectstack dev` seeds admin@objectos.ai / admin123 on an empty DB and the banner prints the credentials. Clause 4 therefore scores whether the newcomer can COMPLETE the documented visual check with that identity, not whether one exists. Still do not import showcase credentials."
+          "A blank scaffold DOES have a loginable identity out of the box: `seed-admin` is default-ON in dev (commands/dev.ts: flags['seed-admin'] ?? true, 'Default: on (idempotent — it acts only while no account holds the seed address and no local password login exists anywhere, never overwrites an existing account)'), so bare `objectstack dev` seeds admin@objectos.ai / admin123 on an empty DB and the banner prints the credentials. Clause 4 therefore scores whether the newcomer can COMPLETE the documented visual check with that identity, not whether one exists. Still do not import showcase credentials."
         ]
       },
       "steps": [

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
   // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
       await stack.shutdown();
     }
   }, 60_000);
+
+  it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+    // The guard's census names `dropTable()` as immediate DDL: it runs
+    // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+    // the real driver over the real file — the deferral held back every
+    // CREATE/ALTER of the two cases above, and this DROP goes straight
+    // through. What #14126 changes is not the execution but its silence: the
+    // call is counted and named, and the run does not print "a plan writes
+    // nothing" over a table it dropped.
+    const before = await inspect();
+    expect(before.tables).toEqual(['defer_widget']);
+
+    let via = '';
+    const dropsATable: Plugin = {
+      name: 'com.example.drops-a-table-from-a-hook',
+      version: '1.0.0',
+      init: async (ctx: PluginContext) => {
+        ctx.hook('kernel:ready', async () => {
+          for (const [name, service] of ctx.getServices().entries()) {
+            if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+              via = name;
+              await service.dropTable('defer_widget');
+              return;
+            }
+          }
+          throw new Error('no driver.* service with dropTable() to drop through');
+        });
+      },
+    };
+
+    const stack = await bootSchemaStack({
+      jsonOutput: false,
+      databaseUrl: `file:${dbFile}`,
+      deferSchemaDdl: true,
+      projectRoot: dir,
+      // The artifact makes this a COMPOSED boot, which is what arms the guard.
+      composeHostStack: true,
+      extraPlugins: [composeForDeclarations(dropsATable)],
+    });
+    try {
+      const after = await inspect();
+      expect(via).not.toBe('');
+      // FORWARDED: the table is really gone.
+      expect(after.tables).not.toContain('defer_widget');
+      // COUNTED, on the guard's own surface…
+      expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+        { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+      ]);
+      // …and REPORTED in the notes the plan prints, with the claim withheld.
+      const notes = stack.composition.notes.join('\n');
+      expect(notes).toContain(
+        `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+      );
+      expect(notes).not.toContain('a plan writes nothing');
+    } finally {
+      await stack.shutdown();
+    }
+  }, 60_000);
 });