Contents
Introduction
Define the replacement meanings
Preserve what the old records cannot establish
Reader and writer compatibility for applications and agents
Expected query results and agent behaviour
Releasing the migration in an agent workflow
Keep historical decisions reconstructable
Roll back without discarding evidence
1 Introduction
Suppose an application uses an OWNS relationship in a Labelled Property Graph (LPG) to identify companies controlled by a particular party. One source uses the relationship for equity ownership, another for voting rights, and an older import leaves the distinction unexplained. The query runs successfully, but its results depend on which meaning happened to enter the graph.
Replacing OWNS with separate relationships requires changes to the applications and agents that consume it. Some answers will change, and some records will no longer support an answer. The migration needs to preserve those gaps while keeping earlier decisions explainable.
In From LPG to GraphRAG: The Minimum Semantic Contract, I defined the meanings, evidence requirements and retrieval rules a runtime may trust [1]. The Missing Half of Enterprise Semantics: What the Agent Must Not Do examined limits on their use [2]. Here, those limits prevent an ambiguous percentage from becoming evidence of voting control.
When the Rules Change, Which Decisions Need Reviewing? described when changed meanings require reassessment [3]. This example adds the release procedure: define the replacement relationships, test expected query changes and account for readers that continue using the old contract during deployment.
2 Define the replacement meanings
The existing template uses OWNS.percentage > 50 to select companies. Contract version 2 replaces that test with a question about voting rights, so it needs two separately defined relationships from a Party to a Company.
The party is entitled to direct the recorded voting rights in the company.
Its share of exercisable votes for the stated voting scope.
The example uses one equity class and one voting pool. Assume that accepted voting mandates explain the unequal equity and voting percentages for Birch and Dune in section 5. Each assertion records direct holdings or authority over specified votes, with evidence, a stable identifier, its measurement basis or voting scope, and temporal history. Beneficial ownership, multiple classes and conditional or indirect rights would require further definitions.
VOTING_CONTROL can record 20 per cent of the votes; the relationship alone does not assert control of the company. The application separately tests for more than 50 per cent of the voting pool. This is an example threshold, not a general legal definition of corporate control. Equity alone does not satisfy it, and the contract does not authorise inferred indirect control through a chain of relationships.
Labels need the same care. Adding Party to existing person and organisation nodes requires an approved membership rule and stable entity identities. Renaming Company to LegalEntity may broaden the population, so it cannot be treated as a spelling change. Even an added label can affect readers that inspect complete label sets.
PG-Schema provides a formal foundation for this discussion. Its PG-Types component describes node and edge types, including allowed labels, properties and endpoint types; PG-Keys supplies integrity constraints such as keys and participation constraints [4]. These concepts help separate structural requirements from the wider agreement about evidence and interpretation.
PG-Schema is a research proposal, and its capabilities should not be assumed available in every database. The implementation must identify which requirements the chosen engine enforces and which need ingestion checks, application validation or release tests. The procedure proposed here does not assume that PG-Schema supplies migration orchestration, proves source evidence or guarantees query compatibility.
3 Preserve what the old records cannot establish
An old OWNS record containing percentage: 60 does not contain enough information to choose between the new relationships. Creating both would manufacture two precise assertions from one ambiguous record.
The migration therefore reviews evidence separately for equity and voting rights. Where the source establishes only equity ownership, it can create an accepted equity assertion while leaving voting control unresolved. Where both are supported, it can create both with their respective evidence. Conflicting sources remain visible as a conflict pending adjudication.
I would preserve the original as a versioned legacy assertion and keep a mapping record for each migration outcome. That record identifies the source version, resulting assertion versions, mapping rule and outcome for each dimension. It distinguishes insufficient evidence from a mapping that has not yet been processed.
Every legacy record can have an accounted-for outcome while some business questions remain unresolved. Report processing coverage separately from the proportion supported for each new meaning, so a completed backfill does not imply complete knowledge.
Missing voting evidence must not become a zero percentage or a negative assertion. The assessment interface needs separate outcomes for a condition established, a condition not met on sufficient evidence, and a condition unresolved. A validation failure is an additional operational state, rather than another way to say that the party has no voting rights.
For richer evidence, an assertion node can hold source versions, qualifications and review history, with derived relationships supporting common traversals. If the chosen implementation stores assertions directly on relationships, it still needs equivalent identity, provenance and version handling. The contract should state how a query reaches those records.
4 Reader and writer compatibility for applications and agents
An agent that calls a graph tool is a reader even when it never sees the underlying query. Its interpretation depends on the tool description, returned fields and instructions retained in its context. If it submits extracted assertions through a write interface, it also participates in the writer contract.
The replacement of OWNS is a breaking semantic change, even if the database deployment only adds structures. Applications and agent hosts must explicitly adopt version 2. Here, a reader version means the contract implemented by the consuming workflow and its tools, rather than the version number of a language model.
The release manifest lists immutable versions of the contract, mappings, rules, query templates, tool definitions, query examples, GraphRAG summaries and the agent configuration used in evaluation. It identifies their data generation. Readers and decision records refer to this manifest instead of assembling their own combinations.
During deployment, the supported combinations are as follows.
Use the new meanings, required evidence and published result states.
An ambiguous legacy contract may have no faithful compatibility projection. A single OWNS.percentage cannot represent 70 per cent equity and 20 per cent voting rights simultaneously. Affected consumers need an upgrade or a restriction before cutover.
Agent hosts should bind each assessment to a supported contract and template version. The service must reject unsupported combinations, since a prompt asking the model to use the latest definition does not enforce compatibility. An agent that prepared a plan before cutover must finish against a still-supported version or obtain a fresh assessment before acting.
Keeping old and new relationships together can also affect broad traversals and counts. Each reader needs a defined view or template boundary to prevent duplicate interpretation. An agent allowed to generate queries needs equivalent checks on the proposed query before execution.
I would derive the permitted representations from one authoritative assertion record or durable change stream. Separate writes require transactional coordination or a durable outbox, with idempotent processing and reconciliation. Assertions proposed by an agent pass through the same evidence and validation rules as other incoming records.
When evidence is superseded, re-evaluate dependent assertions for the affected time interval. Retire any assertion version that no longer meets the evidence rules, while keeping its history. Independent accepted evidence may support the same result in a new assertion version. A correction can change provenance or part of an interval without making the whole result unresolved.
5 Expected query results and agent behaviour
A semantic release needs a statement of its expected answer changes before the migration runs.
Consider five fictional companies assessed for the same party, effective date and source snapshot. For this fixture, the confirmed voting percentages are complete for that party within the stated voting pool. The old template, legacy_majority@1, selects companies where OWNS.percentage > 50. The new template, voting_majority@2, assesses the same threshold using accepted voting evidence.
The selected count falls from four to two, but a count-only check could pass with the wrong companies. Cedar and Elm must remain in the unresolved output.
This table is part of the release specification. Each changed outcome needs a reason tied to the new definition, evidence or mapping. Any additional difference requires investigation, including changes in returned evidence and uncertainty, even when the selected company stays the same.
The assessment must start from a defined candidate population. Starting only from VOTING_CONTROL edges would silently omit Cedar and Elm, making missing evidence indistinguishable from an assessed negative.
An agent consuming these results needs an explicit outcome for each candidate. For example, the application can return established, not_met or unresolved, accompanied by a reason, evidence references and the assessment versions. An unresolved assessment is a valid business result; retrying the same query will not supply the missing evidence.
The tests must separate the assessment from the policy decision. Meeting the voting threshold does not alone authorise action. For Cedar and Elm, this example’s policy permits only evidence collection or authorised review. Other policies may reject or hold requests with missing evidence, or permit action through an authorised exception. Record the decision, governing policy and reason separately. A decision must not turn an unresolved assessment into a factual positive or negative.
Each query template fixes its query content, parameters, temporal filters, result shape and treatment of incomplete evidence. Its release manifest records the contract, mapping and rule dependencies. Agent-facing tools must preserve these commitments.
Cached answers and retrieved memories need provenance that identifies the release and evidence used. Cache keys should include the contract and relevant data generation alongside the request and permission scope.
6 Releasing the migration in an agent workflow
The release includes the tools that agents discover and the workflows that use their results. An old tool can remain available for an approved version 1 workflow. Deployment is incomplete when a workflow can select an unsupported contract or interpret a result under the wrong meaning.
The Model Context Protocol (MCP) is one possible interface. An MCP server can expose named tools with input schemas and structured results, optionally described by output schemas [6]. A tool such as assess_voting_control_v2 could accept a party, candidate companies and assessment dates, then call the approved template. Its result could include each outcome, supporting evidence and the contract version used.
These names and result fields are application design choices. The service must enforce the business contract and the caller’s permissions; adopting MCP does not provide those controls automatically. The MCP protocol version is also separate from the semantic contract version. Changing the meaning behind an unchanged tool name remains a compatibility problem.
I would use the following release sequence.
1. Inventory consumers and capture a baseline. Include agent hosts, tool catalogues, saved plans and scheduled runs, alongside reports and applications. Record representative outputs against a reproducible snapshot. Assign responsibility for approving meanings, release versions and changed outcomes.
2. Deploy the new structures, write validation and tools alongside permitted legacy interfaces. Keep agent-proposed assertions in review until evidence rules are satisfied. Advertise supported tools, mark planned retirements and reject unsupported calls at the service boundary. A deprecation note cannot enforce these restrictions.
3. Backfill from a consistent snapshot while capturing later changes. Record each mapping outcome, including unresolved cases. Use stable identifiers, idempotent processing and reconciliation to make retries safe. Test delayed corrections, duplicated events and a worker stopped between writes. Also test withdrawal of one source when independent evidence still supports the result.
4. Compare both interpretations against equivalent source states, dates and access scopes in a test environment with external actions disabled. Verify the table’s five outcomes and whether agents preserve uncertainty in explanations and tool choices. Repeat runs to expose variable plans; service rules must block forbidden actions regardless of the model’s response. Check structural constraints, temporal boundaries and operating latency.
5. Promote an identified release to a bounded group. Catch up to the declared change watermark before switching. Keep existing runs on a permitted combination or stop them for reassessment. Define when the service accepts an action for execution, binding acceptance to the checked assessment, evidence revisions, policy and permissions. Use transactional or conditional acceptance where available, because evidence or permissions can change between a separate check and acceptance. Record remaining limits for external systems. Make action requests idempotent so a lost response does not cause duplicate effects.
6. Retire legacy interfaces after checking actual usage. Refresh tool catalogues and invalidate affected cached results. Identify resumable runs that depend on old versions, and retain their decision records as described in section 7. Remove compatibility structures after the rollback window and applicable retention period.
Promotion requires explained result differences and complete accounting for source records. The release owner also needs an accepted level of unresolved coverage and processing lag. Unexpected actions, lost lineage or unexplained differences stop the rollout, even when the database migration itself completed successfully.
7 Keep historical decisions reconstructable
Suppose an earlier decision concerning Elm relied on OWNS.percentage = 65. After migration, the current assessment of voting control is unresolved. The original decision should remain attached to the interpretation and evidence actually used at the time.
Each decision record should reference the release manifest and the immutable input assertions and source material used. For agent workflows, retain tool calls and results, access scope and reviewer interventions. Include any run-specific configuration that differs from the evaluated release. Overwritten definitions or data cannot reconstruct a decision.
Time requires two independent questions: when did the asserted relationship apply, and when was that version recorded in the system? This is the distinction captured by bitemporal history [5]. Receipt and approval times may require separate fields. Reconstructing a decision uses the appropriate historical data and interpretation; reassessing the same effective date with later evidence produces a new assessment.
Impact analysis should follow dependencies on changed assertions, mappings and templates, while also rerunning candidate discovery. Dune illustrates why existing decision links are insufficient: the new interpretation can bring a company into the selected population. Decisions based on an asserted absence or completeness assumption need attention as well.
Where a language model produced an explanation, retain that explanation and its supporting context. Rerunning a versioned retrieval process does not guarantee identical generated wording.
8 Roll back without discarding evidence
Rollback becomes harder as soon as version 2 accepts information that version 1 cannot represent. Returning to one percentage would lose the distinction between Birch’s equity interest and its voting rights.
Preserve authoritative assertion history and writes accepted since cutover. The rollback plan should identify the retained release, data view and routing to restore together, and the point beyond which reverse conversion loses meaning. Agent runs prepared under the withdrawn release need reassessment.
Identify pending actions to cancel and completed external actions that require correction or review. Restoring a graph view does not reverse an external submission.
During the reversible window, an operational failure may be handled by routing readers to a retained compatible view while repairing or rebuilding the new projection. If new records cannot be expressed through the old interface, affected operations must pause or return an explicit unsupported state. Restoring a pre-release backup alone would discard accepted writes unless they were captured and replayed safely.
A semantic defect requires additional care. If the new mapping assigned a voting percentage without evidence, the repair must withdraw or supersede the faulty assertion, invalidate affected derived results and identify decisions that used it. Simply restarting the old application leaves those consequences unresolved.
The old interpretation may itself be known to be unsuitable for current decisions. In that case, operational recovery should preserve access to evidence while suspending the affected decision path. A technical rollback cannot make an unsupported interpretation trustworthy again.
Summary
The release specification should explain each change in the company table and preserve unresolved results through the query interface and agent workflow. Decisions must retain the evidence, interpretation and policy used, including any authorised exception.
The migration is complete when every source record has an explained outcome and supported consumers behave as specified. Some questions can remain unresolved because a clearer model cannot supply missing evidence.
References
[1] Sergey Vasiliev. From LPG to GraphRAG: The Minimum Semantic Contract.
[2] Sergey Vasiliev. The Missing Half of Enterprise Semantics: What the Agent Must Not Do.
[3] Sergey Vasiliev. When the Rules Change, Which Decisions Need Reviewing?
[4] Renzo Angles and colleagues. PG-Schema: Schemas for Property Graphs. Proceedings of the ACM on Management of Data, 2023.
https://arxiv.org/abs/2211.10962
[5] Martin Fowler. Bitemporal History.
https://martinfowler.com/articles/bitemporal-history.html
[6] Model Context Protocol. Tools specification, revision 2026-07-28.
https://modelcontextprotocol.io/specification/2026-07-28/server/tools
