fix(cli): serve --no-server with OS_MIGRATE_AND_EXIT=1 provisions the server boot's table set

[objectstack-fleet]

Fixes #22202
Clause-②: no

What was wrong

os serve composed createRestApiPlugin only under flags.server. That plugin's init() registers sys_import_job through the manifest service (packages/rest/src/rest-api-plugin.ts), and schema sync creates tables only for the objects registered in that boot. So serve --no-server with OS_MIGRATE_AND_EXIT=1 created one table fewer than the same config's server boot.

Reproduced first (H1) on origin/main fbcbcf12 with examples/app-todo. Each run used a fresh SQLite file and OS_MIGRATE_AND_EXIT=1; --no-server was the only difference.

run	plugins	tables	difference
server boot	39	70
--no-server	36	69	sys_import_job, and nothing else

The card measured 113 against 114 on cloud's control-plane config, with the same single difference. The cloud report it cites was not readable from this session (see Acceptance notes), so that number is the card's, not re-read here.

What changed

packages/cli/src/commands/serve.ts now composes the REST API plugin on every boot. Only the dispatcher and the no-auth refusal ride flags.server. On a server boot the kernel.use sequence is unchanged: the no-auth refusal, then REST, then the dispatcher.

After the fix, with the same config and procedure:

run	plugins	tables	difference
server boot	39	70
--no-server	37	70	none

With no HTTP server, RestApiPlugin.start() mounts nothing and prints one warn: RestApiPlugin: HTTP Server service 'http.server' not found. REST routes skipped. About a dozen service plugins on that path already do the same: in the same --no-server boot log, storage, settings, sharing, auth, i18n, marketplace and api-trigger each print a "no HTTP server, routes not registered" line.

Where the registration lives, and why it did not move (H3)

The PM's lean was to move sys_import_job to the plugin that owns its neighbouring @objectstack/platform-objects/audit objects, or to the boot path that registers platform objects on every boot. I measured both:

• The neighbours have no common owner. Each one is registered by the plugin that consumes it: sys_job / sys_job_run by JobServicePlugin, sys_job_queue by QueueServicePlugin, sys_notification by MessagingServicePlugin, sys_attachment by StorageServicePlugin, and sys_email / sys_email_template by EmailPlugin. RestApiPlugin already follows that pattern for sys_import_job; its own comment says the REST plugin owns the import feature, so it owns this object.
• serve composes those owners whatever the flag, and without a listener they only skip their routes. So the listener-independent home is the owner itself, composed on every boot. This is the claim's second option: register it from the serve path on every boot.
• The every-boot platform path is PlatformObjectsPlugin in packages/platform-objects. It belongs to another lane, and the order makes a move there a stop-and-report. It would also change the owning manifest. sys_import_job rides com.objectstack.rest.api with scope: 'system' and defaultDatasource: 'cloud', and ObjectQL.resolveDatasourceBinding routes an object by its owning package's defaultDatasource. That is why PlatformObjectsPlugin keeps a separate manifest for the activation ledger. Keeping the owner keeps routing and ownership unchanged.
• A new @objectstack/rest export for the object half would widen the public surface, contrary to Clause-②: no. It would also either break every other composer of createRestApiPlugin (plugin-dev, the verify harness, embedders) or leave two registrars.

Nothing registers it twice. It has one registrar, RestApiPlugin.init(), composed once per boot.

The other flag-gated plugins (H4)

serve composes three plugins only under --server. Only the REST plugin registers an object:

• createRestApiPlugin registers sys_import_job (one manifest registration). This PR fixes it.
• createDispatcherPlugin registers nothing: its init() is a no-op ("Consumer-only plugin — no services registered"), and the file never reads the manifest service.
• HonoServerPlugin registers nothing: zero manifest reads.

After the fix the table sets are equal on both examples/app-todo and the pin's fixture, so no other object is missing.

H5 and docs

The "refuse loudly" fallback is not used, because H3 found a home. No docs edit is owed: cli.mdx's "Skip HTTP server (kernel only)" and "Toggle HTTP server plugin" stay true, since --no-server still adds no HTTP server plugin and no dispatcher.

The pin

packages/cli/test/serve-migrate-exit-schema-parity.integration.test.ts boots os serve twice on one fixture config, each run on a fresh SQLite file with OS_MIGRATE_AND_EXIT=1. It asserts:

• control: both runs exit 0 and print the migrate path's completion line;
• control: the server boot's table set contains the fixture's table and sys_import_job;
• the --no-server table set equals the server boot's.

Tier: integration. The file spawns the CLI, so it runs in pnpm test's integration project on every PR (Test Core), not in the nightly. Locally the file took 22s.

Ablation

I put the REST composition back under flags.server with scripts/ablation-replace.mjs, changing try { to if (flags.server) try { at the createRestApiPlugin import. The anchor went 1 → 0 and the blob 6102920f → 62abf481. The pin spawns bin/run-dev.js, which runs serve.ts from src/ through tsx, so the mutation reached the code under test with no build.

The equality went red and both controls stayed green:

AssertionError: expected [ 'parity_task', 'sys_account', …(66) ] to deeply equal [ 'parity_task', 'sys_account', …(67) ]
-   "sys_import_job",
Tests  1 failed | 2 passed (3)

After the restore, the blob equals HEAD's (6102920f), and both git diff HEAD and git status --porcelain are empty.

Verification, at f0a27d66

• The pin: 3 of 3 passed. That run was at f2264e62; f0a27d66 adds only the changeset.
• @objectstack/cli, --project unit: 264 of 264 files and 3886 tests passed (262 files on the first run; the 2 published-subpath-* pins needed packages/cli/dist and passed once it was built), plus 29 skipped. test/vitest-tiers-partition.test.ts passed.
• @objectstack/cli, --project integration: 94 of 94 files and 903 tests passed, 2 skipped (exit 0). This was run locally because the diff touches the serve boot path and adds an integration-tier file.
• @objectstack/cli typecheck: exit 0. The new test file is in the tsconfig.test.json program (--listFiles, 1 hit) and adds no error; check:test-typecheck reports the 28 existing ledgered errors held.
• @objectstack/rest tests: 262 of 262 files and 4938 tests passed; typecheck exit 0. The package is unchanged; the order named it.
• pnpm lint (full, eslint . --no-inline-config): exit 0.
• The 67 derived gate commands (dispatch-gates.mjs --commands, the same set the order listed): all exit 0. Four of them first answered PREREQUISITE NOT MET (check:dual-build-cjs-loads, check:i18n, check:i18n-coverage and check:i18n-walk-parity), and each was re-run green after the build. dispatch-gates --ran: 67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN.

Acceptance notes

• One composition changes. A config that puts its own HonoServerPlugin in plugins and runs --no-server now gets the REST routes on that server. I measured a fixture of that shape on HEAD and under the ablation above. GET /api/v1/discovery went from 404 to 200, and GET /api/v1/data/OBJECT from 404 to 401 (anonymous access is denied). /api/settings (200) and /api/v1/auth/get-session (401) answered the same in both, so those plugins already mounted on that server. No config in this repo has that shape. Cloud's measured boot differs by three plugins (Hono, REST, dispatcher), so it composes no Hono of its own. The no-auth boot refusal stays keyed on --server, as before.
• --no-server boots now print one more warn line: the REST plugin's "no HTTP server" line.
• NOT MEASURED: the cloud dev report the card cites (objectstack-ai/cloud#2274, comment 6053481678). This session has no access to objectstack-ai/cloud: REST answered 403, and add_repo was refused.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os serve (command, 31 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 28 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6729e107e806b148d809e42b62e7fc0233d3d324 → packageMentionDocs.