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

apps/roam/src/utils/__tests__/importedSourceIdentity.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import type { CrossAppNode } from "@repo/database/crossAppNodeContract";
+import type { json } from "~/utils/getBlockProps";
+import { DISCOURSE_GRAPH_PROP_NAME } from "~/utils/createReifiedBlock";
+import {
+  IMPORTED_FROM_PROP_KEY,
+  parseImportedSourceIdentity,
+  toImportedSourceIdentity,
+  type ImportedSourceIdentity,
+} from "~/utils/importedSourceIdentity";
+
+const identity: ImportedSourceIdentity = {
+  sourceApp: "obsidian",
+  sourceSpaceId: "obsidian:9a8b7c6d5e4f3210",
+  sourceNodeId: "0192f1a0-7b3c-7e2a-9f10-1a2b3c4d5e6f",
+  sourceNodeRid:
+    "orn:obsidian.note:9a8b7c6d5e4f3210/0192f1a0-7b3c-7e2a-9f10-1a2b3c4d5e6f",
+  sourceTitle: "EVD - REM sleep and recall",
+  sourceModifiedAt: "2026-06-14T10:30:00.000Z",
+};
+
+const propsWithImportedFrom = (
+  importedFrom: json,
+  siblingProps: Record<string, json> = {},
+): Record<string, json> => ({
+  [DISCOURSE_GRAPH_PROP_NAME]: {
+    ...siblingProps,
+    [IMPORTED_FROM_PROP_KEY]: importedFrom,
+  },
+});
+
+describe("toImportedSourceIdentity", () => {
+  it("maps the six identity fields from a cross-app node, using direct content as title", () => {
+    const node: CrossAppNode = {
+      sourceApp: "obsidian",
+      sourceSpaceId: identity.sourceSpaceId,
+      sourceSpaceName: "Research Vault",
+      sourceNodeId: identity.sourceNodeId,
+      sourceNodeRid: identity.sourceNodeRid,
+      nodeType: { sourceNodeTypeId: "evd-7c1f9a2b", label: "Evidence" },
+      content: {
+        direct: { value: identity.sourceTitle },
+        full: { format: "text/markdown", value: "# body\n" },
+      },
+      sourceModifiedAt: identity.sourceModifiedAt,
+    };
+
+    const result = toImportedSourceIdentity(node);
+
+    expect(result).toEqual(identity);
+    expect(Object.keys(result).sort()).toEqual(
+      [
+        "sourceApp",
+        "sourceModifiedAt",
+        "sourceNodeId",
+        "sourceNodeRid",
+        "sourceSpaceId",
+        "sourceTitle",
+      ].sort(),
+    );
+  });
+});
+
+describe("parseImportedSourceIdentity", () => {
+  it("round-trips a stored identity", () => {
+    expect(
+      parseImportedSourceIdentity(propsWithImportedFrom(identity)),
+    ).toEqual(identity);
+  });
+
+  it("ignores sibling discourse-graph props", () => {
+    const props = propsWithImportedFrom(identity, {
+      "relation-migration": { abc123: 1718000000000 },
+    });
+    expect(parseImportedSourceIdentity(props)).toEqual(identity);
+  });
+
+  it("returns undefined when there are no discourse-graph props", () => {
+    expect(parseImportedSourceIdentity({})).toBeUndefined();
+  });
+
+  it("returns undefined when discourse-graph has no importedFrom", () => {
+    expect(
+      parseImportedSourceIdentity({
+        [DISCOURSE_GRAPH_PROP_NAME]: { "relation-migration": {} },
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when a required field is missing", () => {
+    const withoutRid = {
+      sourceApp: identity.sourceApp,
+      sourceSpaceId: identity.sourceSpaceId,
+      sourceNodeId: identity.sourceNodeId,
+      sourceTitle: identity.sourceTitle,
+      sourceModifiedAt: identity.sourceModifiedAt,
+    };
+    expect(
+      parseImportedSourceIdentity(propsWithImportedFrom(withoutRid)),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when a field has the wrong type", () => {
+    expect(
+      parseImportedSourceIdentity(
+        propsWithImportedFrom({ ...identity, sourceModifiedAt: 1718000000000 }),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined for an unknown sourceApp", () => {
+    expect(
+      parseImportedSourceIdentity(
+        propsWithImportedFrom({ ...identity, sourceApp: "notion" }),
+      ),
+    ).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,43 @@
+import type { CrossAppNode } from "@repo/database/crossAppNodeContract";
+import { spaceUriAndLocalIdToRid } from "@repo/database/lib/rid";
+import {
+  toImportedSourceIdentity,
+  type ImportedSourceIdentity,
+} from "./importedSourceIdentity";
+
+/**
+ * Example of the source identity persisted on a Roam page when an Obsidian-origin
+ * shared node is imported. Derived from the cross-app node contract so the stored
+ * shape stays in lockstep with `CrossAppNode`. Not imported by runtime code; this
+ * file exists to type-check and document the stored metadata.
+ *
+ * The source node type is intentionally absent from the stored identity: node-type
+ * mapping is the materializer's concern (ENG-1858), not ENG-1856's.
+ */
+
+const OBSIDIAN_SOURCE_SPACE_ID = "obsidian:9a8b7c6d5e4f3210";
+const OBSIDIAN_SOURCE_NODE_ID = "0192f1a0-7b3c-7e2a-9f10-1a2b3c4d5e6f";
+
+const obsidianOriginNode: CrossAppNode = {
+  sourceApp: "obsidian",
+  sourceSpaceId: OBSIDIAN_SOURCE_SPACE_ID,
+  sourceSpaceName: "Research Vault",
+  sourceNodeId: OBSIDIAN_SOURCE_NODE_ID,
+  sourceNodeRid: spaceUriAndLocalIdToRid(
+    OBSIDIAN_SOURCE_SPACE_ID,
+    OBSIDIAN_SOURCE_NODE_ID,
+    "note",
+  ),
+  nodeType: { sourceNodeTypeId: "evd-7c1f9a2b", label: "Evidence" },
+  content: {
+    direct: { value: "EVD - REM sleep and recall" },
+    full: {
+      format: "text/markdown",
+      value: "# REM sleep correlates with recall\n",
+    },
+  },
+  sourceModifiedAt: "2026-06-14T10:30:00.000Z",
+};
+
+export const obsidianImportedIdentityExample: ImportedSourceIdentity =
+  toImportedSourceIdentity(obsidianOriginNode);

apps/roam/src/utils/importedSourceIdentity.ts

@@ -0,0 +1,142 @@
+import type { CrossAppNode } from "@repo/database/crossAppNodeContract";
+import getBlockProps, { type json } from "./getBlockProps";
+import setBlockProps from "./setBlockProps";
+import { DISCOURSE_GRAPH_PROP_NAME } from "./createReifiedBlock";
+
+/**
+ * Stable identity of a node imported into Roam from another app, persisted on the
+ * imported page so it can be re-found (duplicate prevention) and refreshed later.
+ * Field names mirror the app-neutral `CrossAppNode` contract; the page's display
+ * title is kept separate from this stored identity.
+ */
+export type ImportedSourceIdentity = {
+  sourceApp: CrossAppNode["sourceApp"];
+  sourceSpaceId: string;
+  sourceNodeId: string;
+  sourceNodeRid: string;
+  sourceTitle: string;
+  sourceModifiedAt: string;
+};
+
+/**
+ * Sub-key under the shared `discourse-graph` block-props namespace holding the
+ * imported source identity, alongside any other discourse-graph props.
+ */
+export const IMPORTED_FROM_PROP_KEY = "importedFrom";
+
+const isJsonObject = (value: json): value is { [key: string]: json } =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isSourceApp = (value: json): value is CrossAppNode["sourceApp"] =>
+  value === "roam" || value === "obsidian";
+
+/**
+ * Derive the stored identity from a cross-app node payload. The display title
+ * comes from the `direct` content variant, per the contract.
+ */
+export const toImportedSourceIdentity = (
+  node: CrossAppNode,
+): ImportedSourceIdentity => ({
+  sourceApp: node.sourceApp,
+  sourceSpaceId: node.sourceSpaceId,
+  sourceNodeId: node.sourceNodeId,
+  sourceNodeRid: node.sourceNodeRid,
+  sourceTitle: node.content.direct.value,
+  sourceModifiedAt: node.sourceModifiedAt,
+});
+
+/**
+ * Extract the imported source identity from a page's normalized block props, or
+ * `undefined` when the page was not imported (or the metadata is malformed).
+ * Pure: pass the result of `getBlockProps(uid)`.
+ */
+export const parseImportedSourceIdentity = (
+  props: Record<string, json>,
+): ImportedSourceIdentity | undefined => {
+  const dgData = props[DISCOURSE_GRAPH_PROP_NAME];
+  if (!isJsonObject(dgData)) return undefined;
+  const imported = dgData[IMPORTED_FROM_PROP_KEY];
+  if (!isJsonObject(imported)) return undefined;
+  const {
+    sourceApp,
+    sourceSpaceId,
+    sourceNodeId,
+    sourceNodeRid,
+    sourceTitle,
+    sourceModifiedAt,
+  } = imported;
+  if (!isSourceApp(sourceApp)) return undefined;
+  if (
+    typeof sourceSpaceId !== "string" ||
+    typeof sourceNodeId !== "string" ||
+    typeof sourceNodeRid !== "string" ||
+    typeof sourceTitle !== "string" ||
+    typeof sourceModifiedAt !== "string"
+  )
+    return undefined;
+  return {
+    sourceApp,
+    sourceSpaceId,
+    sourceNodeId,
+    sourceNodeRid,
+    sourceTitle,
+    sourceModifiedAt,
+  };
+};
+
+/** Read the imported source identity stored on a Roam page, if any. */
+export const readImportedSourceIdentity = (
+  pageUid: string,
+): ImportedSourceIdentity | undefined =>
+  parseImportedSourceIdentity(getBlockProps(pageUid));
+
+/**
+ * Write (or overwrite) the imported source identity on a Roam page. Merges into
+ * the `discourse-graph` props namespace so sibling metadata is preserved, and
+ * lives in block props so it survives overwrites of the page's content. Used on
+ * first import and on refresh.
+ */
+export const writeImportedSourceIdentity = (
+  pageUid: string,
+  identity: ImportedSourceIdentity,
+): void => {
+  const existing = getBlockProps(pageUid)[DISCOURSE_GRAPH_PROP_NAME];
+  const dgData: Record<string, json> = isJsonObject(existing) ? existing : {};
+  dgData[IMPORTED_FROM_PROP_KEY] = {
+    sourceApp: identity.sourceApp,
+    sourceSpaceId: identity.sourceSpaceId,
+    sourceNodeId: identity.sourceNodeId,
+    sourceNodeRid: identity.sourceNodeRid,
+    sourceTitle: identity.sourceTitle,
+    sourceModifiedAt: identity.sourceModifiedAt,
+  };
+  setBlockProps(pageUid, { [DISCOURSE_GRAPH_PROP_NAME]: dgData });
+};
+
+/**
+ * Find the uid of an already-imported Roam page by its source RID, or `null`.
+ * `sourceNodeRid` is the canonical cross-app identity key, so it alone
+ * identifies an imported node. Warns if more than one page shares a RID.
+ */
+export const findImportedNodeUidByRid = async (
+  sourceNodeRid: string,
+): Promise<string | null> => {
+  const query = `[:find ?uid
+    :in $ ?rid
+    :where
+      [?page :block/uid ?uid]
+      [?page :block/props ?props]
+      [(get ?props :${DISCOURSE_GRAPH_PROP_NAME}) ?dgData]
+      [(get ?dgData :${IMPORTED_FROM_PROP_KEY}) ?imported]
+      [(get ?imported :sourceNodeRid) ?rid]]`;
+  const result = (await window.roamAlphaAPI.data.async.q(
+    query,
+    sourceNodeRid,
+  )) as [string][];
+  if (result.length > 1) {
+    console.warn(
+      `findImportedNodeUidByRid: ${result.length} pages share sourceNodeRid '${sourceNodeRid}'`,
+    );
+  }
+  return result.length > 0 ? result[0][0] : null;
+};