@peers-app/peers-sdk 0.16.5 → 0.17.0

package/dist/contracts/persistent-registry.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistentContractRegistry = void 0;
+const utils_1 = require("../utils");
+const contract_providers_table_1 = require("./contract-providers.table");
+const contracts_table_1 = require("./contracts.table");
+const types_1 = require("./types");
+/**
+ * Bridges the in-memory `ContractRegistry` to SQLite-backed persistence tables.
+ * Handles persisting contract definitions and provider selections, as well as
+ * hydrating a fresh registry from stored data on startup.
+ */
+class PersistentContractRegistry {
+    registry;
+    dataContext;
+    constructor(registry, dataContext) {
+        this.registry = registry;
+        this.dataContext = dataContext;
+    }
+    /**
+     * Persist a contract definition and its provider to the database.
+     * If the definition already exists (same contractId), updates it.
+     * Creates or updates the provider record with the given active status.
+     */
+    async persist(definition, providerPackageId, isActive) {
+        const contractsTable = (0, contracts_table_1.Contracts)(this.dataContext);
+        const providersTable = (0, contract_providers_table_1.ContractProviders)(this.dataContext);
+        const existingContract = await contractsTable.findOne({ contractId: definition.contractId }, { enforceUnique: true });
+        const shape = JSON.stringify({
+            tables: definition.tables,
+            tools: definition.tools,
+            observables: definition.observables,
+        });
+        if (existingContract) {
+            await contractsTable.save({
+                ...existingContract,
+                devTag: definition.devTag,
+                name: definition.name,
+                description: definition.description,
+                shape,
+            });
+        }
+        else {
+            const record = {
+                contractId: definition.contractId,
+                version: definition.version,
+                devTag: definition.devTag,
+                name: definition.name,
+                description: definition.description,
+                shape,
+                registeredAt: new Date().toISOString(),
+            };
+            await contractsTable.save(record);
+        }
+        const existingProvider = await providersTable.findOne({
+            contractId: definition.contractId,
+            version: definition.version,
+            providerPackageId,
+        }, { enforceUnique: true });
+        if (existingProvider) {
+            await providersTable.save({ ...existingProvider, isActive });
+        }
+        else {
+            const providerRecord = {
+                contractProviderId: (0, utils_1.newid)(),
+                contractId: definition.contractId,
+                version: definition.version,
+                providerPackageId,
+                isActive,
+                registeredAt: new Date().toISOString(),
+            };
+            await providersTable.save(providerRecord);
+        }
+    }
+    /**
+     * Hydrate the in-memory registry from persisted definitions and providers.
+     * Registers all stored definitions with their respective providers, then
+     * sets the active provider for each contract.
+     */
+    async hydrate() {
+        const contractsTable = (0, contracts_table_1.Contracts)(this.dataContext);
+        const providersTable = (0, contract_providers_table_1.ContractProviders)(this.dataContext);
+        const allContracts = await contractsTable.list();
+        const allProviders = await providersTable.list();
+        const providersByKey = new Map();
+        for (const p of allProviders) {
+            const key = (0, types_1.contractKey)(p.contractId, p.version);
+            const list = providersByKey.get(key) ?? [];
+            list.push(p);
+            providersByKey.set(key, list);
+        }
+        for (const contractRecord of allContracts) {
+            const definition = this.recordToDefinition(contractRecord);
+            const key = (0, types_1.contractKey)(contractRecord.contractId, contractRecord.version);
+            const providers = providersByKey.get(key) ?? [];
+            for (const provider of providers) {
+                this.registry.register(provider.providerPackageId, definition);
+            }
+            const activeProvider = providers.find((p) => p.isActive);
+            if (activeProvider) {
+                this.registry.setActiveProvider(contractRecord.contractId, contractRecord.version, activeProvider.providerPackageId);
+            }
+        }
+    }
+    /**
+     * Switch the active provider for a contract and persist the change.
+     * Returns false if the switch failed in the in-memory registry.
+     */
+    async setActiveProvider(contractId, version, providerPackageId) {
+        const switched = this.registry.setActiveProvider(contractId, version, providerPackageId);
+        if (!switched)
+            return false;
+        const providersTable = (0, contract_providers_table_1.ContractProviders)(this.dataContext);
+        const providers = await providersTable.list({ contractId, version });
+        for (const provider of providers) {
+            const shouldBeActive = provider.providerPackageId === providerPackageId;
+            if (provider.isActive !== shouldBeActive) {
+                await providersTable.save({ ...provider, isActive: shouldBeActive });
+            }
+        }
+        return true;
+    }
+    /** Convert a persisted contract record back to an `IContractDefinition`. */
+    recordToDefinition(record) {
+        const { tables, tools, observables } = JSON.parse(record.shape);
+        return {
+            contractId: record.contractId,
+            version: record.version,
+            devTag: record.devTag,
+            name: record.name,
+            description: record.description,
+            tables,
+            tools,
+            observables,
+        };
+    }
+}
+exports.PersistentContractRegistry = PersistentContractRegistry;

package/dist/contracts/registry.d.ts

@@ -0,0 +1,58 @@
+import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IValidationResult } from "./types";
+/**
+ * Per-group contract registry. Maps contract identities (contractId + version)
+ * to their active provider.  In V1 this is in-memory only; persistence will
+ * be added when the registry is integrated with the runtime install flow.
+ */
+export declare class ContractRegistry {
+    /** All known contract definitions, keyed by contractKey. */
+    private definitions;
+    /** Active provider for each contract, keyed by contractKey. */
+    private activeProviders;
+    /** All providers for a contract (active + inactive), keyed by contractKey. */
+    private allProviders;
+    /** Reverse index: packageId -> list of contract keys it provides. */
+    private packageContracts;
+    /**
+     * Register a package as a provider for a contract.
+     *
+     * Validates:
+     * 1. The implementation satisfies its own declared contract shape.
+     * 2. Immutability — a frozen contract cannot be redefined with a different shape.
+     * 3. `alsoImplements` declarations.
+     *
+     * If no active provider exists for this contract yet, the new provider
+     * becomes the active one automatically.
+     *
+     * @returns Validation result.  If invalid the provider is not registered.
+     */
+    register(providerPackageId: string, definition: IContractDefinition, alsoImplementsDecls?: IAlsoImplementsDeclaration[]): IValidationResult;
+    /**
+     * Switch the active provider for a contract to a different registered package.
+     * Returns false if the target package is not a registered provider for that contract.
+     */
+    setActiveProvider(contractId: string, version: number, providerPackageId: string): boolean;
+    /**
+     * Resolve the active provider for a contract.
+     * Returns the contract definition if a provider is active, undefined otherwise.
+     */
+    resolve(contractId: string, version: number): IContractDefinition | undefined;
+    /** Get the active provider's package ID for a contract. */
+    getProviderPackageId(contractId: string, version: number): string | undefined;
+    /** Get the stored contract definition (regardless of active provider). */
+    getDefinition(contractId: string, version: number): IContractDefinition | undefined;
+    /**
+     * Remove all contracts provided by a package. If the removed package was
+     * the active provider for a contract, the next registered provider (if any)
+     * becomes active.
+     */
+    unregister(providerPackageId: string): void;
+    /**
+     * Check whether all consumed contracts have an active provider.
+     * Returns an object listing satisfied and missing contracts.
+     */
+    checkConsumerDependencies(consumed: IConsumedContract[]): {
+        satisfied: IConsumedContract[];
+        missing: IConsumedContract[];
+    };
+}

package/dist/contracts/registry.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContractRegistry = void 0;
+const types_1 = require("./types");
+const validate_1 = require("./validate");
+/**
+ * Per-group contract registry. Maps contract identities (contractId + version)
+ * to their active provider.  In V1 this is in-memory only; persistence will
+ * be added when the registry is integrated with the runtime install flow.
+ */
+class ContractRegistry {
+    /** All known contract definitions, keyed by contractKey. */
+    definitions = new Map();
+    /** Active provider for each contract, keyed by contractKey. */
+    activeProviders = new Map();
+    /** All providers for a contract (active + inactive), keyed by contractKey. */
+    allProviders = new Map();
+    /** Reverse index: packageId -> list of contract keys it provides. */
+    packageContracts = new Map();
+    /**
+     * Register a package as a provider for a contract.
+     *
+     * Validates:
+     * 1. The implementation satisfies its own declared contract shape.
+     * 2. Immutability — a frozen contract cannot be redefined with a different shape.
+     * 3. `alsoImplements` declarations.
+     *
+     * If no active provider exists for this contract yet, the new provider
+     * becomes the active one automatically.
+     *
+     * @returns Validation result.  If invalid the provider is not registered.
+     */
+    register(providerPackageId, definition, alsoImplementsDecls = []) {
+        const key = (0, types_1.contractKey)(definition.contractId, definition.version);
+        // Immutability check against any previously stored definition
+        const existingDef = this.definitions.get(key);
+        if (existingDef) {
+            const immResult = (0, validate_1.validateImmutability)(existingDef, definition);
+            if (!immResult.valid)
+                return immResult;
+        }
+        // alsoImplements check
+        if (alsoImplementsDecls.length > 0) {
+            const aiResult = (0, validate_1.validateAlsoImplements)(definition, alsoImplementsDecls, (cid, ver) => this.definitions.get((0, types_1.contractKey)(cid, ver)));
+            if (!aiResult.valid)
+                return aiResult;
+        }
+        // Store the definition (first-come for frozen, latest for dev)
+        this.definitions.set(key, definition);
+        const provider = { providerPackageId, definition };
+        // Add to the all-providers list
+        const providers = this.allProviders.get(key) ?? [];
+        const existingIdx = providers.findIndex((p) => p.providerPackageId === providerPackageId);
+        if (existingIdx >= 0) {
+            providers[existingIdx] = provider;
+        }
+        else {
+            providers.push(provider);
+        }
+        this.allProviders.set(key, providers);
+        // If no active provider, auto-activate
+        if (!this.activeProviders.has(key)) {
+            this.activeProviders.set(key, provider);
+        }
+        // Update reverse index
+        const pkgKeys = this.packageContracts.get(providerPackageId) ?? [];
+        if (!pkgKeys.includes(key)) {
+            pkgKeys.push(key);
+        }
+        this.packageContracts.set(providerPackageId, pkgKeys);
+        return { valid: true, errors: [] };
+    }
+    /**
+     * Switch the active provider for a contract to a different registered package.
+     * Returns false if the target package is not a registered provider for that contract.
+     */
+    setActiveProvider(contractId, version, providerPackageId) {
+        const key = (0, types_1.contractKey)(contractId, version);
+        const providers = this.allProviders.get(key);
+        if (!providers)
+            return false;
+        const target = providers.find((p) => p.providerPackageId === providerPackageId);
+        if (!target)
+            return false;
+        this.activeProviders.set(key, target);
+        return true;
+    }
+    /**
+     * Resolve the active provider for a contract.
+     * Returns the contract definition if a provider is active, undefined otherwise.
+     */
+    resolve(contractId, version) {
+        const key = (0, types_1.contractKey)(contractId, version);
+        return this.activeProviders.get(key)?.definition;
+    }
+    /** Get the active provider's package ID for a contract. */
+    getProviderPackageId(contractId, version) {
+        const key = (0, types_1.contractKey)(contractId, version);
+        return this.activeProviders.get(key)?.providerPackageId;
+    }
+    /** Get the stored contract definition (regardless of active provider). */
+    getDefinition(contractId, version) {
+        return this.definitions.get((0, types_1.contractKey)(contractId, version));
+    }
+    /**
+     * Remove all contracts provided by a package. If the removed package was
+     * the active provider for a contract, the next registered provider (if any)
+     * becomes active.
+     */
+    unregister(providerPackageId) {
+        const keys = this.packageContracts.get(providerPackageId) ?? [];
+        for (const key of keys) {
+            const providers = this.allProviders.get(key);
+            if (providers) {
+                const filtered = providers.filter((p) => p.providerPackageId !== providerPackageId);
+                if (filtered.length > 0) {
+                    this.allProviders.set(key, filtered);
+                }
+                else {
+                    this.allProviders.delete(key);
+                }
+                // If this was the active provider, fall back or remove
+                const active = this.activeProviders.get(key);
+                if (active?.providerPackageId === providerPackageId) {
+                    if (filtered.length > 0) {
+                        this.activeProviders.set(key, filtered[0]);
+                    }
+                    else {
+                        this.activeProviders.delete(key);
+                    }
+                }
+            }
+        }
+        this.packageContracts.delete(providerPackageId);
+    }
+    /**
+     * Check whether all consumed contracts have an active provider.
+     * Returns an object listing satisfied and missing contracts.
+     */
+    checkConsumerDependencies(consumed) {
+        const satisfied = [];
+        const missing = [];
+        for (const dep of consumed) {
+            const key = (0, types_1.contractKey)(dep.contractId, dep.version);
+            if (this.activeProviders.has(key)) {
+                satisfied.push(dep);
+            }
+            else {
+                missing.push(dep);
+            }
+        }
+        return { satisfied, missing };
+    }
+}
+exports.ContractRegistry = ContractRegistry;

package/dist/contracts/types.d.ts

@@ -0,0 +1,108 @@
+import type { Table } from "../data/orm/table";
+import type { ITableDefinition } from "../data/orm/table-definitions.type";
+import type { IToolInstance } from "../data/tools";
+import type { Observable } from "../observable";
+import type { FieldType, IField } from "../types/field-type";
+/**
+ * A versioned interface definition declaring the shape of tables, tools, and
+ * observables that a package provides. Pure data — no executable code.
+ */
+export interface IContractDefinition {
+    contractId: string;
+    version: number;
+    /** Absent = frozen (immutable). `'dev'` = in-development, shape may change. */
+    devTag?: "dev";
+    name: string;
+    description: string;
+    tables: IContractTable[];
+    tools: IContractTool[];
+    observables: IContractObservable[];
+}
+/** Table shape within a contract — derived from ITableMetaData + IField[]. */
+export interface IContractTable {
+    name: string;
+    description: string;
+    primaryKeyName: string;
+    fields: IField[];
+}
+/** Tool signature within a contract — derived from ITool + IOSchema. */
+export interface IContractTool {
+    name: string;
+    usageDescription: string;
+    inputFields: IField[];
+    outputFields: IField[];
+}
+/** Observable value exposed by a contract. */
+export interface IContractObservable {
+    name: string;
+    description: string;
+    valueType: FieldType;
+    writable: boolean;
+}
+/**
+ * A reference to a contract that a package wants to consume.
+ * Recorded during `definePackage` and checked at install time.
+ */
+export interface IConsumedContract {
+    contractId: string;
+    version: number;
+}
+/**
+ * Declares that the owning contract's implementation also satisfies another
+ * contract (single version or inclusive range).
+ */
+export interface IAlsoImplementsDeclaration {
+    contractId: string;
+    version: number | {
+        from: number;
+        to: number;
+    };
+}
+/** The result of calling `definePackage()`. */
+export interface IPackageDefinitionResult {
+    /** The peer ID of this package (25-char alphanumeric). */
+    packageId: string;
+    /** Semantic version string baked in from package.json at build time. */
+    version?: string;
+    /** Version channel tag (e.g. "dev", "beta", "stable"). */
+    versionTag?: string;
+    /** Contracts this package defines and provides. */
+    contracts: IContractDefinition[];
+    /** Contracts this package depends on. */
+    consumes: IConsumedContract[];
+    /** `alsoImplements` declarations keyed by the owning contractId+version. */
+    alsoImplements: Map<string, IAlsoImplementsDeclaration[]>;
+    /** Package-level items not part of any contract. */
+    assistants: unknown[];
+    appNavs: unknown[];
+    /** All executable tool instances across all contracts in this package. */
+    toolInstances: IToolInstance[];
+    /** All table definitions across all contracts in this package. */
+    tableDefinitions: ITableDefinition[];
+}
+/** A resolved contract in the registry, mapping contract shapes to live instances. */
+export interface IResolvedContract {
+    contractId: string;
+    version: number;
+    providerPackageId: string;
+    tables: Record<string, Table<any>>;
+    tools: Record<string, IToolInstance>;
+    observables: Record<string, Observable<any>>;
+}
+/** Outcome of a validation check. */
+export interface IValidationResult {
+    valid: boolean;
+    errors: IValidationError[];
+}
+export interface IValidationError {
+    /** Which element failed: `'table'`, `'tool'`, `'observable'`, `'contract'` */
+    kind: "table" | "tool" | "observable" | "contract" | "field";
+    /** Name of the element (table name, tool name, etc.) */
+    name: string;
+    message: string;
+}
+/**
+ * Builds a stable key for a contract identity (contractId + version).
+ * Used as map keys in the registry and alsoImplements tracking.
+ */
+export declare function contractKey(contractId: string, version: number): string;

package/dist/contracts/types.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractKey = contractKey;
+/**
+ * Builds a stable key for a contract identity (contractId + version).
+ * Used as map keys in the registry and alsoImplements tracking.
+ */
+function contractKey(contractId, version) {
+    return `${contractId}@${version}`;
+}

package/dist/contracts/validate.d.ts

@@ -0,0 +1,24 @@
+import type { IAlsoImplementsDeclaration, IContractDefinition, IValidationResult } from "./types";
+/**
+ * Validate that an implementation contract satisfies a target contract shape.
+ * The implementation must be a superset: all contract tables, tools, and
+ * observables must be present with compatible shapes.
+ */
+export declare function validateProviderSatisfiesContract(impl: IContractDefinition, contract: IContractDefinition): IValidationResult;
+/**
+ * Validate that a frozen (stable) contract definition has not been modified.
+ * If the existing definition has no `devTag` it is frozen; the incoming
+ * definition must be structurally identical and also stable.
+ * Dev contracts (`devTag: "dev"`) may change freely but cannot be registered
+ * once a stable version exists for that contract+version.
+ */
+export declare function validateImmutability(existing: IContractDefinition, incoming: IContractDefinition): IValidationResult;
+/**
+ * Validate that an implementation satisfies all contracts referenced by its
+ * `alsoImplements` declarations.
+ *
+ * @param impl         The implementation's extracted contract definition.
+ * @param declarations The `alsoImplements` declarations for this contract.
+ * @param getContract  Callback to look up an existing contract definition.
+ */
+export declare function validateAlsoImplements(impl: IContractDefinition, declarations: IAlsoImplementsDeclaration[], getContract: (contractId: string, version: number) => IContractDefinition | undefined): IValidationResult;