@peers-app/peers-sdk 0.30.4 → 0.30.6

package/dist/contracts/system/mesh-metrics-types.d.ts

@@ -5,7 +5,9 @@ export type MeshDialReason = "own-device" | "group-network-info" | "broadcast-an
 /** Bounded path categories used for lifetime counters; attempts also retain the address. */
 export type MeshPath = "websocket" | "webrtc" | "cloud" | "discovery";
 /** Failure categories, independent of free-form transport error messages. */
-export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported" | "sender-not-known" | "trust-refused" | "identity-mismatch" | "cancelled" | "capacity";
+export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported" | "sender-not-known"
+/** This device can't encrypt to the target yet: no owner-signed row or profile for it here. */
+ | "recipient-unknown" | "trust-refused" | "identity-mismatch" | "cancelled" | "capacity";
 /** Observed stage; timestamps are offsets in milliseconds from the attempt's queued time. */
 export type MeshStage = "queued" | "started" | "authenticated" | "admitted" | "ready" | "firstSync";
 /** Local dial metadata and cancellation; never serialized into device messages. */
@@ -19,6 +21,12 @@ export interface IMeshDial {
     targetDeviceId?: string;
     /** One-based retry number; absent for the initial dial. */
     retry?: number;
+    /**
+     * Metrics only: the logical dial this transport races alongside (a published address tried
+     * next to the device-id path). It's recorded as an attempt of its own but counted as part of
+     * that dial, and its failures don't end the dial.
+     */
+    siblingOf?: string;
 }
 /** One dial or inbound connection. Missing stages have not been observed. */
 export interface IMeshAttempt {
@@ -135,6 +143,17 @@ export interface IMeshStats {
             probes: number;
             connected: number;
         };
+        /**
+         * Dials helped by what devices publish: dials that tried a device's published addresses,
+         * those an address won, and the relayed protocol queries made and skipped because the
+         * device's protocols were known. Absent from devices older than these counters.
+         */
+        dialHints?: {
+            addressDials: number;
+            addressWins: number;
+            protocolQueries: number;
+            protocolQueriesSkipped: number;
+        };
         /** Lifetime episodes excluded from latency percentiles, by reason. */
         unmeasuredEpisodes?: {
             pageHidden: number;

package/dist/contracts/tool-catalog.d.ts

@@ -49,11 +49,42 @@ export declare class ToolCatalog {
     private subscription?;
     private disposed;
     private reconciliationQueued;
+    /**
+     * This context's Tools rows, read once by {@link ready} and kept current from the table's
+     * change events (local writes and synced changes alike). Publication checks against it:
+     * every start publishes every provider in every context, and reading rows for each one
+     * cost thousands of queries per start on a phone.
+     */
+    private rows?;
+    /** Rows changed since they were last reconciled. */
+    private readonly changed;
+    private readonly pendingRows;
+    private readonly revisions;
     /** Bind to the registry shared by host and isolated providers in this context. */
     constructor(dataContext: DataContext, registry: ContractRegistry);
     private enqueue;
     /** Await successful backfill and system publication. Failed initialization can be retried. */
     ready(): Promise<void>;
+    private initialized;
+    /** True while change events keep {@link rows} current. */
+    private live;
+    /**
+     * Read this context's rows into memory, after subscribing to the table's changes so none
+     * is missed while the read is in flight. A row that changes during the read keeps the
+     * changed version. Where the table can't report changes (a client process whose table
+     * events are off), the rows are read again before each use instead.
+     */
+    private load;
+    /** Read partial notifications in batches, retrying only rows changed during the read. */
+    private loadPendingRows;
+    /** Stop watching the table and forget its rows (after a failed start, or on dispose). */
+    private forget;
+    /**
+     * Record silent writes, but never replace a newer event with an older write result.
+     */
+    private write;
+    private get rowMap();
+    private queueReconciliation;
     private assertLive;
     private validate;
     /**
@@ -80,6 +111,7 @@ export declare class ToolCatalog {
      * leaves every other column, including concurrently synced policy, untouched.
      */
     private refresh;
+    /** Re-derive catalog state for these rows (all of them at startup, then those that change). */
     private reconcile;
     /**
      * Patch supplemental metadata of existing system members, preserving identity,

package/dist/contracts/tool-catalog.js

@@ -6,6 +6,7 @@ exports.retainToolCatalogFields = retainToolCatalogFields;
 exports.validateToolCatalogWrite = validateToolCatalogWrite;
 const lodash_1 = require("lodash");
 const tools_1 = require("../data/tools");
+const rpc_types_1 = require("../rpc-types");
 const registry_1 = require("./registry");
 const system_contracts_1 = require("./system-contracts");
 const tool_catalog_identity_1 = require("./tool-catalog-identity");
@@ -238,6 +239,14 @@ function resolvedFields(target, toolId) {
         catalogReason: undefined,
     };
 }
+/** Table writes normally report full rows; incomplete notifications need a storage read. */
+function isCompleteRow(row) {
+    return (row.name !== undefined &&
+        row.usageDescription !== undefined &&
+        row.inputSchema !== undefined &&
+        row.outputSchema !== undefined &&
+        row.code !== undefined);
+}
 /**
  * Per-context runtime owner of permanent Tools identities. Construction is inert;
  * ready() explicitly initializes storage after UserContext construction completes.
@@ -251,6 +260,17 @@ class ToolCatalog {
     subscription;
     disposed = false;
     reconciliationQueued = false;
+    /**
+     * This context's Tools rows, read once by {@link ready} and kept current from the table's
+     * change events (local writes and synced changes alike). Publication checks against it:
+     * every start publishes every provider in every context, and reading rows for each one
+     * cost thousands of queries per start on a phone.
+     */
+    rows;
+    /** Rows changed since they were last reconciled. */
+    changed = new Set();
+    pendingRows = new Set();
+    revisions = new Map();
     /** Bind to the registry shared by host and isolated providers in this context. */
     constructor(dataContext, registry) {
         this.dataContext = dataContext;
@@ -274,7 +294,8 @@ class ToolCatalog {
             return Promise.reject(new Error("Tool catalog disposed"));
         if (!this.initialization) {
             this.initialization = this.enqueue(async () => {
-                await this.reconcile();
+                await this.load();
+                await this.reconcile([...this.rowMap.keys()]);
                 const groups = new Map();
                 for (const entry of (0, system_contracts_1.listSystemContracts)()) {
                     const entries = groups.get(entry.providerPackageId) ?? [];
@@ -295,25 +316,148 @@ class ToolCatalog {
                         this.registry.replaceBatch(provider, registrations);
                     }
                 });
-                // dispose() may have run while initialization awaited storage; it has
-                // already unsubscribed, so a late subscription would never be released.
+                // dispose() may have run while initialization awaited storage.
                 this.assertLive();
-                this.subscription ??= (0, tools_1.Tools)(this.dataContext).dataChanged.subscribe(() => {
-                    if (this.reconciliationQueued || this.disposed)
-                        return;
-                    this.reconciliationQueued = true;
-                    void this.enqueue(async () => {
-                        this.reconciliationQueued = false;
-                        await this.reconcile();
-                    }).catch((error) => console.error("Tool catalog reconciliation failed", error));
-                });
+                this.initialized = true;
+                this.queueReconciliation();
             }).catch((error) => {
                 this.initialization = undefined;
+                this.forget();
                 throw error;
             });
         }
         return this.initialization;
     }
+    initialized = false;
+    /** True while change events keep {@link rows} current. */
+    live = false;
+    /**
+     * Read this context's rows into memory, after subscribing to the table's changes so none
+     * is missed while the read is in flight. A row that changes during the read keeps the
+     * changed version. Where the table can't report changes (a client process whose table
+     * events are off), the rows are read again before each use instead.
+     */
+    async load() {
+        // Work queued before dispose() would otherwise subscribe again, and nothing would release it.
+        this.assertLive();
+        if (this.rows && this.live)
+            return this.loadPendingRows();
+        const table = (0, tools_1.Tools)(this.dataContext);
+        const rows = new Map();
+        const seen = new Set();
+        if (!this.subscription && table.dataChanged && !(rpc_types_1.isClient && !(0, rpc_types_1.isSingleProcessClient)())) {
+            this.subscription = table.dataChanged.subscribe((event) => {
+                const toolId = event.dataObject.toolId;
+                this.revisions.set(toolId, (this.revisions.get(toolId) ?? 0) + 1);
+                if (!this.rows)
+                    seen.add(toolId);
+                const target = this.rows ?? rows;
+                if (event.op === "delete")
+                    target.delete(toolId);
+                // Full replacements clear omitted optional fields in SQL. Merging would retain
+                // removed provenance, descriptions or quarantine evidence indefinitely.
+                else if (isCompleteRow(event.dataObject))
+                    target.set(toolId, (0, lodash_1.cloneDeep)(event.dataObject));
+                else
+                    this.pendingRows.add(toolId);
+                this.changed.add(toolId);
+                if (this.initialized)
+                    this.queueReconciliation();
+            });
+            this.live = true;
+        }
+        for (const row of await table.list()) {
+            if (!seen.has(row.toolId))
+                rows.set(row.toolId, row);
+        }
+        this.assertLive();
+        this.rows = rows;
+        if (this.pendingRows.size)
+            await this.loadPendingRows();
+    }
+    /** Read partial notifications in batches, retrying only rows changed during the read. */
+    async loadPendingRows() {
+        while (this.pendingRows.size) {
+            const ids = [...this.pendingRows].slice(0, 500);
+            const revisions = ids.map((id) => this.revisions.get(id));
+            const rows = new Map((await (0, tools_1.Tools)(this.dataContext).list({ toolId: { $in: ids } })).map((row) => [
+                row.toolId,
+                row,
+            ]));
+            this.assertLive();
+            ids.forEach((id, index) => {
+                if (this.revisions.get(id) !== revisions[index])
+                    return;
+                const row = rows.get(id);
+                if (row)
+                    this.rowMap.set(id, row);
+                else
+                    this.rowMap.delete(id);
+                this.pendingRows.delete(id);
+            });
+        }
+    }
+    /** Stop watching the table and forget its rows (after a failed start, or on dispose). */
+    forget() {
+        this.subscription?.unsubscribe();
+        this.subscription = undefined;
+        this.live = false;
+        this.rows = undefined;
+        this.changed.clear();
+        this.pendingRows.clear();
+        this.revisions.clear();
+        this.initialized = false;
+    }
+    /**
+     * Record silent writes, but never replace a newer event with an older write result.
+     */
+    async write(toolId, save) {
+        const revision = this.revisions.get(toolId);
+        let row;
+        try {
+            row = await save();
+        }
+        catch (error) {
+            // The row write can succeed before history persistence fails and suppresses its event.
+            if (this.rows)
+                this.pendingRows.add(toolId);
+            throw error;
+        }
+        if (this.rows && this.revisions.get(toolId) === revision) {
+            // Table returns and event payloads can still be held and edited by their caller.
+            if (isCompleteRow(row))
+                this.rows.set(toolId, (0, lodash_1.cloneDeep)(row));
+            else
+                this.pendingRows.add(toolId);
+        }
+        return row;
+    }
+    get rowMap() {
+        if (!this.rows)
+            throw new Error("Tool catalog is not ready");
+        return this.rows;
+    }
+    queueReconciliation() {
+        if (this.reconciliationQueued || this.disposed || !this.changed.size)
+            return;
+        this.reconciliationQueued = true;
+        void this.enqueue(async () => {
+            this.reconciliationQueued = false;
+            const ids = [...this.changed];
+            this.changed.clear();
+            try {
+                if (this.pendingRows.size)
+                    await this.loadPendingRows();
+                await this.reconcile(ids);
+            }
+            catch (error) {
+                // Keep failed and unvisited rows for the next event, like the old full pass.
+                for (const id of ids)
+                    this.changed.add(id);
+                throw error;
+            }
+        }).catch((error) => console.error("Tool catalog reconciliation failed", error));
+    }
     assertLive() {
         if (this.disposed)
             throw new Error("Tool catalog disposed");
@@ -349,6 +493,7 @@ class ToolCatalog {
         }
         await this.ready();
         return this.enqueue(async () => {
+            await this.load();
             this.validate(provider, registrations);
             await this.materialize(registrations, false);
             await prepare();
@@ -356,7 +501,9 @@ class ToolCatalog {
             await this.materialize(registrations, true, provider);
             for (const metadata of toolMetadata) {
                 for (const toolId of (0, tool_catalog_migrations_1.toolCatalogIds)(metadata)) {
-                    const stored = await (0, tools_1.Tools)(this.dataContext).get(toolId);
+                    if (this.pendingRows.size)
+                        await this.loadPendingRows();
+                    const stored = this.rowMap.get(toolId);
                     if (!stored || stored.catalogState !== "resolved")
                         throw new Error(`Missing or quarantined tool identity: ${toolId}`);
                     await this.refresh({ ...metadata, toolId }, stored, tools_1.toolCatalogSupplementalFields);
@@ -392,6 +539,7 @@ class ToolCatalog {
             if (!expected.has(toolId))
                 return;
             try {
+                // Validate the payload as written: a partial row that omits identity fails closed.
                 validateRow(toolId, event.op === "delete" ? undefined : event.dataObject);
             }
             catch (error) {
@@ -405,8 +553,10 @@ class ToolCatalog {
                 this.validate(provider, registrations);
         };
         try {
+            // Clients without table events need the same final storage check as before caching.
+            await this.load();
             for (const toolId of expected.keys())
-                validateRow(toolId, await table.get(toolId));
+                validateRow(toolId, this.rowMap.get(toolId));
             assertCatalogCurrent();
             return await activate(assertCatalogCurrent);
         }
@@ -443,8 +593,9 @@ class ToolCatalog {
      * definition's name, usage description and IO schemas.
      */
     async materialize(registrations, refresh, provider) {
+        await this.load();
         const table = (0, tools_1.Tools)(this.dataContext);
-        const existing = new Map((await table.list()).map((row) => [row.toolId, row]));
+        const existing = this.rowMap;
         const identities = new Map();
         // Reserve the entire reviewed inventory, even on an empty database.
         for (const entry of tool_catalog_migrations_1.toolCatalogMigrations)
@@ -486,23 +637,32 @@ class ToolCatalog {
         // Validate the entire batch before the first write. Catalog metadata never
         // overwrites provider-specific policy or another provider's descriptions.
         for (const row of candidates.values()) {
+            if (this.pendingRows.size)
+                await this.loadPendingRows();
             const previous = existing.get(row.toolId);
+            let restored;
             // Restore missing identity columns only after validating the entire batch.
             // This marked patch leaves concurrent policy and historical fields intact.
             if (previous &&
                 (canRestoreBareDeterministicRow(previous, row) || canResolveMissingTarget(previous, row))) {
-                const restored = await table.update((0, tools_1.toolCatalogPatch)({
+                restored = await this.write(row.toolId, () => table.update((0, tools_1.toolCatalogPatch)({
                     toolId: row.toolId,
                     ...resolvedFields(toolCatalogTarget(row), row.toolId),
-                }));
+                })));
                 validateToolCatalogWrite(row, restored);
                 if (restored.catalogState === "quarantined")
                     throw new Error(`Quarantined tool identity: ${row.toolId}`);
             }
-            // Older runtimes allowed provider removal to leave tombstones. Only a
-            // validated public target may restore one; insert-only still preserves any
-            // row that arrived concurrently, and the returned mapping is checked below.
-            const stored = await table.save(row, { insertOnly: true, restoreIfDeleted: true });
+            // A row already in memory needs no insert-only save, which would only read it back:
+            // every start would cost a query per tool per context. A row that changes later is
+            // caught by guardActivation, which checks again under a subscription before anything
+            // activates. Older runtimes allowed provider removal to leave tombstones, which aren't
+            // in memory: only a validated public target may restore one, and insert-only still
+            // preserves a row that arrived concurrently.
+            let stored = restored ?? previous;
+            if (!stored) {
+                stored = await this.write(row.toolId, () => table.save(row, { insertOnly: true, restoreIfDeleted: true }));
+            }
             validateToolCatalogWrite(row, stored);
             if (!stored || stored.catalogState === "quarantined")
                 throw new Error(`Catalog insert did not succeed: ${row.toolId}`);
@@ -521,14 +681,20 @@ class ToolCatalog {
         const patch = { toolId: desired.toolId };
         for (const field of changed)
             Object.assign(patch, { [field]: desired[field] });
-        const refreshed = await (0, tools_1.Tools)(this.dataContext).update((0, tools_1.toolCatalogPatch)(patch));
+        const refreshed = await this.write(desired.toolId, () => (0, tools_1.Tools)(this.dataContext).update((0, tools_1.toolCatalogPatch)(patch)));
         validateToolCatalogWrite(stored, refreshed);
         if (refreshed.catalogState === "quarantined")
             throw new Error(`Quarantined tool identity: ${desired.toolId}`);
     }
-    async reconcile() {
+    /** Re-derive catalog state for these rows (all of them at startup, then those that change). */
+    async reconcile(toolIds) {
         const table = (0, tools_1.Tools)(this.dataContext);
-        for (const row of await table.list()) {
+        for (const toolId of toolIds) {
+            if (this.pendingRows.size)
+                await this.loadPendingRows();
+            const row = this.rowMap.get(toolId);
+            if (!row)
+                continue;
             let fields;
             // Quarantine is sticky: conflicting evidence is never silently rehabilitated. The one
             // exception is a row quarantined for its missing target that has since received the
@@ -540,7 +706,10 @@ class ToolCatalog {
                 const resolved = { ...row, ...resolvedFields(target, row.toolId) };
                 if (!canResolveMissingTarget(row, resolved))
                     continue;
-                await table.update((0, tools_1.toolCatalogPatch)({ toolId: row.toolId, ...resolvedFields(target, row.toolId) }));
+                await this.write(row.toolId, () => table.update((0, tools_1.toolCatalogPatch)({
+                    toolId: row.toolId,
+                    ...resolvedFields(target, row.toolId),
+                })));
                 continue;
             }
             try {
@@ -554,7 +723,7 @@ class ToolCatalog {
             if (Object.entries(fields).some(([key, value]) => row[key] !== value)) {
                 // Update only catalog-owned fields. A sync write may have changed legacy
                 // metadata since list() returned; writing the snapshot back would lose it.
-                await table.update((0, tools_1.toolCatalogPatch)({ toolId: row.toolId, ...fields }));
+                await this.write(row.toolId, () => table.update((0, tools_1.toolCatalogPatch)({ toolId: row.toolId, ...fields })));
             }
         }
     }
@@ -566,6 +735,7 @@ class ToolCatalog {
     async saveToolMetadata(entries) {
         await this.ready();
         await this.enqueue(async () => {
+            await this.load();
             const members = (0, system_contracts_1.listSystemContracts)().flatMap((entry) => {
                 const definition = entry.getDefinition();
                 return definition.tools.map((tool) => ({
@@ -578,7 +748,7 @@ class ToolCatalog {
             for (const entry of entries) {
                 const target = (0, tool_catalog_migrations_1.resolveLegacyToolId)(entry.toolId) ??
                     members.find((member) => (0, tool_catalog_migrations_1.toolCatalogIds)(member).includes(entry.toolId));
-                const stored = await (0, tools_1.Tools)(this.dataContext).get(entry.toolId);
+                const stored = this.rowMap.get(entry.toolId);
                 if (!target ||
                     !members.some((member) => (0, tool_catalog_identity_1.toolCatalogTargetKey)(member) === (0, tool_catalog_identity_1.toolCatalogTargetKey)(target)) ||
                     !stored ||
@@ -626,7 +796,7 @@ class ToolCatalog {
     /** Stop subscriptions and queued lifecycle work; permanent rows are retained. */
     async dispose() {
         this.disposed = true;
-        this.subscription?.unsubscribe();
+        this.forget();
         await this.tail;
     }
 }

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

@@ -312,6 +312,14 @@ async function checkDevice(existing, candidate, context) {
         !signed(candidate)) {
         throw (0, write_checks_1.writeNotAuthorized)("Devices", "the ownership claim doesn't verify");
     }
+    // Only the owner publishes how to dial its device. Sync keeps the stored block when a writer
+    // drops it or holds an older one (retainDeviceReachability), so this refuses only a forgery.
+    if (candidate?.reachability &&
+        (candidate.userId !== existing?.userId ||
+            !(0, devices_1.sameDeviceReachability)(candidate.reachability, existing?.reachability)) &&
+        !(0, devices_1.isDeviceReachabilitySigned)(candidate, users.get(ownerId ?? candidate.userId)?.publicKey)) {
+        throw (0, write_checks_1.writeNotAuthorized)("Devices", "reachability isn't signed by the device's owner");
+    }
 }
 (0, write_checks_1.registerTableWriteCheck)("Users", checkUser);
 (0, write_checks_1.registerTableWriteCheck)("Devices", checkDevice);

package/dist/data/devices.d.ts

@@ -5,6 +5,34 @@ import { TrustLevel } from "../device/socket.type";
 export declare const DISPLAY_NAME_MAX_LENGTH = 128;
 /** Shared schema for bounded user and device display names. */
 export declare const displayNameSchema: z.ZodString;
+/** Most origins one device publishes: every LAN interface plus a configured public origin. */
+export declare const DEVICE_REACHABILITY_MAX_ADDRESSES = 16;
+/** Most protocol names one device publishes. */
+export declare const DEVICE_REACHABILITY_MAX_PROTOCOLS = 8;
+/**
+ * How a device can be dialed, published by its owner on its own Devices row: the origins its peer
+ * listener accepts connections on, and the protocols it supports. Only the owner writes it, signed
+ * with the owner's key, and the newest signed `updatedAt` wins. Addresses are a fast path; every
+ * dial still checks that the expected device answers.
+ */
+export declare const deviceReachabilitySchema: z.ZodObject<{
+    addresses: z.ZodArray<z.ZodString, "many">;
+    protocols: z.ZodArray<z.ZodString, "many">;
+    updatedAt: z.ZodNumber;
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    updatedAt: number;
+    addresses: string[];
+    protocols: string[];
+}, {
+    signature: string;
+    updatedAt: number;
+    addresses: string[];
+    protocols: string[];
+}>;
+/** How a device can be dialed, as its owner published it (see {@link deviceReachabilitySchema}). */
+export type IDeviceReachability = z.infer<typeof deviceReachabilitySchema>;
 /** Schema for a persisted, context-scoped device record. */
 export declare const deviceSchema: z.ZodObject<{
     deviceId: z.ZodEffects<z.ZodString, string, string>;
@@ -16,6 +44,22 @@ export declare const deviceSchema: z.ZodObject<{
     serverUrl: z.ZodOptional<z.ZodString>;
     trustLevel: z.ZodNativeEnum<typeof TrustLevel>;
     ownerSignature: z.ZodOptional<z.ZodString>;
+    reachability: z.ZodOptional<z.ZodObject<{
+        addresses: z.ZodArray<z.ZodString, "many">;
+        protocols: z.ZodArray<z.ZodString, "many">;
+        updatedAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    }, {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    }>>;
 }, "strip", z.ZodTypeAny, {
     userId: string;
     deviceId: string;
@@ -26,6 +70,12 @@ export declare const deviceSchema: z.ZodObject<{
     reportedName?: string | undefined;
     serverUrl?: string | undefined;
     ownerSignature?: string | undefined;
+    reachability?: {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    } | undefined;
 }, {
     userId: string;
     deviceId: string;
@@ -36,6 +86,12 @@ export declare const deviceSchema: z.ZodObject<{
     reportedName?: string | undefined;
     serverUrl?: string | undefined;
     ownerSignature?: string | undefined;
+    reachability?: {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    } | undefined;
 }>;
 /** A context-scoped device record containing local state and owner-reported metadata. */
 export type IDevice = z.infer<typeof deviceSchema>;
@@ -58,6 +114,41 @@ export declare function deviceOwnerStatement(device: Pick<IDevice, "deviceId" |
  * @param ownerPublicKey - The signing key of `device.userId`, as this device knows it.
  */
 export declare function isDeviceOwnerSigned(device: Pick<IDevice, "deviceId" | "userId" | "ownerSignature">, ownerPublicKey: string | undefined): boolean;
+/**
+ * What a device's owner signs to publish how to dial it: the contents of
+ * `reachability.signature`. Arrays are signed in the order given, so publishers sort them.
+ *
+ * @param deviceId - The device the reachability is for.
+ * @param reachability - Its addresses, protocols and publishing time.
+ */
+export declare function deviceReachabilityStatement(deviceId: string, reachability: Pick<IDeviceReachability, "addresses" | "protocols" | "updatedAt">): {
+    purpose: string;
+    deviceId: string;
+    addresses: string[];
+    protocols: string[];
+    updatedAt: number;
+};
+/**
+ * Whether `device.reachability` carries `ownerPublicKey`'s signature over
+ * {@link deviceReachabilityStatement}: the device's owner published it, not whoever wrote the row.
+ *
+ * @param device - A Devices row.
+ * @param ownerPublicKey - The signing key of the device's owner, as this device knows it.
+ */
+export declare function isDeviceReachabilitySigned(device: Pick<IDevice, "deviceId" | "reachability">, ownerPublicKey: string | undefined): boolean;
+/** Whether two reachability blocks are the same publication. */
+export declare function sameDeviceReachability(a: IDeviceReachability | undefined, b: IDeviceReachability | undefined): boolean;
+/**
+ * The row to store when `candidate` replaces `existing`: the candidate, keeping the stored
+ * `reachability` when the candidate has none or an older one (a tie keeps the stored one too).
+ * Writers that don't know the field (older builds) or hold a stale copy never roll it back;
+ * only a newer publication replaces it. Signatures are checked separately, by the group write
+ * check and by whoever dials.
+ *
+ * @param existing - The row as stored now, if any.
+ * @param candidate - The row about to be stored.
+ */
+export declare function retainDeviceReachability<T extends Partial<IDevice>>(existing: Partial<IDevice> | undefined, candidate: T): T;
 /** Schema for the signed identity and bounded presentation hints exchanged by devices. */
 export declare const deviceInfoSchema: z.ZodObject<{
     userId: z.ZodEffects<z.ZodString, string, string>;
@@ -237,6 +328,12 @@ export declare function Devices(dataContext?: DataContext): import("..").Table<{
     reportedName?: string | undefined;
     serverUrl?: string | undefined;
     ownerSignature?: string | undefined;
+    reachability?: {
+        signature: string;
+        updatedAt: number;
+        addresses: string[];
+        protocols: string[];
+    } | undefined;
 }>;
 /** Persistent identifier for the current physical/runtime device. */
 export declare const thisDeviceId: import("./persistent-vars").PersistentVar<string | undefined>;

package/dist/data/devices.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.thisDeviceId = exports.deviceHandshakeSchema = exports.handshakeFrameCryptoSchema = exports.deviceInfoSchema = exports.deviceSchema = exports.displayNameSchema = exports.DISPLAY_NAME_MAX_LENGTH = void 0;
+exports.thisDeviceId = exports.deviceHandshakeSchema = exports.handshakeFrameCryptoSchema = exports.deviceInfoSchema = exports.deviceSchema = exports.deviceReachabilitySchema = exports.DEVICE_REACHABILITY_MAX_PROTOCOLS = exports.DEVICE_REACHABILITY_MAX_ADDRESSES = exports.displayNameSchema = exports.DISPLAY_NAME_MAX_LENGTH = void 0;
 exports.deviceOwnerStatement = deviceOwnerStatement;
 exports.isDeviceOwnerSigned = isDeviceOwnerSigned;
+exports.deviceReachabilityStatement = deviceReachabilityStatement;
+exports.isDeviceReachabilitySigned = isDeviceReachabilitySigned;
+exports.sameDeviceReachability = sameDeviceReachability;
+exports.retainDeviceReachability = retainDeviceReachability;
 exports.Devices = Devices;
 const zod_1 = require("zod");
 const user_context_singleton_1 = require("../context/user-context-singleton");
@@ -17,6 +21,30 @@ const persistent_vars_1 = require("./persistent-vars");
 exports.DISPLAY_NAME_MAX_LENGTH = 128;
 /** Shared schema for bounded user and device display names. */
 exports.displayNameSchema = zod_1.z.string().max(exports.DISPLAY_NAME_MAX_LENGTH);
+/** Most origins one device publishes: every LAN interface plus a configured public origin. */
+exports.DEVICE_REACHABILITY_MAX_ADDRESSES = 16;
+/** Most protocol names one device publishes. */
+exports.DEVICE_REACHABILITY_MAX_PROTOCOLS = 8;
+/**
+ * How a device can be dialed, published by its owner on its own Devices row: the origins its peer
+ * listener accepts connections on, and the protocols it supports. Only the owner writes it, signed
+ * with the owner's key, and the newest signed `updatedAt` wins. Addresses are a fast path; every
+ * dial still checks that the expected device answers.
+ */
+exports.deviceReachabilitySchema = zod_1.z.object({
+    addresses: zod_1.z
+        .array(zod_1.z.string().max(256))
+        .max(exports.DEVICE_REACHABILITY_MAX_ADDRESSES)
+        .describe("Origins the device's peer listener accepts connections on, in a stable order"),
+    protocols: zod_1.z
+        .array(zod_1.z.string().max(32))
+        .max(exports.DEVICE_REACHABILITY_MAX_PROTOCOLS)
+        .describe("Protocols the device can be dialed with, such as ws and wrtc"),
+    updatedAt: zod_1.z.number().describe("When the owner published this, in ms; the newest one wins"),
+    signature: zod_1.z
+        .string()
+        .describe("The owner's signature over deviceReachabilityStatement, without the key prefix"),
+});
 /** Schema for a persisted, context-scoped device record. */
 exports.deviceSchema = zod_1.z.object({
     deviceId: zod_types_1.zodPeerId,
@@ -31,6 +59,9 @@ exports.deviceSchema = zod_1.z.object({
         .string()
         .optional()
         .describe("The owner's signature claiming this device for userId (see deviceOwnerStatement). In a group, only a row with a valid one says who a device belongs to, and it stays theirs"),
+    reachability: exports.deviceReachabilitySchema
+        .optional()
+        .describe("How to dial this device, published and signed by its owner. Sync keeps the newest signed copy, so a writer without it never clears it"),
 });
 /**
  * What a device's owner signs to claim it: the contents of `ownerSignature`. Each device signs
@@ -56,6 +87,74 @@ function isDeviceOwnerSigned(device, ownerPublicKey) {
         signature: `${ownerPublicKey}:${device.ownerSignature}`,
     }) === ownerPublicKey);
 }
+/**
+ * What a device's owner signs to publish how to dial it: the contents of
+ * `reachability.signature`. Arrays are signed in the order given, so publishers sort them.
+ *
+ * @param deviceId - The device the reachability is for.
+ * @param reachability - Its addresses, protocols and publishing time.
+ */
+function deviceReachabilityStatement(deviceId, reachability) {
+    return {
+        purpose: "peers-device-reachability",
+        deviceId,
+        addresses: reachability.addresses,
+        protocols: reachability.protocols,
+        updatedAt: reachability.updatedAt,
+    };
+}
+/**
+ * Whether `device.reachability` carries `ownerPublicKey`'s signature over
+ * {@link deviceReachabilityStatement}: the device's owner published it, not whoever wrote the row.
+ *
+ * @param device - A Devices row.
+ * @param ownerPublicKey - The signing key of the device's owner, as this device knows it.
+ */
+function isDeviceReachabilitySigned(device, ownerPublicKey) {
+    const reachability = device.reachability;
+    if (!reachability?.signature || !ownerPublicKey)
+        return false;
+    return ((0, keys_1.signedByKey)({
+        ...deviceReachabilityStatement(device.deviceId, reachability),
+        signature: `${ownerPublicKey}:${reachability.signature}`,
+    }) === ownerPublicKey);
+}
+/** Whether two reachability blocks are the same publication. */
+function sameDeviceReachability(a, b) {
+    if (!a || !b)
+        return a === b;
+    return (a.updatedAt === b.updatedAt &&
+        a.signature === b.signature &&
+        a.addresses.length === b.addresses.length &&
+        a.addresses.every((address, i) => address === b.addresses[i]) &&
+        a.protocols.length === b.protocols.length &&
+        a.protocols.every((protocol, i) => protocol === b.protocols[i]));
+}
+/**
+ * The row to store when `candidate` replaces `existing`: the candidate, keeping the stored
+ * `reachability` when the candidate has none or an older one (a tie keeps the stored one too).
+ * Writers that don't know the field (older builds) or hold a stale copy never roll it back;
+ * only a newer publication replaces it. Signatures are checked separately, by the group write
+ * check and by whoever dials.
+ *
+ * @param existing - The row as stored now, if any.
+ * @param candidate - The row about to be stored.
+ */
+function retainDeviceReachability(existing, candidate) {
+    const stored = existing?.reachability;
+    if (!stored)
+        return candidate;
+    // An unclaimed discovery row can acquire a different owner. Its former owner's
+    // publication must neither follow that claim nor prevent the new owner's publication.
+    if (existing.userId && candidate.userId && existing.userId !== candidate.userId)
+        return candidate;
+    const incoming = candidate.reachability;
+    if (incoming && incoming.updatedAt > stored.updatedAt)
+        return candidate;
+    if (incoming && sameDeviceReachability(incoming, stored))
+        return candidate;
+    return { ...candidate, reachability: stored };
+}
 /** Schema for the signed identity and bounded presentation hints exchanged by devices. */
 exports.deviceInfoSchema = zod_1.z.object({
     userId: zod_types_1.zodPeerId,

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

@@ -21,6 +21,8 @@ export declare class Table<T extends {
     protected readonly dataChangedEmitter: Emitter<IDataChangedEvent<T>>;
     readonly dataChanged: Event<IDataChangedEvent<T>>;
     private readonly localOperationCache;
+    /** Rows committed by an in-progress local write, for {@link reportCommittedLocalWrite}. */
+    private readonly committedLocalEvents;
     readonly dataSource: IDataSource<T>;
     readonly metaData: ITableMetaData;
     readonly groupId?: string;
@@ -28,6 +30,12 @@ export declare class Table<T extends {
     private getRecordId;
     private setLocalOperation;
     private clearLocalOperation;
+    /**
+     * A local write failed after its row was committed (for example, a tracked table's history
+     * write failed). Tell subscribers about the committed row, as a successful write would, so
+     * a cache of this table (the Tools catalog's) doesn't miss it.
+     */
+    private reportCommittedLocalWrite;
     private cachedRecords;
     get(id: string, opts?: {
         useCache?: boolean;

package/dist/data/orm/table.js

@@ -28,6 +28,8 @@ class Table {
     dataChangedEmitter;
     dataChanged;
     localOperationCache = new Map();
+    /** Rows committed by an in-progress local write, for {@link reportCommittedLocalWrite}. */
+    committedLocalEvents = new Map();
     dataSource;
     metaData;
     groupId;
@@ -79,6 +81,12 @@ class Table {
                         source: "remote",
                     });
                 }
+                else {
+                    // A local write's row is committed, but the write can still fail after it (a
+                    // tracked table's history write). Keep the event, so a failed write still reports
+                    // the committed row; a successful one emits its own event instead.
+                    this.committedLocalEvents.set(recordId, event);
+                }
             });
         }
     }
@@ -92,6 +100,17 @@ class Table {
     clearLocalOperation(recordId, operation) {
         const cacheKey = `${recordId}-${operation}`;
         this.localOperationCache.delete(cacheKey);
+        this.committedLocalEvents.delete(recordId);
+    }
+    /**
+     * A local write failed after its row was committed (for example, a tracked table's history
+     * write failed). Tell subscribers about the committed row, as a successful write would, so
+     * a cache of this table (the Tools catalog's) doesn't miss it.
+     */
+    reportCommittedLocalWrite(recordId) {
+        const event = this.committedLocalEvents.get(recordId);
+        if (event)
+            this.dataChangedEmitter.emit({ ...event, source: "local" });
     }
     cachedRecords = {};
     async get(id, opts = {}) {
@@ -161,6 +180,10 @@ class Table {
             // TODO: try to avoid the double-read, probably by passing the just-read result as `opts.dbData`
             result = await this.dataSource.save(record, opts);
         }
+        catch (error) {
+            this.reportCommittedLocalWrite(recordId);
+            throw error;
+        }
         finally {
             this.clearLocalOperation(recordId, operation);
         }
@@ -178,6 +201,10 @@ class Table {
         try {
             result = await this.dataSource.insert(record);
         }
+        catch (error) {
+            this.reportCommittedLocalWrite(recordId);
+            throw error;
+        }
         finally {
             this.clearLocalOperation(recordId, "insert");
         }
@@ -196,6 +223,10 @@ class Table {
         try {
             result = await this.dataSource.update(record);
         }
+        catch (error) {
+            this.reportCommittedLocalWrite(recordId);
+            throw error;
+        }
         finally {
             this.clearLocalOperation(recordId, "update");
         }
@@ -217,6 +248,10 @@ class Table {
         try {
             await this.dataSource.delete(idOrRecord);
         }
+        catch (error) {
+            this.reportCommittedLocalWrite(primaryKey);
+            throw error;
+        }
         finally {
             this.clearLocalOperation(primaryKey, "delete");
         }

package/package.json

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