@peers-app/peers-sdk 0.31.4 → 0.31.6

package/dist/define/context.d.ts

@@ -27,6 +27,19 @@ export interface IPackageContext {
      * never use it to decide what a caller may do.
      */
     readonly deviceId: string;
+    /**
+     * The user this call acts for: the signed-in user for a call from this device's own screens or
+     * CLI, or the member whose device called. Use it to record who did something, such as who
+     * created a row; don't use it to decide what the caller may do. The host has already checked
+     * the call against the member's access rules.
+     *
+     * A call the device makes for itself, such as a System Scheduler booking, acts for the
+     * signed-in user. Contract event deliveries act for the subscriber, not the event's author.
+     * It's `undefined` in `onStart`, when no user identity is available, and on older hosts.
+     * Timers and owned-table watches have no caller of their own. A `ctx` captured by a callback
+     * keeps its original caller metadata, even after that call's authority has expired.
+     */
+    readonly callerUserId?: string;
     /** Run a tool on a contract this package consumes (or provides), as this call's caller. */
     callConsumedTool(contractId: string, version: number, toolName: string, args?: unknown, options?: IPackageProviderOptions): Promise<unknown>;
     /**

package/dist/device/device-election.d.ts

@@ -1,18 +1,32 @@
 import type { IDeviceConnection, INetworkInfo } from "../types/peer-device";
+/** Local connections and remote topology snapshots used to choose a group's sync edges. */
 export interface IElectionData {
     deviceId: string;
     myConnections: IDeviceConnection[];
     allNetworkInfo: INetworkInfo[];
 }
+/**
+ * Choose the devices this one syncs with in a group: its preferred devices, plus the devices
+ * that prefer it.
+ *
+ * Once preferences are established, ongoing changes move along these edges in either direction:
+ * a write notifies the writer's preferred and preferred-by devices, and periodic resync pulls
+ * only from preferred devices. The edges must therefore join every device in the group.
+ *
+ * @param data - This device, its direct connections, and each connected device's network info.
+ * @returns The devices to prefer, and the devices whose network info says they prefer this one.
+ */
 export declare function electDevices({ deviceId, myConnections, allNetworkInfo }: IElectionData): {
     preferredDeviceIds: string[];
     preferredByDeviceIds: string[];
 };
+/** A remote topology snapshot annotated with its local link and incoming preferences. */
 export interface ISortableConnection extends INetworkInfo {
     connectedDeviceIds: string[];
     preferredByDeviceIds: string[];
     myConnection: IDeviceConnection | undefined;
 }
+/** Candidate connections and the devices not yet covered by the greedy election pass. */
 export interface ISortConnectionsArgs {
     myDeviceId: string;
     unconnectedDeviceIds: Set<string>;

package/dist/device/device-election.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.electDevices = electDevices;
 exports.getLeastPreferredConnection = getLeastPreferredConnection;
 const lodash_1 = require("lodash");
+/**
+ * Choose the devices this one syncs with in a group: its preferred devices, plus the devices
+ * that prefer it.
+ *
+ * Once preferences are established, ongoing changes move along these edges in either direction:
+ * a write notifies the writer's preferred and preferred-by devices, and periodic resync pulls
+ * only from preferred devices. The edges must therefore join every device in the group.
+ *
+ * @param data - This device, its direct connections, and each connected device's network info.
+ * @returns The devices to prefer, and the devices whose network info says they prefer this one.
+ */
 function electDevices({ deviceId, myConnections, allNetworkInfo }) {
     const allDeviceIdsSet = new Set();
     const _preferredByDeviceIdsSet = new Set();
@@ -47,11 +58,55 @@ function electDevices({ deviceId, myConnections, allNetworkInfo }) {
             break;
         }
     }
+    const preferredDeviceIds = preferredConnections.map((c) => c.deviceId);
+    preferredDeviceIds.push(...connectCompleteViews({
+        deviceId,
+        myConnections,
+        preferredDeviceIds,
+        connections: allConnectionInfos,
+    }));
     return {
-        preferredDeviceIds: preferredConnections.map((c) => c.deviceId),
+        preferredDeviceIds,
         preferredByDeviceIds: Array.from(_preferredByDeviceIdsSet),
     };
 }
+/**
+ * Add stable sync edges when this device has network info for every known device directly.
+ *
+ * The greedy pass counts a device as covered once a preferred device is connected to it, but
+ * ongoing changes move along preference edges. In a full mesh the greedy pass prefers one other,
+ * and two devices that pick each other form an island: their writes never reach the rest, and
+ * the rest's never reach them.
+ *
+ * Devices connected to everyone form an id-ordered chain: each prefers its predecessor. The
+ * first also prefers every device without a complete view, since those cannot build the chain
+ * themselves. In a full mesh this adds at most one preference per device and at most two incident
+ * edges per device, rather than concentrating the extra sync traffic on one hub.
+ *
+ * These edges depend only on topology, never on cached preferences. Bridging only the components
+ * in a snapshot is insufficient: concurrent elections can each rely on edges the others remove,
+ * repeatedly splitting a full mesh even when just one device adds bridges. Once topology and
+ * network-info availability settle, every complete view builds the same chain regardless of
+ * election order or stale preferences. Partial views still use only the greedy pass.
+ */
+function connectCompleteViews({ deviceId, myConnections, preferredDeviceIds, connections, }) {
+    const direct = connections.filter((c) => c.myConnection);
+    const visibleIds = new Set(direct.map((c) => c.deviceId));
+    const knownIds = new Set([
+        deviceId,
+        ...myConnections.map((c) => c.deviceId),
+        ...connections.flatMap((c) => c.connectedDeviceIds),
+    ]);
+    if ([...knownIds].some((id) => id !== deviceId && !visibleIds.has(id)))
+        return [];
+    const seesEveryone = (c) => [...knownIds].every((id) => c.connectedDeviceIds.includes(id));
+    const completeIds = [deviceId, ...direct.filter(seesEveryone).map((c) => c.deviceId)].sort();
+    const index = completeIds.indexOf(deviceId);
+    const backbone = index > 0
+        ? [completeIds[index - 1]]
+        : direct.filter((c) => !seesEveryone(c)).map((c) => c.deviceId);
+    return backbone.filter((id) => !preferredDeviceIds.includes(id));
+}
 /**
  * Sort connections from most preferred to least preferred
  *   The most preferred connections are ones that link us to the most new devices
@@ -66,12 +121,9 @@ function sortConnections({ myDeviceId, connections, unconnectedDeviceIds }) {
         const bLatency = (b.myConnection?.latencyMs || 1) * (b.myConnection?.errorRate || 0.00001);
         return aLatency - bLatency;
     });
-    // sort by preferred by other devices count (higher is better)
-    connections.sort((a, b) => {
-        const aPreferredCount = a.preferredDeviceIds.length;
-        const bPreferredCount = b.preferredDeviceIds.length;
-        return bPreferredCount - aPreferredCount;
-    });
+    // sort by how many other devices prefer it (higher is better), so devices gather on one
+    // another's choices instead of pairing off
+    connections.sort((a, b) => b.preferredByDeviceIds.length - a.preferredByDeviceIds.length);
     // sort by links to new devices - in general, this is most important except for the later edge-cases
     connections.sort((a, b) => {
         const linksToDeviceA = a.connectedDeviceIds.filter((id) => unconnectedDeviceIds.has(id)).length;

package/dist/package-installer/peers-core-installer.js

@@ -24,8 +24,12 @@ const system_ids_1 = require("../system-ids");
 const package_remote_checker_1 = require("./package-remote-checker");
 const package_seed_installer_1 = require("./package-seed-installer");
 const peers_core_trust_anchor_1 = require("./peers-core-trust-anchor");
+// The name and description a new install's Package record gets. peers-core's id now holds only
+// Tasks, but the name stays "peers-core": a dev build's source folder falls back to
+// `~/peers/packages/<name-slug>` (`getPackageLocalPath`), which is the peers-core checkout. Rename
+// it when Tasks gets a folder of its own. Existing records keep the name they were created with.
 const PEERS_CORE_NAME = "peers-core";
-const PEERS_CORE_DESCRIPTION = "Core system package for Peers platform";
+const PEERS_CORE_DESCRIPTION = "Tasks, with subtasks, comments, repeats and a timer.";
 /**
  * Ensure peers-core is installed (with a usable, loaded version) in
  * `dataContext`, applying the layered strategy described in the module docs.

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

@@ -324,7 +324,8 @@ export interface IIsolatedContractProviderGateway {
  * Invoked only by the host for guest-originated gateway calls. The user id and
  * data context must come from authenticated host state, never guest payloads.
  * Return `undefined` when no signed-in identity is available; protected tools
- * then retain their existing missing-caller-identity denial.
+ * then retain their existing missing-caller-identity denial. Its user id is also a guest
+ * handler's `ctx.callerUserId` when the call's principal names no user.
  */
 export type IsolatedLocalUserContextResolver = () => {
     userId: string;

package/package.json

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