jazz-tools 0.20.17 → 0.20.19

package/src/tools/implementation/createContext.ts

@@ -23,6 +23,10 @@ import {
 import { AuthCredentials, NewAccountProps } from "../types.js";
 import { activeAccountContext } from "./activeAccountContext.js";
 import { AnonymousJazzAgent } from "./anonymousJazzAgent.js";
+import {
+  type SessionDurabilityMarker,
+  makeDurabilityMarkerListener,
+} from "./sessionDurabilityMarker.js";
 
 export type Credentials = {
   accountID: ID<Account>;
@@ -38,9 +42,17 @@ export interface SessionProvider {
     accountID: ID<Account>,
     sessionID: SessionID,
   ) => Promise<{ sessionDone: () => void }>;
+  /**
+   * When present, the context marks sessions as unsafe-to-reuse while they
+   * have transactions sent to a sync server but not yet persisted locally,
+   * and the provider must skip marked sessions in acquireSession.
+   */
+  durabilityMarker?: SessionDurabilityMarker;
 }
 
 export class MockSessionProvider implements SessionProvider {
+  durabilityMarker?: SessionDurabilityMarker;
+
   async acquireSession(
     accountID: ID<Account>,
     crypto: CryptoProvider,
@@ -118,6 +130,7 @@ export async function createJazzContextFromExistingCredentials<
   sessionProvider,
   onLogOut,
   asActiveAccount,
+  experimental_clockSyncFromServerPings,
 }: {
   credentials: Credentials;
   peers: Peer[];
@@ -128,12 +141,25 @@ export async function createJazzContextFromExistingCredentials<
   onLogOut?: () => void;
   storage?: StorageAPI;
   asActiveAccount: boolean;
+  experimental_clockSyncFromServerPings?: boolean;
 }): Promise<JazzContextWithAccount<InstanceOfSchema<S>>> {
   const { sessionID, sessionDone } = await sessionProvider.acquireSession(
     credentials.accountID,
     crypto,
   );
 
+  // Defense in depth: acquireSession implementations must never return a
+  // session that is still marked unsafe to reuse (see SessionProvider docs)
+  if (
+    sessionProvider.durabilityMarker &&
+    (await sessionProvider.durabilityMarker.isSet(sessionID))
+  ) {
+    console.warn(
+      "Session provider returned a session still marked unsafe to reuse; a crash may fork it",
+      sessionID,
+    );
+  }
+
   const CurrentAccountSchema =
     PropsAccountSchema ?? (RegisteredSchemas["Account"] as unknown as S);
 
@@ -149,6 +175,10 @@ export async function createJazzContextFromExistingCredentials<
     crypto,
     storage,
     enableFullStorageReconciliation: !!storage,
+    experimental_clockSyncFromServerPings,
+    onLocalStoreDurabilityChange: makeDurabilityMarkerListener(
+      sessionProvider.durabilityMarker,
+    ),
     migration: async (rawAccount, _node, creationProps) => {
       const account = AccountClass.fromRaw(rawAccount) as InstanceOfSchema<S>;
       if (asActiveAccount) {
@@ -193,6 +223,7 @@ export async function createJazzContextForNewAccount<
   onLogOut,
   storage,
   sessionProvider,
+  experimental_clockSyncFromServerPings,
 }: {
   creationProps: { name: string };
   initialAgentSecret?: AgentSecret;
@@ -203,6 +234,7 @@ export async function createJazzContextForNewAccount<
   onLogOut?: () => Promise<void>;
   storage?: StorageAPI;
   sessionProvider: SessionProvider;
+  experimental_clockSyncFromServerPings?: boolean;
 }): Promise<JazzContextWithAccount<InstanceOfSchema<S>>> {
   const CurrentAccountSchema =
     PropsAccountSchema ?? (RegisteredSchemas["Account"] as unknown as S);
@@ -218,6 +250,10 @@ export async function createJazzContextForNewAccount<
     initialAgentSecret,
     storage,
     enableFullStorageReconciliation: !!storage,
+    experimental_clockSyncFromServerPings,
+    onLocalStoreDurabilityChange: makeDurabilityMarkerListener(
+      sessionProvider.durabilityMarker,
+    ),
     migration: async (rawAccount, _node, creationProps) => {
       const account = AccountClass.fromRaw(rawAccount) as InstanceOfSchema<S>;
       activeAccountContext.set(account);
@@ -263,6 +299,7 @@ export async function createJazzContext<
   sessionProvider: SessionProvider;
   authSecretStorage: AuthSecretStorage;
   storage?: StorageAPI;
+  experimental_clockSyncFromServerPings?: boolean;
 }) {
   const crypto = options.crypto;
 
@@ -294,6 +331,8 @@ export async function createJazzContext<
       },
       storage: options.storage,
       asActiveAccount: true,
+      experimental_clockSyncFromServerPings:
+        options.experimental_clockSyncFromServerPings,
     });
   } else {
     const secretSeed = options.crypto.newRandomSecretSeed();
@@ -318,6 +357,8 @@ export async function createJazzContext<
         await authSecretStorage.clearWithoutNotify();
       },
       storage: options.storage,
+      experimental_clockSyncFromServerPings:
+        options.experimental_clockSyncFromServerPings,
     });
 
     if (!options.newAccountProps) {
@@ -341,11 +382,13 @@ export function createAnonymousJazzContext({
   syncWhen,
   crypto,
   storage,
+  experimental_clockSyncFromServerPings,
 }: {
   peers: Peer[];
   syncWhen?: SyncWhen;
   crypto: CryptoProvider;
   storage?: StorageAPI;
+  experimental_clockSyncFromServerPings?: boolean;
 }): JazzContextWithAgent {
   const agentSecret = crypto.newRandomAgentSecret();
 
@@ -355,6 +398,7 @@ export function createAnonymousJazzContext({
     crypto,
     syncWhen,
     !!storage,
+    { experimental_clockSyncFromServerPings },
   );
 
   for (const peer of peers) {

package/src/tools/implementation/sessionDurabilityMarker.ts

@@ -0,0 +1,93 @@
+import type { LocalStoreDurabilityListener, SessionID } from "cojson";
+
+/**
+ * Persists a per-session "dirty" flag that survives crashes.
+ *
+ * The flag is set while the session has transactions that were sent to a sync
+ * server but are not yet durably stored locally. If the process dies inside
+ * that window, local storage is behind what the server received for the
+ * session, and reusing it would fork the session's hash chain. Session
+ * providers must skip sessions whose flag is still set and mint a fresh
+ * session instead.
+ */
+export interface SessionDurabilityMarker {
+  /**
+   * Must be initiated synchronously: the write has to win the race against
+   * the network send that immediately follows it.
+   */
+  set(sessionID: SessionID): void;
+  clear(sessionID: SessionID): void;
+  isSet(sessionID: SessionID): boolean | Promise<boolean>;
+}
+
+/**
+ * Storage key under which a session's dirty flag is persisted. Shared by all
+ * platform marker implementations so the key format cannot silently diverge.
+ */
+export function sessionDurabilityMarkerKey(sessionID: SessionID) {
+  return `jazz_session_dirty_${sessionID}`;
+}
+
+export const SESSION_DURABILITY_CLEAR_DEBOUNCE_MS = 200;
+
+/**
+ * Adapts a SessionDurabilityMarker to LocalNode's onLocalStoreDurabilityChange
+ * hook. Setting is immediate (correctness-critical); clearing is debounced so
+ * the marker doesn't churn on every batch while the user is actively editing.
+ * A crash inside the debounce at worst abandons one session unnecessarily.
+ *
+ * Returns undefined when no marker is provided, matching the optional
+ * listener slot on LocalNode creation options.
+ */
+export function makeDurabilityMarkerListener(
+  marker: SessionDurabilityMarker,
+  clearDebounceMs?: number,
+): LocalStoreDurabilityListener;
+export function makeDurabilityMarkerListener(
+  marker: SessionDurabilityMarker | undefined,
+  clearDebounceMs?: number,
+): LocalStoreDurabilityListener | undefined;
+export function makeDurabilityMarkerListener(
+  marker: SessionDurabilityMarker | undefined,
+  clearDebounceMs: number = SESSION_DURABILITY_CLEAR_DEBOUNCE_MS,
+): LocalStoreDurabilityListener | undefined {
+  if (!marker) {
+    return undefined;
+  }
+
+  let clearTimer: ReturnType<typeof setTimeout> | undefined;
+  let markerIsSet = false;
+
+  return (hasPending, sessionID) => {
+    if (clearTimer !== undefined) {
+      clearTimeout(clearTimer);
+      clearTimer = undefined;
+    }
+
+    if (hasPending) {
+      // A window reopening within the clear debounce finds the marker still
+      // set: skip the write so steady-state editing costs no marker I/O
+      if (markerIsSet) {
+        return;
+      }
+
+      try {
+        marker.set(sessionID);
+        markerIsSet = true;
+      } catch (err) {
+        console.warn("Failed to set session durability marker", err);
+      }
+    } else {
+      clearTimer = setTimeout(() => {
+        clearTimer = undefined;
+
+        try {
+          marker.clear(sessionID);
+          markerIsSet = false;
+        } catch (err) {
+          console.warn("Failed to clear session durability marker", err);
+        }
+      }, clearDebounceMs);
+    }
+  };
+}

package/src/tools/implementation/zodSchema/schemaTypes/CoMapSchema.ts

@@ -524,11 +524,19 @@ export class CoMapSchema<
     Owner,
     DefaultResolveQuery
   > {
+    const extendedShape = {} as z.core.util.Extend<Shape, ExtendShape>;
+
+    Object.defineProperties(
+      extendedShape,
+      Object.getOwnPropertyDescriptors(this.shape),
+    );
+    Object.defineProperties(
+      extendedShape,
+      Object.getOwnPropertyDescriptors(shape),
+    );
+
     return this.copy({
-      shape: {
-        ...this.shape,
-        ...shape,
-      } as z.core.util.Extend<Shape, ExtendShape>,
+      shape: extendedShape,
     });
   }
 
@@ -549,11 +557,19 @@ export class CoMapSchema<
     Owner,
     DefaultResolveQuery
   > {
+    const extendedShape = {} as z.core.util.Extend<Shape, ExtendShape>;
+
+    Object.defineProperties(
+      extendedShape,
+      Object.getOwnPropertyDescriptors(this.shape),
+    );
+    Object.defineProperties(
+      extendedShape,
+      Object.getOwnPropertyDescriptors(shape),
+    );
+
     return this.copy({
-      shape: {
-        ...this.shape,
-        ...shape,
-      } as z.core.util.Extend<Shape, ExtendShape>,
+      shape: extendedShape,
     });
   }
 

package/src/tools/implementation/zodSchema/unionUtils.ts

@@ -8,6 +8,7 @@ import {
   DiscriminableCoValueSchemas,
   DiscriminableCoreCoValueSchema,
   SchemaUnionDiscriminator,
+  SchemaUnionNoMatchingVariantError,
   createCoreCoMapSchema,
 } from "../../internal.js";
 import {
@@ -118,7 +119,7 @@ export function schemaUnionDiscriminatorFor(
         }
       }
 
-      throw new Error(
+      throw new SchemaUnionNoMatchingVariantError(
         "co.discriminatedUnion() of collaborative types with no matching discriminator value found",
       );
     };

package/src/tools/internal.ts

@@ -33,6 +33,7 @@ export * from "./lib/cache.js";
 export * from "./lib/utils.js";
 export * from "./lib/utilityTypes.js";
 export * from "./implementation/createContext.js";
+export * from "./implementation/sessionDurabilityMarker.js";
 
 export * from "./types.js";
 export * from "./implementation/zodSchema/zodSchema.js";

package/src/tools/subscribe/SubscriptionScope.ts

@@ -8,6 +8,7 @@ import {
   NotLoaded,
   type RefEncoded,
   type RefsToResolve,
+  SchemaUnionNoMatchingVariantError,
   TypeSym,
   createUnloadedCoValue,
   instantiateRefEncodedFromRaw,
@@ -173,7 +174,28 @@ export class SubscriptionScope<D extends CoValue> {
           }
 
           this.migrating = true;
-          const instance = instantiateRefEncodedFromRaw(this.schema, value);
+          let instance: CoValue;
+          try {
+            instance = instantiateRefEncodedFromRaw(this.schema, value);
+          } catch (error) {
+            // A discriminated union whose stored value doesn't match any
+            // declared variant would otherwise hang load() — the throw
+            // escapes into cojson's async update loop and nothing settles.
+            // Treat it as unavailable so load() resolves. Other
+            // instantiation errors (e.g. CoVector dimension mismatch) keep
+            // throwing loudly, as they indicate schema drift that callers
+            // should surface.
+            if (!(error instanceof SchemaUnionNoMatchingVariantError)) {
+              throw error;
+            }
+            this.migrationFailed = true;
+            this.migrated = true;
+            console.error(
+              `Schema instantiation failed for ${this.id}: ${error.message}`,
+            );
+            this.handleUpdate(CoValueLoadingState.UNAVAILABLE);
+            return;
+          }
           try {
             applyCoValueMigrations(instance);
           } catch (error) {

package/src/tools/tests/coMap.test.ts

@@ -3057,6 +3057,21 @@ describe("co.map schema", () => {
 
       expect(person.extraField).toEqual("extra");
     });
+
+    test("handles circular references", () => {
+      const BasePerson = co.map({
+        name: z.string(),
+      });
+
+      const Person = BasePerson.extend({
+        get friends() {
+          return co.list(Person);
+        },
+      });
+
+      expect(Person.shape.name).toBeDefined();
+      expect(Person.shape.friends).toBeDefined();
+    });
   });
 
   describe("safeExtend()", () => {
@@ -3101,6 +3116,21 @@ describe("co.map schema", () => {
 
       expect(person.extraField).toEqual("extra");
     });
+
+    test("handles circular references", () => {
+      const BasePerson = co.map({
+        name: z.string(),
+      });
+
+      const Person = BasePerson.safeExtend({
+        get friends(): co.List<any> {
+          return co.list(Person);
+        },
+      });
+
+      expect(Person.shape.name).toBeDefined();
+      expect(Person.shape.friends).toBeDefined();
+    });
   });
 
   describe("schema configuration inheritance", () => {

package/src/tools/tests/createContext.test.ts

@@ -16,6 +16,7 @@ import {
   createJazzContextForNewAccount,
   createJazzContextFromExistingCredentials,
   MockSessionProvider,
+  z,
 } from "../exports";
 import { activeAccountContext } from "../implementation/activeAccountContext";
 import {
@@ -144,6 +145,69 @@ describe("createContext methods", () => {
       );
     });
 
+    test("rejects when the migration throws synchronously", async () => {
+      const CustomAccount = co.account().withMigration(() => {
+        throw new Error("migration failed");
+      });
+
+      const account = await createJazzTestAccount({
+        isCurrentActiveAccount: true,
+      });
+
+      const credentials: Credentials = {
+        accountID: account.$jazz.id,
+        secret: account.$jazz.localNode.getCurrentAgent().agentSecret,
+      };
+
+      await expect(
+        createJazzContextFromExistingCredentials({
+          credentials,
+          peers: [getPeerConnectedToTestSyncServer()],
+          crypto: Crypto,
+          AccountSchema: CustomAccount,
+          sessionProvider: randomSessionProvider,
+          asActiveAccount: true,
+        }),
+      ).rejects.toThrow("migration failed");
+    }, 2000);
+
+    test("does not hang when an account migration loads a discriminated union with no matching variant", async () => {
+      const TypeA = co.map({ type: z.literal("a"), data: z.string() });
+      const TypeB = co.map({ type: z.literal("b"), data: z.string() });
+
+      const account = await createJazzTestAccount({
+        isCurrentActiveAccount: true,
+      });
+      const typeAValue = TypeA.create({ type: "a", data: "hello" }, account);
+
+      // Schema only knows TypeB, so loading a TypeA value through it used
+      // to throw from the async subscription callback and leave load()
+      // unsettled, hanging the account migration and createContext with it.
+      const UnionBOnly = co.discriminatedUnion("type", [TypeB]);
+
+      const AccountSchema = co
+        .account()
+        .withMigration(async (loadedAccount) => {
+          await UnionBOnly.load(typeAValue.$jazz.id, {
+            loadAs: loadedAccount,
+          });
+        });
+
+      const context = await createJazzContextFromExistingCredentials({
+        credentials: {
+          accountID: account.$jazz.id,
+          secret: account.$jazz.localNode.getCurrentAgent().agentSecret,
+        },
+        peers: [getPeerConnectedToTestSyncServer()],
+        crypto: Crypto,
+        AccountSchema,
+        sessionProvider: randomSessionProvider,
+        asActiveAccount: true,
+      });
+      expect(context.account).toBeDefined();
+      context.done();
+    }, 2000);
+
     test("calls onLogOut callback when logging out", async () => {
       const account = await createJazzTestAccount({
         isCurrentActiveAccount: true,

package/src/tools/tests/schemaUnion.test.ts

@@ -2,6 +2,7 @@ import { WasmCrypto } from "cojson/crypto/WasmCrypto";
 import { assert, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import {
   Account,
+  CoValueLoadingState,
   CryptoProvider,
   Loaded,
   co,
@@ -96,6 +97,24 @@ describe("SchemaUnion", () => {
     expect(loadedCheckboxWidget.type).toBe("checkbox");
   });
 
+  it("load() settles as unavailable when the stored value matches no declared variant", async () => {
+    const slider = SliderWidget.create(
+      { type: "slider", min: 0, max: 100 },
+      { owner: me },
+    );
+
+    // Union that doesn't include "slider" — the runtime discriminator will
+    // throw SchemaUnionNoMatchingVariantError from inside the subscription
+    // callback. load() must settle as unavailable rather than hang (async
+    // path) or reject (sync path).
+    const CheckboxOnlyUnion = co.discriminatedUnion("type", [CheckboxWidget]);
+    const loaded = await CheckboxOnlyUnion.load(slider.$jazz.id, {
+      loadAs: me,
+    });
+
+    expect(loaded.$jazz.loadingState).toBe(CoValueLoadingState.UNAVAILABLE);
+  });
+
   it("should integrate with subscribeToCoValue correctly", async () => {
     const buttonWidget = BlueButtonWidget.create(
       { type: "button", color: "blue", label: "Submit", blueness: 100 },

package/src/tools/tests/sessionDurabilityMarker.test.ts

@@ -0,0 +1,183 @@
+import type { SessionID } from "cojson";
+import { WasmCrypto } from "cojson/crypto/WasmCrypto";
+import { LocalNode } from "cojson";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { makeDurabilityMarkerListener } from "../implementation/sessionDurabilityMarker.js";
+import {
+  Credentials,
+  InMemoryKVStore,
+  KvStoreContext,
+  MockSessionProvider,
+  createJazzContextFromExistingCredentials,
+} from "../exports.js";
+import {
+  createJazzTestAccount,
+  getPeerConnectedToTestSyncServer,
+  setupJazzTestSync,
+} from "../testing.js";
+
+const sessionID = "co_ztest_session_ztest" as SessionID;
+
+function mockMarker() {
+  return { set: vi.fn(), clear: vi.fn(), isSet: vi.fn(() => false) };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("makeDurabilityMarkerListener", () => {
+  test("sets the marker synchronously when the window opens", () => {
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker);
+
+    listener(true, sessionID);
+
+    expect(marker.set).toHaveBeenCalledWith(sessionID);
+    expect(marker.clear).not.toHaveBeenCalled();
+  });
+
+  test("clears the marker only after the debounce delay", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    expect(marker.clear).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(200);
+    expect(marker.clear).toHaveBeenCalledWith(sessionID);
+  });
+
+  test("a new pending window cancels a scheduled clear", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    listener(true, sessionID); // window re-opens within the debounce
+    vi.advanceTimersByTime(500);
+
+    expect(marker.clear).not.toHaveBeenCalled();
+  });
+
+  test("consecutive clears don't leave an orphaned timer that clears a fresh set", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    listener(false, sessionID); // must supersede (not orphan) the first timer
+    listener(true, sessionID); // window re-opens: no clear may fire anymore
+    vi.advanceTimersByTime(500);
+
+    expect(marker.clear).not.toHaveBeenCalled();
+  });
+
+  test("a reopen within the debounce doesn't rewrite the still-set marker", () => {
+    vi.useFakeTimers();
+    const marker = mockMarker();
+    const listener = makeDurabilityMarkerListener(marker, 200);
+
+    listener(true, sessionID);
+    listener(false, sessionID);
+    listener(true, sessionID); // marker was never cleared: no write needed
+
+    expect(marker.set).toHaveBeenCalledTimes(1);
+
+    // ...but after an actual clear, the next window writes again
+    listener(false, sessionID);
+    vi.advanceTimersByTime(200);
+    listener(true, sessionID);
+
+    expect(marker.clear).toHaveBeenCalledTimes(1);
+    expect(marker.set).toHaveBeenCalledTimes(2);
+  });
+
+  test("returns undefined when no marker is provided", () => {
+    expect(makeDurabilityMarkerListener(undefined)).toBeUndefined();
+  });
+
+  test("marker errors are swallowed with a warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const marker = mockMarker();
+    marker.set.mockImplementation(() => {
+      throw new Error("quota exceeded");
+    });
+    const listener = makeDurabilityMarkerListener(marker);
+
+    expect(() => listener(true, sessionID)).not.toThrow();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+const Crypto = await WasmCrypto.create();
+KvStoreContext.getInstance().initialize(new InMemoryKVStore());
+
+describe("createContext wiring", () => {
+  test("passes a durability listener to LocalNode when the provider has a marker", async () => {
+    await setupJazzTestSync();
+    const account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const credentials: Credentials = {
+      accountID: account.$jazz.id,
+      secret: account.$jazz.localNode.getCurrentAgent().agentSecret,
+    };
+
+    const spy = vi.spyOn(LocalNode, "withLoadedAccount");
+
+    const provider = new MockSessionProvider();
+    provider.durabilityMarker = mockMarker();
+
+    const context = await createJazzContextFromExistingCredentials({
+      credentials,
+      peers: [getPeerConnectedToTestSyncServer()],
+      crypto: Crypto,
+      sessionProvider: provider,
+      asActiveAccount: false,
+    });
+    context.done();
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onLocalStoreDurabilityChange: expect.any(Function),
+      }),
+    );
+  });
+
+  test("passes no listener when the provider has no marker", async () => {
+    await setupJazzTestSync();
+    const account = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const credentials: Credentials = {
+      accountID: account.$jazz.id,
+      secret: account.$jazz.localNode.getCurrentAgent().agentSecret,
+    };
+
+    const spy = vi.spyOn(LocalNode, "withLoadedAccount");
+
+    const context = await createJazzContextFromExistingCredentials({
+      credentials,
+      peers: [getPeerConnectedToTestSyncServer()],
+      crypto: Crypto,
+      sessionProvider: new MockSessionProvider(),
+      asActiveAccount: false,
+    });
+    context.done();
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        onLocalStoreDurabilityChange: undefined,
+      }),
+    );
+  });
+});