honour aliases as permanent redirects

An alias is a promise that an old URL keeps working, so it answers 301 to the
canonical one rather than serving the same content twice (ADR-0008). Frontmatter
takes a scalar or a list and tolerates surrounding slashes, because authors write
both.

Ambiguity is dropped, not resolved: an alias naming a real bundle, or claimed by
two bundles, is logged and ignored so the real bundle keeps its URL. Aliases
compose with language prefixes for free, since the resolver splits the language
before the key is looked up.

The redirect still fires only for an alias that exists, so a nonexistent path
cannot be probed by 301 — the property prompt 3 established.

Evidence: /pages/bio/ and /about/ both 301 to /pages/about/, /bn/pages/bio/ 301s
to /bn/pages/about/, and /pages/nothing/ is 404.

internal/content/content.go

@@ -38,6 +38,9 @@ type Bundle struct {
 	// Title is empty when frontmatter omits it. Whether that is legal depends on the type, which
 	// nothing decides yet, so the parser accepts it.
 	Title string
+	// Aliases are paths that must keep resolving to this bundle, each redirecting to its canonical URL
+	// (ADR-0008). Additive only: an alias is a promise never withdrawn.
+	Aliases []string
 	// Body is everything after the frontmatter, unrendered.
 	Body []byte
 	// Extra holds every frontmatter key other than title, exactly as YAML parsed it.
@@ -113,9 +116,33 @@ func Parse(name string, data []byte) (Bundle, error) {
 		b.Title = t
 	}
 	delete(b.Extra, "title")
+	b.Aliases = stringList(b.Extra["aliases"])
+	delete(b.Extra, "aliases")
 	return b, nil
 }
 
+// stringList reads a YAML scalar or sequence of strings as keys: normalised, without surrounding
+// slashes. Anything that is not a string is ignored rather than failing the bundle.
+func stringList(v any) []string {
+	var out []string
+	add := func(x any) {
+		if str, ok := x.(string); ok {
+			if k := Normalise(strings.Trim(str, "/")); k != "" {
+				out = append(out, k)
+			}
+		}
+	}
+	switch t := v.(type) {
+	case string:
+		add(t)
+	case []any:
+		for _, x := range t {
+			add(x)
+		}
+	}
+	return out
+}
+
 // Normalise puts s into NFC.
 //
 // Every identifier goes through this: Bengali conjuncts have several byte encodings for text that looks
@@ -220,18 +247,53 @@ func dropCollisions(all []Bundle) []Bundle {
 // Site is a set of bundles indexed for lookup by permalink key.
 type Site struct {
 	byKeyLang map[string]Bundle
+	aliases   map[string]string
 }
 
 // NewSite indexes bundles for lookup. Later variants of a key and language cannot occur, because Scan
 // drops ambiguity before this sees it.
 func NewSite(bundles []Bundle) *Site {
-	s := &Site{byKeyLang: make(map[string]Bundle, len(bundles))}
+	s := &Site{
+		byKeyLang: make(map[string]Bundle, len(bundles)),
+		aliases:   map[string]string{},
+	}
 	for _, b := range bundles {
 		s.byKeyLang[b.Key+"\x00"+b.Lang] = b
 	}
+	s.indexAliases(bundles)
 	return s
 }
 
+// indexAliases maps each alias to the key it redirects to.
+//
+// An alias that names a real bundle, or that two bundles both claim, is ambiguous: it is logged and
+// dropped rather than picking a winner, and the real bundle keeps its URL (ADR-0029).
+func (s *Site) indexAliases(bundles []Bundle) {
+	claimed := map[string][]string{}
+	for _, b := range bundles {
+		for _, a := range b.Aliases {
+			claimed[a] = append(claimed[a], b.Key)
+		}
+	}
+	for alias, keys := range claimed {
+		if _, isReal := s.byKeyLang[alias+"\x00"+DefaultLang]; isReal {
+			slog.Error("ignoring alias that names a real bundle", "alias", alias, "claimed_by", keys)
+			continue
+		}
+		if len(keys) > 1 {
+			slog.Error("ignoring alias claimed by more than one bundle", "alias", alias, "claimed_by", keys)
+			continue
+		}
+		s.aliases[alias] = keys[0]
+	}
+}
+
+// Alias returns the key an alias redirects to.
+func (s *Site) Alias(alias string) (string, bool) {
+	key, ok := s.aliases[alias]
+	return key, ok
+}
+
 // Lookup returns the best variant of a key for a requested language, and the language actually served.
 //
 // The fallback chain is requested → default → any (ADR-0009); "any" is resolved in sorted order so the

internal/content/content_test.go

@@ -215,3 +215,57 @@ func TestURLPrefixesOnlyNonDefaultLanguages(t *testing.T) {
 		}
 	}
 }
+
+func TestAliasesAreParsedAndIndexed(t *testing.T) {
+	fsys := fstest.MapFS{
+		"content/posts/new-name.md": {Data: []byte("---\ntitle: New\naliases: [/posts/old-name/, posts/older]\n---\n")},
+		"content/pages/single.md":   {Data: []byte("---\ntitle: Single\naliases: pages/one\n---\n")},
+	}
+	bundles, err := Scan(fsys)
+	if err != nil {
+		t.Fatal(err)
+	}
+	site := NewSite(bundles)
+	for alias, want := range map[string]string{
+		"posts/old-name": "posts/new-name",
+		"posts/older":    "posts/new-name",
+		"pages/one":      "pages/single",
+	} {
+		got, ok := site.Alias(alias)
+		if !ok || got != want {
+			t.Errorf("Alias(%q) = %q %v, want %q", alias, got, ok, want)
+		}
+	}
+	for _, b := range bundles {
+		if _, leaked := b.Extra["aliases"]; leaked {
+			t.Error("aliases should be lifted out of Extra, not duplicated")
+		}
+	}
+}
+
+func TestAmbiguousAliasesAreDropped(t *testing.T) {
+	fsys := fstest.MapFS{
+		"content/pages/real.md": {Data: []byte("---\ntitle: Real\n---\n")},
+		"content/pages/a.md":    {Data: []byte("---\ntitle: A\naliases: [pages/real, pages/shared]\n---\n")},
+		"content/pages/b.md":    {Data: []byte("---\ntitle: B\naliases: [pages/shared]\n---\n")},
+	}
+	site := NewSite(mustScan(t, fsys))
+	if _, ok := site.Alias("pages/real"); ok {
+		t.Error("an alias naming a real bundle must be dropped, not shadow it")
+	}
+	if _, ok := site.Alias("pages/shared"); ok {
+		t.Error("an alias claimed by two bundles must be dropped, not picked arbitrarily")
+	}
+	if _, _, ok := site.Lookup("pages/real", "en"); !ok {
+		t.Error("the real bundle must keep its URL")
+	}
+}
+
+func mustScan(t *testing.T, fsys fstest.MapFS) []Bundle {
+	t.Helper()
+	b, err := Scan(fsys)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}