feat(kernel): add kernel:bootstrapped lifecycle anchor

kernel:ready handlers run sequentially in plugin-registration order, so a
handler that consumes data produced by a later-starting plugin (security
bootstrap seeds sys_position; the app plugin's seed loader inserts records)
races the very rows it needs. Add kernel:bootstrapped — fired after every
kernel:ready handler has settled but before kernel:listening (HTTP socket
open) — as the correct anchor for reconcile/backfill work. Both ObjectKernel
and LiteKernel trigger it; ordering is locked by tests in kernel.test.ts and
lite-kernel.test.ts. The sharing-rule boot backfill moves from kernel:listening
to kernel:bootstrapped (semantics-only).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017bJWtKmZ2mFpRFAmmmoeqe

Author: claude

.changeset/kernel-bootstrapped-anchor.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/plugin-sharing': patch
+---
+
+feat(kernel): add `kernel:bootstrapped` lifecycle anchor — the phase that fires after every `kernel:ready` handler has settled but before `kernel:listening` (HTTP socket open). `kernel:ready` handlers run sequentially in plugin-registration order, so a handler that consumes data produced by a later-starting plugin (e.g. the security bootstrap seeds `sys_position`; the app plugin's seed loader inserts records) would race the very rows it needs. `kernel:bootstrapped` is the correct anchor for reconcile/backfill work: every producer's ready handler has finished by the time it fires. Both `ObjectKernel` and `LiteKernel` trigger it. The sharing-rule boot backfill moves from `kernel:listening` to `kernel:bootstrapped` (semantics-only; behaviour unchanged).

content/docs/kernel/events.mdx

@@ -19,7 +19,8 @@ Triggered by the Kernel during bootstrap and shutdown:
 | Event | Description |
 | :--- | :--- |
 | `kernel:ready` | All plugins have successfully started. System is live. |
-| `kernel:listening` | Fired after every `kernel:ready` handler has completed (e.g. the HTTP server is accepting connections). |
+| `kernel:bootstrapped` | Fired after every `kernel:ready` handler has settled, before `kernel:listening`. The "all bootstrap + seed data is ready" anchor — use it for reconcile/backfill work that consumes data a later-starting plugin produces during `kernel:ready`. |
+| `kernel:listening` | Fired after every `kernel:ready` and `kernel:bootstrapped` handler has completed (e.g. the HTTP server is accepting connections). |
 | `kernel:shutdown` | Shutdown signal received. Plugins should clean up resources. |
 
 ### Listening to Kernel Events

content/docs/references/kernel/plugin-lifecycle-events.mdx

@@ -142,6 +142,7 @@ Plugin lifecycle event type
 ### Allowed Values
 
 * `kernel:ready`
+* `kernel:bootstrapped`
 * `kernel:listening`
 * `kernel:shutdown`
 * `kernel:before-init`

packages/core/src/kernel.test.ts

@@ -417,6 +417,24 @@ describe('ObjectKernel', () => {
             expect(kernel.getState()).toBe('stopped');
         });
 
+        it('fires kernel:ready → kernel:bootstrapped → kernel:listening in order', async () => {
+            const order: string[] = [];
+            const plugin: Plugin = {
+                name: 'lifecycle-order-plugin',
+                version: '1.0.0',
+                init: async (ctx) => {
+                    ctx.hook('kernel:listening', async () => { order.push('kernel:listening'); });
+                    ctx.hook('kernel:bootstrapped', async () => { order.push('kernel:bootstrapped'); });
+                    ctx.hook('kernel:ready', async () => { order.push('kernel:ready'); });
+                },
+            };
+
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+
+            expect(order).toEqual(['kernel:ready', 'kernel:bootstrapped', 'kernel:listening']);
+        });
+
         it('should trigger shutdown hook', async () => {
             let hookCalled = false;
 

packages/core/src/kernel.ts

@@ -363,6 +363,15 @@ export class ObjectKernel {
             this.logger.debug('Triggering kernel:ready hook');
             await this.context.trigger('kernel:ready');
 
+            // Phase 3.5: Trigger kernel:bootstrapped AFTER every kernel:ready
+            // handler has settled — the "all bootstrap + seed data is ready"
+            // anchor. Reconcile/backfill work that consumes data produced by a
+            // later-starting plugin's kernel:ready handler belongs here, not in
+            // kernel:ready (where handler order would race the data). See
+            // packages/spec/src/contracts/plugin-lifecycle-events.ts.
+            this.logger.debug('Triggering kernel:bootstrapped hook');
+            await this.context.trigger('kernel:bootstrapped');
+
             // Phase 4: Trigger kernel:listening hook AFTER all kernel:ready
             // handlers have completed. This is the cue for HTTP server
             // plugins to actually open the listening socket — by now every

packages/core/src/lite-kernel.test.ts

@@ -251,4 +251,24 @@ describe('LiteKernel with Configurable Logger', () => {
             await kernel.shutdown();
         });
     });
+
+    describe('Lifecycle event ordering', () => {
+        it('fires kernel:ready → kernel:bootstrapped → kernel:listening in order', async () => {
+            const order: string[] = [];
+            const plugin: Plugin = {
+                name: 'lifecycle-order-plugin',
+                init: async (ctx) => {
+                    ctx.hook('kernel:listening', async () => { order.push('kernel:listening'); });
+                    ctx.hook('kernel:bootstrapped', async () => { order.push('kernel:bootstrapped'); });
+                    ctx.hook('kernel:ready', async () => { order.push('kernel:ready'); });
+                },
+            };
+
+            kernel.use(plugin);
+            await kernel.bootstrap();
+            await kernel.shutdown();
+
+            expect(order).toEqual(['kernel:ready', 'kernel:bootstrapped', 'kernel:listening']);
+        });
+    });
 });

packages/core/src/lite-kernel.ts

@@ -77,6 +77,10 @@ export class LiteKernel extends ObjectKernelBase {
 
         // Trigger ready hook (route/middleware registration phase)
         await this.triggerHook('kernel:ready');
+        // Trigger bootstrapped hook — "all bootstrap + seed data is ready"
+        // anchor, strictly after every kernel:ready handler has settled and
+        // before any HTTP socket opens (see plugin-lifecycle-events.ts).
+        await this.triggerHook('kernel:bootstrapped');
         // Trigger listening hook (HTTP servers open their socket here —
         // strictly after every kernel:ready handler has completed).
         await this.triggerHook('kernel:listening');

packages/plugins/plugin-sharing/src/sharing-plugin.ts

@@ -308,10 +308,10 @@ export class SharingServicePlugin implements Plugin {
             bindRuleProvenanceStamp(engine, ctx.logger as any);
 
             // [#2926 ③] Reconciling existing rows against every rule is
-            // deferred to `kernel:listening` (below): seed data is loaded on
+            // deferred to `kernel:bootstrapped` (below): seed data is loaded on
             // `kernel:ready` (raced against a budget, and the AppPlugin's seed
             // hook is a *different* kernel:ready handler), so a backfill here
-            // would race the very records it must materialize. `kernel:listening`
+            // would race the very records it must materialize. `kernel:bootstrapped`
             // fires only after every kernel:ready handler has settled.
           } else {
             ctx.logger.warn('SharingServicePlugin: engine has no hook API — sharing rule auto-evaluation disabled');
@@ -397,17 +397,17 @@ export class SharingServicePlugin implements Plugin {
     // [#2926 ③] Materialize sharing grants for rows already present at boot —
     // notably SeedLoader-inserted seed records, whose write goes through the
     // isSystem short-circuit in the rule hooks and therefore never produces a
-    // `sys_record_share`. Runs on `kernel:listening` (Phase 4), after every
-    // `kernel:ready` handler — including the AppPlugin seed loader — has
-    // completed, so the reconcile sees the seeded rows. Idempotent: a runtime
+    // `sys_record_share`. Runs on `kernel:bootstrapped` — the anchor that fires
+    // after every `kernel:ready` handler (including the AppPlugin seed loader)
+    // has settled — so the reconcile sees the seeded rows. Idempotent: a runtime
     // write that already materialized a grant is reconciled to the same state.
-    ctx.hook('kernel:listening', async () => {
+    ctx.hook('kernel:bootstrapped', async () => {
       if (!this.ruleService) return;
       try {
         const rules = await this.ruleService.listRules({ activeOnly: true }, { isSystem: true } as any);
         await backfillRuleGrants(this.ruleService, rules, ctx.logger as any);
       } catch (err: any) {
-        ctx.logger.warn('SharingServicePlugin: boot rule backfill (kernel:listening) failed', { error: err?.message });
+        ctx.logger.warn('SharingServicePlugin: boot rule backfill (kernel:bootstrapped) failed', { error: err?.message });
       }
     });
   }

packages/spec/src/contracts/plugin-lifecycle-events.test.ts

@@ -6,9 +6,11 @@ describe('Plugin Lifecycle Events Contract', () => {
     it('should define all kernel event types', () => {
       // Compile-time check: verify the event map type is correctly shaped
       const events: Record<keyof Pick<IPluginLifecycleEvents,
-        'kernel:ready' | 'kernel:shutdown' | 'kernel:before-init' | 'kernel:after-init'
+        'kernel:ready' | 'kernel:bootstrapped' | 'kernel:listening' | 'kernel:shutdown' | 'kernel:before-init' | 'kernel:after-init'
       >, any> = {
         'kernel:ready': [],
+        'kernel:bootstrapped': [],
+        'kernel:listening': [],
         'kernel:shutdown': [],
         'kernel:before-init': [],
         'kernel:after-init': [150],

packages/spec/src/contracts/plugin-lifecycle-events.ts

@@ -20,7 +20,26 @@ export interface IPluginLifecycleEvents {
     'kernel:ready': [];
 
     /**
-     * Emitted AFTER all `kernel:ready` handlers have completed.
+     * Emitted AFTER every `kernel:ready` handler has completed, but BEFORE
+     * `kernel:listening` (so before any HTTP socket opens).
+     *
+     * This is the "all bootstrap + seed data has settled" anchor. Because
+     * `kernel:ready` handlers run sequentially in plugin-registration order,
+     * a handler cannot rely on data produced by a plugin that starts later
+     * (e.g. the security bootstrap seeds `sys_position`, the app plugin's
+     * seed loader inserts records) — reconcile/backfill work that consumes
+     * that data would race the very rows it needs. Do such work here instead:
+     * every producer's `kernel:ready` handler has finished by the time this
+     * fires. HTTP `listen()` is deliberately deferred one more phase to
+     * `kernel:listening` so late route registration still lands.
+     *
+     * Payload: []
+     */
+    'kernel:bootstrapped': [];
+
+    /**
+     * Emitted AFTER all `kernel:ready` and `kernel:bootstrapped` handlers
+     * have completed.
      *
      * Use this hook for actions that must happen *strictly after* every
      * other plugin has had a chance to register routes / services /