test(core): create/load distinction test suites (FEP-2548)

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

@@ -0,0 +1,33 @@
+---
+"@stackflow/core": major
+---
+
+Distinguish how a stack is created — freshly (`create`) or restored from a snapshot (`load`) — and add the surface a snapshot round-trip (capture → persist → load) needs, through additive plugin contracts. The addition is runtime-additive — a store with no snapshot provider behaves exactly as before — but at the type level, hand-written `StackflowActions` mocks and code that constructs `onInit` hook arguments (wrap-and-forward plugins) must add the new required members (`captureSnapshot`, `initInfo`), and `overrideInitialEvents` implementations that explicitly annotate their parameter with the previous `(PushedEvent | StepPushedEvent)[]` shape must widen it to `SnapshotEvent[]` (implementations with inferred parameters are unaffected). One more type-level break versus the last release: the exported hook type `StackflowPluginHook` is renamed to `StackflowPluginInitHook` (the `onInit` hook type). The `provideSnapshot` and `onLoadError` hooks below are new additive surface — they land in their final shape (`StackSnapshot | null` and `{ policy: "recover" } | { policy: "propagate" }`), not a change to any published type. Hence a major release.
+
+- `StackSnapshot` (and the `SnapshotEvent` union) — a plain-data value, owned by core, that carries every event the stack recorded at runtime — the six navigation events plus `Paused`/`Resumed` — excluding only the static events (`Initialized`, `ActivityRegistered`), which are config-grade information the current config re-derives at load time. Encoding to a persistence medium (codec) is the consumer's responsibility.
+- `actions.captureSnapshot()` — export the recorded event log as-is (statics excluded); callable from any hook, at any time. Core holds no opinion about when a snapshot is meaningful: capturing a paused stack yields a snapshot that restores a paused stack, and whether to capture at such a moment is the caller's timing choice.
+- `provideSnapshot?({ initialContext })` plugin hook — called synchronously at creation time to supply a snapshot to load from. Returning `null` keeps the create path. If more than one plugin supplies a snapshot, core throws a creation error naming the conflicting keys rather than arbitrating.
+- `onLoadError?({ error, initialContext })` plugin hook + `SnapshotLoadError` (with a `cause.kind` of `"unrecognized-snapshot"`, `"incompatible-events"`, or `"empty-stack"`) — a failed load is routed only to the plugin that provided the snapshot. Returning `{ policy: "recover" }` resumes the create path; returning `{ policy: "propagate" }` (or having no handler) throws the error out of `makeCoreStore`.
+- `onInit` now receives `initInfo: { kind: "create" | "load" }` — a one-shot signal that leaves no trace on the stack state or event log. It is a record rather than a bare string so per-path fields can be added later without breaking the hook signature.
+- `overrideInitialEvents` now runs on the load path too, and its signature widens to `SnapshotEvent[]` in and out, with a new `initInfo` argument (the same record `onInit` receives). On create it keeps deciding the initial entries, as before. On load it receives the provided snapshot's full replay sequence (`Paused`/`Resumed` included when the snapshot recorded them), and its return is adopted as the replay sequence with its event dates preserved — core never re-dates it, so 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, so a failing return surfaces as a `SnapshotLoadError` to the provider. Reshaping the sequence reshapes the reconstructed navigation history: a plugin with no load policy must return `initialEvents` unchanged, and plugins written before this signal that fabricate initial events (e.g. from a URL) should early-return on `initInfo.kind === "load"`.
+
+```ts
+const persisterPlugin = ({ storage, codec }) => () => ({
+  key: "persister",
+  onChanged({ actions }) {
+    storage.write(codec.encode(actions.captureSnapshot()));
+  },
+  provideSnapshot() {
+    const raw = storage.read();
+    return raw ? codec.decode(raw) : null;
+  },
+  onLoadError({ error }) {
+    storage.remove();
+    return { policy: "recover" };
+  },
+});
+```
+
+A load reconstructs the stack by replaying the snapshot's events — as passed through the plugins' `overrideInitialEvents` chain — through the existing aggregate machinery, preserving them byte-for-byte, `eventDate` included: the recorded dates are the replay truth, so a stack captured mid-transition restores mid-transition and a paused stack restores paused, and capture∘load is an identity on the snapshot events. Static information (transition duration, the registered-activity set) is re-derived from the current config, and only those static events are re-dated — to just before the earliest replayed event, so registration and transition duration are in place before any snapshot event applies. Core imposes no settling or date normalization on the replay; a supplier or plugin that wants a fully-settled restore (or protection from a capture clock that ran ahead) re-dates the sequence in `overrideInitialEvents`. No new domain events or stack state properties are introduced.
+
+The snapshot load's registration check is unified into `validateEvents` (run by `aggregate` on every path), which now rejects a `Replaced` that materializes an unregistered activity, matching its long-standing check for `Pushed`. In config-first usage a replace only targets registered activities, so this added check does not fire on the live path.

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[];
+};