@peers-app/peers-sdk 0.23.4 → 0.23.6

package/dist/contracts/registry.js

@@ -31,26 +31,139 @@ class ContractRegistry {
      * @returns Validation result.  If invalid the provider is not registered.
      */
     register(providerPackageId, definition, alsoImplementsDecls = []) {
+        return this.registerBatch(providerPackageId, [
+            { definition, alsoImplements: alsoImplementsDecls },
+        ]);
+    }
+    /**
+     * Atomically register every contract supplied by one provider package.
+     *
+     * Frozen-shape and `alsoImplements` checks run against a candidate registry
+     * containing the whole batch, so declarations may reference another
+     * contract in the same install. If any entry fails, no definition, provider,
+     * active-provider pointer, or reverse index is changed.
+     *
+     * @param providerPackageId - Trusted identity of the provider package.
+     * @param registrations - Contract definitions and compatibility declarations.
+     * @returns The combined validation result.
+     */
+    registerBatch(providerPackageId, registrations) {
+        const validation = this.validateBatch(providerPackageId, registrations);
+        if (!validation.valid) {
+            return validation;
+        }
+        this.commitRegistrations(providerPackageId, registrations);
+        return validation;
+    }
+    /**
+     * Atomically replace the complete contract set for one provider package.
+     *
+     * Validation runs before the existing provider entries are touched. Active
+     * selections remain on this package for contract versions it still provides;
+     * removed versions fall back according to ordinary unregister semantics.
+     *
+     * @param providerPackageId - Trusted provider package identity.
+     * @param registrations - Complete replacement set.
+     * @returns Validation result; invalid replacements leave the registry unchanged.
+     */
+    replaceBatch(providerPackageId, registrations) {
+        const validation = this.validateBatch(providerPackageId, registrations);
+        if (!validation.valid) {
+            return validation;
+        }
+        const previouslyActive = new Set((this.packageContracts.get(providerPackageId) ?? []).filter((key) => this.activeProviders.get(key)?.providerPackageId === providerPackageId));
+        this.unregister(providerPackageId);
+        this.commitRegistrations(providerPackageId, registrations);
+        for (const key of previouslyActive) {
+            const provider = this.allProviders
+                .get(key)
+                ?.find((item) => item.providerPackageId === providerPackageId);
+            if (provider) {
+                this.activeProviders.set(key, provider);
+            }
+        }
+        return validation;
+    }
+    /**
+     * Validate a complete provider registration batch without changing registry state.
+     *
+     * @param providerPackageId - Trusted provider package identity.
+     * @param registrations - Definitions and compatibility declarations to validate.
+     * @returns Combined validation result.
+     */
+    validateBatch(providerPackageId, registrations) {
+        const candidateDefinitions = new Map(this.definitions);
+        const batchKeys = new Set();
+        for (const { definition } of registrations) {
+            const key = (0, types_1.contractKey)(definition.contractId, definition.version);
+            if (batchKeys.has(key)) {
+                return {
+                    valid: false,
+                    errors: [
+                        {
+                            kind: "contract",
+                            name: key,
+                            message: `Provider ${providerPackageId} registered contract ${key} more than once`,
+                        },
+                    ],
+                };
+            }
+            batchKeys.add(key);
+            const existingDef = this.definitions.get(key);
+            if (existingDef) {
+                const immutability = (0, validate_1.validateImmutability)(existingDef, definition);
+                if (!immutability.valid) {
+                    return immutability;
+                }
+            }
+            candidateDefinitions.set(key, definition);
+        }
+        for (const { definition, alsoImplements = [] } of registrations) {
+            if (alsoImplements.length === 0) {
+                continue;
+            }
+            const compatibility = (0, validate_1.validateAlsoImplements)(definition, alsoImplements, (contractId, version) => candidateDefinitions.get((0, types_1.contractKey)(contractId, version)));
+            if (!compatibility.valid) {
+                return compatibility;
+            }
+        }
+        return { valid: true, errors: [] };
+    }
+    commitRegistrations(providerPackageId, registrations) {
+        const explicitKeys = new Set(registrations.map(({ definition }) => (0, types_1.contractKey)(definition.contractId, definition.version)));
+        for (const { definition } of registrations) {
+            this.commitProvider(providerPackageId, definition, definition);
+        }
+        for (const { definition, alsoImplements = [] } of registrations) {
+            for (const declaration of alsoImplements) {
+                const declaredVersion = declaration.version;
+                const versions = typeof declaredVersion === "number"
+                    ? [declaredVersion]
+                    : Array.from({ length: declaredVersion.to - declaredVersion.from + 1 }, (_, index) => declaredVersion.from + index);
+                for (const version of versions) {
+                    const key = (0, types_1.contractKey)(declaration.contractId, version);
+                    if (explicitKeys.has(key)) {
+                        continue;
+                    }
+                    const target = this.definitions.get(key);
+                    if (target) {
+                        this.commitProvider(providerPackageId, target, definition);
+                    }
+                }
+            }
+        }
+    }
+    commitProvider(providerPackageId, definition, implementation) {
         const key = (0, types_1.contractKey)(definition.contractId, definition.version);
-        // Immutability check against any previously stored definition
-        const existingDef = this.definitions.get(key);
-        if (existingDef) {
-            const immResult = (0, validate_1.validateImmutability)(existingDef, definition);
-            if (!immResult.valid)
-                return immResult;
-        }
-        // alsoImplements check
-        if (alsoImplementsDecls.length > 0) {
-            const aiResult = (0, validate_1.validateAlsoImplements)(definition, alsoImplementsDecls, (cid, ver) => this.definitions.get((0, types_1.contractKey)(cid, ver)));
-            if (!aiResult.valid)
-                return aiResult;
-        }
-        // Store the definition (first-come for frozen, latest for dev)
         this.definitions.set(key, definition);
-        const provider = { providerPackageId, definition };
-        // Add to the all-providers list
+        const provider = {
+            providerPackageId,
+            definition,
+            implementationContractId: implementation.contractId,
+            implementationVersion: implementation.version,
+        };
         const providers = this.allProviders.get(key) ?? [];
-        const existingIdx = providers.findIndex((p) => p.providerPackageId === providerPackageId);
+        const existingIdx = providers.findIndex((item) => item.providerPackageId === providerPackageId);
         if (existingIdx >= 0) {
             providers[existingIdx] = provider;
         }
@@ -58,17 +171,15 @@ class ContractRegistry {
             providers.push(provider);
         }
         this.allProviders.set(key, providers);
-        // If no active provider, auto-activate
-        if (!this.activeProviders.has(key)) {
+        const active = this.activeProviders.get(key);
+        if (!active || active.providerPackageId === providerPackageId) {
             this.activeProviders.set(key, provider);
         }
-        // Update reverse index
-        const pkgKeys = this.packageContracts.get(providerPackageId) ?? [];
-        if (!pkgKeys.includes(key)) {
-            pkgKeys.push(key);
+        const packageKeys = this.packageContracts.get(providerPackageId) ?? [];
+        if (!packageKeys.includes(key)) {
+            packageKeys.push(key);
         }
-        this.packageContracts.set(providerPackageId, pkgKeys);
-        return { valid: true, errors: [] };
+        this.packageContracts.set(providerPackageId, packageKeys);
     }
     /**
      * Switch the active provider for a contract to a different registered package.
@@ -106,6 +217,25 @@ class ContractRegistry {
         const key = (0, types_1.contractKey)(contractId, version);
         return (this.allProviders.get(key) ?? []).map((p) => p.providerPackageId);
     }
+    /**
+     * Resolve the concrete contract implementation selected for one provider.
+     *
+     * For a direct registration this matches the requested contract. For an
+     * `alsoImplements` alias it identifies the newer compatible implementation.
+     *
+     * @param contractId - Consumer-requested contract identity.
+     * @param version - Consumer-requested contract version.
+     * @param providerPackageId - Registry-selected provider package.
+     */
+    getProviderImplementation(contractId, version, providerPackageId) {
+        const provider = (this.allProviders.get((0, types_1.contractKey)(contractId, version)) ?? []).find((candidate) => candidate.providerPackageId === providerPackageId);
+        return provider
+            ? {
+                contractId: provider.implementationContractId,
+                version: provider.implementationVersion,
+            }
+            : undefined;
+    }
     /**
      * Pick a provider for a consumed-contract declaration.
      *

package/dist/contracts/system-contracts.js

@@ -25,7 +25,9 @@ function registerSystemContract(registration) {
         const { contractId, version, resolve } = registration;
         queueMicrotask(() => {
             const { registerContractResolver } = require("./contract-resolvers");
-            registerContractResolver(contractId, version, resolve);
+            registerContractResolver(contractId, version, resolve, {
+                providerPackageId: registration.providerPackageId,
+            });
         });
     }
     const key = registration.contractId && registration.version != null

package/dist/data/index.d.ts

@@ -13,6 +13,7 @@ export * from "./group-secret";
 export * from "./group-share";
 export * from "./groups";
 export * from "./messages";
+export * from "./package-table-identity";
 export * from "./package-version-resolver";
 export * from "./package-versions";
 export * from "./packages";

package/dist/data/index.js

@@ -29,6 +29,7 @@ __exportStar(require("./group-secret"), exports);
 __exportStar(require("./group-share"), exports);
 __exportStar(require("./groups"), exports);
 __exportStar(require("./messages"), exports);
+__exportStar(require("./package-table-identity"), exports);
 __exportStar(require("./package-version-resolver"), exports);
 __exportStar(require("./package-versions"), exports);
 __exportStar(require("./packages"), exports);

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

@@ -1,7 +1,15 @@
 import { z } from "zod";
 import { type IField } from "../../types/field-type";
+/** Pure-data schema and storage metadata for a Peers table. */
 export interface ITableMetaData {
     tableId?: string;
+    /**
+     * Trusted owning package for package-scoped physical naming.
+     *
+     * When present, physical naming uses `name_packageId` while `tableId`
+     * remains the independent schema-definition identity.
+     */
+    packageId?: string;
     name: string;
     description: string;
     primaryKeyName: string;
@@ -17,5 +25,16 @@ export interface ITableMetaData {
     localOnly?: boolean;
     versionNumber?: number;
 }
+/**
+ * Convert field metadata to the runtime Zod schema used by table validation.
+ *
+ * @param fields Serializable field definitions.
+ * @param codeSchema Optional author schema whose refinements are intersected.
+ */
 export declare function fieldsToSchema(fields: IField[], codeSchema?: z.AnyZodObject): z.AnyZodObject;
+/**
+ * Convert a Zod object schema to serializable field metadata.
+ *
+ * @param schema Runtime record schema.
+ */
 export declare function schemaToFields(schema: z.AnyZodObject): IField[];

package/dist/data/orm/types.js

@@ -5,6 +5,12 @@ exports.schemaToFields = schemaToFields;
 const zod_1 = require("zod");
 const field_type_1 = require("../../types/field-type");
 const utils_1 = require("../../utils");
+/**
+ * Convert field metadata to the runtime Zod schema used by table validation.
+ *
+ * @param fields Serializable field definitions.
+ * @param codeSchema Optional author schema whose refinements are intersected.
+ */
 function fieldsToSchema(fields, codeSchema) {
     let argsSchema = zod_1.z.object({});
     for (const argSchema of fields) {
@@ -52,6 +58,11 @@ function fieldsToSchema(fields, codeSchema) {
     }
     return argsSchema;
 }
+/**
+ * Convert a Zod object schema to serializable field metadata.
+ *
+ * @param schema Runtime record schema.
+ */
 function schemaToFields(schema) {
     const fields = [];
     for (const name of Object.keys(schema.shape)) {

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

@@ -0,0 +1,46 @@
+/**
+ * Validate a guest-supplied isolated-table or field identifier before it can
+ * reach ORM-generated SQL.
+ *
+ * This intentionally accepts only simple SQLite identifiers. The package
+ * manifest validator and host gateway can share this helper so malformed
+ * names are rejected even when a declaration bypasses artifact loading.
+ *
+ * @param identifier Guest-supplied logical table or field name.
+ * @param label Description used in validation errors.
+ * @returns The unchanged identifier.
+ * @throws When the identifier is empty or contains SQL syntax.
+ */
+export declare function validateIsolatedSqlIdentifier(identifier: string, label?: string): string;
+/**
+ * Validate a package-local table name.
+ *
+ * @param logicalName Guest-visible table name.
+ * @returns The unchanged logical name.
+ * @throws When the name is not a SQL-safe isolated identifier.
+ */
+export declare function validatePackageTableName(logicalName: string): string;
+/**
+ * Derive the physical SQLite name for a package-owned table.
+ *
+ * Package ID is appended so authors only need unique logical names inside
+ * their own package.
+ *
+ * @param packageId Trusted owning package ID.
+ * @param logicalName Package-local table name.
+ * @returns The package-scoped physical table name.
+ * @throws When package or table identity is invalid.
+ */
+export declare function packageScopedTableName(packageId: string, logicalName: string): string;
+/**
+ * Derive the stable host-only ID used to key `TableDefinitions`.
+ *
+ * The ID is intentionally separate from the physical SQLite name so schema
+ * tracking keeps a valid peer ID without producing a triple-suffixed table.
+ *
+ * @param packageId Trusted owning package ID.
+ * @param logicalName Package-local table name.
+ * @returns A deterministic peer ID for the package-owned table definition.
+ * @throws When package or table identity is invalid.
+ */
+export declare function packageScopedTableId(packageId: string, logicalName: string): string;

package/dist/data/package-table-identity.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateIsolatedSqlIdentifier = validateIsolatedSqlIdentifier;
+exports.validatePackageTableName = validatePackageTableName;
+exports.packageScopedTableName = packageScopedTableName;
+exports.packageScopedTableId = packageScopedTableId;
+const utils_1 = require("../utils");
+const ISOLATED_SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Validate a guest-supplied isolated-table or field identifier before it can
+ * reach ORM-generated SQL.
+ *
+ * This intentionally accepts only simple SQLite identifiers. The package
+ * manifest validator and host gateway can share this helper so malformed
+ * names are rejected even when a declaration bypasses artifact loading.
+ *
+ * @param identifier Guest-supplied logical table or field name.
+ * @param label Description used in validation errors.
+ * @returns The unchanged identifier.
+ * @throws When the identifier is empty or contains SQL syntax.
+ */
+function validateIsolatedSqlIdentifier(identifier, label = "Isolated SQL identifier") {
+    if (typeof identifier !== "string" || identifier.trim() === "") {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    if (!ISOLATED_SQL_IDENTIFIER.test(identifier)) {
+        throw new Error(`${label} must start with a letter or underscore and contain only letters, numbers, and underscores`);
+    }
+    return identifier;
+}
+/**
+ * Validate a package-local table name.
+ *
+ * @param logicalName Guest-visible table name.
+ * @returns The unchanged logical name.
+ * @throws When the name is not a SQL-safe isolated identifier.
+ */
+function validatePackageTableName(logicalName) {
+    return validateIsolatedSqlIdentifier(logicalName, "Package table name");
+}
+/**
+ * Derive the physical SQLite name for a package-owned table.
+ *
+ * Package ID is appended so authors only need unique logical names inside
+ * their own package.
+ *
+ * @param packageId Trusted owning package ID.
+ * @param logicalName Package-local table name.
+ * @returns The package-scoped physical table name.
+ * @throws When package or table identity is invalid.
+ */
+function packageScopedTableName(packageId, logicalName) {
+    if (!(0, utils_1.isid)(packageId)) {
+        throw new Error(`Invalid package ID for table: ${packageId}`);
+    }
+    return `${validatePackageTableName(logicalName)}_${packageId}`;
+}
+/**
+ * Derive the stable host-only ID used to key `TableDefinitions`.
+ *
+ * The ID is intentionally separate from the physical SQLite name so schema
+ * tracking keeps a valid peer ID without producing a triple-suffixed table.
+ *
+ * @param packageId Trusted owning package ID.
+ * @param logicalName Package-local table name.
+ * @returns A deterministic peer ID for the package-owned table definition.
+ * @throws When package or table identity is invalid.
+ */
+function packageScopedTableId(packageId, logicalName) {
+    return (0, utils_1.deterministicTableId)(packageScopedTableName(packageId, logicalName));
+}

package/dist/data/package-table-identity.test.d.ts

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

package/dist/data/package-table-identity.test.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("../utils");
+const package_table_identity_1 = require("./package-table-identity");
+describe("package-scoped table identity", () => {
+    test("appends trusted package identity to the logical table name", () => {
+        const packageId = (0, utils_1.newid)();
+        const tableId = (0, package_table_identity_1.packageScopedTableId)(packageId, "Settings");
+        const metaData = {
+            packageId,
+            tableId,
+            name: "Settings",
+            description: "Package settings",
+            primaryKeyName: "settingId",
+            fields: [],
+        };
+        expect((0, package_table_identity_1.packageScopedTableName)(packageId, "Settings")).toBe(`Settings_${packageId}`);
+        expect((0, utils_1.getFullTableName)(metaData)).toBe(`Settings_${packageId}`);
+        expect((0, utils_1.getFullTableName)(metaData)).not.toContain(tableId);
+        expect((0, utils_1.isid)(tableId)).toBe(true);
+        expect((0, utils_1.isDeterministicTableId)(tableId)).toBe(true);
+    });
+    test("keeps existing table naming unchanged", () => {
+        const tableId = (0, utils_1.newid)();
+        expect((0, utils_1.getFullTableName)({
+            tableId,
+            name: "Settings",
+            description: "Existing table",
+            primaryKeyName: "settingId",
+            fields: [],
+        })).toBe(`Settings_${tableId}`);
+    });
+    test("uses package and logical name for stable internal IDs", () => {
+        const packageId = (0, utils_1.newid)();
+        expect((0, package_table_identity_1.packageScopedTableId)(packageId, "One")).toBe((0, package_table_identity_1.packageScopedTableId)(packageId, "One"));
+        expect((0, package_table_identity_1.packageScopedTableId)(packageId, "One")).not.toBe((0, package_table_identity_1.packageScopedTableId)(packageId, "Two"));
+        expect((0, package_table_identity_1.packageScopedTableId)(packageId, "One")).not.toBe((0, package_table_identity_1.packageScopedTableId)((0, utils_1.newid)(), "One"));
+    });
+    test("rejects invalid package IDs and empty logical names", () => {
+        expect(() => (0, package_table_identity_1.packageScopedTableName)("not-an-id", "Settings")).toThrow(/package ID/);
+        expect(() => (0, package_table_identity_1.packageScopedTableName)((0, utils_1.newid)(), " ")).toThrow(/non-empty/);
+        expect(() => (0, package_table_identity_1.packageScopedTableName)((0, utils_1.newid)(), 'State"; DROP TABLE Users; --')).toThrow(/only letters, numbers, and underscores/);
+        expect((0, package_table_identity_1.validateIsolatedSqlIdentifier)("state_value", "field")).toBe("state_value");
+        expect(() => (0, package_table_identity_1.validateIsolatedSqlIdentifier)("state.value", "field")).toThrow(/field/);
+    });
+});

package/dist/data/package-version-resolver.d.ts

@@ -18,6 +18,8 @@ import { type PersistentVar } from "./persistent-vars";
 export interface IDevicePackagePrefs {
     /** Which PV this device currently runs */
     activePackageVersionId?: string;
+    /** Newer selected PV temporarily bypassed because this host could not run it. */
+    compatibilityFallbackForPackageVersionId?: string;
     /** If true, never auto-update this package */
     pinned?: boolean;
     /** Auto-update range: patch | minor | latest */
@@ -98,3 +100,14 @@ export declare function resolveDevicePackageVersion(pkg: IPackage, dataContext:
  * to advance the group-level active version on upgrade.
  */
 export declare function hasDeviceFollowOverride(prefs: IDevicePackagePrefs | undefined): boolean;
+/**
+ * Read the stored local checkout path for a package, if one is set.
+ *
+ * Used so isolated local-dev packages can load `dist/package.bundle.js` from
+ * disk even when startup resolution does not receive an explicit `localPath`.
+ *
+ * @param packageId - Package whose `packageLocalPath_*` device var to read.
+ * @param dataContext - Data context that owns the device var.
+ * @returns Trimmed path, or `undefined` when unset or empty.
+ */
+export declare function readStoredPackageLocalPath(packageId: string, dataContext: DataContext): Promise<string | undefined>;