[I] wisdom: store relationship type markers in `custom_extensions` instead of `ai_context` [ossie-converters]

["jbonofre (via GitHub)" <gi...@apache.org>]

jbonofre opened a new issue, #29:
URL: https://github.com/apache/ossie-converters/issues/29

   ## Summary
   
   The Wisdom converter records the relationship types that Ossie's direction can't carry as text in the relationship's `ai_context`. `wisdom-to-ossie` writes the note and `ossie-to-wisdom` reads it back to restore `relationshipType`. apache/ossie#455 adds a third note for `ONE_TO_MANY` and makes the match exact, through a shared `RELATIONSHIP_TYPE_NOTES`.
   
   That fixes the round trip reported in apache/ossie#425, but it leaves round-trip state in a free-text, AI-facing field. This issue proposes moving it to a `WISDOM` entry in `custom_extensions`.
   
   ## Problems with the notes
   
   1. **The note text is a wire format.** Rewording any note stops documents generated earlier from restoring their type.
   2. **Hand-written notes are misread or ignored.**
      - With prefix matching (main today), any note starting with `one-to-one` or `many-to-many` changes the exported type.
      - With exact matching (#455), a note such as `one-to-one` or `many-to-many relationship` exports as `MANY_TO_ONE`, and the only signal is the generic `AI_CONTEXT_DROPPED`.
      - A hand-written note of exactly `one-to-many relationship` still swaps left and right with no warning.
   3. **The `ONE_TO_MANY` note contradicts the model.** Wisdom `customers ONE_TO_MANY orders` becomes `from: orders, to: customers, ai_context: one-to-many relationship`. `from` is the many side, so the relationship as written is many-to-one; the note only records which table was on the left in Wisdom. Other converters pass a relationship's `ai_context` on to their target (the Microsoft one does), so the misleading text travels.
   4. **A structured `ai_context` is not recognised.** `ai_context: {instructions: "one-to-many relationship"}` exports as `MANY_TO_ONE` with no swap.
   
   ## Proposal
   
   - `wisdom-to-ossie`: record the original `relationshipType` in a `WISDOM` `custom_extensions` entry on the relationship, instead of in `ai_context`.
   - `ossie-to-wisdom`: restore the type, and the left/right orientation for `ONE_TO_MANY`, from that entry.
   - `_report_custom_extensions` currently reports every extension as `CUSTOM_EXTENSION_DROPPED`, whatever the vendor. It needs to skip the `WISDOM` entries the converter consumes.
   - Update the "Relationship cardinality" table and the export section of `converters/wisdom/README.md`.
   
   `OssieVendor.WISDOM` already exists. The Microsoft converter is a precedent for the same flip: it stashes `flipped` and `normalizedEndpoints` on the relationship and checks the endpoints before applying the flip on export. The Cube converter has a similar stash protocol in `_common.py`.
   
   ## Open questions
   
   - **Stale stash:** if `from`/`to` are edited after import, the stashed type may no longer apply. Storing the normalized endpoints next to the type, as the Microsoft converter does, would let the export detect that.
   - **Backward compatibility:** should `ossie-to-wisdom` keep reading the existing `ai_context` notes for documents already generated?
   - **Human-readable note:** the `ONE_TO_ONE` and `MANY_TO_MANY` notes are true statements and useful to an LLM. They could stay as plain `ai_context` text, as long as the export no longer depends on them.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@ossie.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org