◎ OS PUB Apache 2.0 ← All specifications

P154 — AIEP — Schema Migration Without Integrity Loss Protocol

Publication Date: 2026-03-27 Status: Open Source Prior Art Disclosure Licence: Apache License 2.0 Author/Organisation: Phatfella Ltd Schema: AIEP_OS_SPEC_TEMPLATE v1.0.1 — https://aiep.dev/schemas/aiep-os-spec-template/v1.0.1

Framework Context

[0001] This disclosure operates within an Architected Instruction and Evidence Protocol (AIEP) environment as defined in United Kingdom patent application number GB2519711.2, filed 20 November 2025, the entire contents of which are incorporated herein by reference.

[0002] The present disclosure defines a versioned schema evolution protocol enabling EvidenceNode and EvidenceIndexEntry schemas to migrate to new versions while maintaining hash-verifiable integrity of all existing records and guaranteeing backward read compatibility for older nodes operating under the negotiated protocol profile (P153).

Field of the Disclosure

[0003] This disclosure relates to schema migration protocols for verifiable evidence record systems in governed artificial intelligence reasoning environments.

[0004] More particularly, the disclosure concerns a migration descriptor format, an in-place migration procedure, and a compatibility mapping layer that enables nodes on different schema versions to read and verify each other’s evidence records without data loss, field corruption, or hash invalidation.

Background

[0005] The AIEP evidence schema evolves over time as new evidence modalities are supported, new metadata fields are required, and new protocol capabilities are added. Schema evolution is a common source of interoperability failures in distributed systems: adding a required field breaks older clients; removing a field breaks clients that depend on it; renaming a field silently corrupts records that mapped the old name.

[0006] Evidence artefacts are cryptographically hash-bound (P133, P150). Any change to the byte representation of a stored artefact would invalidate its content_hash, breaking verifiability. Schema migrations must therefore define transformations that change the schema interpretation without changing the canonical byte representation on which the hash was computed.

[0007] No existing AIEP specification defines a migration descriptor format, the canonical byte representation rule that permits schema evolution without hash invalidation, or the compatibility mapping layer for cross-version reads.

Summary of the Disclosure

[0008] Schema Version Identifier: Each schema version is identified by a semantic version string. Every EvidenceNode and EvidenceIndexEntry carries a schema_version field. The canonical schema version is published at the .well-known/aiep/schema endpoint.

[0009] Migration Descriptor: A SchemaMigrationDescriptor is published for each schema version transition containing: from_version; to_version; migration_type (ADDITIVE, DEPRECATION, RENAME, RESTRUCTURE); field_changes (one per changed field with change_type, old_name, default_value, deprecation_reason); and hash_computation_unchanged — boolean true if the canonical hash-computation serialisation is unchanged across this migration.

[0010] Hash Preservation Rule: Schema migrations are designed so that hash_computation_unchanged = true wherever possible: hashes are computed over a declared hash_boundary field subset, and new fields are appended rather than inserted, preserving the byte sequence of hash-boundary fields.

[0011] In-Place Migration Procedure: A SchemaMigrationWorker adds defaults for new required fields, renames fields per the migration descriptor, appends a migration_record to each entry, writes back without modifying hash-boundary fields, and verifies that the stored content_hash remains valid by recomputing the hash over hash-boundary fields.

[0012] Backward Compatibility Mapping Layer: When a new-version node receives a record from an old-version node, the compatibility mapping layer reads the record’s schema_version, traverses the migration descriptor chain to map old field names to current names, and fills defaults for absent fields, preserving the sender’s declared schema_version.

[0013] Breaking Change Handling: Migrations with hash_computation_unchanged = false are classified as breaking versions. Evidence exchange sessions spanning a breaking version boundary require explicit compatibility shim negotiation in the CapabilityAdvertisement (P153).

Technical Effect

[0014] The hash-boundary design makes additive schema migrations hash-safe by construction, enabling the vast majority of schema evolution without invalidating existing evidence hashes.

[0015] Migration descriptors published at the well-known schema endpoint enable any node to self-upgrade its stored records with a deterministic in-place migration procedure.

[0016] The compatibility mapping layer in the receiving node allows heterogeneous schema versions to coexist in the network indefinitely, with each node reading foreign-version records through its local mapping layer.

Claims

A schema migration protocol for verifiable evidence records in a governed AI reasoning system, the protocol comprising: SchemaMigrationDescriptors published per schema version transition specifying field changes, migration type, and a hash_computation_unchanged flag; a hash-boundary declaration in each schema version identifying the stable field subset over which content hashes are computed; and an in-place migration procedure applying migrations without modifying hash-boundary fields, preserving content hash validity.
The protocol of claim 1, wherein a SchemaMigrationWorker performs in-place migration by adding default values for new fields, renaming fields per the migration descriptor, and appending a migration_record to each migrated entry, followed by verification that the stored content hash remains valid.
The protocol of claim 1, wherein a backward compatibility mapping layer reads a foreign-version record’s schema_version field, traverses the migration descriptor chain to map old field names to current field names, and fills default values for absent fields, without modifying the record’s declared schema_version.
The protocol of claim 1, wherein schema migrations classified as breaking versions — those where hash_computation_unchanged is false — require explicit compatibility shim negotiation before evidence exchange sessions are established between nodes on opposite sides of the breaking version boundary.

Brief Description of the Drawing

FIG. 1 — Schema migration chain: v1.0 → v1.1 (ADDITIVE) → v1.2 (DEPRECATION) → v2.0 (RESTRUCTURE/breaking) with hash_computation_unchanged flags.

FIG. 2 — Compatibility mapping layer: foreign-version record → schema_version read → migration descriptor chain lookup → field mapping → current-version in-memory representation.

Abstract

A schema migration protocol enables AIEP evidence schema versions to evolve while preserving content hash integrity. SchemaMigrationDescriptors specify field changes and a hash_computation_unchanged flag per version transition. Content hashes are computed over a declared hash-boundary field subset, making additive migrations hash-safe by design. An in-place SchemaMigrationWorker migrates records without modifying hash-boundary fields and verifies hash validity post-migration. A backward compatibility mapping layer enables new-version nodes to read old-version records through a field name mapping chain. Breaking version transitions require explicit compatibility shim negotiation.

Licence

Apache License 2.0 — https://www.apache.org/licenses/LICENSE-2.0