@peers-app/peers-sdk 0.23.11 → 0.23.13

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

@@ -7,7 +7,12 @@
  */
 import { z } from "zod";
 import { Emitter, type Event } from "../events";
+import { HybridLogicalClock } from "../hlc";
 import { type DataFilter, type IDataQueryParams, type ISqlDb, type ITableMetaData, SQLDataSource } from "./orm";
+/**
+ * Zod schema for a single granular change-log row in `ChangeTrackingV2`.
+ * `appliedAt` is assigned locally at insert time; incoming values are replaced.
+ */
 export declare const changeRecordSchema: z.ZodObject<{
     changeId: z.ZodEffects<z.ZodString, string, string>;
     transactionId: z.ZodOptional<z.ZodString>;
@@ -42,13 +47,57 @@ export declare const changeRecordSchema: z.ZodObject<{
     transactionId?: string | undefined;
     supersededAt?: number | undefined;
 }>;
+/**
+ * One JSON-patch operation (or root snapshot / delete) stored for synchronization.
+ */
 export type IChangeRecord = z.infer<typeof changeRecordSchema>;
+/**
+ * Local-only change log used for peer sync.
+ *
+ * Owns two {@link HybridLogicalClock} instances for this database:
+ * - {@link clock} stamps `createdAt` / `supersededAt` (cross-device LWW)
+ * - `appliedClock` stamps `appliedAt` at insert time (per-device sync watermark)
+ */
 export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
     readonly dataChangedEmitter: Emitter<IChangeRecord>;
     readonly dataChanged: Event<IChangeRecord>;
-    constructor({ db }: {
+    /**
+     * Hybrid logical clock for author write times (`createdAt`, `supersededAt`).
+     * Observes accepted incoming `createdAt` values so later local writes order after them.
+     */
+    readonly clock: HybridLogicalClock;
+    private readonly appliedClock;
+    private clockInit;
+    /**
+     * @param db - SQLite database that stores `ChangeTrackingV2`
+     * @param now - Optional physical-time source shared by both clocks (defaults to {@link getTimestamp})
+     */
+    constructor({ db, now }: {
         db: ISqlDb;
+        now?: () => number;
     });
+    /**
+     * Ensures the table exists, seeds both clocks from durable history, and
+     * rewrites any far-future `createdAt` rows this device still owns.
+     *
+     * @param force - Re-run table migration and clock seeding
+     */
+    initTable(force?: boolean): Promise<boolean>;
+    /**
+     * Drop the change-tracking table and clear memoized clock seeding so the next
+     * {@link initTable} reseeds from an empty (or newly created) table.
+     */
+    dropTableIfExists(): Promise<void>;
+    private seedClocksAndRepair;
+    /**
+     * Rewrite local rows whose `createdAt` is beyond the change-timestamp bound.
+     * `createdAt` is restamped from {@link clock} (near wall time) and `appliedAt`
+     * from the unbounded apply clock so peers whose watermark already passed the
+     * old value will pull the repaired rows.
+     *
+     * @returns Number of rows rewritten
+     */
+    repairFutureTimestamps(): Promise<number>;
     /**
      * Efficiently find which recordIds have been deleted.
      *
@@ -79,6 +128,10 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      * @returns Array of changeIds with no change records
      */
     filterToMissingChangeIds(changeIds: string[]): Promise<string[]>;
+    /**
+     * Mark every still-active change for `recordId` whose `createdAt` is older
+     * than `supersededAt`. Used after a root snapshot, delete, or restore.
+     */
     markAllPriorChangesSuperseded(tableName: string, recordId: string, supersededAt: number): Promise<void>;
     /**
      * Batch update supersededAt timestamps for multiple changes.
@@ -99,7 +152,8 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
      */
     get(id: string): Promise<IChangeRecord | undefined>;
     /**
-     * Override to serialize value field to JSON string
+     * Insert a change row, assigning `appliedAt` from the local apply clock
+     * immediately before the SQL statement so watermarks stay monotonic.
      */
     insert(record: IChangeRecord): Promise<IChangeRecord>;
     /**
@@ -109,6 +163,7 @@ export declare class ChangeTrackingTable extends SQLDataSource<IChangeRecord> {
     /**
      * Synchronous insert for use within transactions.
      * Table must be initialized before calling this method.
+     * Assigns `appliedAt` from the local apply clock immediately before the SQL statement.
      */
     insertSync(record: IChangeRecord): IChangeRecord;
     /**

package/dist/data/change-tracking.js

@@ -10,10 +10,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChangeTrackingTable = exports.changeRecordSchema = void 0;
 const zod_1 = require("zod");
 const events_1 = require("../events");
+const hlc_1 = require("../hlc");
 const serial_json_1 = require("../serial-json");
+const peer_device_1 = require("../types/peer-device");
 const zod_types_1 = require("../types/zod-types");
 const utils_1 = require("../utils");
 const orm_1 = require("./orm");
+/**
+ * Zod schema for a single granular change-log row in `ChangeTrackingV2`.
+ * `appliedAt` is assigned locally at insert time; incoming values are replaced.
+ */
 exports.changeRecordSchema = zod_1.z.object({
     changeId: zod_types_1.zodPeerId,
     transactionId: zod_1.z.string().optional(), // not used for now
@@ -25,9 +31,11 @@ exports.changeRecordSchema = zod_1.z.object({
         .any()
         .nullish()
         .describe("JSON value - can be any type (object, string, number, boolean, array, null, or undefined)"),
-    createdAt: zod_1.z.number(),
-    appliedAt: zod_1.z.number(),
-    supersededAt: zod_1.z.number().optional(),
+    createdAt: zod_1.z.number().describe("Author write time from the hybrid logical clock (LWW key)"),
+    appliedAt: zod_1.z
+        .number()
+        .describe("Local apply / sync-visibility time; assigned at insert, incoming values replaced"),
+    supersededAt: zod_1.z.number().optional().describe("When this change was superseded; unset if active"),
 });
 const changeTrackingV2TableMetaData = {
     name: "ChangeTrackingV2",
@@ -47,15 +55,103 @@ const changeTrackingV2TableMetaData = {
     ],
     localOnly: true,
 };
+/**
+ * Local-only change log used for peer sync.
+ *
+ * Owns two {@link HybridLogicalClock} instances for this database:
+ * - {@link clock} stamps `createdAt` / `supersededAt` (cross-device LWW)
+ * - `appliedClock` stamps `appliedAt` at insert time (per-device sync watermark)
+ */
 class ChangeTrackingTable extends orm_1.SQLDataSource {
     dataChangedEmitter;
     dataChanged;
-    constructor({ db }) {
+    /**
+     * Hybrid logical clock for author write times (`createdAt`, `supersededAt`).
+     * Observes accepted incoming `createdAt` values so later local writes order after them.
+     */
+    clock;
+    appliedClock;
+    clockInit;
+    /**
+     * @param db - SQLite database that stores `ChangeTrackingV2`
+     * @param now - Optional physical-time source shared by both clocks (defaults to {@link getTimestamp})
+     */
+    constructor({ db, now }) {
         super(db, changeTrackingV2TableMetaData, exports.changeRecordSchema);
+        const physicalNow = now ?? utils_1.getTimestamp;
+        this.clock = new hlc_1.HybridLogicalClock({ now: physicalNow });
+        this.appliedClock = new hlc_1.HybridLogicalClock({
+            now: physicalNow,
+            maxSkewMs: Number.POSITIVE_INFINITY,
+        });
         const tableName = changeTrackingV2TableMetaData.name;
         this.dataChangedEmitter = new events_1.Emitter(`${tableName}_DataChanged_${(0, utils_1.newid)()}`);
         this.dataChanged = this.dataChangedEmitter.event;
     }
+    /**
+     * Ensures the table exists, seeds both clocks from durable history, and
+     * rewrites any far-future `createdAt` rows this device still owns.
+     *
+     * @param force - Re-run table migration and clock seeding
+     */
+    async initTable(force = false) {
+        const created = await super.initTable(force);
+        if (!this.clockInit || force) {
+            this.clockInit = this.seedClocksAndRepair();
+        }
+        await this.clockInit;
+        return created;
+    }
+    /**
+     * Drop the change-tracking table and clear memoized clock seeding so the next
+     * {@link initTable} reseeds from an empty (or newly created) table.
+     */
+    async dropTableIfExists() {
+        await super.dropTableIfExists();
+        this.clockInit = undefined;
+    }
+    async seedClocksAndRepair() {
+        const physicalNow = this.clock.now();
+        const cutoff = physicalNow + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
+        const bounds = await this.db.get(`SELECT
+         MAX(CASE WHEN createdAt <= ? THEN createdAt END) as maxCreatedAt,
+         MAX(appliedAt) as maxAppliedAt
+       FROM "${this.tableName}"`, [cutoff]);
+        if (bounds?.maxAppliedAt != null) {
+            this.appliedClock.seed(Number(bounds.maxAppliedAt));
+        }
+        if (bounds?.maxCreatedAt != null) {
+            this.clock.seed(Number(bounds.maxCreatedAt));
+        }
+        await this.repairFutureTimestamps();
+    }
+    /**
+     * Rewrite local rows whose `createdAt` is beyond the change-timestamp bound.
+     * `createdAt` is restamped from {@link clock} (near wall time) and `appliedAt`
+     * from the unbounded apply clock so peers whose watermark already passed the
+     * old value will pull the repaired rows.
+     *
+     * @returns Number of rows rewritten
+     */
+    async repairFutureTimestamps() {
+        await super.initTable();
+        const cutoff = this.clock.now() + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
+        const inBoundMax = await this.db.get(`SELECT MAX(createdAt) as maxCreatedAt FROM "${this.tableName}" WHERE createdAt <= ?`, [cutoff]);
+        if (inBoundMax?.maxCreatedAt != null) {
+            this.clock.seed(Number(inBoundMax.maxCreatedAt));
+        }
+        const rows = await this.db.all(`SELECT changeId FROM "${this.tableName}" WHERE createdAt > ? ORDER BY createdAt ASC`, [cutoff]);
+        if (rows.length === 0) {
+            return 0;
+        }
+        for (const row of rows) {
+            const createdAt = this.clock.tick();
+            const appliedAt = this.appliedClock.tick();
+            await this.db.exec(`UPDATE "${this.tableName}" SET createdAt = ?, appliedAt = ? WHERE changeId = ?`, [createdAt, appliedAt, row.changeId]);
+        }
+        console.log(`Repaired ${rows.length} change tracking row(s) with timestamps too far in the future`);
+        return rows.length;
+    }
     /**
      * Efficiently find which recordIds have been deleted.
      *
@@ -144,6 +240,10 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
     `, changeIds);
         return missingChangeIds.map((d) => d.changeId);
     }
+    /**
+     * Mark every still-active change for `recordId` whose `createdAt` is older
+     * than `supersededAt`. Used after a root snapshot, delete, or restore.
+     */
     async markAllPriorChangesSuperseded(tableName, recordId, supersededAt) {
         await this.db.exec(`
       UPDATE "${this.tableName}" 
@@ -193,9 +293,12 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
         return record ? this.deserializeValue(record) : undefined;
     }
     /**
-     * Override to serialize value field to JSON string
+     * Insert a change row, assigning `appliedAt` from the local apply clock
+     * immediately before the SQL statement so watermarks stay monotonic.
      */
     async insert(record) {
+        await this.initTable();
+        record.appliedAt = this.appliedClock.tick();
         if (record.value !== undefined) {
             record.value = (0, serial_json_1.toJSONString)(record.value);
         }
@@ -216,8 +319,10 @@ class ChangeTrackingTable extends orm_1.SQLDataSource {
     /**
      * Synchronous insert for use within transactions.
      * Table must be initialized before calling this method.
+     * Assigns `appliedAt` from the local apply clock immediately before the SQL statement.
      */
     insertSync(record) {
+        record.appliedAt = this.appliedClock.tick();
         if (record.value !== undefined) {
             record = { ...record, value: (0, serial_json_1.toJSONString)(record.value) };
         }

package/dist/device/connection.js

@@ -4,9 +4,9 @@ exports.Connection = void 0;
 exports.normalizeAddress = normalizeAddress;
 const data_1 = require("../data");
 const keys_1 = require("../keys");
+const peer_device_1 = require("../types/peer-device");
 const utils_1 = require("../utils");
 const socket_type_1 = require("./socket.type");
-const HANDSHAKE_TIMESTAMP_TOLERANCE_MS = 300_000; // 5 minutes
 /** Authenticated RPC connection between two Peers devices. */
 class Connection {
     localDevice;
@@ -26,7 +26,7 @@ class Connection {
     onHandshakeComplete;
     timeoutMs = 60_000; // 60 seconds
     maxChunkSize = socket_type_1.DEFAULT_MAX_CHUNK_SIZE;
-    handshakeTimestampToleranceMs = HANDSHAKE_TIMESTAMP_TOLERANCE_MS;
+    handshakeTimestampToleranceMs = peer_device_1.PeerDeviceConsts.CLOCK_SKEW_TOLERANCE_MS;
     _connectionAddress;
     get connectionAddress() {
         return this._connectionAddress;

package/dist/hlc.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Options for {@link HybridLogicalClock}.
+ */
+export interface IHybridLogicalClockOptions {
+    /**
+     * Physical-time source in milliseconds. Defaults to {@link getTimestamp}
+     * so HLC ticks stay on the same clock as existing change-log rows and tests.
+     * (`Date.now` and `performance.timeOrigin + performance.now` drift apart
+     * in long-running processes.) Injected in tests to simulate clock skew.
+     */
+    now?: () => number;
+    /**
+     * Incoming timestamps more than this many ms ahead of {@link HybridLogicalClock.now}
+     * are ignored by {@link HybridLogicalClock.observe}. Defaults to
+     * {@link PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS}.
+     */
+    maxSkewMs?: number;
+}
+/**
+ * Compact hybrid logical clock stored as a single millisecond number.
+ *
+ * `tick()` is `max(now(), last + 1)` so local timestamps stay close to wall time
+ * while remaining strictly monotonic even when the system clock jumps backward.
+ * `observe(ts)` raises `last` to a received timestamp so a later local tick
+ * always orders after a change this device has already seen.
+ */
+export declare class HybridLogicalClock {
+    private last;
+    private readonly getNow;
+    private readonly maxSkewMs;
+    /**
+     * @param opts - Optional physical-time source and observe-skew bound
+     */
+    constructor(opts?: IHybridLogicalClockOptions);
+    /**
+     * Current physical time from the injected `now` function. Does not advance the clock.
+     */
+    now(): number;
+    /**
+     * Last assigned or observed value, or `0` before the first tick/seed/observe.
+     */
+    get value(): number;
+    /**
+     * Assign the next timestamp: `last = max(now(), last + 1)`.
+     *
+     * @returns The newly assigned timestamp
+     */
+    tick(): number;
+    /**
+     * Incorporate a timestamp received from another device.
+     * Values that are not finite, or that exceed `now() + maxSkewMs`, are ignored
+     * so one misconfigured peer cannot push this clock into the far future.
+     *
+     * @param ts - Received timestamp
+     * @returns `true` if the clock absorbed `ts`
+     */
+    observe(ts: number): boolean;
+    /**
+     * Raise `last` to at least `ts` without consulting the skew bound.
+     * Used when seeding from durable local history on startup.
+     *
+     * @param ts - Known-good timestamp from local storage
+     */
+    seed(ts: number): void;
+}

package/dist/hlc.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HybridLogicalClock = void 0;
+const peer_device_1 = require("./types/peer-device");
+const utils_1 = require("./utils");
+/**
+ * Compact hybrid logical clock stored as a single millisecond number.
+ *
+ * `tick()` is `max(now(), last + 1)` so local timestamps stay close to wall time
+ * while remaining strictly monotonic even when the system clock jumps backward.
+ * `observe(ts)` raises `last` to a received timestamp so a later local tick
+ * always orders after a change this device has already seen.
+ */
+class HybridLogicalClock {
+    last = 0;
+    getNow;
+    maxSkewMs;
+    /**
+     * @param opts - Optional physical-time source and observe-skew bound
+     */
+    constructor(opts) {
+        this.getNow = opts?.now ?? utils_1.getTimestamp;
+        this.maxSkewMs = opts?.maxSkewMs ?? peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS;
+    }
+    /**
+     * Current physical time from the injected `now` function. Does not advance the clock.
+     */
+    now() {
+        return this.getNow();
+    }
+    /**
+     * Last assigned or observed value, or `0` before the first tick/seed/observe.
+     */
+    get value() {
+        return this.last;
+    }
+    /**
+     * Assign the next timestamp: `last = max(now(), last + 1)`.
+     *
+     * @returns The newly assigned timestamp
+     */
+    tick() {
+        this.last = Math.max(this.getNow(), this.last + 1);
+        return this.last;
+    }
+    /**
+     * Incorporate a timestamp received from another device.
+     * Values that are not finite, or that exceed `now() + maxSkewMs`, are ignored
+     * so one misconfigured peer cannot push this clock into the far future.
+     *
+     * @param ts - Received timestamp
+     * @returns `true` if the clock absorbed `ts`
+     */
+    observe(ts) {
+        if (!Number.isFinite(ts)) {
+            return false;
+        }
+        if (ts > this.getNow() + this.maxSkewMs) {
+            return false;
+        }
+        this.last = Math.max(this.last, ts);
+        return true;
+    }
+    /**
+     * Raise `last` to at least `ts` without consulting the skew bound.
+     * Used when seeding from durable local history on startup.
+     *
+     * @param ts - Known-good timestamp from local storage
+     */
+    seed(ts) {
+        if (!Number.isFinite(ts)) {
+            return;
+        }
+        this.last = Math.max(this.last, ts);
+    }
+}
+exports.HybridLogicalClock = HybridLogicalClock;

package/dist/hlc.test.d.ts

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

package/dist/hlc.test.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const hlc_1 = require("./hlc");
+const peer_device_1 = require("./types/peer-device");
+describe("HybridLogicalClock", () => {
+    it("is monotonic when now goes backward", () => {
+        let t = 1000;
+        const clock = new hlc_1.HybridLogicalClock({ now: () => t });
+        const first = clock.tick();
+        t = 100;
+        const second = clock.tick();
+        expect(second).toBe(first + 1);
+    });
+    it("advances by 1 on the same millisecond", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 5000 });
+        expect(clock.tick()).toBe(5000);
+        expect(clock.tick()).toBe(5001);
+        expect(clock.tick()).toBe(5002);
+    });
+    it("observe advances last so the next tick is after the observed time", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 1000 });
+        expect(clock.observe(2500)).toBe(true);
+        expect(clock.tick()).toBe(2501);
+    });
+    it("observe ignores timestamps beyond the skew bound", () => {
+        const now = 10_000;
+        const clock = new hlc_1.HybridLogicalClock({ now: () => now });
+        const future = now + peer_device_1.PeerDeviceConsts.CHANGE_TIMESTAMP_TOLERANCE_MS + 1;
+        expect(clock.observe(future)).toBe(false);
+        expect(clock.tick()).toBe(now);
+    });
+    it("seed raises last without going backward", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 1000 });
+        clock.seed(2000);
+        clock.seed(1500);
+        expect(clock.tick()).toBe(2001);
+    });
+    it("now peeks physical time without advancing", () => {
+        const clock = new hlc_1.HybridLogicalClock({ now: () => 42 });
+        expect(clock.now()).toBe(42);
+        expect(clock.now()).toBe(42);
+        expect(clock.value).toBe(0);
+        expect(clock.tick()).toBe(42);
+    });
+});

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from "./device/tx-encoding";
 export * from "./device-pairing";
 export * from "./events";
 export * from "./group-invite";
+export * from "./hlc";
 export * from "./keys";
 export * from "./logging";
 export * from "./mentions";

package/dist/index.js

@@ -37,6 +37,7 @@ __exportStar(require("./device/tx-encoding"), exports);
 __exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
 __exportStar(require("./group-invite"), exports);
+__exportStar(require("./hlc"), exports);
 __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./mentions"), exports);

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

@@ -1,4 +1,4 @@
-import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractObservable, IContractTool } from "../contracts/types";
+import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractEvent, IContractObservable, IContractTool } from "../contracts/types";
 import { type PersistentVarScope } from "../data/persistent-var-identity";
 import type { IAppNav } from "../types/app-nav";
 import { type IField } from "../types/field-type";
@@ -20,16 +20,21 @@ export interface IIsolatedContractToolRef {
 /**
  * Tool advertised on an isolated provided contract.
  *
- * Shape matches {@link IContractTool}. `suggestedAccessLevel` is a package
- * hint only — the host keeps the effective level at Self until an
- * administrator approves it.
+ * Shape matches {@link IContractTool}. `suggestedAccessLevel` is the default
+ * effective level until install-time approval exists and calls `approveTool`.
+ * Omit it to keep the fail-closed Self default.
  */
 export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields" | "outputFields"> {
     /** Defaults to `[]` during validation when omitted. */
     inputFields?: IField[];
     /** Defaults to `[]` during validation when omitted. */
     outputFields?: IField[];
-    /** Package suggestion only. Effective level stays Self until approved. */
+    /**
+     * Default effective access level for this tool.
+     *
+     * Used until an administrator explicitly approves the tool at install time.
+     * Omit to keep the fail-closed Self default.
+     */
     suggestedAccessLevel?: number;
 }
 /**
@@ -60,6 +65,18 @@ export interface IIsolatedContractPersistentVarBinding {
 export interface IIsolatedContractObservable extends IContractObservable {
     persistentVar: IIsolatedContractPersistentVarBinding;
 }
+/**
+ * Event an isolated provider may emit from an active tool invocation.
+ *
+ * Shape matches {@link IContractEvent}. `payloadFields` defaults to `[]`
+ * during validation when omitted. Events are host-owned: the worker emits via
+ * `emitContractEvent`, and local consumers subscribe through the contract
+ * proxy. Events are fire-and-forget (no replay) and local-only in this slice.
+ */
+export interface IIsolatedContractEvent extends Omit<IContractEvent, "payloadFields"> {
+    /** Defaults to `[]` during validation when omitted. */
+    payloadFields?: IField[];
+}
 /** Contract this package implements and serves from its isolated worker. */
 export interface IIsolatedProvidedContract {
     contractId: string;
@@ -71,6 +88,8 @@ export interface IIsolatedProvidedContract {
     tables?: IIsolatedContractTableRef[];
     /** Pvar-backed observable values exposed to consumers. */
     observables?: IIsolatedContractObservable[];
+    /** Events the worker may emit during an active invocation. */
+    events?: IIsolatedContractEvent[];
     /** Older contract versions this provider shape also satisfies. */
     alsoImplements?: IAlsoImplementsDeclaration[];
 }
@@ -132,6 +151,8 @@ export declare const ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
 export declare const ISOLATED_TABLE_HOST_MEMBER = "package.table";
 /** Host-contract member guests use to read or write package-prefixed pvars. */
 export declare const ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
+/** Host-contract member guests use to emit a provided-contract event. */
+export declare const ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 /**
  * True when `bundle` starts with {@link ISOLATED_PACKAGE_MAGIC}.
  *
@@ -210,6 +231,24 @@ export declare function findProvidedContractTable(provides: IIsolatedProvidedCon
  * @param observableName Public observable name.
  */
 export declare function findProvidedContractObservable(provides: IIsolatedProvidedContract[], contractId: string, version: number, observableName: string): IIsolatedContractObservable | undefined;
+/**
+ * Return a declared event from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param eventName Event name on that contract.
+ */
+export declare function findProvidedContractEvent(provides: IIsolatedProvidedContract[], contractId: string, version: number, eventName: string): IIsolatedContractEvent | undefined;
+/**
+ * True when the package advertises this event on a provided contract.
+ *
+ * @param provides - Provided contracts from the manifest.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ * @param eventName - Event name on that contract.
+ */
+export declare function packageProvidesEvent(provides: IIsolatedProvidedContract[], contractId: string, version: number, eventName: string): boolean;
 /**
  * True when the package declares a private table.
  *

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_PACKAGE_MAGIC = void 0;
+exports.ISOLATED_EVENT_HOST_MEMBER = exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = exports.ISOLATED_TABLE_HOST_MEMBER = exports.ISOLATED_CONSUME_HOST_MEMBER = exports.ISOLATED_PACKAGE_MAGIC = void 0;
 exports.looksLikeIsolatedPackageArtifact = looksLikeIsolatedPackageArtifact;
 exports.validateIsolatedPackageArtifact = validateIsolatedPackageArtifact;
 exports.parseIsolatedPackageArtifact = parseIsolatedPackageArtifact;
@@ -10,6 +10,8 @@ exports.packageDeclaresConsume = packageDeclaresConsume;
 exports.packageProvidesTool = packageProvidesTool;
 exports.findProvidedContractTable = findProvidedContractTable;
 exports.findProvidedContractObservable = findProvidedContractObservable;
+exports.findProvidedContractEvent = findProvidedContractEvent;
+exports.packageProvidesEvent = packageProvidesEvent;
 exports.packageProvidesTable = packageProvidesTable;
 exports.findPackageTable = findPackageTable;
 exports.toConsumedContracts = toConsumedContracts;
@@ -29,6 +31,8 @@ exports.ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
 exports.ISOLATED_TABLE_HOST_MEMBER = "package.table";
 /** Host-contract member guests use to read or write package-prefixed pvars. */
 exports.ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
+/** Host-contract member guests use to emit a provided-contract event. */
+exports.ISOLATED_EVENT_HOST_MEMBER = "contract.emit";
 const FIELD_TYPES = new Set(Object.values(field_type_1.FieldType));
 const OBSERVABLE_FIELD_TYPES = new Set([
     field_type_1.FieldType.id,
@@ -209,6 +213,7 @@ function validateProvidedContract(contract, index, packageTables) {
         "tools",
         "tables",
         "observables",
+        "events",
         "alsoImplements",
     ], label);
     assertPeerId(contract.contractId, `${label}.contractId`);
@@ -339,7 +344,36 @@ function validateProvidedContract(contract, index, packageTables) {
         pvarBindings.add(bindingKey);
         validateObservableDefault(binding.defaultValue, observable.valueType, `${observableLabel}.persistentVar.defaultValue`);
     }
-    if (contract.tools.length + contract.tables.length + contract.observables.length === 0) {
+    if (contract.events === undefined) {
+        contract.events = [];
+    }
+    if (!Array.isArray(contract.events)) {
+        throw new Error(`${label}.events must be an array`);
+    }
+    const eventNames = new Set();
+    for (const [eventIndex, event] of contract.events.entries()) {
+        const eventLabel = `${label}.events[${eventIndex}]`;
+        if (!event || typeof event !== "object" || Array.isArray(event)) {
+            throw new Error(`${eventLabel} must be an object`);
+        }
+        assertOnlyKeys(event, ["name", "description", "payloadFields"], eventLabel);
+        if (typeof event.name !== "string" || event.name.trim() === "") {
+            throw new Error(`${eventLabel}.name is required`);
+        }
+        if (eventNames.has(event.name)) {
+            throw new Error(`${label} declares duplicate event "${event.name}"`);
+        }
+        eventNames.add(event.name);
+        if (typeof event.description !== "string") {
+            throw new Error(`${eventLabel}.description is required`);
+        }
+        event.payloadFields = validateFields(event.payloadFields, `${eventLabel}.payloadFields`);
+    }
+    if (contract.tools.length +
+        contract.tables.length +
+        contract.observables.length +
+        contract.events.length ===
+        0) {
         throw new Error(`${label} must declare at least one contract member`);
     }
     if (contract.alsoImplements === undefined) {
@@ -564,6 +598,11 @@ function isolatedContractToDefinition(contract, packageTables) {
         valueType: observable.valueType,
         writable: observable.writable,
     }));
+    const events = (contract.events ?? []).map((event) => ({
+        name: event.name,
+        description: event.description,
+        payloadFields: event.payloadFields ?? [],
+    }));
     return {
         contractId: contract.contractId,
         version: contract.version,
@@ -572,7 +611,7 @@ function isolatedContractToDefinition(contract, packageTables) {
         tables,
         tools,
         observables,
-        events: [],
+        events,
     };
 }
 /**
@@ -623,6 +662,30 @@ function findProvidedContractObservable(provides, contractId, version, observabl
         .find((contract) => contract.contractId === contractId && contract.version === version)
         ?.observables?.find((observable) => observable.name === observableName);
 }
+/**
+ * Return a declared event from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param eventName Event name on that contract.
+ */
+function findProvidedContractEvent(provides, contractId, version, eventName) {
+    return provides
+        .find((contract) => contract.contractId === contractId && contract.version === version)
+        ?.events?.find((event) => event.name === eventName);
+}
+/**
+ * True when the package advertises this event on a provided contract.
+ *
+ * @param provides - Provided contracts from the manifest.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ * @param eventName - Event name on that contract.
+ */
+function packageProvidesEvent(provides, contractId, version, eventName) {
+    return findProvidedContractEvent(provides, contractId, version, eventName) !== undefined;
+}
 /**
  * True when the package declares a private table.
  *

package/dist/package-loader/isolated-artifact.test.js

@@ -235,12 +235,60 @@ describe("isolated package artifact", () => {
             { contractId: targetContractId, version: { from: 2, to: 4 } },
         ]);
     });
-    test("rejects unsupported contract features instead of dropping them", () => {
+    test("maps declared events to the public contract definition", () => {
         const { artifact } = makeArtifact();
         artifact.manifest.provides[0].events = [
-            { name: "changed", payloadFields: [] },
+            {
+                name: "changed",
+                description: "State changed",
+                payloadFields: [{ name: "count", type: field_type_1.FieldType.number }],
+            },
+            { name: "pinged", description: "No payload" },
         ];
-        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/events is not supported/);
+        const manifest = (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact);
+        expect(manifest.provides[0].events?.[1].payloadFields).toEqual([]);
+        const definition = (0, isolated_artifact_1.isolatedContractToDefinition)(manifest.provides[0], manifest.tables ?? []);
+        expect(definition.events).toEqual([
+            {
+                name: "changed",
+                description: "State changed",
+                payloadFields: [{ name: "count", type: field_type_1.FieldType.number }],
+            },
+            { name: "pinged", description: "No payload", payloadFields: [] },
+        ]);
+        expect((0, isolated_artifact_1.findProvidedContractEvent)(manifest.provides, definition.contractId, 1, "changed")).toBe(manifest.provides[0].events?.[0]);
+        expect((0, isolated_artifact_1.packageProvidesEvent)(manifest.provides, definition.contractId, 1, "missing")).toBe(false);
+    });
+    test("allows an events-only contract", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].tools = [];
+        artifact.manifest.provides[0].events = [{ name: "changed", description: "State changed" }];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).not.toThrow();
+        artifact.manifest.provides[0].events = [];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/at least one contract member/);
+    });
+    test("rejects malformed or duplicate events", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].events = [
+            { name: "changed", description: "a" },
+            { name: "changed", description: "b" },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/duplicate event "changed"/);
+        artifact.manifest.provides[0].events = [{ name: "changed" }];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/description is required/);
+        artifact.manifest.provides[0].events = [
+            { name: "changed", description: "a", accessLevel: 50 },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/accessLevel is not supported/);
+        artifact.manifest.provides[0].events = [
+            { name: "changed", description: "a", payloadFields: [{ name: "x", type: "nope" }] },
+        ];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/type must be a FieldType/);
+    });
+    test("rejects unsupported contract features instead of dropping them", () => {
+        const { artifact } = makeArtifact();
+        artifact.manifest.provides[0].streams = [];
+        expect(() => (0, isolated_artifact_1.validateIsolatedPackageArtifact)(artifact)).toThrow(/streams is not supported/);
     });
     test("rejects missing public table references and malformed observable bindings", () => {
         const { artifact } = makeArtifact();

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

@@ -126,7 +126,19 @@ export interface IIsolatedPackageTableGateway {
      * The host validates declaration and provider identity before calling the gateway.
      */
     call(ref: IIsolatedPackageTableRef, operation: IsolatedContractTableOperation, args: unknown[]): Promise<unknown>;
+    /**
+     * Subscribe to a host-owned table event. Only `dataChanged` is supported;
+     * payloads are copied before delivery. The host validates declaration and
+     * contract exposure before calling the gateway.
+     *
+     * @returns A callback that detaches the host-side subscription.
+     */
+    subscribe(ref: IIsolatedPackageTableRef, eventName: IsolatedContractTableEvent, handler: (event: unknown) => void): Promise<() => void>;
 }
+/** Table events consumers may subscribe to on an isolated contract table. */
+export declare const ISOLATED_CONTRACT_TABLE_EVENTS: readonly ["dataChanged"];
+/** Consumer-subscribable event on an isolated contract table. */
+export type IsolatedContractTableEvent = (typeof ISOLATED_CONTRACT_TABLE_EVENTS)[number];
 /**
  * Trusted identity of one package-owned pvar.
  *

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_CONTRACT_TABLE_OPERATIONS = void 0;
+exports.ISOLATED_CONTRACT_TABLE_EVENTS = exports.ISOLATED_CONTRACT_TABLE_OPERATIONS = void 0;
 exports.setIsolatedPackageRuntimeFactory = setIsolatedPackageRuntimeFactory;
 exports.getIsolatedPackageRuntimeFactory = getIsolatedPackageRuntimeFactory;
 /** Standard table methods exposed through isolated contract-table references. */
@@ -14,6 +14,8 @@ exports.ISOLATED_CONTRACT_TABLE_OPERATIONS = [
     "update",
     "delete",
 ];
+/** Table events consumers may subscribe to on an isolated contract table. */
+exports.ISOLATED_CONTRACT_TABLE_EVENTS = ["dataChanged"];
 let isolatedRuntimeFactory;
 /**
  * Register the process-wide isolated package runtime factory.

package/dist/package-loader/isolated-table-gateway.d.ts

@@ -1,5 +1,5 @@
 import type { DataContext } from "../context/data-context";
-import type { IIsolatedPackageTableGateway } from "./isolated-runtime";
+import { type IIsolatedPackageTableGateway } from "./isolated-runtime";
 /**
  * In-memory isolated table gateway for tests. Bindings and rows survive
  * `register` of the same owner so unload/reinstall can resume persisted data.

package/dist/package-loader/isolated-table-gateway.js

@@ -6,7 +6,9 @@ const table_container_1 = require("../data/orm/table-container");
 const types_1 = require("../data/orm/types");
 const package_table_identity_1 = require("../data/package-table-identity");
 const table_definitions_table_1 = require("../data/table-definitions-table");
+const events_1 = require("../events");
 const utils_1 = require("../utils");
+const isolated_runtime_1 = require("./isolated-runtime");
 const isolated_value_1 = require("./isolated-value");
 function tableKey(ref) {
     return `${ref.packageId}:${ref.tableName}`;
@@ -159,6 +161,12 @@ function copyTableResult(value) {
 function matchesFilter(row, filter = {}) {
     return Object.entries(filter).every(([name, value]) => row[name] === value);
 }
+function assertTableEvent(eventName) {
+    if (!isolated_runtime_1.ISOLATED_CONTRACT_TABLE_EVENTS.includes(eventName)) {
+        throw new Error(`Unsupported isolated table event '${eventName}'`);
+    }
+    return eventName;
+}
 /**
  * In-memory isolated table gateway for tests. Bindings and rows survive
  * `register` of the same owner so unload/reinstall can resume persisted data.
@@ -169,6 +177,19 @@ function createMemoryIsolatedPackageTableGateway() {
     const declarations = new Map();
     const byTableId = new Map();
     const rows = new Map();
+    const emitters = new Map();
+    const emitterFor = (key) => {
+        let emitter = emitters.get(key);
+        if (!emitter) {
+            // Unique per gateway instance so parallel tests never share a global event name.
+            emitter = new events_1.Emitter(`isolated-memory-table:${(0, utils_1.newid)()}:${key}`);
+            emitters.set(key, emitter);
+        }
+        return emitter;
+    };
+    const emitChange = (key, op, dataObject) => {
+        void emitterFor(key).emit({ dataObject, op, source: "local" });
+    };
     const registerBatch = async (batch) => {
         const candidateDeclarations = new Map(declarations);
         const candidateByTableId = new Map(byTableId);
@@ -213,6 +234,7 @@ function createMemoryIsolatedPackageTableGateway() {
             const tableRows = rows.get(key) ?? new Map();
             tableRows.set(recordId, stored);
             rows.set(key, tableRows);
+            emitChange(key, "save", stored);
             return (0, isolated_value_1.copyIsolatedValue)(stored);
         },
         async call(ref, operation, args) {
@@ -259,6 +281,7 @@ function createMemoryIsolatedPackageTableGateway() {
                         throw new Error(`Record ${id} does not exist`);
                     }
                     tableRows.set(id, stored);
+                    emitChange(key, operation, stored);
                     return (0, isolated_value_1.copyIsolatedValue)(stored);
                 }
                 case "delete": {
@@ -268,11 +291,28 @@ function createMemoryIsolatedPackageTableGateway() {
                     if (typeof id !== "string") {
                         throw new Error(`Isolated table delete requires "${declaration.primaryKeyName}"`);
                     }
+                    const existing = tableRows.get(id);
                     tableRows.delete(id);
+                    if (existing) {
+                        emitChange(key, "delete", existing);
+                    }
                     return undefined;
                 }
             }
         },
+        async subscribe(ref, eventName, handler) {
+            assertTableEvent(eventName);
+            const key = tableKey(ref);
+            if (!declarations.has(key)) {
+                throw new Error(`Undeclared isolated table ${ref.tableName}`);
+            }
+            const subscription = emitterFor(key).event.subscribe((event) => {
+                handler((0, isolated_value_1.copyIsolatedValue)(event));
+            });
+            return () => {
+                subscription.unsubscribe();
+            };
+        },
     };
 }
 /**
@@ -371,5 +411,19 @@ function createIsolatedPackageTableGateway(dataContext) {
             const result = await method.apply(table, (0, isolated_value_1.copyIsolatedValue)(args));
             return copyTableResult(result);
         },
+        async subscribe(ref, eventName, handler) {
+            assertTableEvent(eventName);
+            await registrationQueue;
+            const table = await ensureTable(resolve(ref));
+            const subscription = table.dataChanged.subscribe((event) => {
+                handler({
+                    ...event,
+                    dataObject: copyTableResult(event.dataObject),
+                });
+            });
+            return () => {
+                subscription.unsubscribe();
+            };
+        },
     };
 }

package/dist/package-loader/isolated-table-gateway.test.js

@@ -203,4 +203,65 @@ describe("isolated package table gateway", () => {
             count: 4,
         });
     });
+    test("memory gateway delivers copied dataChanged events for save/call and detaches", async () => {
+        const gateway = (0, isolated_table_gateway_1.createMemoryIsolatedPackageTableGateway)();
+        const declaration = makeDeclaration();
+        const other = makeDeclaration();
+        const recordId = (0, utils_1.newid)();
+        await gateway.registerBatch([declaration, other]);
+        const received = [];
+        const unsubscribe = await gateway.subscribe(declaration, "dataChanged", (event) => {
+            received.push(event);
+        });
+        await gateway.save(declaration, { stateId: recordId, count: 1 });
+        await gateway.call(declaration, "update", [{ stateId: recordId, count: 2 }]);
+        await gateway.save(other, { stateId: (0, utils_1.newid)(), count: 9 });
+        await gateway.call(declaration, "delete", [recordId]);
+        await new Promise((resolve) => setImmediate(resolve));
+        expect(received).toEqual([
+            { dataObject: { stateId: recordId, count: 1 }, op: "save", source: "local" },
+            { dataObject: { stateId: recordId, count: 2 }, op: "update", source: "local" },
+            { dataObject: { stateId: recordId, count: 2 }, op: "delete", source: "local" },
+        ]);
+        const first = received[0];
+        first.dataObject.count = 99;
+        await expect(gateway.get(declaration, recordId)).resolves.toBeUndefined();
+        unsubscribe();
+        await gateway.save(declaration, { stateId: recordId, count: 3 });
+        await new Promise((resolve) => setImmediate(resolve));
+        expect(received).toHaveLength(3);
+        await expect(gateway.subscribe(declaration, "somethingElse", () => undefined)).rejects.toThrow(/Unsupported isolated table event/);
+        await expect(gateway.subscribe(makeDeclaration(), "dataChanged", () => undefined)).rejects.toThrow(/Undeclared isolated table/);
+    });
+    test("data-context gateway subscribes to the host table dataChanged event", async () => {
+        const declaration = makeDeclaration();
+        const handlers = new Set();
+        const table = {
+            get: jest.fn(),
+            save: jest.fn(),
+            dataChanged: {
+                subscribe: jest.fn((handler) => {
+                    handlers.add(handler);
+                    return { unsubscribe: () => handlers.delete(handler) };
+                }),
+            },
+        };
+        const gateway = (0, isolated_table_gateway_1.createIsolatedPackageTableGateway)({
+            tableContainer: { registerTableDefinition: jest.fn(), getTable: jest.fn(() => table) },
+        });
+        await gateway.register(declaration);
+        const received = [];
+        const unsubscribe = await gateway.subscribe(declaration, "dataChanged", (event) => {
+            received.push(event);
+        });
+        expect(table.dataChanged.subscribe).toHaveBeenCalledTimes(1);
+        const row = { stateId: (0, utils_1.newid)(), count: 1 };
+        for (const handler of handlers) {
+            handler({ dataObject: row, op: "save", source: "local" });
+        }
+        expect(received).toEqual([{ dataObject: row, op: "save", source: "local" }]);
+        expect(received[0].dataObject).not.toBe(row);
+        unsubscribe();
+        expect(handlers.size).toBe(0);
+    });
 });

package/dist/types/peer-device.d.ts

@@ -81,6 +81,14 @@ export declare const PeerDeviceConsts: Readonly<{
     readonly TIMEOUT_MIN: 3000;
     readonly TIMEOUT_MAX: 30000;
     readonly NETWORK_INFO_CACHE_TIME: 1000;
+    /** Handshake rejects peers whose wall clock differs by more than this. */
+    readonly CLOCK_SKEW_TOLERANCE_MS: 300000;
+    /**
+     * Incoming change `createdAt` values more than this far ahead of local now
+     * are skipped. 2× the handshake bound so multi-hop HLC lead plus allowed
+     * skew does not reject legitimate changes.
+     */
+    readonly CHANGE_TIMESTAMP_TOLERANCE_MS: 600000;
 }>;
 /** Availability and queue information for a requested file chunk. */
 export type IFileChunkInfo = {

package/dist/types/peer-device.js

@@ -13,4 +13,12 @@ exports.PeerDeviceConsts = Object.freeze({
     TIMEOUT_MIN: 3_000,
     TIMEOUT_MAX: 30_000,
     NETWORK_INFO_CACHE_TIME: 1000,
+    /** Handshake rejects peers whose wall clock differs by more than this. */
+    CLOCK_SKEW_TOLERANCE_MS: 300_000,
+    /**
+     * Incoming change `createdAt` values more than this far ahead of local now
+     * are skipped. 2× the handshake bound so multi-hop HLC lead plus allowed
+     * skew does not reject legitimate changes.
+     */
+    CHANGE_TIMESTAMP_TOLERANCE_MS: 600_000,
 });

package/package.json

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