@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/contracts/validate.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateProviderSatisfiesContract = validateProviderSatisfiesContract;
+exports.contractShapeChanges = contractShapeChanges;
 exports.validateImmutability = validateImmutability;
 exports.validateAlsoImplements = validateAlsoImplements;
+const lodash_1 = require("lodash");
 const types_1 = require("./types");
 function ok() {
     return { valid: true, errors: [] };
@@ -15,12 +17,13 @@ function merge(results) {
     return { valid: errors.length === 0, errors };
 }
 /**
- * Check whether `implField` satisfies the contract's `contractField`.
- * - Types must match exactly.
- * - If the contract field is required, the implementation must also be required.
- * - `isArray` must match.
+ * Check whether `implField` satisfies the contract's `contractField` for its callers.
+ * - Types must match exactly, and so must `isArray`.
+ * - What callers receive: a field the contract requires must be required.
+ * - What callers send: a field the contract makes optional must be optional, since callers may
+ *   leave it out; the implementation may make a required one optional.
  */
-function isFieldCompatible(contractField, implField) {
+function isFieldCompatible(contractField, implField, direction) {
     if (contractField.type !== implField.type) {
         return `type mismatch: contract requires '${contractField.type}', implementation has '${implField.type}'`;
     }
@@ -30,9 +33,12 @@ function isFieldCompatible(contractField, implField) {
     if (!contractField.isArray && implField.isArray) {
         return "contract requires scalar, implementation is an array";
     }
-    if (!contractField.optional && implField.optional) {
+    if (direction !== "input" && !contractField.optional && implField.optional) {
         return "contract requires a required field, implementation marks it optional";
     }
+    if (direction !== "output" && contractField.optional && !implField.optional) {
+        return "contract marks the field optional, implementation requires it";
+    }
     return null;
 }
 function validateTableFields(contractTable, implTable) {
@@ -50,7 +56,7 @@ function validateTableFields(contractTable, implTable) {
             }
             continue;
         }
-        const compat = isFieldCompatible(contractField, implField);
+        const compat = isFieldCompatible(contractField, implField, "both");
         if (compat) {
             errors.push({
                 kind: "field",
@@ -89,7 +95,7 @@ function validateToolFields(contractTool, implTool, direction) {
             }
             continue;
         }
-        const compat = isFieldCompatible(contractField, implField);
+        const compat = isFieldCompatible(contractField, implField, direction);
         if (compat) {
             errors.push({
                 kind: "field",
@@ -129,7 +135,7 @@ function validateEventFields(contractEvent, implEvent) {
             }
             continue;
         }
-        const compat = isFieldCompatible(contractField, implField);
+        const compat = isFieldCompatible(contractField, implField, "output");
         if (compat) {
             errors.push({
                 kind: "field",
@@ -226,12 +232,132 @@ function validateProviderSatisfiesContract(impl, contract) {
     }
     return errors.length === 0 ? ok() : fail(errors);
 }
+/**
+ * Keys the frozen comparison ignores: a stable version's descriptions may change, and so may a
+ * tool's policy (`remoteAccessLevel`, `requiresWorkflowRun`), which isn't part of its shape.
+ */
+const IGNORED_KEYS = new Set([
+    "description",
+    "usageDescription",
+    "remoteAccessLevel",
+    "requiresWorkflowRun",
+]);
+/**
+ * IR keys added after contracts were first frozen. A shape that has one matches a shape that
+ * doesn't (a provider built with an older SDK); where both have it, they must agree.
+ */
+const LATER_IR_KEYS = new Set(["fields", "enumValues", "value"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function uniqueNames(items) {
+    const byName = new Map();
+    for (const item of items) {
+        if (!isRecord(item) || typeof item.name !== "string" || byName.has(item.name)) {
+            return undefined;
+        }
+        byName.set(item.name, item);
+    }
+    return byName;
+}
+/**
+ * Structural equality for the frozen comparison. Members and fields match by name in any order,
+ * `enumValues` as sets, and keys in any order; descriptions and tool policy are ignored, and so is
+ * a later IR key only one side has. A `defaultValue` must be equal as data.
+ */
+function sameShape(a, b, key) {
+    if (key === "defaultValue") {
+        // Legacy schemaToFields retains Zod's default factories. Compare only their wire data,
+        // as the previous JSON comparison did, without executing or comparing factory identities.
+        return (0, lodash_1.isEqual)(JSON.parse(JSON.stringify({ value: a })), JSON.parse(JSON.stringify({ value: b })));
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (key === "enumValues") {
+            const values = new Set(b);
+            return new Set(a).size === values.size && a.every((value) => values.has(value));
+        }
+        if (a.length !== b.length) {
+            return false;
+        }
+        const aByName = uniqueNames(a);
+        const bByName = uniqueNames(b);
+        if (aByName && bByName) {
+            return [...aByName].every(([name, item]) => bByName.has(name) && sameShape(item, bByName.get(name)));
+        }
+        return a.every((item, index) => sameShape(item, b[index]));
+    }
+    if (isRecord(a) && isRecord(b)) {
+        for (const name of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            const left = a[name];
+            const right = b[name];
+            if (IGNORED_KEYS.has(name) ||
+                (left === undefined && right === undefined) ||
+                (LATER_IR_KEYS.has(name) && (left === undefined || right === undefined))) {
+                continue;
+            }
+            if (!sameShape(left, right, name)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return a === b;
+}
+/** A contract's member lists, with what to call one member of each in a change. */
+const MEMBER_KINDS = [
+    ["tables", "table"],
+    ["tools", "tool"],
+    ["observables", "observable"],
+    ["events", "event"],
+];
+/**
+ * What changed between two shapes of one contract version, member by member: a table, tool,
+ * observable, or event that was added, removed, or changed. Empty when the shapes match.
+ * Descriptions and tool policy are ignored, as in {@link validateImmutability}.
+ *
+ * @param existing - The frozen shape.
+ * @param incoming - The shape to compare with it.
+ * @returns One line per changed member, such as `tool add-item changed`.
+ */
+function contractShapeChanges(existing, incoming) {
+    const changes = [];
+    for (const [kind, label] of MEMBER_KINDS) {
+        const beforeMembers = existing[kind] ?? [];
+        const afterMembers = incoming[kind] ?? [];
+        // Do not collapse duplicate names: host-backed registrations can reach this comparison
+        // without isolated-artifact validation. Preserve the list comparison for such inputs.
+        if (!uniqueNames(beforeMembers) || !uniqueNames(afterMembers)) {
+            if (!sameShape(beforeMembers, afterMembers)) {
+                changes.push(`${label} list changed (duplicate member names)`);
+            }
+            continue;
+        }
+        const before = new Map(beforeMembers.map((member) => [member.name, member]));
+        const after = new Map(afterMembers.map((member) => [member.name, member]));
+        for (const [name, member] of before) {
+            if (!after.has(name))
+                changes.push(`${label} ${name} was removed`);
+            else if (!sameShape(member, after.get(name)))
+                changes.push(`${label} ${name} changed`);
+        }
+        for (const name of after.keys()) {
+            if (!before.has(name))
+                changes.push(`${label} ${name} was added`);
+        }
+    }
+    return changes;
+}
 /**
  * Validate that a frozen (stable) contract definition has not been modified.
  * If the existing definition has no `devTag` it is frozen; the incoming
- * definition must be structurally identical and also stable.
+ * definition must have the same shape and also be stable.
  * Dev contracts (`devTag: "dev"`) may change freely but cannot be registered
  * once a stable version exists for that contract+version.
+ *
+ * Descriptions may change on a frozen version (to point callers at a newer one, say), and so
+ * may a tool's policy (`remoteAccessLevel`, `requiresWorkflowRun`); member, field, and key order
+ * don't matter. IR keys added later (`fields`, `enumValues`, and an
+ * observable's `value`) are compared only when both definitions have them.
  */
 function validateImmutability(existing, incoming) {
     if (existing.devTag === "dev") {
@@ -247,25 +373,13 @@ function validateImmutability(existing, incoming) {
             },
         ]);
     }
-    // Deep-compare the shapes. We serialize to JSON for a simple structural comparison.
-    const existingShape = JSON.stringify({
-        tables: existing.tables,
-        tools: existing.tools,
-        observables: existing.observables,
-        events: existing.events ?? [],
-    });
-    const incomingShape = JSON.stringify({
-        tables: incoming.tables,
-        tools: incoming.tools,
-        observables: incoming.observables,
-        events: incoming.events ?? [],
-    });
-    if (existingShape !== incomingShape) {
+    const changes = contractShapeChanges(existing, incoming);
+    if (changes.length > 0) {
         return fail([
             {
                 kind: "contract",
                 name: (0, types_1.contractKey)(existing.contractId, existing.version),
-                message: `Stable contract ${existing.name} v${existing.version} is frozen and cannot be modified`,
+                message: `Stable contract ${existing.name} v${existing.version} is frozen and cannot be modified (${changes.join("; ")})`,
             },
         ]);
     }

package/dist/data/change-tracking.d.ts

@@ -59,7 +59,12 @@ export type IChangeRecord = z.infer<typeof changeRecordSchema>;
  * - `appliedClock` stamps `appliedAt` at insert time (per-device sync watermark)
  */
 export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
+    /**
+     * Writers fire this after storing change rows, whether written on this device, applied from a
+     * peer, or backfilled. Sync listens to advertise its latest `appliedAt`.
+     */
     readonly dataChangedEmitter: Emitter<IChangeRecord>;
+    /** Subscribe side of {@link dataChangedEmitter}. */
     readonly dataChanged: Event<IChangeRecord>;
     /**
      * Hybrid logical clock for author write times (`createdAt`, `supersededAt`).
@@ -112,15 +117,16 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      */
     filterToDeletedIds(recordIds: string[]): Promise<string[]>;
     /**
-     * Find recordIds that have no change records at all.
+     * Find recordIds that have no change records, in any table or only in `tableName`.
      *
      * This is useful for identifying records that were never synced
      * or have been completely cleaned up.
      *
      * @param recordIds - Array of recordIds to check
+     * @param tableName - Limit the lookup to this table; omitted checks across all tables
      * @returns Array of recordIds with no change records
      */
-    filterToMissingIds(recordIds: string[]): Promise<string[]>;
+    filterToMissingIds(recordIds: string[], tableName?: string): Promise<string[]>;
     /**
      * Find changeIds that we do not have
      *
@@ -214,12 +220,18 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      */
     deleteSupersededChangesOlderThan(tableName: string, beforeTimestamp: number): Promise<void>;
     /**
-     * Bulk delete changes
+     * Bulk delete changes by ID.
      *
-     * @param tableName - Name of the table to compact
-     * @param beforeTimestamp - Delete changes superseded before this timestamp
+     * @param changeIds - IDs of the change rows to delete
      */
     deleteChanges(changeIds: string[]): Promise<void>;
+    /**
+     * Delete every change row for one table, active or superseded. Used when a table is deleted or
+     * becomes local-only: its rows stop syncing until a later schema enables sync again.
+     *
+     * @param tableName - Full name of the tracked table, as stored in each row's `tableName`
+     */
+    deleteTableChanges(tableName: string): Promise<void>;
     /**
      * Clear inline values on insert changes (op='set', path='/') for a specific table.
      * These values are no longer needed since they are resolved from the source table at query time.

package/dist/data/change-tracking.js

@@ -63,7 +63,12 @@ const changeTrackingV2TableMetaData = {
  * - `appliedClock` stamps `appliedAt` at insert time (per-device sync watermark)
  */
 class ChangeTrackingTable extends orm_1.SQLDataSource {
+    /**
+     * Writers fire this after storing change rows, whether written on this device, applied from a
+     * peer, or backfilled. Sync listens to advertise its latest `appliedAt`.
+     */
     dataChangedEmitter;
+    /** Subscribe side of {@link dataChangedEmitter}. */
     dataChanged;
     /**
      * Hybrid logical clock for author write times (`createdAt`, `supersededAt`).
@@ -171,15 +176,16 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         return deletedRecordsResult.map((d) => d.recordId);
     }
     /**
-     * Find recordIds that have no change records at all.
+     * Find recordIds that have no change records, in any table or only in `tableName`.
      *
      * This is useful for identifying records that were never synced
      * or have been completely cleaned up.
      *
      * @param recordIds - Array of recordIds to check
+     * @param tableName - Limit the lookup to this table; omitted checks across all tables
      * @returns Array of recordIds with no change records
      */
-    async filterToMissingIds(recordIds) {
+    async filterToMissingIds(recordIds, tableName) {
         if (recordIds.length === 0)
             return [];
         await this.initTable();
@@ -193,8 +199,9 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
       FROM InputRecordIds AS i
       LEFT JOIN "${this.tableName}" AS existing
         ON i.recordId = existing.recordId
+        ${tableName === undefined ? "" : "AND existing.tableName = ?"}
       WHERE existing.recordId IS NULL
-    `, recordIds);
+    `, tableName === undefined ? recordIds : [...recordIds, tableName]);
         return missingRecordsResult.map((d) => d.recordId);
     }
     /**
@@ -443,10 +450,9 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
     `, [tableName, beforeTimestamp]);
     }
     /**
-     * Bulk delete changes
+     * Bulk delete changes by ID.
      *
-     * @param tableName - Name of the table to compact
-     * @param beforeTimestamp - Delete changes superseded before this timestamp
+     * @param changeIds - IDs of the change rows to delete
      */
     async deleteChanges(changeIds) {
         await this.initTable();
@@ -455,6 +461,16 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
       WHERE changeId IN (${changeIds.map((_c) => "?").join()})
     `, changeIds);
     }
+    /**
+     * Delete every change row for one table, active or superseded. Used when a table is deleted or
+     * becomes local-only: its rows stop syncing until a later schema enables sync again.
+     *
+     * @param tableName - Full name of the tracked table, as stored in each row's `tableName`
+     */
+    async deleteTableChanges(tableName) {
+        await this.initTable();
+        await this.db.exec(`DELETE FROM "${this.tableName}" WHERE tableName = ?`, [tableName]);
+    }
     /**
      * Clear inline values on insert changes (op='set', path='/') for a specific table.
      * These values are no longer needed since they are resolved from the source table at query time.

package/dist/data/change-tracking.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/data/change-tracking.test.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SQLiteDB = require("better-sqlite3");
+const utils_1 = require("../utils");
+const change_tracking_1 = require("./change-tracking");
+describe("ChangeTrackingTable table-scoped history", () => {
+    let sqlite;
+    let changes;
+    beforeEach(() => {
+        sqlite = new SQLiteDB(":memory:");
+        const db = {
+            async get(sql, params = []) {
+                return sqlite.prepare(sql).get(params);
+            },
+            async all(sql, params = []) {
+                return sqlite.prepare(sql).all(params);
+            },
+            async exec(sql, params = []) {
+                return { changes: sqlite.prepare(sql).run(params).changes };
+            },
+            async close() {
+                sqlite.close();
+            },
+        };
+        changes = new change_tracking_1.ChangeTrackingTable({ db });
+    });
+    afterEach(() => sqlite.close());
+    const change = (tableName, recordId) => ({
+        changeId: (0, utils_1.newid)(),
+        tableName,
+        recordId,
+        op: "set",
+        path: "/",
+        value: null,
+        createdAt: Date.now(),
+        appliedAt: 0,
+    });
+    it("checks missing IDs within the requested table, preserving unscoped lookups", async () => {
+        const sharedId = (0, utils_1.newid)();
+        const trackedId = (0, utils_1.newid)();
+        const missingId = (0, utils_1.newid)();
+        await changes.insert(change("Other", sharedId));
+        await changes.insert(change("State", trackedId));
+        await expect(changes.filterToMissingIds([sharedId, trackedId, missingId], "State")).resolves.toEqual([sharedId, missingId]);
+        await expect(changes.filterToMissingIds([sharedId, trackedId, missingId])).resolves.toEqual([
+            missingId,
+        ]);
+        await expect(changes.filterToMissingIds([], "State")).resolves.toEqual([]);
+    });
+    it("deletes active, superseded, and deleted history only for the named table", async () => {
+        const tableName = "State'with-quote";
+        const recordId = (0, utils_1.newid)();
+        const other = change("Other", recordId);
+        await changes.insert(change(tableName, recordId));
+        await changes.insert({ ...change(tableName, recordId), supersededAt: Date.now() });
+        await changes.insert({ ...change(tableName, recordId), op: "delete" });
+        await changes.insert(other);
+        await changes.deleteTableChanges(tableName);
+        await changes.deleteTableChanges(tableName);
+        expect(await changes.list()).toEqual([expect.objectContaining({ changeId: other.changeId })]);
+    });
+});

package/dist/data/create-group.js

@@ -51,7 +51,7 @@ async function createGroup(userContext, input) {
     });
     await (0, groups_1.Groups)(groupDataContext).signAndSave(group);
     await (0, group_members_1.GroupMembers)(groupDataContext).signAndSave({
-        groupMemberId: (0, utils_1.newid)(),
+        groupMemberId: (0, utils_1.deterministicGroupMemberId)(groupId, me.userId),
         groupId,
         userId: me.userId,
         role: group_member_roles_1.GroupMemberRole.Founder,

package/dist/data/group-members.d.ts

@@ -36,6 +36,20 @@ export declare class GroupMembersTable extends Table<IGroupMember> {
     save(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     signAndSave(groupMember: IGroupMember, opts?: ISaveOptions): Promise<IGroupMember>;
     delete(groupMemberId: string): Promise<void>;
+    /**
+     * Settle two membership rows for the same user in the same group: devices that approved the
+     * same join at once could each write one, under a different id.
+     *
+     * Merged only when both rows grant the same access (role and deleted state), so nothing about
+     * the member's access changes. The id {@link deterministicGroupMemberId} gives wins if either
+     * row has it, otherwise the lexicographically smaller id; the winner is kept as it is, signature
+     * included. Rows that disagree stay queued for a person. A pure function of the two rows, so
+     * every device keeps the same one.
+     */
+    resolveUniqueConflict(incoming: IGroupMember, existing: IGroupMember): {
+        winner: IGroupMember;
+        loserId: string;
+    } | undefined;
     /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
     static enableGroupMemberSigning(fn: (groupMember: IGroupMember) => IGroupMember): void;
     /** @deprecated Forbidden on GroupsTable; use save() */

package/dist/data/group-members.js

@@ -40,6 +40,7 @@ const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const decorators_1 = require("../data/orm/decorators");
 const zod_types_1 = require("../types/zod-types");
+const utils_1 = require("../utils");
 const group_member_roles_1 = require("./group-member-roles");
 const group_permissions_1 = require("./group-permissions");
 const table_1 = require("./orm/table");
@@ -125,6 +126,41 @@ let GroupMembersTable = (() => {
                 await this.signAndSave(groupMember);
             }
         }
+        /**
+         * Settle two membership rows for the same user in the same group: devices that approved the
+         * same join at once could each write one, under a different id.
+         *
+         * Merged only when both rows grant the same access (role and deleted state), so nothing about
+         * the member's access changes. The id {@link deterministicGroupMemberId} gives wins if either
+         * row has it, otherwise the lexicographically smaller id; the winner is kept as it is, signature
+         * included. Rows that disagree stay queued for a person. A pure function of the two rows, so
+         * every device keeps the same one.
+         */
+        resolveUniqueConflict(incoming, existing) {
+            if (incoming.groupId !== existing.groupId || incoming.userId !== existing.userId) {
+                return undefined;
+            }
+            if (incoming.groupMemberId === existing.groupMemberId) {
+                return undefined;
+            }
+            if (incoming.role !== existing.role ||
+                Boolean(incoming.deleted) !== Boolean(existing.deleted)) {
+                return undefined;
+            }
+            const derivedId = (0, utils_1.deterministicGroupMemberId)(incoming.groupId, incoming.userId);
+            let winner;
+            if (incoming.groupMemberId === derivedId) {
+                winner = incoming;
+            }
+            else if (existing.groupMemberId === derivedId) {
+                winner = existing;
+            }
+            else {
+                winner = incoming.groupMemberId < existing.groupMemberId ? incoming : existing;
+            }
+            const loser = winner === incoming ? existing : incoming;
+            return { winner, loserId: loser.groupMemberId };
+        }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enableGroupMemberSigning(fn) {
             signingGlobals[signingKey] = fn;

package/dist/data/group-members.test.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const group_members_1 = require("./group-members");
 const group_permissions_1 = require("./group-permissions");
 // Test the group members signature logic directly without ORM dependencies
 describe("Group Members Signature Logic", () => {
@@ -285,3 +287,50 @@ describe("Group Members Signature Logic", () => {
         });
     });
 });
+describe("GroupMembersTable.resolveUniqueConflict", () => {
+    const groupId = (0, utils_1.newid)();
+    const userId = (0, utils_1.newid)();
+    const resolve = (incoming, existing) => group_members_1.GroupMembersTable.prototype.resolveUniqueConflict.call({}, incoming, existing);
+    const row = (groupMemberId, overrides = {}) => ({
+        groupMemberId,
+        groupId,
+        userId,
+        role: group_permissions_1.GroupMemberRole.Writer,
+        signature: `sig-${groupMemberId}`,
+        ...overrides,
+    });
+    it("keeps the smaller id, unchanged, whichever row arrives", () => {
+        const [low, high] = [(0, utils_1.newid)(), (0, utils_1.newid)()].sort();
+        const a = row(low);
+        const b = row(high);
+        expect(resolve(a, b)).toEqual({ winner: a, loserId: high });
+        expect(resolve(b, a)).toEqual({ winner: a, loserId: high });
+        expect(resolve(b, a)?.winner.signature).toBe(`sig-${low}`);
+    });
+    it("prefers the id derived from the group and user", () => {
+        const derived = row((0, utils_1.deterministicGroupMemberId)(groupId, userId));
+        const other = row("00000000000000000000000001");
+        expect(resolve(other, derived)).toEqual({ winner: derived, loserId: other.groupMemberId });
+        expect(resolve(derived, other)).toEqual({ winner: derived, loserId: other.groupMemberId });
+    });
+    it("leaves rows that grant different access for a person to settle", () => {
+        const a = row((0, utils_1.newid)());
+        expect(resolve(a, row((0, utils_1.newid)(), { role: group_permissions_1.GroupMemberRole.Admin }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { deleted: true }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { userId: (0, utils_1.newid)() }))).toBeUndefined();
+        expect(resolve(a, row((0, utils_1.newid)(), { groupId: (0, utils_1.newid)() }))).toBeUndefined();
+        expect(resolve(a, { ...a })).toBeUndefined();
+    });
+    it("treats a missing deleted flag as not deleted", () => {
+        const a = row((0, utils_1.newid)());
+        const b = row((0, utils_1.newid)(), { deleted: false });
+        expect(resolve(a, b)).toBeDefined();
+    });
+    it("depends only on the two signed rows and never modifies either one", () => {
+        const a = Object.freeze(row((0, utils_1.newid)()));
+        const b = Object.freeze(row((0, utils_1.newid)()));
+        const before = [structuredClone(a), structuredClone(b)];
+        expect(resolve(a, b)).toEqual(resolve(b, a));
+        expect([a, b]).toEqual(before);
+    });
+});

package/dist/data/orm/sql.data-source.d.ts

@@ -42,6 +42,15 @@ export declare class SQLDataSource<T extends {
      * columns (for example `accessLevel`) are written on insert.
      */
     private applySchemaDefaults;
+    /**
+     * Remove `record`'s empty fields in place, so a row is written and returned as it's stored:
+     * an optional field that is `null` or `undefined` is left out, and so is an empty field with a
+     * default, which gets the default. Returns the defaulted fields' names. A required field
+     * without a default keeps its value for validation to refuse.
+     */
+    private removeEmptyFields;
+    /** Copy the parsed defaults requested by {@link removeEmptyFields} onto `record`. */
+    private applyDefaults;
     /**
      * Columns to SET on update. Required fields that are missing are omitted so
      * older peers without a new column do not overwrite a local value with NULL.

package/dist/data/orm/sql.data-source.js

@@ -258,6 +258,7 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
+        this.removeEmptyFields(record);
         this.applySchemaDefaults(record);
         const fields = this.metaData.fields.map((field) => `"${field.name}"`).join(", ");
         const values = this.metaData.fields.map((field) => jsValueToSqlValue(record[field.name]));
@@ -276,8 +277,9 @@ class SQLDataSource {
         // Explicit catalog patches write only their own columns. Keep ordinary row-save
         // semantics (omitted optional fields clear) unchanged for all other writes.
         const catalogPatch = this.tableName === "Tools" && (0, tool_catalog_fields_1.isToolCatalogPatch)(record);
+        const defaulted = catalogPatch ? [] : this.removeEmptyFields(record);
         const updated = catalogPatch ? { ...(await this.get(primaryKey)), ...record } : record;
-        this.schema.parse(updated);
+        this.applyDefaults(record, this.schema.parse(updated), defaulted);
         const updateFields = this.fieldsForUpdate(record).filter((field) => !catalogPatch || Object.hasOwn(record, field.name));
         if (updateFields.length === 0) {
             return updated;
@@ -327,6 +329,47 @@ class SQLDataSource {
             }
         }
     }
+    /**
+     * Remove `record`'s empty fields in place, so a row is written and returned as it's stored:
+     * an optional field that is `null` or `undefined` is left out, and so is an empty field with a
+     * default, which gets the default. Returns the defaulted fields' names. A required field
+     * without a default keeps its value for validation to refuse.
+     */
+    removeEmptyFields(record) {
+        const writable = record;
+        const cleaned = (0, types_1.withoutEmptyFields)(this.metaData.fields, writable);
+        const defaulted = [];
+        for (const field of this.metaData.fields) {
+            // A missing optional column is cleared on update too. Its default must win over NULL;
+            // a missing required column still keeps the stored value for older syncing peers.
+            if (field.defaultValue !== undefined &&
+                writable[field.name] == null &&
+                (Object.hasOwn(writable, field.name) || field.optional)) {
+                defaulted.push(field.name);
+            }
+            if (!Object.hasOwn(writable, field.name)) {
+                continue;
+            }
+            if (!Object.hasOwn(cleaned, field.name)) {
+                delete writable[field.name];
+            }
+            else if (cleaned[field.name] !== writable[field.name]) {
+                writable[field.name] = cleaned[field.name];
+            }
+        }
+        return defaulted;
+    }
+    /** Copy the parsed defaults requested by {@link removeEmptyFields} onto `record`. */
+    applyDefaults(record, parsed, names) {
+        for (const name of names) {
+            if (parsed[name] === undefined) {
+                delete record[name];
+            }
+            else {
+                record[name] = parsed[name];
+            }
+        }
+    }
     /**
      * Columns to SET on update. Required fields that are missing are omitted so
      * older peers without a new column do not overwrite a local value with NULL.
@@ -366,6 +409,7 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
+        this.removeEmptyFields(record);
         this.applySchemaDefaults(record);
         const fields = this.metaData.fields.map((field) => `"${field.name}"`).join(", ");
         const values = this.metaData.fields.map((field) => jsValueToSqlValue(record[field.name]));
@@ -383,7 +427,8 @@ class SQLDataSource {
             // @ts-expect-error - need to figure out how to get typescript to understand what's going on here
             record[this.metaData.primaryKeyName] = (0, utils_1.newid)();
         }
-        this.schema.parse(record);
+        const defaulted = this.removeEmptyFields(record);
+        this.applyDefaults(record, this.schema.parse(record), defaulted);
         const primaryKey = record[this.metaData.primaryKeyName];
         const updateFields = this.fieldsForUpdate(record);
         if (updateFields.length === 0) {