Auto-Commit Inverse SmartLinks During Relationship Persistence (Commit Pass 2)

[owleyeview]

1. Summary

Extend Pass 2 of commit_functions::commit() so that when a declared relationship is persisted as a SmartLink, the commit logic also resolves and persists the corresponding inverse SmartLink automatically.

This enforces the MAP schema contract that all declared relationships are bidirectional and materialized, and ensures graph traversal works correctly from both directions.

---

2. Problem Statement

The MAP type system defines DeclaredRelationshipType and InverseRelationshipType as a paired schema contract:

• A declared relationship links to its inverse via HasInverse
• The inverse links back via InverseOf
• This guarantees bidirectional traversal of relationships

However, Pass 2 of commit_functions::commit() currently:

• Persists only forward SmartLinks from the declaring side
• Does not resolve or persist inverse relationships
• Does not enforce the schema requirement that inverses must exist

As a result:

• Graph traversal from the target side may fail silently
• Schema guarantees are not enforced at persistence time
• Relationship consistency depends on caller behavior (which is incorrect)

Importantly:

Inverse relationships are not directly writable via the MAP API

Therefore:

• Callers cannot and should not stage inverse relationships
• Commit-time population is the only valid mechanism for materializing inverse links
• Missing inverses represent a schema contract violation

---

3. Scope

This issue focuses exclusively on:

• Resolving inverse relationship names from the type system
• Persisting inverse SmartLinks during Pass 2
• Enforcing declaring-side-only mutation semantics

This issue does not include:

• Changes to the StagedHolon state machine
• Relationship source anchoring refinements (see Issue 2)
• Duplicate detection or idempotency behavior (see Issue 3)

---

4. Proposed Solution

4.1 Commit-Side Inverse Resolution

For each declared relationship collection being committed:

1. Determine the source LocalId used for forward SmartLink persistence
2. Follow DescribedBy to the source holon’s TypeDescriptor
3. Follow InstanceRelationships to candidate DeclaredRelationshipType descriptors
4. Match the relationship name against the descriptor’s type_name
5. Follow HasInverse to the corresponding InverseRelationshipType
6. Read the inverse descriptor’s type_name to determine the inverse relationship name
7. For each forward relationship member:
   • Persist the forward SmartLink
   • Persist the inverse SmartLink with endpoints reversed

---

4.2 Declaring-Side-Only Mutation Rule

• Relationship mutations originate only from the declaring (forward) side
• Inverse relationships are never staged or directly written by callers
• Commit is responsible for inverse materialization

---

4.3 Source Selection (Current Behavior)

This issue reuses the existing logic for determining the source LocalId of forward SmartLinks.

⚠️ Note:

• This behavior will be refined in Issue 2, which introduces explicit staged states (ForUpdateNewVersion, ForUpdateGraphOnly) and a formal relationship anchoring rule
• When Issue 2 lands, both forward and inverse persistence must derive their source from that rule rather than assuming the staged holon is always the source

---

4.4 Bootstrap Safety

Inverse resolution must work when schema holons are:

• staged (during bootstrap), or
• already persisted

Traversal should:

• read staged relationship maps when available
• fall back to persisted graph traversal otherwise

The invariant is:

Schema closure must be resolvable from staged or saved state

---

4.5 Schema Invariant

All DeclaredRelationshipType descriptors are expected to have an inverse.

If:

• a declared relationship is matched, and
• no HasInverse target can be resolved

then:

• this must be treated as a schema error, not silently ignored

---

4.6 External Target Constraint

Inverse persistence is only valid when the target holon is local.

If a relationship target resolves to a non-local holon:

• forward SmartLink may still be written (if supported by current logic)
• inverse SmartLink must not be written locally

This defines a boundary of schema contract enforcement.

---

5. Scope and Impact

Component	File(s)	Impact
Commit Pass 2	commit_functions.rs	Primary implementation site
SmartLink persistence	smartlink_adapter.rs	Likely unchanged
Type graph traversal	descriptor resolution logic	Extended for inverse lookup

Out of scope:

• StagedHolon state model changes (Issue 2)
• Duplicate detection and idempotency (Issue 3)
• Inverse deletion semantics
• Cardinality enforcement
• External/proxied inverse propagation

---

6. Testing Considerations

• Verify forward + inverse traversal for committed relationships
• Verify inverse resolution works with staged schema (bootstrap)
• Verify inverse resolution works with persisted schema
• Verify missing HasInverse produces a schema error
• Verify external targets do not cause commit failure

---

7. Definition of Done

• Declared relationships automatically produce inverse SmartLinks at commit
• Inverse relationships are never staged or directly written by callers
• Inverse resolution works against both staged and persisted schema
• Missing HasInverse is treated as a schema error
• External targets do not trigger invalid inverse writes
• Existing tests pass without regression
• At least one end-to-end test validates bidirectional traversal after commit

---

8. Key Design Principles

• Inverse relationships are schema-enforced, not caller-supplied
• All mutations originate from the declaring side
• Commit enforces schema contracts, not just mechanical persistence
• Inverse persistence must mirror forward persistence using the same resolved source

[evomimic]

NOTE: This comment applies to the initial Issue Description created on April 8, 2026. The issue description has since been updated to reflect this feedback.

Clarifications & Corrections to Issue Description

While reviewing this issue in the context of recent work on commit semantics, staging behavior, and validation, several important gaps and inaccuracies have emerged in the current description. I plan to update the description accordingly. For now, here is a summary of the key issues, tied to the relevant sections:

---

1. Mischaracterization of Inverse Persistence as a Convenience

Section: 2. Problem Statement

The current description frames inverse SmartLink creation as a convenience (“removes the need for callers to manually stage inverse relationships”).

This is incorrect. By design, inverse relationships are not directly writable via the MAP API. Therefore, commit-time population is the only valid mechanism by which inverse relationships can be materialized.

Implication:
This is not an enhancement but enforcement of a schema-level contract. Missing inverses should be treated as a correctness failure, not a caller omission.

---

2. Incorrect Assumption that Callers May Stage Inverses

Section: 2. Problem Statement, 4. Proposed Solution

The description assumes that callers can and sometimes should stage inverse relationships. This contradicts the intended model.

Correction:

• All relationship mutations must originate from the declaring (forward) side only
• Inverse relationships must be derived and persisted automatically at commit

---

3. Lack of Distinction Between Definitional and Non-Definitional Relationships

Section: 4. Proposed Solution, 5. Scope and Impact

The current design assumes uniform handling of all declared relationships.

However, MAP distinguishes:

• Definitional relationships → part of holon identity (require staging + versioning)
• Non-definitional relationships → graph-level associations (do not require new holon version)

Implication:
Commit behavior must account for this distinction, particularly:

• Whether a new holon version is required
• Whether relationships are anchored to the predecessor or the new version
• Whether staging is being used as a versioning mechanism or as a mutation context

---

4. Missing Rule for Relationship Source Resolution

Section: 4. Proposed Solution

The description does not specify how to determine which holon version a new relationship should attach to when a staged holon may or may not produce a new version.

Correction:
Introduce a deterministic rule:

• If the staged holon produces a new version → relationships attach to the new version
• Otherwise → relationships attach to the existing (predecessor) holon

Implication:
Relationship intent is transaction-scoped and resolved at commit time, avoiding premature binding and ambiguity.

---

5. Overlooking Uniqueness Semantics and Race Conditions

Section: 6. Testing Considerations

The current description does not address duplicate relationship handling.

Clarification:

• For newly created holons and staged clones, duplicate targets can be reliably detected and rejected in the nursery
• The only remaining risk is a narrow race condition when adding non-definitional relationships to an unchanged saved holon

Correction:

• Enforce strict duplicate checks at add-time in the nursery
• Apply idempotent duplicate suppression at commit for persisted SmartLinks

---

6. Missing Pre-Commit Nursery Responsibilities (Duplicate Detection & Idempotency)

Section: 4. Proposed Solution

The current design places all responsibility for relationship correctness at commit time.

Correction:
Some logic must be pushed earlier into nursery-level mutation functions, especially:

• add_related_holon(...) should:
  • detect and reject duplicate targets within the staged relationship set
  • behave idempotently when the same relationship is added multiple times within a transaction

Implication:

• Nursery functions become the primary enforcement point for local relationship invariants
• Commit logic serves as a final reconciliation layer (including race-condition handling), not the first line of defense

---

7. Incomplete Treatment of Staging Semantics

Section: 4. Proposed Solution

The description assumes staging is purely for holon mutation.

Clarification:
Staging also functions as a transactional mutation context for relationships, even when no new holon version is ultimately produced.

Implication:
A staged holon may:

• produce a new version (definitional changes), or
• act solely as a context for graph mutations (non-definitional relationships)

Commit logic must account for both outcomes explicitly.

---

8. External Target Constraint Needs Stronger Framing

Section: 4. Proposed Solution (External Target Constraint)

The current description treats inability to write inverses for external targets as a limitation.

Clarification:
This is not just a limitation but a boundary of schema contract enforcement. If inverse materialization cannot occur, the system cannot fully satisfy the declared relationship contract locally.

Implication:
This may require stricter handling or explicit deferral semantics rather than silent omission.

---

These corrections will be incorporated into a revised issue description that more accurately reflects MAP’s relationship model, staging semantics, and commit-time responsibilities.

[owleyeview]

Proposal: Split Into Three Issues

This issue covers three distinct concerns that have different scopes, different code surfaces, and no hard implementation dependencies between them. Bundling them into one ticket makes it difficult to scope, estimate, and close. I propose splitting into three issues and implementing in this order:

Issue 1: Auto-Commit Inverse SmartLinks During Relationship Persistence (Pass 2)

Scope: Extend commit_functions::commit() Pass 2 to resolve and persist inverse SmartLinks automatically when committing declared relationships.

What it covers:

• Schema traversal: DescribedBy → InstanceRelationships → match by name → HasInverse → InverseRelationshipType.type_name
• Traversal works against staged relationship maps (bootstrap) and DHT SmartLinks (post-bootstrap)
• Missing HasInverse treated as a schema-closure error
• External targets excluded from inverse auto-write (forward link still written)
• Declaring-side-only mutation rule: inverse links are materialized at commit, never staged by callers

Primary files: commit_functions.rs
Why first: This is the original motivating problem — graph traversal from the target side silently fails today. It can ship against the current StagedState model without any staging refactor. The source LocalId for both forward and inverse SmartLinks is already available from the Committed(local_id) state after Pass 1.

Issue 2: Action-Oriented StagedHolon States for Versioning vs. Graph-Only Mutation

Scope: Refine StagedState to distinguish definitional changes (requiring a new holon version) from non-definitional graph mutations (relationship-only, no new version).

What it covers:

• New states: ForUpdateNewVersion, ForUpdateGraphOnly (or similar naming)
• State transition rules: non-definitional mutations don't escalate to versioning; definitional mutations dominate
• Deterministic relationship anchoring: new version → attach to new version; graph-only → attach to existing holon
• Commit Pass 1 behavior driven by state

Primary files: staged_holon.rs, nursery.rs, commit_functions.rs (Pass 1)
Why second: This is a deeper change to the staging model that touches the mutation facade, nursery, and commit Pass 1. Issue 1's inverse logic doesn't depend on it — it only needs the source holon's LocalId, which is resolved the same way regardless of whether the holon was created, versioned, or unchanged. Once this lands, Issue 1's inverse SmartLinks automatically benefit from correct anchoring because they use the same LocalId that forward links use.

Issue 3: Nursery-Level Duplicate Detection and Idempotent SmartLink Persistence

Scope: Enforce relationship uniqueness at mutation time and handle concurrent duplicates at commit time.

What it covers:

• add_related_holons(...) rejects duplicate targets within a staged relationship collection
• Idempotent behavior when the same relationship is added multiple times within a transaction
• Commit-time duplicate suppression for SmartLinks targeting already-persisted holons (race condition window)

Primary files: nursery.rs (or mutation facade), commit_functions.rs (Pass 2), smartlink_adapter.rs
Why third: This is defensive infrastructure that hardens the system but isn't required for correctness of Issues 1 or 2. Today, the only path that could produce duplicate inverse links would be a caller explicitly staging a relationship that commit also auto-generates — and if Issue 1 establishes the declaring-side-only rule, that path doesn't exist for inverse links. This issue becomes most valuable once the staging model stabilizes from Issue 2.

Dependencies

None of these three issues have hard implementation dependencies on each other. Issue 1 can ship first and will be refined (not broken) by the later issues. Issue 2 can proceed in parallel if desired. Issue 3 is independently useful but lowest urgency.

[evomimic]

I agree with the proposed split and sequencing.

One important clarification, though: Issue 1 can land first, but it is not semantically independent of Issue 2.

Specifically, Issue 1 will be wrong if it assumes that the staged holon always becomes the source of the persisted relationship. Once Issue 2 lands, source anchoring must instead follow an explicit rule:

• If a staged holon results in a new version → relationships attach to the new version
• Otherwise → relationships attach to the existing holon

So I would suggest making explicit that:

• Issue 1 may initially reuse the current forward-link source selection behavior
• but when Issue 2 lands, both forward and inverse persistence must be updated to derive their source from the staged state / anchoring rule, rather than from the staged holon by default

On Issue 3, I agree it is not required for correctness of Issues 1 or 2, but I would emphasize that it has heightened importance for fail-fast semantics and developer experience:

• Duplicate detection at mutation time (nursery) provides immediate feedback
• Idempotency guarantees reduce ambiguity during composition of operations
• Without it, errors may only surface indirectly or post-commit, which degrades usability

So while I am fine with the proposed sequencing, I would frame Issue 3 as important for human-facing ergonomics, not just defensive hardening.

Otherwise, this breakdown looks good to me.