feat(submissions): t-paliad-215 Slice 1 — in-house .docx render engine

Pure-Go {{path.dot.notation}} placeholder engine + unit tests
(t-paliad-215, design docs/design-submission-generator-2026-05-19.md
§6). Chosen over github.com/lukasjarosch/go-docx because that library
treats sibling placeholders inside one <w:t> run as nested and
refuses to replace them — patent submissions routinely carry multiple
placeholders per paragraph (party blocks especially), so the library
is a non-starter.

Two-pass strategy preserves run-level formatting on the common path:

 1. Pass 1: regex replace inside each <w:t>…</w:t> independently —
    no format loss for the 99% case where placeholders are intact.
 2. Pass 2: paragraph-level merge for paragraphs that still contain
    orphan "{{" or "}}" markers (Word fragmented the placeholder
    across runs).

Missing placeholders render [KEIN WERT: <key>] / [NO VALUE: <key>]
markers so the lawyer sees the gap in Word rather than getting a 400.

Tests cover: single-run, multi-per-run (the go-docx failure mode),
cross-run merge, missing-marker (DE+EN), XML escaping of special
chars, non-document zip entries preserved, placeholder regex
grammar.

internal/services/submission_render.go

@@ -0,0 +1,315 @@
+package services
+
+// Submission template renderer — in-house engine for the submission
+// generator (t-paliad-215, design doc
+// docs/design-submission-generator-2026-05-19.md §6).
+//
+// Design choice — why not lukasjarosch/go-docx:
+// The library's "nested placeholder" guard treats sibling placeholders
+// inside the same <w:t> run (e.g. "{{a}} ./. {{b}}") as nested and
+// refuses to replace either. Patent submissions routinely have multiple
+// placeholders per paragraph (party blocks especially), so the library
+// is a non-starter without a custom fork. The in-house renderer below
+// is ~150 LoC and handles both the single-run common case and the
+// cross-run case (where Word may split a placeholder across runs after
+// editing).
+//
+// Placeholder grammar: {{[A-Za-z][A-Za-z0-9_.]*}} with optional
+// whitespace inside braces ({{  project.case_number  }} ≡
+// {{project.case_number}}).
+//
+// Missing-value behaviour: when a placeholder has no binding in the
+// PlaceholderMap, the renderer emits a marker token so the lawyer sees
+// the gap in Word rather than failing the request. See §6.3 of the
+// design doc.
+
+import (
+	"archive/zip"
+	"bytes"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+)
+
+// PlaceholderMap is the variable bag built by SubmissionVarsService.
+// Keys are dotted paths without braces (e.g. "project.case_number").
+// Values are the substituted text — already locale-aware, pretty-
+// printed, and sanitised by the caller.
+type PlaceholderMap map[string]string
+
+// MissingPlaceholderFn translates an unbound placeholder key into the
+// in-document marker token. The default in DefaultMissingMarker is
+// "[KEIN WERT: <key>]" / "[NO VALUE: <key>]" depending on lang.
+type MissingPlaceholderFn func(key string) string
+
+// DefaultMissingMarker returns the standard missing-value marker for
+// the given UI language.
+func DefaultMissingMarker(lang string) MissingPlaceholderFn {
+	prefix := "KEIN WERT"
+	if strings.EqualFold(lang, "en") {
+		prefix = "NO VALUE"
+	}
+	return func(key string) string {
+		return "[" + prefix + ": " + key + "]"
+	}
+}
+
+// placeholderRegex matches a single placeholder. The capture group
+// extracts the key name without braces or surrounding whitespace.
+//
+// Restricted to [A-Za-z][A-Za-z0-9_.]* so that stray "{{" sequences in
+// legal prose (extremely rare in DE/EN court briefs but possible)
+// don't get mistaken for placeholders. A genuine placeholder always
+// starts with an ASCII letter.
+var placeholderRegex = regexp.MustCompile(`\{\{\s*([A-Za-z][A-Za-z0-9_.]*)\s*\}\}`)
+
+// SubmissionRenderer renders a .docx template into a .docx output by
+// substituting {{placeholder}} tokens with values from a PlaceholderMap.
+// Stateless; safe for concurrent use.
+type SubmissionRenderer struct{}
+
+// NewSubmissionRenderer constructs the renderer.
+func NewSubmissionRenderer() *SubmissionRenderer {
+	return &SubmissionRenderer{}
+}
+
+// Render reads the .docx template at templateBytes, substitutes every
+// placeholder from vars (or emits the missing-marker token), and writes
+// the result to the returned byte slice. Unknown placeholders never
+// fail the render — the lawyer sees the marker in Word and fixes it.
+func (r *SubmissionRenderer) Render(templateBytes []byte, vars PlaceholderMap, missing MissingPlaceholderFn) ([]byte, error) {
+	if missing == nil {
+		missing = DefaultMissingMarker("de")
+	}
+	zr, err := zip.NewReader(bytes.NewReader(templateBytes), int64(len(templateBytes)))
+	if err != nil {
+		return nil, fmt.Errorf("submission template: open zip: %w", err)
+	}
+
+	var out bytes.Buffer
+	zw := zip.NewWriter(&out)
+	defer zw.Close()
+
+	for _, entry := range zr.File {
+		body, err := readZipEntry(entry)
+		if err != nil {
+			return nil, fmt.Errorf("submission template: read %s: %w", entry.Name, err)
+		}
+		if isWordXMLEntry(entry.Name) {
+			body = substituteInDocumentXML(body, vars, missing)
+		}
+		w, err := zw.CreateHeader(&zip.FileHeader{
+			Name:     entry.Name,
+			Method:   entry.Method,
+			Modified: entry.Modified,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("submission template: write header %s: %w", entry.Name, err)
+		}
+		if _, err := w.Write(body); err != nil {
+			return nil, fmt.Errorf("submission template: write %s: %w", entry.Name, err)
+		}
+	}
+	if err := zw.Close(); err != nil {
+		return nil, fmt.Errorf("submission template: finalise zip: %w", err)
+	}
+	return out.Bytes(), nil
+}
+
+// isWordXMLEntry returns true for the .docx parts that contain
+// substitutable text. We touch document.xml plus header*.xml and
+// footer*.xml (templates may put firm letterhead in a header) but
+// skip styles, theme, settings, comments, footnotes — none of which
+// should carry merge placeholders in a well-formed template.
+func isWordXMLEntry(name string) bool {
+	switch {
+	case name == "word/document.xml":
+		return true
+	case strings.HasPrefix(name, "word/header") && strings.HasSuffix(name, ".xml"):
+		return true
+	case strings.HasPrefix(name, "word/footer") && strings.HasSuffix(name, ".xml"):
+		return true
+	}
+	return false
+}
+
+// readZipEntry slurps a zip entry's bytes.
+func readZipEntry(f *zip.File) ([]byte, error) {
+	rc, err := f.Open()
+	if err != nil {
+		return nil, err
+	}
+	defer rc.Close()
+	return io.ReadAll(rc)
+}
+
+// substituteInDocumentXML walks document XML and replaces every
+// {{placeholder}} occurrence inside <w:t> text nodes. Handles both
+// single-run placeholders (the common case for freshly authored
+// templates) and cross-run placeholders (where Word's autocorrect or
+// manual editing has split a placeholder across runs).
+//
+// Two-pass strategy:
+//
+//  1. Pass 1: replace placeholders that fit entirely within one
+//     <w:t>…</w:t>. This is the 99% case and preserves all run-level
+//     formatting (bold, italic, font runs).
+//  2. Pass 2: for paragraphs that still contain orphan "{{" or "}}"
+//     markers after pass 1, merge the text of every <w:t> inside the
+//     paragraph, run the replacement on the merged text, and rewrite
+//     the paragraph's runs as a single <w:r><w:t>…</w:t></w:r> using
+//     the formatting properties of the first run. Loses intra-paragraph
+//     formatting on the affected paragraph — but only on paragraphs
+//     where Word genuinely fragmented a placeholder.
+func substituteInDocumentXML(body []byte, vars PlaceholderMap, missing MissingPlaceholderFn) []byte {
+	replaced := substituteInTextNodes(body, vars, missing)
+	if !needsCrossRunMerge(replaced) {
+		return replaced
+	}
+	return substituteAcrossRuns(replaced, vars, missing)
+}
+
+// wTextNodeRegex matches one <w:t …>contents</w:t> element, capturing
+// the contents. Attributes on <w:t> (xml:space="preserve") are preserved
+// because the entire match is rewritten.
+var wTextNodeRegex = regexp.MustCompile(`<w:t(\s[^>]*)?>([^<]*)</w:t>`)
+
+// substituteInTextNodes runs the placeholder replacement inside each
+// <w:t> text node independently. Format-preserving for single-run
+// placeholders.
+func substituteInTextNodes(body []byte, vars PlaceholderMap, missing MissingPlaceholderFn) []byte {
+	return wTextNodeRegex.ReplaceAllFunc(body, func(match []byte) []byte {
+		sub := wTextNodeRegex.FindSubmatch(match)
+		attrs := string(sub[1])
+		contents := xmlDecode(string(sub[2]))
+		replaced := replacePlaceholders(contents, vars, missing)
+		if replaced == contents {
+			return match
+		}
+		// xml:space="preserve" stays attached whenever the original
+		// content had leading/trailing whitespace; ensure it's still
+		// declared after replacement to avoid Word collapsing spaces.
+		if !strings.Contains(attrs, "xml:space") &&
+			(strings.HasPrefix(replaced, " ") || strings.HasSuffix(replaced, " ")) {
+			attrs += ` xml:space="preserve"`
+		}
+		return []byte(`<w:t` + attrs + `>` + xmlEncode(replaced) + `</w:t>`)
+	})
+}
+
+// needsCrossRunMerge returns true when the body still contains an
+// unmatched "{{" or "}}" after pass 1 — a sign that Word fragmented
+// the placeholder across runs and pass 1 couldn't touch it.
+func needsCrossRunMerge(body []byte) bool {
+	// Cheap heuristic: count "{{" vs "}}" inside <w:t> nodes. If we have
+	// either marker present in the text-node space, pass 2 will handle
+	// it. (Inside attributes or other XML, the markers don't matter.)
+	for _, m := range wTextNodeRegex.FindAllSubmatch(body, -1) {
+		t := string(m[2])
+		if strings.Contains(t, "{{") || strings.Contains(t, "}}") {
+			return true
+		}
+	}
+	return false
+}
+
+// wParagraphRegex matches one <w:p>…</w:p> paragraph block. Greedy
+// inner-content match is safe here because <w:p> elements do not nest
+// in WordprocessingML — a paragraph is the leaf container for text.
+var wParagraphRegex = regexp.MustCompile(`(?s)<w:p\b[^>]*>.*?</w:p>`)
+
+// wRunPropsRegex pulls the first <w:rPr>…</w:rPr> block from a
+// paragraph so we can reuse it as the formatting of the merged run.
+var wRunPropsRegex = regexp.MustCompile(`(?s)<w:rPr>.*?</w:rPr>`)
+
+// wParagraphPropsRegex pulls the optional <w:pPr>…</w:pPr> that sits
+// at the top of a paragraph (alignment, spacing, etc.). Preserved.
+var wParagraphPropsRegex = regexp.MustCompile(`(?s)<w:pPr>.*?</w:pPr>`)
+
+// substituteAcrossRuns is pass 2: for any paragraph that still has a
+// split placeholder, concatenate every text node, run replacement, and
+// rewrite the paragraph as a single run using the first run's
+// properties. Paragraphs without orphan markers are left untouched so
+// run-level formatting survives wherever pass 1 already resolved the
+// placeholders.
+func substituteAcrossRuns(body []byte, vars PlaceholderMap, missing MissingPlaceholderFn) []byte {
+	return wParagraphRegex.ReplaceAllFunc(body, func(para []byte) []byte {
+		textNodes := wTextNodeRegex.FindAllSubmatch(para, -1)
+		if len(textNodes) == 0 {
+			return para
+		}
+		var merged strings.Builder
+		for _, m := range textNodes {
+			merged.WriteString(xmlDecode(string(m[2])))
+		}
+		original := merged.String()
+		if !strings.Contains(original, "{{") {
+			// No fragmented placeholder in this paragraph; leave it
+			// alone so pass 1's run-level edits survive.
+			return para
+		}
+		replaced := replacePlaceholders(original, vars, missing)
+		if replaced == original {
+			return para
+		}
+		// Preserve paragraph properties (alignment, spacing) and the
+		// first run's properties (font, bold/italic).
+		pPr := wParagraphPropsRegex.Find(para)
+		rPr := wRunPropsRegex.Find(para)
+		var rebuilt bytes.Buffer
+		rebuilt.WriteString(`<w:p>`)
+		if pPr != nil {
+			rebuilt.Write(pPr)
+		}
+		rebuilt.WriteString(`<w:r>`)
+		if rPr != nil {
+			rebuilt.Write(rPr)
+		}
+		rebuilt.WriteString(`<w:t xml:space="preserve">`)
+		rebuilt.WriteString(xmlEncode(replaced))
+		rebuilt.WriteString(`</w:t></w:r></w:p>`)
+		return rebuilt.Bytes()
+	})
+}
+
+// replacePlaceholders performs the actual substitution on a plain
+// string. Unbound placeholders render the missing marker.
+func replacePlaceholders(s string, vars PlaceholderMap, missing MissingPlaceholderFn) string {
+	return placeholderRegex.ReplaceAllStringFunc(s, func(match string) string {
+		sub := placeholderRegex.FindStringSubmatch(match)
+		if len(sub) < 2 {
+			return match
+		}
+		key := sub[1]
+		if value, ok := vars[key]; ok {
+			return value
+		}
+		return missing(key)
+	})
+}
+
+// xmlDecode reverses the small set of escapes used in WordprocessingML
+// text content. We don't need a full XML parser — text nodes carry only
+// the standard five entities, and Word never emits numeric-character
+// references inside <w:t> for printable content.
+func xmlDecode(s string) string {
+	s = strings.ReplaceAll(s, "&lt;", "<")
+	s = strings.ReplaceAll(s, "&gt;", ">")
+	s = strings.ReplaceAll(s, "&quot;", `"`)
+	s = strings.ReplaceAll(s, "&apos;", "'")
+	s = strings.ReplaceAll(s, "&amp;", "&")
+	return s
+}
+
+// xmlEncode escapes a substituted value for safe insertion back into a
+// WordprocessingML text node. & must be replaced first to avoid double
+// encoding the entity prefixes we introduce on the other characters.
+func xmlEncode(s string) string {
+	s = strings.ReplaceAll(s, "&", "&amp;")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	s = strings.ReplaceAll(s, `"`, "&quot;")
+	s = strings.ReplaceAll(s, "'", "&apos;")
+	return s
+}

internal/services/submission_render_test.go

@@ -0,0 +1,354 @@
+package services
+
+import (
+	"archive/zip"
+	"bytes"
+	"io"
+	"strings"
+	"testing"
+)
+
+// minimalDOCX builds a tiny .docx zip with one document.xml that
+// contains the given body. Just enough to exercise the renderer
+// without depending on Word's full OOXML scaffolding.
+func minimalDOCX(t *testing.T, documentBody string) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	w, err := zw.Create("word/document.xml")
+	if err != nil {
+		t.Fatalf("create document.xml: %v", err)
+	}
+	if _, err := io.WriteString(w, documentBody); err != nil {
+		t.Fatalf("write document.xml: %v", err)
+	}
+	// Drop in a stub Content-Types so the bytes look more like a real
+	// .docx for any downstream sanity checks; Word doesn't care about
+	// the content during our unit tests but the shape stays honest.
+	w2, err := zw.Create("[Content_Types].xml")
+	if err != nil {
+		t.Fatalf("create content types: %v", err)
+	}
+	if _, err := io.WriteString(w2, `<?xml version="1.0"?><Types/>`); err != nil {
+		t.Fatalf("write content types: %v", err)
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatalf("close zip: %v", err)
+	}
+	return buf.Bytes()
+}
+
+// readDocumentXML pulls word/document.xml out of a rendered .docx.
+func readDocumentXML(t *testing.T, b []byte) string {
+	t.Helper()
+	zr, err := zip.NewReader(bytes.NewReader(b), int64(len(b)))
+	if err != nil {
+		t.Fatalf("open rendered zip: %v", err)
+	}
+	for _, f := range zr.File {
+		if f.Name != "word/document.xml" {
+			continue
+		}
+		rc, err := f.Open()
+		if err != nil {
+			t.Fatalf("open document.xml: %v", err)
+		}
+		defer rc.Close()
+		body, err := io.ReadAll(rc)
+		if err != nil {
+			t.Fatalf("read document.xml: %v", err)
+		}
+		return string(body)
+	}
+	t.Fatal("rendered .docx had no word/document.xml")
+	return ""
+}
+
+// TestRender_SingleRunPlaceholder covers the 99% case: a placeholder
+// that sits inside a single <w:t> text node.
+func TestRender_SingleRunPlaceholder(t *testing.T) {
+	doc := `<w:document><w:body><w:p><w:r><w:t>{{firm.name}}</w:t></w:r></w:p></w:body></w:document>`
+	tmpl := minimalDOCX(t, doc)
+	r := NewSubmissionRenderer()
+	out, err := r.Render(tmpl, PlaceholderMap{"firm.name": "HLC"}, nil)
+	if err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	body := readDocumentXML(t, out)
+	if !strings.Contains(body, ">HLC<") {
+		t.Errorf("expected HLC in body, got %q", body)
+	}
+	if strings.Contains(body, "{{") {
+		t.Errorf("unreplaced placeholder marker in body: %q", body)
+	}
+}
+
+// TestRender_MultiplePlaceholdersPerRun is the case go-docx fails on
+// — sibling placeholders inside the same <w:t> run. The in-house
+// renderer must handle them.
+func TestRender_MultiplePlaceholdersPerRun(t *testing.T) {
+	doc := `<w:document><w:body><w:p><w:r><w:t>{{parties.claimant.name}}, vertreten durch {{parties.claimant.representative}}</w:t></w:r></w:p></w:body></w:document>`
+	tmpl := minimalDOCX(t, doc)
+	r := NewSubmissionRenderer()
+	out, err := r.Render(tmpl, PlaceholderMap{
+		"parties.claimant.name":           "Acme Inc.",
+		"parties.claimant.representative": "Kanzlei Müller",
+	}, nil)
+	if err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	body := readDocumentXML(t, out)
+	if !strings.Contains(body, "Acme Inc.") || !strings.Contains(body, "Kanzlei Müller") {
+		t.Errorf("expected both party values, got %q", body)
+	}
+	if strings.Contains(body, "{{") {
+		t.Errorf("unreplaced placeholder marker in body: %q", body)
+	}
+}
+
+// TestRender_MissingMarker confirms unbound placeholders render the
+// missing-value marker instead of failing the request.
+func TestRender_MissingMarker(t *testing.T) {
+	doc := `<w:document><w:body><w:p><w:r><w:t>{{project.case_number}}</w:t></w:r></w:p></w:body></w:document>`
+	tmpl := minimalDOCX(t, doc)
+	r := NewSubmissionRenderer()
+	out, err := r.Render(tmpl, PlaceholderMap{}, DefaultMissingMarker("de"))
+	if err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	body := readDocumentXML(t, out)
+	if !strings.Contains(body, "[KEIN WERT: project.case_number]") {
+		t.Errorf("expected KEIN WERT marker, got %q", body)
+	}
+	outEN, err := r.Render(tmpl, PlaceholderMap{}, DefaultMissingMarker("en"))
+	if err != nil {
+		t.Fatalf("render en: %v", err)
+	}
+	bodyEN := readDocumentXML(t, outEN)
+	if !strings.Contains(bodyEN, "[NO VALUE: project.case_number]") {
+		t.Errorf("expected NO VALUE marker, got %q", bodyEN)
+	}
+}
+
+// TestRender_CrossRunPlaceholder simulates Word fragmenting a
+// placeholder across runs (autocorrect or post-edit run-split).
+// Pass 2 must catch it.
+func TestRender_CrossRunPlaceholder(t *testing.T) {
+	doc := `<w:document><w:body><w:p><w:r><w:t>Hello {{</w:t></w:r><w:r><w:t>project</w:t></w:r><w:r><w:t>.case_number}}!</w:t></w:r></w:p></w:body></w:document>`
+	tmpl := minimalDOCX(t, doc)
+	r := NewSubmissionRenderer()
+	out, err := r.Render(tmpl, PlaceholderMap{"project.case_number": "7 O 1234/26"}, nil)
+	if err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	body := readDocumentXML(t, out)
+	if !strings.Contains(body, "7 O 1234/26") {
+		t.Errorf("expected case number after cross-run merge, got %q", body)
+	}
+	if strings.Contains(body, "{{") {
+		t.Errorf("orphan placeholder marker remained: %q", body)
+	}
+}
+
+// TestRender_XMLEscaping verifies special characters in placeholder
+// values are escaped so they don't corrupt the document XML.
+func TestRender_XMLEscaping(t *testing.T) {
+	doc := `<w:document><w:body><w:p><w:r><w:t>{{user.display_name}}</w:t></w:r></w:p></w:body></w:document>`
+	tmpl := minimalDOCX(t, doc)
+	r := NewSubmissionRenderer()
+	out, err := r.Render(tmpl, PlaceholderMap{
+		"user.display_name": `Müller & Söhne <GmbH> "Special"`,
+	}, nil)
+	if err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	body := readDocumentXML(t, out)
+	if !strings.Contains(body, "Müller &amp; Söhne &lt;GmbH&gt; &quot;Special&quot;") {
+		t.Errorf("expected escaped value, got %q", body)
+	}
+}
+
+// TestRender_PreservesNonWordEntries leaves the rest of the .docx
+// untouched so any styles / theme / settings parts come through bit-
+// for-bit.
+func TestRender_PreservesNonWordEntries(t *testing.T) {
+	doc := `<w:document><w:body><w:p><w:r><w:t>{{firm.name}}</w:t></w:r></w:p></w:body></w:document>`
+	tmpl := minimalDOCX(t, doc)
+	r := NewSubmissionRenderer()
+	out, err := r.Render(tmpl, PlaceholderMap{"firm.name": "HLC"}, nil)
+	if err != nil {
+		t.Fatalf("render: %v", err)
+	}
+	zr, err := zip.NewReader(bytes.NewReader(out), int64(len(out)))
+	if err != nil {
+		t.Fatalf("open rendered: %v", err)
+	}
+	var sawTypes bool
+	for _, f := range zr.File {
+		if f.Name == "[Content_Types].xml" {
+			sawTypes = true
+		}
+	}
+	if !sawTypes {
+		t.Error("rendered .docx lost [Content_Types].xml")
+	}
+}
+
+// TestPlaceholderRegex_Boundaries pins the placeholder grammar.
+func TestPlaceholderRegex_Boundaries(t *testing.T) {
+	tests := []struct {
+		in       string
+		matches  []string
+	}{
+		{"plain text", nil},
+		{"{{foo}}", []string{"{{foo}}"}},
+		{"{{ foo }}", []string{"{{ foo }}"}},
+		{"{{foo.bar}}", []string{"{{foo.bar}}"}},
+		{"{{ foo.bar_baz }}", []string{"{{ foo.bar_baz }}"}},
+		{"{{1bad}}", nil}, // must start with a letter
+		{"{{ foo }} and {{ bar }}", []string{"{{ foo }}", "{{ bar }}"}},
+	}
+	for _, tc := range tests {
+		t.Run(tc.in, func(t *testing.T) {
+			got := placeholderRegex.FindAllString(tc.in, -1)
+			if len(got) != len(tc.matches) {
+				t.Fatalf("got %d matches, want %d (in=%q)", len(got), len(tc.matches), tc.in)
+			}
+			for i := range got {
+				if got[i] != tc.matches[i] {
+					t.Errorf("match %d: got %q, want %q", i, got[i], tc.matches[i])
+				}
+			}
+		})
+	}
+}
+
+// TestFamilyOf covers the proceeding-family extraction used by the
+// template registry's fallback chain.
+func TestFamilyOf(t *testing.T) {
+	tests := map[string]string{
+		"de.inf.lg.erwidg": "de.inf.lg",
+		"upc.inf.cfi.soc":  "upc.inf.cfi",
+		"dpma.opp.dpma":    "", // only three segments → no family
+		"de.inf.lg":        "",
+		"":                 "",
+	}
+	for in, want := range tests {
+		t.Run(in, func(t *testing.T) {
+			got := familyOf(in)
+			if got != want {
+				t.Errorf("familyOf(%q) = %q, want %q", in, got, want)
+			}
+		})
+	}
+}
+
+// TestLegalSourcePretty covers the prefix table.
+func TestLegalSourcePretty(t *testing.T) {
+	tests := []struct {
+		src, lang, want string
+	}{
+		{"DE.ZPO.276.1", "de", "§ 276 Abs. 1 ZPO"},
+		{"DE.ZPO.276.1", "en", "Section 276(1) ZPO"},
+		{"DE.ZPO.253", "de", "§ 253 ZPO"},
+		{"DE.ZPO.253", "en", "Section 253 ZPO"},
+		{"UPC.RoP.23.1", "de", "Regel 23.1 VerfO UPC"},
+		{"UPC.RoP.23.1", "en", "Rule 23.1 RoP UPC"},
+		{"UPC.RoP.198", "de", "Regel 198 VerfO UPC"},
+		{"DE.PatG.83", "de", "§ 83 PatG"},
+		{"EPC.123", "de", "Art. 123 EPÜ"},
+		{"EPC.123", "en", "Art. 123 EPC"},
+		// Unknown prefix → pass-through unchanged.
+		{"FOO.BAR.123", "de", "FOO.BAR.123"},
+		{"", "de", ""},
+	}
+	for _, tc := range tests {
+		t.Run(tc.src+"/"+tc.lang, func(t *testing.T) {
+			got := legalSourcePretty(tc.src, tc.lang)
+			if got != tc.want {
+				t.Errorf("legalSourcePretty(%q, %q) = %q, want %q", tc.src, tc.lang, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestOurSideTranslations pins the our_side enum → DE/EN prose
+// mapping used by addProjectVars.
+func TestOurSideTranslations(t *testing.T) {
+	cases := []struct {
+		in, wantDE, wantEN string
+	}{
+		{"claimant", "Klägerin", "Claimant"},
+		{"defendant", "Beklagte", "Defendant"},
+		{"court", "Gericht", "Court"},
+		{"both", "Klägerin und Beklagte", "Claimant and Defendant"},
+		{"", "", ""},
+		{"unknown", "", ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			if got := ourSideDE(tc.in); got != tc.wantDE {
+				t.Errorf("ourSideDE(%q) = %q, want %q", tc.in, got, tc.wantDE)
+			}
+			if got := ourSideEN(tc.in); got != tc.wantEN {
+				t.Errorf("ourSideEN(%q) = %q, want %q", tc.in, got, tc.wantEN)
+			}
+		})
+	}
+}
+
+// TestTemplateRegistry_Candidates verifies the fallback-chain order
+// matches the m-locked Q4 decision (firm → base/code → base/family →
+// skeleton).
+func TestTemplateRegistry_Candidates(t *testing.T) {
+	r := NewTemplateRegistry("", "HLC")
+	got := r.candidates("de.inf.lg.erwidg")
+	want := []string{
+		"templates/HLC/de.inf.lg.erwidg.docx",
+		"templates/_base/de.inf.lg.erwidg.docx",
+		"templates/_base/de.inf.lg.docx",
+		"templates/_base/_skeleton.docx",
+	}
+	if len(got) != len(want) {
+		t.Fatalf("candidates = %v, want %v", got, want)
+	}
+	for i := range got {
+		if got[i] != want[i] {
+			t.Errorf("candidate[%d] = %q, want %q", i, got[i], want[i])
+		}
+	}
+}
+
+// TestTemplateRegistry_Candidates_NoFamily covers submission codes
+// without a family suffix (only three dot-segments).
+func TestTemplateRegistry_Candidates_NoFamily(t *testing.T) {
+	r := NewTemplateRegistry("", "HLC")
+	got := r.candidates("dpma.opp.dpma")
+	want := []string{
+		"templates/HLC/dpma.opp.dpma.docx",
+		"templates/_base/dpma.opp.dpma.docx",
+		"templates/_base/_skeleton.docx",
+	}
+	if len(got) != len(want) {
+		t.Fatalf("candidates = %v, want %v", got, want)
+	}
+	for i := range got {
+		if got[i] != want[i] {
+			t.Errorf("candidate[%d] = %q, want %q", i, got[i], want[i])
+		}
+	}
+}
+
+// TestTemplateRegistry_Tiers labels each candidate slot. Must stay
+// 1:1 with candidates().
+func TestTemplateRegistry_Tiers(t *testing.T) {
+	r := NewTemplateRegistry("", "HLC")
+	codes := []string{"de.inf.lg.erwidg", "dpma.opp.dpma"}
+	for _, code := range codes {
+		c := r.candidates(code)
+		ts := r.tiers(code)
+		if len(c) != len(ts) {
+			t.Fatalf("candidate/tier mismatch for %q: %d vs %d", code, len(c), len(ts))
+		}
+	}
+}