fix(core): resolve Markdown path links against the note at resolution time

[phernandez]

Summary

Fixes the #1514 follow-up where Markdown path links were resolved at parse time from the file's location on disk. Cloud's S3FileService.read_entity_content parsed a note from a temp file outside the project root, Path.relative_to raised, and the read failed (cloud main CI red; cloud side fixed in basicmachines-co/basic-memory-cloud#2086).

The root cause was in core: a Markdown link was the only relation whose meaning depended on where the parser read the bytes. Wikilinks are recorded as authored and resolved later against database state. This PR makes path links behave the same way, and gives path-shaped wikilinks ([[../x.md]], [[./x.md]]) the same exact-file resolution.

What changes

• Parser (markdown/entity_parser.py, markdown/path_links.py): parse(content) no longer takes a source_path. A Markdown link is stored as the path its author wrote: ../guides/Guide.md, ./same.md (a bare same.md gets the ./ mark so the stored target says it is a path, not a title), or a rooted /root.md. URLs, mailto:/file: links, fragment-only links, backslash or null-byte paths, and folder hrefs (./, docs/) create no relation.
• Resolution (services/link_resolver.py, services/bulk_link_resolver.py): both resolvers detect a path target (/, ./, ../) after wikilink normalization and resolve it with resolve_project_path(target, source_path) against the note's own project path. Exact file only. No title, permalink, alias, or cross-project fallback. A path that climbs past the project root resolves to nothing.
• Background resolution (indexing/relation_resolution.py, indexing/models.py): the batch resolver contract now takes RelationTargetRequest(link_text, source_path). Identity targets carry no source and resolve once for every note; path targets are keyed by their source note, so ./Guide.md from a/ and from b/ resolve to two different files in one pass. Source paths are fetched with one find_by_ids call only when the batch contains a path target.
• Self-edges (services/note_preparation.py): the write-time self-link check resolves the authored path against the note's own path, so [self](Self.md) in notes/Self.md still resolves to itself.
• Docs: docs/MARKDOWN_RELATIONS.md describes the stored form and resolution rule; CHANGELOG.md gets a Bug Fixes entry.

Behaviour change for stored data

Relation rows for Markdown links now store the authored path instead of the parser-resolved rooted path. Existing rows are rewritten on the note's next edit or reindex, as the docs already state for these relations. Unresolved rooted rows (/x.md) from before this change resolve the same way they did.

Tests

• tests/markdown/test_path_links.py: tables for markdown_link_path, resolve_project_path, is_path_target; parser test proves the authored form is stored and that parsing needs no filesystem location.
• tests/services/test_markdown_path_resolution.py: rooted, ./, ../, no-source, past-root, and [[../x.md|alias]] cases through LinkResolver.
• tests/services/test_bulk_link_resolver.py: the same authored path resolves to a different file from each source note; a path never falls back to a title.
• tests/indexing/test_relation_resolution.py: path targets keyed per source note in one batch, identity targets still deduplicated.
• test-int/mcp/test_markdown_path_relations_integration.py: end-to-end through write_note, including a path-shaped wikilink and a self-link.

Verification run locally:

just fast-check                      # ruff fix, format, ty: clean
just test-unit-sqlite                # 7678 passed, 48 skipped
uv run pytest tests/markdown tests/services/test_bulk_link_resolver.py \
  tests/services/test_link_resolver.py tests/services/test_markdown_path_resolution.py \
  tests/indexing tests/index tests/sync \
  test-int/mcp/test_markdown_path_relations_integration.py   # 1248 passed

Cloud follow-up

After this merges, cloud re-pins basic-memory to the new SHA. The in-memory parse in cloud #2086 stays correct either way; with this change the parser no longer needs a project-relative path at all.

Closes the parse-time half of #1514.

🤖 Generated with Claude Code

https://claude.ai/code/session_019YW9ysxugGGBCNEGzsxtFV

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.