fix(cli): preserve OKF permalink resolution precedence

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/okf/render.py

@@ -63,6 +63,7 @@ def convert_wikilinks(
     *,
     include_project: bool = True,
     ambiguous_aliases: frozenset[str] = frozenset(),
+    permalinks: dict[str, str] | None = None,
 ) -> str:
     """Use MarkdownIt's code/escape/link rules while retaining untouched source bytes."""
     body = body.replace("\r\n", "\n").replace("\r", "\n")
@@ -114,6 +115,16 @@ def wikilink(state: StateInline, silent: bool) -> bool:
             resolved = targets.get(relative.lstrip("/"))
             if resolved is None:
                 resolved = targets.get(relative.lstrip("/") + ".md")
+        if resolved is None and permalinks:
+            # Semantic addresses precede title/path aliases, even when they look like filenames.
+            for candidate in build_permalink_resolution_candidates(
+                target, project, include_project
+            ):
+                if target in ambiguous_aliases and candidate != target:
+                    break
+                if candidate in permalinks:
+                    resolved = permalinks[candidate]
+                    break
         if resolved is None:
             for candidate in build_permalink_resolution_candidates(
                 target, project, include_project
@@ -195,6 +206,7 @@ def wikilink(state: StateInline, silent: bool) -> bool:
 def render_bundle(snapshot: ExportSnapshot) -> tuple[ExportFile, ...]:
     """Preserve frontmatter and prose; attach only semantics lost by link conversion."""
     targets: dict[str, str] = {}
+    permalinks: dict[str, str] = {}
     ambiguous: set[str] = set()
     documents: dict[str, Document] = {}
     titles: dict[str, str] = {}
@@ -220,7 +232,7 @@ def render_bundle(snapshot: ExportSnapshot) -> tuple[ExportFile, ...]:
         aliases = {file.path, str(PurePosixPath(file.path).with_suffix("")), title}
         permalink = normalize_frontmatter_value(source_metadata.get("permalink"))
         if isinstance(permalink, str) and permalink:
-            aliases.add(permalink)
+            permalinks[permalink] = file.path
         for alias in aliases:
             if alias in targets and targets[alias] != file.path:
                 ambiguous.add(alias)
@@ -268,6 +280,7 @@ def render_bundle(snapshot: ExportSnapshot) -> tuple[ExportFile, ...]:
             snapshot.project,
             include_project=snapshot.permalinks_include_project,
             ambiguous_aliases=frozenset(ambiguous),
+            permalinks=permalinks,
         )
         content = "---\n" + yaml.safe_dump(metadata, allow_unicode=True, sort_keys=False)
         content += "---\n" + body

tests/okf/test_okf.py

@@ -497,11 +497,11 @@ def test_ambiguous_bare_title_does_not_fall_through_to_filename():
         (
             ExportFile("Same.md", b"---\ntitle: Same\n---\n"),
             ExportFile("other.md", b"---\ntitle: Same\npermalink: same\n---\n"),
-            ExportFile("source.md", b"[[Same]] and [[Same.md]]"),
+            ExportFile("source.md", b"[[Same]] and [[Same.md]] and [[./Same.md]]"),
         ),
     )
     source = next(file.content for file in render_bundle(snapshot) if file.path == "source.md")
-    assert b"[Same](/Same) and [Same.md](/Same.md)" in source
+    assert b"[Same](/Same) and [Same.md](/other.md) and [./Same.md](/Same.md)" in source
 
 
 @pytest.mark.parametrize(
@@ -619,3 +619,32 @@ def test_scalar_permalink_aliases_preserve_authored_metadata(yaml_permalink, tar
 )
 def test_wikilink_delimiters_use_canonical_escape_rules(body, target, expected):
     assert convert_wikilinks(body, "source.md", {target: "note.md"}, "p") == expected
+
+
+@pytest.mark.parametrize("permalink", ["foo.md", "foo"])
+def test_permalink_precedes_file_alias_but_explicit_relative_path_stays_a_path(
+    permalink, test_project
+):
+    from basic_memory.models import Entity
+    from basic_memory.services.bulk_link_resolver import ProjectEntityIdentityIndex
+
+    owner = Entity(title="Owner", file_path="owner.md", permalink=permalink)
+    index = ProjectEntityIdentityIndex.from_entities(
+        test_project, [Entity(title="foo", file_path="foo.md"), owner]
+    )
+    assert (
+        index.resolve_strict(
+            "foo.md", include_project_permalinks=True, workspace_permalink=None
+        ).entity
+        is owner
+    )
+    snapshot = ExportSnapshot(
+        "p",
+        (
+            ExportFile("foo.md", b"# File"),
+            ExportFile("owner.md", f"---\npermalink: {permalink}\n---\n# Permalink owner".encode()),
+            ExportFile("source.md", b"[[foo.md]] and [[./foo.md]]"),
+        ),
+    )
+    source = next(file.content for file in render_bundle(snapshot) if file.path == "source.md")
+    assert b"[foo.md](/owner.md) and [./foo.md](/foo.md)" in source