A written model of pages, names, aliases, journals and references: please try to break it

[martinkoutecky]

This cites #422 (where this was asked for), #619 and #702.

1. What this is, and why

In #422 hestratos asked for one written place that says what a page, a name, an alias, a journal and a reference are, so that Linked References, rename, queries and aliases cannot quietly disagree. The point came back in #619 and in the question under #702 about formalising the whole model. Martin agreed in #422 that it also helps development, since agents need written designs even more than humans do. This post is the first version.

It is a precise statement of the rules, not a description of the code. Where today's Tine differs, the model is what we would move the code toward, after this discussion and only for the parts you do not talk us out of.

What "proved in Lean" means. As with the storage model (#702), the rules are an executable program in the Lean proof assistant: a function from a graph's files to the pages, blocks, alias groups and references they mean, plus rename. Computer-checked proofs (751 theorems, rebuilt by an independent verifier) show that the rules fit together: what a name means depends only on which files exist, never on the order Tine happens to read them in (ties are broken by a fixed rule on file paths, rule 3); alias groups really are groups; rename does exactly what rule 6 says; and and/or/not in queries behave like ordinary logic. They do not show that Tine's code follows the rules; that comes later, by running the same small graphs through the model and through Tine. The model is not published yet, so there is no link; it goes under docs/conceptual-model/ after this discussion.

2. The rules

Rule 1: one name, one page. Two spellings are the same name when their keys are equal: trimmed, boundary slashes removed, lower-cased, Unicode-normalised. A page is its name plus its kind (page or journal). A file's name is its title:: if it has one, otherwise its file name. A page named n/y also makes page n exist, even if nothing links to n.

pages/Project Alpha.md
[[project alpha]]    opens pages/Project Alpha.md

Rule 2: an alias group is one thing. Every alias:: declaration joins two names into one group, and groups are closed under chains: if A declares B and B declares C, A, B and C are one group. Cycles, self-aliases and one alias declared by several pages are allowed. Linked References, counts and a query's [[A]] all see the whole group. A name that is only an alias, with no file, is not a page of its own.

pages/A.md   alias:: B
pages/B.md   alias:: C
pages/C.md   alias:: D          (no file for D)
a block saying [[D]] appears in the Linked References of A, B, C and D

Rule 3: a name with its own file opens that file; an alias-only name opens the page that declares it. If several pages declare it, the one whose graph-relative file path sorts first, byte by byte in UTF-8, wins. So capital letters sort before lower case.

pages/ML.md                  (has content)
pages/Machine Learning.md    alias:: ML
[[ML]] opens pages/ML.md. A block with [[ML]] still counts for the whole group.

pages/Alpha.md   alias:: Shared
pages/Beta.md    alias:: Shared
[[Shared]] opens pages/Alpha.md      (pages/Zed.md would beat pages/alpha.md)

Only pages that declare the name directly are considered. If A declares B, B is a real page, and B declares X, with no file for X, then [[X]] opens B. An empty file counts as a file. The group is shown under "Also called" and "Related pages in this alias group"; that display is interface, outside the model.

Rule 4: date-shaped names are journals. Whether a file is a journal depends on its folder (journals/ or pages/). A name that has no file at all, but is date-shaped in a format Tine already recognises, is that day's journal. A real ordinary file such as pages/2026-10-26.md still opens as itself, empty or not, when no journal of that day exists.

journals/2026_10_26.md
[[2026-10-26]] opens that journal

(no 2026-10-27 file anywhere)
[[2026-10-27]] is a reference-only journal page

Rule 5: journals may declare aliases. A link to the alias counts for that day, and it opens the journal.

journals/2026_10_26.md    alias:: launch day
pages/Notes.md            - see [[launch day]]
[[launch day]] opens the 2026-10-26 journal; Notes is in its Linked References

Rule 6: what rename does, exactly. Rename page… from old to new:

1. Moves the page old and every page under old/… (old/sub, old/sub/deep, including pages that exist only as names). Journal files never move.
2. In every file, journals included, rewrites each spelling of old or old/… in links, tags, page embeds, property keys, property values that are links, tags:: and alias:: members, and Org file links. It never rewrites task markers (TODO) or priorities ([#A]), which count as references to pages of those names. Page-name arguments inside queries ([[Tasks]], (page "Tasks") and the like) are rewritten too, so a query follows the rename as links do; plain search text such as "Tasks" is not a page reference and stays. Block references address blocks by id and are outside the rewrite.
3. Is allowed onto a name that exists only as a link (the two merge), and may create namespace pages: x to n/y creates page n.
4. Is refused if new is already a real page outside the moved set, if it is a real page in old's alias group other than old itself, if two moved pages would end up with the same name, or if any involved name is claimed by two files. A rename that keeps the same name as far as Tine's name matching goes (Foo to foo) passes the first two checks; it is refused only if a moved name is claimed by two files. (Corrected 2026-11-02, see the comment below.)
5. Is refused if it would stop a block from mentioning a name a journal is known by (its own name or an alias it declares): journals do not move, so Tine refuses rather than let a link drift away from one. The check protects the exact spelling and is deliberately conservative.

pages/old.md
pages/p.md                - see [[old/sub]]
journals/2026_10_26.md    alias:: old/sub
Rename old to new: refused (the link to old/sub would no longer reach the journal)

What we promise, in words: after a successful rename the graph is exactly what that rewrite produces, and everything else (what links to what) is read off the rewritten text. We do not promise "rename preserves meaning", because that is false:

a.md  - see [[b]]      rename a to b: the pages merge, and a's link becomes a page linking to itself, which is not a link between pages
x                      rename x to n/y: page n appears from nothing

References, pages and blocks do carry over one-to-one under conditions that are sufficient, not necessary: the new names are fresh, nothing merges, no name changes between page and journal, and no unrewritten spelling points into the moved set. A successful rename does not guarantee them. Favorites entries of moved pages follow the rename. Saved queries find the corresponding renamed pages and blocks under similar explicit conditions, which also cover ancestry and any other search conditions in the query; merges, new namespace pages and names becoming aliases can change their answers.

Rule 7: query results are the matched things themselves. A query denotes a set of blocks or a set of pages; and, or and not are intersection, union and complement within that set; and every view (list, table, groups, sort) shows exactly that set, rearranged. In #744 this means a property search that matches a child block shows that child as the row, not its parent. In our reading of the source, OG and Logseq DB do the same; what an empty Name cell shows is presentation, not decided. A query's [[A]] or refs matches A's whole alias group; name and page conditions compare the literal name. The model also states which conditions mean the same on pages and blocks, the fact #619's "pages vs blocks" question depends on; this post decides no interface.

3. Where this differs from OG Logseq, and why

• Names are trimmed (OG does not). Nobody wants " Foo" and "Foo" to differ.
• Alias groups are fully transitive. OG expands a name to its direct aliases plus two steps, so with ABC~D it links A to C but not to D. A real equivalence relation is what the proofs can state, and Tine then finds a superset of OG's results.
• An alias-only name opens the first declaring path. OG uses its "first source page".
• An empty page file keeps its own file when another page declares it as an alias. OG may redirect an empty alias page to its source (see question 2).
• Journal identity of a file is its folder; OG classifies by whether the name parses as a date. A lone nonblank pages/2026-10-26.md is an ordinary page here, and that day's journal in OG.
• Rename rewrites alias:: members. OG file graphs do not, and neither did Tine when we checked on 18 October. Without it, renaming Old when some page has alias:: Old silently moves Old's links away from that group.
• Rename rewrites page names inside queries. In OG, and in today's Tine, a block that only mentions the page inside a {{query}} is not updated, so the query goes stale while links follow the rename. (OG's plain text replacement does reach a query when the same block also has an ordinary link to the page.)
• Two files claiming one name are an invalid state. OG keeps whichever file it loads first and skips the other with a warning. See question 1.
• Query references expand aliases, which differs from OG and Logseq DB. It makes a query's [[A]] agree with Linked References.
• An alias-only name is not a page of its own, which follows Logseq DB.
• Matches OG: rename rewrites property keys; [#A] is a reference to page A; a file n/y alone makes page n.

Not all of this is in the app yet. Before code changes (step 3 below) we check each rule against current Tine and list the gaps in this thread.

4. Questions for you

Q1. Two files claim one name. For example pages/Foo.md and pages/foo.md on a case-sensitive disk, a title:: Foo in another file, or pages/2026-10-26.md next to journals/2026_10_26.md. Martin's earlier ruling: detect every case, refuse operations that depend on which file wins (rename, for one) with a pointer to the fix, and otherwise use a fixed documented rule. The open part is that rule. Tine's intended preference is: date-named journal file, then the file whose name matches the page name, then Markdown before Org, then file name, then path.

• (a) Keep that fixed order, document it in the Guide, and warn that a conflict exists. This is our current recommendation.
• (b) OG's rule: whichever file loads first. It depends on the order files are read, which the model deliberately excludes.
• (c) Treat the name as unresolvable until you fix it, and show both files.

Do you have graphs with such duplicates, and which file would you expect to win?

Q2. An empty file against an alias. pages/ML.md exists but is empty, and pages/Machine Learning.md has alias:: ML. The model, following Martin's ruling that a name with its own file opens that file, opens the empty ML.md. OG may redirect to Machine Learning.

• (a) Own file always wins, empty or not. This is the model and our recommendation.
• (b) An empty file does not count: redirect to the declaring page, like OG.
• (c) Own file wins, but offer to delete it or to merge when it is empty.

We also still need to check that today's Tine does (a). Has an empty alias page ever surprised you?

Q3. How should we word the rename promise to users? The exact statement is in rule 6, and "rename preserves meaning" cannot be used. Martin has not yet chosen the user-facing wording.

• (a) Put the exact statement in the Guide: "rename rewrites names everywhere; a rename that merges or creates pages can change what links to what; links to journals are protected".
• (b) Say nothing general, but have the rename confirmation list what will merge or be created.
• (c) Both.

We propose (c). Which would you want to read before pressing the button?

Q4. Experience reports on aliases. These rules are decided but have not met your graphs. Tell us where the answer is wrong for you: chains longer than two steps; one alias declared by two pages; an alias that also has its own page with content; a journal declaring aliases; a group you would not want merged; a rename that touched an alias. What did you expect [[X]] to open, and where should its links show up?

5. What happens next

1. This discussion. The model may change because of what you say here, and its proofs will be redone.
2. The final model, with the proofs, goes into the repository under docs/conceptual-model/.
3. Only then do code changes follow, together with tests comparing the model and Tine on small graphs.
4. Supertags come after that and are built on this model, so the alias rules matter beyond aliases.

Nothing in the app changes because of this post.

Claude (working on Martin's behalf)

[martinkoutecky]

@hestratos I remember you saying that aliases are incorrect; I think they are certainly weird, but they can be made correct for what I understand to be a purpose of a conceptual model. And another important point is, you can also just use aliases in a non-weird (simpler) way. But I am curious what you think about the above, and if it is what you had in mind in the first place. I'm happy to ask Claude to try to prove more properties from the same model, which is the point (the thing that something is not proven above does not mean it is not true / provable).

[hestratos]

Sorry for the delay in getting back to you. I've been quite busy lately.

Thanks, Martin, for all of this. I really appreciate it.

I use aliases in a very simple way, either to shorten long namespaces or as abbreviations for something. Nothing particularly fancy. However, that doesn't mean I'm immune to issues such as problems with queries or cases where a page gets created using an alias, effectively breaking the alias (you describe this quite well in the rules).

For some additional context, I asked the AI to recall what it knew about this and provide some background. It helped refresh my memory.

In a nutshell, the idea was to mimic Wikipedia's behaviour, and cannibalox was the person who had a particularly strong influence on this. He was building a movie wiki and even created a project, movie-cli-2, to insert information into Logseq.

Relevant forum discussions:

• https://discuss.logseq.com/t/improve-implementation-of-aliases/81?page=2 (this is the important one)
• https://discuss.logseq.com/t/aliases-could-use-some-tlc-tender-loving-care/1124

Relevant GitHub issues:

• #4709
• #4129
• #7183
• #8602
• #8523

Point the AI bot to these references; I assume it might be able to provide some additional background.

---

I have a few questions about what you've written.

1. Was the information generated by the bot obtained solely by looking at the source code? Does it also have context from the forum discussions and GitHub issues? I'm just asking to understand how much context it has and how reliable its understanding is.

2. I don't understand some of the terminology used.

What exactly is a real page? A file, whether it has content or not?
What is an empty page? One that contains no content?
What counts as content in a page? Does a page containing only title:: count as having content? What about one containing only icon::?

What I want to emphasise here is that I'm not familiar with the definitions of the concepts the AI is using.

3. Could rule 3 lead to shadowing? In other words, could there be a page that exists but that you can't access? Should Tine check the integrity of a graph when opening it and warn the user about any issues it finds?

4. Empty pages. Logseq used to create lots of pages containing just a -. This eventually became quite annoying when working with journals, because opening a journal page would create one of these pages. I think Logseq eventually considered a page containing only - to be empty and deleted it.

This would also prevent pages containing just - from being treated as pages with actual content. I'm bringing this up because it was an alias-related bug that drove me crazy.

5. Rename rewrites alias:: members. OG file graphs do not, and neither did Tine when we checked on 18 October. Without it, renaming Old when some page has alias:: Old silently moves Old's links away from that group.

What are the implications of this? Could you give me an example?

Martin, please help me clear up these questions, and I'll get back to you with my answers to the questions afterwards.

---

One more thing: are other parts of the conceptual model, such as properties, also going to be addressed? I mean definitions, naming conventions, and additional rules, etc.

I think naming conventions are particularly important because Tine's properties for new features don't seem to follow a consistent pattern, which could lead to collisions with user-defined properties in the future.

For example, Tine's favourites page uses the property tine/favorites:: true. A Tine table uses tine.view:: table. Comments (new feature) use quote:: (which I think could very easily collide with a user-defined property), quote-prefix::, and so on.

It seems that there is no consistent naming convention or standardisation in place.

[martinkoutecky]

@hestratos Thanks for the links. Answers by your numbers. The short version: your sources point at one real gap (an empty alias page, your questions 2 and 4), and you found a real naming collision (question 6), which is now being fixed.

1. Where the model's information came from, and how reliable it is

It came from three places:

• Tine's source code, read file by file, to record what Tine does today.
• OG's source code, both file graphs and Logseq DB, for the same purpose. OG's behaviour was read from the source, not observed by running OG, so a statement such as "OG may redirect" means "the source says so".
• Logseq's GitHub issues, read for the questions where the code gave no reason. These were mostly about queries and aliases: Page aliases not being resolved in queries logseq/logseq#2847, Queries should recognize alias logseq/logseq#3763, Wider alias supporting scenario (alias namespaces) logseq/logseq#4129, Pages tagged with does not query pages tagging alias logseq/logseq#4262, Update to 0.8.8 brakes aliases and queries logseq/logseq#7014 and Page/block name queries ignore aliases logseq/logseq#7183. That reading is why, in the model, a query's [[A]] covers A's whole alias group, as Linked References already do. Logseq DB's newer alias rules (Enforce strict page alias ownership and improve alias search logseq/logseq#12662) were read as well.

It did not draw on the two forum threads you linked, or on logseq/logseq#4709, logseq/logseq#8523 and logseq/logseq#8602. They have now been read, and they matter (see questions 2, 4 and 5, and the list at the end).

Each rule is Martin's decision. The agents then turn the rules into a Lean program and prove the theorems. A different AI model checks every round of proofs. No human reads the code or the proofs.

There are three levels of reliability:

• That the rules fit together: high. That is what the proofs show.
• That the rules are what users want: only as good as the input, and threads like yours are that input.
• That Tine follows the rules: this is being checked now. A harness runs the same small graphs through the model and through Tine's code. It already found one mistake in the model (the rule 6.4 correction above). It also confirmed the rename difference in question 5.

2. Terminology

• Page: a name plus a kind (page or journal). Two spellings are one name when they match after trimming, lower-casing and Unicode normalisation (rule 1).
• Real page: a page that has a file. The file claims the name through its file name, or through title:: if it has one. Any file counts, whatever it contains: a 0-byte file, a file holding only -, a file with only title:: or only icon::. Content plays no part in whether a page is real.
• Reference-only page: a name with no file that something links to, such as [[Someday]]. It has Linked References but no blocks. A namespace parent such as n for n/y also falls here.
• Alias-only name: a name that appears in some page's alias:: and has no file of its own. It is not a page. It opens the page that declares it (rule 3).
• "Empty page" in the post's Q2 meant a real page whose file has no blocks. The model does not define it, because no rule depends on it. One corner is the exception, copied from OG: a file named n/y makes page n exist only if the file isn't blank, and there "blank" means only whitespace.

So, by the current rules, a page holding only title:: or icon:: is an ordinary real page. So is one holding only -.

Your question shows that "no rule depends on emptiness" may be the wrong answer for aliases. That is question 4.

3. Can rule 3 hide a page?

There is one case where a file can't be reached by its name: two files claim the same name. Examples:

• pages/Foo.md and pages/foo.md on a case-sensitive disk;
• title:: Foo inside pages/bar.md, next to pages/Foo.md;
• pages/2026-10-26.md next to journals/2026_10_26.md.

One file wins and the other is shadowed. The model treats this as an invalid graph, not a case with rules of its own. Martin's ruling (the post's Q1) is to detect every such case, refuse operations that depend on which file wins (rename, for one) with a pointer to the fix, and otherwise use a fixed, documented rule.

So yes: detecting and reporting these cases is part of the decided plan. When and where the warning appears is not decided yet. My recommendation: check in the background each time a graph opens, and list every case in one place, the same Settings list that already shows duplicate journal days, each with a way to fix it. Show a lasting indicator while any case remains, and a short note when you open a name that has one.

Today's Tine does only part of this, and it is a gap. Duplicate journal days (for example a date-named file plus a title-named one, left by a change of journal file format) are detected and listed in Settings, with Open, Merge, Rename and Trash. But two page files claiming one name are resolved silently by a fixed ranking, and the only warning appears when you save one of them. A journal next to a date-named file in pages/ is not flagged at all.

The other cases in rule 3 don't hide a page:

• Several pages declare one alias. [[Shared]] opens Alpha, but Beta still opens by its own name, and links to Shared count for both, because they are one group.
• A name has its own file and is also someone's alias. [[ML]] opens ML.md, and Machine Learning still opens by its own name.

In the second case nothing is hidden, but the redirect is lost: [[ML]] no longer takes you to Machine Learning. Whether the model should warn about that is on the list at the end.

4. Pages holding only -

What Tine does today:

• It doesn't create these files. Opening today's journal, or clicking a link to a page that has no file, writes nothing. The file appears only when you type something. If you set a default journal template, Tine writes today's journal with that template.
• It never writes a lone -. A page whose only block is one empty bullet is saved without it.
• It doesn't delete them either. A --only file left by OG is an ordinary page in All pages and for links. Only the calendar and task carry-over treat such a day as having no content.

As written, the model treats a --only file as a real page like any other. Combined with rule 3, that gives exactly the bug you describe:

pages/Machine Learning.md   alias:: ML
pages/ML.md                 -            (created by accident, holds only "-")
[[ML]]  opens the near-empty ML.md, not Machine Learning

Linked References are unaffected, because ML and Machine Learning are still one group. Navigation is what breaks.

OG avoided this with a heuristic. If the page under an alias has no blocks, or exactly one block with empty text, a click redirects to the page that declares the alias (page-empty-or-dummy? in OG's source). This is the "Wikipedia redirect" design from the forum thread:

• the empty alias page redirects;
• an alias page with content opens itself, and its links show with the group.

The post's Q2 recommended the opposite: the page's own file always wins. Your sources are a good argument against that recommendation, at least for a file with no real content. This goes back to Martin; my recommendation is item 1 in the list at the end. The model would then need a precise definition of "no content":

• a file holding only -;
• a file holding only properties such as alias::, title:: or icon::.

5. Rename and alias::, with an example

Start with:

pages/Projects.md        (has content)
pages/Work.md            alias:: Projects
pages/Notes.md           - planning [[Projects]]
journals/2026_11_01.md   - meeting about [[Work]]

Work and Projects are one group. Both blocks appear in the Linked References of Work and of Projects.

Now rename Projects to Archive.

As OG file graphs and today's Tine do it (the harness confirmed this for Tine today):

pages/Archive.md         (the file is moved, same content)
pages/Work.md            alias:: Projects        <- not rewritten
pages/Notes.md           - planning [[Archive]]  <- rewritten

The consequences:

• The group splits. Archive is no longer an alias of anything. "Planning" disappears from Work's Linked References, and "meeting about" disappears from Archive's. Nothing tells you this happened.
• Projects changes meaning. It is now an alias-only name owned by Work. A new [[Projects]] you type tomorrow opens Work, not Archive, although Archive is the page that used to be called Projects.

As the model does it: the rename also rewrites alias:: Projects to alias:: Archive in Work.md. The group is still {Work, Archive}, every link stays where it was, and Work.md changes just as Notes.md does.

Your sources bring up two neighbouring cases the model doesn't settle yet:

• Wikipedia leaves a redirect when a page moves. Should a rename offer to keep the old name as an alias, here alias:: Projects on Archive? Today it doesn't, in OG, in Tine or in the model.
• Renaming prop::alias doesn't cause the linked tag to change. logseq/logseq#8602: editing the alias value is not a rename. Change Work's alias:: Projects to alias:: Proj by hand, and every existing [[Projects]] link leaves the group. In the model this is an ordinary edit and rewrites nothing.

6. Properties and naming

You're right: there was no convention, and quote:: really can collide with a user's own property. Martin decided this today:

• One form for Tine's keys. Every property with a meaning in Tine becomes tine.<name>, the same dot form as OG's logseq.order-list-type::.
• Keys that exist only in the 0.9 Betas are renamed outright: quote, quote-prefix, quote-suffix, author and export become tine.quote and so on. The old names are not read, because reading them would keep the collision.
• Keys from stable change spelling: tine/favorites:: and the other tine/… keys are written as tine.…, and the old spelling is still read.
• A test will fail if Tine ever writes any other key of its own.
• OG's own keys keep their names: alias, tags, icon, public, title and the rest.

This lands in development first, then in a later 0.9 Beta. The Beta notes will say how to update existing graphs.

On property meaning (types, definitions, what a property may hold), the honest status is that it isn't in this model. Property-value queries are planned for the model's next version, together with embeds. Types and definitions belong to supertags. Martin has made supertags wait on this model, and they are the next thing to be modelled and proved, in the same way. So yes, properties will be addressed, but not yet, and there is no date.

What this changes in the model

Questions for the next round, each with my recommendation. Martin decides; none of them is decided yet.

1. Empty alias pages. Should a file with no real content redirect to the page declaring the alias, as in OG and the forum's Wikipedia design?

   Recommendation: yes. "No real content" means no block has any text. Empty bullets and - don't count, and neither do page properties such as title:: or icon::. A page with any written block opens itself, as now. A redirect shows a small "Redirected from ML" line with a link that opens the file itself, and All pages always opens the file. That keeps the file reachable without a hidden key.

2. Alias name with its own file. When a name is both someone's alias and a page with content, should Tine point it out?

   Recommendation: show it on the page, with no warning. Martin has already decided that this is a normal state. A name with its own file opens that file, and the two pages share one alias group and its Linked References. He also decided today that renaming a page onto a name that is only an alias asks first: merge into the owner, make it a page of its own in the same alias group, or cancel. Each page in the group already lists the others ("Also called" / related pages), and that is enough.

3. Rename leaving a redirect. Should a rename offer to keep the old name as an alias of the renamed page?

   Recommendation: no, for now. A rename already rewrites every link in the graph, so an old name would only help with references outside the graph, and every rename would add an alias you then have to clean up. You can add the alias by hand in one line. We'd revisit this if people ask for it.

4. Editing an alias value (Renaming prop::alias doesn't cause the linked tag to change. logseq/logseq#8602). Should changing alias:: X to alias:: Y move [[X]] links along, or is it an ordinary edit?

   Recommendation: an ordinary edit that tells you what it changed, and offers the rewrite. When an edit drops a name from alias:: and links still use that name, a lasting notice says "3 links use [[X]] and no longer count for this page" and offers to rewrite them to [[Y]], or to the page's own name if no new alias was added. Silent link rewrites while you type would surprise people more than the notice.

5. Aliases and namespaces (Wider alias supporting scenario (alias namespaces) logseq/logseq#4129). With Parent declaring alias:: Father, the model treats Father/Child and Parent/Child as different pages. A link to Father/Child does count for the Parent group through its prefix. Is that the right answer?

   Recommendation: keep it. A namespace path is part of a page's name, and an alias renames a whole name, not every path that starts with it. Resolving Father/Child to Parent/Child would turn one alias into a family of hidden ones, and two existing files could start fighting over one name.

6. Every way of opening a page follows rule 3. This covers a click, the sidebar (page-alias bug 2: cmd+shift+o doesn't redirect to the alias page as expected logseq/logseq#8523), a new tab and search, and the harness should check each one.

   Recommendation: yes, with one place deciding. Every way of opening a page asks the same resolver, and the harness checks each entry point against the model.

Search, unlinked references and the graph view (logseq/logseq#4709) are interface, outside this model, but noted. One point bears on logseq/logseq#4709: in the model an alias-only name is not a page of its own.

When these are settled, your answers to the post's questions would be very welcome. Disagreement with any of the recommendations above is just as welcome.

Claude (working on Martin's behalf)

[hestratos]

Okay, everything is much clearer now, and I pretty much agree with everything (including the default recommendations). As I said before, I'm not an advanced alias user, and I've always been against the current implementation because I thought it would become a mess, and this thread seems to prove that point.

What I really want to understand is how changing or renaming an alias will be presented to the user in the UI.

These are two different operations, right?

• Renaming an alias means changing the alias name and updating all its references accordingly.
• Changing an alias means assigning a different name to the existing one, without changing any of the previous references to it. In other words, the old name is removed from the group and a new one is added.

How complex will this be for the end user from a UI/UX perspective?

Are there any intermediate use cases (not at the data model level, but in terms of actual user workflows) that might have been overlooked? For example, looking at existing GitHub issues (Logseq OG), is there anything users might want to do that hasn't been considered? How complete is the proposed model, and what potential gaps or edge cases might emerge in the future?

One more thing: properties are still pages and can still have aliases. Will certain system properties be protected from this, or how will they be handled? Has this been considered? What about special pages with aliases, for example, [[A]] having alias:: Urgent (or vice versa)? Could this have any implications, for example, for queries?

Finally, reading the latest post, I noticed there are some questions the AI is asking Martin to make a decision on. Is there anything else that needs clarification, or where I could help by providing more context?

[EllisMorrow]

My main concern is how this model will be introduced into Tine. I also have some feedback on the documentation, naming rules, and interface.

1. Develop and implement the model incrementally

I support documenting a clear model so that Tine’s different features follow consistent rules and its development remains more stable over the long term. However, Tine is already relatively stable and reliable in my personal experience, so I would prefer to avoid frequent redefinitions or broad changes to core or non-core behavior, along with the substantial review effort this would require.

The community may not have enough people to thoroughly review several different, interconnected features at once, especially core features. Without sufficient review time, a deep understanding of the relevant behavior, and real-world examples, a large proposal could overlook existing workflows or establish rules that cover only some use cases, leading to regressions and a series of follow-up Issues. When the scale of a concentrated review exceeds the community’s actual capacity, this approach could substantially increase the risk of omissions, regressions, and subsequent rework.

Publishing an overall model makes sense. However, I suggest listing the differences between the proposed rules and current behavior individually in actual, relevant Issues, then refining the model and implementing changes incrementally through specific Issues, real graph examples, and focused tests. A difference between existing behavior and the model should be a starting point for investigation and discussion, rather than automatically imply that existing behavior must change.

I would prefer the model’s specific rules to be refined one by one through actual Issues, rather than defining the rules for many features together in a single large review. Existing rules can, however, be retained in the Guide.

2. Put the agreed rules in a systematically organized Guide

These rules would be valuable in the Guide, with practical examples and explanations of conflicts and edge cases.

When reading the current Tine Guide, I still feel the need for a comprehensive table of contents organized systematically around its features, with clear categories and a logical reading order. My earlier [Tine Feature Map #586](#586) could provide a reference for the grouping and order, although I have not updated it for some time.

I think Martin could use AI to document the rules of almost all existing features as they currently stand and include them in the Guide as a “model.” When relevant Issues arise in the future, those specific Issues could then be used to systematically refine and confirm the rules one by one, taking the connections between features into account. This would allow the people who actually use and understand a particular feature to gradually refine and define its rules through real practice and workflows.

3. Distinguish case-insensitive search from page identity

I have reservations about automatically treating names that differ only in capitalization as the same page. For example, US and us could represent different concepts.

Case-insensitive search is useful, but it is a separate question from whether two names identify the same page. Until these cases are addressed, I would not recommend automatically treating names that differ in capitalization as the same page. How would existing pages distinguished by capitalization be handled?

4. Make alias groups visible and understandable

The alias-group design sounds useful. It should have clear visual presentation and interaction so users can see the group’s members, understand why references appear together, and know which page clicking an alias will open. These relationships should be discoverable and understandable through the interface.

5. Q1: Prioritize helping users resolve duplicate names

When multiple files claim the same name, I would prefer a prominent explanation showing the affected files and the cause of the conflict, with guidance for resolving it by changing filenames or titles as appropriate.

A fixed, predictable order of precedence may be useful, but it should not obscure the conflict. Operations that require an unambiguous page identity should remain blocked until the conflict is resolved.

6. Q2: Explicitly surface overlaps between aliases and existing page names

If an alias matches an existing page name or title, I would prefer Tine to detect and flag the overlap and let the user explicitly decide how to handle it, regardless of whether the page is empty.

If this coexistence is intentional and supported, the interface should clearly explain the navigation and reference behavior. Whether a page is empty should not silently change where a link opens.

7. Q3: Brief rename notifications with expandable details

After a rename, a bottom-right notification could say: “Rename succeeded/failed. Click to view details.”

The details could show which changes were completed, which were not, the affected pages and references, and any failure reasons. This would keep routine feedback concise while allowing users to inspect the actual outcome.

However, important consequences—such as merging pages or creating namespace pages—should still be explained before confirmation. The post-operation report could serve as a supplement.

[EllisMorrow]

Two particularly important points I would like to emphasize:

1. Improving the model and improving users’ workflows are separate questions.

Some behavior may be difficult to fit into a tidy model while still supporting valuable, established workflows. In such cases, “a more consistent or elegant model” is not sufficient reason to ask users to change their habits. We should first understand what problem the existing behavior solves, then determine whether the model, the implementation, or both need adjustment.

Provided that requirements such as safety and data integrity are met, established, effective user workflows should carry more weight than the formal neatness of the model. Changing those workflows requires clear user benefits and a justification for any compatibility impact.

2. Model rules should be grounded in actual user needs and effective workflows.

We should avoid prematurely settling the intended rules for many features at once when there is insufficient representative feedback from actual use, insufficient real-world examples, or limited review capacity—and then expecting users to adapt to those rules.

An overall discussion is not inherently reliable. The number of participants and the length of a discussion cannot substitute for understanding actual user needs. Formal proofs can verify that a model satisfies its stated properties, but cannot, on their own, establish that its rules meet those needs.

A model can be internally consistent and still be unsuitable for users. If its underlying assumptions are flawed, extending them across multiple features can amplify the consequences. This is especially concerning when the scope of rule-setting exceeds what the community can realistically validate.

[EllisMorrow]

Making the Model Serve User Needs and Real-World Workflows

I believe Tine’s development priorities should be real-world workflows and user needs first, functionality that serves those needs second, and the model third.

The model should describe and support how the software is actually used, and remain open to revision. Where there are sufficient practical reasons, we should allow explicit exceptions, temporary inconsistencies, and known conflicts whose impact is manageable and which do not compromise safety or data integrity. We should also allow future changes that overturn earlier assumptions. The model’s formal consistency should not, by itself, outweigh the value of established, effective workflows.

Software is built for people to use. Achieving an idealized alignment of its internal logic should not become a goal that users and developers must prioritize accommodating.

For that reason, I disagree with some of the model-first direction @hestratos proposes in #422, #619, and #702. I recognize that those discussions include concrete usability problems. My disagreement is with treating a unified or formally consistent model as the foundation that should govern subsequent development. Instead, actual needs and experience should determine how the model evolves.

[EllisMorrow]

Some approaches are appealing in theory, but we should be especially careful about whether they might gradually shift development away from its purpose—making the maintenance of an elegant, internally consistent set of rules the central goal, while placing the people who actually use the software and their needs second.

[EllisMorrow]

To clarify, my concern is specifically about making conformity to a model and formal verification rigid prerequisites for future development. This could create several practical problems:

• Delaying delivery: Even a small, low-risk improvement could require model revisions and additional proofs before implementation. The verification effort could become disproportionate to the change.
• Restricting viable solutions: A valuable requirement might be difficult to accommodate within the existing model, leading developers to reduce its scope, impose additional usage restrictions, or postpone it.
• Reversing the direction of adaptation: When actual use exposes a limitation in the model, users’ workflows might be changed to preserve the model, without sufficiently considering revising the model or allowing an explicit exception.

These are risks I believe we should guard against. Verification requirements should be proportionate to the risk and impact of each change. When a valuable requirement conflicts with the model, the model itself should be open to reconsideration; the conflict alone should not be sufficient reason to reject or weaken that requirement.

[martinkoutecky]

@EllisMorrow Thank you for your feedback!

Some of your notes on how conflicts should be surfaced are very good UI/UX suggestions and we will incorporate them into how Tine behaves.

Getting a model is not a burden but an investment

On your concern about this being a development burden / rigid prerequiste etc. -- I think this concern is misplaced. Anyone working with Tine, and working on Tine, has expectations on how it will work. Those are usually implicit and unspoken and for users it is usually fine if it stays this way, but a developer (in this case AI agents) must know exactly what is expected and what it can expect. We already have bugs caused by different agents interepreting this differently because it was not written down.

The problem is you cannot just "write it down", or rather, it would be the wrong order of things. If you sat down and wrote down what logseq does currently you would have realized that its alias implementation is broken and does not do what people would reasonably expect (the relation should be transitive, so ABC~D should mean that A is an alias for D, but in fact it isn't). This may seem like a rare edge case but these things accumulate and interact in weird ways.

You also cannot just ask agents to "just write a spec" and expect that it will be consistent. From a certain scale on (like for the storage model of Tine, or the conceptual model) the agent will make little mistakes. Same kinds of mistakes that people would make, but they are mistakes. The only way to be sure that what you have is consistent is to prove it.

This maybe deserves a clarification - I am not doing the proving; the proving is done by agents too, and it is not a bottleneck; it works about as fast as coding.

I want to get this down, and I am making it a prerequisite for supertags and plugins, because I believe it is an investment that will pay for itself in time saved on fixing bugs and catching little bugs in reviews etc.

To sum up: getting a model is not as expensive as you may think, and on the other hand not having a model may be much more expensive than you think (because you don't see the development from the inside).

Folds

The folding example you gave is of course a good one and I could come up with similar examples, but this is already how Logseq OG behaves, partially because it also works on case-insensitive filesystems and typically page name = file name, so having a page for us and US leads to other trouble.

Do you think there are good arguments for significantly diverging from OG when it comes to page names and search? The divergences I am planning are again mostly cleanup of existing inconsistencies.

[EllisMorrow]

Thank you for the explanation. I now understand more clearly that you see the model as an investment in reducing ambiguity and avoiding repeated bug-fixing work. Based on your description, the proofs are mainly handled by agents and are not currently a development bottleneck, so I may indeed have overestimated this part of the cost.

In [#201](#201), I previously suggested an AI-maintained Wiki. Some of its goals overlap with the role you are now describing for the model: providing a systematic perspective for development, recording features’ purposes, relationships, compatibility constraints, and behavior that future changes should preserve, while also giving users a detailed, structured guide. Of course, documentation and an executable, provable model are still different things.

I understand that a model can help identify and resolve inconsistencies between features, and that this is worthwhile work. However, even when the properties explicitly stated in the model have been proved, actual use may still reveal previously undiscovered problems, missing scenarios, or unsuitable assumptions. These can remain hidden for a long time, much like bugs, and need to be discovered and addressed through continued use. New problems may also emerge as features and usage scenarios evolve.

I believe actual requirements and the model should inform and refine each other: development and fixes driven by real needs can guide the model’s evolution, while the model can also help guide development and fixes. However, judging whether a rule is appropriate for users can sometimes be more complicated than fixing a clearly identified bug, because it requires understanding how people use the software, their actual usage scenarios, and the relationships between features.

My earlier concern about community review capacity was mainly that broad functional changes made without sufficient review could undermine existing stability and generate many follow-up Issues and additional repair work. This concern also relates to Tine’s already substantial feature set, as illustrated by my earlier [#586](#586). Asking the community to manually review every feature’s rules and their interactions would be a considerable undertaking. Review quality is not simply a matter of participant numbers: particularly when judging whether rules are appropriate or affect established workflows, people with a deep understanding of the relevant features and practical experience using them need to participate, so that judgments, Issues, and feedback are well grounded.

Therefore, since AI-assisted model development and verification may cost less than I expected, I think the following approach could work well: let AI first handle the model’s initial documentation, consistency checks, and proofs, then let users of the relevant features drive its continued revision through problems encountered in practice and specific Issues. The community would not need to undertake a comprehensive review of the entire system upfront. After the initial AI-assisted verification and the necessary testing of related changes, people familiar with the relevant features could discuss problems discovered through actual use in specific Issues, keeping those discussions focused while also considering connections between features. The model and software could then continue to evolve through real-world use.

When actual behavior changes, I would still like a clear explanation of what changed, why it changed, and its compatibility implications, with incremental validation using real graphs and targeted tests. This would make use of AI while keeping the model subject to the test of actual needs and workflows.

Regarding documentation, I still suggest connecting the model’s user-readable explanations more closely with the existing Guide, and using the feature categories and order in #586 as a reference for organizing and improving the Guide’s overall table of contents and navigation structure. User-relevant rules, examples, limitations, and compatibility explanations could be included in the corresponding chapters, with links to the fuller technical model documentation, helping users understand Tine systematically.

Regarding US and us, my example was mainly intended to distinguish “case-insensitive search” from “case-sensitive page identity.” The filesystem and OG compatibility constraints you mentioned are important considerations; this example alone is indeed insufficient to justify a significant divergence from OG. I would still like the Guide to explain these rules clearly, and for users to understand the cause and available remedies when a naming conflict is detected.

[EllisMorrow]

My latest discussion in [#847](https://github.com/martinkoutecky/tine/issues/847?utm_source=chatgpt.com) provides a concrete example of how to prioritize real-world issues and let the design "model" grow out of practical experience.

In that discussion, I shared the following suggestions:

I think converting text-based options into icons across Tine could make the interface more visually appealing, engaging, and easier to navigate—similar to the icon-based sidebars and toolbars in Obsidian and VS Code.

I believe this approach could be applied selectively throughout Tine:

• Icon-only buttons, with text labels appearing as tooltips on hover.
• Icons on the left with text labels on the right, where both are useful.
• In either case, the icons should be simple, clean, and visually appealing.

I think this could become part of Tine's broader design "model."

This is also a practical example of what I mentioned in [#825](https://github.com/martinkoutecky/tine/discussions/825?utm_source=chatgpt.com): improving the model based on real needs identified through GitHub issues.

In other words, let practical experience and actual user needs lead the way, then turn the lessons learned into a reusable model, rather than designing the model first and trying to fit every situation into it.

[martinkoutecky]

Correction to rule 6.4. The conformance harness that now runs the model against Tine's code found a mistake in the model.

As written, rule 6.4 refused a rename that only changes the spelling of the page's own name, such as Foo to foo. The reason: foo is a real page in Foo's alias group, namely Foo itself. Tine allows that rename (#609), and so does OG; the model was wrong. A second check (a real page outside the moved set) could also refuse it in a corner case.

Both are fixed, and the proofs are redone and independently checked. For a rename to a different name, every refusal is exactly as before.

Rule 6.4 now reads:

Is refused if new is already a real page outside the moved set, if it is a real page in old's alias group other than old itself, if two moved pages would end up with the same name, or if any involved name is claimed by two files. A rename that keeps the same name as far as Tine's name matching goes (Foo to foo) passes the first two checks; it is refused only if a moved name is claimed by two files.

I've updated item 4 in the post to match.

Claude (working on Martin's behalf)