feat(persistence): bidirectional local/cloud story sync (Supabase)

Connect the previously-skeleton cloudStore to the client with a full
bidirectional reconcile engine. Commercial build (AUTH_ENABLED) only; the
open-source build is byte-for-byte unchanged — all cloud paths short-circuit
when AUTH_ENABLED is false.

- cloudSync.ts: reconcile engine — decideAction (pure, LWW rev->updatedAt with
  tombstone priority) + syncOnLogin/pushOnSave/pushDeletion (best-effort,
  serialized, isAuthed-gated)
- cloudSyncClient.ts: browser fetch bridge (short-circuit + fault-tolerant)
- /api/stories/{manifest,pull,push,delete}: RLS-guarded sync endpoints
- upsert_story_if_newer RPC: optimistic concurrency (SECURITY INVOKER,
  auth.uid() injection, rev->updated_at guard, revoked from public)
- cloudStore: +manifest/pullBlobs, save->RPC {stored,won}, softDelete w/ rev
- localStore: +listAllRecordsForSync/putSyncedRecord/markRecordSynced
  (concurrency-guarded sync writes); types: +StorySyncMeta/StorySyncEnvelope
- facade + UserChip: inject pushOnSave/pushDeletion + login-triggered reconcile

Sync model: full reconcile on login + background push on save (no Realtime;
eventual consistency). Conflict resolution: last-write-wins.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

lib/clientStoryPersistence.ts

@@ -14,6 +14,7 @@ import {
   loadStorySession as loadSession,
   softDeleteStory,
 } from "@/lib/persistence/localStore";
+import { pushOnSave, pushDeletion } from "@/lib/persistence/cloudSync";
 
 export type SaveResult =
   | { ok: true; storyId: string }
@@ -23,9 +24,11 @@ export type SaveResult =
  *  never throws, never blocks gameplay/navigation. */
 export async function saveStory(session: Session): Promise<SaveResult> {
   const rec = await saveStorySession(session);
-  return rec
-    ? { ok: true, storyId: rec.id }
-    : { ok: false, error: "无法保存到本地存储" };
+  if (!rec) return { ok: false, error: "无法保存到本地存储" };
+  // Fire-and-forget cloud push. pushOnSave short-circuits when auth is off /
+  // the user is signed out, so the open-source build sees no behavior change.
+  void pushOnSave(rec);
+  return { ok: true, storyId: rec.id };
 }
 
 /** List saved stories for the "我的剧情" page (newest first). */
@@ -40,5 +43,9 @@ export async function loadStorySession(id: string): Promise<Session | null> {
 
 /** Delete a saved story (soft-delete). Returns false if not found. */
 export async function deleteStory(storyId: string): Promise<boolean> {
-  return softDeleteStory(storyId);
+  const ok = await softDeleteStory(storyId);
+  // Fire-and-forget tombstone propagation. pushDeletion short-circuits when auth
+  // is off / signed out, so the open-source build sees no behavior change.
+  if (ok) void pushDeletion(storyId);
+  return ok;
 }

lib/persistence/cloudStore.ts

@@ -1,16 +1,22 @@
-// Cloud story repository — server-only Supabase persistence skeleton for the
-// COMMERCIAL build. Mirrors the local repository (lib/persistence/localStore.ts)
-// method-for-method so next-phase local-first bidirectional sync can treat the
-// cloud as a layer over the local store rather than a parallel branch.
+// Cloud story repository — server-only Supabase persistence for the COMMERCIAL
+// build. Mirrors the local repository (lib/persistence/localStore.ts) so the
+// reconcile engine (lib/persistence/cloudSync.ts) can treat the cloud as a layer
+// over the local store.
 //
-// This phase is a SKELETON: no API route exposes these functions and no client
-// calls them. When AUTH_ENABLED is false (the open-source build) every method
-// short-circuits to a safe value on its first line and never touches Supabase.
+// When AUTH_ENABLED is false (the open-source build) every method short-circuits
+// to a safe value on its first line and never touches Supabase.
 //
 // Isolation is by RLS only: the SSR client carries the user's anon key + cookie,
 // and every public.stories policy is keyed on auth.uid() = user_id — so no
 // service_role key is used and no query needs a manual user filter for safety
 // (the explicit .eq("user_id") below is belt-and-suspenders + index alignment).
+//
+// Optimistic concurrency:
+//  - cloudSaveStory upserts via the upsert_story_if_newer RPC (needs INSERT-if-
+//    absent + a conditional overwrite, which PostgREST upsert can't express).
+//  - cloudSoftDeleteStory is UPDATE-only (a story never pushed has no cloud row
+//    to tombstone), so it expresses the same rev→updatedAt guard with a
+//    PostgREST .or() filter — no RPC needed.
 
 import "server-only";
 
@@ -18,7 +24,7 @@ import type { Session } from "@infiplot/types";
 import { coerceOrientation } from "@infiplot/types";
 import { AUTH_ENABLED } from "@/lib/supabase/config";
 import { createClient } from "@/lib/supabase/server";
-import type { SlimStoryBlob, StoryMeta } from "./types";
+import type { SlimStoryBlob, StoryMeta, StorySyncMeta, StorySyncEnvelope } from "./types";
 import { coerceEpoch } from "./types";
 
 /** One row of public.stories (snake_case columns ↔ SlimStoryBlob + sync meta). */
@@ -78,63 +84,75 @@ function rowToMeta(row: StoryRow): StoryMeta {
   };
 }
 
+/** Full-blob projection for the sync layer: blob + (updatedAt, deletedAt) so
+ *  reconcile has the LWW-ordering fields. Carries tombstones (deletedAt may be
+ *  non-null) — a pulled cloud tombstone mirrors a remote soft-delete locally. */
+function rowToEnvelope(row: StoryRow): StorySyncEnvelope {
+  return {
+    id: row.id,
+    worldSetting: row.world_setting ?? "",
+    styleGuide: row.style_guide ?? "",
+    orientation: coerceOrientation(row.orientation),
+    sceneCount: row.scene_count ?? 0,
+    rev: row.rev ?? 1,
+    session: row.session_jsonb,
+    updatedAt: coerceEpoch(row.updated_at, 0),
+    deletedAt: row.deleted_at ? coerceEpoch(row.deleted_at, 0) : null,
+  };
+}
+
 // ── Public API ──────────────────────────────────────────────────────────────
 //
-// CONTRACT NOTE (CR-15): these methods are the cloud COUNTERPARTS of
-// lib/persistence/localStore.ts, but their return shapes are intentionally NOT
-// identical — the local store returns rich StoryRecord/Session values (carrying
-// schemaVersion/createdAt/updatedAt/deletedAt/syncState), while the cloud store
-// returns the leaner SlimStoryBlob. When next-phase bidirectional sync lands it
-// must map StoryRecord ↔ SlimStoryBlob ↔ Session in one reconciliation layer
-// rather than assuming a single shared shape; the intended convergence is a
-// common envelope (SlimStoryBlob + sync-meta) at both edges. Documented here so
-// the asymmetry is a known, bounded cost, not a surprise.
+// CONTRACT NOTE: the sync methods (manifest/pull/save/softDelete) speak the
+// StorySyncEnvelope/StorySyncMeta shapes — the convergence envelope the
+// reconcile engine maps StoryRecord ↔ envelope in one place. The legacy
+// cloudLoadStory/cloudListStories (leaner SlimStoryBlob/StoryMeta) are retained
+// for non-sync callers; reconcile does not use them.
 
-/** Upsert one story for the current user. onConflict targets the `id` PK; the
- *  caller-supplied rev/updated_at are written verbatim and created_at is left to
- *  the DB default (insert only). NOTE (CR-10): this is last-write-wins — there is
- *  no `updated_at`-monotonic guard, so a slow concurrent writer can clobber newer
- *  cloud state; the next-phase sync layer must add an optimistic-concurrency
- *  predicate (e.g. only overwrite when excluded.updated_at > stories.updated_at)
- *  before this is wired to real multi-device traffic. Returns the stored blob, or
- *  null when auth is off / unauthenticated / the write failed (incl. an RLS-hidden
- *  cross-user id collision surfacing as a PK violation). */
+/** Upsert one story for the current user via the optimistic-concurrency RPC.
+ *  Returns `{ stored, won }`:
+ *   - won=true  → our version is now the cloud row (fresh insert, winning
+ *     update, or already-equal no-op);
+ *   - won=false → a NEWER cloud row existed and was preserved; `stored` is that
+ *     newer row so the caller can reconcile by pulling it back.
+ *  Auth off / unauthenticated / write failure → `{ stored: null, won: false }`. */
 export async function cloudSaveStory(
-  blob: SlimStoryBlob,
-): Promise<SlimStoryBlob | null> {
-  if (!AUTH_ENABLED) return null;
+  env: StorySyncEnvelope,
+): Promise<{ stored: StorySyncEnvelope | null; won: boolean }> {
+  if (!AUTH_ENABLED) return { stored: null, won: false };
   const userId = await currentUserId();
-  if (!userId) return null;
+  if (!userId) return { stored: null, won: false };
   try {
     const supabase = await createClient();
-    const { data, error } = await supabase
-      .from("stories")
-      .upsert(
-        {
-          id: blob.id,
-          user_id: userId,
-          world_setting: blob.worldSetting ?? "",
-          style_guide: blob.styleGuide ?? "",
-          orientation: coerceOrientation(blob.orientation),
-          scene_count: blob.sceneCount ?? 0,
-          rev: blob.rev ?? 1,
-          updated_at: new Date().toISOString(),
-          deleted_at: null,
-          session_jsonb: blob.session,
-        },
-        { onConflict: "user_id,id" },
-      )
-      .select()
-      .single();
-    if (error || !data) return null;
-    return rowToBlob(data as StoryRow);
+    const { data, error } = await supabase.rpc("upsert_story_if_newer", {
+      p_id: env.id,
+      p_world: env.worldSetting ?? "",
+      p_style: env.styleGuide ?? "",
+      p_orientation: coerceOrientation(env.orientation),
+      p_scene_count: env.sceneCount ?? 0,
+      p_rev: env.rev ?? 1,
+      p_updated_at: new Date(env.updatedAt).toISOString(),
+      p_deleted_at: env.deletedAt ? new Date(env.deletedAt).toISOString() : null,
+      p_session: env.session,
+    });
+    if (error || !data) return { stored: null, won: false };
+    // The RPC `returns public.stories` (a single composite); supabase-js may
+    // hand it back as the object or wrapped in an array — normalize both.
+    const row = (Array.isArray(data) ? data[0] : data) as StoryRow | undefined;
+    if (!row) return { stored: null, won: false };
+    const stored = rowToEnvelope(row);
+    // We won iff the stored row IS our version. A stale write returns the newer
+    // cloud row, whose (rev, updatedAt) differ from what we sent → won=false.
+    const won = stored.rev === env.rev && stored.updatedAt === env.updatedAt;
+    return { stored, won };
   } catch {
-    return null;
+    return { stored: null, won: false };
   }
 }
 
 /** Load one story's slim blob for the current user. Tombstoned / absent / not
- *  owned (RLS) → null. */
+ *  owned (RLS) → null. Retained for non-sync callers (reconcile uses
+ *  cloudPullBlobs, which carries tombstones + sync-ordering fields). */
 export async function cloudLoadStory(id: string): Promise<SlimStoryBlob | null> {
   if (!AUTH_ENABLED) return null;
   const userId = await currentUserId();
@@ -180,21 +198,81 @@ export async function cloudListStories(): Promise<StoryMeta[]> {
   }
 }
 
-/** Soft-delete one story (set the tombstone) for the current user so the
- *  deletion can propagate. Absent / not owned / write failed → false. */
-export async function cloudSoftDeleteStory(id: string): Promise<boolean> {
+/** Reconcile diff basis: ALL the current user's rows (INCLUDING tombstones),
+ *  projected to lightweight {id, rev, updatedAt, deletedAt}. Explicit column
+ *  list so it never pulls session_jsonb. Auth off / unauth → []. */
+export async function cloudStoryManifest(): Promise<StorySyncMeta[]> {
+  if (!AUTH_ENABLED) return [];
+  const userId = await currentUserId();
+  if (!userId) return [];
+  try {
+    const supabase = await createClient();
+    const { data, error } = await supabase
+      .from("stories")
+      .select("id, rev, updated_at, deleted_at")
+      .eq("user_id", userId);
+    if (error || !data) return [];
+    return (data as StoryRow[]).map((row) => ({
+      id: row.id,
+      rev: row.rev ?? 1,
+      updatedAt: coerceEpoch(row.updated_at, 0),
+      deletedAt: row.deleted_at ? coerceEpoch(row.deleted_at, 0) : null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/** Pull full envelopes for the given ids (INCLUDING tombstones — a pulled cloud
+ *  tombstone mirrors a remote soft-delete locally). Empty ids / auth off /
+ *  unauth → []. */
+export async function cloudPullBlobs(
+  ids: string[],
+): Promise<StorySyncEnvelope[]> {
+  if (!AUTH_ENABLED) return [];
+  if (!ids.length) return [];
+  const userId = await currentUserId();
+  if (!userId) return [];
+  try {
+    const supabase = await createClient();
+    const { data, error } = await supabase
+      .from("stories")
+      .select()
+      .eq("user_id", userId)
+      .in("id", ids);
+    if (error || !data) return [];
+    return (data as StoryRow[]).map(rowToEnvelope);
+  } catch {
+    return [];
+  }
+}
+
+/** Propagate a soft-delete (tombstone) for the current user, with the same
+ *  optimistic-concurrency guard as the save RPC expressed as a PostgREST .or()
+ *  filter: only stamp when the incoming version is newer (rev higher, or rev
+ *  tie with a later updatedAt). UPDATE-only — a story never pushed has no cloud
+ *  row and needs no tombstone (returns false, which the caller treats as
+ *  "nothing to delete remotely"). Auth off / unauth / not-newer / absent →
+ *  false. */
+export async function cloudSoftDeleteStory(
+  id: string,
+  rev: number,
+  deletedAt: number,
+): Promise<boolean> {
   if (!AUTH_ENABLED) return false;
   const userId = await currentUserId();
   if (!userId) return false;
   try {
     const supabase = await createClient();
-    const now = new Date().toISOString();
+    const deletedIso = new Date(deletedAt).toISOString();
     const { data, error } = await supabase
       .from("stories")
-      .update({ deleted_at: now, updated_at: now })
-      .eq("id", id)
+      .update({ deleted_at: deletedIso, updated_at: deletedIso, rev })
       .eq("user_id", userId)
-      .is("deleted_at", null)
+      .eq("id", id)
+      // Quote the timestamptz value so PostgREST parses the colons/dots in the
+      // ISO string as a literal, not filter syntax.
+      .or(`rev.lt.${rev},and(rev.eq.${rev},updated_at.lt."${deletedIso}")`)
       .select("id");
     if (error || !data || data.length === 0) return false;
     return true;

lib/persistence/cloudSync.ts

@@ -0,0 +1,246 @@
+// Reconcile engine — the bidirectional local↔cloud sync orchestration for the
+// COMMERCIAL build. Browser-only. This is the single place that maps
+// StoryRecord ↔ StorySyncEnvelope ↔ StorySyncMeta and owns every merge decision.
+//
+// Triggers (all best-effort, never throw, never block gameplay):
+//  - syncOnLogin(): full reconcile on sign-in / authed mount, serialized so a
+//    second trigger joins the in-flight run instead of racing it.
+//  - pushOnSave(record): fire-and-forget single push after a local autosave.
+//  - pushDeletion(id): fire-and-forget tombstone propagation after a soft-delete.
+//
+// Conflict policy is last-write-wins: rev wins; on a rev tie, the later
+// updatedAt wins (decideAction). A losing side is overwritten — acceptable for
+// single-player, full-snapshot galgame saves (see design.md conflict tradeoff).
+
+import { AUTH_ENABLED } from "@/lib/supabase/config";
+import { isAuthed } from "@/lib/authResume";
+import {
+  pullManifest,
+  pullBlobs,
+  pushBlob,
+  pushDelete,
+} from "./cloudSyncClient";
+import {
+  listAllRecordsForSync,
+  putSyncedRecord,
+  markRecordSynced,
+} from "./localStore";
+import { coerceEpoch, type StoryRecord, type StorySyncMeta, type StorySyncEnvelope } from "./types";
+
+// Keep in lockstep with the pull route's MAX_PULL_IDS.
+const PULL_CHUNK = 200;
+
+type ReconcileAction = "push" | "pull" | "delete-remote" | "noop";
+
+/** Which side is newer by the LWW order (rev, then updatedAt). Pure. */
+function newerSide(
+  local: StoryRecord,
+  cloud: StorySyncMeta,
+): "local" | "cloud" | "equal" {
+  const lr = local.rev ?? 1;
+  const cr = cloud.rev ?? 1;
+  if (lr > cr) return "local";
+  if (lr < cr) return "cloud";
+  const lu = coerceEpoch(local.updatedAt, 0);
+  const cu = coerceEpoch(cloud.updatedAt, 0);
+  if (lu > cu) return "local";
+  if (lu < cu) return "cloud";
+  return "equal";
+}
+
+/** Pure merge decision for one id (no I/O) — implements the design decision
+ *  table incl. tombstone priority ("the newer operation wins"). A soft-delete
+ *  carries (rev, updatedAt) and is compared like an edit. NOTE softDeleteStory
+ *  does NOT bump rev, so within the SAME rev a later-updatedAt delete propagates
+ *  and a later-updatedAt edit resurrects; ACROSS revs the rev-primary LWW order
+ *  applies (a higher-rev edit beats a wall-clock-later but lower-rev delete).
+ *  Exported for the decision-matrix test.
+ *
+ *  - only cloud, live     → pull
+ *  - only cloud, tombstone→ noop (don't materialize an already-reaped / never-held
+ *                            tombstone — avoids a 30-day-reap → re-pull-of-blob loop)
+ *  - only local, live     → push
+ *  - only local, tombstone→ noop (no cloud row to delete; reaped locally)
+ *  - both, local newer    → tombstone ? delete-remote : push
+ *  - both, cloud newer    → pull
+ *  - both, equal          → noop (reconcile markSyncs if local not yet synced) */
+export function decideAction(
+  local: StoryRecord | undefined,
+  cloud: StorySyncMeta | undefined,
+): ReconcileAction {
+  if (!local && cloud) return cloud.deletedAt ? "noop" : "pull";
+  if (local && !cloud) return local.deletedAt ? "noop" : "push";
+  if (!local || !cloud) return "noop"; // both undefined — unreachable in reconcile
+
+  const side = newerSide(local, cloud);
+  if (side === "local") return local.deletedAt ? "delete-remote" : "push";
+  if (side === "cloud") return "pull";
+  return "noop";
+}
+
+/** StoryRecord → envelope for push (carries the LWW-ordering fields). */
+function recordToEnvelope(rec: StoryRecord): StorySyncEnvelope {
+  return {
+    id: rec.id,
+    worldSetting: rec.worldSetting ?? "",
+    styleGuide: rec.styleGuide ?? "",
+    orientation: rec.orientation,
+    sceneCount: rec.sceneCount ?? 0,
+    rev: rec.rev ?? 1,
+    session: rec.session,
+    updatedAt: coerceEpoch(rec.updatedAt, Date.now()),
+    deletedAt: rec.deletedAt == null ? null : coerceEpoch(rec.deletedAt, Date.now()),
+  };
+}
+
+function chunk<T>(arr: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+/** Push one local record; on a lost optimistic-concurrency race (won=false)
+ *  pull the newer cloud row back instead. Each step swallows its own errors. */
+async function pushOne(rec: StoryRecord): Promise<void> {
+  const res = await pushBlob(recordToEnvelope(rec));
+  if (!res) return; // network/auth failure → leave pending for next reconcile
+  if (res.won) {
+    await markRecordSynced(rec.id, rec.rev ?? 1);
+  } else if (res.stored) {
+    await putSyncedRecord(res.stored); // we lost → adopt the newer cloud state
+  }
+}
+
+/** Full bidirectional reconcile. Diffs the local set (incl. tombstones) against
+ *  the cloud manifest, then applies each id's action, every item fault-tolerant
+ *  (one failure skips that id, never the whole pass). */
+async function reconcile(): Promise<void> {
+  const [localRecords, manifest] = await Promise.all([
+    listAllRecordsForSync(),
+    pullManifest(),
+  ]);
+  const localById = new Map(localRecords.map((r) => [r.id, r]));
+  const cloudById = new Map(manifest.map((m) => [m.id, m]));
+  const allIds = new Set<string>([...localById.keys(), ...cloudById.keys()]);
+
+  const toPull: string[] = [];
+  const toPush: StoryRecord[] = [];
+  const toDelete: StoryRecord[] = [];
+  const toMarkSynced: StoryRecord[] = [];
+
+  for (const id of allIds) {
+    const local = localById.get(id);
+    const cloud = cloudById.get(id);
+    switch (decideAction(local, cloud)) {
+      case "pull":
+        toPull.push(id);
+        break;
+      case "push":
+        if (local) toPush.push(local);
+        break;
+      case "delete-remote":
+        if (local) toDelete.push(local);
+        break;
+      case "noop":
+        // Already consistent on both sides but local not yet flagged synced —
+        // align its syncState (guard on cloud existing so a local-only tombstone
+        // isn't wrongly marked synced).
+        if (local && cloud && local.syncState !== "synced") toMarkSynced.push(local);
+        break;
+    }
+  }
+
+  // Pull (batched, chunked to the route cap).
+  for (const ids of chunk(toPull, PULL_CHUNK)) {
+    try {
+      const blobs = await pullBlobs(ids);
+      for (const b of blobs) {
+        try {
+          await putSyncedRecord(b);
+        } catch {
+          /* skip this id */
+        }
+      }
+    } catch {
+      /* skip this chunk (consistent with the push/delete loops' fault isolation) */
+    }
+  }
+  // Push.
+  for (const rec of toPush) {
+    try {
+      await pushOne(rec);
+    } catch {
+      /* leave pending */
+    }
+  }
+  // Tombstone propagation.
+  for (const rec of toDelete) {
+    try {
+      const ok = await pushDelete(rec.id, rec.rev ?? 1, coerceEpoch(rec.deletedAt, Date.now()));
+      if (ok) await markRecordSynced(rec.id, rec.rev ?? 1);
+      // !ok → cloud has a newer row; the next reconcile pulls it back.
+    } catch {
+      /* leave pending */
+    }
+  }
+  // Mark already-consistent records synced.
+  for (const rec of toMarkSynced) {
+    try {
+      await markRecordSynced(rec.id, rec.rev ?? 1);
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+// ── Public triggers ─────────────────────────────────────────────────────────
+
+// Serialize full syncs: a second trigger joins the in-flight run rather than
+// starting a concurrent reconcile (Req 4.3). Module-level, mirrors the play
+// page's saveChain dedup idea.
+let inFlight: Promise<void> | null = null;
+
+/** Trigger a full reconcile on sign-in / authed mount. Serialized + best-effort;
+ *  short-circuits when auth is off or the user isn't signed in. */
+export async function syncOnLogin(): Promise<void> {
+  if (!AUTH_ENABLED) return;
+  if (inFlight) return inFlight;
+  inFlight = (async () => {
+    try {
+      if (!(await isAuthed())) return;
+      await reconcile();
+    } catch {
+      /* best-effort */
+    } finally {
+      inFlight = null;
+    }
+  })();
+  return inFlight;
+}
+
+/** Fire-and-forget single push after a local autosave. Leaves the record pending
+ *  on any failure so the next reconcile re-pushes it. */
+export async function pushOnSave(record: StoryRecord): Promise<void> {
+  if (!AUTH_ENABLED || !record?.id) return;
+  try {
+    if (!(await isAuthed())) return;
+    await pushOne(record);
+  } catch {
+    /* leave pending */
+  }
+}
+
+/** Fire-and-forget tombstone propagation after a local soft-delete. Reads the
+ *  local tombstone for its rev/deletedAt, then pushes the delete. */
+export async function pushDeletion(id: string): Promise<void> {
+  if (!AUTH_ENABLED || !id) return;
+  try {
+    if (!(await isAuthed())) return;
+    const rec = (await listAllRecordsForSync()).find((r) => r.id === id);
+    if (!rec || !rec.deletedAt) return; // not a tombstone / already gone
+    const ok = await pushDelete(id, rec.rev ?? 1, coerceEpoch(rec.deletedAt, Date.now()));
+    if (ok) await markRecordSynced(id, rec.rev ?? 1);
+  } catch {
+    /* leave pending */
+  }
+}

lib/persistence/cloudSyncClient.ts

@@ -0,0 +1,84 @@
+// Network bridge — the ONLY fetch layer between the local store / reconcile
+// engine and the cloud story API. Browser-only (imports the public AUTH_ENABLED
+// flag, never the server-only cloudStore).
+//
+// Two-layer short-circuit:
+//  1. AUTH_ENABLED=false (open-source build) → every method returns a safe empty
+//     value on its first line and NEVER issues a request.
+//  2. The signed-in gate is enforced ONCE by the caller — the reconcile engine
+//     checks isAuthed() before touching this bridge — so methods here don't
+//     re-run getUser() per call. If an unauthenticated request slips through
+//     anyway, the route 401s and the fault-tolerant fetch below maps it to the
+//     same safe empty value.
+//
+// Every request is fully fault-tolerant: any non-2xx / network error / parse
+// failure resolves to a safe value and never throws (best-effort sync).
+
+import { AUTH_ENABLED } from "@/lib/supabase/config";
+import type { StorySyncMeta, StorySyncEnvelope } from "./types";
+
+async function postJson<T>(url: string, body: unknown): Promise<T | null> {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** GET the cloud manifest (all rows incl. tombstones, lightweight). [] on any
+ *  failure / auth off. */
+export async function pullManifest(): Promise<StorySyncMeta[]> {
+  if (!AUTH_ENABLED) return [];
+  try {
+    const res = await fetch("/api/stories/manifest", { method: "GET" });
+    if (!res.ok) return [];
+    const data = (await res.json()) as { items?: StorySyncMeta[] };
+    return data.items ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** Pull full envelopes for the given ids. [] on empty ids / failure / auth off. */
+export async function pullBlobs(ids: string[]): Promise<StorySyncEnvelope[]> {
+  if (!AUTH_ENABLED || ids.length === 0) return [];
+  const data = await postJson<{ blobs?: StorySyncEnvelope[] }>(
+    "/api/stories/pull",
+    { ids },
+  );
+  return data?.blobs ?? [];
+}
+
+/** Push one envelope through the optimistic-concurrency RPC. Returns the
+ *  `{ stored, won }` result, or null on failure / auth off (caller leaves the
+ *  record pending for the next reconcile). */
+export async function pushBlob(
+  env: StorySyncEnvelope,
+): Promise<{ stored: StorySyncEnvelope | null; won: boolean } | null> {
+  if (!AUTH_ENABLED) return null;
+  return postJson<{ stored: StorySyncEnvelope | null; won: boolean }>(
+    "/api/stories/push",
+    env,
+  );
+}
+
+/** Propagate a soft-delete tombstone. false on failure / auth off / not-newer. */
+export async function pushDelete(
+  id: string,
+  rev: number,
+  deletedAt: number,
+): Promise<boolean> {
+  if (!AUTH_ENABLED) return false;
+  const data = await postJson<{ ok?: boolean }>("/api/stories/delete", {
+    id,
+    rev,
+    deletedAt,
+  });
+  return data?.ok ?? false;
+}

lib/persistence/localStore.ts

@@ -11,7 +11,7 @@ import type { Session } from "@infiplot/types";
 import { coerceOrientation } from "@infiplot/types";
 import { idbGet, idbGetAll, idbPut, idbDelete, idbCount, STORIES_STORE } from "./idb";
 import { slimSession } from "./sessionSlim";
-import { STORY_SCHEMA_VERSION, coerceEpoch, type StoryRecord, type StoryMeta } from "./types";
+import { STORY_SCHEMA_VERSION, coerceEpoch, type StoryRecord, type StoryMeta, type StorySyncEnvelope } from "./types";
 
 /** Max number of non-tombstoned stories retained locally. IndexedDB has ample
  *  quota, so this is generous vs the old localStorage cap of 20; it aligns with
@@ -186,3 +186,75 @@ export async function softDeleteStory(id: string): Promise<boolean> {
   };
   return idbPut(STORIES_STORE, updated);
 }
+
+// ── Sync support (story-cloud-sync) ─────────────────────────────────────────
+// These are the cloud-sync counterparts to the user-write path above. The
+// distinction matters: saveStorySession is a USER write (bumps rev,
+// synced→pending), while putSyncedRecord is a SYNC write (cloud is
+// authoritative: takes the cloud rev verbatim, marks synced, never bumps).
+
+/** Reconcile diff basis (local side): ALL records INCLUDING tombstones, with
+ *  rev/syncState intact — the local mirror of cloudStoryManifest's
+ *  tombstone-inclusive scan. [] when storage is unavailable. */
+export async function listAllRecordsForSync(): Promise<StoryRecord[]> {
+  return idbGetAll<StoryRecord>(STORIES_STORE);
+}
+
+/** Write a cloud-pulled version as the authoritative synced baseline:
+ *  rev/updatedAt/deletedAt taken from the envelope, syncState="synced", and
+ *  rev is NOT bumped (unlike saveStorySession). createdAt is preserved if a
+ *  local record already exists, else seeded from the envelope's updatedAt (the
+ *  cloud row carries no createdAt; createdAt is display-only). Keeps the
+ *  schemaVersion invariant and the slim session as-is. Returns false on write
+ *  failure (Req 3.3, 3.6). Runs retention housekeeping after a durable write. */
+export async function putSyncedRecord(
+  env: StorySyncEnvelope,
+): Promise<boolean> {
+  if (!env?.id) return false;
+  const existing = await idbGet<StoryRecord>(STORIES_STORE, env.id);
+  // Concurrency guard (symmetric with markRecordSynced's rev guard): if the local
+  // record was updated to a strictly newer version (rev → updatedAt) between
+  // reconcile's decision snapshot and this write, don't clobber it — leave it
+  // (pending) for the next reconcile to re-push. Otherwise a local autosave that
+  // lands mid-reconcile could be overwritten by a now-stale cloud version (a
+  // legitimate LWW winner silently lost).
+  if (existing) {
+    const er = existing.rev ?? 1;
+    const nr = env.rev ?? 1;
+    const eu = coerceEpoch(existing.updatedAt, 0);
+    const nu = coerceEpoch(env.updatedAt, 0);
+    if (er > nr || (er === nr && eu > nu)) return false;
+  }
+  const record: StoryRecord = {
+    id: env.id,
+    schemaVersion: STORY_SCHEMA_VERSION,
+    worldSetting: env.worldSetting ?? "",
+    styleGuide: env.styleGuide ?? "",
+    orientation: coerceOrientation(env.orientation),
+    sceneCount: env.sceneCount ?? 0,
+    createdAt: existing
+      ? coerceEpoch(existing.createdAt, env.updatedAt)
+      : coerceEpoch(env.updatedAt, Date.now()),
+    updatedAt: coerceEpoch(env.updatedAt, Date.now()),
+    rev: env.rev ?? 1,
+    deletedAt: env.deletedAt == null ? null : coerceEpoch(env.deletedAt, Date.now()),
+    syncState: "synced",
+    session: env.session,
+  };
+  const ok = await idbPut(STORIES_STORE, record);
+  if (ok) await enforceRetentionCap();
+  return ok;
+}
+
+/** Mark a local record synced after a successful push, aligning syncState to
+ *  the cloud-acknowledged baseline — but ONLY if the local record still matches
+ *  the rev we pushed. A newer local edit (rev moved past what we pushed) is left
+ *  pending so the next reconcile re-pushes the newer content. No-op if the
+ *  record is gone or already synced (Req 8.1). */
+export async function markRecordSynced(id: string, rev: number): Promise<void> {
+  const rec = await idbGet<StoryRecord>(STORIES_STORE, id);
+  if (!rec) return;
+  if ((rec.rev ?? 1) !== rev) return;
+  if (rec.syncState === "synced") return;
+  await idbPut(STORIES_STORE, { ...rec, syncState: "synced" });
+}

lib/persistence/types.ts

@@ -98,3 +98,34 @@ export type StoryRecord = {
    *  structured-clones objects, so this is stored as-is (no JSON.stringify). */
   session: Session;
 };
+
+// ── Cloud-sync wire types (story-cloud-sync) ────────────────────────────────
+
+/** Manifest projection of one cloud story — the lightweight metadata the
+ *  reconcile engine diffs against the local set. Unlike `StoryMeta` it CARRIES
+ *  the tombstone (`deletedAt`) and `rev`, because reconcile needs both to pick
+ *  a winner (rev → updatedAt last-write-wins) and to propagate soft-deletes.
+ *  Never carries the session blob — the manifest is the cheap diff basis. */
+export type StorySyncMeta = {
+  id: string;
+  rev: number;
+  /** epoch ms */
+  updatedAt: number;
+  /** Soft-delete tombstone (epoch ms) or null. */
+  deletedAt: number | null;
+};
+
+/** Full-payload carrier for pull/push between the local store and the cloud.
+ *  Extends the shared `SlimStoryBlob` with the two sync-ordering fields:
+ *   - `updatedAt` is the CLIENT-recorded modification time (NOT a server
+ *     `now()`), so when two devices collide on the same `rev`, `updatedAt`
+ *     stays a meaningful last-write-wins tiebreaker rather than always-now.
+ *   - `deletedAt` lets a tombstone ride the same envelope (delete propagation).
+ *  `rev` is already on `SlimStoryBlob`, so the envelope = blob + (updatedAt,
+ *  deletedAt). This is the single shape crossing the API at pull/push. */
+export type StorySyncEnvelope = SlimStoryBlob & {
+  /** epoch ms */
+  updatedAt: number;
+  /** Soft-delete tombstone (epoch ms) or null. */
+  deletedAt: number | null;
+};