feat(core): create/load distinction mechanism for snapshot restoration (FEP-2548)

.changeset/fep-2548-create-load-distinction.md

@@ -0,0 +1,17 @@
+---
+"@stackflow/core": major
+---
+
+Distinguish how a stack is initialized — created fresh (`create`) or restored from a snapshot (`load`) — and add the surface a snapshot round-trip needs: `StackSnapshot`, `actions.captureSnapshot()`, the `provideSnapshot` / `onLoadError` plugin hooks, and `initInfo` on `onInit`. Runtime behavior is unchanged when no snapshot is provided; the breaks are type-level only — the `StackflowPluginHook` → `StackflowPluginInitHook` rename, plus new required members on `StackflowActions` and on the `onInit` / `overrideInitialEvents` hook signatures — hence the major.
+
+**Added**
+
+- `StackSnapshot` (with the `SnapshotEvent` / `NavigationEvent` unions) — a plain-data record of the events a stack recorded at runtime — plus `SnapshotLoadError`.
+- `actions.captureSnapshot()` to export that record, and the `provideSnapshot` / `onLoadError` plugin hooks to supply a snapshot at creation time and route a failed load.
+- `initInfo: { kind: "create" | "load" }` on `onInit`; `overrideInitialEvents` now runs on the load path too and receives the same `initInfo`.
+
+**Changed**
+
+- Renamed the `StackflowPluginHook` type to `StackflowPluginInitHook`.
+- `StackflowActions` now requires `captureSnapshot`, the `onInit` / `overrideInitialEvents` hook arguments now require `initInfo`, and `overrideInitialEvents`' parameter widens from `(PushedEvent | StepPushedEvent)[]` to `SnapshotEvent[]` — hand-written mocks and wrap-and-forward plugins must adopt these.
+- `validateEvents` now also rejects a `Replaced` that names an unregistered activity (does not fire in config-first usage).

core/src/SnapshotLoadError.ts

@@ -0,0 +1,39 @@
+/**
+ * Why a snapshot load failed, in three kinds that read as the
+ * snapshot → events → stack pipeline:
+ * - `unrecognized-snapshot`: the value is not a snapshot structure core
+ *   recognizes — a catch-all over the structural checks (`$schema` mismatch,
+ *   `events` not being an array, or an item that is not one of the six
+ *   navigation events, including a missing `id`/`name`). `detail` names the
+ *   check that failed.
+ * - `incompatible-events`: the structure is recognized but the event sequence
+ *   is incompatible with the current config (e.g. it materializes an
+ *   unregistered activity) — a relational failure against the config, not a
+ *   defect intrinsic to the events. `detail` is the raw error thrown by the
+ *   replay machinery (`aggregate`/`validateEvents`), carried unflattened —
+ *   hence `unknown`. Narrowing it to the offending events would drop the
+ *   thrown error's call stack, which is the useful diagnostic here.
+ * - `empty-stack`: replay succeeded but left zero activities in an enter
+ *   state, so there is nothing to show. Note the condition is "zero
+ *   enter-state activities", not an empty `activities` array — exit-done
+ *   activities may remain.
+ */
+export type SnapshotLoadErrorCause =
+  | { kind: "unrecognized-snapshot"; detail: string }
+  | { kind: "incompatible-events"; detail: unknown }
+  | { kind: "empty-stack" };
+
+/**
+ * Thrown when loading a provided snapshot fails. Routed to the providing
+ * plugin's `onLoadError` first (R5); if unrecovered, thrown out of
+ * `makeCoreStore` (R4).
+ */
+export class SnapshotLoadError extends Error {
+  cause: SnapshotLoadErrorCause;
+
+  constructor(cause: SnapshotLoadErrorCause, message?: string) {
+    super(message ?? `failed to load snapshot: ${cause.kind}`);
+    this.name = "SnapshotLoadError";
+    this.cause = cause;
+  }
+}

core/src/StackSnapshot.ts

@@ -0,0 +1,53 @@
+import type {
+  PausedEvent,
+  PoppedEvent,
+  PushedEvent,
+  ReplacedEvent,
+  ResumedEvent,
+  StepPoppedEvent,
+  StepPushedEvent,
+  StepReplacedEvent,
+} from "./event-types";
+
+/**
+ * The six navigation events — a subset union of the existing domain event
+ * types (no new vocabulary is introduced).
+ */
+export type NavigationEvent =
+  | PushedEvent
+  | ReplacedEvent
+  | PoppedEvent
+  | StepPushedEvent
+  | StepReplacedEvent
+  | StepPoppedEvent;
+
+/**
+ * The events a snapshot carries: every domain event except the static ones
+ * (`Initialized`, `ActivityRegistered`). Statics are config/source-grade
+ * information — they may legitimately differ after a reload, so the current
+ * config re-derives them at load time instead of trusting the snapshot.
+ * Everything the stack recorded at runtime, `Paused`/`Resumed` included, is
+ * exported as-is.
+ */
+export type SnapshotEvent = NavigationEvent | PausedEvent | ResumedEvent;
+
+/**
+ * A plain-data value whose structure is owned by core. Encoding to a
+ * persistence medium (codec) is the consumer's responsibility.
+ */
+export type StackSnapshot = {
+  /**
+   * Structural discriminator tag. A mismatch fails the load as
+   * `SnapshotLoadError` — version migration is a non-goal.
+   */
+  $schema: "stackflow.snapshot.v1";
+
+  /**
+   * The event log as recorded, minus the static events the current config
+   * re-derives at load time. Left in recorded order — load replays through
+   * `aggregate`, which sorts by eventDate and dedupes by id. Whether to
+   * capture a paused stack is the caller's choice — core exports the stack it
+   * is asked about, pause state and all.
+   */
+  events: SnapshotEvent[];
+};

core/src/event-utils/index.ts

@@ -1,4 +1,5 @@
 export * from "./dispatchEvent";
 export * from "./filterEvents";
+export * from "./isSnapshotEvent";
 export * from "./makeEvent";
 export * from "./validateEvents";

core/src/event-utils/isSnapshotEvent.ts

@@ -0,0 +1,36 @@
+import type { DomainEvent } from "../event-types";
+import type { SnapshotEvent } from "../StackSnapshot";
+
+/**
+ * The events a snapshot carries — every domain event except the static ones
+ * (`Initialized`, `ActivityRegistered`), which the current config re-derives
+ * at load time. Single source of truth for the capture-side filter and the
+ * load-side structure check.
+ *
+ * Its members are constrained to `SnapshotEvent["name"]` at construction (a
+ * typo or a non-snapshot name fails to compile), but the set itself is typed
+ * `ReadonlySet<string>` so both membership checks below can pass a plain event
+ * name — a `DomainEvent["name"]` or a runtime `string` — without a cast.
+ */
+const SNAPSHOT_EVENT_NAMES: ReadonlySet<string> = new Set<
+  SnapshotEvent["name"]
+>([
+  "Pushed",
+  "Replaced",
+  "Popped",
+  "StepPushed",
+  "StepReplaced",
+  "StepPopped",
+  "Paused",
+  "Resumed",
+]);
+
+/** Whether an event is one a snapshot carries (i.e. not a static event). */
+export function isSnapshotEvent(event: DomainEvent): event is SnapshotEvent {
+  return SNAPSHOT_EVENT_NAMES.has(event.name);
+}
+
+/** Whether a value is the name of an event a snapshot carries. */
+export function isSnapshotEventName(name: unknown): boolean {
+  return typeof name === "string" && SNAPSHOT_EVENT_NAMES.has(name);
+}

core/src/event-utils/validateEvents.ts

@@ -18,9 +18,15 @@ export function validateEvents(events: DomainEvent[]) {
     activityRegisteredEvents.map((e) => e.activityName),
   );
 
-  const pushedEvents = filterEvents(events, "Pushed");
+  // Both Pushed and Replaced materialize an activity by name, so both must
+  // name a registered activity — checking only Pushed left Replaced an
+  // asymmetric gap.
+  const materializingEvents = [
+    ...filterEvents(events, "Pushed"),
+    ...filterEvents(events, "Replaced"),
+  ];
 
-  if (pushedEvents.some((e) => !registeredActivityNames.has(e.activityName))) {
+  if (materializingEvents.some((e) => !registeredActivityNames.has(e.activityName))) {
     throw new Error("the corresponding activity does not exist");
   }
 }

core/src/index.ts

@@ -5,11 +5,17 @@ export { DispatchEvent, makeEvent } from "./event-utils";
 export * from "./interfaces";
 export * from "./makeCoreStore";
 export { produceEffects } from "./produceEffects";
+export { SnapshotLoadError, SnapshotLoadErrorCause } from "./SnapshotLoadError";
 export {
   Activity,
   ActivityStep,
   ActivityTransitionState,
   RegisteredActivity,
   Stack,
 } from "./Stack";
+export {
+  NavigationEvent,
+  SnapshotEvent,
+  StackSnapshot,
+} from "./StackSnapshot";
 export { id } from "./utils";

core/src/interfaces/StackflowActions.ts

@@ -11,13 +11,20 @@ import type {
 import type { BaseDomainEvent } from "../event-types/_base";
 import type { DispatchEvent } from "../event-utils";
 import type { Stack } from "../Stack";
+import type { StackSnapshot } from "../StackSnapshot";
 
 export type StackflowActions = {
   /**
    * Get current stack state
    */
   getStack: () => Stack;
 
+  /**
+   * Capture the current navigation history as a snapshot. Callable from any
+   * hook, at any time; normalizes the event log into navigation events.
+   */
+  captureSnapshot: () => StackSnapshot;
+
   /**
    * Dispatch new event to the core without pre-effect hooks
    */

core/src/interfaces/StackflowPlugin.ts

@@ -9,10 +9,13 @@ import type {
   StepReplacedEvent,
 } from "../event-types";
 import type { BaseDomainEvent } from "../event-types/_base";
+import type { SnapshotLoadError } from "../SnapshotLoadError";
+import type { SnapshotEvent, StackSnapshot } from "../StackSnapshot";
 import type {
-  StackflowPluginHook,
+  StackflowPluginInitHook,
   StackflowPluginPostEffectHook,
   StackflowPluginPreEffectHook,
+  StackInitInfo,
 } from "./StackflowPluginHook";
 
 export type StackflowPlugin = () => {
@@ -24,7 +27,7 @@ export type StackflowPlugin = () => {
   /**
    * Called when the <Stack /> component is initialized for the first time
    */
-  onInit?: StackflowPluginHook;
+  onInit?: StackflowPluginInitHook;
 
   /**
    * Called before the `push()` function of `useActions()` is called and the corresponding signal is delivered to the core
@@ -128,10 +131,55 @@ export type StackflowPlugin = () => {
   onChanged?: StackflowPluginPostEffectHook<"%SOMETHING_CHANGED%">;
 
   /**
-   * Specifies the first `PushedEvent`, `StepPushedEvent` (Overrides the `initialActivity` option specified in the `stackflow()` function)
+   * Intercept the event sequence a stack is built from. Chained across
+   * plugins in array order — each plugin receives the previous one's
+   * return. `initInfo` says which path is running, in the same record shape
+   * `onInit` receives:
+   * - `{ kind: "create" }`: `initialEvents` holds the initial entry events
+   *   (`PushedEvent`/`StepPushedEvent`, from the `initialActivity` option or
+   *   earlier plugins). The return decides the initial entries.
+   * - `{ kind: "load" }`: `initialEvents` holds the provided snapshot's full
+   *   replay sequence (structure-validated, original field values) —
+   *   `Paused`/`Resumed` included when the snapshot recorded them. The
+   *   return is adopted as the replay sequence with its event dates
+   *   preserved: core never re-dates it, so replay order follows the
+   *   recorded dates and a guarantee like "every restored activity is
+   *   settled" is this hook's to provide, by re-dating the events itself.
+   *   The return then runs through the same load validation as the snapshot
+   *   itself (activity registration, replay, at least one enter-state
+   *   activity), so a failing return surfaces as a `SnapshotLoadError` to
+   *   the snapshot provider. Reshaping the sequence reshapes the
+   *   reconstructed navigation history — a plugin with no load policy must
+   *   return `initialEvents` unchanged.
    */
   overrideInitialEvents?: (args: {
-    initialEvents: (PushedEvent | StepPushedEvent)[];
+    initialEvents: SnapshotEvent[];
     initialContext: any;
-  }) => (PushedEvent | StepPushedEvent)[];
+    initInfo: StackInitInfo;
+  }) => SnapshotEvent[];
+
+  /**
+   * Called synchronously at stack creation time to provide a snapshot to load
+   * from. Returning `null` means "nothing to provide" and the create path
+   * continues. If more than one plugin returns a non-null snapshot, core
+   * throws a creation error naming the conflicting keys — it does not
+   * arbitrate (R9).
+   */
+  provideSnapshot?: (args: { initialContext: any }) => StackSnapshot | null;
+
+  /**
+   * Called — only on the plugin that provided the failing snapshot (R5) — when
+   * that snapshot fails to load. Returning `{ policy: "recover" }` resumes the
+   * create path without re-polling; returning `{ policy: "propagate" }` (or
+   * having no handler) throws the `SnapshotLoadError` out of `makeCoreStore`
+   * (R4). Both outcomes share the `policy` discriminant so a handler chooses
+   * recover vs propagate explicitly, rather than propagating by falling off
+   * the end. `"recover"` currently resumes the sole create path; a future
+   * recovery target would extend this branch (e.g. an added field) rather
+   * than the discriminant.
+   */
+  onLoadError?: (args: {
+    error: SnapshotLoadError;
+    initialContext: any;
+  }) => { policy: "recover" } | { policy: "propagate" };
 };

core/src/interfaces/StackflowPluginHook.ts

@@ -1,7 +1,19 @@
 import type { Effect } from "../Effect";
 import type { StackflowActions } from "./StackflowActions";
 
-export type StackflowPluginHook = (args: { actions: StackflowActions }) => void;
+/**
+ * Which path created this stack — `{ kind: "create" }` (fresh) or
+ * `{ kind: "load" }` (restored from a snapshot). A one-shot signal that
+ * leaves no trace on the stack. A record rather than a bare string so
+ * per-path fields can be added later without breaking hook signatures.
+ * `onInit` and `overrideInitialEvents` receive the signal in this same shape.
+ */
+export type StackInitInfo = { kind: "create" | "load" };
+
+export type StackflowPluginInitHook = (args: {
+  actions: StackflowActions;
+  initInfo: StackInitInfo;
+}) => void;
 
 export type StackflowPluginPreEffectHook<T> = (args: {
   actionParams: T;