Skip to content

Commit 73256b7

Browse files
committed
docs(runtime): the ordering note in createStandaloneStack describes the order the kernel actually resolves (#4131)
The comment on `defaultDatasourcePlugin`'s slot claimed the position was load-bearing — "MUST precede ObjectQLPlugin: its start() connects the default driver … ObjectQLPlugin.start() runs boot schema-sync right after". Both halves are wrong, and reading the slot as a guarantee is how #4085 happened: - the connect happens in `init()`, not `start()`; - the position cannot deliver that order anyway. `DefaultDatasourcePlugin` declares a hard dependency on ObjectQL, so `resolveDependencies` HOISTS ObjectQLPlugin ahead of it. Measured on a real serve boot: `com.objectstack.engine.objectql` inits at #10, `com.objectstack.runtime.default-datasource` at #16 — the reverse of what the slot reads as. What actually orders them is the phase split (Phase 1 completes before any `start()`) plus that declared dependency — the contract already documented on the plugin itself, under its "Ordering — phase, not list position" note, which records the no-tables boot that taught it to us. This comment now points there instead of contradicting it two files away. Comment only; no behaviour changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ve9HidCGRGtS2UjNPUGHSV
1 parent 857a6cf commit 73256b7

2 files changed

Lines changed: 23 additions & 3 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
---
3+
4+
Comment-only: correct the plugin-ordering note in `createStandaloneStack`. No
5+
package behaviour changes, so this releases nothing.

packages/runtime/src/standalone-stack.ts

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -306,9 +306,24 @@ export async function createStandaloneStack(config?: StandaloneStackConfig): Pro
306306
stampSearchPinyinEnabled(artifactBundle?.i18n);
307307

308308
const plugins: any[] = [
309-
// MUST precede ObjectQLPlugin: its start() connects the default driver
310-
// through the datasource connection service, and ObjectQLPlugin.start()
311-
// runs boot schema-sync right after — the driver has to exist by then.
309+
// This position buys NOTHING, and reading it as an ordering guarantee is
310+
// how #4085 happened. The kernel resolves both init and start order from
311+
// the plugin dependency graph, and `DefaultDatasourcePlugin` declares a
312+
// hard dependency on ObjectQL — which HOISTS ObjectQLPlugin ahead of it
313+
// (measured on a serve boot: `com.objectstack.engine.objectql` inits
314+
// 6 slots BEFORE `com.objectstack.runtime.default-datasource`), the exact
315+
// opposite of what this slot looks like it is asking for.
316+
//
317+
// What actually makes the driver exist before boot schema-sync is the
318+
// PHASE split, not this list: the datasource plugin connects in `init()`
319+
// (Phase 1 completes before ANY `start()` runs) and depends on ObjectQL
320+
// so ITS init registers the engine first. That contract, and the earlier
321+
// no-tables boot that taught it to us, are documented on the plugin
322+
// itself — see the "Ordering — phase, not list position" note in
323+
// `default-datasource-plugin.ts`. Order requirements belong THERE, next
324+
// to the code the kernel enforces them from; a comment on an array index
325+
// cannot enforce anything. (#4131 tracks making the AppPlugin end of this
326+
// contract enforced rather than conventional.)
312327
defaultDatasourcePlugin,
313328
new MetadataPlugin({
314329
// Source-file scanner OFF — declarative metadata is loaded

0 commit comments

Comments
 (0)