@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/define/context.d.ts

@@ -0,0 +1,77 @@
+import type { PersistentVarScope } from "../data/persistent-var-identity";
+import type { IsolatedContractTableOperation } from "../package-loader/isolated-runtime";
+/**
+ * Ends a subscription or a watch. Unsubscribing from a consumed contract waits for the provider
+ * and rejects if it fails, so await it or catch the rejection.
+ */
+export type PackageUnsubscribe = () => unknown;
+/** A consumed-event callback. `ctx` belongs to that delivery. */
+export type PackageEventHandler = (payload: unknown, ctx: IPackageContext) => unknown;
+/** Picks one provider of a consumed contract. */
+export interface IPackageProviderOptions {
+    /** Package that serves the contract. Omit for the group's default provider. */
+    providerPackageId?: string;
+}
+/**
+ * The host functions the Runtime gives one handler call (guest API 2 and 3).
+ *
+ * Every tool handler gets its own `ctx`, and host calls made through it act for that call's
+ * caller, even while other calls run. The table and contract handles in this module take a
+ * `ctx` and make these calls for you, and the package's variables (`deviceVar` and the rest),
+ * events, and observables need none; use these directly only for what those don't cover yet.
+ */
+export interface IPackageContext {
+    /** Run a tool on a contract this package consumes (or provides), as this call's caller. */
+    callConsumedTool(contractId: string, version: number, toolName: string, args?: unknown, options?: IPackageProviderOptions): Promise<unknown>;
+    /** Run a tool on another device. The remote device authorizes the call. */
+    callRemoteTool(contractId: string, version: number, deviceId: string, toolName: string, args?: unknown): Promise<unknown>;
+    /** Subscribe to an event on a consumed or provided contract. */
+    subscribeConsumedEvent(contractId: string, version: number, eventName: string, handler: PackageEventHandler): Promise<PackageUnsubscribe>;
+    /** Subscribe to `dataChanged` on a table another package exposes through a contract. */
+    subscribeConsumedTableEvent(contractId: string, version: number, tableName: string, eventName: "dataChanged", handler: PackageEventHandler): Promise<PackageUnsubscribe>;
+    /** Emit an event declared on one of this package's provided contracts. */
+    emitContractEvent(contractId: string, version: number, eventName: string, payload: unknown): Promise<unknown>;
+    /** Call a standard method on a table another package exposes through a contract. */
+    callConsumedTable(contractId: string, version: number, tableName: string, operation: IsolatedContractTableOperation, args?: unknown[]): Promise<unknown>;
+    /** Read one row from a consumed contract table. */
+    getConsumedTableRecord(contractId: string, version: number, tableName: string, recordId: string): Promise<unknown>;
+    /** Save one row to a consumed contract table. */
+    saveConsumedTableRecord(contractId: string, version: number, tableName: string, record: unknown): Promise<unknown>;
+    /** Read a consumed contract's observable. */
+    getConsumedObservable(contractId: string, version: number, observableName: string, options?: IPackageProviderOptions): Promise<unknown>;
+    /** Write a consumed contract's writable observable. */
+    setConsumedObservable(contractId: string, version: number, observableName: string, value: unknown, options?: IPackageProviderOptions): Promise<unknown>;
+    /** Call a standard method on one of this package's own tables, with its arguments. */
+    callOwnedTable(tableName: string, operation: IsolatedContractTableOperation, args?: unknown[]): Promise<unknown>;
+    /** Read one owned row by id. */
+    getOwnedTableRecord(tableName: string, recordId: string): Promise<unknown>;
+    /** Insert or replace one owned row. */
+    saveOwnedTableRecord(tableName: string, record: unknown): Promise<unknown>;
+    /** List owned rows (at most 500; use `callOwnedTable` to filter or page). */
+    listOwnedTableRecords(tableName: string): Promise<unknown>;
+    /** Delete one owned row by id. */
+    deleteOwnedTableRecord(tableName: string, recordId: string): Promise<unknown>;
+    /** Read a package-owned persistent variable. The host applies the package prefix. */
+    getOwnedPersistentVar(scope: PersistentVarScope, name: string): Promise<unknown>;
+    /** Replace a package-owned persistent variable. */
+    setOwnedPersistentVar(scope: PersistentVarScope, name: string, value: unknown): Promise<unknown>;
+    /**
+     * Call `handler` when a package-owned persistent variable changes, including through device
+     * sync, until the returned function is called or the worker stops. `handler` gets no value:
+     * read it again.
+     */
+    watchOwnedPersistentVar(scope: PersistentVarScope, name: string, handler: () => unknown): Promise<PackageUnsubscribe>;
+    /**
+     * Set the value of an in-memory observable this package provides (one declared without a
+     * `persistentVar`). The host checks it against the observable's `valueType`, keeps it for
+     * readers, and pushes it to subscribers. Allowed at any time while the worker runs.
+     */
+    publishOwnedObservable(contractId: string, version: number, observableName: string, value: unknown): Promise<unknown>;
+    /**
+     * Take guest API 2 consumers' writes to a writable in-memory observable this package
+     * provides. `handler` gets the value with no caller authority, stores and publishes it, and
+     * returns what it stored. A later call replaces the handler. Guest API 3 instead routes
+     * writes through the contract member handler under the caller's authority.
+     */
+    onOwnedObservableSet(contractId: string, version: number, observableName: string, handler: (value: unknown) => unknown): void;
+}

package/dist/define/context.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/define/contract-ref.d.ts

@@ -0,0 +1,177 @@
+import type { z } from "zod";
+import type { IPackageContext, IPackageProviderOptions } from "./context";
+import type { IContractMembers } from "./define-package";
+import type { IPackageEvent } from "./events";
+import type { IPackageObservableDeclaration } from "./observables";
+import type { IPackageTable, IPackageTableHandle } from "./table";
+import type { IPackageToolDeclaration } from "./tool";
+/**
+ * One tool on a contract client: a tool declaration, or a function signature. A declared tool's
+ * input may be left out when none of its fields is required.
+ */
+export type ContractClientTool<T> = T extends IPackageToolDeclaration<infer I, infer O, any, any> ? (...args: Partial<I> extends I ? [args?: I] : [args: I]) => Promise<O> : T extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+/** A contract's tools, typed from tool declarations or function signatures. */
+export type ContractClientTools<T> = {
+    readonly [K in keyof T]: ContractClientTool<T[K]>;
+};
+/** Untyped tools: any name, any arguments. */
+export type AnyContractTools = Record<string, (args?: unknown) => Promise<unknown>>;
+/** A member's name: from its definition (`defineTool` and the rest) or from Peers IR. */
+type MemberName<M> = M extends {
+    definition: {
+        name: infer N extends string;
+    };
+} ? N : M extends {
+    name: infer N extends string;
+} ? N : never;
+/** Untyped rows, for a reference typed by its tools only. */
+type AnyRow = Record<string, any>;
+/** A contract's members, unwrapping a declaration's reference when necessary. */
+export type ContractMembersOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? D : T;
+/** The contract's id, when `T` is a contract type; otherwise any string. */
+export type ContractIdOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractIdOf<D> : T extends IContractMembers<infer Id, any, any, any, any, any> ? Id : string;
+/** The contract's version, when `T` is a contract type; otherwise any number. */
+export type ContractVersionOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractVersionOf<D> : T extends IContractMembers<any, infer V, any, any, any, any> ? V : number;
+/**
+ * A contract's tools by name: from a contract type (`typeof News`, or a declaration's), or a
+ * map of tool declarations or function signatures.
+ */
+export type ContractToolsOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractToolsOf<D> : T extends IContractMembers<any, any, any, infer Tools, any, any> ? {
+    readonly [K in Tools[number] as MemberName<K>]: ContractClientTool<K>;
+} : ContractClientTools<T>;
+/** A contract's table rows by table name. Untyped for a reference typed by its tools only. */
+export type ContractTableRowsOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractTableRowsOf<D> : T extends IContractMembers<any, any, infer Tables, any, any, any> ? {
+    [K in Tables[number] as MemberName<K>]: K extends IPackageTable<infer S, any> ? z.infer<S> : AnyRow;
+} : Record<string, AnyRow>;
+/**
+ * What a contract's tables take on `save`, by table name: the schema's input, so fields with
+ * defaults may be left out. The provider's table parses every save, consumers' included.
+ * Untyped for a reference typed by its tools only.
+ */
+export type ContractTableInputsOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractTableInputsOf<D> : T extends IContractMembers<any, any, infer Tables, any, any, any> ? {
+    [K in Tables[number] as MemberName<K>]: K extends IPackageTable<infer S, any, any> ? z.input<S> : AnyRow;
+} : Record<string, AnyRow>;
+/** A contract's event payloads by event name. IR events carry `unknown`. */
+export type ContractEventPayloadsOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractEventPayloadsOf<D> : T extends IContractMembers<any, any, any, any, any, infer Events> ? {
+    [K in Events[number] as MemberName<K>]: K extends IPackageEvent<any, any, infer O> ? O : unknown;
+} : Record<string, unknown>;
+/** A contract's observable values by observable name. IR observables carry `unknown`. */
+export type ContractObservableValuesOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractObservableValuesOf<D> : T extends IContractMembers<any, any, any, any, infer Observables, any> ? {
+    [K in Observables[number] as MemberName<K>]: K extends IPackageObservableDeclaration<infer V, any, any> ? V : unknown;
+} : Record<string, unknown>;
+/** A contract's observable writability, preserving literal declarations; unknown for tools-only refs. */
+export type ContractObservableWritabilityOf<T> = T extends {
+    readonly kind: "contract-ref";
+    readonly declaration: infer D;
+} ? ContractObservableWritabilityOf<D> : T extends IContractMembers<any, any, any, any, infer Observables, any> ? {
+    [K in Observables[number] as MemberName<K>]: K extends IPackageObservableDeclaration<any, any, infer W> ? W : K extends {
+        writable?: infer W;
+    } ? W : false;
+} : Record<string, boolean>;
+/** A table's handle for a row type. */
+type RowHandle<R, I> = R extends AnyRow ? IPackageTableHandle<R, I> : never;
+/** One observable on a contract client: read it, and write it when the contract allows. */
+export type ContractClientObservable<V, W> = true extends W ? {
+    /** The provider's current value. An empty whole value crosses the bridge as `null`. */
+    get(): Promise<V | null | undefined>;
+    /**
+     * Write as this call's caller. Whole values can't carry `undefined`; to clear one, its
+     * schema must allow `null`. Returns the stored value; an empty whole value is `null`.
+     */
+    set(value: Exclude<V, undefined>): Promise<V | null>;
+} : {
+    /** The provider's current value. An empty whole value crosses the bridge as `null`. */
+    get(): Promise<V | null | undefined>;
+};
+/** Options for a contract client: which provider its calls reach. */
+export interface IContractClientOptions extends IPackageProviderOptions {
+}
+/** A contract's members, bound to one handler call. */
+export interface IContractClient<T> {
+    /** Tools, run as this call's caller: `Http(ctx).tools.request({ ... })`. */
+    readonly tools: ContractToolsOf<T>;
+    /**
+     * Tables the contract exposes, used as this call's caller: `News(ctx).tables.Headlines.list()`.
+     * Every call goes through the providing package's table (its class, if it has one), so
+     * `save` takes the schema's input and the provider's defaults and transforms apply.
+     */
+    readonly tables: {
+        readonly [K in keyof ContractTableRowsOf<T>]: RowHandle<ContractTableRowsOf<T>[K], K extends keyof ContractTableInputsOf<T> ? ContractTableInputsOf<T>[K] : never>;
+    };
+    /**
+     * Observables the contract exposes, read (and written, when writable) as this call's
+     * caller: `await Weather(ctx).observables.forecast.get()`.
+     */
+    readonly observables: {
+        readonly [K in keyof ContractObservableValuesOf<T>]: ContractClientObservable<ContractObservableValuesOf<T>[K], K extends keyof ContractObservableWritabilityOf<T> ? ContractObservableWritabilityOf<T>[K] : boolean>;
+    };
+}
+/**
+ * A reference to a contract: one this package consumes, one it provides when it should call
+ * itself through the Runtime so the caller's access is checked again, or (with `hostContract`)
+ * the one a UI calls.
+ */
+export interface IContractRef<T = AnyContractTools> {
+    /**
+     * The contract's members for one handler call. Pass `{ providerPackageId }` to reach one
+     * provider rather than the group's default (to call every provider of a contract, say).
+     * Table calls can't pick a provider yet.
+     */
+    (ctx: IPackageContext, options?: IContractClientOptions): IContractClient<T>;
+    /** Marks a contract reference. */
+    readonly kind: "contract-ref";
+    /** The contract's id. */
+    readonly contractId: string;
+    /** The contract's version. */
+    readonly version: number;
+}
+/**
+ * Reference a contract by id and version. Declare it with `pkg.consumes(ref)` when another
+ * package provides it, then call it from a handler: `await Http(ctx).tools.request({ ... })`.
+ *
+ * Type it with the contract (`contractRef<typeof News>(contractId, version)`, where `News` is
+ * from `defineContract` or `declareContract`; import it with `import type` so no handler code comes along), which
+ * types every member and checks the id and version against it. Or type just the tools, with an
+ * interface of function signatures (`IHttpConsumer["tools"]`) or tool declarations
+ * (`{ refresh: typeof refreshTool }`). A member named `then`, `toJSON`, `toString`, `valueOf`,
+ * or `constructor` needs `ctx.callConsumedTool` (or `callConsumedTable`) instead.
+ *
+ * @param contractId - The contract's id.
+ * @param version - The contract's version.
+ */
+export declare function contractRef<T = AnyContractTools>(contractId: ContractIdOf<T>, version: ContractVersionOf<T>): IContractRef<T>;
+/**
+ * Make a contract reference with extra properties (a declaration's members, say). Not part of
+ * the public API: use {@link contractRef} or `declareContract`.
+ *
+ * @internal
+ * @param contractId - The contract's id.
+ * @param version - The contract's version.
+ * @param extra - Properties to add to the reference.
+ */
+export declare function createContractRef<T, X extends object = object>(contractId: string, version: number, extra: X): IContractRef<T> & X;
+export {};

package/dist/define/contract-ref.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractRef = contractRef;
+exports.createContractRef = createContractRef;
+const lazy_members_1 = require("./lazy-members");
+const table_handle_1 = require("./table-handle");
+const wire_value_1 = require("./wire-value");
+/**
+ * Reference a contract by id and version. Declare it with `pkg.consumes(ref)` when another
+ * package provides it, then call it from a handler: `await Http(ctx).tools.request({ ... })`.
+ *
+ * Type it with the contract (`contractRef<typeof News>(contractId, version)`, where `News` is
+ * from `defineContract` or `declareContract`; import it with `import type` so no handler code comes along), which
+ * types every member and checks the id and version against it. Or type just the tools, with an
+ * interface of function signatures (`IHttpConsumer["tools"]`) or tool declarations
+ * (`{ refresh: typeof refreshTool }`). A member named `then`, `toJSON`, `toString`, `valueOf`,
+ * or `constructor` needs `ctx.callConsumedTool` (or `callConsumedTable`) instead.
+ *
+ * @param contractId - The contract's id.
+ * @param version - The contract's version.
+ */
+function contractRef(contractId, version) {
+    return createContractRef(contractId, version, {});
+}
+/**
+ * Make a contract reference with extra properties (a declaration's members, say). Not part of
+ * the public API: use {@link contractRef} or `declareContract`.
+ *
+ * @internal
+ * @param contractId - The contract's id.
+ * @param version - The contract's version.
+ * @param extra - Properties to add to the reference.
+ */
+function createContractRef(contractId, version, extra) {
+    if (typeof contractId !== "string" || contractId.trim() === "") {
+        throw new Error("contractRef requires a contractId");
+    }
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`contractRef version must be a positive integer, got ${version}`);
+    }
+    const client = (ctx, options = {}) => {
+        const { providerPackageId } = options ?? {};
+        if (providerPackageId !== undefined &&
+            (typeof providerPackageId !== "string" || providerPackageId.trim() === "")) {
+            throw new Error("providerPackageId must be a non-empty package id");
+        }
+        // Options go only when a provider is chosen: the bridge would carry `undefined` as null.
+        const provider = providerPackageId
+            ? [{ providerPackageId }]
+            : [];
+        const label = `${contractId}@${version}`;
+        // Arguments go as the bridge carries them: a field left undefined is omitted.
+        const tools = (0, lazy_members_1.lazyMembers)((toolName) => (args) => ctx.callConsumedTool(contractId, version, toolName, args === undefined ? args : (0, wire_value_1.snapshotPackageValue)(args), ...provider));
+        const tables = (0, lazy_members_1.lazyMembers)((tableName) => (0, table_handle_1.packageTableMethods)((operation, args) => {
+            if (providerPackageId) {
+                throw new Error(`Table calls on ${label} can't pick a provider; call ${tableName} without providerPackageId`);
+            }
+            return ctx.callConsumedTable(contractId, version, tableName, operation, args);
+        }));
+        const observables = (0, lazy_members_1.lazyMembers)((observableName) => Object.freeze({
+            get: () => ctx.getConsumedObservable(contractId, version, observableName, ...provider),
+            set: (value) => ctx.setConsumedObservable(contractId, version, observableName, value === undefined ? value : (0, wire_value_1.snapshotPackageValue)(value), ...provider),
+        }));
+        return Object.freeze({ tools, tables, observables });
+    };
+    return Object.freeze(Object.assign(client, { ...extra, kind: "contract-ref", contractId, version }));
+}

package/dist/define/declare-contract.d.ts

@@ -0,0 +1,167 @@
+import type { InvariantObservable, Observable } from "../observable";
+import type { IPackageContext } from "./context";
+import { type ContractMembersOf, type IContractRef } from "./contract-ref";
+import { type AlsoImplementsTarget, type IContractMembers, type IPackageContract, type PackageContractEvent, type PackageContractObservableDeclaration } from "./define-package";
+import { type IPackageObservable, type IPackageObservableDeclaration } from "./observables";
+import type { IPackageTable } from "./table";
+import { type IPackageTool, type IPackageToolDeclaration } from "./tool";
+/** What {@link declareContract} takes. Omitted member lists are empty. */
+export interface IContractDeclarationDefinition<Id extends string = string, V extends number = number, Tables extends readonly IPackageTable<any>[] = readonly IPackageTable<any>[], Tools extends readonly IPackageToolDeclaration<any, any>[] = readonly IPackageToolDeclaration<any, any>[], Observables extends readonly IPackageObservableDeclaration<any>[] = readonly IPackageObservableDeclaration<any>[], Events extends readonly PackageContractEvent[] = readonly PackageContractEvent[]> {
+    /** The contract's id, from `newid()`. */
+    contractId: Id;
+    /** The contract's version, a positive integer. */
+    version: V;
+    /** Human-readable name. */
+    name: string;
+    /** What the contract is for. */
+    description?: string;
+    /** Tables the contract exposes, from `defineTable` (without a `tableClass`). */
+    tables?: Tables;
+    /** Tools the contract provides, from `declareTool`. */
+    tools?: Tools;
+    /** Observables the contract exposes, from `declareObservable`. */
+    observables?: Observables;
+    /** Events the contract may emit, from `defineEvent`. */
+    events?: Events;
+}
+/** A declaration's members: a contract's shape with no handlers or sources. */
+export interface IContractDeclarationMembers<Id extends string = string, V extends number = number, Tables extends readonly IPackageTable<any>[] = readonly IPackageTable<any>[], Tools extends readonly IPackageToolDeclaration<any, any>[] = readonly IPackageToolDeclaration<any, any>[], Observables extends readonly PackageContractObservableDeclaration[] = readonly PackageContractObservableDeclaration[], Events extends readonly PackageContractEvent[] = readonly PackageContractEvent[]> extends IContractMembers<Id, V, Tables, Tools, Observables, Events> {
+    /** Marks a declaration's members. */
+    readonly kind: "contract-declaration";
+}
+/**
+ * A contract declared with {@link declareContract}: its shape, with no handlers, and a
+ * reference to it. Consumers use it as the reference (`pkg.consumes(VoiceSkill)`,
+ * `VoiceSkill(ctx).tools.invoke(...)`, `hostContract(VoiceSkill)`); a provider implements it
+ * with {@link implementContract}. It holds no package code, so it's safe to import or copy.
+ */
+export type IContractDeclaration<Id extends string = string, V extends number = number, Tables extends readonly IPackageTable<any>[] = readonly IPackageTable<any>[], Tools extends readonly IPackageToolDeclaration<any, any>[] = readonly IPackageToolDeclaration<any, any>[], Observables extends readonly PackageContractObservableDeclaration[] = readonly PackageContractObservableDeclaration[], Events extends readonly PackageContractEvent[] = readonly PackageContractEvent[]> = IContractRef<IContractDeclarationMembers<Id, V, Tables, Tools, Observables, Events>> & {
+    /** The declared contract's id, preserving its literal type. */
+    readonly contractId: Id;
+    /** The declared contract's version, preserving its literal type. */
+    readonly version: V;
+    /** The contract's members, as declared. */
+    readonly declaration: IContractDeclarationMembers<Id, V, Tables, Tools, Observables, Events>;
+};
+/** A member's name, from its definition. */
+type MemberName<M> = M extends {
+    definition: {
+        name: infer N extends string;
+    };
+} ? N : never;
+/** A tool's handler: the parsed input in, the output (or a promise of it) back. */
+export type ContractToolHandler<T> = T extends IPackageToolDeclaration<any, infer O, any, infer P> ? (args: P, ctx: IPackageContext) => O | Promise<O> : never;
+/**
+ * How a provider implements one declared tool: its handler, or the handler with this
+ * provider's deadline (`timeoutMs`, at most 120 000).
+ */
+export type ContractToolImplementation<T> = ContractToolHandler<T> | {
+    handler: ContractToolHandler<T>;
+    timeoutMs?: number;
+};
+/**
+ * What holds a declared observable's value: a package variable (`deviceVar`, `groupVar`, …)
+ * or an `observable()`, whose value fits the declared schema. A writable source must also
+ * accept every value consumers may write; a read-only source may have a narrower value type.
+ */
+export type ContractObservableSource<T> = T extends IPackageObservableDeclaration<infer V, any, infer W> ? true extends W ? InvariantObservable<V> : Observable<any> & (() => V) : never;
+type ImplementationTools<Tools extends readonly unknown[]> = [Tools[number]] extends [never] ? {
+    tools?: Record<string, never>;
+} : {
+    tools: {
+        [K in Tools[number] as MemberName<K>]: ContractToolImplementation<K>;
+    };
+};
+type ImplementationObservables<Observables extends readonly unknown[]> = [
+    Observables[number]
+] extends [never] ? {
+    observables?: Record<string, never>;
+} : {
+    observables: {
+        [K in Observables[number] as MemberName<K>]: ContractObservableSource<K>;
+    };
+};
+/**
+ * A contract a provider can expose through a hub's contract: one it also provides (from
+ * `defineContract` or `implementContract`), or that contract's reference.
+ */
+export interface IExposableContract {
+    /** The contract's id. */
+    readonly contractId: string;
+    /** The contract's version. */
+    readonly version: number;
+}
+/** The part of an implementation any declaration accepts: what it exposes and also implements. */
+interface ImplementationExposes {
+    /**
+     * Other contracts this package provides whose tools the hub contract's consumers may call on
+     * this provider, without consuming them. For a hub's contract, such as Voice Skill.
+     */
+    exposes?: readonly IExposableContract[];
+    /**
+     * Older versions of the declared contract (by number) or other contracts (by declaration)
+     * whose consumers this implementation also serves; see {@link AlsoImplementsTarget}.
+     */
+    alsoImplements?: readonly AlsoImplementsTarget[];
+}
+/**
+ * What {@link implementContract} takes for a declaration: a handler for every declared tool and
+ * a source for every declared observable, by name, and optionally the contracts it exposes and
+ * the versions it also implements.
+ * Tables and events need nothing.
+ */
+export type ContractImplementation<D> = ContractMembersOf<D> extends IContractMembers<any, any, any, infer Tools, infer Observables, any> ? ImplementationTools<Tools> & ImplementationObservables<Observables> & ImplementationExposes : never;
+/** Declared tools, each with its handler. */
+type ImplementedTools<Tools extends readonly unknown[]> = {
+    [K in keyof Tools]: Tools[K] extends IPackageToolDeclaration<infer I, infer O, infer N, infer P> ? IPackageTool<I, O, N, P> : never;
+};
+/** Declared observables, each with its source. */
+type ImplementedObservables<Observables extends readonly unknown[]> = {
+    [K in keyof Observables]: Observables[K] extends IPackageObservableDeclaration<infer V, infer N, infer W> ? IPackageObservable<V, N, W> : never;
+};
+/** The contract {@link implementContract} makes from a declaration. */
+export type ImplementedContract<D> = ContractMembersOf<D> extends IContractMembers<infer Id, infer V, infer Tables, infer Tools, infer Observables, infer Events> ? IPackageContract<Id, V, Tables, ImplementedTools<Tools> extends readonly IPackageTool<any, any>[] ? ImplementedTools<Tools> : never, ImplementedObservables<Observables> extends readonly IPackageObservable<any>[] ? ImplementedObservables<Observables> : never, Events> : never;
+/**
+ * Declare a contract's shape without providing it: its id, version, name, and the tables,
+ * tools, observables, and events it exposes, with no handlers. Use it for a contract several
+ * packages implement (Voice Skill, which every skill provides). Each provider implements it
+ * with {@link implementContract}; consumers use the declaration itself as the reference.
+ *
+ * Tools come from `declareTool` and observables from `declareObservable`: `defineTool` and
+ * `defineObservable` without the handler or source. Events (`defineEvent`) and tables
+ * (`defineTable`) are listed as they are; a table can't have a `tableClass` here.
+ *
+ * @param definition - Id, version, name, description, and members.
+ */
+export declare function declareContract<Id extends string, V extends number, Tables extends readonly IPackageTable<any>[] = [], Tools extends readonly IPackageToolDeclaration<any, any>[] = [], Observables extends readonly IPackageObservableDeclaration<any>[] = [], Events extends readonly PackageContractEvent[] = []>(definition: IContractDeclarationDefinition<Id, V, Tables, Tools, Observables, Events>): IContractDeclaration<Id, V, Tables, Tools, Observables, Events>;
+/**
+ * Implement a declared contract: a handler for each of its tools and a source for each of its
+ * observables, by name. Returns the contract for `pkg.provides`, as {@link defineContract}
+ * would; its manifest shape comes from the declaration, so it can't drift from it.
+ *
+ * ```ts
+ * export const TimersVoiceSkill = implementContract(VoiceSkill, {
+ *   tools: { invoke: async ({ tool, args }, ctx) => ({ speech: "Done." }) },
+ *   observables: { skill: deviceVar<VoiceSkillCatalog>("skill", { defaultValue: catalog }) },
+ * });
+ * pkg.provides(TimersVoiceSkill);
+ * ```
+ *
+ * A tool's entry may also set this provider's deadline: `{ handler, timeoutMs }`. The
+ * declaration's events are emitted with their own `emit`.
+ *
+ * For a hub's contract, `exposes` lists other contracts the package provides whose tools the
+ * hub contract's consumers may call on this provider: `exposes: [News]`. Each must also be in
+ * `pkg.provides`. The hub reaches only their tools, each at its own access level, as the user.
+ *
+ * @param declaration - From {@link declareContract}.
+ * @param implementation - Handlers and sources, by member name, and the contracts it exposes.
+ */
+export declare function implementContract<D extends IContractDeclaration<any, any, any, any, any, any>>(declaration: D, implementation: ContractImplementation<NoInfer<D>>): ImplementedContract<D>;
+/**
+ * True for a declaration from {@link declareContract}.
+ *
+ * @param value - A contract reference, contract, or anything else.
+ */
+export declare function isContractDeclaration(value: unknown): value is IContractDeclaration;
+export {};