@peers-app/peers-sdk 0.28.2 → 0.28.3

package/dist/context/user-context-singleton.js

@@ -9,6 +9,7 @@ exports.getTableContainer = getTableContainer;
 exports.setDefaultClientUserContext = setDefaultClientUserContext;
 exports.getAllTables = getAllTables;
 const client_proxy_data_source_1 = require("../data/orm/client-proxy.data-source");
+const decorators_1 = require("../data/orm/decorators");
 const rpc_types_1 = require("../rpc-types");
 const utils_1 = require("../utils");
 const user_context_1 = require("./user-context");
@@ -170,6 +171,7 @@ if (!rpc_types_1.isClient) {
         if (typeof method !== "function") {
             throw new Error(`Method ${methodName} not found on table ${tableName}`);
         }
+        (0, decorators_1.checkRemoteTableSaveOptions)(methodName, args);
         // @ts-expect-error - call this way to ensure 'this' is correct
         return table[methodName](...args);
     };

package/dist/contracts/contract-proxy.js

@@ -584,6 +584,7 @@ function createContractProvider(resolution, opts = {}) {
                     !(0, decorators_1.isContractRemoteTableMethod)(method)) {
                     throw new Error(`Table method '${call.name}.${call.operation}' is not remotely callable`);
                 }
+                (0, decorators_1.checkRemoteTableSaveOptions)(call.operation, call.args);
                 return impl.apply(table, call.args);
             }
             case "tool": {

package/dist/data/group-members.js

@@ -131,9 +131,10 @@ let GroupMembersTable = (() => {
                 ...(await (0, write_checks_1.signingStamp)(this, groupMember, current)),
             });
             return this.save(groupMember, {
-                saveAsSnapshot: true,
                 restoreIfDeleted: true,
                 ...(opts || {}),
+                saveAsSnapshot: true,
+                writtenAt: groupMember.signedAt,
             });
         }
         async delete(groupMemberId) {

package/dist/data/group-resign.js

@@ -39,7 +39,10 @@ async function resignGroupAuthority(dataContext, opts = {}) {
             try {
                 if (opts.secretKey) {
                     const stamp = await (0, write_checks_1.signingStamp)(table, row, row);
-                    await table.save((0, keys_1.addSignatureToObject)({ ...row, ...stamp }, opts.secretKey), snapshot);
+                    await table.save((0, keys_1.addSignatureToObject)({ ...row, ...stamp }, opts.secretKey), {
+                        ...snapshot,
+                        writtenAt: stamp.signedAt,
+                    });
                 }
                 else {
                     await table.signAndSave(prepare(row), snapshot);

package/dist/data/groups.js

@@ -116,7 +116,8 @@ let GroupsTable = (() => {
                 ...group,
                 ...(await (0, write_checks_1.signingStamp)(this, group)),
             });
-            return this.save(group, opts);
+            // Field patches from concurrent writes could combine into a row nobody signed.
+            return this.save(group, { ...opts, saveAsSnapshot: true, writtenAt: group.signedAt });
         }
         /**
          * Re-sign this group's authority rows (group row, memberships, packages, package versions)

package/dist/data/orm/client-proxy.data-source.d.ts

@@ -1,6 +1,7 @@
 import type { z } from "zod";
 import { type DataFilter, type ICursorIterable, type IDataQueryParams, type IDataSource, type ISaveOptions } from "./data-query";
 import { type ITableMetaData } from "./types";
+/** A renderer's table data source, forwarding operations to the host over RPC. */
 export declare class ClientProxyDataSource<T extends {
     [key: string]: any;
 }> implements IDataSource<T> {

package/dist/data/orm/client-proxy.data-source.js

@@ -4,7 +4,9 @@ exports.ClientProxyDataSource = void 0;
 const rpc_types_1 = require("../../rpc-types");
 const utils_1 = require("../../utils");
 const data_query_1 = require("./data-query");
+const decorators_1 = require("./decorators");
 const types_1 = require("./types");
+/** A renderer's table data source, forwarding operations to the host over RPC. */
 class ClientProxyDataSource {
     metaData;
     schema;
@@ -38,6 +40,7 @@ class ClientProxyDataSource {
         return rpc_types_1.rpcServerCalls.tableMethodCall(this.dataContextId, this.tableName, "findOne", filter, opts);
     }
     async save(record, opts) {
+        (0, decorators_1.checkRemoteTableSaveOptions)("save", [record, opts]);
         return rpc_types_1.rpcServerCalls.tableMethodCall(this.dataContextId, this.tableName, "save", record, opts);
     }
     async insert(record) {

package/dist/data/orm/data-query.d.ts

@@ -1,9 +1,13 @@
+/** Options controlling how a host table save is recorded. */
 export interface ISaveOptions {
     restoreIfDeleted?: boolean;
+    /** @internal Host-only change time for signed rows; must match their signedAt. */
+    writtenAt?: number;
     saveAsSnapshot?: boolean;
     weakInsert?: boolean;
     insertOnly?: boolean;
 }
+/** Persistence operations for one table. */
 export interface IDataSource<T extends {
     [key: string]: any;
 }> {
@@ -18,6 +22,7 @@ export interface IDataSource<T extends {
     update: (record: T) => Promise<T>;
     delete: (data: string | T) => Promise<void>;
 }
+/** Table operations needed to execute a data query. */
 export interface ITable<T extends Record<string, any>> {
     tableName: string;
     metaData: {
@@ -34,6 +39,7 @@ export interface ITable<T extends Record<string, any>> {
         textSearch?: string;
     }) => Promise<T[]>;
 }
+/** Filtering, ordering and pagination for table reads. */
 export interface IDataQueryParams<T extends Record<string, any>> {
     page?: number;
     pageSize?: number;
@@ -43,6 +49,7 @@ export interface IDataQueryParams<T extends Record<string, any>> {
     textSearchExact?: boolean;
     skipPast?: T;
 }
+/** A table query that can be listed or consumed through a cursor. */
 export declare class DataQuery<T extends Record<string, any>> {
     readonly table: ITable<T>;
     constructor(table: ITable<T>, { page, pageSize, sortBy, filter, textSearch, textSearchExact }?: IDataQueryParams<T>);
@@ -55,18 +62,23 @@ export declare class DataQuery<T extends Record<string, any>> {
     cursor(): ICursorIterable<T>;
     list(): Promise<T[]>;
 }
+/** A cursor positioned at a row, with optional seek support. */
 export interface ICursor<T> {
     value: T | null;
     next: (skipPast?: T) => Promise<T | null>;
 }
+/** A cursor that also supports asynchronous iteration. */
 export type ICursorIterable<T> = ICursor<T> & AsyncIterable<T>;
+/** Adds asynchronous iteration to a cursor. */
 export declare function iterableCursor<T>(cursor: ICursor<T>): ICursorIterable<T>;
+/** Reads a data source in pages through an asynchronous cursor. */
 export declare function dataSourceCursor<T extends {
     [key: string]: any;
 }>(dataSource: {
     list: (filter?: DataFilter<T>, opts?: IDataQueryParams<T>) => Promise<T[]>;
     primaryKeyName: string;
 }, filter?: DataFilter<T>, opts?: IDataQueryParams<T>): ICursorIterable<T>;
+/** Counts matching rows, falling back to a cursor when native count is unavailable. */
 export declare function dataSourceCount<T extends {
     [key: string]: any;
 }>(dataSource: {
@@ -74,11 +86,15 @@ export declare function dataSourceCount<T extends {
     list: (filter?: DataFilter<T>, opts?: IDataQueryParams<T>) => Promise<T[]>;
     primaryKeyName: string;
 }, filter?: DataFilter<T>): Promise<number>;
+/** Ordered fields; a leading minus selects descending order. */
 export type SortBy<T extends {
     [key: string]: any;
 }> = (keyof T extends string | number ? keyof T | `-${keyof T}` : never)[];
+/** Scalar values accepted by data filters. */
 export type DataFieldScalar = boolean | number | string | Date | null;
+/** Comparison operators accepted in a field filter. */
 export type DataFilterValueOperator = "$eq" | "$ne" | "$gt" | "$gte" | "$lt" | "$lte" | "$exists" | "$matchWords" | "$substr" | "$expr" | "$in";
+/** A field value or comparison used in a data filter. */
 export type DataFilterValue = DataFieldScalar | DataFieldScalar[] | {
     [key in Exclude<DataFilterValueOperator, "$in">]?: DataFieldScalar;
 } | {
@@ -86,13 +102,17 @@ export type DataFilterValue = DataFieldScalar | DataFieldScalar[] | {
 } | {
     $in: DataFieldScalar[];
 };
+/** Field predicates combined with AND. */
 export type DataFilterAnd<T> = {
     [key in keyof T]?: DataFilterValue;
 };
+/** Alternative groups of field predicates combined with OR. */
 export type DataFilterOr<T> = DataFilterAnd<T>[] | {
     $or: DataFilterAnd<T>[];
 };
+/** A table filter composed of field predicates and logical groups. */
 export type DataFilter<T> = DataFilterAnd<T> | DataFilterOr<T> | {
     $and: DataFilter<T>[];
 };
+/** Adds predicates to resume an ordered query after the supplied row. */
 export declare function filterToSkipPastValue(filter: DataFilter<unknown>, sortBy: string[], skipPast: any): DataFilter<unknown>;

package/dist/data/orm/data-query.js

@@ -5,6 +5,7 @@ exports.iterableCursor = iterableCursor;
 exports.dataSourceCursor = dataSourceCursor;
 exports.dataSourceCount = dataSourceCount;
 exports.filterToSkipPastValue = filterToSkipPastValue;
+/** A table query that can be listed or consumed through a cursor. */
 class DataQuery {
     table;
     constructor(table, { page, pageSize, sortBy, filter, textSearch, textSearchExact } = {}) {
@@ -85,6 +86,7 @@ class DataQuery {
     }
 }
 exports.DataQuery = DataQuery;
+/** Adds asynchronous iteration to a cursor. */
 function iterableCursor(cursor) {
     // @ts-expect-error - we're explicitly extending the cursor object to have this symbol
     cursor[Symbol.asyncIterator] = () => {
@@ -97,6 +99,7 @@ function iterableCursor(cursor) {
     };
     return cursor;
 }
+/** Reads a data source in pages through an asynchronous cursor. */
 function dataSourceCursor(dataSource, filter = {}, opts = {}) {
     // if (dataSource.cursor) {
     //   return dataSource.cursor(filter, opts);
@@ -157,6 +160,7 @@ function dataSourceCursor(dataSource, filter = {}, opts = {}) {
     };
     return iterableCursor(cursor);
 }
+/** Counts matching rows, falling back to a cursor when native count is unavailable. */
 async function dataSourceCount(dataSource, filter = {}) {
     if (dataSource.count) {
         return dataSource.count(filter);
@@ -169,6 +173,7 @@ async function dataSourceCount(dataSource, filter = {}) {
     }
     return count;
 }
+/** Adds predicates to resume an ordered query after the supplied row. */
 function filterToSkipPastValue(filter, sortBy, skipPast) {
     const sortByFilters = [];
     for (let i = 0; i < sortBy.length; i++) {

package/dist/data/orm/decorators.d.ts

@@ -1,3 +1,5 @@
+/** Refuse host-only signed write times supplied through a table RPC or contract call. */
+export declare function checkRemoteTableSaveOptions(methodName: string, args: readonly unknown[]): void;
 /**
  * Return whether a table method was explicitly marked for remote invocation by
  * {@link ProxyClientTableMethodCalls}. Client proxies are recognized through their

package/dist/data/orm/decorators.js

@@ -1,9 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRemoteTableSaveOptions = checkRemoteTableSaveOptions;
 exports.isContractRemoteTableMethod = isContractRemoteTableMethod;
 exports.ProxyClientTableMethodCalls = ProxyClientTableMethodCalls;
 const rpc_types_1 = require("../../rpc-types");
 const contractRemoteTableMethod = Symbol("contractRemoteTableMethod");
+/** Refuse host-only signed write times supplied through a table RPC or contract call. */
+function checkRemoteTableSaveOptions(methodName, args) {
+    if (!["save", "insert", "update", "signAndSave"].includes(methodName))
+        return;
+    const options = args[1];
+    if (options && typeof options === "object" && "writtenAt" in options) {
+        throw new Error("writtenAt is host-only; use signAndSave to sign a new change");
+    }
+}
 function markContractRemoteTableMethod(method) {
     Object.defineProperty(method, contractRemoteTableMethod, { value: true });
 }
@@ -37,6 +47,7 @@ function ProxyClientTableMethodCalls() {
             const methodName = context.name;
             // WARNING: Using typescript's magical `this` param
             const proxyFn = function (...args) {
+                checkRemoteTableSaveOptions(methodName, args);
                 const dataContextId = this.dataSource.dataContextId || this.groupId || "";
                 return rpc_types_1.rpcServerCalls.tableMethodCall(dataContextId, this.tableName, methodName, ...args);
             };

package/dist/data/orm/write-checks.d.ts

@@ -57,10 +57,12 @@ export declare function checkLocalSave<T extends {
  */
 export declare const packageApprovalTables: ReadonlySet<string>;
 /**
- * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, now or
- * just after the row on record when that was signed by a clock running ahead, so the new
- * signature counts as the later one (and, for a package table, after the deleted row's
- * retained stamp); for a package table also the context the approval is for.
+ * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, a tick of
+ * the context's write clock (wall time without a tracked source) or just after the row on record
+ * when that was signed by a clock running ahead, so the new signature counts as the later one
+ * (and, for a package table, after the deleted row's retained stamp); for a package table also
+ * the context the approval is for. The save then records the change at this same time
+ * (`writtenAt`), so sync and the signed order agree on which concurrent write is later.
  *
  * @param table - The table being signed for.
  * @param row - The row being signed.

package/dist/data/orm/write-checks.js

@@ -56,10 +56,12 @@ async function checkLocalSave(table, row, check) {
  */
 exports.packageApprovalTables = new Set(["Packages", "PackageVersions"]);
 /**
- * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, now or
- * just after the row on record when that was signed by a clock running ahead, so the new
- * signature counts as the later one (and, for a package table, after the deleted row's
- * retained stamp); for a package table also the context the approval is for.
+ * What a table's `signAndSave` (and a re-sign) puts under the signature: `signedAt`, a tick of
+ * the context's write clock (wall time without a tracked source) or just after the row on record
+ * when that was signed by a clock running ahead, so the new signature counts as the later one
+ * (and, for a package table, after the deleted row's retained stamp); for a package table also
+ * the context the approval is for. The save then records the change at this same time
+ * (`writtenAt`), so sync and the signed order agree on which concurrent write is later.
  *
  * @param table - The table being signed for.
  * @param row - The row being signed.
@@ -76,8 +78,13 @@ async function signingStamp(table, row, current) {
         const dataContext = (await getUserContext()).getDataContext(groupId);
         floor = await deletedSignedAt(tableName, { dataContext, recordId });
     }
+    // Duck typing also works when the data source comes from another installed SDK copy.
+    let source = table.dataSource;
+    while (source && !source.getWriteClock)
+        source = source.dataSource;
+    const clock = await source?.getWriteClock?.();
     return {
-        signedAt: Math.max(Date.now(), floor + 1),
+        signedAt: Math.max(clock ? Math.ceil(clock.tick()) : Date.now(), floor + 1),
         ...(packageTable ? { signedContextId: groupId } : {}),
     };
 }

package/dist/data/package-versions.js

@@ -137,7 +137,12 @@ let PackageVersionsTable = (() => {
                 ...packageVersion,
                 ...(await (0, write_checks_1.signingStamp)(this, packageVersion)),
             });
-            return this.save(packageVersion, opts);
+            // Field patches from concurrent writes could combine into a row nobody signed.
+            return this.save(packageVersion, {
+                ...opts,
+                saveAsSnapshot: true,
+                writtenAt: packageVersion.signedAt,
+            });
         }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enablePackageVersionSigning(fn) {

package/dist/data/packages.js

@@ -127,7 +127,8 @@ let PackagesTable = (() => {
                 ...packageObj,
                 ...(await (0, write_checks_1.signingStamp)(this, packageObj)),
             });
-            return this.save(packageObj, opts);
+            // Field patches from concurrent writes could combine into a row nobody signed.
+            return this.save(packageObj, { ...opts, saveAsSnapshot: true, writtenAt: packageObj.signedAt });
         }
         /** Registers the signer for all SDK copies in this JavaScript realm. Replaces any prior signer. */
         static enablePackageSigning(fn) {

package/dist/data/table-definitions-table.d.ts

@@ -9,18 +9,18 @@ export declare const tableDefinitionRecordSchema: z.ZodObject<{
     deleted: z.ZodOptional<z.ZodDate>;
 }, "strip", z.ZodTypeAny, {
     name: string;
+    tableId: string;
     metaData: {} & {
         [k: string]: any;
     };
-    tableId: string;
     versionNumber: number;
     deleted?: Date | undefined;
 }, {
     name: string;
+    tableId: string;
     metaData: {} & {
         [k: string]: any;
     };
-    tableId: string;
     deleted?: Date | undefined;
     versionNumber?: number | undefined;
 }>;
@@ -36,10 +36,10 @@ export type ITableDefinitionRecord = z.infer<typeof tableDefinitionRecordSchema>
  */
 export declare function TableDefinitions(dataContext?: DataContext): import("..").Table<{
     name: string;
+    tableId: string;
     metaData: {} & {
         [k: string]: any;
     };
-    tableId: string;
     versionNumber: number;
     deleted?: Date | undefined;
 }>;

package/dist/data/tool-access-approvals.d.ts

@@ -46,9 +46,9 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     nonce: string;
     status: ToolAccessApprovalStatus;
-    userId: string;
     toolName: string;
     toolId: string;
+    userId: string;
     scope: ToolAccessApprovalScope;
     createdAt: Date;
     dataContextId: string;
@@ -69,9 +69,9 @@ export declare const toolAccessApprovalSchema: z.ZodObject<{
     resultSummary?: string | undefined;
 }, {
     nonce: string;
-    userId: string;
     toolName: string;
     toolId: string;
+    userId: string;
     dataContextId: string;
     expiresAt: Date;
     toolAccessApprovalId: string;
@@ -102,9 +102,9 @@ export type IToolAccessApproval = z.infer<typeof toolAccessApprovalSchema>;
 export declare function ToolAccessApprovals(dataContext?: DataContext): import("..").Table<{
     nonce: string;
     status: ToolAccessApprovalStatus;
-    userId: string;
     toolName: string;
     toolId: string;
+    userId: string;
     scope: ToolAccessApprovalScope;
     createdAt: Date;
     dataContextId: string;

package/dist/package-loader/isolated-runtime.d.ts

@@ -18,6 +18,8 @@ export interface IPackageSaveOptions {
 /**
  * The save options a package may use, from whatever a caller passed: only `restoreIfDeleted`.
  * The host's other save options (snapshots, weak inserts) stay out of package hands.
+ * `writtenAt` must stay host-only even if this allowlist expands: it orders signed rows,
+ * and accepting it from a package would let that package backdate writes.
  *
  * @param options - A table `save`'s second argument, as received.
  * @returns The allowed options, or `undefined` when none are set.

package/dist/package-loader/isolated-runtime.js

@@ -18,6 +18,8 @@ exports.ISOLATED_CONTRACT_TABLE_OPERATIONS = [
 /**
  * The save options a package may use, from whatever a caller passed: only `restoreIfDeleted`.
  * The host's other save options (snapshots, weak inserts) stay out of package hands.
+ * `writtenAt` must stay host-only even if this allowlist expands: it orders signed rows,
+ * and accepting it from a package would let that package backdate writes.
  *
  * @param options - A table `save`'s second argument, as received.
  * @returns The allowed options, or `undefined` when none are set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.28.2",
+  "version": "0.28.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"