# PRD — Composable Name/Filename Generator Engine

**Task:** t-paliad-355 · **Author:** leibniz (inventor) · **Date:** 2026-06-01
**Status:** DESIGN — awaiting head go/no-go on coder shift
**Builds on:** t-paliad-352 / m/paliad#155 (draft title), t-paliad-354 (export filename, merged `94adeeb`)
**Related:** `docs/plans/prd-docforge-2026-05-29.md` (doc-generation engine — a future naming consumer)

---

## § m's decisions (2026-06-01)

All eight grilling questions answered; every pick matched the inventor recommendation.

**Batch 1 — model:**
- Q1 (Composition model): **Structured segments + string shorthand.** Canonical model is an ordered segment list with per-segment missing-rules; a token-template string is an optional authoring shorthand that compiles to segments.
- Q2 (v1 precedence): **System → Firm → User → per-document.** Mirrors the existing dashboard-layout chain exactly. Project-level deferred to v1.1.
- Q3 (Engine depth): **Reusable engine, wire 3 known consumers.** Real engine now; only draft-title, submission-.docx, and the non-project fix are wired. Other surfaces register as known artifacts but keep current code.
- Q4 (Non-project name): **`<date> <keyword>`**, falling back to `Entwurf N` only when no type context exists.

**Batch 2 — concrete:**
- Q5 (Missing-rule set): **omit + placeholder + literal**, per segment.
- Q6 (Date semantics): **Render-time "today", Europe/Berlin, `YYYY-MM-DD`.**
- Q7 (Settings UX): **Live-preview string field on `/settings`** + clickable `{token}` palette. Missing-rules use defaults (not user-editable in v1).
- Q8 (Artifact scope): **2 submission artifacts (`submission_draft_title`, `submission_docx_filename`) + extensible registry.** docforge-export, data-zip, projection-slug registered as known artifacts but unwired in v1.

These are necessary for a coder shift, **not** sufficient — the head still gates whether/who/when to implement (inventor→coder rule).

---

## §0 Premises (verified against the live system, 2026-06-01)

| # | Premise | How verified |
|---|---------|--------------|
| P1 | Draft title = `<date> <client> ./. <forum> ./. <opponent>`, project-bound only, missing segments dropped-with-separator. | Read `internal/services/submission_autoname.go` (`AutoSubmissionTitle`). |
| P2 | Non-project drafts fall back to `Entwurf N` / `Draft N` counter. | Read `submission_draft_service.go` `newDraftName`/`Create`. |
| P3 | Export filename = `<date> <keyword> (<case | "Az. folgt">).docx`; keyword overridable per-draft via `composer_meta.filename_keyword`. | Read `internal/handlers/submissions.go` `submissionFileName` + `submissionFilenameKeyword`. |
| P4 | Sanitiser `SanitiseSubmissionFileName` folds umlauts, maps `/\:*?<>|`→`_`, strips `"'`, **preserves spaces/parens**. Lives in `pkg/docforge/docx/dotm.go`, re-exported via `services.SanitiseSubmissionFileName` (`docforge_shims.go`). | Read `pkg/docforge/docx/dotm.go`. |
| P5 | `DashboardLayoutSpec` is a production precedent for a validated jsonb spec: code `FactoryDefaultLayout` → admin `firm_dashboard_default` (db row id=1) → per-user `user_dashboard_layouts`, with `Validate()` (write) + `SanitizeForRead()` (read). | Read `dashboard_layout_spec.go`, `firm_dashboard_default_service.go`. |
| P6 | `users.email_preferences jsonb` (per-user bag) and `projects.metadata jsonb` exist live. No dedicated `user_preferences` table — migration 017 only added the `email_preferences` column. | `information_schema.columns` query on live `paliad` schema. |
| P7 | Draft titles are de-duplicated at create time via `uniqueDraftName` (appends a counter on collision). | Read `newDraftName`. |

**Doc-is-the-bug flags raised:** none. The two shipped behaviours are exactly as the task described; `projects.metadata` exists so a project-level override needs no new column when v1.1 arrives (only a documented sub-key).

---

## §1 The problem

Two one-off naming functions shipped in successive tasks (#155, 354). Each hardcodes: a date format, an ordered set of segments, a separator, and a missing-value policy. m wants to stop re-deriving this per feature — "we will need a filename generator more often later on" — and to expose **defaults / compositions** as a **user (and maybe project) setting**. Plus one immediate gap: non-project drafts get no date-led name.

The design must:
1. Extract a **reusable composition engine** that renders a name from (template, variable-bag, render-target).
2. Reproduce **both shipped schemes byte-for-byte** as seed defaults (no behaviour regression).
3. Add **settings** with a clean precedence chain, built **on** the dashboard-spec pattern (P5), not beside it.
4. Fix the **non-project** gap inside the engine, not as another special case.

---

## §2 The engine

A new package **`pkg/nomen`** (Latin *nomen* = "name"; firm-agnostic, sits beside `pkg/docforge`). Pure, dependency-light, table-testable. No DB, no HTTP — consumers resolve variables and hand them in, exactly as `AutoSubmissionTitle` is pure today.

> **FLAG (coder + m):** package name `nomen` is the inventor pick. Alternatives: `pkg/naming`, `internal/services/namegen`. Pick at implementation; nothing downstream depends on the name.

### 2.1 Core types (interface sketch — not final Go)

```go
package nomen

// Segment is one piece of a composition: a variable reference, the
// separator that precedes it, and what to do when the variable resolves
// empty.
type Segment struct {
    Var     string      // key into the variable catalog, e.g. "date", "keyword"
    Sep     string      // TRAILING separator: emitted AFTER this segment iff a
                        // later segment also emits. The last emitted segment's
                        // Sep is never used. (See Slice-1 note below.)
    Wrap    [2]string   // optional surrounding literals, e.g. {"(", ")"} for case-no.
    Missing MissingRule // omit | placeholder | literal
}

type MissingRule struct {
    Kind  MissingKind // KindOmit | KindPlaceholder | KindLiteral
    Value string      // placeholder/literal text (e.g. "Az. folgt"); ignored for omit
}

// Composition is the canonical, validated model.
type Composition struct {
    Version  int       // schema version (start at 1)
    Segments []Segment
}

// VarResolver yields a variable's value for one render. Returns ("", false)
// when the variable is unavailable in this context (→ Missing rule applies).
type VarResolver func(key string) (string, bool)

// RenderTarget post-processes the assembled string (sanitisation, suffix).
type RenderTarget interface {
    Name() string                 // "title" | "filename"
    Transform(assembled string) string
}

func (c Composition) Render(resolve VarResolver, target RenderTarget) string
func (c Composition) Validate(catalog VarCatalog) error
```

> **Implementation note (Slice 1, 2026-06-01 — `Sep` is trailing, not leading).**
> This PRD originally sketched `Sep` as the separator emitted *before* a
> segment. During Slice 1 that model proved unable to reproduce #155
> byte-for-byte: the existing test `"no client — client segment omitted"`
> requires `2026-05-31 UPC ./. Novartis Pharma` — the date must join the
> *forum* with a single space when the client is absent, while the
> forum-to-opponent join stays ` ./. `. A separator owned by the right-hand
> segment would need two different values for the same segment depending on
> what was omitted before it. Making the separator **trailing** (owned by
> the left-hand segment) is the minimal faithful fix: the date's trailing
> ` ` is used whenever any identity segment follows, and each party's
> trailing ` ./. ` is used whenever another party follows. All shipped
> #155/354 tests pass unchanged. Implemented in `pkg/nomen/nomen.go`; the
> realised `RenderTarget` also splits `Transform` into `SanitiseValue`
> (per-variable) + `Finalise` (whole-string + suffix) per §2.3.

### 2.2 Render algorithm (reproduces both shipped schemes)

For each segment, in order:
1. `val, ok := resolve(seg.Var)`.
2. If `!ok || strings.TrimSpace(val) == ""`, apply `seg.Missing`:
   - `KindOmit` → segment contributes nothing (and its `Sep` is suppressed).
   - `KindPlaceholder` → `val = seg.Missing.Value` (treated as present).
   - `KindLiteral` → `val = seg.Missing.Value` (same as placeholder; distinct *intent* in the model — "this is a fixed label", not "this is a stand-in for missing data" — so the settings UI can word them differently and future policy can diverge).
3. If the segment emits, prepend `seg.Sep` **iff at least one segment already emitted** (kills the leading-separator problem the #155 code solves by hand), then wrap with `seg.Wrap`.
4. Concatenate.
5. `target.Transform(assembled)` runs once on the whole string.

**Separator suppression** is the generalisation of #155's "drop segment + its leading separator". **Placeholder** is the generalisation of 354's `(Az. folgt)`.

### 2.3 Render targets

The **same** `Composition` renders to different targets:

| Target | `Transform` | Used by |
|--------|-------------|---------|
| `TitleTarget` | identity (spaces, umlauts, ` ./. ` all valid in a human title) | `submission_draft_title` |
| `FilenameTarget{ext: ".docx"}` | per-segment-aware: applies `services.SanitiseSubmissionFileName` to **variable values** (not the frame — preserve the spaces/parens/wrap), then appends `ext`. | `submission_docx_filename` |

> **Design note — where sanitisation runs.** 354 sanitises *each variable value* but keeps the assembled frame (`<date> <kw> (<case>)`) intact. To preserve that exactly, the `FilenameTarget` is **not** a dumb whole-string transform — the engine sanitises each resolved variable value *before* assembly when the target requests it, and the target only appends the extension at the end. So `RenderTarget` gains one more hook:

```go
type RenderTarget interface {
    Name() string
    SanitiseValue(v string) string  // per-variable; identity for TitleTarget
    Finalise(assembled string) string // whole-string; appends ".docx" for filename
}
```

This is the one subtlety that makes the engine faithful to 354. Both shipped schemes drop out of `(Composition, VarResolver, RenderTarget)` with no special-casing.

### 2.4 Variable catalog

A `VarCatalog` is an extensible registry: `key → VarDef{ Label, LabelEN, Description, Group }`. The catalog is **metadata only** (for validation + the settings palette); **values** come from the per-render `VarResolver` the consumer supplies. This keeps the engine pure — a consumer registers which keys it can resolve, the engine validates a composition only references known keys.

v1 catalog (the union of what the two schemes need + obvious near-neighbours):

| key | meaning | resolver source (submission consumer) |
|-----|---------|----------------------------------------|
| `date` | render-time today, Europe/Berlin, `YYYY-MM-DD` | engine-provided default resolver (see §2.5) |
| `keyword` | document/submission type; user-overridable | `composer_meta.filename_keyword` → rule name (lang-aware) → "submission" |
| `case_number` | project Aktenzeichen | `project.CaseNumber` |
| `client` | root-ancestor client name | project-tree walk (existing `autoNameForProject`) |
| `forum` | short forum label (UPC/EPA/LG/…) | `submissionForumShort(pt)` (existing) |
| `opponent` | primary opposing party name | `submissionOpponentName(parties, ourSide)` (existing) |

Registered-but-deferred keys (declared so compositions can reference them, resolvers added when a consumer needs them): `proceeding`, `lang`, `client_matter`, `project_name`, `draft_counter`.

**Extensibility contract:** a new consumer (e.g. docforge export) builds its own `VarCatalog` subset + `VarResolver` and registers an artifact (§4). It never edits the engine.

### 2.5 The `date` resolver

The engine ships a default `date` resolver: `time.Now()` → `Europe/Berlin` → `Format("2006-01-02")`. This is the **one** variable the engine resolves itself (both shipped schemes compute it identically), so a consumer that only wants the standard date doesn't re-implement it. A consumer may override `date` in its resolver (e.g. a created-at date) — but v1 does not.

---

## §3 Settings & precedence

### 3.1 Precedence chain (v1)

Resolution order for a given artifact, **first hit wins**:

```
per-document override  →  user override  →  firm default  →  system default
   (highest priority)                                        (always present)
```

- **System default** — code-resident, per artifact. The seed `Composition` literals (§5). Always exists; nothing can delete it.
- **Firm default** — optional admin-set row, mirrors `firm_dashboard_default` (P5). A firm can mandate a house naming convention. Cleared → reverts to system.
- **User override** — per-user, stored in a jsonb bag keyed by artifact id. Absent key → fall through.
- **Per-document override** — the **already-shipped** `composer_meta.filename_keyword`, generalised to a `composer_meta.name_overrides` map of `{var → value}` (back-compat: `filename_keyword` reads as `name_overrides.keyword` for the filename artifact). This is a *variable-value* override, not a *composition* override — the user is replacing one token's value for one document, not redefining the template.

> **Why per-document is a value override, not a template override:** the shipped "Stichwort" editor lets a lawyer change *what the keyword is* for one draft, not *the shape of the name*. Keeping per-document as value-only avoids giving every draft its own editable template (scope creep) while preserving the shipped UX exactly.

### 3.2 Storage

| Level | Where | Shape |
|-------|-------|-------|
| System | Go code (`nomen` consumer package) | `Composition` literals |
| Firm | **new** `paliad.firm_name_compositions` (id=1 singleton, mirrors `firm_dashboard_default`) | `jsonb`: `{ artifact_id: Composition }` map, validated |
| User | **new column** `paliad.users.name_compositions jsonb NOT NULL DEFAULT '{}'` (mirrors `email_preferences`) | `{ artifact_id: Composition }` map |
| Per-document | **existing** `submission_drafts.composer_meta` | `{ name_overrides: { var: value } }` (supersedes flat `filename_keyword`) |

A `NameCompositionSpec` type gets `Validate()` (write — references-known-vars, known-artifact, ≤ N segments) and `SanitizeForRead()` (read — drop segments referencing dropped vars, clamp version), exactly like `DashboardLayoutSpec`. This is the closest existing analog and the pattern is copy-shaped.

> **Project-level (v1.1, deferred):** when it lands, it slots between user and firm (`per-document → user → project → firm → system`) and stores under a documented `projects.metadata.name_compositions` sub-key — **no migration needed** (P6: column exists). The "project vs user, who wins?" call (Q2) is deferred with it; the v1.1 default is **user wins** (a lawyer's personal convention beats a matter's), but that's a v1.1 decision, flagged here so v1 storage doesn't preclude it.

---

## §4 Artifact registry

An **artifact** is a named thing that gets a name: it binds a default composition, an allowed-variable subset, and a render target.

```go
type Artifact struct {
    ID            string        // "submission_draft_title", "submission_docx_filename"
    Label         string        // for the settings UI
    Catalog       VarCatalog    // which variables are available here
    Target        RenderTarget  // title vs filename
    SystemDefault Composition   // the seed (§5)
}
```

v1 registry (`internal/services/namegen` — the paliad-side wiring; `pkg/nomen` stays pure):

| Artifact ID | Target | Wired in v1? |
|-------------|--------|--------------|
| `submission_draft_title` | title | **yes** |
| `submission_docx_filename` | filename `.docx` | **yes** |
| `docforge_export` | filename | registered, **unwired** (opts in when docforge ships) |
| `data_zip_export` | filename `.zip` | registered, **unwired** (keeps `ExportFilename` shape) |
| `projection_slug` | slug | registered, **unwired** |

Registering-but-not-wiring means: the artifact ID exists in the catalog so the settings UI *could* list it and a composition *could* be stored, but the consumer still calls its current code path until a follow-up task flips it. No dead behaviour, no speculative resolver code.

> **`data_zip_export` note:** `ExportFilename` (`paliad-export-project-<slug>-<short>-<ts>.zip`) is deliberately machine-shaped (UTC timestamp, uuid disambiguator) — it is **not** a legal title and should **not** inherit the legal-composition defaults. It is registered for *discoverability*, but its eventual opt-in would use a distinct catalog (slug/timestamp/uuid vars), confirming the engine generalises beyond the legal-title model without forcing that model on it.

---

## §5 Seed defaults (the two shipped schemes, as data)

### 5.1 `submission_draft_title` (reproduces `AutoSubmissionTitle`, #155)

```
Segments:
  { Var: "date",     Sep: "",      Missing: omit }
  { Var: "client",   Sep: " ",     Missing: omit }
  { Var: "forum",    Sep: " ./. ", Missing: omit }
  { Var: "opponent", Sep: " ./. ", Missing: omit }
Target: TitleTarget
```

- All-omit + separator-suppression reproduces "drop empty segment with its leading separator".
- `date` with `Sep: ""` and the others' first-emitted-suppresses-Sep rule yields `2026-05-31 Bayer AG ./. UPC` when opponent is empty — identical to today.
- Non-project draft: `client`/`forum`/`opponent` resolve `("", false)` → all omitted → renders bare `<date>`. **This is the non-project fix** (§6).

### 5.2 `submission_docx_filename` (reproduces `submissionFileName`, 354)

```
Segments:
  { Var: "date",        Sep: "",  Missing: omit }
  { Var: "keyword",     Sep: " ", Missing: literal("submission") }
  { Var: "case_number", Sep: " ", Wrap: {"(", ")"},
                                  Missing: placeholder("Az. folgt") }
Target: FilenameTarget{ext: ".docx"}
```

- `keyword` missing → `literal("submission")` reproduces the `kw == "" → "submission"` fallback.
- `case_number` missing → `placeholder("Az. folgt")`, wrapped in parens → `(Az. folgt)`.
- `FilenameTarget` sanitises each value via `SanitiseSubmissionFileName`, preserves the frame, appends `.docx`. Output identical to 354.

**Faithfulness test (acceptance gate):** golden-file table tests assert the engine's output is byte-equal to the current `AutoSubmissionTitle` / `submissionFileName` across the existing test matrix (with/without opponent, with/without case-number, en/de, umlaut folding). The shipped funcs become thin wrappers over the engine, or are deleted once call-sites move.

---

## §6 The non-project fix

Currently `newDraftName` only calls `autoNameForProject` when `project != nil`; otherwise `nextDraftName` → `Entwurf N`. Under the engine:

- A non-project draft renders `submission_draft_title` with a resolver where `client/forum/opponent` are all `("", false)` → composition degrades to `<date>`.
- Per Q4, the default gains a `keyword` segment so non-project drafts read **`<date> <keyword>`** where `keyword` = submission/document type if the draft has a `submission_code` that maps to a rule, else falls back.
- **Fallback when no keyword context:** if `keyword` also resolves empty (project-less draft with no `submission_code`/rule), the title degrades to `<date> Entwurf N` — `Entwurf N` enters as the `keyword` segment's `literal` fallback **with** the existing counter, so uniqueness is preserved via `uniqueDraftName` (P7).

> **FLAG (coder):** confirm whether project-less drafts (t-paliad-243) carry a `submission_code`. If yes, `keyword` derives from the rule like the project path. If no, the `literal("Entwurf N")` fallback is the norm and non-project names read `<date> Entwurf N` — still satisfies "date first there" (m's ask). Resolve in implementation; both paths are handled by the same composition.

The non-project title is the **same** `submission_draft_title` artifact — not a separate composition. Degradation is data-driven, not a code branch. This is the payoff of the engine: the gap closes by *removing* the `project != nil` special-case, not adding another.

---

## §7 Settings UX (v1)

A section on the existing `/settings` page (017 surface):

- **Per artifact** (v1 lists the 2 wired ones): a single-line **token-template string** field, e.g. `{date} {keyword} ({case_number})`.
- A **token palette**: clickable chips (`{date}` `{client}` `{forum}` `{opponent}` `{keyword}` `{case_number}`) insert at cursor. Chips show the localised label (DE primary / EN secondary).
- A **live preview** rendered against a **sample project** (fixed fixture: client "Bayer AG", forum "UPC", opponent "Sandoz", case "UPC_CFI_123/2026", today's date) so the user sees the result instantly — and a second preview line with empties so they see the missing-rule behaviour.
- **Reset to firm/system default** button (mirrors the dashboard "reset layout").

**String ⇄ segments:** the field is the *shorthand* (Q1). A small parser compiles `{var}` tokens + surrounding literals into `Segments` (separators = the literal runs between tokens; `(…)` around a token → `Wrap`). Missing-rules are **not** in the string (Q7) — they come from the system default for that var and are not user-editable in v1. So a user can reorder/drop/re-add tokens and change literals, but can't (yet) flip case-number from placeholder to omit. That's a deliberate v1 boundary; the structured model already supports it, the UI just doesn't expose it.

> Parser edge: a `{token}` the catalog doesn't know → inline validation error ("Unknown variable {foo}"), preview shows nothing, save disabled. Mirrors `DashboardLayoutSpec.Validate` rejecting unknown widget keys.

---

## §8 Slice train

Sliced so a **tracer bullet** ships value before the settings UI exists.

- **Slice 1 — Engine + faithful refactor (no behaviour change).**
  `pkg/nomen` (types, render, targets, catalog) + `internal/services/namegen` (artifact registry + the 2 seed compositions + resolvers built from existing `submission_autoname.go` helpers). Re-point `AutoSubmissionTitle` and `submissionFileName` call-sites at the engine. **Acceptance:** §5 golden-file byte-equality; all existing #155/354 tests green unchanged. *No user-visible change — this is the safety net.*
- **Slice 2 — Non-project date-first (§6).**
  Remove the `project != nil` special-case in `newDraftName`; non-project drafts render `submission_draft_title`. **Acceptance:** project-less draft gets `<date> <keyword>` (or `<date> Entwurf N` fallback); existing project drafts unchanged. *First user-visible win, m's immediate ask.*
- **Slice 3 — Precedence: system → user (per-document already shipped).**
  `users.name_compositions jsonb` column + `NameCompositionSpec` (`Validate`/`SanitizeForRead`) + resolution that prefers a user override over the system default. Generalise `composer_meta.filename_keyword` → `name_overrides.keyword` (back-compat read). *No UI yet — overrides settable via API/test.*
- **Slice 4 — Settings UX (§7).**
  `/settings` token-template field + palette + live preview for the 2 wired artifacts. *User can now customise.*
- **Slice 5 — Firm default.**
  `firm_name_compositions` singleton + admin surface, mirroring `firm_dashboard_default`. Slots into precedence below user. *Firm-wide convention.*

Slices 1–2 are the tracer bullet (engine proven on shipped behaviour + the gap closed). 3–5 layer settings without re-touching the engine.

---

## §9 Out of scope (this PRD)

- Implementation, migration SQL drafting, Go code.
- Re-litigating #155 / 354 behaviour — they are the seed defaults, reproduced not redesigned.
- **Project-level** compositions (v1.1; storage path reserved in §3.2, precedence call deferred).
- Wiring `docforge_export`, `data_zip_export`, `projection_slug` — registered, not migrated (each is its own follow-up when the surface needs it).
- Naming for non-doc-generation strings across the app.
- User-editable **missing-rules** in the settings UI (model supports it; UI deferred past v1).

---

## §10 Open questions (historical record — resolved in § m's decisions)

1. Composition representation — token-string vs structured-segments vs both. → **Q1: structured + string shorthand.**
2. v1 precedence levels. → **Q2: system → firm → user → per-document.**
3. Generalisation depth (YAGNI vs engine-now). → **Q3: reusable engine, 3 consumers wired.**
4. Non-project default name. → **Q4: `<date> <keyword>`.**
5. Missing-rule policy set. → **Q5: omit + placeholder + literal.**
6. Date semantics. → **Q6: render-time today, Europe/Berlin, `YYYY-MM-DD`.**
7. Settings UX shape. → **Q7: live-preview string field + palette.**
8. Artifact registry scope. → **Q8: 2 submission artifacts + extensible registry.**

**Remaining FLAGs for the coder (not blocking design approval):**
- Package name `pkg/nomen` (vs `naming`/`namegen`) — implementation pick.
- Whether project-less drafts carry a `submission_code` (decides `keyword` source in §6).
- `name_overrides` back-compat read of the existing `filename_keyword` key — confirm the one shipped draft-keyword row migrates cleanly (live round-trip test, like t-paliad-354's).
