fix(cli): a config-booted app keeps its module code — action handlers reach the engine again (#4095)

[os-zhuang]

Closes #4095.

The loss

os serve <config> calls createStandaloneStack(), which reads dist/objectstack.json and returns a ready-made AppPlugin for the app. That satisfied serve's "does the host already wrap itself?" guard, so the new AppPlugin(config) built from the loaded module — the only one carrying the module's onEnable — was skipped. A JSON artifact cannot hold a function, so the app booted with all of its metadata and none of its code.

Two probes nail it. First, what createStandaloneStack() actually returns once the artifact resolves:

PLUGINS: 4
 - com.objectstack.runtime.default-datasource   isApp=false
 - com.objectstack.metadata                     isApp=false
 - com.objectstack.engine.objectql              isApp=false
 - plugin.app.com.example.todo   ctor=AppPlugin  isApp=true
   bundle.onEnable = undefined      ← the hook that registers the handlers
   bundle.actions  = 8              ← all eight declarations

Second, serve at the branch that discards it:

[PROBE] hasAppPluginAlready=true  configHasMetadata=true  config.onEnable=function

The hook survives the entire config chain — mod.default || mod, the named-export preservation, the docs graft, both mergeBootConfig calls — and is then dropped by the guard. Exactly the observed split: metadata survives, code does not.

examples/app-todo is correctly authored — it declares target: 'completeTask', registers todo_task:completeTask, and exports onEnable. The ADR-0110 D5 inventory had been naming all eight actions since #4012 made boot warnings visible, and it was right.

#4110 has since landed on this same seam from the other side, and its own comment corroborates the diagnosis — "the artifact path never hit it only because createStandaloneStack appends ITS AppPlugin after the engine". It fixed the ordering; the code loss is untouched by it (see "Re-verified against the new base" below).

The fix

Serve grafts the module's executable members onto the app bundle already registered, instead of dropping them along with the wrap.

• Only what AppPlugin executes travels — onEnable and the functions map that string-named hook/job handlers resolve against. onDisable is deliberately excluded: it is declared in packages/spec but grep finds no kernel, runtime or service that ever calls it, so grafting it would wire a hook nothing runs.
• The artifact stays the metadata source of truth. Neither side is a superset — the artifact carries compile-time enrichment the config never has (ADR-0046 packaged docs, which serve already grafts the other way), so this is a graft, not a swap. Code only; never metadata.
• Targeting is by manifest.id, so a host composing several AppPlugins can never have one app's handlers attached to another. With no id to match it falls back to the single app bundle present, and refuses rather than guess when there are several.
• A bundle's own value always wins, so a host that wrapped itself on purpose is untouched.
• Orphaned code is now loud. A config whose hooks find no bundle gets a boot warning naming the consequence ("they 404 at dispatch") instead of vanishing — that silent drop is what hid this for so long.

isAppPluginLike is shared between the guard and the graft, so the decision to skip the wrap and the compensation for skipping it cannot drift apart.

Verification — the user-visible thing actually works

Live HTTP against a real examples/app-todo boot:

	before	after
POST /api/v1/actions/todo_task/complete_task	404 RESOURCE_NOT_FOUND — Action 'complete_task' on object 'todo_task' not found	{"success":true}
POST …/export_csv	same 404	{"success":true,"data":"subject,status,priority,…\nLearn ObjectStack,completed,…"} — real seeded rows
[action-governance] boot warning	1, naming all 8	0

The intermediate state was informative too: with an empty body the handler returned 400 VALIDATION_ERROR — Update requires an ID, i.e. the failure moved from the router into the handler's own logic.

Tests

• 14 unit cases on the graft, weighted toward the refusals — id mismatch, ambiguity, never-overwrite, metadata-must-not-travel, onDisable-must-not-travel, and the degenerate inputs a boot can hand it.
• 1 end-to-end case boots a real stack through bin/run-dev.js with a fixture whose action is executable only if onEnable ran, and asserts the inventory reports nothing. It also asserts the boot reached its banner, so "no warning" cannot pass vacuously. It uses the shared test/helpers/serve-process.ts harness fix(cli,core,metadata,runtime): the platform boots with no application — os serve no longer needs a compiled artifact (#4085) #4110 extracted rather than carrying a second copy.

Its os compile step is retained, with its justification inverted: it was originally a workaround for config-boot being unable to start without an artifact (#4085, now fixed), and it is kept because the artifact is what makes createStandaloneStack() contribute the artifact-derived AppPlugin this regression is about. Without it, serve wraps the config directly, onEnable runs for the trivial reason, and the test would pass while exercising nothing.

Re-verified against the new base

main moved by 12 commits mid-review (#4110, #4133, #4117, #4120, #4114, #4136 …), including two that touch this exact area, so the whole thing was re-checked rather than assumed:

• Merged main in at 001c01e.
• The bug is still live. With packages/cli/src/commands/serve.ts taken verbatim from origin/main, the e2e fails with the action's handler went unregistered. fix(cli,core,metadata,runtime): the platform boots with no application — os serve no longer needs a compiled artifact (#4085) #4110 fixed the plugin ordering; the code loss is a different branch of the same if, and remains.
• Full CLI suite 88 files / 909 tests green; eslint src clean; check:wildcard-fallthrough green (7 yielding / 0 ratcheted / 5 exempt).

I earlier carried a two-line fix here for the wildcard guard that was failing on main — that is now dropped: #4133 fixed the same stale MOUNTS entry independently and better (it records why the storage twin disappeared), so the merge takes main's version and my commit contributes nothing. Nothing in this PR touches scripts/ any more.

Relationship to #4085 — checked, and they were not the same bug

I verified this before #4085 was fixed: os serve <config> could not boot without dist/objectstack.json, and that reproduced unchanged with this fix applied — a separate defect on the other side of the same fork. #4110 has since fixed it, from the ordering angle, which confirms the split. The verdict and the lead I left are on #4085.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 30, 2026 11:30am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli.

18 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/cli)
• content/docs/api/client-sdk.mdx (via @objectstack/cli)
• content/docs/api/data-flow.mdx (via @objectstack/cli)
• content/docs/api/environment-routing.mdx (via @objectstack/cli)
• content/docs/api/error-catalog.mdx (via @objectstack/cli)
• content/docs/automation/hook-bodies.mdx (via packages/cli)
• content/docs/deployment/backup-restore.mdx (via @objectstack/cli)
• content/docs/deployment/cli.mdx (via @objectstack/cli)
• content/docs/deployment/self-hosting.mdx (via @objectstack/cli)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/cli)
• content/docs/kernel/runtime-services/index.mdx (via packages/cli)
• content/docs/permissions/authentication.mdx (via @objectstack/cli)
• content/docs/plugins/packages.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/cli)
• content/docs/releases/implementation-status.mdx (via @objectstack/cli)
• content/docs/releases/v16.mdx (via @objectstack/cli)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

Blocked on a red main, not on this diff. The ESLint check is failing, but the failing step inside that job is not ESLint — it is the new wildcard fall-through guard:

✗ wildcard fall-through guard (#4116)

  packages/adapters/hono/src/index.ts:all `${prefix}/storage/*`
    DECLARED but not found by the scan. Moved, renamed or deleted? Update MOUNTS.

Verified on pristine origin/main with this branch nowhere in the picture — same single failure:

git worktree add /tmp/main-check origin/main
cd /tmp/main-check && node scripts/check-wildcard-fallthrough.mjs
#   ✗ wildcard fall-through guard (#4116)  →  1 problem(s)

Cause — a merge-order collision between two landed PRs

• fix(runtime,hono,plugin-dev): 退役 dispatcher 的 /storage bridge —— 它从来没按契约调用过 storage (#4087) #4112 (4be9d99) retired the /storage dispatcher bridge, deleting the app.all(prefix + '/storage/*') mount. packages/adapters/hono/src/index.ts:351 now carries a comment describing the removal.
• chore(tooling): enumerate namespace-claiming wildcard mounts and require each to be classified (#4116) #4122 (3df8819) landed after it and added scripts/check-wildcard-fallthrough.mjs, whose MOUNTS table still declares that mount at line 158:

'packages/adapters/hono/src/index.ts:all `${prefix}/storage/*`': {
  ratchet: '#4117 — terminal, same shape as #4088; adapter has no in-repo consumer',
},

Each was green on its own base; together the declaration is stale. Since the guard runs on every PR, this currently blocks all of them, not just this one.

Why I have not fixed it here

The remedy is the two-line deletion the guard's own message asks for, but it is in another change's guard and there is a real choice behind it — drop the stale MOUNTS entry, or have the guard tolerate a declared-then-deleted mount rather than fail. That belongs to whoever owns #4116/#4117, so I am not making that call inside an unrelated CLI fix. Happy to push the one-line MOUNTS deletion if that is the wanted shape — just say so.

This branch has main merged in as of 6a381db, and everything under this PR's own scope is green against it: 87 files / 906 tests in @objectstack/cli, eslint src clean, and the end-to-end proof re-verified (complete_task → {"success":true}).

---

Generated by Claude Code