@peers-app/peers-sdk 0.26.5 → 0.27.0

package/README.md

@@ -12,6 +12,8 @@ Peers is a local-first personal computing platform. Your data lives on your devi
 
 `definePackage()` and the contract builder API let you declare tables, tools, assistants, screens, and navigation entries. The runtime installs, loads, and hot-reloads your package across all devices.
 
+Isolated packages declare themselves with `@peers-app/peers-sdk/define`: `definePackage`, `defineTable`, `defineTool`, and `contractRef`, in a `src/package.ts`, with the package's own state in `deviceVar`, `userVar`, and the other persistent variables. The `peers-package` command (`peers-package manifest`, `peers-package build`) turns that declaration into the package's manifest, plain JSON in Peers IR, and bundles the same code for the sandbox. `peers-package contract freeze` records the contract versions a stable release froze (`frozen-contracts.json`), and the build refuses a change to one. It uses the package's own `esbuild`. See [Declaring a package](https://peers-app.github.io/Packages/declaring-a-package).
+
 ### ORM
 
 Table definitions with Zod schemas, data queries with a Mongo-style filter syntax, and async cursors. Tables sync across devices and encrypt automatically — you just define the schema.
@@ -75,7 +77,7 @@ Dynamic tool dispatch carries trusted signed identity and a strict delegated cei
 
 `accessLevel` is independent admission policy. A `preserve` tool with no entry level admits at None (0); an ordinary unclassified tool retains Self (100). Inside strict dispatch, an ordinary tool contributes its own effective level to the outgoing ceiling, while a `preserve` tool omits it but still retains the live user role, any inherited ceiling, and the contract consume ceiling. An Admin entering a Reader `preserve` router can therefore select an Admin target, but an Admin arriving through an ordinary Reader tool stays capped at Reader. Even None `preserve` tools require trusted identity and context. Strict dispatch denies step-up and unsupported remote or cross-context hops.
 
-Host packages select public targets through `context.dispatchTool({contractId, version, toolName, providerPackageId}, args)` and package-owned canonical aliases through `context.dispatchAction(alias, args)`. Isolated packages use `callConsumedTool`; all use the same runtime authorizer. Private aliases stay pinned to their owning implementation and target levels are read live on every call. Catalog `authorizedActions` is advisory; execution rechecks. Tool arguments never supply authority.
+Host packages select public targets through `context.dispatchTool({contractId, version, toolName, providerPackageId}, args)`. Isolated packages use `callConsumedTool`; both use the same runtime authorizer. A `private` tool is callable only by its own package, and target levels are read live on every call. The Contract Catalog's per-caller listings are advisory; execution rechecks. Tool arguments never supply authority.
 
 ## License
 

package/bin/peers-package.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Build an isolated package from its declarations. See `peers-package --help`.
+require("../dist/package-build/cli")
+  .main(process.argv.slice(2))
+  .then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      console.error(error instanceof Error ? error.message : error);
+      process.exitCode = 1;
+    },
+  );

package/define/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../dist/define/index.js",
+  "types": "../dist/define/index.d.ts"
+}

package/dist/contracts/__tests__/action-dispatch.test.js

@@ -2,10 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const group_member_roles_1 = require("../../data/group-member-roles");
 const utils_1 = require("../../utils");
-const VOICE_ACTION_CONTRACT_ID = "00muxgugn6xvs8f2r80ru205t";
+/** Voice Hub's contract, whose `voice-hub-run-action` declares preserve. */
+const VOICE_HUB_CONTRACT_ID = "00mskqamhdq1327mqehy58pps";
+/** The contract whose tools a test's entry tool dispatches to. */
+const TARGETS = (0, utils_1.newid)();
 const contract_provider_router_1 = require("../contract-provider-router");
 const contract_proxy_1 = require("../contract-proxy");
 const contract_transport_1 = require("../contract-transport");
+const target_dispatch_1 = require("./target-dispatch");
 function groupContext() {
     const userId = (0, utils_1.newid)();
     const groupId = (0, utils_1.newid)();
@@ -55,7 +59,11 @@ function tool(name, level, toolFn) {
         toolFn,
     };
 }
-describe("strict voice/touch action transport in a group", () => {
+/** A tool that runs the target `name` through `context.dispatchTool`. */
+function hop(name, level, target) {
+    return tool(name, level, (_, context) => context.dispatchTool?.({ contractId: TARGETS, version: 1, toolName: target }, {}));
+}
+describe("strict delegated tool dispatch in a group", () => {
     it("leaves ordinary host-tool admission outside the action scope on its existing user-role path", async () => {
         const group = groupContext();
         const contractId = (0, utils_1.newid)();
@@ -92,29 +100,21 @@ describe("strict voice/touch action transport in a group", () => {
     function setup(authority) {
         const group = groupContext();
         const writes = jest.fn(async () => ({ result: "milk" }));
+        const targets = {
+            list: tool("list", 20, async () => ({ result: [] })),
+            add: tool("add", 40, writes),
+            reader: hop("reader", 20, "add"),
+            writer: hop("writer", 40, "history"),
+            "writer-self": hop("writer-self", 40, "self"),
+            history: tool("history", 80, writes),
+            self: tool("self", undefined, writes),
+        };
         const resolution = {
-            contractId: VOICE_ACTION_CONTRACT_ID,
+            contractId: VOICE_HUB_CONTRACT_ID,
             version: 1,
+            forwardCallContext: true,
             tools: {
-                invoke: tool("invoke", 20, (input, context) => context.dispatchAction?.(input.tool, input.args ?? {})),
-            },
-            actionAliases: {
-                list_items: "list",
-                add_item: "add",
-                reader_hop: "reader",
-                writer_hop: "writer",
-                writer_self: "writer-self",
-                owner: "history",
-                self: "self",
-            },
-            actionTools: {
-                list: tool("list", 20, async () => ({ result: [] })),
-                add: tool("add", 40, writes),
-                reader: tool("reader", 20, (_, context) => context.dispatchAction?.("add_item", {})),
-                writer: tool("writer", 40, (_, context) => context.dispatchAction?.("owner", {})),
-                "writer-self": tool("writer-self", 40, (_, context) => context.dispatchAction?.("self", {})),
-                history: tool("history", 80, writes),
-                self: tool("self", undefined, writes),
+                invoke: tool("invoke", 20, (input, context) => context.dispatchTool?.({ contractId: TARGETS, version: 1, toolName: input.tool }, input.args ?? {})),
             },
         };
         Object.assign(resolution.tools.invoke.tool, { authorityPropagation: "preserve" });
@@ -125,11 +125,14 @@ describe("strict voice/touch action transport in a group", () => {
             authority,
         };
         const [client, server] = (0, contract_transport_1.inProcessTransportPair)();
-        const session = (0, contract_proxy_1.createContractProviderSession)(resolution, server, { context });
+        const session = (0, contract_proxy_1.createContractProviderSession)(resolution, server, {
+            context,
+            dispatchTool: (0, target_dispatch_1.targetDispatch)(TARGETS, targets),
+        });
         const consumer = (0, contract_proxy_1.createContractConsumer)({
-            contractId: VOICE_ACTION_CONTRACT_ID,
+            contractId: VOICE_HUB_CONTRACT_ID,
             version: 1,
-            name: "Voice Skill",
+            name: "Hub",
             description: "",
             tables: [],
             observables: [],
@@ -139,7 +142,7 @@ describe("strict voice/touch action transport in a group", () => {
         return {
             ...group,
             writes,
-            resolution,
+            targets,
             context,
             consumer,
             dispose: () => {
@@ -148,16 +151,16 @@ describe("strict voice/touch action transport in a group", () => {
             },
         };
     }
-    it("allows direct Writer dispatch while a group Reader can only list, including touch envelopes", async () => {
+    it("allows direct Writer dispatch while a group Reader can only list, ignoring payload grants", async () => {
         const p = setup();
         try {
-            await expect(p.consumer.tools.invoke({ tool: "add_item", args: { name: "milk" } })).resolves.toEqual({ result: "milk" });
+            await expect(p.consumer.tools.invoke({ tool: "add", args: { name: "milk" } })).resolves.toEqual({ result: "milk" });
             p.setRole(group_member_roles_1.GroupMemberRole.Reader);
-            await expect(p.consumer.tools.invoke({ tool: "list_items" })).resolves.toEqual({
+            await expect(p.consumer.tools.invoke({ tool: "list" })).resolves.toEqual({
                 result: [],
             });
             await expect(p.consumer.tools.invoke({
-                tool: "add_item",
+                tool: "add",
                 args: {
                     name: "milk",
                     userId: p.userId,
@@ -168,51 +171,36 @@ describe("strict voice/touch action transport in a group", () => {
                 },
             })).rejects.toThrow("Permission denied");
             expect(p.writes).toHaveBeenCalledTimes(1);
-            expect(await (0, contract_proxy_1.authorizedContractActionNames)(p.resolution, p.context)).toEqual(expect.not.arrayContaining(["add_item", "owner", "self"]));
         }
         finally {
             p.dispose();
         }
     });
-    it("caps Reader tools through invoke, denies Owner and Self from Writer tools, and ignores grants", async () => {
+    it("caps Reader tools through invoke, and denies Owner and Self from Writer tools", async () => {
         const p = setup();
         try {
-            await expect(p.consumer.tools.invoke({ tool: "reader_hop" })).rejects.toThrow("Permission denied");
-            await expect(p.consumer.tools.invoke({ tool: "writer_hop" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "reader" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "writer" })).rejects.toThrow("Permission denied");
             await expect(p.consumer.tools.invoke({ tool: "self" })).rejects.toThrow("Permission denied");
             p.setRole(group_member_roles_1.GroupMemberRole.Owner);
-            await expect(p.consumer.tools.invoke({ tool: "writer_hop" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "writer" })).rejects.toThrow("Permission denied");
             p.setRole(group_member_roles_1.GroupMemberRole.Founder);
-            await expect(p.consumer.tools.invoke({ tool: "writer_self" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "writer-self" })).rejects.toThrow("Permission denied");
             expect(p.writes).not.toHaveBeenCalled();
         }
         finally {
             p.dispose();
         }
     });
-    it("rechecks role and live metadata after catalog projection", async () => {
+    it("rechecks role and live metadata on every call", async () => {
         const p = setup();
         try {
-            expect(await (0, contract_proxy_1.authorizedContractActionNames)(p.resolution, p.context)).toContain("add_item");
             p.setRole(group_member_roles_1.GroupMemberRole.Reader);
-            await expect(p.consumer.tools.invoke({ tool: "add_item" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "add" })).rejects.toThrow("Permission denied");
             p.setRole(group_member_roles_1.GroupMemberRole.Writer);
-            if (!p.resolution.actionTools)
-                throw new Error("Missing actions");
-            p.resolution.actionTools.add.tool.accessLevel = 80;
-            await expect(p.consumer.tools.invoke({ tool: "add_item" })).rejects.toThrow("Permission denied");
-            await expect(p.consumer.tools.invoke({ tool: "invented" })).rejects.toThrow("Unknown action");
-            expect(p.writes).not.toHaveBeenCalled();
-        }
-        finally {
-            p.dispose();
-        }
-    });
-    it("refuses a Reader wrapper with no checked actions before an old raw handler can run", async () => {
-        const p = setup();
-        try {
-            delete p.resolution.actionAliases;
-            await expect(p.consumer.tools.invoke({ tool: "add_item" })).rejects.toThrow("Action dispatcher requires registered checked actions");
+            p.targets.add.tool.accessLevel = 80;
+            await expect(p.consumer.tools.invoke({ tool: "add" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "invented" })).rejects.toThrow("does not provide tool 'invented'");
             expect(p.writes).not.toHaveBeenCalled();
         }
         finally {
@@ -222,10 +210,10 @@ describe("strict voice/touch action transport in a group", () => {
     it("retains a delegated Reader frame from a trusted caller and fails missing identity closed", async () => {
         const p = setup({ userAccessLevel: 40, assistantAccessLevel: 20, strictActionScope: true });
         try {
-            await expect(p.consumer.tools.invoke({ tool: "add_item" })).rejects.toThrow("Permission denied");
+            await expect(p.consumer.tools.invoke({ tool: "add" })).rejects.toThrow("Permission denied");
             delete p.context.callerUserId;
             delete p.context.localUserId;
-            await expect(p.consumer.tools.invoke({ tool: "list_items", args: { callerUserId: p.userId } })).rejects.toThrow("missing caller identity");
+            await expect(p.consumer.tools.invoke({ tool: "list", args: { callerUserId: p.userId } })).rejects.toThrow("missing caller identity");
             expect(p.writes).not.toHaveBeenCalled();
         }
         finally {
@@ -271,17 +259,11 @@ describe("declared tool authority propagation", () => {
         const group = groupContext();
         group.setRole(userLevel);
         const effect = jest.fn(() => "executed");
-        const router = tool("route", entryLevel, (_, context) => context.dispatchAction?.("act", {}));
+        const router = hop("route", entryLevel, "target");
         if (preserve)
             Object.assign(router.tool, { authorityPropagation: "preserve" });
         const contractId = (0, utils_1.newid)();
-        const dispatch = (0, contract_proxy_1.createContractProvider)({
-            contractId,
-            version: 1,
-            tools: { route: router },
-            actionAliases: { act: "target" },
-            actionTools: { target: tool("target", targetLevel, effect) },
-        });
+        const dispatch = (0, contract_proxy_1.createContractProvider)({ contractId, version: 1, tools: { route: router }, forwardCallContext: true }, { dispatchTool: (0, target_dispatch_1.targetDispatch)(TARGETS, { target: tool("target", targetLevel, effect) }) });
         const result = dispatch({ contractId, version: 1, member: "tool", name: "route", operation: "run", args: [{}] }, {
             callerUserId: group.userId,
             dataContext: group.dataContext,
@@ -293,21 +275,19 @@ describe("declared tool authority propagation", () => {
             await expect(result).rejects.toThrow(/Permission denied/);
         expect(effect).toHaveBeenCalledTimes(allowed ? 1 : 0);
     });
-    it.each([
-        [VOICE_ACTION_CONTRACT_ID, 1, "invoke"],
-        ["00mskqamhdq1327mqehy58pps", 3, "voice-hub-run-action"],
-    ])("honors declared preserve on %s v%s %s without raising an inherited ceiling", async (contractId, version, name) => {
+    it("honors declared preserve on Voice Hub's voice-hub-run-action without raising an inherited ceiling", async () => {
+        const contractId = VOICE_HUB_CONTRACT_ID;
+        const version = 4;
+        const name = "voice-hub-run-action";
         const group = groupContext();
         const effect = jest.fn(() => ({ writerTargetExecuted: true }));
         const resolution = {
             contractId,
             version,
-            tools: {
-                [name]: tool(name, 20, (_, context) => context.dispatchAction?.("write", {})),
-            },
-            actionAliases: { write: "write" },
-            actionTools: { write: tool("write", 40, effect) },
+            forwardCallContext: true,
+            tools: { [name]: hop(name, 20, "write") },
         };
+        const dispatchTool = (0, target_dispatch_1.targetDispatch)(TARGETS, { write: tool("write", 40, effect) });
         const call = {
             contractId,
             version,
@@ -318,12 +298,12 @@ describe("declared tool authority propagation", () => {
         };
         const context = { callerUserId: group.userId, dataContext: group.dataContext };
         // An ordinary Reader wrapper caps a direct Writer at Reader inside the action scope.
-        const capped = (0, contract_proxy_1.createContractProvider)(resolution);
+        const capped = (0, contract_proxy_1.createContractProvider)(resolution, { dispatchTool });
         await expect(capped(call, context)).rejects.toThrow("Permission denied: strict delegation");
         expect(effect).not.toHaveBeenCalled();
         // The same wrapper declared preserve passes the Writer through to a Writer target.
         Object.assign(resolution.tools[name].tool, { authorityPropagation: "preserve" });
-        const preserving = (0, contract_proxy_1.createContractProvider)(resolution);
+        const preserving = (0, contract_proxy_1.createContractProvider)(resolution, { dispatchTool });
         await expect(preserving(call, context)).resolves.toEqual({ writerTargetExecuted: true });
         // An inherited Reader frame from an upstream ordinary tool is never raised.
         await expect(preserving(call, {

package/dist/contracts/__tests__/also-implements.test.d.ts

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

package/dist/contracts/__tests__/also-implements.test.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const field_type_1 = require("../../types/field-type");
+const utils_1 = require("../../utils");
+const registry_1 = require("../registry");
+const validate_1 = require("../validate");
+const contractId = (0, utils_1.newid)();
+/** Notes vN with one `add` tool taking `inputs`, returning `outputs`, and one `Notes` table. */
+function notes(version, { inputs = [], outputs = [], rows = [], } = {}, devTag) {
+    return {
+        contractId,
+        version,
+        ...(devTag ? { devTag } : {}),
+        name: "Notes",
+        description: "",
+        tables: [
+            {
+                name: "Notes",
+                description: "",
+                primaryKeyName: "noteId",
+                fields: [{ name: "noteId", type: field_type_1.FieldType.id }, ...rows],
+            },
+        ],
+        tools: [{ name: "add", usageDescription: "Add.", inputFields: inputs, outputFields: outputs }],
+        observables: [],
+        events: [],
+    };
+}
+const field = (name, optional = false) => ({
+    name,
+    type: field_type_1.FieldType.string,
+    ...(optional ? { optional } : {}),
+});
+describe("alsoImplements compatibility, by what callers send and receive", () => {
+    const satisfies = (implementation, target) => (0, validate_1.validateProviderSatisfiesContract)(implementation, target).valid;
+    it("lets an input become optional, but not an optional one required", () => {
+        expect(satisfies(notes(2, { inputs: [field("title", true)] }), notes(1, { inputs: [field("title")] }))).toBe(true);
+        expect(satisfies(notes(2, { inputs: [field("title")] }), notes(1, { inputs: [field("title", true)] }))).toBe(false);
+    });
+    it("keeps a required output required, and a table field's optionality as it was", () => {
+        expect(satisfies(notes(2, { outputs: [field("id", true)] }), notes(1, { outputs: [field("id")] }))).toBe(false);
+        expect(satisfies(notes(2, { outputs: [field("id")] }), notes(1, { outputs: [field("id", true)] }))).toBe(true);
+        expect(satisfies(notes(2, { rows: [field("title", true)] }), notes(1, { rows: [field("title")] }))).toBe(false);
+        expect(satisfies(notes(2, { rows: [field("title")] }), notes(1, { rows: [field("title", true)] }))).toBe(false);
+    });
+    it("keeps a required event payload field required, while allowing optional ones to become required", () => {
+        const event = (optional) => ({
+            ...notes(1),
+            events: [{ name: "added", description: "", payloadFields: [field("title", optional)] }],
+        });
+        expect(satisfies(event(true), event(false))).toBe(false);
+        expect(satisfies(event(false), event(true))).toBe(true);
+    });
+});
+describe("a carried alsoImplements definition", () => {
+    const providerId = (0, utils_1.newid)();
+    const v1 = notes(1, { inputs: [field("title")] });
+    const v2 = notes(2, { inputs: [field("title"), field("tag", true)] });
+    const alias = (definition = v1) => ({
+        definition: v2,
+        alsoImplements: [{ contractId, version: 1, definition }],
+    });
+    it("registers the target when the registry has none, and keeps one it already has", () => {
+        const cold = new registry_1.ContractRegistry();
+        expect(cold.registerBatch(providerId, [alias()]).valid).toBe(true);
+        expect(cold.getDefinition(contractId, 1)).toEqual(v1);
+        expect(cold.getProviderImplementation(contractId, 1, providerId)).toEqual({
+            contractId,
+            version: 2,
+        });
+        const warm = new registry_1.ContractRegistry();
+        const devV1 = { ...v1, devTag: "dev" };
+        warm.registerBatch((0, utils_1.newid)(), [{ definition: devV1 }]);
+        warm.registerBatch(providerId, [alias()]);
+        expect(warm.getDefinition(contractId, 1)).toEqual(devV1);
+    });
+    it("must match a frozen registered target, and be the version it declares", () => {
+        const registry = new registry_1.ContractRegistry();
+        registry.registerBatch((0, utils_1.newid)(), [{ definition: v1 }]);
+        const changed = notes(1, { inputs: [field("title"), field("body", true)] });
+        const refused = registry.registerBatch(providerId, [alias(changed)]);
+        expect(refused.valid).toBe(false);
+        expect(refused.errors[0].message).toContain("is frozen and cannot be modified");
+        expect(registry.getProviderPackageId(contractId, 2)).toBeUndefined();
+        const mislabeled = new registry_1.ContractRegistry().registerBatch(providerId, [
+            alias(notes(3, { inputs: [field("title")] })),
+        ]);
+        expect(mislabeled.errors[0].message).toContain("alsoImplements carries a definition that isn't");
+    });
+});
+test("legacy ranges retain explicitly provided handlers and alias the remaining versions", () => {
+    const registry = new registry_1.ContractRegistry();
+    const providerId = (0, utils_1.newid)();
+    expect(registry.register((0, utils_1.newid)(), notes(2)).valid).toBe(true);
+    expect(registry.registerBatch(providerId, [
+        { definition: notes(1) },
+        {
+            definition: notes(3),
+            alsoImplements: [{ contractId, version: { from: 1, to: 2 } }],
+        },
+    ]).valid).toBe(true);
+    expect(registry.getProviderImplementation(contractId, 1, providerId)).toEqual({
+        contractId,
+        version: 1,
+    });
+    expect(registry.getProviderImplementation(contractId, 2, providerId)).toEqual({
+        contractId,
+        version: 3,
+    });
+});

package/dist/contracts/__tests__/builder.test.js

@@ -18,6 +18,17 @@ const PROJECTS_ID = (0, utils_1.newid)();
 const FANCY_TASKS_ID = (0, utils_1.newid)();
 const GENERIC_ID = (0, utils_1.newid)();
 describe("definePackage", () => {
+    it("carries a contract's description, or an empty one", () => {
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.contract(TASKS_ID, 1, "Tasks", "Your tasks, by status.");
+            pkg.contract(NOTES_ID, 1, "Notes");
+        });
+        expect(result.contracts.map(({ name, description }) => [name, description])).toEqual([
+            ["Tasks", "Your tasks, by status."],
+            ["Notes", ""],
+        ]);
+    });
     it("produces a contract definition from a single contract with tables and tools", () => {
         const result = (0, builder_1.definePackage)((pkg) => {
             pkg.packageId = TEST_PKG_ID;
@@ -320,6 +331,40 @@ describe("definePackage", () => {
         expect(decls[0]).toEqual({ contractId: TASKS_ID, version: 1 });
         expect(decls[1]).toEqual({ contractId: TASKS_ID, version: { from: 1, to: 3 } });
     });
+    it("records the contracts a hub implementation exposes", () => {
+        const hubId = (0, utils_1.newid)();
+        const result = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.contract(GENERIC_ID, 1, "Generic");
+            const hub = pkg.contract(hubId, 2, "Hub");
+            hub.exposes(GENERIC_ID, 1);
+        });
+        expect(result.exposes?.get((0, types_2.contractKey)(hubId, 2))).toEqual([
+            { contractId: GENERIC_ID, version: 1 },
+        ]);
+        expect(result.exposes?.has((0, types_2.contractKey)(GENERIC_ID, 1))).toBe(false);
+        expect(result.contracts.find((contract) => contract.contractId === hubId)).not.toHaveProperty("exposes");
+        const hub = (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            const contract = pkg.contract(hubId, 2, "Hub");
+            expect(() => contract.exposes("short", 1)).toThrow("valid peer ID");
+            expect(() => contract.exposes(GENERIC_ID, 0)).toThrow("positive integer");
+        });
+        expect(hub.exposes?.size).toBe(0);
+    });
+    it("rejects invalid legacy exposures before installation", () => {
+        const hubId = (0, utils_1.newid)();
+        const build = (targets) => (0, builder_1.definePackage)((pkg) => {
+            pkg.packageId = TEST_PKG_ID;
+            pkg.contract(GENERIC_ID, 1, "Generic");
+            const hub = pkg.contract(hubId, 1, "Hub");
+            for (const target of targets)
+                hub.exposes(target, 1);
+        });
+        expect(() => build([(0, utils_1.newid)()])).toThrow("doesn't provide");
+        expect(() => build([hubId])).toThrow("can't expose itself");
+        expect(() => build([GENERIC_ID, GENERIC_ID])).toThrow("twice");
+    });
     it("includes package-level assistants and appNavs", () => {
         const assistant = { id: "asst1", name: "Task Bot" };
         const nav = { name: "Tasks", iconClassName: "bi bi-list-task", navigationPath: "app" };

package/dist/contracts/__tests__/contract-resolvers.test.js

@@ -240,7 +240,13 @@ describe("remote contract call authorization (group members)", () => {
             groupId,
             packageLoader: {
                 contractRegistry: {
-                    getDefinition: jest.fn((id, version) => id === contractId && version === 1 ? definition : undefined),
+                    selectProvider: jest.fn(({ contractId: id, version }) => id === contractId && version === 1
+                        ? { providerPackageId: "provider-a", definition }
+                        : undefined),
+                    getProviderImplementation: jest.fn((id, version) => ({
+                        contractId: id,
+                        version,
+                    })),
                 },
             },
         };
@@ -263,6 +269,127 @@ describe("remote contract call authorization (group members)", () => {
         expect(route.context?.dataContext).toBe(groupDataContext);
         expect(accessLevelMock.calls).toEqual([[groupDataContext, remoteIdentity.userId]]);
     });
+    it("uses the active frozen provider's remote policy, not the last registration's", async () => {
+        const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Admin,
+            callerLevel: access_level_1.AccessLevel.Reader,
+        });
+        const selected = groupDataContext.packageLoader.contractRegistry.selectProvider({
+            contractId,
+            version: 1,
+        });
+        if (!selected)
+            throw new Error("Missing test provider");
+        const { definition } = selected;
+        const registry = new index_1.ContractRegistry();
+        expect(registry.register("strict", definition).valid).toBe(true);
+        const permissive = {
+            ...definition,
+            tools: definition.tools.map((tool) => ({ ...tool, remoteAccessLevel: access_level_1.AccessLevel.Reader })),
+        };
+        expect(registry.register("permissive", permissive).valid).toBe(true);
+        Object.assign(groupDataContext.packageLoader, { contractRegistry: registry });
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("requires Admin");
+        registry.setActiveProvider(contractId, 1, "permissive");
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).resolves.toMatchObject({ providerPackageId: "permissive" });
+        expect(registry.register("dev", { ...permissive, devTag: "dev" }).valid).toBe(false);
+    });
+    it("uses the implementing tool's remote policy for a version the provider also implements", async () => {
+        const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            callerLevel: access_level_1.AccessLevel.Reader,
+        });
+        const selected = groupDataContext.packageLoader.contractRegistry.selectProvider({
+            contractId,
+            version: 1,
+        });
+        if (!selected)
+            throw new Error("Missing test provider");
+        const v1 = selected.definition;
+        // v2 keeps v1's tools but asks a remote caller for Admin.
+        const v2 = {
+            ...v1,
+            version: 2,
+            tools: v1.tools.map((tool) => ({ ...tool, remoteAccessLevel: access_level_1.AccessLevel.Admin })),
+        };
+        const registry = new index_1.ContractRegistry();
+        const registered = registry.registerBatch("upgraded", [
+            { definition: v2, alsoImplements: [{ contractId, version: 1, definition: v1 }] },
+        ]);
+        expect(registered.valid).toBe(true);
+        Object.assign(groupDataContext.packageLoader, { contractRegistry: registry });
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("requires Admin");
+        // Another provider's permissive policy must not admit this provider's alias.
+        expect(registry.register("permissive", { ...v2, tools: v1.tools }).valid).toBe(true);
+        expect(registry.setActiveProvider(contractId, 2, "permissive")).toBe(true);
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("requires Admin");
+    });
+    it("denies an alias when its implementing tool has no remote policy, and denies newer-only tools", async () => {
+        const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            callerLevel: access_level_1.AccessLevel.Reader,
+        });
+        const selected = groupDataContext.packageLoader.contractRegistry.selectProvider({
+            contractId,
+            version: 1,
+        });
+        if (!selected)
+            throw new Error("Missing test provider");
+        const v1 = selected.definition;
+        const v2 = {
+            ...v1,
+            version: 2,
+            tools: [
+                ...v1.tools.map(({ remoteAccessLevel: _level, ...tool }) => tool),
+                { ...v1.tools[0], name: "newTool" },
+            ],
+        };
+        const registry = new index_1.ContractRegistry();
+        expect(registry.register("upgraded", v2, [{ contractId, version: 1, definition: v1 }]).valid).toBe(true);
+        Object.assign(groupDataContext.packageLoader, { contractRegistry: registry });
+        await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("not remotely callable");
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, name: "newTool" }, userContext, remoteIdentity)).rejects.toThrow("not provided in this data context");
+        await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, version: 2, name: "newTool" }, userContext, remoteIdentity)).resolves.toMatchObject({ providerPackageId: "upgraded" });
+    });
+    it.each([
+        "request",
+        "router",
+    ])("keeps the authorized provider through %s dispatch", async (route) => {
+        const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
+            remoteAccessLevel: access_level_1.AccessLevel.Reader,
+            callerLevel: access_level_1.AccessLevel.Reader,
+        });
+        const handleCall = jest.fn(async () => "ok");
+        const resolveContractEndpoint = jest.fn(async (_request) => ({
+            handleCall,
+            dispose: jest.fn(),
+        }));
+        const getActiveContractProviderPackageId = jest.fn(() => "different-provider");
+        Object.assign(groupDataContext.packageLoader, {
+            resolveContractEndpoint,
+            getActiveContractProviderPackageId,
+        });
+        if (route === "request") {
+            await expect((0, index_1.handleContractCall)(toolCall, { userContext, remoteIdentity })).resolves.toBe("ok");
+        }
+        else {
+            const [consumer, provider] = (0, index_1.inProcessTransportPair)();
+            const router = (0, index_1.createUserContextContractProviderRouter)(provider, {
+                userContext,
+                remoteIdentity,
+            });
+            try {
+                await expect(consumer.emit(index_1.CONTRACT_REQUEST_CHANNEL, toolCall)).resolves.toBe("ok");
+            }
+            finally {
+                router.dispose();
+            }
+        }
+        expect(resolveContractEndpoint.mock.calls[0][0]).toMatchObject({
+            providerPackageId: "provider-a",
+        });
+        expect(getActiveContractProviderPackageId).not.toHaveBeenCalled();
+    });
     it("waits for catalog persistence before authorizing a cold group's first call", async () => {
         const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
             remoteAccessLevel: access_level_1.AccessLevel.Writer,
@@ -276,7 +403,7 @@ describe("remote contract call authorization (group members)", () => {
         const pending = (0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity);
         try {
             await new Promise((resolve) => setImmediate(resolve));
-            expect(groupDataContext.packageLoader.contractRegistry.getDefinition).not.toHaveBeenCalled();
+            expect(groupDataContext.packageLoader.contractRegistry.selectProvider).not.toHaveBeenCalled();
             expect(accessLevelMock.calls).toEqual([]);
         }
         finally {
@@ -294,7 +421,7 @@ describe("remote contract call authorization (group members)", () => {
             get: () => (fail ? Promise.reject(new Error("catalog unavailable")) : Promise.resolve()),
         });
         await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).rejects.toThrow("catalog unavailable");
-        expect(groupDataContext.packageLoader.contractRegistry.getDefinition).not.toHaveBeenCalled();
+        expect(groupDataContext.packageLoader.contractRegistry.selectProvider).not.toHaveBeenCalled();
         expect(accessLevelMock.calls).toEqual([]);
         fail = false;
         await expect((0, index_1.authorizeRemoteContractCall)(toolCall, userContext, remoteIdentity)).resolves.toMatchObject({ dataContextId: groupId });
@@ -359,7 +486,10 @@ describe("remote contract call authorization (group members)", () => {
         const { remoteIdentity, userContext, groupDataContext } = setupGroupMember({
             callerLevel: level,
         });
-        groupDataContext.packageLoader.contractRegistry.getDefinition.mockReturnValue((0, index_1.getPackagesContractDefinition)());
+        groupDataContext.packageLoader.contractRegistry.selectProvider.mockReturnValue({
+            providerPackageId: "system",
+            definition: (0, index_1.getPackagesContractDefinition)(),
+        });
         await expect((0, index_1.authorizeRemoteContractCall)({ ...toolCall, contractId: system_ids_1.packagesContractId, name: "listPackages" }, userContext, remoteIdentity)).rejects.toThrow("tool is not remotely callable");
     });
     it("keeps full access for Self-trusted callers without consulting remoteAccessLevel", async () => {

package/dist/contracts/__tests__/frozen-contracts.test.d.ts

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