mirror of
https://github.com/usememos/memos.git
synced 2026-11-19 10:29:11 +01:00
docs: retire ADRs and freeze implemented designs
This commit is contained in:
@@ -8,7 +8,7 @@ repo. If a fact here conflicts with source files or CI config, trust the source
|
||||
Memos is a self-hosted note-taking app.
|
||||
|
||||
- Backend: Go 1.27.0, Echo v5, Connect RPC, gRPC-Gateway, Protocol Buffers.
|
||||
- Frontend: React 19, TypeScript 6, Vite 8, Tailwind CSS v4, React Query v5.
|
||||
- Frontend: React 19, TypeScript 7, Vite 8, Tailwind CSS v4, React Query v5.
|
||||
- Storage: SQLite, MySQL, PostgreSQL.
|
||||
- Generated API outputs: `proto/gen/` for Go/OpenAPI, `web/src/types/proto/` for TypeScript.
|
||||
|
||||
@@ -21,6 +21,13 @@ Memos is a self-hosted note-taking app.
|
||||
- Add public API endpoints to `server/api/v1/acl_config.go`.
|
||||
- Ask before adding heavy dependencies, changing auth/token behavior, or altering Docker/release workflows.
|
||||
|
||||
## Documentation
|
||||
|
||||
- ADRs and their companion glossary have been retired. Do not recreate them unless explicitly requested.
|
||||
- Design documents in `docs/design/` are frozen after implementation. Do not update implemented designs to track later code changes.
|
||||
- New and unimplemented designs may still evolve. Frozen documents record the original design; verify current behavior in source code and tests.
|
||||
- Keep contributor guidance in this file and package-local `README.md` or `doc.go` files current when relevant code changes.
|
||||
|
||||
## Commands
|
||||
|
||||
Run from the repository root unless a command starts with `cd`.
|
||||
@@ -64,7 +71,7 @@ Every root folder is named for what it holds. Read the folder's `doc.go` or `REA
|
||||
| `server/frontend/` | Static SPA serving; `dist/` is the built SPA baked in by `go:embed` | |
|
||||
| `server/mcp/` | Model Context Protocol server | |
|
||||
| `server/auth/` | JWT access tokens, refresh tokens, PAT handling | |
|
||||
| `core/` | Business rules with no HTTP and no SQL: `access`, `notification`, `memopayload` | store, provider, markdown, filter, internal |
|
||||
| `core/` | Business rules with no HTTP and no SQL: `access`, `notification`, `memopayload`, `memoexport` | store, provider, markdown, filter, internal |
|
||||
| `store/` | Store facade, cache, migrations, `Driver` interface; `store/db/{sqlite,mysql,postgres}/` implement it | provider, markdown, filter, internal |
|
||||
| `markdown/` | Markdown engine: parser, AST, memos syntax extensions, renderer, memo payload | proto/gen, internal |
|
||||
| `filter/` | CEL filter compiler: parse to IR, render to SQL per driver, filterable field schema | internal |
|
||||
@@ -112,7 +119,7 @@ Black-box service tests live in `server/api/v1/test/`, unit tests next to the co
|
||||
- Follow Biome formatting: 2-space indent, double quotes, semicolons, 140-character line width.
|
||||
- Put server data in React Query hooks under `web/src/hooks/`; keep UI-only state in contexts or component state.
|
||||
- Use Tailwind CSS v4 utilities, `cn()` for class merging, and CVA for variants.
|
||||
- Reuse Radix primitives and existing components before adding new UI primitives.
|
||||
- Reuse Base UI primitives and existing components before adding new UI primitives.
|
||||
- Keep generated proto TypeScript under `web/src/types/proto/` out of manual edits and Biome rewrites.
|
||||
|
||||
## Database And Proto Rules
|
||||
|
||||
@@ -1,635 +0,0 @@
|
||||
# ADR 0001: Tag Syntax and Recognition
|
||||
|
||||
Status: Accepted
|
||||
|
||||
Date: 2026-08-01
|
||||
|
||||
Domain glossary: [Memos domain glossary](../glossary.md)
|
||||
|
||||
## Context
|
||||
|
||||
Tags are part of Memos' Markdown language, not merely an editor decoration. A tag occurrence affects rendered memo content, the derived tags stored in a
|
||||
memo payload, API responses, tag counts, filters, tag metadata, navigation, and editor completion.
|
||||
|
||||
Memos currently has four related but different implementations:
|
||||
|
||||
- The Go Markdown parser recognizes Unicode letters, marks, numbers, and symbols, plus `ZWJ`, `_`, `-`, `/`, and `&`. It extracts at most 100 Unicode
|
||||
code points and has no general left boundary.
|
||||
- The read-only remark plugin uses a similar frontend character class without `ZWJ`. It rejects a run longer than 100 code points and has special handling
|
||||
for adjacent `#` characters.
|
||||
- The editor decoration uses the frontend character class but requires a non-letter/non-number before `#`, so it does not highlight `hello#tag`. It scans
|
||||
raw text without consulting the editor's Markdown syntax tree.
|
||||
- Editor completion has no left boundary, no length limit, and no Markdown-context check.
|
||||
|
||||
These differences expose implementation drift but do not define the desired language. This ADR starts from intended product semantics; current behavior
|
||||
is non-normative.
|
||||
|
||||
This ADR defines the current Memos tag syntax and recognition rules, covering:
|
||||
|
||||
- The lexical form of a tag identifier.
|
||||
- How a tag candidate is found in flowing Markdown text.
|
||||
- Which Markdown contexts can contain a tag occurrence.
|
||||
- Pinned Unicode and emoji data.
|
||||
|
||||
Existing-data migration, rollout, backfill, and metadata remapping are outside this ADR's scope.
|
||||
|
||||
Markdown context is defined against the [GFM 0.29-gfm specification](https://github.github.com/gfm/). Memos-specific Markdown extensions layer on that
|
||||
baseline and are opaque to tag recognition unless their own definition explicitly exposes ordinary text.
|
||||
|
||||
The slash is a hierarchy separator between non-empty segments. `-`, `+`, and `&` are unrestricted visible segment units. Tag equality is exact: the display
|
||||
value itself is the comparison key, with no case folding or Unicode normalization.
|
||||
|
||||
A tag is a value derived from memo Markdown, not a durable entity with an identity independent of its source occurrences. Memos cannot rename a tag by
|
||||
changing metadata or a separate tag record. Renaming `#Work` to `#work` across 100 memos requires editing those 100 memo sources.
|
||||
|
||||
## Decision drivers
|
||||
|
||||
- Work naturally for multilingual personal notes, including numeric tags and emoji.
|
||||
- Preserve common word-internal apostrophes without absorbing surrounding quotation punctuation into tag values.
|
||||
- Recognize `hello#tag` intentionally without mistaking URL fragments for tags.
|
||||
- Give the backend, renderer, editor decoration, and completion the same values and source spans.
|
||||
- Use Markdown syntax rather than ad hoc URL or code regular expressions.
|
||||
- Avoid accepting every Unicode symbol merely to support emoji.
|
||||
- Keep parsing deterministic across Go, JavaScript runtimes, and Unicode upgrades.
|
||||
- Keep lexical scanning linear in memo size.
|
||||
|
||||
## Terminology
|
||||
|
||||
**Tag**
|
||||
: A classification value in a memo tag set, derived from one or more tag occurrences either as a direct tag value or as an implied ancestor. A tag is not
|
||||
independently created, owned, or renamed outside the source text that produces it.
|
||||
|
||||
**Introducer**
|
||||
: An ASCII number sign `#` (U+0023) that is not part of a matched fully-qualified emoji sequence and begins a tag candidate. It is not included in the
|
||||
extracted tag value.
|
||||
|
||||
**Tag identifier**
|
||||
: The non-empty Unicode code-point sequence emitted from a tag source spelling, for example `work/notes` from `#work/notes`.
|
||||
|
||||
**Tag candidate**
|
||||
: An introducer followed by a source spelling that matches the lexical grammar entirely within one literal-source run, before that run's Markdown context
|
||||
is checked for eligibility.
|
||||
|
||||
**Tag occurrence**
|
||||
: A tag candidate whose complete recognized source span is in an eligible literal-source run.
|
||||
|
||||
**Literal-source run**
|
||||
: A contiguous range of original Markdown source exposed by parsing as literal characters with no intervening Markdown escape, character reference, syntax
|
||||
token, or node boundary. Each run retains its enclosing Markdown context for eligibility checks.
|
||||
|
||||
**Eligible text**
|
||||
: A literal-source run whose enclosing context is classified as textual content by GFM 0.29-gfm or explicitly exposed as ordinary text by a Memos
|
||||
Markdown extension.
|
||||
|
||||
**Opaque Markdown node**
|
||||
: A GFM syntax node or Memos extension node whose source is not eligible for tag recognition. New extension node types are opaque by default.
|
||||
|
||||
**Source spelling**
|
||||
: The exact source substring consumed after the introducer, including ignored default-ignorable code points and ignored leading combining marks. Inline
|
||||
rendering and source-preserving operations use this spelling.
|
||||
|
||||
**Recognized source span**
|
||||
: The exact contiguous substring of original Markdown formed by the introducer and its complete source spelling.
|
||||
|
||||
**Direct tag value**
|
||||
: The identifier value emitted from a tag occurrence before hierarchy expansion. It may differ from the source spelling because default-ignorable code
|
||||
points outside a matched fully-qualified emoji sequence and ignored leading combining marks before the starter of each segment are consumed but omitted.
|
||||
|
||||
**Implied ancestor tag**
|
||||
: A slash-delimited prefix derived from a direct tag value. For example, `book` is an implied ancestor of the direct value `book/fiction`.
|
||||
|
||||
**Tag segment**
|
||||
: A non-empty component of a hierarchical tag identifier. Slashes separate segments and are not part of any segment.
|
||||
|
||||
**Apostrophe joiner**
|
||||
: U+0027 APOSTROPHE (`'`) or U+2019 RIGHT SINGLE QUOTATION MARK (`’`) emitted inside a tag segment only when, after emoji-first tokenization, the
|
||||
immediately preceding source code point emits as an `XID_Continue` code point and the immediately following source code point emits as a non-combining
|
||||
`XID_Continue` code point.
|
||||
|
||||
**Display value**
|
||||
: The direct or implied value presented as a derived tag label. It preserves emitted code points exactly but does not contain ignored default-ignorable code
|
||||
points or ignored leading combining marks.
|
||||
|
||||
**Comparison key**
|
||||
: The value used to compare two display values for tag identity. It is the exact display value without case folding or Unicode
|
||||
normalization.
|
||||
|
||||
**Memo tag set**
|
||||
: The union of direct tag values and their implied ancestor tags exposed for a memo. Each exactly equal value appears once; any difference in the value's
|
||||
Unicode code-point sequence produces a separate membership.
|
||||
|
||||
**Tag metadata rule**
|
||||
: User configuration that selects tag values and supplies presentation or behavior metadata. Creating or changing a metadata rule does not create or rename
|
||||
a tag.
|
||||
|
||||
## Decision
|
||||
|
||||
### Domain ownership
|
||||
|
||||
Memo Markdown is the source of truth for tags. Stored payload tags, API fields, counts, navigation entries, completion candidates, and metadata matches are
|
||||
derived projections of recognized source occurrences.
|
||||
|
||||
There is no independently mutable tag resource in this domain model. In particular:
|
||||
|
||||
- A tag cannot be renamed without editing every memo source occurrence that should change.
|
||||
- Tag metadata may decorate or affect matching derived values, but it cannot change their source spelling or identity.
|
||||
- Persisted payload tags are rebuildable indexes, not authoritative tag records.
|
||||
- Import and export preserve memo Markdown; they do not substitute a separate canonical tag label for the spelling in source.
|
||||
|
||||
### Lexical syntax
|
||||
|
||||
Memos tag syntax is based on Unicode UAX #31 and Unicode Emoji data, with custom rules for Memos. It is not an unchanged implementation of UAX31-R8 or
|
||||
the UAX #31 Emoji Profile.
|
||||
|
||||
The normative grammar is:
|
||||
|
||||
```text
|
||||
TagCandidate := Introducer TagSourceSpelling
|
||||
Introducer := U+0023 NUMBER SIGN ("#") outside a FullyQualifiedEmoji
|
||||
TagSourceSpelling := TagSegmentSpelling ("/" TagSegmentSpelling)*
|
||||
TagSegmentSpelling := IgnoredPrefix* SegmentStarter SegmentContinuation*
|
||||
IgnoredPrefix := IgnoredDefaultIgnorable | IgnoredLeadingCombiningMark
|
||||
SegmentContinuation := ValueUnit | ApostropheJoiner | IgnoredDefaultIgnorable
|
||||
|
||||
SegmentStarter := EmittedXIDContinueCodePointExceptCombiningMark
|
||||
| FullyQualifiedEmoji
|
||||
| "-"
|
||||
| "+"
|
||||
| "&"
|
||||
|
||||
ValueUnit := EmittedXIDContinueCodePoint
|
||||
| FullyQualifiedEmoji
|
||||
| "-"
|
||||
| "+"
|
||||
| "&"
|
||||
|
||||
ApostropheJoiner := U+0027 APOSTROPHE ("'")
|
||||
| U+2019 RIGHT SINGLE QUOTATION MARK ("’")
|
||||
|
||||
IgnoredDefaultIgnorable := Default_Ignorable_Code_Point outside a FullyQualifiedEmoji
|
||||
IgnoredLeadingCombiningMark := XID_Continue with General_Category Mn or Mc,
|
||||
minus Default_Ignorable_Code_Point, before SegmentStarter
|
||||
```
|
||||
|
||||
The grammar recognizes source spelling and emits a tag identifier as follows:
|
||||
|
||||
- Each `SegmentStarter`, `ValueUnit`, and contextually valid `ApostropheJoiner` emits its exact source code-point sequence. A `FullyQualifiedEmoji`
|
||||
therefore emits its complete matched sequence.
|
||||
- Each consumed `/` emits one U+002F SOLIDUS into the identifier.
|
||||
- `Introducer`, `IgnoredDefaultIgnorable`, and `IgnoredLeadingCombiningMark` emit nothing.
|
||||
|
||||
At every source position, the token priority is the longest `FullyQualifiedEmoji`, then `IgnoredDefaultIgnorable`, then `IgnoredLeadingCombiningMark`, then
|
||||
a contextually valid `ApostropheJoiner`, then an emitted code point or Memos extension unit. This preserves default-ignorable code points inside matched
|
||||
fully-qualified emoji sequences while omitting them everywhere else.
|
||||
|
||||
The emitted tag identifier is the direct tag value.
|
||||
|
||||
Rules:
|
||||
|
||||
1. `EmittedXIDContinueCodePoint` is a Unicode code point with the `XID_Continue` property in Unicode 17.0, minus
|
||||
`Default_Ignorable_Code_Point` in Unicode 17.0.
|
||||
2. `EmittedXIDContinueCodePointExceptCombiningMark` additionally excludes General Category `Mn` and `Mc` code points.
|
||||
3. `_` is already included in `XID_Continue` and is not a separate extension.
|
||||
4. `FullyQualifiedEmoji` is a code-point sequence whose `RGI_Emoji_Qualification` value is `Fully_Qualified`, represented by status `fully-qualified` in
|
||||
the Emoji 17.0 `emoji-test.txt` data. It is matched atomically and before any shorter unit. The `Standalone_Component` value, represented by status
|
||||
`component`, is not included.
|
||||
5. The raw union of `Extended_Pictographic` and `Emoji_Component` is not used. That union admits bare `*`, isolated emoji components, invisible emoji tag
|
||||
characters, and code points reserved for future emoji.
|
||||
6. U+0023 ASCII NUMBER SIGN is the only tag introducer, but a `#` already matched inside the fully-qualified keycap sequence `#️⃣` is an emoji unit rather
|
||||
than an introducer. U+FE5F SMALL NUMBER SIGN and U+FF03 FULLWIDTH NUMBER SIGN are ordinary text.
|
||||
7. An ordinary `#` that does not begin a `FullyQualifiedEmoji` terminates the current identifier and may introduce another tag. The `#` in `#️⃣` is
|
||||
preserved as part of that atomic emoji value unit under the same longest-match rule as every other admitted emoji.
|
||||
8. Numeric-only and emoji-only identifiers are valid.
|
||||
9. `/` is a hierarchy separator and is consumed only between two non-empty segments. It cannot begin or end an identifier, and two `/` separators cannot be
|
||||
adjacent.
|
||||
10. `-`, `+`, and `&` are Memos-specific segment-unit extensions. They are allowed at any position, may repeat, and may form an entire segment.
|
||||
11. Default-ignorable code points inside a `FullyQualifiedEmoji` are preserved as part of that atomic value unit. Any other
|
||||
`Default_Ignorable_Code_Point` is consumed as part of the source spelling but emits no code point into the direct tag value. Ignored code points do not
|
||||
by themselves make a segment non-empty.
|
||||
12. A non-default-ignorable `XID_Continue` code point whose General Category is `Mn` (Nonspacing Mark) or `Mc` (Spacing Combining Mark) is consumed but
|
||||
omitted while it precedes the starter of its segment. The same non-default-ignorable code point is preserved as a value unit after that segment's
|
||||
starter.
|
||||
13. After applying the longest-`FullyQualifiedEmoji` token priority, U+0027 APOSTROPHE and U+2019 RIGHT SINGLE QUOTATION MARK are emitted as
|
||||
`ApostropheJoiner` only when the immediately preceding source code point in the same segment was emitted as an `EmittedXIDContinueCodePoint` and the
|
||||
immediately following source code point can emit as an
|
||||
`EmittedXIDContinueCodePointExceptCombiningMark`. An apostrophe joiner therefore cannot start or end a segment, repeat without an intervening XID
|
||||
code point, adjoin a fully-qualified emoji or Memos extension unit, or join across an ignored code point.
|
||||
14. U+02BC MODIFIER LETTER APOSTROPHE (`ʼ`) is already an `XID_Continue` code point. It follows the ordinary XID rules rather than the contextual
|
||||
apostrophe-joiner rule.
|
||||
15. There is no tag-specific identifier length limit. The enclosing memo-size limit provides the resource bound.
|
||||
|
||||
The grammar is intentionally broader than a programming-language identifier grammar. It does not require the first emitted unit to be `XID_Start`:
|
||||
digits, `_`, `-`, `+`, `&`, and fully-qualified emoji can start a segment. Default-ignorable code points and non-default-ignorable `Mn` or `Mc` code points
|
||||
may occur before each segment's starter but are omitted from the value. After the starter, those non-default-ignorable `Mn` and `Mc` code points are
|
||||
preserved. ASCII and right-curly apostrophes are emitted only as contextual joiners between XID code points. A slash cannot begin a segment, and segments
|
||||
made only from `-`, `+`, and `&` are explicitly valid.
|
||||
|
||||
### Maximal-prefix scanning
|
||||
|
||||
After finding an introducer, the lexer consumes the longest valid `TagSourceSpelling` within the current literal-source run:
|
||||
|
||||
1. Before each segment's starter, consume default-ignorable code points and non-default-ignorable `XID_Continue` code points in General Category `Mn` or
|
||||
`Mc` into the source spelling without emitting them.
|
||||
2. Emit a segment starter, trying the longest matching `FullyQualifiedEmoji` before any shorter unit.
|
||||
3. After the starter, preserve non-default-ignorable `XID_Continue` combining marks as ordinary value units; continue consuming default-ignorable code
|
||||
points without emitting them.
|
||||
4. Emit U+0027 or U+2019 as an apostrophe joiner only when, after emoji-first tokenization, the immediately preceding source code point emitted an XID
|
||||
continuation unit and the immediately following source code point can emit a non-combining XID continuation unit. Otherwise stop before the
|
||||
apostrophe.
|
||||
5. Consume `/` only when the following source, after any ignored prefix, can emit a segment starter; then consume that segment.
|
||||
6. Stop before a `/` that is leading, trailing, or followed only by an ignored prefix and then another `/`, a non-starter, or the end of the literal-source
|
||||
run, leaving that slash and the remaining source unconsumed.
|
||||
7. Otherwise stop before the first code point that cannot begin a valid continuation unit.
|
||||
8. Keep the valid prefix already consumed; a later invalid character does not invalidate it.
|
||||
9. Produce no candidate if the first `TagSegmentSpelling` cannot match.
|
||||
|
||||
### Candidate enumeration
|
||||
|
||||
Candidate discovery and identifier scanning use the same token priority:
|
||||
|
||||
1. Match the longest `FullyQualifiedEmoji` at the current position before interpreting any constituent code point separately. Outside an active tag
|
||||
candidate, advance past the complete sequence.
|
||||
2. If no emoji sequence matches and the current code point is an introducer, scan a tag candidate.
|
||||
3. After a successful candidate, continue at the first unconsumed source position. An ordinary terminating `#` is therefore reconsidered as a possible next
|
||||
introducer.
|
||||
4. After a failed introducer, advance by one code point so an adjacent `#` is still considered.
|
||||
5. Otherwise, advance by one code point.
|
||||
|
||||
This produces:
|
||||
|
||||
```text
|
||||
#️⃣ -> no tag; the source is one emoji
|
||||
##️⃣ -> #️⃣
|
||||
#first#️⃣ -> first#️⃣
|
||||
#first#second -> first, second
|
||||
##tag -> tag
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
| Source | Identifier | Remaining source |
|
||||
| --- | --- | --- |
|
||||
| `#foo,bar` | `foo` | `,bar` |
|
||||
| `#foo.bar` | `foo` | `.bar` |
|
||||
| `#foo:bar` | `foo` | `:bar` |
|
||||
| `#x=y` | `x` | `=y` |
|
||||
| `#price€` | `price` | `€` |
|
||||
| `#C++` | `C++` | empty |
|
||||
| `#R&D` | `R&D` | empty |
|
||||
| `#tag's` | `tag's` | empty |
|
||||
| `#сім'я` | `сім'я` | empty |
|
||||
| `#O’Brien` | `O’Brien` | empty |
|
||||
| `#café's` | `café's` | empty |
|
||||
| `#users'` | `users` | `'` |
|
||||
| `#foo'1️⃣` | `foo` | `'1️⃣` |
|
||||
| `#'tag` | none | `'tag` |
|
||||
| `#-foo` | `-foo` | empty |
|
||||
| `#foo-` | `foo-` | empty |
|
||||
| `#---` | `---` | empty |
|
||||
| `#&&` | `&&` | empty |
|
||||
| `#AB` | `AB` | empty |
|
||||
| `#foo` | `foo` | empty |
|
||||
| `#AB` | `AB` | empty |
|
||||
| `#foo` | `foo` | empty |
|
||||
| `#A️B` | `AB` | empty |
|
||||
| `#́foo` | `foo` | empty |
|
||||
| `#́` | none | U+0301 COMBINING ACUTE ACCENT |
|
||||
| `#café` | `café` | empty |
|
||||
| `#work/notes` | `work/notes` | empty |
|
||||
| `#foo/́bar` | `foo/bar` | empty |
|
||||
| `#book/` | `book` | `/` |
|
||||
| `#/book` | none | `/book` |
|
||||
| `#book//fiction` | `book` | `//fiction` |
|
||||
| `#book/fiction/` | `book/fiction` | `/` |
|
||||
| `#foo\+bar` | `foo` | `\+bar` |
|
||||
| `#R&D` | `R` | `&D` |
|
||||
|
||||
For the source below, the identifier is `foo`; the inline-code span begins immediately afterward:
|
||||
|
||||
```markdown
|
||||
#foo`test`
|
||||
```
|
||||
|
||||
### Introducer boundary
|
||||
|
||||
There is no general character boundary before the introducer. The following all contain the identifier `tag`:
|
||||
|
||||
```text
|
||||
#tag
|
||||
hello#tag
|
||||
中文#tag
|
||||
```
|
||||
|
||||
This intentionally differs from the flowing-text boundary recommendation in UAX #31. Memos can distinguish URL fragments using its Markdown parser and
|
||||
does not need to approximate URLs by forbidding a letter or number before `#`.
|
||||
|
||||
An ordinary `#` is a hard boundary between identifiers:
|
||||
|
||||
```text
|
||||
#first#second -> first, second
|
||||
##tag -> tag, introduced by the second #
|
||||
## tag -> no tag; this is an ATX heading marker followed by text
|
||||
```
|
||||
|
||||
### Markdown-context validation
|
||||
|
||||
Markdown parsing first divides the original source into literal-source runs and records each run's enclosing context. Lexical scanning then finds candidates
|
||||
within, but never across, those runs. A candidate becomes a tag occurrence only when its complete source span is in eligible text under GFM 0.29-gfm plus
|
||||
the declared Memos extensions.
|
||||
|
||||
The lexer reads literal characters from each literal-source run's original source range. It does not scan a decoded or rendered text-node value. A Markdown
|
||||
escape, character reference, or other syntax node is a hard boundary that a candidate cannot cross.
|
||||
|
||||
Tag occurrences are allowed in text contained by formatting and block structure, including emphasis, strong emphasis, strikethrough, headings, lists,
|
||||
quotes, and table cells.
|
||||
|
||||
Tag occurrences do not arise from source that is:
|
||||
|
||||
- Escaped by Markdown, as in `\#tag`.
|
||||
- Inside inline code, fenced code, or indented code.
|
||||
- Anywhere inside a Markdown link, autolink, GFM literal URL, link reference, image, or image alt text.
|
||||
- Inside raw HTML syntax or an opaque raw HTML block.
|
||||
- Inside an opaque Memos extension node, including inline or block math.
|
||||
|
||||
Consequently, a character reference that renders as `#` is not an introducer, and syntax that renders as an otherwise valid tag unit does not join the
|
||||
literal source on either side:
|
||||
|
||||
```text
|
||||
#tag -> no tag
|
||||
#tag -> no tag
|
||||
#foo\+bar -> foo
|
||||
#R&D -> R
|
||||
#R&D -> R&D
|
||||
```
|
||||
|
||||
The complete link-like node is excluded, not only its destination. Therefore neither the label nor destination produces a tag:
|
||||
|
||||
```markdown
|
||||
[release #notes](https://example.com/releases#notes)
|
||||
```
|
||||
|
||||
Context is determined by the Markdown syntax tree or AST, not by a second URL regular expression. This has two important consequences:
|
||||
|
||||
```text
|
||||
https://example.com/path#tag -> no tag when parsed as a URL/autolink
|
||||
/path#tag -> tag when the text is not parsed as a link
|
||||
```
|
||||
|
||||
Text between inline HTML tags may still contain a tag when the Markdown parser exposes that text as an ordinary text node. The HTML markup itself and
|
||||
opaque HTML blocks are never scanned.
|
||||
|
||||
### Extracted value and source span
|
||||
|
||||
- The extracted direct tag value contains the emitted identifier only, never the introducer.
|
||||
- The recognized source span contains the introducer and the entire consumed source spelling.
|
||||
- Highlighting and inline rendered tag markup use that full source span and preserve its source spelling; derived tag labels use the display value.
|
||||
- Completion replaces the consumed source spelling after the introducer; it does not replace preceding prose.
|
||||
- The original source spelling is preserved. Case folding and normalization must not occur before lexical boundaries are found.
|
||||
- A default-ignorable code point outside a matched fully-qualified emoji sequence or an ignored leading combining mark before any segment's starter belongs
|
||||
to the recognized source span but is omitted from the extracted value.
|
||||
|
||||
For example, `##tag` extracts the value `tag`, while the recognized source span is the second `#tag`.
|
||||
|
||||
For `#AB`, the recognized source span contains `#`, `A`, U+200D ZWJ, and `B`, while the extracted direct value is the two-code-point string `AB`.
|
||||
|
||||
For `#́foo`, the recognized source span includes the leading U+0301 COMBINING ACUTE ACCENT, while the extracted direct value is `foo`. In `#café`, the
|
||||
same U+0301 follows a segment starter and remains part of the extracted value.
|
||||
|
||||
### Identifier equality
|
||||
|
||||
The comparison key is the emitted display value. Two identifiers are equal only when their emitted Unicode code-point sequences are identical. Source
|
||||
spellings that differ only by ignored default-ignorable code points or ignored leading combining marks therefore compare equal.
|
||||
|
||||
Memos does not apply case folding, canonical normalization, compatibility normalization, width folding, locale-sensitive comparison, or accent folding when
|
||||
deduplicating, counting, filtering, navigating, or performing exact metadata lookup. Consequently, each pair below contains two distinct tags:
|
||||
|
||||
```text
|
||||
#Work / #work
|
||||
#café / #café
|
||||
#A / #A
|
||||
#straße / #STRASSE
|
||||
#O'Brien / #O’Brien
|
||||
#O’Brien / #OʼBrien
|
||||
```
|
||||
|
||||
Multiple occurrences that emit exactly equal direct tag values in one memo produce one memo-tag membership. A tag metadata rule may deliberately match
|
||||
several distinct tags, but that rule does not change their identity.
|
||||
|
||||
Lexical emission applies only when recognizing Markdown source. An operand supplied to an exact filter or metadata lookup is already a tag value: it is
|
||||
compared as supplied and is not re-lexed or stripped of code points.
|
||||
|
||||
For example, `#AB`, `#AB`, and `#AB` all emit the comparison key `AB`; `#foo` and `#́foo` both emit `foo`. Each group contributes one tag membership if its
|
||||
spellings occur in the same memo. Their Markdown source remains unchanged.
|
||||
|
||||
### Hierarchy and memo membership
|
||||
|
||||
The slash `/` is a structural hierarchy separator, not an opaque character in a tag value. A direct tag value contributes itself and every slash-delimited
|
||||
ancestor prefix to the memo tag set:
|
||||
|
||||
```text
|
||||
Source occurrence: #book/fiction/history
|
||||
Direct tag value: book/fiction/history
|
||||
Memo tag set: book, book/fiction, book/fiction/history
|
||||
```
|
||||
|
||||
Hierarchy expansion has the following domain semantics:
|
||||
|
||||
- `Memo.tags` exposes both direct values and implied ancestors.
|
||||
- Exact membership filtering for an ancestor matches a memo containing only a descendant occurrence.
|
||||
- A tag count is the number of memo tag sets containing that value. One memo contributes at most one count to each direct or implied tag.
|
||||
- Rendering and export preserve the one source occurrence; hierarchy expansion does not insert ancestor hashtags into Markdown.
|
||||
|
||||
Every hierarchy segment is non-empty. A leading slash produces no candidate; a trailing or repeated slash terminates the identifier before that slash under
|
||||
the maximal-prefix rule.
|
||||
|
||||
### Pinned Unicode and emoji data
|
||||
|
||||
Tag recognition is pinned to Unicode 17.0 and Emoji 17.0. Go, browser, and Node runtime tables are not implicitly normative.
|
||||
|
||||
The pinned Unicode property assignments and Emoji data are normative, rather than the tables supplied by a particular runtime. Updating either data set
|
||||
requires an explicit specification change because newly assigned `XID_Continue` characters and newly fully-qualified emoji sequences change what source
|
||||
text means. Effects on existing data after such an update are outside scope.
|
||||
|
||||
## Conformance examples
|
||||
|
||||
The following examples are normative for the lexical and context decisions already made:
|
||||
|
||||
| Source | Extracted identifiers | Reason |
|
||||
| --- | --- | --- |
|
||||
| `#tag` | `tag` | Basic identifier |
|
||||
| `hello#tag` | `tag` | No general left boundary |
|
||||
| `#标签` | `标签` | Multilingual XID characters |
|
||||
| `#2026` | `2026` | Numeric-only identifiers are valid |
|
||||
| `#C++` | `C++` | Explicit `+` extension |
|
||||
| `#R&D` | `R&D` | Explicit `&` extension |
|
||||
| `#tag's` | `tag's` | ASCII apostrophe joins two XID code points |
|
||||
| `#сім'я` | `сім'я` | ASCII apostrophe preserves a Ukrainian word |
|
||||
| `#O’Brien` | `O’Brien` | Right single quotation mark joins two XID code points |
|
||||
| `#café's` | `café's` | An emitted combining mark may precede an apostrophe joiner |
|
||||
| `#users'` | `users` | A trailing apostrophe is not a joiner |
|
||||
| `#foo'1️⃣` | `foo` | Emoji-first tokenization prevents an apostrophe from adjoining the keycap sequence |
|
||||
| `#'tag` | none | An apostrophe cannot start a segment |
|
||||
| `'#tag'` | `tag` | Surrounding quotation punctuation remains outside the occurrence |
|
||||
| `#rock’n’roll` | `rock’n’roll` | Multiple apostrophe joiners are valid when each independently satisfies the context rule |
|
||||
| `#OʼBrien` | `OʼBrien` | U+02BC is an ordinary `XID_Continue` code point |
|
||||
| `#` followed by 101 `a` code points | all 101 `a` code points | There is no tag-specific length limit |
|
||||
| `#-foo` | `-foo` | Visible connector extensions may begin a segment |
|
||||
| `#foo-` | `foo-` | Visible connector extensions may end a segment |
|
||||
| `#---` | `---` | A segment may contain only visible connector extensions |
|
||||
| `#&&` | `&&` | Visible connector extensions may repeat |
|
||||
| `#AB` | `AB` | A non-emoji ZWJ is consumed but omitted from the value |
|
||||
| `#foo` | `foo` | An ignored leading ZWJ does not prevent a later value unit from starting the segment |
|
||||
| `#AB` | `AB` | A non-emoji ZWNJ is consumed but omitted from the value |
|
||||
| `#foo` | `foo` | An ignored leading ZWNJ does not prevent a later value unit from starting the segment |
|
||||
| `#` | none | Ignored default-ignorable code points alone do not form a segment |
|
||||
| `#A️B` | `AB` | A default-ignorable variation selector outside a matched fully-qualified emoji is omitted even after a starter |
|
||||
| `#́foo` | `foo` | A non-default-ignorable combining mark before the segment starter is consumed but omitted |
|
||||
| `#́` | none | Leading combining marks alone do not form a segment |
|
||||
| `#café` | `café` | A non-default-ignorable combining mark after the segment starter is preserved |
|
||||
| `#work/notes` | `work/notes` | Direct hierarchical identifier; memo membership also includes `work` |
|
||||
| `#foo/́bar` | `foo/bar` | Ignored leading combining-mark handling restarts for each segment |
|
||||
| `#book/` | `book` | A trailing slash is not consumed |
|
||||
| `#/book` | none | A hierarchy cannot begin with an empty segment |
|
||||
| `#book//fiction` | `book` | A repeated slash terminates before the first slash |
|
||||
| `#book/fiction/` | `book/fiction` | The valid hierarchical prefix is retained |
|
||||
| `#l·l` | `l·l` | Middle dot is `XID_Continue` |
|
||||
| `#foo‿bar` | `foo‿bar` | Connector punctuation is `XID_Continue` |
|
||||
| `#*️⃣` | `*️⃣` | Fully-qualified keycap sequence |
|
||||
| `#‼️` | `‼️` | Fully-qualified emoji sequence |
|
||||
| `#♥` | none | Bare text-presentation symbol is neither XID nor fully-qualified emoji |
|
||||
| `#♥️` | `♥️` | Fully-qualified emoji sequence |
|
||||
| `#🏻` | none | A standalone emoji component is excluded from `FullyQualifiedEmoji` |
|
||||
| `#foo,` | `foo` | Comma terminates the identifier |
|
||||
| `#price€` | `price` | Currency symbol terminates the identifier |
|
||||
| `#€budget` | none | The first body character is not a unit |
|
||||
| `#v²` | `v` | `Other_Number` is not generally `XID_Continue` |
|
||||
| `#first#second` | `first`, `second` | Ordinary `#` terminates and starts candidates |
|
||||
| `#️⃣` | none | The complete source is a fully-qualified emoji, not an introducer plus identifier |
|
||||
| `##️⃣` | `#️⃣` | The first `#` introduces the atomic keycap emoji value |
|
||||
| `#first#️⃣` | `first#️⃣` | The keycap emoji is an ordinary fully-qualified continuation unit |
|
||||
| `#tag` | none | Fullwidth number sign is not an introducer |
|
||||
| `﹟tag` | none | Small number sign is not an introducer |
|
||||
| `#tag` | none | A character reference is not a literal introducer |
|
||||
| `#tag` | none | Decoded text is not rescanned for candidates |
|
||||
| `\#tag` | none | Escaped introducer |
|
||||
| `#foo\+bar` | `foo` | A Markdown escape terminates the literal-source range |
|
||||
| `#R&D` | `R` | A character reference terminates the literal-source range |
|
||||
| `#R&D` | `R&D` | A literal ampersand is a value unit |
|
||||
| `` `#tag` `` | none | Inline-code context |
|
||||
| `**#urgent**` | `urgent` | Formatted normal text remains eligible |
|
||||
| `https://example.com/#tag` | none | GFM URL/autolink context |
|
||||
| `/path#tag` | `tag` | Plain text path is not guessed to be a URL |
|
||||
| `[hello#tag](https://example.com)` | none | The complete link is excluded |
|
||||
| `$#tag$` | none | A Memos math node is opaque |
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Tag meaning is specified independently of any single parser or issue.
|
||||
- Common multilingual tags, numeric tags, hierarchy characters, and emoji remain expressive.
|
||||
- Hierarchical ancestors have one consistent meaning across API membership, exact filters, navigation, and counts.
|
||||
- `hello#tag` works consistently while actual Markdown links and URLs are excluded structurally.
|
||||
- Common word-internal apostrophes support multilingual words and names while surrounding quotation punctuation remains outside tag values.
|
||||
- Unsupported Markdown punctuation, delimiters, currency symbols, and operators stop an identifier predictably; apostrophes are the explicitly
|
||||
constrained exception.
|
||||
- Exact equality preserves every emitted code-point distinction and avoids locale-dependent identity rules.
|
||||
- Ignoring default-ignorable code points outside emoji avoids invisible tag distinctions while preserving matched fully-qualified emoji sequences.
|
||||
- Ignoring leading non-default-ignorable `Mn` and `Mc` code points only before each segment's visible starter avoids invisible-leading segments without
|
||||
breaking decomposed writing inside words.
|
||||
- Keeping `-`, `+`, and `&` position-independent avoids a second connector-validation layer.
|
||||
- The memo-size limit provides the only length bound, avoiding tag-specific counting and overflow rules.
|
||||
- All consumers can implement the same language contract.
|
||||
- Unicode repertoire changes require an explicit specification update rather than depending on runtime tables.
|
||||
|
||||
### Negative
|
||||
|
||||
- Fully-qualified emoji matching requires sequence-aware data, not a simple code-point character class.
|
||||
- Pinning Unicode data requires maintenance when Unicode and Emoji data are updated.
|
||||
- Visually indistinguishable or canonically equivalent source spellings whose emitted values differ remain separate tags unless the user edits their memo
|
||||
sources to make those values identical.
|
||||
- Visually similar apostrophe spellings such as U+0027, U+2019, and U+02BC remain distinct under exact tag identity.
|
||||
- English possessive-looking source such as `#tag's` denotes the complete tag value `tag's`, not `tag` followed by prose.
|
||||
- Source spellings that differ only by ignored default-ignorable code points intentionally collapse to the same emitted tag value.
|
||||
- Source spellings that differ only by ignored leading combining marks intentionally collapse to the same emitted tag value.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### Keep `L/M/N/S` and patch URL detection
|
||||
|
||||
Rejected. `\p{S}` admits currency, mathematical operators, modifier symbols, and Markdown backticks merely as a side effect of supporting emoji. URL detection
|
||||
would still differ across consumers and would duplicate the Markdown parser.
|
||||
|
||||
### Require a whitespace or punctuation boundary before `#`
|
||||
|
||||
Rejected. It makes the intentionally supported `hello#tag` form invalid and uses a lexical approximation to solve a structural URL problem.
|
||||
|
||||
### Adopt UAX31-R8 unchanged
|
||||
|
||||
Rejected. UAX31-R8 recommends a flowing-text left boundary that does not match the product decision, and its raw emoji component repertoire is broader than
|
||||
the desired complete-sequence behavior. Memos instead defines an explicit UAX #31 profile.
|
||||
|
||||
### Use `Extended_Pictographic | Emoji_Component` as code-point characters
|
||||
|
||||
Rejected. It admits bare `*`, isolated modifiers and regional indicators, invisible emoji tag characters, and unassigned code points reserved for future
|
||||
emoji. Matching only fully-qualified entries expresses the intended user-visible unit.
|
||||
|
||||
### Keep the 100-code-point limit
|
||||
|
||||
Rejected. The value is arbitrary, counts code points rather than user-perceived characters, and currently has three different overflow behaviors. Memo-size
|
||||
limits already bound work.
|
||||
|
||||
### Reject an entire candidate when a later invalid character appears
|
||||
|
||||
Rejected. Hashtags in flowing text conventionally end at punctuation. Maximal-prefix behavior makes `#foo,` and `#foo` followed by inline code predictable.
|
||||
|
||||
### Allow empty hierarchy segments
|
||||
|
||||
Rejected. Empty segments have no useful navigation or membership meaning and would require special handling in hierarchy expansion. The grammar permits `/`
|
||||
only between two non-empty segments.
|
||||
|
||||
### Reject a whole hierarchy after an invalid slash
|
||||
|
||||
Rejected. Keeping the longest valid prefix makes a trailing or repeated slash behave like other terminating syntax and avoids erasing an otherwise valid
|
||||
tag. The slash and remaining source stay ordinary Markdown.
|
||||
|
||||
### Restrict visible connectors by position
|
||||
|
||||
Rejected. Requiring `-`, `+`, or `&` to be medial, non-repeating, or accompanied by a letter would add validation rules without resolving a structural
|
||||
ambiguity. They remain ordinary segment units; only `/` has structural meaning.
|
||||
|
||||
### Treat apostrophes as unrestricted value units
|
||||
|
||||
Rejected. Allowing apostrophes as starters, trailing units, or repeatable ordinary units would absorb surrounding quotation punctuation into values such
|
||||
as `tag'` and make quoted source such as `'#tag'` ambiguous. The contextual joiner rule supports words and names while leaving punctuation at tag
|
||||
boundaries unconsumed.
|
||||
|
||||
### Recognize compatibility number signs
|
||||
|
||||
Rejected. U+FE5F SMALL NUMBER SIGN and U+FF03 FULLWIDTH NUMBER SIGN are visually similar to `#` but are not Markdown syntax. Recognizing only ASCII U+0023
|
||||
keeps the introducer rule literal and unambiguous.
|
||||
|
||||
### Special-case the number-sign keycap
|
||||
|
||||
Rejected. `#️⃣` follows the same longest-sequence matching rule as every other admitted fully-qualified emoji. Excluding it or splitting its code points
|
||||
would add an exception to the emoji profile.
|
||||
|
||||
### Scan decoded Markdown text
|
||||
|
||||
Rejected. Decoding character references and escapes before tag scanning would allow non-literal introducers and require source reconstruction for exact
|
||||
spans. Tag lexing uses original source ranges; Markdown syntax nodes act as boundaries.
|
||||
|
||||
### Leave the Markdown dialect parser-defined
|
||||
|
||||
Rejected. Parser-dependent context would allow identical source to produce different tags. GFM 0.29-gfm is the structural baseline; additional Memos
|
||||
extensions are opaque unless explicitly declared transparent to tag recognition.
|
||||
|
||||
## References
|
||||
|
||||
- [Unicode 17.0 Standard Annex #31: Unicode Identifiers and Syntax](https://www.unicode.org/reports/tr31/tr31-43.html)
|
||||
- [UAX #31 Hashtag Identifiers](https://www.unicode.org/reports/tr31/tr31-43.html#Hashtag_Identifiers)
|
||||
- [UAX #31 Emoji Profile](https://www.unicode.org/reports/tr31/tr31-43.html#Emoji_Profile)
|
||||
- [Unicode Emoji 17.0 (UTS #51)](https://www.unicode.org/reports/tr51/tr51-29.html)
|
||||
- [Unicode Emoji 17.0 test data](https://www.unicode.org/Public/17.0.0/emoji/emoji-test.txt)
|
||||
- [GitHub Flavored Markdown specification](https://github.github.com/gfm/)
|
||||
- [Memos tag documentation](https://usememos.com/docs/usage/tags)
|
||||
@@ -1,260 +0,0 @@
|
||||
# ADR 0002: Username Format and References
|
||||
|
||||
Status: Accepted
|
||||
|
||||
Date: 2026-08-02
|
||||
|
||||
Domain glossary: [Memos domain glossary](../glossary.md)
|
||||
|
||||
## Context
|
||||
|
||||
A username is a user identifier used by account creation and updates, authentication, public user resource names, API lookup, SSO provisioning, and
|
||||
references to users. Those uses must share one format rather than defining separate username-like tokens.
|
||||
|
||||
Memos already restricts newly written usernames to ASCII letters, digits, and hyphens, with a 36-character limit and alphanumeric ends. Existing
|
||||
installations may also contain older usernames such as email addresses or values with underscores. Memos continues to read and resolve those legacy
|
||||
values, but they are not valid new usernames.
|
||||
|
||||
Markdown mentions currently drift from the writable username format: the backend accepts up to 63 Unicode letters, numbers, and hyphens; the frontend
|
||||
accepts up to 63 ASCII characters; both allow invalid username shapes; and extraction lowercases the result. Editor decoration also scans raw source in
|
||||
contexts where Markdown must be opaque.
|
||||
|
||||
This ADR defines:
|
||||
|
||||
- The format and case-preservation semantics for writable usernames.
|
||||
- How username references resolve.
|
||||
- Markdown mention as one source form of username reference.
|
||||
|
||||
Changing or migrating legacy username data is outside this ADR's scope.
|
||||
Username rename and reuse policy, and the durable binding of an already resolved mention across those lifecycle events, are also outside scope.
|
||||
Notification timing, deduplication, access policy, self-mention behavior, and other downstream effects are unchanged and outside scope.
|
||||
|
||||
## Decision drivers
|
||||
|
||||
- Give every username write path one small, stable validation rule.
|
||||
- Make a reference use the username format instead of inventing another identifier grammar.
|
||||
- Preserve the spelling and case selected by the user.
|
||||
- Keep username write validation, reference rendering, extraction, editor recognition, and notification resolution aligned.
|
||||
- Use parsed Markdown context rather than special-case regular expressions for code, links, email addresses, and other opaque syntax.
|
||||
- Keep recognition deterministic and linear in memo size.
|
||||
|
||||
## Terminology
|
||||
|
||||
**User**
|
||||
: A durable Memos account identified internally by an immutable user ID.
|
||||
|
||||
**Username**
|
||||
: A user-selected, case-sensitive public identifier used for account addressing. A username is distinct from a display name and from the user's internal
|
||||
ID.
|
||||
|
||||
**Writable username**
|
||||
: A username accepted when an account is created, renamed, or provisioned after this decision.
|
||||
|
||||
**Legacy username**
|
||||
: A stored username that does not satisfy the writable format but remains readable and addressable for compatibility.
|
||||
|
||||
**Username reference**
|
||||
: Source text that names a username so Memos can attempt to resolve it to a user ID. The source spelling is not itself a durable relationship.
|
||||
|
||||
**Mention candidate**
|
||||
: A Markdown source span with the form `@` followed by a complete writable username and satisfying the mention boundary and context rules.
|
||||
|
||||
**Resolved mention**
|
||||
: A mention candidate whose username resolves to a user under the consuming operation's existing account-status and visibility policy.
|
||||
|
||||
## Decision
|
||||
|
||||
### Writable username format
|
||||
|
||||
The normative grammar is:
|
||||
|
||||
```text
|
||||
Username := Alphanumeric
|
||||
| Alphanumeric UsernameCharacter{0,34} Alphanumeric
|
||||
UsernameCharacter := Alphanumeric | "-"
|
||||
Alphanumeric := ASCII letter | ASCII digit
|
||||
ASCII letter := "A".."Z" | "a".."z"
|
||||
ASCII digit := "0".."9"
|
||||
```
|
||||
|
||||
- A username is 1 through 36 ASCII characters.
|
||||
- ASCII letters, digits, and `-` are the only admitted characters.
|
||||
- The first and last characters are letters or digits.
|
||||
- Consecutive interior hyphens are valid; there is no additional rule limiting their number.
|
||||
- A digits-only value is valid.
|
||||
- Case is preserved.
|
||||
|
||||
Requiring alphanumeric ends also excludes values made only of hyphens and prevents a trailing hyphen from becoming an ambiguous-looking part of a
|
||||
Markdown mention.
|
||||
|
||||
The minimum is one because Username needs no product-level namespace-scarcity policy beyond being non-empty. The maximum is 36 so every UUID value has a
|
||||
canonical textual representation that fits while public URLs and reference tokens remain bounded.
|
||||
|
||||
The ASCII-only restriction is intentional: Username is a machine-facing public identifier used in URLs, authentication, and references. Internationalized
|
||||
human-readable naming belongs to Display Name rather than expanding Username normalization and comparison rules.
|
||||
|
||||
Examples:
|
||||
|
||||
| Value | Writable | Reason |
|
||||
| --- | --- | --- |
|
||||
| `alice` | yes | Letters only |
|
||||
| `Alice-2` | yes | Case is preserved; interior hyphen is valid |
|
||||
| `1alice` | yes | A digit may begin a username that also contains a letter |
|
||||
| `a--b` | yes | Consecutive interior hyphens are valid |
|
||||
| `a---b` | yes | Interior hyphens have no repetition limit |
|
||||
| `123` | yes | Numeric spelling has no special meaning |
|
||||
| `123-456` | yes | Digits and interior hyphens satisfy the grammar |
|
||||
| `00000000-0000-0000-0000-000000000000` | yes | A canonical UUID occupies 36 characters |
|
||||
| `-alice` | no | A hyphen cannot begin a username |
|
||||
| `alice-` | no | A hyphen cannot end a username |
|
||||
| `alice_smith` | no | `_` is outside the format |
|
||||
| `alice@example.com` | no | Email syntax is outside the format |
|
||||
| `álîçé` | no | The writable format is ASCII |
|
||||
| `张三` | no | Internationalized naming belongs to Display Name |
|
||||
|
||||
All account creation, username update, and automatic provisioning paths use this rule. A generic resource-name rule is not the username contract and
|
||||
must not be reused as a substitute merely because its current regular expression is similar.
|
||||
|
||||
### Username allocation
|
||||
|
||||
The writable format has no reserved spellings. Values such as `admin`, `root`, `system`, `api`, `memos`, and `support` are ordinary usernames and are
|
||||
available subject to the same exact-case uniqueness rule as every other value. A username does not grant authority or establish trust; those properties
|
||||
come from the resolved user ID, role, and explicit product presentation. Manual registration, rename, and automatic provisioning apply the same policy.
|
||||
|
||||
If Memos later needs a system-owned username, the corresponding account claims it through ordinary uniqueness rather than expanding a lexical reserved
|
||||
list.
|
||||
|
||||
SSO provisioning adopts the external identifier exactly when it is a valid, available writable username. If it is invalid or already belongs to another
|
||||
user, provisioning assigns a generated canonical UUID instead. A matching username never links or takes over an account; only the persisted identity
|
||||
binding formed by the identity-provider key and external subject identifies a returning SSO user.
|
||||
|
||||
### Username identity and resolution
|
||||
|
||||
Username spelling is case-preserving and username equality is exact ASCII byte equality. Memos does not lowercase, case-fold, or otherwise normalize a
|
||||
username before validation, uniqueness checks, authentication, resource lookup, or reference resolution. In particular, surrounding whitespace is not
|
||||
trimmed into a different username; a value such as ` alice ` is invalid. `Alice` and `alice` are distinct usernames and may identify different users.
|
||||
|
||||
All storage backends and application lookup paths must preserve this equality rule. A database collation that treats `Alice` and `alice` as equal, or a
|
||||
lookup that silently resolves one spelling to the other, does not conform to this decision.
|
||||
|
||||
The `username` column therefore uses an explicit case-sensitive binary collation on every supported storage backend: `utf8mb4_bin` on MySQL, `C` on
|
||||
PostgreSQL, and `BINARY` on SQLite. For the writable ASCII format, this makes exact-byte uniqueness and lookup a schema property rather than an assumption
|
||||
about each database's default collation.
|
||||
|
||||
A username-bearing field or resource-name segment always resolves as a username, including when its spelling contains only digits. Character shape must
|
||||
not select the internal user-ID namespace; an operation that addresses a user by internal ID must expose that choice separately.
|
||||
|
||||
The stable identity of a user is the internal user ID. A username reference is resolved as late as the consuming operation permits:
|
||||
|
||||
1. Preserve the username exactly as written.
|
||||
2. Look up that exact username in the operation's visibility and account-status scope.
|
||||
3. If it resolves, use the resulting user ID for durable effects.
|
||||
4. If it does not resolve, retain ordinary source text and produce no user-targeted effect.
|
||||
|
||||
Product intent permits username rename and later reuse while requiring an already resolved mention not to change users. A source spelling alone cannot
|
||||
satisfy all three properties: preserving the original target requires a durable binding to the user ID outside the `@username` text. This ADR does not
|
||||
define that binding, historical re-resolution behavior, or the username lifecycle needed to support it.
|
||||
|
||||
Legacy usernames remain valid exact lookup keys for existing API resource names and authentication flows. They are not accepted by write validation and
|
||||
are not added to new reference syntaxes. Changing legacy username values remains outside this decision, but every lookup preserves their stored spelling.
|
||||
|
||||
### Markdown mention syntax
|
||||
|
||||
A Markdown mention is the first defined username-reference syntax:
|
||||
|
||||
```text
|
||||
MentionCandidate := "@" Username
|
||||
```
|
||||
|
||||
The `Username` production is the complete writable username format above. Mention parsing has no independent character set or length limit.
|
||||
|
||||
Candidate recognition follows these rules:
|
||||
|
||||
1. The `@` is U+0040 COMMERCIAL AT in an eligible literal-source run.
|
||||
2. At the start of the document, the left boundary is satisfied. Otherwise the immediately preceding source character must not be a
|
||||
`UsernameCharacter`. The username format therefore defines the boundary: a preceding letter, digit, or hyphen blocks recognition.
|
||||
3. The lexer consumes the complete consecutive run of ASCII letters, digits, and hyphens after `@`, then validates that whole run as a writable username.
|
||||
It does not shorten an invalid run into a valid prefix.
|
||||
4. GFM email-address recognition takes precedence. No substring of a recognized email address is a mention.
|
||||
|
||||
Characters outside `UsernameCharacter`, including `_`, `@`, and non-ASCII characters, are ordinary boundaries and receive no special handling.
|
||||
|
||||
The rules produce:
|
||||
|
||||
| Source | Mention candidate |
|
||||
| --- | --- |
|
||||
| `@alice` | `alice` |
|
||||
| `@Alice-2` | `Alice-2` |
|
||||
| `hi, @alice.` | `alice` |
|
||||
| `中文@alice` | `alice` |
|
||||
| `hello@alice` | none |
|
||||
| `foo-@alice` | none |
|
||||
| `foo_@alice` | `alice` |
|
||||
| `@123` | `123` |
|
||||
| `@-alice` | none |
|
||||
| `@alice-` | none |
|
||||
| `@alice_smith` | `alice` |
|
||||
| `@alice@example` | `alice` |
|
||||
| `@alice@bob` | `alice` |
|
||||
| `@alice@example.com` | none |
|
||||
| `@` followed by 37 valid username characters | none |
|
||||
|
||||
### Markdown context
|
||||
|
||||
Mention recognition operates on original Markdown source after GFM and Memos block and inline structure is resolved. It uses the same literal-source-run
|
||||
and opaque-node model as other Memos inline extensions:
|
||||
|
||||
- Paragraphs, headings, block quotes, list items, table text, emphasis, strong emphasis, and strikethrough expose ordinary text.
|
||||
- Code spans, code blocks, resolved links and images, autolinks, recognized GFM email addresses, raw HTML, and math are opaque.
|
||||
- Escapes, character references, line endings, and syntax delimiters end a literal-source run. An escaped or character-reference-produced `@` is not an
|
||||
introducer.
|
||||
- Unknown future Markdown extension nodes are opaque unless their definition explicitly exposes ordinary text.
|
||||
|
||||
Parsing, read rendering, metadata extraction, editor decoration, and any future mention completion must use these same lexical and context rules.
|
||||
|
||||
This decision changes only which exact username spellings are extracted as mention candidates. Existing resolution, rendering, notification, and access
|
||||
policies consume those candidates without otherwise changing behavior. Autocomplete, suggestion ranking, and a dedicated structured mention payload are
|
||||
also outside this decision.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Username validation becomes a domain primitive shared by every write path.
|
||||
- Username uniqueness, authentication, resource lookup, and reference resolution use the same case-sensitive equality rule on every storage backend.
|
||||
- Mention syntax automatically follows future username-format decisions only when this ADR is superseded and both uses are updated together.
|
||||
- Existing valid mixed-case usernames can be mentioned without lowercasing.
|
||||
- Values accepted only by the old 63-character or Unicode mention lexers stop being mention candidates because they were never writable usernames.
|
||||
- Legacy email-like or underscore-containing usernames remain usable through compatibility lookup but cannot be authored as new Markdown mentions.
|
||||
- Markdown-aware recognition removes false mentions from code, links, email addresses, HTML, math, escapes, and character references.
|
||||
- Username rename, reuse, and historical mention stability remain an explicit follow-up because source text alone cannot represent the intended stable
|
||||
user binding.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### Define mention syntax first
|
||||
|
||||
Rejected because it creates a second username-like grammar and allows account validation and references to drift again.
|
||||
|
||||
### Allow a broader mention token than writable usernames
|
||||
|
||||
Rejected because such candidates cannot reliably identify newly writable accounts and complicate boundaries, validation, and UI messaging.
|
||||
|
||||
### Store stable user IDs with a mention
|
||||
|
||||
Deferred. Stable IDs make renames and username reuse robust but require either a new source representation or persisted occurrence bindings, plus editing
|
||||
UX, import/export behavior, and compatibility policy. Exact username references are sufficient for candidate recognition in the current scope, but do not
|
||||
solve historical binding.
|
||||
|
||||
### Unicode usernames
|
||||
|
||||
Deferred. A safe Unicode identifier design needs a pinned Unicode version, normalization, script and confusable policy, and consistent database collation.
|
||||
ASCII keeps this decision small and matches the existing writable format.
|
||||
|
||||
## References
|
||||
|
||||
- [GitHub Flavored Markdown 0.29-gfm](https://github.github.com/gfm/)
|
||||
- [GitHub: Mentioning people and teams](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams)
|
||||
- [Slack message formatting: mentioning users](https://docs.slack.dev/messaging/formatting-message-text/#mentioning-users)
|
||||
- [Matrix client-server API: user and room mentions](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions)
|
||||
- [Activity Streams 2.0 Vocabulary: Mention](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mention)
|
||||
- [Unicode Standard Annex #31: Unicode Identifiers and Syntax](https://www.unicode.org/reports/tr31/)
|
||||
- [Unicode Technical Standard #39: Unicode Security Mechanisms](https://www.unicode.org/reports/tr39/)
|
||||
@@ -1,65 +0,0 @@
|
||||
# ADR 0003: Space UID Allocation and Format
|
||||
|
||||
Status: Accepted
|
||||
|
||||
Date: 2026-08-27
|
||||
|
||||
Domain glossary: [Memos domain glossary](../glossary.md)
|
||||
|
||||
## Context
|
||||
|
||||
A Space title is mutable and non-unique. Using it alone in switchers, settings, badges, and destructive confirmations makes distinct Spaces with the same
|
||||
title difficult to tell apart. The immutable public identity is instead the instance-wide UID embedded in the resource name `spaces/{space UID}`.
|
||||
|
||||
Previously, first-party clients omitted the UID and the server generated a short UUID. That prevented clients from choosing a stable identifier before
|
||||
creation and made the default differ from other newer UUID-backed identities. Existing clients may still omit the request field, and existing short UIDs
|
||||
must remain valid without a data migration.
|
||||
|
||||
## Decision drivers
|
||||
|
||||
- Give clients a stable identifier before they issue a create request.
|
||||
- Keep old clients and existing Space resource names compatible.
|
||||
- Reuse the established public-resource UID grammar instead of introducing a Space-only slug format.
|
||||
- Keep the complete immutable UID discoverable in Settings without adding identity metadata to every compact Space label.
|
||||
|
||||
## Decision
|
||||
|
||||
The first-party client generates a canonical lowercase UUID v4 for every new Space and sends it in `CreateSpaceRequest.space_id`. It may expose that value
|
||||
before creation and let the user replace it with a custom UID. A retry of the same create interaction reuses the same generated value.
|
||||
|
||||
The API field remains optional for compatibility. When it is empty, the server generates a canonical lowercase UUID v4. A supplied value uses the shared
|
||||
public-resource grammar:
|
||||
|
||||
```text
|
||||
SpaceUID := Alphanumeric
|
||||
| Alphanumeric UIDCharacter{0,34} Alphanumeric
|
||||
UIDCharacter := Alphanumeric | "-"
|
||||
Alphanumeric := ASCII letter | ASCII digit
|
||||
```
|
||||
|
||||
The UID is therefore 1 through 36 characters. Consecutive interior hyphens, uppercase letters, and digits-only values are valid. The one-character
|
||||
minimum matches the other public-resource UIDs; increasing it would not materially prevent collisions or name claiming. The spelling is preserved.
|
||||
|
||||
The UI uses the title as the primary label. Settings surfaces and their management subflows always show the complete UID with an explicit `Space UID`
|
||||
label. Other surfaces show the UID only when two known Spaces have exactly matching, case-sensitive titles, or when the title is unavailable and the UID
|
||||
is the only usable identity. When compact identity metadata is needed, canonical UUIDs use an eight-character prefix; short custom UIDs are shown in
|
||||
full, while long custom UIDs show both ends so late differences remain visible. Accessible labels and tooltips retain the complete UID in those cases.
|
||||
|
||||
Existing Space UIDs remain readable and are not rewritten.
|
||||
|
||||
## Consequences
|
||||
|
||||
- New first-party creates use UUID v4 by default, while custom identifiers remain concise and human-readable when desired.
|
||||
- Old clients continue to work through the server fallback.
|
||||
- Duplicate titles remain allowed and require no rename or uniqueness migration.
|
||||
- Compact Space labels stay title-only until a matching title or missing-title fallback makes the UID necessary.
|
||||
- UID collisions are rejected by the existing instance-wide uniqueness constraint.
|
||||
- Case-preserving UID input is accepted. Aligning exact-case uniqueness and lookup across database collations is a separate schema decision.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Require unique titles.** Rejected because titles are display labels and users may legitimately reuse them.
|
||||
- **Always show UIDs across the UI.** Rejected because it makes a technical identifier compete with the human-readable title even when no ambiguity exists.
|
||||
- **Only show UIDs in Settings.** Rejected because matching titles would remain ambiguous in switchers, badges, and scoped search.
|
||||
- **Keep server-only allocation.** Rejected because the first-party client cannot retain one identity across retries or offer customization before creation.
|
||||
- **Require a longer custom UID.** Rejected because length does not meaningfully solve collision or namespace-claiming concerns.
|
||||
@@ -1,62 +0,0 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
Architecture Decision Records (ADRs) document significant technical and product decisions whose rationale should remain available after the related
|
||||
implementation work is complete.
|
||||
|
||||
## Index
|
||||
|
||||
| ADR | Title | Status | Date |
|
||||
| --- | --- | --- | --- |
|
||||
| [0001](0001-tag-syntax-and-recognition.md) | Tag Syntax and Recognition | Accepted | 2026-08-01 |
|
||||
| [0002](0002-username-format-and-references.md) | Username Format and References | Accepted | 2026-08-02 |
|
||||
| [0003](0003-space-uid-allocation-and-format.md) | Space UID Allocation and Format | Accepted | 2026-08-27 |
|
||||
|
||||
## Conventions
|
||||
|
||||
- Name files `NNNN-short-kebab-case-title.md`, using a four-digit number that is never reused.
|
||||
- Assign the next number when an ADR is opened, even if an earlier ADR is later rejected or superseded.
|
||||
- Use the title `# ADR NNNN: Title` and record dates as `YYYY-MM-DD`.
|
||||
- Keep accepted ADRs as historical records. Replace a decision with a new ADR rather than rewriting the original rationale.
|
||||
- When one ADR replaces another, add `Supersedes: ADR NNNN` to the new ADR and `Superseded by: ADR NNNN` to the old ADR.
|
||||
|
||||
## Statuses
|
||||
|
||||
- **Proposed**: Under discussion; unresolved questions may remain.
|
||||
- **Accepted**: Approved as the decision to implement and maintain.
|
||||
- **Rejected**: Considered but not selected.
|
||||
- **Superseded**: Replaced by a later ADR.
|
||||
|
||||
## Suggested structure
|
||||
|
||||
Each ADR should contain enough information to understand the decision without reconstructing the original discussion:
|
||||
|
||||
```markdown
|
||||
# ADR NNNN: Title
|
||||
|
||||
Status: Proposed
|
||||
|
||||
Date: YYYY-MM-DD
|
||||
|
||||
## Context
|
||||
|
||||
## Decision drivers
|
||||
|
||||
## Decision
|
||||
|
||||
## Consequences
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
## Open questions before acceptance
|
||||
|
||||
## References
|
||||
```
|
||||
|
||||
Optional sections may be omitted when they do not add useful context.
|
||||
|
||||
## Process
|
||||
|
||||
1. Create a `Proposed` ADR with the next available number and add it to the index.
|
||||
2. Discuss the proposal with maintainers, updating the ADR as the decision develops.
|
||||
3. Change the status to `Accepted` or `Rejected` when the outcome is clear.
|
||||
4. If an accepted decision changes materially, create a new ADR and cross-link the superseding records.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Design Documents
|
||||
|
||||
Design documents may evolve while a feature is being designed and implemented. Once implementation is complete, set `Status: Implemented` and freeze the document.
|
||||
|
||||
Do not update implemented designs to track later code changes. They preserve the original design and rationale; source code and tests describe current
|
||||
behavior. New and unimplemented designs may still be added or revised.
|
||||
|
||||
The following designs have been implemented and are frozen:
|
||||
|
||||
- [API abuse controls](api-abuse-controls.md)
|
||||
- [Configuration provisioning](configuration-provisioning.md)
|
||||
- [Memos Export Format](memos-export-format.md), including the schemas under `memo-export/1.0/`
|
||||
- [Multi-Spaces](multi-spaces.md)
|
||||
- [Unique email](unique-email.md)
|
||||
|
||||
The configuration provisioning design was moved here from `docs/configuration-provisioning.md` and frozen after implementation.
|
||||
@@ -1,6 +1,6 @@
|
||||
# API Abuse Controls Design
|
||||
|
||||
Status: Accepted
|
||||
Status: Implemented
|
||||
|
||||
Date: 2026-09-12
|
||||
|
||||
|
||||
@@ -68,7 +68,7 @@
|
||||
"username": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "Username as defined by ADR 0002."
|
||||
"description": "Username identifying the user in the export."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -89,7 +89,7 @@
|
||||
"username": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "Username as defined by ADR 0002."
|
||||
"description": "Username identifying the user in the export."
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Memos Export Format
|
||||
|
||||
Status: Proposed
|
||||
Status: Implemented
|
||||
|
||||
Date: 2026-09-16
|
||||
|
||||
Existing domain language: [Memos context](../../CONTEXT.md)
|
||||
|
||||
Related: [Multi-Spaces Design](multi-spaces.md), [ADR 0002: Username Format and References](../adr/0002-username-format-and-references.md), [ADR 0003: Space UID Allocation and Format](../adr/0003-space-uid-allocation-and-format.md)
|
||||
Related: [Multi-Spaces Design](multi-spaces.md)
|
||||
|
||||
Normative schemas: [`memo-export/1.0/manifest.schema.json`](memo-export/1.0/manifest.schema.json), [`memo-export/1.0/memo.schema.json`](memo-export/1.0/memo.schema.json)
|
||||
|
||||
@@ -81,8 +81,8 @@ Container rules:
|
||||
|
||||
### Identifiers
|
||||
|
||||
- A memo is identified by its Memo UID, the `{memo}` segment of `memos/{memo}`, matching `^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$`. An attachment is identified by the `{attachment}` segment of `attachments/{attachment}`, which uses the same grammar. A Space is identified by its Space UID under ADR 0003 and carries its Space title for fallback matching. Database identifiers never appear.
|
||||
- A user is identified by username under ADR 0002.
|
||||
- A memo is identified by its Memo UID, the `{memo}` segment of `memos/{memo}`, matching `^[a-zA-Z0-9]([a-zA-Z0-9-]{0,34}[a-zA-Z0-9])?$`. An attachment is identified by the `{attachment}` segment of `attachments/{attachment}`, which uses the same grammar. A Space is identified by its Space UID and carries its Space title for fallback matching. Database identifiers never appear.
|
||||
- A user is identified by username.
|
||||
- References inside the archive are bare UIDs, never resource names, so the resource name patterns of the API can change without a format change.
|
||||
|
||||
### Records
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Multi-Spaces Design
|
||||
|
||||
Status: Accepted
|
||||
Status: Implemented
|
||||
|
||||
Date: 2026-08-23
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Unique Email Design
|
||||
|
||||
Status: Accepted
|
||||
Status: Implemented
|
||||
|
||||
Date: 2026-09-12
|
||||
|
||||
Existing domain language: [Memos context](../../CONTEXT.md)
|
||||
|
||||
Related: [Multi-Spaces Design](multi-spaces.md), [ADR 0002: Username Format and References](../adr/0002-username-format-and-references.md)
|
||||
Related: [Multi-Spaces Design](multi-spaces.md)
|
||||
|
||||
## Summary
|
||||
|
||||
|
||||
@@ -1,145 +0,0 @@
|
||||
# Memos Domain Glossary
|
||||
|
||||
This glossary defines product and domain language shared across Memos design documents. Protocol, Unicode, and parser-specific terms remain in the ADRs
|
||||
that use them.
|
||||
|
||||
## Users and usernames
|
||||
|
||||
### User
|
||||
|
||||
A durable Memos account. Its stable identity is an internal user ID, not its mutable username or display name.
|
||||
|
||||
### Username
|
||||
|
||||
A user-selected, case-sensitive public account identifier used for authentication, user resource names, lookup, and references. Username spelling is
|
||||
case-preserving, is not implicitly trimmed or normalized, and equality is exact ASCII byte equality, so `Alice` and `alice` are distinct usernames. A
|
||||
username is distinct from both a display name and the user's internal ID. Its spelling does not grant a role or establish that the user is trusted.
|
||||
|
||||
### Writable username
|
||||
|
||||
A username accepted for account creation, rename, or automatic provisioning. It is 1 through 36 ASCII letters, digits, or hyphens; begins and ends with an
|
||||
ASCII letter or digit; and may contain repeated interior hyphens without an additional restriction. Numeric spelling has no special meaning, so a value
|
||||
containing only digits is also a writable username. Internationalized human-readable naming belongs to the user's display name.
|
||||
|
||||
### Legacy username
|
||||
|
||||
A stored username that does not satisfy the writable format but remains readable and addressable for compatibility. Legacy usernames are not accepted by
|
||||
new write validation or added to new reference syntaxes.
|
||||
|
||||
### Username reference
|
||||
|
||||
Source text that names an exact, case-sensitive username so Memos can attempt to resolve it to a user ID. The source spelling alone is not a durable user
|
||||
binding. Stability across username rename and reuse requires additional persisted identity that the current username-reference specification does not
|
||||
define.
|
||||
|
||||
### Mention candidate
|
||||
|
||||
An eligible memo Markdown source span formed by an ASCII `@` followed by one complete writable username. Recognition also applies the boundary and opaque
|
||||
Markdown-context rules in the active username-reference specification. The same ASCII letters, digits, and hyphen admitted inside a username define the
|
||||
mention boundaries: they block a mention immediately to their right and are consumed as part of the complete candidate to their left. Other characters
|
||||
receive no special boundary handling.
|
||||
|
||||
### Resolved mention
|
||||
|
||||
A mention candidate whose exact username resolves to a user under the consuming operation's existing account-status and visibility policy. User-targeted
|
||||
effects apply to the resolved user ID, not to unresolved source text.
|
||||
|
||||
## Spaces
|
||||
|
||||
### Space
|
||||
|
||||
An instance-scoped collaboration boundary for accepted members and memo placement. A Space is not a tenant, folder, or application-wide authorization
|
||||
role.
|
||||
|
||||
### Space ID
|
||||
|
||||
The stable internal identity of a Space. It is distinct from the public Space UID and the mutable Space title.
|
||||
|
||||
### Space UID
|
||||
|
||||
The immutable, instance-wide public identifier assigned when a Space is created. It may be user-defined or generated automatically.
|
||||
|
||||
### Space resource name
|
||||
|
||||
The API identity of a Space in the form `spaces/{space UID}`.
|
||||
|
||||
### Space title
|
||||
|
||||
The mutable, non-unique display label of a Space.
|
||||
|
||||
## Tags
|
||||
|
||||
### Tag
|
||||
|
||||
A classification value in a memo tag set, derived from one or more tag occurrences either as a direct tag value or as an implied ancestor. A tag is not a
|
||||
durable entity and cannot be independently created or renamed. Changing a tag's spelling requires editing the relevant memo source occurrences.
|
||||
|
||||
### Tag introducer
|
||||
|
||||
An ASCII `#` character (U+0023) that is not part of a matched fully-qualified emoji sequence and starts a tag candidate. Visually similar fullwidth and small
|
||||
number-sign characters are not introducers.
|
||||
|
||||
### Tag occurrence
|
||||
|
||||
An eligible source span in memo Markdown formed by a tag introducer and its consumed source spelling. The spelling emits a tag identifier, which is the
|
||||
direct tag value. Recognition rules, including excluded Markdown contexts, are defined by the active tag-syntax profile.
|
||||
|
||||
### Eligible tag text
|
||||
|
||||
A contiguous original-source range with no intervening Markdown syntax boundary, classified as textual content by GFM 0.29-gfm or explicitly exposed as
|
||||
ordinary text by a Memos Markdown extension. Extension nodes are opaque by default, so their source does not produce tags unless the extension definition
|
||||
opts in.
|
||||
|
||||
### Source spelling
|
||||
|
||||
The exact source substring consumed after the `#` introducer. It includes default-ignorable code points outside matched fully-qualified emoji sequences and
|
||||
ignored leading combining marks before each segment's starter, both of which the lexer ignores. Inline rendering and source-preserving operations use this
|
||||
spelling.
|
||||
|
||||
### Direct tag value
|
||||
|
||||
The identifier emitted from one tag occurrence before hierarchy expansion. `book/fiction` is the direct value produced by `#book/fiction`.
|
||||
Default-ignorable code points outside matched fully-qualified emoji sequences and ignored leading combining marks before each segment's starter are
|
||||
consumed from the source spelling but omitted from this value.
|
||||
|
||||
### Implied ancestor tag
|
||||
|
||||
A slash-delimited prefix derived from a direct tag value. A direct value of `book/fiction/history` implies the ancestor tags `book` and `book/fiction`.
|
||||
|
||||
### Tag segment
|
||||
|
||||
A non-empty component of a hierarchical tag identifier. `/` separates segments and is consumed only when another non-empty segment follows. A leading slash
|
||||
produces no tag; a trailing or repeated slash terminates the identifier before that slash. `-`, `+`, and `&` are ordinary segment units: they may appear at
|
||||
any position, repeat, or form a complete segment. Default-ignorable code points and ignored leading combining marks do not make a segment non-empty.
|
||||
|
||||
### Tag identifier
|
||||
|
||||
The non-empty Unicode code-point sequence emitted from a tag source spelling. The identifier excludes the introducer and all ignored source code points.
|
||||
|
||||
### Display value
|
||||
|
||||
The direct or implied value presented as a derived tag label. Memos does not normalize or case-fold emitted code points for identity, but ignored
|
||||
default-ignorable code points and ignored leading combining marks are not part of the display value.
|
||||
|
||||
### Comparison key
|
||||
|
||||
The value used for deduplication, counting, filtering, navigation, and exact metadata matching. It is identical to the emitted display value. Two tags
|
||||
compare as equal only when those emitted Unicode code-point sequences are identical; case and canonical or compatibility-equivalent spellings remain
|
||||
distinct. Source spellings that differ only by ignored default-ignorable code points or ignored leading combining marks compare equal. Inputs to exact
|
||||
value filters and metadata lookups are already tag values and are compared as supplied; they are not re-lexed as source spellings.
|
||||
|
||||
### Memo tag set
|
||||
|
||||
The union of direct tag values and their implied ancestor tags for one memo, exposed as `Memo.tags`. It is rebuildable from the memo's Markdown and is not an
|
||||
authoritative source of tags. Each exactly equal emitted value appears once, even when produced both directly and as an ancestor. Different source
|
||||
spellings remain separate only when they emit different code-point sequences.
|
||||
|
||||
### Tag metadata rule
|
||||
|
||||
User configuration that selects tag values and supplies presentation or behavior metadata, such as color or content blurring. A metadata rule may match
|
||||
multiple values and does not create, own, or rename a tag.
|
||||
|
||||
### Tag count
|
||||
|
||||
The number of memo tag sets containing an exactly equal direct or implied tag value, not the number of textual occurrences. A memo containing only
|
||||
`#book/fiction` contributes one to both the `book` and `book/fiction` counts.
|
||||
Reference in New Issue
Block a user