Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /dislovelhl_enhanced-agent-bus /schema_evolution.py
| """ | |
| ACGS-2 Enhanced Agent Bus - Schema Evolution | |
| Constitutional Hash: 608508a9bd224290 | |
| Versioned schema metadata and compatibility helpers for message evolution. | |
| """ | |
| from __future__ import annotations | |
| import hashlib | |
| import re | |
| from collections.abc import Callable | |
| from dataclasses import dataclass, field | |
| from enum import Enum | |
| from functools import total_ordering | |
| from pydantic import BaseModel, Field | |
| try: | |
| from enhanced_agent_bus._compat.constants import CONSTITUTIONAL_HASH | |
| except ImportError: | |
| CONSTITUTIONAL_HASH = "standalone" | |
| try: | |
| from .rust.fast_hash import fast_hash | |
| FAST_HASH_AVAILABLE = True | |
| except ImportError: # pragma: no cover - optional acceleration | |
| fast_hash = None | |
| FAST_HASH_AVAILABLE = False | |
| class SchemaCompatibility(str, Enum): | |
| BACKWARD = "backward" | |
| FORWARD = "forward" | |
| FULL = "full" | |
| class EvolutionType(str, Enum): | |
| ADD_FIELD = "add_field" | |
| REMOVE_FIELD = "remove_field" | |
| CHANGE_TYPE = "change_type" | |
| DEPRECATE_FIELD = "deprecate_field" | |
| class MigrationStatus(str, Enum): | |
| PENDING = "pending" | |
| REGISTERED = "registered" | |
| APPLIED = "applied" | |
| FAILED = "failed" | |
| class SchemaVersion: | |
| major: int | |
| minor: int | |
| patch: int | |
| prerelease: str = "" | |
| def parse(cls, value: str) -> "SchemaVersion": | |
| match = re.fullmatch(r"(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?", value) | |
| if match is None: | |
| raise ValueError(f"Invalid version format: {value}") | |
| return cls( | |
| major=int(match.group(1)), | |
| minor=int(match.group(2)), | |
| patch=int(match.group(3)), | |
| prerelease=match.group(4) or "", | |
| ) | |
| def __str__(self) -> str: | |
| suffix = f"-{self.prerelease}" if self.prerelease else "" | |
| return f"{self.major}.{self.minor}.{self.patch}{suffix}" | |
| def __lt__(self, other: object) -> bool: | |
| if not isinstance(other, SchemaVersion): | |
| return NotImplemented | |
| left = (self.major, self.minor, self.patch) | |
| right = (other.major, other.minor, other.patch) | |
| if left != right: | |
| return left < right | |
| if self.prerelease == other.prerelease: | |
| return False | |
| if not self.prerelease: | |
| return False | |
| if not other.prerelease: | |
| return True | |
| return self.prerelease < other.prerelease | |
| def is_compatible_with(self, other: "SchemaVersion", mode: SchemaCompatibility) -> bool: | |
| if mode == SchemaCompatibility.BACKWARD: | |
| return self.major == other.major and self >= other | |
| if mode == SchemaCompatibility.FORWARD: | |
| return self.major == other.major and self <= other | |
| return self.major == other.major and self.minor == other.minor | |
| class SchemaFieldDefinition: | |
| name: str | |
| field_type: str | |
| required: bool = True | |
| default: object | None = None | |
| deprecated: bool = False | |
| deprecated_since: str = "" | |
| class SchemaDefinition: | |
| schema_id: str | |
| name: str | |
| version: str | |
| fields: list[SchemaFieldDefinition] = field(default_factory=list) | |
| constitutional_hash: str = CONSTITUTIONAL_HASH | |
| deprecated: bool = False | |
| def __post_init__(self) -> None: | |
| if self.constitutional_hash != CONSTITUTIONAL_HASH: | |
| raise ValueError("Invalid constitutional hash") | |
| def get_version(self) -> SchemaVersion: | |
| return SchemaVersion.parse(self.version) | |
| def compute_fingerprint(self) -> str: | |
| payload = "|".join( | |
| [ | |
| self.name, | |
| self.version, | |
| self.constitutional_hash, | |
| *( | |
| f"{field.name}:{field.field_type}:{field.required}:" | |
| f"{field.default!r}:{field.deprecated}:{field.deprecated_since}" | |
| for field in self.fields | |
| ), | |
| ] | |
| ) | |
| if FAST_HASH_AVAILABLE and fast_hash is not None: | |
| return f"{fast_hash(payload):016x}" | |
| return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16] | |
| def get_required_fields(self) -> list[SchemaFieldDefinition]: | |
| return [field for field in self.fields if field.required] | |
| def get_optional_fields(self) -> list[SchemaFieldDefinition]: | |
| return [field for field in self.fields if not field.required] | |
| class SchemaEvolutionChange: | |
| change_id: str | |
| evolution_type: EvolutionType | |
| field_name: str | |
| old_value: object | None = None | |
| new_value: object | None = None | |
| is_breaking: bool = False | |
| description: str = "" | |
| class CompatibilityChecker: | |
| def __init__(self, compatibility_mode: SchemaCompatibility) -> None: | |
| self.compatibility_mode = compatibility_mode | |
| def check_compatibility( | |
| self, old_schema: SchemaDefinition, new_schema: SchemaDefinition | |
| ) -> tuple[bool, list[SchemaEvolutionChange]]: | |
| old_fields = {field.name: field for field in old_schema.fields} | |
| new_fields = {field.name: field for field in new_schema.fields} | |
| changes: list[SchemaEvolutionChange] = [] | |
| for name, field_info in new_fields.items(): | |
| if name not in old_fields: | |
| is_breaking = field_info.required and field_info.default is None | |
| changes.append( | |
| SchemaEvolutionChange( | |
| change_id=f"add_{name}", | |
| evolution_type=EvolutionType.ADD_FIELD, | |
| field_name=name, | |
| new_value=field_info.field_type, | |
| is_breaking=is_breaking, | |
| ) | |
| ) | |
| continue | |
| old_field = old_fields[name] | |
| if old_field.field_type != field_info.field_type: | |
| is_breaking = not self._is_type_change_compatible( | |
| old_field.field_type, field_info.field_type | |
| ) | |
| changes.append( | |
| SchemaEvolutionChange( | |
| change_id=f"change_type_{name}", | |
| evolution_type=EvolutionType.CHANGE_TYPE, | |
| field_name=name, | |
| old_value=old_field.field_type, | |
| new_value=field_info.field_type, | |
| is_breaking=is_breaking, | |
| ) | |
| ) | |
| if not old_field.deprecated and field_info.deprecated: | |
| changes.append( | |
| SchemaEvolutionChange( | |
| change_id=f"deprecate_{name}", | |
| evolution_type=EvolutionType.DEPRECATE_FIELD, | |
| field_name=name, | |
| old_value=False, | |
| new_value=True, | |
| is_breaking=False, | |
| ) | |
| ) | |
| for name, old_field_info in old_fields.items(): | |
| if name in new_fields: | |
| continue | |
| changes.append( | |
| SchemaEvolutionChange( | |
| change_id=f"remove_{name}", | |
| evolution_type=EvolutionType.REMOVE_FIELD, | |
| field_name=name, | |
| old_value=old_field_info.field_type, | |
| is_breaking=old_field_info.required, | |
| ) | |
| ) | |
| return self._evaluate(changes), changes | |
| def _evaluate(self, changes: list[SchemaEvolutionChange]) -> bool: | |
| if self.compatibility_mode == SchemaCompatibility.BACKWARD: | |
| return not any( | |
| change.evolution_type == EvolutionType.ADD_FIELD | |
| and change.is_breaking | |
| or change.evolution_type == EvolutionType.CHANGE_TYPE | |
| and change.is_breaking | |
| for change in changes | |
| ) | |
| if self.compatibility_mode == SchemaCompatibility.FORWARD: | |
| return not any( | |
| change.evolution_type == EvolutionType.REMOVE_FIELD | |
| and change.is_breaking | |
| or change.evolution_type == EvolutionType.CHANGE_TYPE | |
| and change.is_breaking | |
| for change in changes | |
| ) | |
| return not any(change.is_breaking for change in changes) | |
| def _is_type_change_compatible(old_type: str, new_type: str) -> bool: | |
| if old_type == new_type: | |
| return True | |
| compatible_pairs = { | |
| ("int", "float"), | |
| } | |
| return (old_type, new_type) in compatible_pairs | |
| class SchemaMigration: | |
| migration_id: str | |
| from_version: str | |
| to_version: str | |
| schema_name: str | |
| changes: list[SchemaEvolutionChange] = field(default_factory=list) | |
| status: MigrationStatus = MigrationStatus.PENDING | |
| constitutional_hash: str = CONSTITUTIONAL_HASH | |
| rollback_supported: bool = True | |
| class SchemaRegistry: | |
| def __init__( | |
| self, compatibility_mode: SchemaCompatibility = SchemaCompatibility.BACKWARD | |
| ) -> None: | |
| self.compatibility_mode = compatibility_mode | |
| self._schemas: dict[str, dict[str, SchemaDefinition]] = {} | |
| def register( | |
| self, schema: SchemaDefinition, check_compatibility: bool = True | |
| ) -> tuple[bool, str]: | |
| versions = self._schemas.setdefault(schema.name, {}) | |
| if schema.version in versions: | |
| return False, f"Schema {schema.name} version {schema.version} already exists" | |
| latest = self.get_schema(schema.name) | |
| if check_compatibility and latest is not None: | |
| checker = CompatibilityChecker(self.compatibility_mode) | |
| is_compatible, _changes = checker.check_compatibility(latest, schema) | |
| if not is_compatible: | |
| return False, f"Schema {schema.name} version {schema.version} is not compatible" | |
| versions[schema.version] = schema | |
| return True, f"Schema {schema.name} version {schema.version} registered successfully" | |
| def get_schema(self, schema_name: str, version: str | None = None) -> SchemaDefinition | None: | |
| versions = self._schemas.get(schema_name, {}) | |
| if not versions: | |
| return None | |
| if version is None: | |
| latest_version = self.get_latest_version(schema_name) | |
| return versions.get(latest_version) if latest_version is not None else None | |
| return versions.get(version) | |
| def get_all_versions(self, schema_name: str) -> list[str]: | |
| versions = self._schemas.get(schema_name, {}) | |
| return [str(version) for version in sorted(SchemaVersion.parse(v) for v in versions)] | |
| def get_latest_version(self, schema_name: str) -> str | None: | |
| versions = self.get_all_versions(schema_name) | |
| return versions[-1] if versions else None | |
| def deprecate_schema(self, schema_name: str, version: str) -> bool: | |
| schema = self.get_schema(schema_name, version) | |
| if schema is None: | |
| return False | |
| schema.deprecated = True | |
| return True | |
| class SchemaMigrator: | |
| def __init__(self, registry: SchemaRegistry) -> None: | |
| self.registry = registry | |
| self._migrations: dict[tuple[str, str, str], SchemaMigration] = {} | |
| self._transforms: dict[ | |
| tuple[str, str, str], Callable[[dict[str, object]], dict[str, object]] | |
| ] = {} | |
| def create_migration( | |
| self, schema_name: str, from_version: str, to_version: str | |
| ) -> SchemaMigration: | |
| old_schema = self.registry.get_schema(schema_name, from_version) | |
| new_schema = self.registry.get_schema(schema_name, to_version) | |
| if old_schema is None or new_schema is None: | |
| raise ValueError("Schema versions must exist before creating a migration") | |
| checker = CompatibilityChecker(self.registry.compatibility_mode) | |
| _is_compatible, changes = checker.check_compatibility(old_schema, new_schema) | |
| migration = SchemaMigration( | |
| migration_id=f"{schema_name}:{from_version}->{to_version}", | |
| from_version=from_version, | |
| to_version=to_version, | |
| schema_name=schema_name, | |
| changes=changes, | |
| rollback_supported=not any(change.is_breaking for change in changes), | |
| ) | |
| self._migrations[(schema_name, from_version, to_version)] = migration | |
| return migration | |
| def register_migration( | |
| self, | |
| migration: SchemaMigration, | |
| transform: Callable[[dict[str, object]], dict[str, object]], | |
| ) -> None: | |
| key = (migration.schema_name, migration.from_version, migration.to_version) | |
| migration.status = MigrationStatus.REGISTERED | |
| self._migrations[key] = migration | |
| self._transforms[key] = transform | |
| def get_migration_path(self, schema_name: str, from_version: str, to_version: str) -> list[str]: | |
| if self.registry.get_schema(schema_name, from_version) is None: | |
| return [] | |
| if self.registry.get_schema(schema_name, to_version) is None: | |
| return [] | |
| return [from_version, to_version] | |
| def migrate_data( | |
| self, | |
| data: dict[str, object], | |
| schema_name: str, | |
| from_version: str, | |
| to_version: str, | |
| ) -> tuple[dict[str, object], bool]: | |
| old_schema = self.registry.get_schema(schema_name, from_version) | |
| new_schema = self.registry.get_schema(schema_name, to_version) | |
| if old_schema is None or new_schema is None: | |
| return data, False | |
| key = (schema_name, from_version, to_version) | |
| migration = self._migrations.get(key) or self.create_migration( | |
| schema_name, from_version, to_version | |
| ) | |
| transformed = dict(data) | |
| transform = self._transforms.get(key) | |
| if transform is not None: | |
| transformed = transform(transformed) | |
| else: | |
| new_field_map = {field.name: field for field in new_schema.fields} | |
| for field_name, field in new_field_map.items(): | |
| if field_name not in transformed and field.default is not None: | |
| transformed[field_name] = field.default | |
| transformed["_schema_version"] = to_version | |
| transformed["_constitutional_hash"] = CONSTITUTIONAL_HASH | |
| migration.status = MigrationStatus.APPLIED | |
| return transformed, True | |
| class VersionedMessageBase(BaseModel): | |
| constitutional_hash: str = Field(default=CONSTITUTIONAL_HASH) | |
| def get_schema_version(self) -> str: | |
| return getattr(type(self), "_schema_version", "1.0.0") | |
| def get_schema_name(self) -> str: | |
| return getattr(type(self), "_schema_name", type(self).__name__) | |
| AGENT_MESSAGE_SCHEMA_V1 = SchemaDefinition( | |
| schema_id="agent_message_v1", | |
| name="AgentMessage", | |
| version="1.0.0", | |
| fields=[ | |
| SchemaFieldDefinition(name="message_id", field_type="str"), | |
| SchemaFieldDefinition(name="conversation_id", field_type="str"), | |
| SchemaFieldDefinition(name="content", field_type="dict"), | |
| SchemaFieldDefinition(name="from_agent", field_type="str"), | |
| SchemaFieldDefinition(name="to_agent", field_type="str"), | |
| SchemaFieldDefinition(name="message_type", field_type="str"), | |
| SchemaFieldDefinition(name="constitutional_hash", field_type="str"), | |
| ], | |
| ) | |
| AGENT_MESSAGE_SCHEMA_V1_1 = SchemaDefinition( | |
| schema_id="agent_message_v1_1", | |
| name="AgentMessage", | |
| version="1.1.0", | |
| fields=[ | |
| *AGENT_MESSAGE_SCHEMA_V1.fields, | |
| SchemaFieldDefinition(name="session_id", field_type="str", required=False), | |
| SchemaFieldDefinition(name="session_context", field_type="dict", required=False), | |
| ], | |
| ) | |
| AGENT_MESSAGE_SCHEMA_V1_2 = SchemaDefinition( | |
| schema_id="agent_message_v1_2", | |
| name="AgentMessage", | |
| version="1.2.0", | |
| fields=[ | |
| *AGENT_MESSAGE_SCHEMA_V1_1.fields, | |
| SchemaFieldDefinition(name="pqc_signature", field_type="str", required=False), | |
| SchemaFieldDefinition(name="pqc_public_key", field_type="str", required=False), | |
| SchemaFieldDefinition(name="pqc_algorithm", field_type="str", required=False), | |
| ], | |
| ) | |
| def create_default_registry() -> SchemaRegistry: | |
| registry = SchemaRegistry(compatibility_mode=SchemaCompatibility.BACKWARD) | |
| for schema in ( | |
| AGENT_MESSAGE_SCHEMA_V1, | |
| AGENT_MESSAGE_SCHEMA_V1_1, | |
| AGENT_MESSAGE_SCHEMA_V1_2, | |
| ): | |
| registry.register(schema, check_compatibility=False) | |
| return registry | |
| __all__ = [ | |
| "AGENT_MESSAGE_SCHEMA_V1", | |
| "AGENT_MESSAGE_SCHEMA_V1_1", | |
| "AGENT_MESSAGE_SCHEMA_V1_2", | |
| "CONSTITUTIONAL_HASH", | |
| "FAST_HASH_AVAILABLE", | |
| "CompatibilityChecker", | |
| "EvolutionType", | |
| "MigrationStatus", | |
| "SchemaCompatibility", | |
| "SchemaDefinition", | |
| "SchemaEvolutionChange", | |
| "SchemaFieldDefinition", | |
| "SchemaMigration", | |
| "SchemaMigrator", | |
| "SchemaRegistry", | |
| "SchemaVersion", | |
| "VersionedMessageBase", | |
| "create_default_registry", | |
| "fast_hash", | |
| ] | |
Xet Storage Details
- Size:
- 16.9 kB
- Xet hash:
- 6a498fb9f4c7c66235b8e8d567f3d030c9e88faa2b5f04e22e49941dfdad9440
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.