@peers-app/peers-sdk 0.28.6 → 0.28.8

package/README.md

@@ -32,7 +32,7 @@ NaCl-based key management, message signing and verification, box encryption, and
 
 ### Tools Framework
 
-Define AI-callable tools with `ITool` and `IToolInstance`. Tools are registered at runtime and available to built-in and user-defined AI assistants and workflows.
+Declare AI-callable tools with `definePackage()` and provide their implementations through contract resolvers. Use `IContractToolImplementation` for provider implementations.
 
 ### Identity and Groups
 
@@ -58,7 +58,7 @@ The fastest way to build a Peers package is to start from the template:
 | `DataQuery` / `DataFilter`           | Mongo-style query filters translated to SQL                             |
 | `observable()` / `computed()`        | Reactive state primitives                                               |
 | `deviceVar` / `userVar` / `groupVar` | Persistent variables — observables backed by the database               |
-| `ITool` / `IToolInstance`            | AI-callable tool definitions                                            |
+| `ITool` / `IContractToolImplementation`            | AI-callable tool definitions                                            |
 | `IPeersUI` / `IPeersUIRoute`         | Screen and route declarations for package UIs                           |
 | `newid()`                            | Generate 25-character time-sortable peer IDs                            |
 | `newKeys()` / `hydrateKeys()`        | Cryptographic key pair generation and hydration                         |

package/dist/contracts/builder.d.ts

@@ -18,7 +18,6 @@ export declare class ContractBuilder {
     private _events;
     private _alsoImplements;
     private _exposes;
-    private warnedAboutToolInstances;
     /** Full table definitions for this contract (used by the install flow). */
     private _tableDefinitions;
     constructor(contractId: string, version: number, name: string, description?: string | undefined);
@@ -35,11 +34,6 @@ export declare class ContractBuilder {
      */
     set events(events: IContractEvent[]);
     get events(): IContractEvent[];
-    /**
-     * Discard executable assignments from bundles compiled against an older SDK.
-     * @deprecated Implement tools with registerContractResolver instead.
-     */
-    set toolInstances(_instances: never);
     /** Full table definitions for runtime table registration. */
     set tableDefinitions(defs: ITableDefinition[]);
     get tableDefinitions(): ITableDefinition[];

package/dist/contracts/builder.js

@@ -26,7 +26,6 @@ class ContractBuilder {
     _events = [];
     _alsoImplements = [];
     _exposes = [];
-    warnedAboutToolInstances = false;
     /** Full table definitions for this contract (used by the install flow). */
     _tableDefinitions = [];
     constructor(contractId, version, name, description) {
@@ -64,16 +63,6 @@ class ContractBuilder {
     get events() {
         return this._events;
     }
-    /**
-     * Discard executable assignments from bundles compiled against an older SDK.
-     * @deprecated Implement tools with registerContractResolver instead.
-     */
-    set toolInstances(_instances) {
-        if (this.warnedAboutToolInstances)
-            return;
-        this.warnedAboutToolInstances = true;
-        console.warn(`Contract ${this.name} (${this.contractId}@${this.version}) assigned toolInstances, which no longer run; implement these tools with registerContractResolver (docs/Packages/contracts.md#migrating-from-toolinstances)`);
-    }
     /** Full table definitions for runtime table registration. */
     set tableDefinitions(defs) {
         this._tableDefinitions = defs;

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

@@ -1,6 +1,7 @@
+import type { z } from "zod";
 import type { DataContext } from "../context/data-context";
 import type { Table } from "../data/orm/table";
-import type { ITool, IToolInstance } from "../data/tools";
+import type { ITool } from "../data/tools";
 import type { Event, ISubscriptionResult } from "../events";
 import { type Observable } from "../observable";
 import { type IIsolatedCallPrincipal } from "../package-loader/isolated-runtime";
@@ -359,15 +360,15 @@ export declare function createRemoteContractConsumer(contract: IContractDefiniti
     dataContextId?: string;
 }): IRemoteContractConsumer<IContractConsumer>;
 /**
- * Provider-local executable metadata. Existing IToolInstance values remain assignable;
- * new implementations need no catalog ID, persisted row, or executable registration.
+ * Provider-local executable metadata for contract tools.
+ * Implementations need no catalog ID, persisted row, or executable registration.
  */
 export interface IContractToolImplementation {
     /** Provider metadata; the contract member name supplies identity, without a Tools row. */
     tool: Pick<ITool, "name" | "usageDescription"> & Partial<Pick<ITool, "toolId" | "detailedDescription" | "inputSchema" | "outputSchema" | "accessLevel" | "authorityPropagation" | "remoteAccessLevel">>;
-    toolFn: IToolInstance["toolFn"];
-    inputSchema?: IToolInstance["inputSchema"];
-    outputSchema?: IToolInstance["outputSchema"];
+    toolFn: (...args: any[]) => any;
+    inputSchema?: z.ZodObject<any>;
+    outputSchema?: z.ZodObject<any>;
 }
 /** Context-bound live members of a provider; executable ownership stays with the contract. */
 export interface IContractResolution {

package/dist/contracts/extract.d.ts

@@ -18,7 +18,7 @@ export interface IExtractableTableDef {
 }
 /**
  * Minimal tool-instance shape accepted by extractToolShape.
- * Mirrors the subset of IToolInstance we need.
+ * Mirrors the subset of IContractToolImplementation we need.
  */
 export interface IExtractableToolInstance {
     /** Host-only workflow policy carried into the contract definition. */

package/dist/contracts/system/contract-catalog-contract.d.ts

@@ -71,6 +71,12 @@ export interface IContractDefinitionWithPolicy {
     definition: IContractDefinition;
     /** Each tool's policy, where the Runtime knows it. */
     tools?: IContractToolPolicy[];
+    /** Active provider's table settings, when known; absent on older hosts. */
+    tables?: {
+        name: string;
+        versionNumber?: number;
+        localOnly?: boolean;
+    }[];
 }
 /**
  * Consumer shape for the System Contract Catalog.

package/dist/contracts/system/contract-catalog-contract.js

@@ -47,6 +47,7 @@ function getContractCatalogDefinition() {
                 outputFields: [
                     field("definition", field_type_1.FieldType.object, "The registered definition, in Peers IR."),
                     field("tools", field_type_1.FieldType.object, "Each tool's name, accessLevel, and authorityPropagation on the active provider.", { isArray: true, optional: true }),
+                    field("tables", field_type_1.FieldType.object, "Each table's name, versionNumber, and localOnly setting on the active provider.", { isArray: true, optional: true }),
                 ],
             },
         ],

package/dist/contracts/system/packages-contract.d.ts

@@ -42,6 +42,8 @@ export interface IPackageObservedRuntime {
 export interface IPackageRequestedVersion {
     /** Group-wide active version (`Packages.activePackageVersionId`). */
     groupActivePackageVersionId?: string;
+    /** The group selected a version whose row is not on this device yet. */
+    groupVersionMissing?: boolean;
     /** This device's override, when set. */
     deviceActivePackageVersionId?: string;
     /** The version this device should run: the device override, else the group version. */
@@ -101,8 +103,8 @@ export interface IPackageOperationResult {
     /** True when `createPackage` scaffolded a new package instead of importing an existing folder. */
     created?: boolean;
     /**
-     * Non-fatal problem the caller should show: for example a missing package template, or a
-     * reloaded dev build that reuses a released version number and should be bumped.
+     * Non-fatal problem the caller should show, for example a missing package template.
+     * Older hosts also report released-number conflicts here instead of refusing reload.
      */
     warning?: string;
     /** The package after the operation. */
@@ -120,7 +122,7 @@ export interface IPackageReloadOutcome {
     changed?: boolean;
     /** Failure message when `ok` is false. */
     error?: string;
-    /** Non-fatal problem, such as a dev build that reuses a released version number. */
+    /** Non-fatal problem; older hosts may warn here about a reused released number. */
     warning?: string;
 }
 /** Result of `reloadAllPackages`. */
@@ -141,11 +143,19 @@ export interface IPromotePackageVersionResult extends IPackageOperationResult {
     /** True when this device holds the package signing key and signed the promoted version. */
     signed: boolean;
     /**
-     * True when the version this device was running now matches the group's follow policy
-     * and was activated, for the group unless this device overrides group settings.
+     * True when activation ran, either explicitly with activateForGroup or automatically
+     * under the group follow policy. See groupRunsPromotedVersion for the group outcome.
      */
     activated: boolean;
+    /** Group selection after promotion, when one is set. */
+    groupActivePackageVersionId?: string;
+    /** True even when the group already selected this id before it was re-tagged. */
+    groupRunsPromotedVersion?: boolean;
+    /** What the group now runs, why selection stayed unchanged, and any next command. */
+    activationNote?: string;
 }
+/** Explain a group version missing locally and how to select an available release. */
+export declare function packageGroupVersionWarning(packageId: string, requested: Pick<IPackageRequestedVersion, "groupActivePackageVersionId" | "groupVersionMissing">): string | undefined;
 /**
  * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
  * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
@@ -207,7 +217,7 @@ export interface IPackagesConsumer extends IContractConsumerBase {
             packageVersionId?: string;
             scope?: "device" | "group";
         }): Promise<IPackageOperationResult>;
-        /** Rebuild the dev version from disk when it changed, then force-reload the package. */
+        /** Read local bundles, then force-reload the selected version even when unchanged. */
         reloadPackage(input: {
             packageId: string;
         }): Promise<IPackageOperationResult>;
@@ -228,10 +238,13 @@ export interface IPackagesConsumer extends IContractConsumerBase {
          * Promote a stored version to `beta` or `stable`: re-tag, re-sign with the package author
          * key when this device has it, record the promotion in the version's history, and
          * activate it when this device was running it and the group follows the new tag.
+         * activateForGroup explicitly selects it for the group and follows that selection here.
          */
         promotePackageVersion(input: {
             packageVersionId: string;
             versionTag: string;
+            /** Also select the promoted version for the group and follow it here (Admin). */
+            activateForGroup?: boolean;
         }): Promise<IPromotePackageVersionResult>;
         /** Install the default packages into the bound data context. */
         installDefaultPackages(): Promise<{

package/dist/contracts/system/packages-contract.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PACKAGES_CONTRACT_VERSION = void 0;
+exports.packageGroupVersionWarning = packageGroupVersionWarning;
 exports.packageVersionPromotionTargets = packageVersionPromotionTargets;
 exports.isPackageRepositoryUrl = isPackageRepositoryUrl;
 exports.getPackagesContractDefinition = getPackagesContractDefinition;
@@ -9,6 +10,12 @@ const field_type_1 = require("../../types/field-type");
 const system_contracts_1 = require("../system-contracts");
 /** Version of the built-in System Packages contract. */
 exports.PACKAGES_CONTRACT_VERSION = 1;
+/** Explain a group version missing locally and how to select an available release. */
+function packageGroupVersionWarning(packageId, requested) {
+    if (!requested.groupVersionMissing || !requested.groupActivePackageVersionId)
+        return undefined;
+    return `The group's selected version ${requested.groupActivePackageVersionId} isn't on this device; it may not have synced yet. To select an available beta or stable version for the group, run: peers packages activate ${packageId} <packageVersionId> --group`;
+}
 /**
  * Release channels a version may be promoted to from its current tag: `dev` to `beta` or
  * `stable`, and `beta` to `stable`. Missing or empty tags on legacy versions mean `dev`,
@@ -138,7 +145,7 @@ function getPackagesContractDefinition() {
             },
             {
                 name: "reloadPackage",
-                usageDescription: "Rebuild the dev version from the package folder when it changed, then force-reload the package on this device.",
+                usageDescription: "Read local bundles, then force-reload the selected version even when unchanged. Changed builds at a released number are refused.",
                 inputFields: [packageIdField],
                 outputFields: operationResultFields,
             },
@@ -170,10 +177,11 @@ function getPackagesContractDefinition() {
             },
             {
                 name: "promotePackageVersion",
-                usageDescription: "Promote a stored package version to beta or stable (dev to beta or stable, beta to stable). Re-signs it with the package author key when this device has it, records the promotion in its history, and activates it when this device was running it and the group follows the new tag.",
+                usageDescription: "Promote a stored package version to beta or stable (dev to beta or stable, beta to stable). Re-signs it with the package author key when this device has it, records the promotion in its history, and activates it when this device was running it and the group follows the new tag. Optionally selects it for the group with activateForGroup. Reports the group selection and any next command.",
                 inputFields: [
                     field("packageVersionId", field_type_1.FieldType.id, "Version to promote."),
                     field("versionTag", field_type_1.FieldType.string, "New release channel: beta or stable."),
+                    field("activateForGroup", field_type_1.FieldType.boolean, "Also select this version for the group and follow it here (Admin).", { optional: true }),
                 ],
                 outputFields: [
                     ...operationResultFields,
@@ -181,6 +189,11 @@ function getPackagesContractDefinition() {
                     field("version", field_type_1.FieldType.string, "Its version number."),
                     field("versionTag", field_type_1.FieldType.string, "Its new release channel."),
                     field("signed", field_type_1.FieldType.boolean, "True when this device signed the promoted version."),
+                    field("groupActivePackageVersionId", field_type_1.FieldType.id, "Group selection after promotion.", {
+                        optional: true,
+                    }),
+                    field("groupRunsPromotedVersion", field_type_1.FieldType.boolean, "Whether the group now selects the promoted version, including an already-selected id.", { optional: true }),
+                    field("activationNote", field_type_1.FieldType.string, "What the group now runs and any next command.", { optional: true }),
                     field("activated", field_type_1.FieldType.boolean, "True when the promotion also activated the version for the group or this device."),
                 ],
             },

package/dist/data/package-version-resolver.js

@@ -18,14 +18,12 @@ exports.hasDeviceFollowOverride = hasDeviceFollowOverride;
 exports.readStoredPackageLocalPath = readStoredPackageLocalPath;
 const user_context_singleton_1 = require("../context/user-context-singleton");
 const keys_1 = require("../keys");
-const assistants_1 = require("./assistants");
 const file_types_1 = require("./files/file.types");
 const group_member_roles_1 = require("./group-member-roles");
 const group_permissions_1 = require("./group-permissions");
 const package_versions_1 = require("./package-versions");
 const packages_1 = require("./packages");
 const persistent_vars_1 = require("./persistent-vars");
-const workflows_1 = require("./workflows");
 /**
  * Reactive, cached observable holding device-local preferences for a single
  * package. Backed by a `groupDeviceVar` so the UI can subscribe via
@@ -344,9 +342,7 @@ async function resolveDevicePackageVersion(pkg, dataContext, opts) {
         }
         return { loaded: false, upgraded: false };
     }
-    // Load succeeded - install assistants/workflows, then persist the activation
-    // either as a group-level active version or as device-local state.
-    await installPackageContents(dataContext, pkg, instance);
+    // Load succeeded; persist activation as a group default or device-local state.
     // When the device is following group settings (no device-level follow
     // override) and the upgraded version is non-dev, also advance the group's
     // activePackageVersionId so other devices stay in sync. Only admin+ users
@@ -436,20 +432,6 @@ async function loadOlderCompatiblePackageVersion(pkg, dataContext, unavailableVe
     }
     return undefined;
 }
-/**
- * Save a loaded package's assistants and workflows into the data context.
- * Contract-installed packages are skipped because their content is already
- * managed by the contract loader.
- */
-async function installPackageContents(dataContext, pkg, instance) {
-    if (dataContext.packageLoader.isContractInstalled(pkg.packageId))
-        return;
-    const saves = [
-        ...(instance.assistants?.map((a) => (0, assistants_1.Assistants)(dataContext).save(a)) ?? []),
-        ...(instance.workflows?.map((w) => (0, workflows_1.Workflows)(dataContext).save(w)) ?? []),
-    ];
-    await Promise.all(saves);
-}
 /**
  * Returns true when the device has an explicit follow-policy override
  * (`followRange`, `followTags`, or `pinned`). Used by the UI to drive the

package/dist/data/package-versions.d.ts

@@ -115,6 +115,10 @@ declare const schema: z.ZodObject<{
 }>;
 /** A signed package build and its bundle hashes, tag, and lifecycle history. */
 export type IPackageVersion = z.infer<typeof schema>;
+/** Find a beta or stable build with the same package and version number, excluding a supplied id. */
+export declare function releasedVersionWithNumber(versions: readonly IPackageVersion[], candidate: Pick<IPackageVersion, "packageId" | "version"> & {
+    packageVersionId?: string;
+}): IPackageVersion | undefined;
 /** Package version table with signature and group promotion permission checks. */
 export declare class PackageVersionsTable extends Table<IPackageVersion> {
     static isPassthrough: boolean;

package/dist/data/package-versions.js

@@ -35,6 +35,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PackageVersionsTable = void 0;
+exports.releasedVersionWithNumber = releasedVersionWithNumber;
 exports.PackageVersions = PackageVersions;
 exports.computePackageVersionHash = computePackageVersionHash;
 exports.isVersionInRange = isVersionInRange;
@@ -100,6 +101,13 @@ const metaData = {
     fields: (0, types_1.schemaToFields)(schema),
     indexes: [{ fields: ["packageId"] }],
 };
+/** Find a beta or stable build with the same package and version number, excluding a supplied id. */
+function releasedVersionWithNumber(versions, candidate) {
+    return versions.find((other) => other.packageId === candidate.packageId &&
+        other.packageVersionId !== candidate.packageVersionId &&
+        other.version === candidate.version &&
+        (other.versionTag === "beta" || other.versionTag === "stable"));
+}
 // Symbol.for keeps signer registration shared by separately installed SDK copies.
 const signingKey = Symbol.for("@peers-app/peers-sdk/package-version-signing");
 const signingGlobals = globalThis;

package/dist/data/packages.utils.d.ts

@@ -1,3 +1,7 @@
 import type { DataContext } from "../context/data-context";
 import { type IPackage } from "./packages";
+/**
+ * Copy a package and its active version's bundles into another context.
+ * Restores an uninstalled package; uninstall keeps version and file rows.
+ */
 export declare function copyPackageToAnotherDataContext(packageId: string, fromDataContext: DataContext, toDataContext: DataContext): Promise<IPackage>;

package/dist/data/packages.utils.js

@@ -15,6 +15,10 @@ async function copyBundleFile(fileId, fromFiles, toFiles, label) {
         console.warn(`${label} file ${fileId} not found in source context`);
     }
 }
+/**
+ * Copy a package and its active version's bundles into another context.
+ * Restores an uninstalled package; uninstall keeps version and file rows.
+ */
 async function copyPackageToAnotherDataContext(packageId, fromDataContext, toDataContext) {
     const fromPackages = (0, packages_1.Packages)(fromDataContext);
     const toPackages = (0, packages_1.Packages)(toDataContext);
@@ -35,5 +39,5 @@ async function copyPackageToAnotherDataContext(packageId, fromDataContext, toDat
             await toPvTable.signAndSave(pv, { saveAsSnapshot: true });
         }
     }
-    return toPackages.signAndSave(pkg);
+    return toPackages.signAndSave(pkg, { restoreIfDeleted: true, saveAsSnapshot: true });
 }

package/dist/data/tools.d.ts

@@ -172,16 +172,6 @@ export declare const toolSchema: z.ZodObject<{
 }>;
 /** A tool definition stored in the Tools table. */
 export type ITool = z.infer<typeof toolSchema>;
-/**
- * Historical tool instance shape used by older packages.
- * @deprecated Use IContractToolImplementation with a contract resolver.
- */
-export interface IToolInstance {
-    tool: ITool;
-    toolFn: (...args: any[]) => any;
-    inputSchema?: z.ZodObject<any>;
-    outputSchema?: z.ZodObject<any>;
-}
 /**
  * Accessor for the Tools table.
  *

package/dist/define/context.d.ts

@@ -14,7 +14,7 @@ export interface IPackageProviderOptions {
     providerPackageId?: string;
 }
 /**
- * The host functions the Runtime gives one handler call (guest API 2 and 3).
+ * The host functions the Runtime gives one guest API 3 handler call.
  *
  * 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
@@ -75,15 +75,13 @@ export interface IPackageContext {
     watchOwnedTable(tableName: string, handler: (event: IDataChangedEvent<unknown>) => 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.
+     * `persistentVar`). The host checks it against the observable's `valueType` 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.
+     * Compatibility no-op retained for built guest API 3 bundles. Consumer writes are
+     * served 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/observables.js

@@ -162,8 +162,7 @@ async function serveObservable(observable, targets, ctx) {
     });
     serving.set(observable, () => subscription.dispose());
     if (definition.writable) {
-        // Guest API 3 calls this from its member handler under the caller's authority; guest
-        // API 2 uses onOwnedObservableSet without a caller frame. Both parse before writing.
+        // The member handler runs this under the caller's authority and parses before writing.
         const write = async (value) => {
             const next = schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, value)) : value;
             applying = true;
@@ -177,9 +176,6 @@ async function serveObservable(observable, targets, ctx) {
             return publish(source());
         };
         writers.set(observable, write);
-        for (const target of targets) {
-            ctx.onOwnedObservableSet(target.contractId, target.version, name, write);
-        }
     }
     // A successful start guarantees readers have a published value. Later background failures
     // are logged, but a failed initial publish must fail startup rather than silently serve null.

package/dist/package-build/cli.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const node_fs_1 = require("node:fs");
 const path = require("node:path");
+const sdk_version_1 = require("../sdk-version");
 const build_package_1 = require("./build-package");
 const contract_add_1 = require("./contract-add");
 const freeze_contracts_1 = require("./freeze-contracts");
@@ -11,7 +12,7 @@ const USAGE = `Usage: peers-package <command> [options]
 Commands:
   manifest              Write dist/manifest.json from the package's declarations (src/package.ts).
   build                 Write the manifest and dist/package.bundle.js, the artifact the Runtime
-                        installs.
+                        installs. Prints the SDK version used to build it.
   contract add <source> Write src/contracts/<name>.v<version>.ts, a declaration of a contract this
                         package implements or calls, generated from <source>: a declaration module
                         and its export (path/to/file.ts#Name), a provider's manifest.json or
@@ -96,13 +97,13 @@ async function main(argv) {
                 console.error(`Build failed: ${result.message}`);
                 return;
             }
-            console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+            console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; SDK ${sdk_version_1.SDK_VERSION}; provider ${Math.round(result.providerChars / 1024)} KB)`);
         });
         console.log("Watching for changes");
         return new Promise(() => undefined);
     }
     const result = await (0, build_package_1.buildPackage)(options);
-    console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; provider ${Math.round(result.providerChars / 1024)} KB)`);
+    console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; SDK ${sdk_version_1.SDK_VERSION}; provider ${Math.round(result.providerChars / 1024)} KB)`);
     return 0;
 }
 /** `peers-package contract add <source> [options]` or `peers-package contract freeze [options]`. */

package/dist/package-build/contract-add.d.ts

@@ -1,11 +1,13 @@
+import { type IContractSource } from "./contract-source";
 /** What {@link addContract} takes. */
 export interface IContractAddOptions {
     /**
      * Where the contract comes from: a declaration module and its export
      * (`../voice-hub/src/contracts/voice-skill.ts#VoiceSkill`), a provider's `manifest.json` or
-     * `package.bundle.js`, or the JSON `getContractDefinition` returned.
+     * `package.bundle.js`, the JSON `getContractDefinition` returned, or an in-memory
+     * contract source (for example from `contractSourceFromDefinition`).
      */
-    source: string;
+    source: string | IContractSource;
     /** `contractId@version`, for a manifest that provides more than one contract. */
     contract?: string;
     /** Package root. Defaults to the current directory. */

package/dist/package-build/contract-add.js

@@ -19,9 +19,10 @@ const contract_source_1 = require("./contract-source");
  */
 async function addContract(options) {
     const root = path.resolve(options.root ?? process.cwd());
-    const contract = await readContractSource(root, options);
+    const contract = typeof options.source === "string"
+        ? await readContractSource(root, { ...options, source: options.source })
+        : options.source;
     const generated = (0, contract_source_1.generateContractDeclaration)(contract, {
-        from: sourceLabel(root, options.source),
         ...(options.name ? { exportName: options.name } : {}),
     });
     const target = path.join(path.resolve(root, options.outDir ?? "src/contracts"), generated.fileName);
@@ -41,15 +42,6 @@ function splitSource(source) {
         ? { file: source.slice(0, hash), exportName: source.slice(hash + 1) }
         : { file: source };
 }
-/**
- * The source as the file's header names it: relative to the package root, with `/`, so the
- * generated file (and `--check`) doesn't depend on where the command ran or on local paths.
- */
-function sourceLabel(root, source) {
-    const { file, exportName } = splitSource(source);
-    const relative = path.relative(root, path.resolve(file)).split(path.sep).join("/");
-    return exportName === undefined ? relative : `${relative}#${exportName}`;
-}
 async function readContractSource(root, options) {
     const { file, exportName } = splitSource(options.source);
     if (exportName !== undefined) {

package/dist/package-build/contract-source.d.ts

@@ -49,11 +49,14 @@ export declare function parseContractSelector(selector: string): {
  * propagation. Refinements (a regex, a minimum) and defaults made by code aren't in the IR, so
  * generated schemas check only what the IR describes. Objects keep keys their fields don't list.
  *
+ * Table storage settings are preserved: implementing the declaration uses its tables.
+ * Default settings (schema version 1 and synced storage) are omitted.
+ *
  * @param input - The contract and its tables.
- * @param options - Where it came from (for the file's header), and an export name to use
- *   instead of the one made from the contract's name.
+ * @param options - An export name to use instead of the one made from the contract's name.
  */
-export declare function generateContractDeclaration(input: IContractSource, options: {
-    from: string;
+export declare function generateContractDeclaration(input: IContractSource, options?: {
+    /** Ignored for compatibility with older callers; generated headers never name a source. */
+    from?: string;
     exportName?: string;
 }): IGeneratedContractDeclaration;

package/dist/package-build/contract-source.js

@@ -67,6 +67,7 @@ function contractSourceFromDefinition(input) {
         throw new Error("Expected getContractDefinition's result: { definition, tools }");
     }
     const policy = new Map((input.tools ?? []).map((tool) => [tool.name, tool]));
+    const tablePolicy = new Map((input.tables ?? []).map((table) => [table.name, table]));
     const tools = definition.tools.map((tool) => {
         const toolPolicy = policy.get(tool.name);
         if (toolPolicy?.accessLevel === undefined) {
@@ -101,12 +102,17 @@ function contractSourceFromDefinition(input) {
             ...(definition.observables?.length ? { observables: definition.observables } : {}),
             ...(definition.events?.length ? { events: definition.events } : {}),
         },
-        tables: (definition.tables ?? []).map((table) => ({
-            name: table.name,
-            description: table.description,
-            primaryKeyName: table.primaryKeyName,
-            fields: table.fields,
-        })),
+        tables: (definition.tables ?? []).map((table) => {
+            const settings = tablePolicy.get(table.name);
+            return {
+                name: table.name,
+                description: table.description,
+                primaryKeyName: table.primaryKeyName,
+                fields: table.fields,
+                ...(settings?.versionNumber === undefined ? {} : { versionNumber: settings.versionNumber }),
+                ...(settings?.localOnly ? { localOnly: true } : {}),
+            };
+        }),
     };
 }
 /**
@@ -131,11 +137,13 @@ function parseContractSelector(selector) {
  * propagation. Refinements (a regex, a minimum) and defaults made by code aren't in the IR, so
  * generated schemas check only what the IR describes. Objects keep keys their fields don't list.
  *
+ * Table storage settings are preserved: implementing the declaration uses its tables.
+ * Default settings (schema version 1 and synced storage) are omitted.
+ *
  * @param input - The contract and its tables.
- * @param options - Where it came from (for the file's header), and an export name to use
- *   instead of the one made from the contract's name.
+ * @param options - An export name to use instead of the one made from the contract's name.
  */
-function generateContractDeclaration(input, options) {
+function generateContractDeclaration(input, options = {}) {
     const { contract, tables } = input;
     assertVersion(contract.version, "Contract version");
     const exportName = options.exportName ?? pascalCase(contract.name);
@@ -145,7 +153,7 @@ function generateContractDeclaration(input, options) {
     const imports = new Set(["declareContract"]);
     const code = new Code(imports);
     const lines = [];
-    lines.push(`// Generated by \`peers-package contract add\` from ${docText(options.from)}.`, "// Regenerate it rather than edit it; a stable package release freezes the contract's shape.", "");
+    lines.push(`// Generated contract declaration. Regenerate with \`peers contracts add ${docText(contract.contractId)}@${contract.version}\``, "// or `peers-package contract add <source>`; do not edit by hand.", "");
     const eventNames = new Map();
     for (const event of contract.events ?? []) {
         const name = uniqueName(`${camelCase(exportName)}${pascalCase(event.name)}`, new Set([...RESERVED_NAMES, exportName, ...eventNames.values()]));
@@ -223,7 +231,7 @@ class Code {
             ["description", JSON.stringify(table.description ?? "")],
             ["primaryKeyName", JSON.stringify(table.primaryKeyName)],
             ["schema", this.objectSchema(table.fields, depth + 1)],
-            ...(table.versionNumber === undefined
+            ...(table.versionNumber === undefined || table.versionNumber === 1
                 ? []
                 : [["versionNumber", String(table.versionNumber)]]),
             ...(table.localOnly ? [["localOnly", "true"]] : []),
@@ -237,7 +245,7 @@ class Code {
             ["name", JSON.stringify(tool.name)],
             ["usageDescription", JSON.stringify(tool.usageDescription)],
             ["accessLevel", this.accessLevel(level)],
-            ...(tool.authorityPropagation
+            ...(tool.authorityPropagation && tool.authorityPropagation !== "cap"
                 ? [["authorityPropagation", JSON.stringify(tool.authorityPropagation)]]
                 : []),
             ...(tool.remoteAccessLevel === undefined
@@ -323,7 +331,10 @@ class Code {
         return `generatedField(${schema}, ${this.shapeSource(metadata)}${valueType === undefined ? "" : `, ${this.fieldType(valueType)}`})`;
     }
     shapeSource(shape) {
-        const entries = Object.entries(shape).map(([key, value]) => {
+        const entries = Object.entries(shape)
+            .filter(([, value]) => value !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, value]) => {
             const source = key === "type"
                 ? this.fieldType(value)
                 : key === "fields"
@@ -422,6 +433,8 @@ function dataSource(value) {
         return `[${value.map(dataSource).join(", ")}]`;
     if (value && typeof value === "object") {
         return `{ ${Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
             .map(([key, entry]) => `${propertyKey(key)}: ${dataSource(entry)}`)
             .join(", ")} }`;
     }