@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/contracts/contract-proxy.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sameUserContractPermissionCheck = exports.CONTRACT_CALL_RPC = void 0;
+exports.createContractConsumerMembers = createContractConsumerMembers;
 exports.createContractConsumer = createContractConsumer;
 exports.createRemoteContractConsumer = createRemoteContractConsumer;
-exports.validateContractActions = validateContractActions;
-exports.authorizedContractActionNames = authorizedContractActionNames;
 exports.createContractProvider = createContractProvider;
 exports.createContractProviderEndpoint = createContractProviderEndpoint;
 exports.createContractProviderSession = createContractProviderSession;
@@ -48,40 +47,16 @@ const FORBIDDEN_REMOTE_TABLE_PROPERTIES = new Set([
  */
 exports.CONTRACT_CALL_RPC = contract_transport_1.CONTRACT_REQUEST_CHANNEL;
 /**
- * Build the **consumer** side of a contract proxy from a contract definition and a
- * transport. Member names come from the contract shape; table members are backed by a
- * `Proxy` that forwards accessed method names. The provider accepts only standard data
- * operations and custom methods marked by `ProxyClientTableMethodCalls`.
- *
- * Every access is turned into an {@link IContractCall} sent on the transport's fixed
- * {@link CONTRACT_REQUEST_CHANNEL}; the resolved ack is the provider's return value.
- *
- * Provider-only tables are omitted from {@link IContractConsumer.tables}; consumers must
- * call a declared provider method instead of raw CRUD.
- *
- * The consumer also subscribes to provider pushes: `events[name].subscribe(handler)` and
- * `tables[name].dataChanged.subscribe(handler)` both send a `"subscribe"` request and
- * demultiplex provider pushes arriving on {@link CONTRACT_NOTIFY_CHANNEL} by their
- * `subscriptionId` (shared `subscribeVia` path). Observables use the same push channel but
- * are *not* gated: each `observables[name]` is a live {@link Observable} mirror that subscribes
- * implicitly at creation, loads an initial snapshot (awaitable via
- * {@link IContractConsumer.loadingPromise}), and streams every subsequent change; local writes
- * send a fire-and-forget `set`. Call {@link IContractConsumer.dispose} to remove the notify
- * listener and unsubscribe every stream. Read-only observable writes are rejected on both
- * consumer and provider boundaries. Disposal is idempotent and prevents new remote operations;
- * cached observable reads remain available afterward.
+ * Build the member builders for one contract over `transport`. See
+ * {@link IContractConsumerMembers}.
  *
- * To run tools on another device use {@link createRemoteContractConsumer} instead.
- *
- * @param contract   The contract definition (shape) being consumed.
- * @param transport  Bidirectional channel to the provider; requests go out on
- *   {@link CONTRACT_REQUEST_CHANNEL}, notifications arrive on {@link CONTRACT_NOTIFY_CHANNEL}.
- * @param opts.dataContextId  Optional data context to scope every call to.
- * @param opts.providerPackageId  Optional provider to address. The local host
- *   accepts it only when that package is registered for this contract version.
+ * @param contractId The contract's id.
+ * @param version The contract's version.
+ * @param transport Bidirectional channel to the provider.
+ * @param opts.dataContextId Optional data context to scope every call to.
+ * @param opts.providerPackageId Optional provider to address.
  */
-function createContractConsumer(contract, transport, opts = {}) {
-    const { contractId, version } = contract;
+function createContractConsumerMembers(contractId, version, transport, opts = {}) {
     const { dataContextId, providerPackageId } = opts;
     let disposed = false;
     const emitRequest = (call) => transport.emit(contract_transport_1.CONTRACT_REQUEST_CHANNEL, {
@@ -140,6 +115,7 @@ function createContractConsumer(contract, transport, opts = {}) {
             }
         };
         const subscription = {
+            ready: subscribeAck,
             unsubscribe: () => {
                 if (!active) {
                     return false;
@@ -158,13 +134,11 @@ function createContractConsumer(contract, transport, opts = {}) {
         subscriptions.add(subscription);
         return subscription;
     };
-    const tables = {};
-    for (const table of contract.tables) {
-        const name = table.name;
+    const table = (name) => {
         // `dataChanged` is a subscribable that rides the notify channel (created lazily and
         // cached); every other accessed name forwards as a remote method call.
         let dataChanged;
-        tables[name] = new Proxy({}, {
+        return new Proxy({}, {
             get(_target, operation) {
                 if (typeof operation !== "string") {
                     return undefined;
@@ -196,39 +170,28 @@ function createContractConsumer(contract, transport, opts = {}) {
                 });
             },
         });
-    }
-    const tools = {};
-    for (const tool of contract.tools) {
-        const name = tool.name;
-        tools[name] = (...args) => request({
+    };
+    const tool = (name) => (...args) => request({
+        contractId,
+        version,
+        member: "tool",
+        name,
+        operation: "run",
+        args,
+        dataContextId,
+    });
+    const event = (name) => ({
+        subscribe: subscribeVia((subscriptionId, operation) => ({
             contractId,
             version,
-            member: "tool",
+            member: "event",
             name,
-            operation: "run",
-            args,
+            operation,
+            subscriptionId,
+            args: [],
             dataContextId,
-        });
-    }
-    const events = {};
-    for (const evt of contract.events ?? []) {
-        const name = evt.name;
-        events[name] = {
-            subscribe: subscribeVia((subscriptionId, operation) => ({
-                contractId,
-                version,
-                member: "event",
-                name,
-                operation,
-                subscriptionId,
-                args: [],
-                dataContextId,
-            })),
-        };
-    }
-    // Observables are backed by real, callable Observable mirrors (see below).
-    const observables = {};
-    const observableLoads = [];
+        })),
+    });
     const dispose = () => {
         if (disposed) {
             return;
@@ -243,32 +206,30 @@ function createContractConsumer(contract, transport, opts = {}) {
         offNotify();
         notifyHandlers.clear();
     };
-    const consumer = {
+    const setObservable = (name, value) => request({
         contractId,
         version,
-        tables,
-        tools,
-        observables,
-        events,
-        loadingPromise: Promise.resolve(),
-        dispose,
-    };
-    // Build each observable as a locally-mirrored Observable kept current by provider pushes
+        member: "observable",
+        name,
+        operation: "set",
+        args: [value],
+        dataContextId,
+    });
+    // Each observable is a locally-mirrored Observable kept current by provider pushes
     // (decision 4: observables are always streamed so reads are synchronous). Writes are
-    // fire-and-forget and chained onto the proxy-level loadingPromise for awaitable durability
-    // — the same shape as a persistent var (see data/persistent-vars.ts).
-    for (const obs of contract.observables) {
-        const name = obs.name;
+    // fire-and-forget, ordered by the caller's `chainWrite` — the same shape as a persistent var
+    // (see data/persistent-vars.ts).
+    const observableMirror = (name, writable, chainWrite) => {
         const mirror = (0, observable_1.observable)();
         // Guards against echo loops: while applying a provider push we must not re-`set` it, and
         // once a push has updated the mirror a later (possibly stale) initial `get` is ignored.
         let applyingRemote = false;
-        let pushed = false;
+        let revision = 0;
         const applyRemote = (value) => {
             if (disposed) {
                 return;
             }
-            pushed = true;
+            revision++;
             applyingRemote = true;
             try {
                 mirror(value);
@@ -277,9 +238,18 @@ function createContractConsumer(contract, transport, opts = {}) {
                 applyingRemote = false;
             }
         };
+        const get = () => request({
+            contractId,
+            version,
+            member: "observable",
+            name,
+            operation: "get",
+            args: [],
+            dataContextId,
+        });
         // Implicit, always-on subscription (not gated). `subscribeVia` registers the handler
         // before asking the provider to start streaming, so no push can arrive unhandled.
-        subscribeVia((subscriptionId, operation) => ({
+        const subscription = subscribeVia((subscriptionId, operation) => ({
             contractId,
             version,
             member: "observable",
@@ -299,7 +269,7 @@ function createContractConsumer(contract, transport, opts = {}) {
             if (disposed) {
                 throw new Error(`Contract consumer ${contractId} v${version} is disposed`);
             }
-            if (!obs.writable) {
+            if (!writable) {
                 throw new Error(`Observable '${name}' is read-only`);
             }
             return mirror(args[0]);
@@ -309,39 +279,104 @@ function createContractConsumer(contract, transport, opts = {}) {
         exposedMirror.subscriberCount = mirror.subscriberCount;
         // Initial snapshot so the mirror has a value to read synchronously. A push that arrived
         // first wins — the snapshot may already be stale by the time it resolves.
-        observableLoads.push(request({
-            contractId,
-            version,
-            member: "observable",
-            name,
-            operation: "get",
-            args: [],
-            dataContextId,
-        })
-            .then((value) => {
-            if (!disposed && !pushed) {
+        const loaded = subscription.ready
+            .then(async () => {
+            if (disposed)
+                return;
+            const value = await get();
+            if (!disposed && revision === 0) {
                 applyRemote(value);
             }
         })
-            .catch((err) => console.error("Contract observable initial get failed", err)));
-        // Local writes → fire-and-forget `set`, chained onto loadingPromise for durability.
+            .catch((err) => console.error("Contract observable initial get failed", err));
+        // Local writes → `set` through the caller's write chain.
         observableWriteSubscriptions.push(mirror.subscribe((value) => {
             if (applyingRemote || disposed) {
                 return;
             }
-            consumer.loadingPromise = consumer.loadingPromise.then(() => request({
-                contractId,
-                version,
-                member: "observable",
-                name,
-                operation: "set",
-                args: [value],
-                dataContextId,
-            })
-                .then(() => undefined)
-                .catch((err) => console.error("Contract observable set failed", err)));
+            revision++;
+            chainWrite(() => setObservable(name, value).then(() => undefined));
         }));
-        observables[name] = exposedMirror;
+        const refresh = () => {
+            const before = revision;
+            return get()
+                .then((value) => {
+                if (revision === before)
+                    applyRemote(value);
+            })
+                .catch((err) => console.error("Contract observable get failed", err));
+        };
+        return { observable: exposedMirror, loaded, refresh };
+    };
+    return { table, tool, event, observable: observableMirror, setObservable, dispose };
+}
+/**
+ * Build the **consumer** side of a contract proxy from a contract definition and a
+ * transport. Member names come from the contract shape; table members are backed by a
+ * `Proxy` that forwards accessed method names. The provider accepts only standard data
+ * operations and custom methods marked by `ProxyClientTableMethodCalls`.
+ *
+ * Every access is turned into an {@link IContractCall} sent on the transport's fixed
+ * {@link CONTRACT_REQUEST_CHANNEL}; the resolved ack is the provider's return value.
+ *
+ * Provider-only tables are omitted from {@link IContractConsumer.tables}; consumers must
+ * call a declared provider method instead of raw CRUD.
+ *
+ * The consumer also subscribes to provider pushes: `events[name].subscribe(handler)` and
+ * `tables[name].dataChanged.subscribe(handler)` both send a `"subscribe"` request and
+ * demultiplex provider pushes arriving on {@link CONTRACT_NOTIFY_CHANNEL} by their
+ * `subscriptionId` (shared `subscribeVia` path). Observables use the same push channel but
+ * are *not* gated: each `observables[name]` is a live {@link Observable} mirror that subscribes
+ * implicitly at creation, loads an initial snapshot (awaitable via
+ * {@link IContractConsumer.loadingPromise}), and streams every subsequent change; local writes
+ * send a fire-and-forget `set`. Call {@link IContractConsumer.dispose} to remove the notify
+ * listener and unsubscribe every stream. Read-only observable writes are rejected on both
+ * consumer and provider boundaries. Disposal is idempotent and prevents new remote operations;
+ * cached observable reads remain available afterward.
+ *
+ * To run tools on another device use {@link createRemoteContractConsumer} instead.
+ *
+ * @param contract   The contract definition (shape) being consumed.
+ * @param transport  Bidirectional channel to the provider; requests go out on
+ *   {@link CONTRACT_REQUEST_CHANNEL}, notifications arrive on {@link CONTRACT_NOTIFY_CHANNEL}.
+ * @param opts.dataContextId  Optional data context to scope every call to.
+ * @param opts.providerPackageId  Optional provider to address. The local host
+ *   accepts it only when that package is registered for this contract version.
+ */
+function createContractConsumer(contract, transport, opts = {}) {
+    const { contractId, version } = contract;
+    const members = createContractConsumerMembers(contractId, version, transport, opts);
+    const tables = {};
+    for (const table of contract.tables) {
+        tables[table.name] = members.table(table.name);
+    }
+    const tools = {};
+    for (const tool of contract.tools) {
+        tools[tool.name] = members.tool(tool.name);
+    }
+    const events = {};
+    for (const evt of contract.events ?? []) {
+        events[evt.name] = members.event(evt.name);
+    }
+    const observables = {};
+    const consumer = {
+        contractId,
+        version,
+        tables,
+        tools,
+        observables,
+        events,
+        loadingPromise: Promise.resolve(),
+        dispose: members.dispose,
+    };
+    // Writes are chained onto the proxy-level loadingPromise for awaitable durability.
+    const observableLoads = [];
+    for (const obs of contract.observables) {
+        const { observable: mirror, loaded } = members.observable(obs.name, Boolean(obs.writable), (send) => {
+            consumer.loadingPromise = consumer.loadingPromise.then(() => send().catch((err) => console.error("Contract observable set failed", err)));
+        });
+        observables[obs.name] = mirror;
+        observableLoads.push(loaded);
     }
     consumer.loadingPromise = Promise.all(observableLoads).then(() => undefined);
     return consumer;
@@ -502,70 +537,6 @@ async function assertContractToolAccess(tool, call, context) {
         : access_level_1.AccessLevel.None;
     return (0, action_dispatch_1.authorizeToolDispatch)({ ...context.authority, userId, userAccessLevel: userLevel }, required, mode, strict);
 }
-/** Validate private alias registrations before exposing any action wrapper. */
-function validateContractActions(resolution) {
-    for (const [name, target] of Object.entries(resolution.actionAliases ?? {})) {
-        const tool = resolution.actionTools?.[target];
-        if (!name || !tool || tool.tool.name !== target || target === resolution.actionDispatcher)
-            throw new Error(`Unregistered action target: ${name} -> ${target}`);
-    }
-}
-/**
- * Project executable aliases using live tool metadata and trusted caller identity.
- *
- * Catalog filtering is advisory; execution rechecks every target.
- */
-async function authorizedContractActionNames(resolution, context) {
-    validateContractActions(resolution);
-    if (!(context.callerUserId ?? context.localUserId) || !context.dataContext)
-        return [];
-    const wrapperName = resolution.actionDispatcher ??
-        Object.keys(resolution.tools ?? {}).find((name) => resolution.tools?.[name].tool.authorityPropagation === "preserve");
-    const wrapper = wrapperName ? resolution.tools?.[wrapperName] : undefined;
-    if (!wrapper)
-        return [];
-    let wrapperAuthority;
-    try {
-        wrapperAuthority = await assertContractToolAccess(wrapper, {
-            contractId: resolution.contractId,
-            version: resolution.version,
-            member: "tool",
-            name: wrapperName,
-            operation: "run",
-            args: [],
-        }, context);
-    }
-    catch {
-        return [];
-    }
-    const allowed = [];
-    for (const [name, target] of Object.entries(resolution.actionAliases ?? {})) {
-        try {
-            const action = resolution.actionTools?.[target];
-            if (!action)
-                continue;
-            await assertContractToolAccess(action, {
-                contractId: resolution.contractId,
-                version: resolution.version,
-                member: "tool",
-                name: target,
-                operation: "run",
-                args: [],
-            }, {
-                ...context,
-                authority: {
-                    ...wrapperAuthority,
-                    strictActionScope: true,
-                },
-            });
-            allowed.push(name);
-        }
-        catch {
-            /* Denied aliases are not executable. */
-        }
-    }
-    return allowed;
-}
 /**
  * Build the **provider** side of a contract proxy: an async handler that permission-checks
  * an {@link IContractCall} and dispatches it to the live table method / tool fn / observable
@@ -580,7 +551,6 @@ async function authorizedContractActionNames(resolution, context) {
  */
 function createContractProvider(resolution, opts = {}) {
     const { permissionCheck } = opts;
-    validateContractActions(resolution);
     return async (call, context = {}) => {
         if (call.contractId !== resolution.contractId || call.version !== resolution.version) {
             throw new Error(`Contract mismatch: resolution provides ${resolution.contractId} v${resolution.version} ` +
@@ -622,13 +592,10 @@ function createContractProvider(resolution, opts = {}) {
                 if (!tool) {
                     throw new Error(`Contract ${call.contractId} does not provide tool '${call.name}'`);
                 }
-                if (resolution.actionTools && !Object.keys(resolution.actionAliases ?? {}).length)
-                    throw new Error("Action dispatcher requires registered checked actions");
                 const { workflow, ...caller } = context;
                 const authority = await assertContractToolAccess(tool, call, caller);
                 if (resolution.toolContext ||
                     resolution.forwardCallContext ||
-                    resolution.actionAliases ||
                     authority.strictActionScope) {
                     if (call.args.length > 1) {
                         throw new Error("Permission denied: tool runs accept a single argument when host context is forwarded");
@@ -654,29 +621,6 @@ function createContractProvider(resolution, opts = {}) {
                             authority: (0, action_dispatch_1.narrowActionPrincipal)(frame, true),
                         });
                     };
-                    const checkedActionDispatcher = (frame, capabilities) => async (name, args) => {
-                        const target = resolution.actionAliases?.[name];
-                        const action = target ? resolution.actionTools?.[target] : undefined;
-                        if (!target || !action)
-                            throw new Error(`Unknown action selector: ${name}`);
-                        const actionCall = { ...call, name: target, args: [args] };
-                        const actionContext = {
-                            ...caller,
-                            authority: { ...frame, strictActionScope: true },
-                        };
-                        const checked = await assertContractToolAccess(action, actionCall, actionContext);
-                        return action.toolFn(args, {
-                            ...capabilities,
-                            workflow: undefined,
-                            callerPackageId: caller.callerPackageId,
-                            actorUserId: checked.userId,
-                            authority: checked,
-                            callContext: { ...caller, authority: checked },
-                            incomingCallContext: actionContext,
-                            dispatchAction: checkedActionDispatcher(checked, capabilities),
-                            dispatchTool: dispatchTool(checked),
-                        });
-                    };
                     return tool.toolFn(call.args[0], {
                         ...base,
                         workflow: caller.callerDeviceId || caller.callerPackageId ? undefined : workflow,
@@ -686,9 +630,6 @@ function createContractProvider(resolution, opts = {}) {
                         incomingCallContext: caller,
                         dispatchTool: dispatchTool(authority),
                         authority,
-                        dispatchAction: resolution.actionAliases
-                            ? checkedActionDispatcher(authority, base)
-                            : undefined,
                     });
                 }
                 return tool.toolFn(...call.args);

package/dist/contracts/contract-resolvers.d.ts

@@ -102,10 +102,12 @@ export declare function isLocalOnlyContractId(contractId: string): boolean;
  *    `TrustLevel.Self`) keeps full access; an omitted data context selects the provider's
  *    personal context, and a named one must be a group this device already has.
  * 4. Any other verified caller is treated as a **group member**: the call must name a
- *    group the provider belongs to, must be a tool run, the contract definition registered
- *    for that group must mark the tool with {@link IContractTool.remoteAccessLevel}, and
- *    the caller's role in that group must meet it. Missing loader, definition, or level
- *    fails closed. Catalog readiness precedes reading the group's definitions.
+ *    group the provider belongs to, must be a tool run, the selected provider's definition
+ *    must mark the tool with {@link IContractTool.remoteAccessLevel}, and
+ *    the caller's role in that group must meet it. For a version the provider also implements,
+ *    the requested version must declare the tool and the implementing contract's tool gives the
+ *    level. Missing loader, definition, or level fails closed. Catalog readiness precedes
+ *    reading the group's definitions.
  *
  * @param call Inbound call.
  * @param userContext Provider's user context.

package/dist/contracts/contract-resolvers.js

@@ -241,10 +241,12 @@ function isLocalOnlyContractId(contractId) {
  *    `TrustLevel.Self`) keeps full access; an omitted data context selects the provider's
  *    personal context, and a named one must be a group this device already has.
  * 4. Any other verified caller is treated as a **group member**: the call must name a
- *    group the provider belongs to, must be a tool run, the contract definition registered
- *    for that group must mark the tool with {@link IContractTool.remoteAccessLevel}, and
- *    the caller's role in that group must meet it. Missing loader, definition, or level
- *    fails closed. Catalog readiness precedes reading the group's definitions.
+ *    group the provider belongs to, must be a tool run, the selected provider's definition
+ *    must mark the tool with {@link IContractTool.remoteAccessLevel}, and
+ *    the caller's role in that group must meet it. For a version the provider also implements,
+ *    the requested version must declare the tool and the implementing contract's tool gives the
+ *    level. Missing loader, definition, or level fails closed. Catalog readiness precedes
+ *    reading the group's definitions.
  *
  * @param call Inbound call.
  * @param userContext Provider's user context.
@@ -284,8 +286,28 @@ async function authorizeRemoteContractCall(call, userContext, remoteIdentity) {
     }
     const dataContext = userContext.getDataContext(dataContextId);
     await dataContext.packageLoader?.catalogReady;
-    const definition = dataContext.packageLoader?.contractRegistry?.getDefinition(call.contractId, call.version);
-    const tool = definition?.tools.find((entry) => entry.name === call.name);
+    const callerLevel = await (0, group_permissions_1.getUserAccessLevel)(dataContext, remoteIdentity.userId);
+    // Policy belongs to the executing provider, not the latest registration of this shape.
+    // Select after the async role lookup and retain the selection through endpoint resolution.
+    const registry = dataContext.packageLoader?.contractRegistry;
+    const selected = registry?.selectProvider({
+        contractId: call.contractId,
+        version: call.version,
+    });
+    // A version the provider also implements runs its implementing contract's tool, so that tool's
+    // policy decides; the requested version must still declare the tool.
+    const implementation = selected &&
+        registry?.getProviderImplementation(call.contractId, call.version, selected.providerPackageId);
+    const running = implementation &&
+        registry?.selectProvider({
+            contractId: implementation.contractId,
+            version: implementation.version,
+            providerPackageIds: [selected.providerPackageId],
+        });
+    const declared = selected?.definition.tools.some((entry) => entry.name === call.name);
+    const tool = declared
+        ? running?.definition.tools.find((entry) => entry.name === call.name)
+        : undefined;
     if (!tool) {
         throw permissionDenied(call, "tool is not provided in this data context");
     }
@@ -293,12 +315,12 @@ async function authorizeRemoteContractCall(call, userContext, remoteIdentity) {
         throw permissionDenied(call, "tool is not remotely callable");
     }
     const requiredLevel = (0, access_level_1.resolveAccessLevel)(tool.remoteAccessLevel);
-    const callerLevel = await (0, group_permissions_1.getUserAccessLevel)(dataContext, remoteIdentity.userId);
     if (callerLevel <= access_level_1.AccessLevel.None || callerLevel < requiredLevel) {
         throw permissionDenied(call, `requires ${(0, access_level_1.getAccessLevelLabel)(requiredLevel)} (${requiredLevel}), caller has ${(0, access_level_1.getAccessLevelLabel)(callerLevel)} (${callerLevel})`);
     }
     return {
         dataContextId,
+        providerPackageId: selected?.providerPackageId,
         context: {
             callerUserId: remoteIdentity.userId,
             localUserId: userContext.userId,
@@ -509,7 +531,8 @@ async function handleContractCall(call, opts) {
         const endpoint = await dataContext.packageLoader.resolveContractEndpoint({
             contractId: call.contractId,
             version: call.version,
-            providerPackageId: await getActiveProviderPackageId(dataContext, call.contractId, call.version),
+            providerPackageId: authorization.providerPackageId ??
+                (await getActiveProviderPackageId(dataContext, call.contractId, call.version)),
             dataContextId: authorization.dataContextId,
             context: authorization.context ?? {},
             notify: async () => undefined,
@@ -521,7 +544,7 @@ async function handleContractCall(call, opts) {
             endpoint.dispose();
         }
     }
-    const resolver = getContractResolver(call.contractId, call.version, undefined, dataContext);
+    const resolver = getContractResolver(call.contractId, call.version, authorization.providerPackageId, dataContext);
     if (!resolver) {
         throw new Error(`No contract provider registered for ${call.contractId} v${call.version}`);
     }

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

@@ -0,0 +1,59 @@
+import type { IContractDefinition } from "./types";
+/** The file, at a package's root, that records the contract versions its stable releases froze. */
+export declare const FROZEN_CONTRACTS_FILE = "frozen-contracts.json";
+/** One contract version a stable release froze: its shape as released, and that release. */
+export interface IFrozenContract extends Omit<IContractDefinition, "devTag"> {
+    /** The package version whose stable release froze it. */
+    frozenBy: string;
+}
+/** What `frozen-contracts.json` holds. */
+export interface IFrozenContracts {
+    /** What the file is, for someone who opens it. */
+    about?: string;
+    /** Every frozen contract version, by contract id and version. */
+    contracts: IFrozenContract[];
+}
+/** A frozen contract version the package still provides, but with another shape. */
+export interface IFrozenContractChange {
+    /** The contract version as frozen. */
+    contract: IFrozenContract;
+    /** What changed, one member per line (`tool add-item changed`). */
+    changes: string[];
+}
+/** What {@link checkFrozenContracts} found. */
+export interface IFrozenContractsCheck {
+    /** Frozen contract versions the package provides with a different shape. */
+    changed: IFrozenContractChange[];
+    /** Frozen contract versions the package no longer provides (allowed; a consumer may miss it). */
+    notProvided: IFrozenContract[];
+}
+/**
+ * Check the contracts a package provides against the versions its stable releases froze.
+ *
+ * @param frozen - The package's `frozen-contracts.json`.
+ * @param provided - The contracts the package provides now. A `devTag` is ignored.
+ * @returns The frozen versions it changed, and those it no longer provides.
+ * @throws When the package provides the same contract identity more than once.
+ */
+export declare function checkFrozenContracts(frozen: IFrozenContracts, provided: readonly IContractDefinition[]): IFrozenContractsCheck;
+/**
+ * Record every contract version a release provides as frozen by that release, keeping the
+ * versions already frozen. Refuses (records nothing) when the release changed a frozen version.
+ *
+ * @param frozen - The package's `frozen-contracts.json`, or undefined when it has none yet.
+ * @param provided - The contracts the release provides.
+ * @param packageVersion - The release's package version.
+ * @returns The file's new content, the versions it added, and the check that decided.
+ * @throws When the package version is blank or provided contract identities repeat.
+ */
+export declare function freezeContracts(frozen: IFrozenContracts | undefined, provided: readonly IContractDefinition[], packageVersion: string): {
+    frozen: IFrozenContracts;
+    added: IFrozenContract[];
+    check: IFrozenContractsCheck;
+};
+/**
+ * Describe a check's failures, one line per changed contract version, for a build or test error.
+ *
+ * @param check - What {@link checkFrozenContracts} found.
+ */
+export declare function describeFrozenContractChanges(check: IFrozenContractsCheck): string[];