@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/auth/oauth-core.js

@@ -0,0 +1,121 @@
+import { createHash, randomBytes } from 'node:crypto';
+export function createOAuthState(bytes = 24) {
+    return randomBytes(bytes).toString('base64url');
+}
+export function createPkceVerifier(bytes = 32) {
+    return randomBytes(bytes).toString('base64url');
+}
+export function createPkceChallenge(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+export function parseOAuthScopes(raw) {
+    if (typeof raw !== 'string')
+        return undefined;
+    const scopes = raw.split(' ').map((value) => value.trim()).filter(Boolean);
+    return scopes.length > 0 ? scopes : undefined;
+}
+export function buildOAuthAuthorizationStart(config, input) {
+    const state = input?.state ?? createOAuthState();
+    const verifier = input?.verifier ?? createPkceVerifier();
+    const redirectUri = input?.redirectUri ?? config.redirectUri;
+    const url = new URL(config.authUrl);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('redirect_uri', redirectUri);
+    url.searchParams.set('state', state);
+    if (config.scopes && config.scopes.length > 0) {
+        url.searchParams.set('scope', config.scopes.join(' '));
+    }
+    if (config.audience) {
+        url.searchParams.set('audience', config.audience);
+    }
+    if (config.usePkce ?? true) {
+        url.searchParams.set('code_challenge', createPkceChallenge(verifier));
+        url.searchParams.set('code_challenge_method', 'S256');
+    }
+    for (const [key, value] of Object.entries(config.authParams ?? {})) {
+        url.searchParams.set(key, value);
+    }
+    return {
+        authorizationUrl: url.toString(),
+        state,
+        verifier,
+        redirectUri,
+    };
+}
+async function exchangeOAuthRequest(url, encoding, payload) {
+    const body = encoding === 'json'
+        ? JSON.stringify(payload)
+        : new URLSearchParams(Object.entries(payload).map(([key, value]) => [key, String(value)])).toString();
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': encoding === 'json' ? 'application/json' : 'application/x-www-form-urlencoded',
+        },
+        body,
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`OAuth token exchange failed (${response.status}): ${text}`);
+    }
+    const json = await response.json();
+    if (typeof json.access_token !== 'string' || json.access_token.length === 0) {
+        throw new Error('OAuth token exchange did not return an access token.');
+    }
+    return {
+        accessToken: json.access_token,
+        ...(typeof json.refresh_token === 'string' && json.refresh_token.length > 0
+            ? { refreshToken: json.refresh_token }
+            : {}),
+        tokenType: typeof json.token_type === 'string' && json.token_type.length > 0 ? json.token_type : 'Bearer',
+        ...(typeof json.expires_in === 'number' && Number.isFinite(json.expires_in)
+            ? { expiresAt: Date.now() + (json.expires_in * 1000) }
+            : {}),
+        ...(parseOAuthScopes(json.scope) ? { scopes: parseOAuthScopes(json.scope) } : {}),
+    };
+}
+export async function exchangeOAuthAuthorizationCode(config, input) {
+    const payload = {
+        grant_type: 'authorization_code',
+        client_id: config.clientId,
+        redirect_uri: input.redirectUri,
+        code: input.code,
+    };
+    if (config.usePkce ?? true)
+        payload.code_verifier = input.verifier;
+    if (config.audience)
+        payload.audience = config.audience;
+    if (config.includeStateInTokenRequest && input.state)
+        payload.state = input.state;
+    for (const [key, value] of Object.entries(config.tokenRequestExtras ?? {})) {
+        payload[key] = value;
+    }
+    return exchangeOAuthRequest(config.tokenUrl, config.tokenRequestEncoding ?? 'form', payload);
+}
+export async function refreshOAuthAccessToken(config, refreshToken) {
+    const payload = {
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: config.clientId,
+    };
+    if (config.refreshScopes && config.refreshScopes.length > 0) {
+        payload.scope = config.refreshScopes.join(' ');
+    }
+    if (config.audience)
+        payload.audience = config.audience;
+    for (const [key, value] of Object.entries(config.refreshRequestExtras ?? {})) {
+        payload[key] = value;
+    }
+    return exchangeOAuthRequest(config.tokenUrl, config.refreshRequestEncoding ?? config.tokenRequestEncoding ?? 'form', payload);
+}
+export function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/_internal/platform/runtime/contracts/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Compatibility Contracts — Module barrel and factory
+ *
+ * Entry point for the schema versioning, validation, and migration
+ * infrastructure. Use `createContractRegistry()` to obtain a fully
+ * initialized registry with all domain contracts registered.
+ *
+ * Usage:
+ * ```ts
+ * import { createContractRegistry } from './contracts/index.js';
+ * const { registry, contracts } = createContractRegistry();
+ * const result = contracts.get('runtimeState')?.validate(rawData);
+ * ```
+ *
+ * @module contracts
+ */
+export { MigrationRegistry } from './migrations/index.js';
+export * from './types.js';
+export * from './version.js';
+export * from './validators/index.js';
+import { MigrationRegistry } from './migrations/index.js';
+import type { SchemaContract } from './types.js';
+import type { ContractName } from './version.js';
+/**
+ * Creates a fully initialized contract registry with all domain migration
+ * steps registered and SchemaContract instances built for each domain.
+ *
+ * Each SchemaContract provides:
+ * - `validate(data)` — runtime shape validation returning a ValidationResult
+ * - `migrate(data, fromVersion)` — migration chain execution via MigrationRegistry
+ *
+ * @returns An object containing:
+ *   - `registry` — the MigrationRegistry with all steps registered
+ *   - `contracts` — a Map of contract name → SchemaContract
+ */
+export declare function createContractRegistry(): {
+    registry: MigrationRegistry;
+    contracts: Map<ContractName, SchemaContract>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AAEtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAUjD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,GAAG,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;CAC9C,CAsGA"}

package/dist/_internal/platform/runtime/contracts/index.js

@@ -0,0 +1,137 @@
+/**
+ * Compatibility Contracts — Module barrel and factory
+ *
+ * Entry point for the schema versioning, validation, and migration
+ * infrastructure. Use `createContractRegistry()` to obtain a fully
+ * initialized registry with all domain contracts registered.
+ *
+ * Usage:
+ * ```ts
+ * import { createContractRegistry } from './contracts/index.js';
+ * const { registry, contracts } = createContractRegistry();
+ * const result = contracts.get('runtimeState')?.validate(rawData);
+ * ```
+ *
+ * @module contracts
+ */
+export { MigrationRegistry } from './migrations/index.js';
+export * from './types.js';
+export * from './version.js';
+export * from './validators/index.js';
+import { MigrationRegistry } from './migrations/index.js';
+import { SCHEMA_VERSIONS, MIN_SUPPORTED_VERSIONS } from './version.js';
+import { getRuntimeStateMigrationSteps } from './migrations/runtime-state.js';
+import { getEventEnvelopeMigrationSteps } from './migrations/event-envelope.js';
+import { getSessionMigrationSteps } from './migrations/session.js';
+import { getPluginManifestMigrationSteps } from './migrations/plugin-manifest.js';
+import { getTaskRecordMigrationSteps } from './migrations/task-record.js';
+import { validateRuntimeState } from './validators/runtime-state.js';
+import { validateEventEnvelope } from './validators/event-envelope.js';
+import { validateSession } from './validators/session.js';
+/**
+ * Creates a fully initialized contract registry with all domain migration
+ * steps registered and SchemaContract instances built for each domain.
+ *
+ * Each SchemaContract provides:
+ * - `validate(data)` — runtime shape validation returning a ValidationResult
+ * - `migrate(data, fromVersion)` — migration chain execution via MigrationRegistry
+ *
+ * @returns An object containing:
+ *   - `registry` — the MigrationRegistry with all steps registered
+ *   - `contracts` — a Map of contract name → SchemaContract
+ */
+export function createContractRegistry() {
+    const registry = new MigrationRegistry();
+    // Register all domain migration steps
+    for (const step of getRuntimeStateMigrationSteps()) {
+        registry.register('runtimeState', step);
+    }
+    for (const step of getEventEnvelopeMigrationSteps()) {
+        registry.register('eventEnvelope', step);
+    }
+    for (const step of getSessionMigrationSteps()) {
+        registry.register('session', step);
+    }
+    for (const step of getPluginManifestMigrationSteps()) {
+        registry.register('pluginManifest', step);
+    }
+    for (const step of getTaskRecordMigrationSteps()) {
+        registry.register('taskRecord', step);
+    }
+    const contracts = new Map();
+    // runtimeState contract
+    contracts.set('runtimeState', {
+        name: 'runtimeState',
+        currentVersion: SCHEMA_VERSIONS.runtimeState,
+        minSupportedVersion: MIN_SUPPORTED_VERSIONS.runtimeState,
+        validate: validateRuntimeState,
+        migrate: (data, fromVersion) => registry.migrate('runtimeState', data, fromVersion),
+    });
+    // eventEnvelope contract
+    contracts.set('eventEnvelope', {
+        name: 'eventEnvelope',
+        currentVersion: SCHEMA_VERSIONS.eventEnvelope,
+        minSupportedVersion: MIN_SUPPORTED_VERSIONS.eventEnvelope,
+        validate: validateEventEnvelope,
+        migrate: (data, fromVersion) => registry.migrate('eventEnvelope', data, fromVersion),
+    });
+    // session contract
+    contracts.set('session', {
+        name: 'session',
+        currentVersion: SCHEMA_VERSIONS.session,
+        minSupportedVersion: MIN_SUPPORTED_VERSIONS.session,
+        validate: validateSession,
+        migrate: (data, fromVersion) => registry.migrate('session', data, fromVersion),
+    });
+    // pluginManifest contract
+    contracts.set('pluginManifest', {
+        name: 'pluginManifest',
+        currentVersion: SCHEMA_VERSIONS.pluginManifest,
+        minSupportedVersion: MIN_SUPPORTED_VERSIONS.pluginManifest,
+        validate: (data) => {
+            const errors = [];
+            if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+                errors.push({ path: '', message: 'pluginManifest must be a non-null object', expected: 'object', actual: data === null ? 'null' : Array.isArray(data) ? 'array' : typeof data });
+                return { valid: false, errors };
+            }
+            const record = data;
+            if (typeof record['name'] !== 'string' || record['name'].length === 0) {
+                errors.push({ path: 'name', message: "Field 'name' must be a non-empty string", expected: 'non-empty string', actual: typeof record['name'] });
+            }
+            if (typeof record['version'] !== 'string' || record['version'].length === 0) {
+                errors.push({ path: 'version', message: "Field 'version' must be a non-empty string", expected: 'non-empty string', actual: typeof record['version'] });
+            }
+            if (!Array.isArray(record['capabilities'])) {
+                errors.push({ path: 'capabilities', message: "Field 'capabilities' must be an array", expected: 'array', actual: typeof record['capabilities'] });
+            }
+            return { valid: errors.length === 0, errors, version: SCHEMA_VERSIONS.pluginManifest };
+        },
+        migrate: (data, fromVersion) => registry.migrate('pluginManifest', data, fromVersion),
+    });
+    // taskRecord contract
+    contracts.set('taskRecord', {
+        name: 'taskRecord',
+        currentVersion: SCHEMA_VERSIONS.taskRecord,
+        minSupportedVersion: MIN_SUPPORTED_VERSIONS.taskRecord,
+        validate: (data) => {
+            const errors = [];
+            if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+                errors.push({ path: '', message: 'taskRecord must be a non-null object', expected: 'object', actual: data === null ? 'null' : Array.isArray(data) ? 'array' : typeof data });
+                return { valid: false, errors };
+            }
+            const record = data;
+            if (typeof record['id'] !== 'string' || record['id'].length === 0) {
+                errors.push({ path: 'id', message: "Field 'id' must be a non-empty string", expected: 'non-empty string', actual: typeof record['id'] });
+            }
+            if (typeof record['type'] !== 'string' || record['type'].length === 0) {
+                errors.push({ path: 'type', message: "Field 'type' must be a non-empty string", expected: 'non-empty string', actual: typeof record['type'] });
+            }
+            if (typeof record['status'] !== 'string' || record['status'].length === 0) {
+                errors.push({ path: 'status', message: "Field 'status' must be a non-empty string", expected: 'non-empty string', actual: typeof record['status'] });
+            }
+            return { valid: errors.length === 0, errors, version: SCHEMA_VERSIONS.taskRecord };
+        },
+        migrate: (data, fromVersion) => registry.migrate('taskRecord', data, fromVersion),
+    });
+    return { registry, contracts };
+}

package/dist/_internal/platform/runtime/contracts/migrations/event-envelope.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compatibility Contracts — EventEnvelope Migrations
+ *
+ * Migration steps for the RuntimeEventEnvelope persistence schema.
+ * All steps are pure functions — they do not mutate their input.
+ *
+ * @module contracts/migrations/event-envelope
+ */
+import type { MigrationStep } from '../types.js';
+/**
+ * The current EventEnvelope schema version (re-exported for convenience).
+ */
+export declare const EVENT_ENVELOPE_VERSION: {
+    readonly major: 1;
+    readonly minor: 0;
+    readonly patch: 0;
+};
+/**
+ * Returns all EventEnvelope migration steps.
+ * Used by the contract registry during initialization.
+ */
+export declare function getEventEnvelopeMigrationSteps(): MigrationStep[];
+//# sourceMappingURL=event-envelope.d.ts.map

package/dist/_internal/platform/runtime/contracts/migrations/event-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/migrations/event-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyBjD;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;CAAgC,CAAC;AAEpE;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,aAAa,EAAE,CAEhE"}

package/dist/_internal/platform/runtime/contracts/migrations/event-envelope.js

@@ -0,0 +1,41 @@
+/**
+ * Compatibility Contracts — EventEnvelope Migrations
+ *
+ * Migration steps for the RuntimeEventEnvelope persistence schema.
+ * All steps are pure functions — they do not mutate their input.
+ *
+ * @module contracts/migrations/event-envelope
+ */
+import { SCHEMA_VERSIONS } from '../version.js';
+/**
+ * All registered EventEnvelope migration steps.
+ *
+ * Currently empty — the schema is at its initial version (1.0.0).
+ * Future steps must be appended here and registered via the contract registry.
+ *
+ * Example: if `agentId` becomes required in v1.1.0, a migration step would
+ * backfill it with a sentinel value for older persisted envelopes.
+ */
+const EVENT_ENVELOPE_STEPS = [
+// Example structure for future use:
+// {
+//   from: { major: 1, minor: 0, patch: 0 },
+//   to: { major: 1, minor: 1, patch: 0 },
+//   description: 'Backfill missing agentId with null sentinel',
+//   migrate: (data: unknown): unknown => {
+//     const d = data as Record<string, unknown>;
+//     return { ...d, agentId: d['agentId'] ?? null };
+//   },
+// },
+];
+/**
+ * The current EventEnvelope schema version (re-exported for convenience).
+ */
+export const EVENT_ENVELOPE_VERSION = SCHEMA_VERSIONS.eventEnvelope;
+/**
+ * Returns all EventEnvelope migration steps.
+ * Used by the contract registry during initialization.
+ */
+export function getEventEnvelopeMigrationSteps() {
+    return EVENT_ENVELOPE_STEPS;
+}

package/dist/_internal/platform/runtime/contracts/migrations/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Compatibility Contracts — Migration Registry
+ *
+ * The MigrationRegistry holds all registered schema migration steps and
+ * provides path resolution and ordered execution for any version pair.
+ *
+ * @module contracts/migrations
+ */
+import { type MigrationStep, type MigrationResult, type SchemaVersion } from '../types.js';
+/**
+ * Central registry for all schema migration steps.
+ *
+ * Migrations are registered per contract name and resolved as an ordered
+ * chain from a given source version to the current target version.
+ * All migration functions must be pure (no mutations, no side effects).
+ */
+export declare class MigrationRegistry {
+    private readonly steps;
+    /**
+     * Registers a migration step for a given contract.
+     *
+     * Steps are stored in insertion order and sorted at resolution time.
+     * Duplicate from→to pairs for the same contract are not permitted.
+     *
+     * @param contract - The contract name (e.g. 'runtimeState').
+     * @param step - The migration step to register.
+     * @throws If a step with the same from→to is already registered.
+     */
+    register(contract: string, step: MigrationStep): void;
+    /**
+     * Returns true if any migration path exists from `fromVersion` toward
+     * a higher version for the given contract.
+     *
+     * @param contract - The contract name.
+     * @param fromVersion - The source schema version to migrate from.
+     */
+    canMigrate(contract: string, fromVersion: SchemaVersion): boolean;
+    /**
+     * Resolves an ordered chain of migration steps from `from` to `to`.
+     *
+     * Uses a greedy forward walk: at each version, finds the step that advances
+     * closest to the target. Throws if no complete path exists.
+     *
+     * @param contract - The contract name.
+     * @param from - The starting schema version.
+     * @param to - The target schema version.
+     * @returns Ordered array of MigrationSteps forming the complete path.
+     * @throws If no migration path exists between the two versions.
+     */
+    getMigrationPath(contract: string, from: SchemaVersion, to: SchemaVersion): MigrationStep[];
+    /**
+     * Migrates data from `fromVersion` to the latest version reachable via
+     * registered steps for the given contract.
+     *
+     * If `fromVersion` already matches the end of the migration chain,
+     * the data is returned as-is without transformation.
+     *
+     * @param contract - The contract name.
+     * @param data - The raw data to migrate.
+     * @param fromVersion - The schema version of the incoming data.
+     * @returns The migrated data and the version it was migrated to.
+     * @throws If the migration path is incomplete or a step throws.
+     */
+    migrate(contract: string, data: unknown, fromVersion: SchemaVersion): MigrationResult;
+    /**
+     * Resolves the highest version reachable from `fromVersion` by following
+     * the chain of registered steps.
+     */
+    private _resolveLatestVersion;
+    /**
+     * Returns all registered contract names.
+     */
+    contractNames(): string[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/contracts/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAE5D;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;IAiBrD;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,GAAG,OAAO;IAKjE;;;;;;;;;;;OAWG;IACH,gBAAgB,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,aAAa,GAChB,aAAa,EAAE;IAqDlB;;;;;;;;;;;;OAYG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,aAAa,GACzB,eAAe;IAiBlB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;CAG1B"}

package/dist/_internal/platform/runtime/contracts/migrations/index.js

@@ -0,0 +1,158 @@
+/**
+ * Compatibility Contracts — Migration Registry
+ *
+ * The MigrationRegistry holds all registered schema migration steps and
+ * provides path resolution and ordered execution for any version pair.
+ *
+ * @module contracts/migrations
+ */
+import { compareVersions, versionsEqual, versionToString, } from '../types.js';
+/**
+ * Central registry for all schema migration steps.
+ *
+ * Migrations are registered per contract name and resolved as an ordered
+ * chain from a given source version to the current target version.
+ * All migration functions must be pure (no mutations, no side effects).
+ */
+export class MigrationRegistry {
+    steps = new Map();
+    /**
+     * Registers a migration step for a given contract.
+     *
+     * Steps are stored in insertion order and sorted at resolution time.
+     * Duplicate from→to pairs for the same contract are not permitted.
+     *
+     * @param contract - The contract name (e.g. 'runtimeState').
+     * @param step - The migration step to register.
+     * @throws If a step with the same from→to is already registered.
+     */
+    register(contract, step) {
+        if (!this.steps.has(contract)) {
+            this.steps.set(contract, []);
+        }
+        const existing = this.steps.get(contract);
+        const duplicate = existing.find((s) => versionsEqual(s.from, step.from) && versionsEqual(s.to, step.to));
+        if (duplicate) {
+            throw new Error(`Duplicate migration step for contract '${contract}': ` +
+                `${versionToString(step.from)} → ${versionToString(step.to)}`);
+        }
+        existing.push(step);
+    }
+    /**
+     * Returns true if any migration path exists from `fromVersion` toward
+     * a higher version for the given contract.
+     *
+     * @param contract - The contract name.
+     * @param fromVersion - The source schema version to migrate from.
+     */
+    canMigrate(contract, fromVersion) {
+        const steps = this.steps.get(contract) ?? [];
+        return steps.some((s) => versionsEqual(s.from, fromVersion));
+    }
+    /**
+     * Resolves an ordered chain of migration steps from `from` to `to`.
+     *
+     * Uses a greedy forward walk: at each version, finds the step that advances
+     * closest to the target. Throws if no complete path exists.
+     *
+     * @param contract - The contract name.
+     * @param from - The starting schema version.
+     * @param to - The target schema version.
+     * @returns Ordered array of MigrationSteps forming the complete path.
+     * @throws If no migration path exists between the two versions.
+     */
+    getMigrationPath(contract, from, to) {
+        if (versionsEqual(from, to))
+            return [];
+        if (compareVersions(from, to) > 0) {
+            throw new Error(`Downgrade migration is not supported for contract '${contract}': ` +
+                `cannot migrate from ${versionToString(from)} to ${versionToString(to)}`);
+        }
+        const allSteps = this.steps.get(contract) ?? [];
+        const path = [];
+        let current = from;
+        while (!versionsEqual(current, to)) {
+            // Find all steps that start from the current version
+            const candidates = allSteps.filter((s) => versionsEqual(s.from, current));
+            if (candidates.length === 0) {
+                throw new Error(`No migration step found for contract '${contract}' ` +
+                    `at version ${versionToString(current)} (target: ${versionToString(to)})`);
+            }
+            // Pick the step that advances closest to the target without overshooting
+            const step = candidates.reduce((best, candidate) => {
+                const cmpBest = compareVersions(best.to, to);
+                const cmpCandidate = compareVersions(candidate.to, to);
+                // Prefer steps that don't overshoot; among those, prefer the one closest to target
+                if (cmpBest > 0 && cmpCandidate <= 0)
+                    return candidate;
+                if (cmpCandidate > 0 && cmpBest <= 0)
+                    return best;
+                return compareVersions(candidate.to, best.to) > 0 ? candidate : best;
+            });
+            if (compareVersions(step.to, current) <= 0) {
+                throw new Error(`Migration step for contract '${contract}' does not advance version: ` +
+                    `${versionToString(step.from)} → ${versionToString(step.to)}`);
+            }
+            path.push(step);
+            current = step.to;
+            if (path.length > 100) {
+                throw new Error(`Migration path for contract '${contract}' exceeded 100 steps — possible cycle detected`);
+            }
+        }
+        return path;
+    }
+    /**
+     * Migrates data from `fromVersion` to the latest version reachable via
+     * registered steps for the given contract.
+     *
+     * If `fromVersion` already matches the end of the migration chain,
+     * the data is returned as-is without transformation.
+     *
+     * @param contract - The contract name.
+     * @param data - The raw data to migrate.
+     * @param fromVersion - The schema version of the incoming data.
+     * @returns The migrated data and the version it was migrated to.
+     * @throws If the migration path is incomplete or a step throws.
+     */
+    migrate(contract, data, fromVersion) {
+        // Find the highest reachable version from this starting point
+        const targetVersion = this._resolveLatestVersion(contract, fromVersion);
+        if (versionsEqual(fromVersion, targetVersion)) {
+            return { data, version: fromVersion };
+        }
+        const path = this.getMigrationPath(contract, fromVersion, targetVersion);
+        let current = data;
+        for (const step of path) {
+            current = step.migrate(current);
+        }
+        return { data: current, version: targetVersion };
+    }
+    /**
+     * Resolves the highest version reachable from `fromVersion` by following
+     * the chain of registered steps.
+     */
+    _resolveLatestVersion(contract, fromVersion) {
+        const allSteps = this.steps.get(contract) ?? [];
+        let current = fromVersion;
+        const visited = new Set();
+        while (true) {
+            const key = versionToString(current);
+            if (visited.has(key))
+                break;
+            visited.add(key);
+            const next = allSteps
+                .filter((s) => versionsEqual(s.from, current))
+                .sort((a, b) => compareVersions(b.to, a.to))[0];
+            if (!next)
+                break;
+            current = next.to;
+        }
+        return current;
+    }
+    /**
+     * Returns all registered contract names.
+     */
+    contractNames() {
+        return [...this.steps.keys()];
+    }
+}

package/dist/_internal/platform/runtime/contracts/migrations/plugin-manifest.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compatibility Contracts — Plugin Manifest Migrations
+ *
+ * Migration steps for the plugin manifest and capability descriptor schema.
+ * All steps are pure functions — they do not mutate their input.
+ *
+ * @module contracts/migrations/plugin-manifest
+ */
+import type { MigrationStep } from '../types.js';
+/**
+ * The current PluginManifest schema version (re-exported for convenience).
+ */
+export declare const PLUGIN_MANIFEST_VERSION: {
+    readonly major: 1;
+    readonly minor: 0;
+    readonly patch: 0;
+};
+/**
+ * Returns all PluginManifest migration steps.
+ * Used by the contract registry during initialization.
+ */
+export declare function getPluginManifestMigrationSteps(): MigrationStep[];
+//# sourceMappingURL=plugin-manifest.d.ts.map

package/dist/_internal/platform/runtime/contracts/migrations/plugin-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manifest.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/migrations/plugin-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyBjD;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;CAAiC,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,aAAa,EAAE,CAEjE"}