Merge remote-tracking branch 'origin/main' into claude/issue-14141-hook-selftest-deps-comment

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/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);
 });