ENG-2247 Copy a node's assets and rewrite its markdown for Roam

[maparent]

Reviewer brief

This creates a utility function, importAssetNodes, that ties together rewriteAssetLinks (ENG-2217) and mirrorAssetToRoamStorage (ENG-2218) to actually import the nodes detected in given markdown.
This also involves a refactoring of a repeated and defective utility function.
Finally, this includes some end-to-end tests (in a separate commit) that rely on importAssetNodes.

Verification

Includes unit tests.
Behaviour tests in #1401

Loom video

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

Scope check

• Ran $scope-check against the ENG ticket and final diff.
• Scope beyond Done When: None. ENG-2247's criteria were written after the split, so
  they describe this diff by construction. The list below measures against the original
  ENG-2219 Done When, which is what was agreed before the split.

Beyond the original ENG-2219 scope:

1. The tokenizer API. rewriteAssetLinks exports lookupCandidates and gains
   collectAssetLocators, so the stage copies only references the rewriter can resolve.

   • Required now: without it the stage copies every recorded row, including ones whose
     locator no longer appears in the fetched markdown once frontmatter and the title
     heading are stripped. A Roam upload is a permanent charge on the user's storage, so
     this is reachable the moment the stage ships. Deriving the spellings forward instead
     does not work: a note writes fig#1.png as fig%231.png, and encodeURI leaves
     # alone.
   • parseMatch, which this depends on, went to ENG-2217 as a pure refactor.

2. getErrorMessage consolidated into apps/roam/src/utils/getErrorMessage.ts,
   replacing the copies in materializeSharedNode and in mirrorAssetToRoamStorage (an
   ENG-2218 file), plus a branch for the { message } objects Supabase returns.

   • Required now: No. A module-local copy in importNodeAssets would have satisfied the
     ticket. This is cleanup, and it changes the error text of three existing callers. It
     consolidates the two copies that had to share it; other inline copies elsewhere in
     the codebase are untouched.

3. assetDegradation.test.ts asserts the degradation path across the publish and
   import seam, calling ENG-1870's publishNodeAssets alongside importNodeAssets.

   • Required now: it satisfies task 6.1 of the cross-app-asset-references OpenSpec
     change. The contract between the two halves cannot be asserted from either side
     alone.
   • Decision: recorded on ENG-2219, comment of 2026-09-06.

4. A doc comment in mirrorAssetToRoamStorage recording that nothing rolls an upload
   back. Comment only, no behaviour change.

   • Required now: importNodeAssets depends on that constraint and it was uncaptured.

• Anyone affected or consulted: No, except item 3, agreed on ENG-2219 before the split.
• Decision: item 3 as above; the rest are recorded in ENG-2247's description.

Local delegated full review

• Ran a comprehensive review of the entire final diff in a subagent with a fresh context. Use $dg-delegated-full-review when no other full-review workflow is available.

https://linear.app/discourse-graphs/issue/ENG-2247/copy-a-nodes-assets-and-rewrite-its-markdown-for-roam

[linear-code]

ENG-2247

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
discourse-graph	Skipped		Sep 10, 2026 10:07pm UTC

[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.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🔴 Asset import never reaches materialization

importNodeAssets has no production caller, so materialization writes unchanged asset locators. Obsidian assets become empty page references, and Roam assets remain origin-dependent.

Learn more

The new asset stage is only referenced by tests. After fetchFullMarkdown, materialization passes content.markdown directly to page creation or replacement. Therefore neither shared-storage downloads nor Roam uploads occur during an actual import, and rewriteAssetLinks never changes the markdown written to the page.

Example: Importing Obsidian markdown ![[attachments/diagram.png]] leaves that text unchanged. Roam interprets it as a page reference instead of displaying the published image. A Roam-origin Firebase URL still renders initially, but deleting the origin graph's blob later breaks the imported page.

Recommended fix: Call importNodeAssets({ client, sharedNode, markdown: content.markdown }) before createImportedPage or updateImportedPage, pass its returned markdown into materialization, and propagate its report to the import result or existing user-facing summary. Add materialization tests proving both create and update paths write rewritten markdown.

---

Was this helpful? React with 👍 or 👎 to provide feedback.