eng-1863 Relation cross-app contract

[maparent]

ENG-1863: Define cross-app relation contract and fixtures

https://www.loom.com/share/f29f528856dc427da89cf87fc22b4993

---

[linear-code]

ENG-1863

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
discourse-graph	Ready	Preview, Comment	Jul 10, 2026 1:42pm

[supabase]

This pull request has been ignored for the connected project zytfjzqyijgagqxrzbmz because there are no changes detected in packages/database/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[devin-ai-integration]

Devin Review found 1 potential issue.

[graphite-app]

PR size/scope check

This PR is over our review-size guideline.

• Recommended: ~200 lines changed
• Acceptable limit: up to 400 lines when well-scoped/self-contained
• Preferred file count: fewer than 5 files

Please split this into smaller PRs unless there is a clear reason the changes need to land together.

If keeping it as one PR, please add a brief justification covering:

• What single problem this PR solves
• Why the files/changes are coupled

[mdroidian]

Are all of these union variants required? If so, could we add examples showing where each is already used or needed by upcoming work? Otherwise, I’d prefer to keep the contract limited to the variants we currently need and add others when a concrete use case arises.

Including speculative variants increases the contract’s conceptual surface area and requires additional validation, tests, and converter paths, which may create unnecessary confusion and complexity.

[maparent]

We do use the Rid in

discourse-graph/apps/obsidian/src/utils/conceptConversion.ts

Line 224 in 7e058c1

(sourceNode.frontmatter.importedFromRid as string | undefined) ??

And I expect this pattern to hold: We store a Rid and send it back.
We do not currently have a version that requires space directly at the upsert_concept call points, because the burden of computing the Rid from space+localId is currently on the platform (8 calls to spaceUriAndLocalIdToRid in the Obsidian code base, many upstream of upsert_concept.)
Having the space+localId variant in the contract will help centralize the Rid computation in the database package.

[mdroidian]

Thanks, that confirms the { rid } variant is required.

I agree that centralizing the spaceUri + localId → RID normalization could be useful. What I’m trying to separate is centralizing the RID implementation—which already lives in @repo/database/lib/rid—from expanding the shared relation contract to accept another representation of the same identity.

The existing Obsidian call sites use RIDs for several platform-level purposes, including imported provenance, duplicate detection, previews, and endpoint lookup. Because of that, moving normalization into the upsert converter would not replace all eight call sites.

This rationale also seems to support, at most, a { localId, spaceUri } input. I don’t see the same justification yet for the top-level { dbId }, { localId, space: { dbId } }, or the sourceApp property. The current converter does not use sourceApp, and its space.dbId branch is explicitly unresolved.

I’d prefer to keep the shared endpoint contract as LocalRef | RidRef for now:

type RelationEndpointRef =
  | { localId: string }
  | { rid: string };

This gives the shared boundary one canonical representation for remote identity: an RID. A platform that naturally has spaceUri + localId can normalize it before constructing the contract.

If an upcoming Roam or Obsidian producer genuinely benefits from emitting { localId, spaceUri }, we can add that form alongside the producer and a test demonstrating its normalization to the expected RID.