@peers-app/peers-sdk 0.23.2 → 0.23.5

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/group-share.d.ts

@@ -1,3 +1,4 @@
+import type { UserContext } from "../context/user-context";
 import { type IGroupMember } from "./group-members";
 import { type IGroup } from "./groups";
 /**
@@ -16,6 +17,18 @@ export interface IGroupShare {
  * @throws Error if group not found or user lacks permission
  */
 export declare function generateGroupShare(groupId: string): Promise<IGroupShare>;
+/**
+ * Write a group record and missing membership rows into the group's data context.
+ *
+ * Uses the lowest data source so bootstrap can seed already-signed rows without
+ * re-running table permission checks. Existing memberships for the same user
+ * are left in place so retries can repair a partial import.
+ *
+ * @param userContext - Joiner or importer whose group context should be seeded
+ * @param groupShare - Canonical group plus Admin+ memberships
+ * @param extraMembers - Additional signed rows such as a newly approved Reader
+ */
+export declare function seedGroupContextFromShare(userContext: UserContext, groupShare: Pick<IGroupShare, "group" | "groupMembers">, extraMembers?: IGroupMember[]): Promise<void>;
 /**
  * Validates that an object has the correct GroupShare structure
  * @param obj Object to validate

package/dist/data/group-share.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateGroupShare = generateGroupShare;
+exports.seedGroupContextFromShare = seedGroupContextFromShare;
 exports.validateGroupShare = validateGroupShare;
 exports.estimateGroupShareSize = estimateGroupShareSize;
 exports.checkQRCodeCompatibility = checkQRCodeCompatibility;
@@ -57,7 +58,7 @@ async function importGroupShare(groupShareJson) {
         throw new Error("Invalid GroupShare structure");
     }
     const userContext = await (0, user_context_singleton_1.getUserContext)();
-    const { group, groupMembers } = groupShare;
+    const { group } = groupShare;
     // Check if group already exists
     const existingGroup = await (0, groups_1.Groups)(userContext.userDataContext).get(group.groupId);
     if (existingGroup) {
@@ -65,19 +66,42 @@ async function importGroupShare(groupShareJson) {
     }
     // Save group to user's groups table
     await (0, groups_1.Groups)(userContext.userDataContext).save(group, { restoreIfDeleted: true });
-    // Get group data context for the new group
+    await seedGroupContextFromShare(userContext, groupShare);
+    return group.groupId;
+}
+/**
+ * Write a group record and missing membership rows into the group's data context.
+ *
+ * Uses the lowest data source so bootstrap can seed already-signed rows without
+ * re-running table permission checks. Existing memberships for the same user
+ * are left in place so retries can repair a partial import.
+ *
+ * @param userContext - Joiner or importer whose group context should be seeded
+ * @param groupShare - Canonical group plus Admin+ memberships
+ * @param extraMembers - Additional signed rows such as a newly approved Reader
+ */
+async function seedGroupContextFromShare(userContext, groupShare, extraMembers = []) {
+    const { group, groupMembers } = groupShare;
     const groupDataContext = userContext.getDataContext(group.groupId);
-    // Save the group data to the group's own context
     const groupsTable = (0, groups_1.Groups)(groupDataContext);
-    const groupsTableDataSource = getLowestDataSource(groupsTable);
-    await groupsTableDataSource.save(group);
-    // Save all admin members as seed data for device recognition
+    await getLowestDataSource(groupsTable).save(group);
     const groupMembersTable = (0, group_members_1.GroupMembers)(groupDataContext);
     const groupMembersDataSource = getLowestDataSource(groupMembersTable);
-    for (const member of groupMembers) {
+    const seenUserIds = new Set();
+    for (const member of [...groupMembers, ...extraMembers]) {
+        if (!member?.userId || member.groupId !== group.groupId || seenUserIds.has(member.userId)) {
+            continue;
+        }
+        seenUserIds.add(member.userId);
+        const existing = await groupMembersTable.findOne({
+            groupId: group.groupId,
+            userId: member.userId,
+        });
+        if (existing) {
+            continue;
+        }
         await groupMembersDataSource.save(member);
     }
-    return group.groupId;
 }
 /**
  * Validates that an object has the correct GroupShare structure

package/dist/data/group-share.test.d.ts

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

package/dist/data/group-share.test.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SQLiteDB = require("better-sqlite3");
+const user_context_1 = require("../context/user-context");
+const utils_1 = require("../utils");
+const group_member_roles_1 = require("./group-member-roles");
+const group_members_1 = require("./group-members");
+const group_share_1 = require("./group-share");
+const groups_1 = require("./groups");
+const sql_data_source_1 = require("./orm/sql.data-source");
+class DBHarness {
+    _db = null;
+    get db() {
+        if (!this._db) {
+            this._db = new SQLiteDB(":memory:");
+            this._db.pragma("journal_mode = WAL");
+        }
+        return this._db;
+    }
+    async get(sql, params = []) {
+        return this.db.prepare(sql).get(params);
+    }
+    async all(sql, params = []) {
+        return this.db.prepare(sql).all(params);
+    }
+    async exec(sql, params = []) {
+        const result = this.db.prepare(sql).run(params);
+        return { changes: result.changes };
+    }
+    async close() {
+        this._db?.close();
+        this._db = null;
+    }
+}
+describe("seedGroupContextFromShare", () => {
+    const dbs = new Map();
+    let userContext;
+    const userId = (0, utils_1.newid)();
+    beforeAll(async () => {
+        groups_1.GroupsTable.isPassthrough = true;
+        group_members_1.GroupMembersTable.isPassthrough = true;
+        const dataSourceFactory = (metaData, schema, groupId) => {
+            const key = groupId || userId;
+            let db = dbs.get(key);
+            if (!db) {
+                db = new DBHarness();
+                dbs.set(key, db);
+            }
+            return new sql_data_source_1.SQLDataSource(db, metaData, schema);
+        };
+        userContext = new user_context_1.UserContext(userId, dataSourceFactory, true);
+        await userContext.loadingPromise;
+        userContext.deviceId((0, utils_1.newid)());
+    });
+    afterAll(async () => {
+        groups_1.GroupsTable.isPassthrough = false;
+        group_members_1.GroupMembersTable.isPassthrough = false;
+        userContext.dispose();
+        await Promise.all([...dbs.values()].map((db) => db.close()));
+    });
+    function makeGroup() {
+        return {
+            groupId: (0, utils_1.newid)(),
+            name: "Home",
+            description: "",
+            founderUserId: (0, utils_1.newid)(),
+            signature: "group-sig",
+            publicKey: "pk",
+            publicBoxKey: "pbk",
+        };
+    }
+    function makeMember(groupId, memberUserId, role) {
+        return {
+            groupMemberId: (0, utils_1.newid)(),
+            groupId,
+            userId: memberUserId,
+            role,
+            signature: "member-sig",
+        };
+    }
+    it("seeds the group record and missing memberships, including extra Reader rows", async () => {
+        const group = makeGroup();
+        const admin = makeMember(group.groupId, (0, utils_1.newid)(), group_member_roles_1.GroupMemberRole.Admin);
+        const joiner = makeMember(group.groupId, userId, group_member_roles_1.GroupMemberRole.Reader);
+        await (0, group_share_1.seedGroupContextFromShare)(userContext, { group, groupMembers: [admin] }, [joiner]);
+        const groupContext = userContext.getDataContext(group.groupId);
+        await expect((0, groups_1.Groups)(groupContext).get(group.groupId)).resolves.toMatchObject({
+            name: "Home",
+        });
+        await expect((0, group_members_1.GroupMembers)(groupContext).findOne({ userId: admin.userId, groupId: group.groupId })).resolves.toMatchObject({ role: group_member_roles_1.GroupMemberRole.Admin });
+        await expect((0, group_members_1.GroupMembers)(groupContext).findOne({ userId: userId, groupId: group.groupId })).resolves.toMatchObject({ role: group_member_roles_1.GroupMemberRole.Reader });
+    });
+    it("leaves existing memberships in place on a retry", async () => {
+        const group = makeGroup();
+        const admin = makeMember(group.groupId, (0, utils_1.newid)(), group_member_roles_1.GroupMemberRole.Admin);
+        await (0, group_share_1.seedGroupContextFromShare)(userContext, { group, groupMembers: [admin] });
+        const replacement = {
+            ...admin,
+            groupMemberId: (0, utils_1.newid)(),
+            signature: "other-sig",
+        };
+        await (0, group_share_1.seedGroupContextFromShare)(userContext, { group, groupMembers: [replacement] });
+        const saved = await (0, group_members_1.GroupMembers)(userContext.getDataContext(group.groupId)).findOne({
+            userId: admin.userId,
+            groupId: group.groupId,
+        });
+        expect(saved?.groupMemberId).toBe(admin.groupMemberId);
+        expect(saved?.signature).toBe("member-sig");
+    });
+});

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/);
+    });
+});