feat(core,egg): add V8 startup snapshot lifecycle hooks and APIs

Add snapshotWillSerialize/snapshotDidDeserialize lifecycle hooks and
snapshot-safe initialization patterns for V8 startup snapshot support.

## core changes
- Add `snapshotWillSerialize()` / `snapshotDidDeserialize()` to ILifecycleBoot
- triggerSnapshotWillSerialize: reverse order (LIFO, like beforeClose)
- triggerSnapshotDidDeserialize: forward order (FIFO), resumes lifecycle from configDidLoad
- Expose trigger methods on EggCore for build scripts

## egg changes
- Agent keepalive timer moved to configDidLoad via object literal boot hook
- Messenger/logger/unhandledRejection cleanup via protected snapshotWillSerialize/snapshotDidDeserialize methods
- Zero `if (this.options.snapshot)` guards — all handled by lifecycle structure
- New APIs: startEggForSnapshot(), buildSnapshot(), restoreSnapshot()
- loadFinished promise for snapshot build scripts

## Tests
- 16 core snapshot tests (hook ordering, async, error handling, lifecycle resume)
- 10 egg snapshot tests (agent keepalive, messenger, logger, unhandledRejection, APIs)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: killagu

packages/core/src/egg.ts

@@ -412,6 +412,24 @@ export class EggCore extends KoaApplication {
     this.lifecycle.registerBeforeClose(fn, name);
   }
 
+  /**
+   * Trigger snapshotWillSerialize lifecycle hooks on all boots in reverse order.
+   * Called by the build script before V8 serializes the heap.
+   * Cleans up non-serializable resources: file handles, timers, listeners, connections.
+   */
+  async triggerSnapshotWillSerialize(): Promise<void> {
+    return this.lifecycle.triggerSnapshotWillSerialize();
+  }
+
+  /**
+   * Trigger snapshotDidDeserialize lifecycle hooks on all boots in forward order.
+   * Called by the restore entry after V8 deserializes the heap.
+   * Restores non-serializable resources and resumes the lifecycle from configDidLoad.
+   */
+  async triggerSnapshotDidDeserialize(): Promise<void> {
+    return this.lifecycle.triggerSnapshotDidDeserialize();
+  }
+
   /**
    * Close all, it will close
    * - callbacks registered by beforeClose

packages/core/src/lifecycle.ts

@@ -61,6 +61,23 @@ export interface ILifecycleBoot {
    * when the application is started with metadataOnly: true.
    */
   loadMetadata?(): Promise<void> | void;
+
+  /**
+   * Called before V8 serializes the heap for startup snapshot.
+   * Clean up non-serializable resources: close file handles, clear timers,
+   * remove process listeners, close network connections.
+   * Executed in REVERSE registration order (like beforeClose).
+   */
+  snapshotWillSerialize?(): Promise<void> | void;
+
+  /**
+   * Called after V8 deserializes the heap from a startup snapshot.
+   * Restore non-serializable resources: reopen file handles, recreate timers,
+   * re-register process listeners, reinitialize connections.
+   * Executed in FORWARD registration order (like configWillLoad).
+   * After all hooks complete, the normal lifecycle resumes from configDidLoad.
+   */
+  snapshotDidDeserialize?(): Promise<void> | void;
 }
 
 export type BootImplClass<T = ILifecycleBoot> = new (...args: any[]) => T;
@@ -380,6 +397,79 @@ export class Lifecycle extends EventEmitter {
     this.ready(firstError ?? true);
   }
 
+  /**
+   * Trigger snapshotWillSerialize on all boots in REVERSE order.
+   * Called by the build script before V8 serializes the heap.
+   */
+  async triggerSnapshotWillSerialize(): Promise<void> {
+    debug('trigger snapshotWillSerialize start');
+    const boots = [...this.#boots].reverse();
+    for (const boot of boots) {
+      if (typeof boot.snapshotWillSerialize !== 'function') {
+        continue;
+      }
+      const fullPath = boot.fullPath ?? 'unknown';
+      debug('trigger snapshotWillSerialize at %o', fullPath);
+      const timingKey = `Snapshot Will Serialize in ${utils.getResolvedFilename(fullPath, this.app.baseDir)}`;
+      this.timing.start(timingKey);
+      try {
+        await utils.callFn(boot.snapshotWillSerialize.bind(boot));
+      } catch (err) {
+        debug('trigger snapshotWillSerialize error at %o, error: %s', fullPath, err);
+        this.emit('error', err);
+      }
+      this.timing.end(timingKey);
+    }
+    debug('trigger snapshotWillSerialize end');
+  }
+
+  /**
+   * Trigger snapshotDidDeserialize on all boots in FORWARD order.
+   * Called by the restore entry after V8 deserializes the heap.
+   * After all hooks complete, resets the ready state and resumes the normal
+   * lifecycle from configDidLoad. The returned promise resolves when the
+   * full lifecycle (configDidLoad → didLoad → willReady) has completed.
+   */
+  async triggerSnapshotDidDeserialize(): Promise<void> {
+    debug('trigger snapshotDidDeserialize start');
+    for (const boot of this.#boots) {
+      if (typeof boot.snapshotDidDeserialize !== 'function') {
+        continue;
+      }
+      const fullPath = boot.fullPath ?? 'unknown';
+      debug('trigger snapshotDidDeserialize at %o', fullPath);
+      const timingKey = `Snapshot Did Deserialize in ${utils.getResolvedFilename(fullPath, this.app.baseDir)}`;
+      this.timing.start(timingKey);
+      try {
+        await utils.callFn(boot.snapshotDidDeserialize.bind(boot));
+      } catch (err) {
+        debug('trigger snapshotDidDeserialize error at %o, error: %s', fullPath, err);
+        this.emit('error', err);
+      }
+      this.timing.end(timingKey);
+    }
+    debug('trigger snapshotDidDeserialize end');
+
+    // Reset ready state for the resumed lifecycle.
+    // In snapshot mode, ready(true) was called during triggerConfigWillLoad,
+    // resolving the ready promise early. We need fresh ready objects so the
+    // resumed lifecycle (didLoad → willReady → didReady) can track properly.
+    // Note: keep options.snapshot = true so the constructor's stale ready
+    // callback (which may fire asynchronously) correctly skips triggerDidReady.
+    this.#readyObject = new ReadyObject();
+    this.#initReady();
+    this.ready((err) => {
+      void this.triggerDidReady(err);
+      debug('app ready after snapshot deserialize');
+    });
+
+    // Resume the normal lifecycle from configDidLoad
+    this.triggerConfigDidLoad();
+
+    // Wait for the full resumed lifecycle to complete
+    await this.ready();
+  }
+
   #initReady(): void {
     debug('loadReady init');
     this.loadReady = new Ready({ timeout: this.readyTimeout, lazyStart: true });