@pellux/goodvibes-sdk 0.18.3 → 0.18.12

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

@@ -0,0 +1,41 @@
+/**
+ * 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 { SCHEMA_VERSIONS } from '../version.js';
+/**
+ * All registered PluginManifest 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 `capabilities` becomes an explicit array in v1.1.0, a migration
+ * step would synthesize it from `registerCommand`/`registerTool` declarations.
+ */
+const PLUGIN_MANIFEST_STEPS = [
+// Example structure for future use:
+// {
+//   from: { major: 1, minor: 0, patch: 0 },
+//   to: { major: 1, minor: 1, patch: 0 },
+//   description: 'Add capabilities array to plugin manifest',
+//   migrate: (data: unknown): unknown => {
+//     const d = data as Record<string, unknown>;
+//     return { ...d, capabilities: d['capabilities'] ?? [] };
+//   },
+// },
+];
+/**
+ * The current PluginManifest schema version (re-exported for convenience).
+ */
+export const PLUGIN_MANIFEST_VERSION = SCHEMA_VERSIONS.pluginManifest;
+/**
+ * Returns all PluginManifest migration steps.
+ * Used by the contract registry during initialization.
+ */
+export function getPluginManifestMigrationSteps() {
+    return PLUGIN_MANIFEST_STEPS;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-state.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/migrations/runtime-state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA6BjD;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;CAA+B,CAAC;AAElE;;;GAGG;AACH,wBAAgB,6BAA6B,IAAI,aAAa,EAAE,CAE/D"}

package/dist/_internal/platform/runtime/contracts/migrations/runtime-state.js

@@ -0,0 +1,44 @@
+/**
+ * Compatibility Contracts — RuntimeState Migrations
+ *
+ * Migration steps for the top-level RuntimeState snapshot schema.
+ * All steps are pure functions — they do not mutate their input.
+ *
+ * @module contracts/migrations/runtime-state
+ */
+import { SCHEMA_VERSIONS } from '../version.js';
+/**
+ * Placeholder step from v1.0.0 → v1.0.0 (identity, no structural change yet).
+ *
+ * When the schema is bumped to v1.1.0 or v2.0.0, add new steps here.
+ * Example v1.0.0 → v1.1.0 would add a new optional field with a default.
+ */
+/**
+ * All registered RuntimeState migration steps.
+ *
+ * Currently empty — the schema is at its initial version (1.0.0).
+ * Future steps must be appended here and registered via `registerRuntimeStateMigrations`.
+ */
+const RUNTIME_STATE_STEPS = [
+// Example structure for future use:
+// {
+//   from: { major: 1, minor: 0, patch: 0 },
+//   to: { major: 1, minor: 1, patch: 0 },
+//   description: 'Add optional uiSettings field with defaults',
+//   migrate: (data: unknown): unknown => {
+//     const d = data as Record<string, unknown>;
+//     return { ...d, uiSettings: d['uiSettings'] ?? { theme: 'dark' } };
+//   },
+// },
+];
+/**
+ * The current RuntimeState schema version (re-exported for convenience).
+ */
+export const RUNTIME_STATE_VERSION = SCHEMA_VERSIONS.runtimeState;
+/**
+ * Returns all RuntimeState migration steps.
+ * Used by the contract registry during initialization.
+ */
+export function getRuntimeStateMigrationSteps() {
+    return RUNTIME_STATE_STEPS;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/migrations/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA0BjD;;GAEG;AACH,eAAO,MAAM,eAAe;;;;CAA0B,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,aAAa,EAAE,CAE1D"}

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

@@ -0,0 +1,42 @@
+/**
+ * Compatibility Contracts — Session Migrations
+ *
+ * Migration steps for the session persistence format (messages + meta).
+ * All steps are pure functions — they do not mutate their input.
+ *
+ * @module contracts/migrations/session
+ */
+import { SCHEMA_VERSIONS } from '../version.js';
+/**
+ * All registered Session 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 session files gain a `tags` array in v1.1.0, a migration step
+ * would backfill it as an empty array for existing sessions.
+ */
+const SESSION_STEPS = [
+// Example structure for future use:
+// {
+//   from: { major: 1, minor: 0, patch: 0 },
+//   to: { major: 1, minor: 1, patch: 0 },
+//   description: 'Add empty tags array to session meta',
+//   migrate: (data: unknown): unknown => {
+//     const d = data as Record<string, unknown>;
+//     const meta = d['meta'] as Record<string, unknown>;
+//     return { ...d, meta: { ...meta, tags: meta['tags'] ?? [] } };
+//   },
+// },
+];
+/**
+ * The current Session schema version (re-exported for convenience).
+ */
+export const SESSION_VERSION = SCHEMA_VERSIONS.session;
+/**
+ * Returns all Session migration steps.
+ * Used by the contract registry during initialization.
+ */
+export function getSessionMigrationSteps() {
+    return SESSION_STEPS;
+}

package/dist/_internal/platform/runtime/contracts/migrations/task-record.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compatibility Contracts — TaskRecord Migrations
+ *
+ * Migration steps for the RuntimeTask record schema used in task domain
+ * persistence and serialization. All steps are pure functions.
+ *
+ * @module contracts/migrations/task-record
+ */
+import type { MigrationStep } from '../types.js';
+/**
+ * The current TaskRecord schema version (re-exported for convenience).
+ */
+export declare const TASK_RECORD_VERSION: {
+    readonly major: 1;
+    readonly minor: 0;
+    readonly patch: 0;
+};
+/**
+ * Returns all TaskRecord migration steps.
+ * Used by the contract registry during initialization.
+ */
+export declare function getTaskRecordMigrationSteps(): MigrationStep[];
+//# sourceMappingURL=task-record.d.ts.map

package/dist/_internal/platform/runtime/contracts/migrations/task-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-record.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/migrations/task-record.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyBjD;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;CAA6B,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,aAAa,EAAE,CAE7D"}

package/dist/_internal/platform/runtime/contracts/migrations/task-record.js

@@ -0,0 +1,41 @@
+/**
+ * Compatibility Contracts — TaskRecord Migrations
+ *
+ * Migration steps for the RuntimeTask record schema used in task domain
+ * persistence and serialization. All steps are pure functions.
+ *
+ * @module contracts/migrations/task-record
+ */
+import { SCHEMA_VERSIONS } from '../version.js';
+/**
+ * All registered TaskRecord 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 `metadata` map is added to RuntimeTask in v1.1.0, a migration
+ * step would backfill it as an empty object for existing persisted records.
+ */
+const TASK_RECORD_STEPS = [
+// Example structure for future use:
+// {
+//   from: { major: 1, minor: 0, patch: 0 },
+//   to: { major: 1, minor: 1, patch: 0 },
+//   description: 'Add metadata object to task records',
+//   migrate: (data: unknown): unknown => {
+//     const d = data as Record<string, unknown>;
+//     return { ...d, metadata: d['metadata'] ?? {} };
+//   },
+// },
+];
+/**
+ * The current TaskRecord schema version (re-exported for convenience).
+ */
+export const TASK_RECORD_VERSION = SCHEMA_VERSIONS.taskRecord;
+/**
+ * Returns all TaskRecord migration steps.
+ * Used by the contract registry during initialization.
+ */
+export function getTaskRecordMigrationSteps() {
+    return TASK_RECORD_STEPS;
+}

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

@@ -0,0 +1,123 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Compatibility Contracts — Core Types
+ *
+ * Defines the foundational types used by the schema versioning and migration
+ * infrastructure across all runtime domains.
+ *
+ * @module contracts/types
+ */
+/**
+ * A semantic version identifier for a schema.
+ *
+ * Follows major.minor.patch semantics:
+ * - major: breaking change, requires explicit migration
+ * - minor: additive change, backward-compatible
+ * - patch: non-structural fix, always backward-compatible
+ */
+export interface SchemaVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+}
+/**
+ * The result of a schema validation operation.
+ */
+export interface ValidationResult {
+    /** Whether the data is valid against the expected schema. */
+    readonly valid: boolean;
+    /** Structured list of validation errors (empty when valid). */
+    readonly errors: ValidationError[];
+    /** The detected schema version, if parseable. */
+    readonly version?: SchemaVersion;
+}
+/**
+ * A single validation failure with path and diagnostic context.
+ */
+export interface ValidationError {
+    /** Dot-delimited path to the invalid field (e.g. 'envelope.sessionId'). */
+    readonly path: string;
+    /** Human-readable description of the failure. */
+    readonly message: string;
+    /** Description of the expected type or value. */
+    readonly expected?: string;
+    /** Description of the actual type or value found. */
+    readonly actual?: string;
+}
+/**
+ * A pure transformation function that migrates data from one schema version
+ * to the next. Must not mutate the input — return a new object.
+ *
+ * The `unknown` input/output types are intentional: migration functions operate
+ * on raw persisted data whose shape may predate current TypeScript interfaces.
+ */
+export type MigrationFn = (data: unknown) => unknown;
+/**
+ * Describes a single step in a migration chain, moving data from `from` to `to`.
+ *
+ * All steps must be registered in the MigrationRegistry before use.
+ */
+export interface MigrationStep {
+    /** Source schema version this step migrates from. */
+    readonly from: SchemaVersion;
+    /** Target schema version this step migrates to. */
+    readonly to: SchemaVersion;
+    /** Pure transformation function. Must not mutate input. */
+    readonly migrate: MigrationFn;
+    /** Human-readable description of what this migration changes. */
+    readonly description: string;
+}
+/**
+ * The result of a migration operation, containing the transformed data
+ * and the version it was migrated to.
+ */
+export interface MigrationResult {
+    /** The migrated data at the target schema version. */
+    readonly data: unknown;
+    /** The schema version of the migrated data. */
+    readonly version: SchemaVersion;
+}
+/**
+ * A schema contract defines the versioning, validation, and migration
+ * interface for a single domain schema (e.g. RuntimeState, EventEnvelope).
+ */
+export interface SchemaContract {
+    /** Unique name identifying this contract (e.g. 'runtimeState'). */
+    readonly name: string;
+    /** The current schema version emitted by this runtime. */
+    readonly currentVersion: SchemaVersion;
+    /** The oldest schema version this runtime can still migrate from. */
+    readonly minSupportedVersion: SchemaVersion;
+    /**
+     * Validates that the given data matches the expected schema shape.
+     * Performs runtime type checks — not just TypeScript type narrowing.
+     */
+    validate: (data: unknown) => ValidationResult;
+    /**
+     * Migrates data from an older schema version to the current version.
+     * Returns a MigrationResult with the migrated data and target version,
+     * or throws if migration is not possible.
+     */
+    migrate: (data: unknown, fromVersion: SchemaVersion) => MigrationResult;
+}
+/**
+ * Compares two SchemaVersions. Returns:
+ * - negative if a < b
+ * - 0 if a === b
+ * - positive if a > b
+ */
+export declare function compareVersions(a: SchemaVersion, b: SchemaVersion): number;
+/**
+ * Returns true if the two SchemaVersions are equal.
+ */
+export declare function versionsEqual(a: SchemaVersion, b: SchemaVersion): boolean;
+/**
+ * Serializes a SchemaVersion to a canonical string (e.g. '1.0.0').
+ */
+export declare function versionToString(v: SchemaVersion): string;
+/**
+ * Parses a version string (e.g. '1.2.3') into a SchemaVersion.
+ * Throws if the string is not a valid semver triple.
+ */
+export declare function parseVersion(raw: string): SchemaVersion;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/contracts/types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC;IAC5C;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,gBAAgB,CAAC;IAC9C;;;;OAIG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,KAAK,eAAe,CAAC;CACzE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAI1E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAEzE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAUvD"}

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

@@ -0,0 +1,41 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Compares two SchemaVersions. Returns:
+ * - negative if a < b
+ * - 0 if a === b
+ * - positive if a > b
+ */
+export function compareVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+/**
+ * Returns true if the two SchemaVersions are equal.
+ */
+export function versionsEqual(a, b) {
+    return a.major === b.major && a.minor === b.minor && a.patch === b.patch;
+}
+/**
+ * Serializes a SchemaVersion to a canonical string (e.g. '1.0.0').
+ */
+export function versionToString(v) {
+    return `${v.major}.${v.minor}.${v.patch}`;
+}
+/**
+ * Parses a version string (e.g. '1.2.3') into a SchemaVersion.
+ * Throws if the string is not a valid semver triple.
+ */
+export function parseVersion(raw) {
+    const parts = raw.split('.');
+    if (parts.length !== 3) {
+        throw new Error(`Invalid schema version string: '${raw}' (expected 'major.minor.patch')`);
+    }
+    const [major, minor, patch] = parts.map(Number);
+    if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) {
+        throw new Error(`Non-integer component in schema version: '${raw}'`);
+    }
+    return { major, minor, patch };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Compatibility Contracts — EventEnvelope Validator
+ *
+ * Performs runtime shape validation for the RuntimeEventEnvelope persistence schema.
+ * Returns a structured ValidationResult rather than throwing.
+ *
+ * @module contracts/validators/event-envelope
+ */
+import type { ValidationResult } from '../types.js';
+/**
+ * Validates that `data` conforms to the expected RuntimeEventEnvelope persistence shape.
+ *
+ * Checks:
+ * - `data` is a non-null object
+ * - `type`, `traceId`, `sessionId`, `source` are non-empty strings
+ * - `ts` is a finite number (Unix ms timestamp)
+ * - `payload` is present and is a non-null object
+ * - `version` (if present) has numeric `major`, `minor`, `patch` fields
+ *
+ * @param data - The raw persisted data to validate.
+ * @returns A ValidationResult with structured errors if any field is invalid.
+ */
+export declare function validateEventEnvelope(data: unknown): ValidationResult;
+//# sourceMappingURL=event-envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/validators/event-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAkC,MAAM,aAAa,CAAC;AAOpF;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAgFrE"}

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

@@ -0,0 +1,104 @@
+/**
+ * Compatibility Contracts — EventEnvelope Validator
+ *
+ * Performs runtime shape validation for the RuntimeEventEnvelope persistence schema.
+ * Returns a structured ValidationResult rather than throwing.
+ *
+ * @module contracts/validators/event-envelope
+ */
+/**
+ * Required fields for a persisted RuntimeEventEnvelope.
+ */
+const REQUIRED_STRING_FIELDS = ['type', 'traceId', 'sessionId', 'source'];
+/**
+ * Validates that `data` conforms to the expected RuntimeEventEnvelope persistence shape.
+ *
+ * Checks:
+ * - `data` is a non-null object
+ * - `type`, `traceId`, `sessionId`, `source` are non-empty strings
+ * - `ts` is a finite number (Unix ms timestamp)
+ * - `payload` is present and is a non-null object
+ * - `version` (if present) has numeric `major`, `minor`, `patch` fields
+ *
+ * @param data - The raw persisted data to validate.
+ * @returns A ValidationResult with structured errors if any field is invalid.
+ */
+export function validateEventEnvelope(data) {
+    const errors = [];
+    if (data === null || typeof data !== 'object') {
+        errors.push({
+            path: '',
+            message: 'EventEnvelope must be a non-null object',
+            expected: 'object',
+            actual: data === null ? 'null' : typeof data,
+        });
+        return { valid: false, errors };
+    }
+    const record = data;
+    // Validate required string fields
+    for (const field of REQUIRED_STRING_FIELDS) {
+        const value = record[field];
+        if (typeof value !== 'string' || value.length === 0) {
+            errors.push({
+                path: field,
+                message: `Field '${field}' must be a non-empty string`,
+                expected: 'non-empty string',
+                actual: value === undefined ? 'undefined' : value === null ? 'null' : typeof value,
+            });
+        }
+    }
+    // Validate ts: finite number
+    const tsRaw = record['ts'];
+    if (typeof tsRaw !== 'number' || !Number.isFinite(tsRaw)) {
+        errors.push({
+            path: 'ts',
+            message: "Field 'ts' must be a finite number (Unix ms timestamp)",
+            expected: 'finite number',
+            actual: tsRaw === undefined ? 'undefined' : tsRaw === null ? 'null' : typeof tsRaw,
+        });
+    }
+    // Validate payload: non-null object
+    const payloadRaw = record['payload'];
+    if (payloadRaw === undefined || payloadRaw === null || typeof payloadRaw !== 'object') {
+        errors.push({
+            path: 'payload',
+            message: "Field 'payload' must be a non-null object",
+            expected: 'object',
+            actual: payloadRaw === undefined ? 'undefined' : payloadRaw === null ? 'null' : typeof payloadRaw,
+        });
+    }
+    // Detect version if present
+    let detectedVersion;
+    const versionRaw = record['version'];
+    if (versionRaw !== undefined && versionRaw !== null && typeof versionRaw === 'object') {
+        const v = versionRaw;
+        const allNumeric = typeof v['major'] === 'number' &&
+            typeof v['minor'] === 'number' &&
+            typeof v['patch'] === 'number';
+        if (allNumeric) {
+            detectedVersion = {
+                major: v['major'],
+                minor: v['minor'],
+                patch: v['patch'],
+            };
+        }
+        else {
+            errors.push({
+                path: 'version',
+                message: "Field 'version' must have numeric major, minor, patch components",
+                expected: '{ major: number, minor: number, patch: number }',
+                actual: (() => { try {
+                    return JSON.stringify(versionRaw);
+                }
+                catch {
+                    return String(versionRaw);
+                } })(),
+            });
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        version: detectedVersion,
+    };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Compatibility Contracts — Validators barrel
+ *
+ * Re-exports all runtime shape validators for the contract registry.
+ *
+ * @module contracts/validators
+ */
+export { validateRuntimeState } from './runtime-state.js';
+export { validateEventEnvelope } from './event-envelope.js';
+export { validateSession } from './session.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/validators/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

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

@@ -0,0 +1,10 @@
+/**
+ * Compatibility Contracts — Validators barrel
+ *
+ * Re-exports all runtime shape validators for the contract registry.
+ *
+ * @module contracts/validators
+ */
+export { validateRuntimeState } from './runtime-state.js';
+export { validateEventEnvelope } from './event-envelope.js';
+export { validateSession } from './session.js';

package/dist/_internal/platform/runtime/contracts/validators/runtime-state.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compatibility Contracts — RuntimeState Validator
+ *
+ * Performs runtime shape validation for the top-level RuntimeState snapshot schema.
+ * Returns a structured ValidationResult rather than throwing.
+ *
+ * @module contracts/validators/runtime-state
+ */
+import type { ValidationResult } from '../types.js';
+/**
+ * Validates that `data` conforms to the expected RuntimeState snapshot shape.
+ *
+ * Checks:
+ * - `data` is a non-null object
+ * - `version` is present and has numeric `major`, `minor`, `patch` fields
+ * - `domains` is present and is a non-null object
+ *
+ * @param data - The raw persisted data to validate.
+ * @returns A ValidationResult with `valid: true` if the shape is correct,
+ *   or `valid: false` with a list of errors if any required field is missing or malformed.
+ */
+export declare function validateRuntimeState(data: unknown): ValidationResult;
+//# sourceMappingURL=runtime-state.d.ts.map

package/dist/_internal/platform/runtime/contracts/validators/runtime-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-state.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/contracts/validators/runtime-state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAkC,MAAM,aAAa,CAAC;AAQpF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAgFpE"}