[ENG-1856] Store source identity metadata for Roam imported nodes by sid597 · Pull Request #1161 · DiscourseGraphs/discourse-graph

sid597 · 2026-06-26T15:27:36Z

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

What

Adds the Roam-side storage layer for imported cross-app node identity (ENG-1856, M2 "Bidirectional node import"). When Roam imports an Obsidian-origin shared node, it must remember the node's stable source identity so it can (a) prevent duplicate imports and (b) refresh it later.

apps/roam/src/utils/importedSourceIdentity.ts:

ImportedSourceIdentity — 6 app-neutral fields mirroring the CrossAppNode contract: sourceApp, sourceSpaceId, sourceNodeId, sourceNodeRid, sourceTitle, sourceModifiedAt.
toImportedSourceIdentity(node) — derive the stored identity from a CrossAppNode (title from the direct content variant).
writeImportedSourceIdentity(uid, identity) / readImportedSourceIdentity(uid) — persist/read under the page's :block/props → discourse-graph → importedFrom, merging alongside any sibling discourse-graph props (mirrors migrateRelations / createReifiedBlock).
findImportedNodeUidByRid(rid) — datalog lookup returning an already-imported page's uid (duplicate prevention), keyed on the canonical sourceNodeRid.

Storage is block-props (not page content), so identity survives content overwrite on import/refresh and is datalog-queryable.

Scope / boundaries (pre-flight approved)

This is a foundational helper PR — the exported helpers are the deliverable; their consumers are downstream M2 issues, so there is no in-PR caller by design:

ENG-1855 marks already-imported nodes via findImportedNodeUidByRid
ENG-1858 materializer writes identity via writeImportedSourceIdentity(uid, toImportedSourceIdentity(node))
ENG-1859 import action dedups; ENG-1860 / ENG-1861 refresh read identity + sourceModifiedAt

Deliberately out of scope (named owners): node-type mapping → ENG-1858; author/provenance → ENG-1875; discovery UI → ENG-1855.

Notes for review

IMPORTED_FROM_PROP_KEY is exported following the existing DISCOURSE_GRAPH_PROP_NAME precedent (wire-key constants exported from their owning module); ENG-1861 (refresh-all) / ENG-1875 (provenance) will enumerate imported pages by it.
The single as [string][] on the datalog result matches strictQueryForReifiedBlocks's handling of untyped query output.
Builds on merged ENG-1847 (CrossAppNode + rid.ts); branched off main@36e3348.

Tests

vitest unit tests for the pure functions — toImportedSourceIdentity and parseImportedSourceIdentity (round-trip + rejection of missing / wrong-typed fields and unknown sourceApp, and coexistence with sibling discourse-graph props): 8/8 pass.
prettier / eslint / tsc clean on changed files. (Two pre-existing tsc errors in discourseNodeSearchProviders.ts are unrelated to this PR.)

Runtime proof (Loom — owed)

write/read/find call window.roamAlphaAPI; with no UI consumer yet, proof is a console round-trip on a test page PUID:

const id = {sourceApp:"obsidian",sourceSpaceId:"obsidian:vault",sourceNodeId:"abc",sourceNodeRid:"orn:obsidian.note:vault/abc",sourceTitle:"T",sourceModifiedAt:"2026-06-14T10:30:00.000Z"};
await roamAlphaAPI.data.block.update({block:{uid:PUID,props:{"discourse-graph":{importedFrom:id}}}});   // write
roamAlphaAPI.pull("[:block/props]",[":block/uid",PUID]);                                                 // confirm stored
// overwrite the page body here, then re-pull to show identity persists
await roamAlphaAPI.data.async.q(`[:find ?u :in $ ?rid :where [?p :block/uid ?u][?p :block/props ?pr][(get ?pr :discourse-graph) ?d][(get ?d :importedFrom) ?i][(get ?i :sourceNodeRid) ?rid]]`,"orn:obsidian.note:vault/abc"); // find → [[PUID]]; unknown rid → []

Persist an imported cross-app node's stable source identity in the Roam page's block-props under `discourse-graph.importedFrom`, with helpers to derive it from a CrossAppNode, read/write it, and find an imported page by sourceNodeRid for duplicate prevention. Stored in block-props so it survives content overwrite and is datalog-queryable; mirrors the reified-block props pattern and reuses the shared rid.ts helpers. Includes a typed example fixture and unit tests for the pure functions.

linear-code · 2026-06-26T15:27:41Z

ENG-1856

supabase · 2026-06-26T15:27:42Z

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 ↗︎.

vercel · 2026-06-26T15:27:45Z

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
discourse-graph	Skipped		Jun 28, 2026 6:53pm

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Sibling block-props utils carry no JSDoc; reviewer orientation moves to PR review comments rather than living in the code.

sid597 · 2026-06-28T18:55:40Z

+  },
+});
+
+describe("toImportedSourceIdentity", () => {


What this covers: the two PURE functions — toImportedSourceIdentity (CrossAppNode → stored shape, using direct content as the title) and parseImportedSourceIdentity (round-trip + reject no-props / no importedFrom / missing field / wrong type / unknown sourceApp).

Run from apps/roam: pnpm test src/utils/__tests__/importedSourceIdentity.test.ts

sid597 · 2026-06-28T18:56:48Z

+    sourceTitle: identity.sourceTitle,
+    sourceModifiedAt: identity.sourceModifiedAt,
+  };
+  setBlockProps(pageUid, { [DISCOURSE_GRAPH_PROP_NAME]: dgData });


Merged into the shared discourse-graph namespace (not replaced) so sibling props like relation-migration survive. Block-props rather than page content = survives a content overwrite on refresh, and is queryable from datalog (see find below).

sid597 · 2026-06-28T18:57:50Z

+  setBlockProps(pageUid, { [DISCOURSE_GRAPH_PROP_NAME]: dgData });
+};
+
+export const findImportedNodeUidByRid = async (


Duplicate-prevention entry point: before importing, look up by sourceNodeRid (the canonical cross-app key — it alone identifies a node) and reuse the page if found. Warns instead of throwing on >1 match so a bad data state degrades gracefully.

mdroidian · 2026-06-28T19:21:12Z

@sid597 could you create a Loom video of you demonstrating the Runtime proof and add it to the top of the body of the PR, please? 👍

sid597 · 2026-06-29T06:26:24Z

@mdroidian added the loom video

maparent · 2026-06-29T14:14:26Z

+  sourceApp: "obsidian",
+  sourceSpaceId: "obsidian:9a8b7c6d5e4f3210",
+  sourceNodeId: "0192f1a0-7b3c-7e2a-9f10-1a2b3c4d5e6f",
+  sourceNodeRid:


I'm puzzled that the structure contains both the sourceNodeRid on the one hand, and the set of sourceSpaceId, sourceNodeId, and sourceApp on the other. The former is a compressed representation of all the latter, and we have a utility function to recover them. So this is very redundant. I would only keep the Rid.
If you compare to the obsidian implementation, OTH, we also have authorId (which I understand we may punt; we have not thought enough about multiple authors.)

maparent · 2026-06-29T14:16:03Z

@@ -0,0 +1,38 @@
+import type { CrossAppNode } from "@repo/database/crossAppNodeContract";


Nit: Should the example live in the test folder?

maparent

Submitting the review failed, so I have two comments which are somehow not associated with the review.

devin-ai-integration Bot reviewed Jun 26, 2026

View reviewed changes

sid597 mentioned this pull request Jun 28, 2026

[ENG-1858] Materialize Obsidian-origin markdown into Roam #1171

Open

[ENG-1856] Remove doc comments from imported identity helpers

5aaaf1f

Sibling block-props utils carry no JSDoc; reviewer orientation moves to PR review comments rather than living in the code.

vercel Bot temporarily deployed to Preview June 28, 2026 18:53 Inactive

sid597 commented Jun 28, 2026

View reviewed changes

sid597 requested review from maparent and mdroidian June 28, 2026 18:59

maparent requested changes Jun 29, 2026

View reviewed changes

mdroidian removed their request for review June 29, 2026 17:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[ENG-1856] Store source identity metadata for Roam imported nodes#1161

[ENG-1856] Store source identity metadata for Roam imported nodes#1161
sid597 wants to merge 2 commits into
mainfrom
eng-1856-store-source-identity-metadata-for-roam-imported-nodes

sid597 commented Jun 26, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented Jun 26, 2026

Uh oh!

supabase Bot commented Jun 26, 2026

Uh oh!

vercel Bot commented Jun 26, 2026 •

edited

Loading

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

sid597 Jun 28, 2026

Uh oh!

sid597 Jun 28, 2026

Uh oh!

sid597 Jun 28, 2026

Uh oh!

mdroidian commented Jun 28, 2026

Uh oh!

sid597 commented Jun 29, 2026

Uh oh!

maparent Jun 29, 2026

Uh oh!

maparent Jun 29, 2026

Uh oh!

maparent left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,38 @@
		import type { CrossAppNode } from "@repo/database/crossAppNodeContract";

Uh oh!

Conversation

sid597 commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Scope / boundaries (pre-flight approved)

Notes for review

Tests

Runtime proof (Loom — owed)

Uh oh!

linear-code Bot commented Jun 26, 2026

Uh oh!

supabase Bot commented Jun 26, 2026

Uh oh!

vercel Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

sid597 Jun 28, 2026

Choose a reason for hiding this comment

Uh oh!

sid597 Jun 28, 2026

Choose a reason for hiding this comment

Uh oh!

sid597 Jun 28, 2026

Choose a reason for hiding this comment

Uh oh!

mdroidian commented Jun 28, 2026

Uh oh!

sid597 commented Jun 29, 2026

Uh oh!

maparent Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

maparent Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

maparent left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sid597 commented Jun 26, 2026 •

edited

Loading

vercel Bot commented Jun 26, 2026 •

edited

Loading