paliad/docs/design-litigation-planner-2026-05-26.md

Litigation Planner suite — extract Fristenrechner/Verfahrensablauf into a Go package for paliad + youpc.org reuse

Task: t-paliad-292 (m/paliad#124) · inventor design phase · read-only · NO code, NO migrations Branch: mai/cronus/inventor-litigation Author: cronus (inventor) Date: 2026-05-26 Issue: #124

---

§0.5 m's decisions (2026-05-26, AskUserQuestion round)

After Q1+Q2 escalation, m chose AskUserQuestion-mode + revised Q2 framing. Four-question round answered live:

Q	Topic	m's pick	Note
§0.5-Q1	Composition shape	Primary + spawned (v1) with multi-proceeding peer compose as the goal (v2)	"Usually it would be 1 — but 2 is the goal. So people can create more complex scenarios." The jsonb spec is architected for N entries from day 1; v1 ships with N=1; v2 adds peers without a schema migration.
§0.5-Q2	Scope	Per-project + abstract	Scenarios attach to a real Akte (project_id non-NULL) AND can be created standalone on /tools/verfahrensablauf (project_id NULL = abstract saved templates).
§0.5-Q3	Trigger dates	Per-anchor overrides over one base date	Matches today's compute model — one trigger date + AnchorOverrides for known court-set / extended dates. Per-proceeding dates inside the spawn graph derive from base + parent chain.
§0.5-Q4	Storage	New paliad.scenarios table with jsonb spec	Beats the column-extension option because the spec carries multi-proceeding compose, abstract-vs-project distinction, and absorbs future schema churn inside jsonb.

Additional clarification (m's text): "users should not add their own rules. I want them to setup a scenario with different existing proceeding types / submissions that trigger sequences."

→ Original Slice E (user-authored rules) is DROPPED. paliad.deadline_rules.project_id column is OUT. Scenarios are pure compositions of existing rules/proceedings/submissions — never authored corpus. §6 below is preserved as historical context; the slice plan in §10 is revised.

→ New Slice E = abstract scenarios surface on /tools/verfahrensablauf (Speichern affordance + per-user saved-template list). Different chrome, same scenarios table, same engine.

§5 has been rewritten to match these picks; §6 is preserved struck-through; §10 slice plan is revised. The package layout in §2 and the public API in §3 are unchanged by these decisions — the library shape was decoupled by design from persistence + UI choices.

---

§0 TL;DR

paliad + youpc.org both import a single Go package — pkg/litigationplanner — that owns the deadline-rule model, the calendar arithmetic, the condition-expression gate, the sub-track routing, and the timeline composer. Persistence stays at the call-site: paliad's internal/services/* implements the Catalog / HolidayCalendar / CourtRegistry interfaces against Postgres; youpc.org imports embedded/upc.Catalog() + friends and runs the same engine against a generator-produced JSON snapshot of paliad's UPC subset.

The convergence:

1. Today the calc is 1505 LoC in internal/services/fristenrechner.go + 175 LoC in deadline_calculator.go + helpers, all paliad-internal.
2. Phase 2 unification (t-paliad-181 / Slices 1-10, all shipped) collapsed Pipelines A + B + C onto a single paliad.deadline_rules table — 231 rows, 20 active proceeding types, lifecycle_state-gated, condition_expr-gated, 77 UPC rules.
3. The body to extract is already structurally a library; the work is moving it across the package boundary atomically and replacing the DB-coupled imports with abstract Catalog / HolidayCalendar / CourtRegistry interfaces.
4. youpc.org's UPC-restricted reuse rides on an embedded JSON snapshot (UPC subset + UPC/EU holidays + UPC courts) shipped inside the package — import "mgit.msbls.de/m/paliad/pkg/litigationplanner/embedded/upc" is the entire integration surface on the youpc side.
5. Scenarios + user-authored rules are paliad-side persistence concerns that the package's request shape (CalcRequest) already supports via RuleOverrides + per-card Choices. The pkg need not grow new contracts for either; only paliad's catalog impl + paliad-side tables grow.

Six slices, each independently shippable on the paliad side; one paired PR on the youpc side at the end (revised per §0.5):

• Slice A — atomic extract of calc + types + condition_expr + sub-track + legal-source helpers into pkg/litigationplanner. No behaviour change. paliad's internal/services/fristenrechner.go becomes a 60-line shell.
• Slice B — Catalog / HolidayCalendar / CourtRegistry interfaces + paliad's default loaders implementing them.
• Slice C — embedded UPC snapshot + scripts/snapshot-upc/main.go generator.
• Slice D — paliad.scenarios table + jsonb spec + per-project chip group. Composition-of-existing-rules (NOT user-authored rules — §6 retracted).
• Slice E — abstract scenarios on /tools/verfahrensablauf (Speichern als Vorlage + Meine Vorlagen list). Same table, project_id IS NULL.
• Slice F — youpc.org integration (separate PR on the youpc repo).

m's locked decisions (latest = §0.5):

• Package within paliad (option 1, not a separate repo). ✓
• AskUserQuestion permitted this session — m flipped the protocol mid-session. ✓
• Scenarios = jsonb spec, per-project + abstract, primary+spawned for v1, multi-peer for v2. ✓
• No user-authored rules. Composition only. ✓

---

§1 Today's surfaces converging

Three surfaces share the same compute core today. The package crystallises that:

1. Fristenrechner (/tools/fristenrechner)

Knowledge-tool surface. Manual deadline calculation: user picks proceeding type + trigger date + optional flags + per-card choices, gets a flat list of computed deadlines. Backed by FristenrechnerService.Calculate(ctx, proceedingCode, triggerDateStr, opts CalcOptions) (*UIResponse, error). Implemented at internal/services/fristenrechner.go:270 and consumed by internal/handlers/fristenrechner.go.

Path-A (abstract browse via ?path=a) and Path-B (Determinator concept-cascade via ?path=b, t-paliad-166) feed the same Calculate.

2. Verfahrensablauf (/tools/verfahrensablauf)

Knowledge-tool surface. Same compute, different chrome — abstract browse-a-proceeding with variant chips + consolidated-vs-lane view + side-by-side compare (t-paliad-178/179, shipped). The frontend lifts a shared client/views/verfahrensablauf-core.ts module; both routes call the SAME Calculate endpoint, just with different UI framing.

3. SmartTimeline (/projects/{id} Verlauf)

Per-project read view. ProjectionService.For(ctx, projectID, opts) (*ResponseEnvelope, error) at internal/services/projection_service.go:1 builds the merged stream:

• Past actuals from paliad.deadlines ∪ appointments ∪ project_events (filtered to opted-in timeline_kind)
• Future-projected rows from FristenrechnerService.Calculate(...) driven by the project's proceeding_type_id + anchor map built from already-completed actuals
• Off-script events (counterclaim_created, scope_change, custom_milestone)

ProjectionService is paliad-only — it speaks Postgres directly (loads project + counterclaim children + actuals, builds the anchor override map, merges + sorts the events, applies levelPolicy at Patent/Litigation/Client). The compute step inside it (the FristenrechnerService.Calculate call at projection_service.go:813) is the only part that crosses into the library.

What converges, what doesn't

Concern	Goes into pkg/litigationplanner	Stays in internal/services
Rule model (Rule, ProceedingType)	✓	—
Calendar arithmetic + working-day walker	✓	—
condition_expr jsonb evaluator	✓	—
Sub-track routing	✓	—
Legal-source display/URL formatting	✓	—
MapLitigationToFristenrechner	✓	—
CalcOptions (flags, anchor overrides, per-card choices, skip rules)	✓	—
Calculate + CalculateRule (the pure entry points)	✓	—
Catalog / HolidayCalendar / CourtRegistry interfaces	✓	—
paliad-specific Catalog impl (reads paliad.deadline_rules)	—	✓ (slim)
paliad-specific HolidayCalendar impl (reads paliad.holidays)	—	✓
paliad-specific CourtRegistry impl (reads paliad.courts)	—	✓
ProjectionService (per-project SmartTimeline)	—	✓ (no change)
Scenarios persistence (table writes)	—	✓
User-authored rule writes (insert into paliad.deadline_rules)	—	✓ (rule editor)
Audit log + RLS	—	✓
HTTP handlers + UI response JSON tags	—	✓ (UIResponse shape kept byte-identical)

Verfahrensablauf and /tools/fristenrechner become thin wrappers over the package; SmartTimeline still owns its merge logic but delegates the future-projection step to the package.

---

§2 Target package layout

pkg/litigationplanner/
  doc.go                       — package docstring, reuse manifesto, version banner
  types.go                     — Rule, ProceedingType, Court, Holiday, CalcOptions,
                                 Timeline, TimelineEntry, RuleCalculation, ConditionExpr
  catalog.go                   — Catalog interface + ProjectHint
  holidays.go                  — HolidayCalendar interface + AdjustForNonWorkingDays
                                 + AdjustForNonWorkingDaysBackward
  courts.go                    — CourtRegistry interface + DefaultsForJurisdiction
  expr.go                      — condition_expr jsonb evaluator (pure)
  durations.go                 — applyDuration + addWorkingDays (pure, takes a
                                 HolidayCalendar)
  subtrack.go                  — SubTrackRouting registry (statically embedded —
                                 the 1 entry today is upc.ccr.cfi → upc.inf.cfi)
  legal_source.go              — FormatLegalSourceDisplay + BuildLegalSourceURL
  proceeding_mapping.go        — MapLitigationToFristenrechner + code constants
  engine.go                    — Calculate(ctx, req CalcRequest, cat Catalog,
                                 hol HolidayCalendar, crt CourtRegistry) (*Timeline, error)
                                 + CalculateRule(...) for the single-rule v4 surface
  embedded/
    upc/
      catalog.go               — //go:embed catalog.json + NewCatalog() Catalog
      catalog.json             — 9 proceeding types × 77 rules (generator output)
      holidays.go              — //go:embed holidays.json + NewHolidayCalendar()
      holidays.json            — UPC summer vacation + UPC public holidays + EU
                                 public holidays (regime='UPC' + country='DE'+'FR'+
                                 'NL'+'IT' subsets paliad already carries)
      courts.go                — //go:embed courts.json + NewCourtRegistry()
      courts.json              — UPC LDs + CFI + CoA + LDC, country/regime tagged
      version.go               — //go:embed VERSION (paliad release tag the
                                 snapshot was generated against)
      snapshot_test.go         — golden test: every rule's compute matches the
                                 reference fixture compute
  scripts/
    snapshot/
      main.go                  — reads paliad.deadline_rules etc. via $DATABASE_URL,
                                 writes embedded/upc/{catalog,holidays,courts}.json
                                 + bumps VERSION
      README.md                — "How to regenerate the UPC snapshot"
  testdata/
    fixtures/                  — input + expected-output JSON pairs (per proceeding
                                 type, per scenario) for golden tests
  README.md                    — "How to import this package"
  CHANGELOG.md                 — package-internal changelog (semver beats)

Why a sub-package per snapshot

embedded/upc/ (and any future embedded/de/, embedded/epa/, …) sits below pkg/litigationplanner/ so the snapshot is opt-in: youpc.org imports the snapshot, paliad does not (paliad runs against its live DB). Importing the snapshot pulls the JSON into the binary; consumers who only want the engine pay zero binary bloat.

Why no scenarios/ sub-package

m's framing — "create scenarios" — is paliad-side persistence: name a state, store it, switch active. The package's CalcRequest already accepts the only field that varies per scenario (Choices + AnchorOverrides). Scenarios are a paliad table; the package needs no new contract. See §5.

---

§3 Public API + types

Rule

// Rule is the canonical deadline rule shape. JSON tags match the
// paliad.deadline_rules columns 1:1 so the generator can dump rows
// straight into the snapshot.
type Rule struct {
    ID                       uuid.UUID       `json:"id"`
    ProceedingTypeID         int             `json:"proceeding_type_id"`
    ParentID                 *uuid.UUID      `json:"parent_id,omitempty"`
    SubmissionCode           *string         `json:"submission_code,omitempty"`
    Name                     string          `json:"name"`
    NameEN                   string          `json:"name_en"`
    Description              *string         `json:"description,omitempty"`
    PrimaryParty             *string         `json:"primary_party,omitempty"`
    EventType                *string         `json:"event_type,omitempty"`

    DurationValue            int             `json:"duration_value"`
    DurationUnit             string          `json:"duration_unit"` // days|weeks|months|working_days
    Timing                   *string         `json:"timing,omitempty"` // after|before
    AltDurationValue         *int            `json:"alt_duration_value,omitempty"`
    AltDurationUnit          *string         `json:"alt_duration_unit,omitempty"`
    AltRuleCode              *string         `json:"alt_rule_code,omitempty"`
    CombineOp                *string         `json:"combine_op,omitempty"` // min|max
    AnchorAlt                *string         `json:"anchor_alt,omitempty"` // priority_date

    RuleCode                 *string         `json:"rule_code,omitempty"`
    DeadlineNotes            *string         `json:"deadline_notes,omitempty"`
    DeadlineNotesEN          *string         `json:"deadline_notes_en,omitempty"`
    SequenceOrder            int             `json:"sequence_order"`

    ConditionExpr            json.RawMessage `json:"condition_expr,omitempty"`
    Priority                 string          `json:"priority"` // mandatory|recommended|optional|informational
    IsCourtSet               bool            `json:"is_court_set"`
    IsSpawn                  bool            `json:"is_spawn"`
    SpawnLabel               *string         `json:"spawn_label,omitempty"`
    SpawnProceedingTypeID    *int            `json:"spawn_proceeding_type_id,omitempty"`
    LegalSource              *string         `json:"legal_source,omitempty"`
    ConceptID                *uuid.UUID      `json:"concept_id,omitempty"`
    IsBilateral              bool            `json:"is_bilateral"`
    TriggerEventID           *int64          `json:"trigger_event_id,omitempty"`
    ChoicesOffered           json.RawMessage `json:"choices_offered,omitempty"`

    // Lifecycle fields are part of the schema but irrelevant to the
    // calculator (a non-published rule never reaches the engine). They
    // ship in the snapshot for traceability but the engine ignores them.
    LifecycleState           string          `json:"lifecycle_state"`
    DraftOf                  *uuid.UUID      `json:"draft_of,omitempty"`
    PublishedAt              *time.Time      `json:"published_at,omitempty"`
}

ProceedingType

type ProceedingType struct {
    ID                  int     `json:"id"`
    Code                string  `json:"code"` // upc.inf.cfi
    Name                string  `json:"name"`
    NameEN              string  `json:"name_en"`
    Description         *string `json:"description,omitempty"`
    Jurisdiction        *string `json:"jurisdiction,omitempty"` // UPC|DE|EPA|DPMA
    DefaultColor        string  `json:"default_color"`
    SortOrder           int     `json:"sort_order"`
    DisplayOrder        int     `json:"display_order"`
    TriggerEventLabelDE *string `json:"trigger_event_label_de,omitempty"`
    TriggerEventLabelEN *string `json:"trigger_event_label_en,omitempty"`
}

Catalog interface

// Catalog supplies proceeding-type metadata + rules. Implementations:
//   - paliad: SELECTs from paliad.deadline_rules + paliad.proceeding_types,
//     filtered to lifecycle_state='published' AND is_active=true. Optional
//     ProjectHint (Slice E) merges in project-scoped rules.
//   - embedded/upc: in-memory map keyed by code, populated once at init
//     from the embedded JSON.
type Catalog interface {
    Proceeding(ctx context.Context, code string, hint ProjectHint) (*ProceedingType, []Rule, error)
    SubTrackRouting(code string) (SubTrackRouting, bool)
}

// ProjectHint scopes a Catalog call to a specific project. paliad's
// catalog uses ProjectID to merge in rules with project_id = hint.ProjectID
// (Slice E). youpc's catalog ignores the hint (no projects exist).
//
// Zero value = no project context (the abstract Verfahrensablauf /
// public Fristenrechner case).
type ProjectHint struct {
    ProjectID uuid.UUID
}

var ErrUnknownProceedingType = errors.New("unknown proceeding type")

HolidayCalendar interface

// HolidayCalendar adjusts dates onto working days for a given
// (country, regime) pair. The package's calc only needs three primitives:
//
//   - IsNonWorkingDay  — used by addWorkingDays walker
//   - AdjustForNonWorkingDays         — forward snap (timing='after')
//   - AdjustForNonWorkingDaysBackward — backward snap (timing='before')
//
// Implementations:
//   - paliad: reads paliad.holidays, caches per-year, merges DE federal
//     fallback. Existing HolidayService at internal/services/holidays.go
//     already does this; gains a thin satisfying-the-interface shim.
//   - embedded/upc: in-memory year-keyed map populated from the embedded
//     JSON snapshot. Covers UPC summer vacation, UPC public holidays,
//     and the country-tagged subsets paliad ships for UPC LDs (DE, FR,
//     NL, IT — the countries the LDs sit in).
type HolidayCalendar interface {
    IsNonWorkingDay(date time.Time, country, regime string) bool
    AdjustForNonWorkingDays(date time.Time, country, regime string) (time.Time, bool)
    AdjustForNonWorkingDaysBackward(date time.Time, country, regime string) (time.Time, bool)
    AdjustmentReason(date time.Time, country, regime string) *AdjustmentReason
}

type AdjustmentReason struct {
    Country    string `json:"country,omitempty"`
    Regime     string `json:"regime,omitempty"`
    Name       string `json:"name,omitempty"`
    IsVacation bool   `json:"isVacation,omitempty"`
    IsClosure  bool   `json:"isClosure,omitempty"`
}

CourtRegistry interface

// CourtRegistry maps a court id (e.g. "upc-ld-paris", "de-bgh") to its
// (country, regime) tuple, which drives non-working-day adjustment.
//
// Implementations:
//   - paliad: reads paliad.courts. Existing CourtService.CountryRegime
//     already does this lookup with a fallback to defaults.
//   - embedded/upc: in-memory map populated from the embedded JSON.
//     Carries every UPC LD + CFI + CoA, country-tagged.
type CourtRegistry interface {
    CountryRegime(courtID, defaultCountry, defaultRegime string) (country, regime string, err error)
}

// DefaultsForJurisdiction is the fallback used when CourtID is empty.
// Identical to the existing helper in internal/services. Pure function,
// no I/O — lives directly in pkg/litigationplanner.
func DefaultsForJurisdiction(jurisdiction *string) (country, regime string)

CalcRequest + CalcOptions

type CalcRequest struct {
    ProceedingCode string
    TriggerDate    time.Time
    Options        CalcOptions
}

// CalcOptions carries the optional knobs. Same shape as today's
// internal/services.CalcOptions — verbatim, no field rename.
type CalcOptions struct {
    PriorityDate     *time.Time
    Flags            []string
    AnchorOverrides  map[string]time.Time
    CourtID          string

    // Catalog hint — only paliad-side catalogs consume this.
    ProjectHint      ProjectHint

    // Event-driven branch (event_trigger_service callers)
    TriggerEventIDFilter *int64

    // Editor preview / sandbox
    RuleOverrides    []Rule

    // Per-card choices (t-paliad-265)
    PerCardAppellant map[string]string
    SkipRules        map[string]struct{}
    IncludeCCRFor    map[string]struct{}
    IncludeHidden    bool
}

Timeline (result)

// Timeline is the package's structured return. Aligns with paliad's
// internal/services.UIResponse field-for-field so paliad's HTTP
// handlers serve it directly with no shim.
type Timeline struct {
    ProceedingType       string         `json:"proceedingType"`
    ProceedingName       string         `json:"proceedingName"`
    ProceedingNameEN     string         `json:"proceedingNameEN,omitempty"`
    TriggerDate          string         `json:"triggerDate"`
    Entries              []TimelineEntry `json:"deadlines"`
    ContextualNote       string         `json:"contextualNote,omitempty"`
    ContextualNoteEN     string         `json:"contextualNoteEN,omitempty"`
    TriggerEventLabel    string         `json:"triggerEventLabel,omitempty"`
    TriggerEventLabelEN  string         `json:"triggerEventLabelEN,omitempty"`
    HiddenCount          int            `json:"hiddenCount"`
}

// TimelineEntry == paliad's UIDeadline. Same JSON tags.
type TimelineEntry struct { /* identical to current UIDeadline */ }

The package emits Timeline; paliad's handler aliases Timeline → UIResponse and TimelineEntry → UIDeadline (type aliases keep call-sites byte-identical):

// internal/services/fristenrechner.go (post-Slice-A, ~60 lines)
type (
    UIResponse = litigationplanner.Timeline
    UIDeadline = litigationplanner.TimelineEntry
    CalcOptions = litigationplanner.CalcOptions
    AdjustmentReason = litigationplanner.AdjustmentReason
)

func (s *FristenrechnerService) Calculate(ctx context.Context, code, dateStr string, opts CalcOptions) (*UIResponse, error) {
    td, err := time.Parse("2006-01-02", dateStr)
    if err != nil { return nil, fmt.Errorf("invalid trigger date %q: %w", dateStr, err) }
    return litigationplanner.Calculate(ctx, litigationplanner.CalcRequest{
        ProceedingCode: code, TriggerDate: td, Options: opts,
    }, s.catalog, s.holidays, s.courts)
}

paliad's handlers, projection_service, event_deadline_service all call FristenrechnerService.Calculate(...) exactly as today.

---

§4 Catalog interface — embedded snapshot design (Q3.A.1)

Snapshot generation

pkg/litigationplanner/scripts/snapshot/main.go is run inside paliad's repo against paliad's DB (it's a paliad-side generator, paliad-only $DATABASE_URL requirement). It:

1. Connects to $DATABASE_URL (paliad's Postgres).
2. Reads paliad.proceeding_types filtered to is_active=true AND category='fristenrechner' AND jurisdiction IN ('UPC'). (One generator-level flag selects the jurisdiction subset; today only UPC is exported. Future generator runs can produce embedded/de/ or embedded/epa/.)
3. For each proceeding, reads paliad.deadline_rules filtered to proceeding_type_id IN (...) AND is_active=true AND lifecycle_state='published' AND project_id IS NULL. (project_id filter ensures user-authored rules from Slice E don't leak into the snapshot.)
4. Reads paliad.holidays for the past 5 + next 10 years (configurable), filtered to entries that apply to a UPC court (regime='UPC' OR country IN ('DE','FR','NL','IT')).
5. Reads paliad.courts for the UPC subset (regime='UPC').
6. Writes embedded/upc/catalog.json + embedded/upc/holidays.json + embedded/upc/courts.json + embedded/upc/VERSION (= current paliad git tag, e.g. v0.42.0).
7. Re-renders the snapshot test's golden fixtures (or fails if the snapshot diverges from the live calc in an unexpected way — the test compute-loop guards against silent corruption).
8. Exits non-zero on any DB integrity check failure (orphan rules, dangling FKs, etc.).

# Regenerate the UPC snapshot.
DATABASE_URL=$PALIAD_DB go run ./pkg/litigationplanner/scripts/snapshot \
    --jurisdiction=UPC \
    --output=./pkg/litigationplanner/embedded/upc \
    --tag=$(git describe --tags --always)
go test ./pkg/litigationplanner/embedded/upc/...

Snapshot consumer (youpc.org)

youpc.org imports the snapshot once at boot:

import (
    lp "mgit.msbls.de/m/paliad/pkg/litigationplanner"
    upc "mgit.msbls.de/m/paliad/pkg/litigationplanner/embedded/upc"
)

var (
    catalog  lp.Catalog          = upc.NewCatalog()
    holidays lp.HolidayCalendar  = upc.NewHolidayCalendar()
    courts   lp.CourtRegistry    = upc.NewCourtRegistry()
)

func handleFristenrechner(w http.ResponseWriter, r *http.Request) {
    code := r.URL.Query().Get("proceeding")
    dateStr := r.URL.Query().Get("trigger_date")
    td, _ := time.Parse("2006-01-02", dateStr)
    timeline, err := lp.Calculate(r.Context(), lp.CalcRequest{
        ProceedingCode: code,
        TriggerDate:    td,
        // No project hint (youpc has no projects), no flags by default.
    }, catalog, holidays, courts)
    // ... render JSON ...
}

The snapshot constructors are zero-arg, the in-memory maps populate on first call (sync.Once), and the binary footprint of the embedded JSON is small (77 rules × ~1KB per rule + ~5KB courts + ~25KB holidays ≈ 110KB total).

Why the JSON shape mirrors the schema

The snapshot stores rows in close to their DB shape (snake_case JSON tags, same field names) so a future schema addition (a new column on paliad.deadline_rules) is a one-line update: add the field to Rule, regenerate the snapshot, ship a minor-version bump. The package itself never needs to know what the columns ARE — it just consumes the Rule struct.

What the snapshot does NOT include

• paliad.deadline_concepts (rule grouping for cascade) — not needed for compute. The cascade UI is paliad-only.
• paliad.event_categories (Determinator B1 taxonomy) — paliad-only UI.
• paliad.event_types (concept default event-type hydration) — not needed for compute. youpc rendering can re-derive from rule metadata.
• paliad.trigger_events (event-driven branch) — out of scope for v1 youpc; if needed later, generator gains a --with-events flag.
• All paliad-state tables (projects, deadlines, project_event_choices, audit log, …).

---

§5 Scenarios design (m's picks — REVISED 2026-05-26)

m's framing (verbatim)

Where we can add proceeding types or specific submissions and then get the whole sequence with options for the steps so we can create scenarios etc as well. […] users should not add their own rules. I want them to setup a scenario with different existing proceeding types / submissions that trigger sequences.

A scenario is a named composition built from existing proceedings, existing submissions, existing flags, and anchor dates. It is not authored corpus — every rule it references is already in paliad.deadline_rules. The scenario glues them together with the user's choices + dates and produces a complete timeline.

Recommended design — paliad.scenarios table with jsonb spec

Schema

-- Slice D migration (paliad-side, NOT in pkg/litigationplanner).
CREATE TABLE paliad.scenarios (
    id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    project_id      uuid NULL REFERENCES paliad.projects(id) ON DELETE CASCADE,
    -- project_id NULL = abstract scenario (saved Verfahrensablauf template).
    -- project_id NOT NULL = attached to an Akte (the common case).
    name            text NOT NULL,
    description     text NULL,
    spec            jsonb NOT NULL,
    -- spec carries the full composition; see §5.1.
    created_by      uuid NULL REFERENCES paliad.users(id) ON DELETE SET NULL,
    created_at      timestamptz NOT NULL DEFAULT now(),
    updated_at      timestamptz NOT NULL DEFAULT now(),
    -- Within a single project, names are unique. Abstract scenarios are
    -- unique per (created_by, name) so two users can each have a "with_ccr"
    -- saved template without colliding.
    CONSTRAINT scenarios_unique_per_scope UNIQUE NULLS NOT DISTINCT
        (project_id, created_by, name)
);

CREATE INDEX scenarios_project_id_idx ON paliad.scenarios(project_id);
CREATE INDEX scenarios_abstract_user_idx
    ON paliad.scenarios(created_by) WHERE project_id IS NULL;

-- Active scenario per project. NULL = use today's ad-hoc choice state
-- (paliad.project_event_choices) — pre-scenario behaviour preserved.
ALTER TABLE paliad.projects
  ADD COLUMN active_scenario_id uuid NULL
    REFERENCES paliad.scenarios(id) ON DELETE SET NULL;

-- RLS: project-scoped scenarios inherit team visibility via
-- paliad.can_see_project(project_id). Abstract scenarios are
-- created_by-owner-only (private) for v1; later we can add a shared flag.

paliad.project_event_choices is NOT modified by this design. It continues to store the un-named "current" choice state for back-compat; once a project switches to a saved scenario, the engine reads from scenarios.spec instead.

Spec shape (jsonb)

Architected for multi-proceeding compose from day 1 — v1 ships with N=1 entries under proceedings[]; v2 lifts to N=peer.

{
  "version": 1,
  "base_trigger_date": "2026-05-26",
  "proceedings": [
    {
      "code": "upc.inf.cfi",
      "role": "primary",
      "flags": ["with_ccr", "with_amend"],
      "per_card_choices": {
        "inf.r30_amend": {"appellant": "claimant"},
        "inf.rejoin": {"include_ccr": true}
      },
      "anchor_overrides": {
        "inf.reply": "2026-08-15",
        "inf.urteil": "2027-02-01"
      },
      "skip_rules": ["inf.r30_amend_response"]
    }
    // v2 (future): additional peer proceeding entries here, each with
    // its own trigger_date override + flags + choices + anchors.
  ]
}

Field semantics:

• version — schema version of the spec format. v1. Bumped when the spec shape changes incompatibly.
• base_trigger_date — the case's anchor date (e.g. when the Klage was filed). Every proceeding without its own trigger_date_override uses this.
• proceedings[] — array of proceeding entries:
  • code — proceeding type code (e.g. upc.inf.cfi).
  • role — "primary" (the main proceeding) or "peer" (v2 extension; ignored in v1).
  • trigger_date_override — optional ISO date, defaults to base_trigger_date. v1 uses the base; v2 enables per-proceeding offsets.
  • flags[] — array of flag strings (with_ccr, with_amend, with_cci).
  • per_card_choices — map of submission_code → {appellant?, include_ccr?, …} (today's PerCardAppellant + IncludeCCRFor merged into one shape).
  • anchor_overrides — map of submission_code → ISO date (today's AnchorOverrides — court-extended deadlines, court-set decision dates known retroactively).
  • skip_rules[] — array of submission_codes the user has opted out of (today's SkipRules).

Cross-proceeding spawns (the existing is_spawn graph — AMD / APP / CCR spawned from primary INF) are handled automatically by the engine inside the primary entry — the user does not list spawn outcomes in the spec; the engine expands them via expandCrossProceedingSpawns. The spec only carries primary picks + (later) peer picks.

Why jsonb spec

• Multi-proceeding-ready from day 1. v1 has 1 entry in proceedings[]; v2 has N. No schema migration needed for the lift.
• Absorbs future per-card-choice keys without ALTER TABLE. The choices vocabulary (appellant, include_ccr, …) is already extension-friendly inside the calculator; the spec inherits that.
• Single round-trip to load a scenario — no joins.
• Validatable at write time — a JSON-schema check in the service layer asserts every code resolves to an active proceeding, every submission_code resolves to a rule, every flag is known. Bad scenarios cannot be saved; the user gets a clear error.

Engine integration

paliad's FristenrechnerService.Calculate is unchanged. The new code path is the request builder: when a project has active_scenario_id non-NULL, paliad reads the scenario's spec, builds CalcOptions from the primary proceeding entry, and calls Calculate(ctx, primary.code, scenario.base_trigger_date, opts). The package gets the same CalcOptions shape it's always gotten.

v2 multi-peer expansion: iterate proceedings[], call Calculate per entry, merge results client-side in ProjectionService.For (paliad-side). Still no library API change.

Endpoints

• GET /api/projects/{id}/scenarios — list project's scenarios + active.
• GET /api/scenarios?abstract=true — list current user's abstract scenarios.
• POST /api/projects/{id}/scenarios — create scoped scenario (body: name, spec).
• POST /api/scenarios — create abstract scenario (body: name, spec).
• PATCH /api/scenarios/{id} — rename / edit spec.
• PUT /api/projects/{id}/active-scenario — set active (body: scenario_id, or null to clear).
• DELETE /api/scenarios/{id} — remove (also clears any project.active_scenario_id pointing at it).
• POST /api/scenarios/{id}/clone — copy with new name. Supports cloning abstract → project-scoped and vice versa (the clone source gets project_id re-targeted).

UI surfaces

Project page (Akte-mode):

• "Szenarien" chip group above SmartTimeline: [Aktuell] [mit CCR] [+ Neu].
• "Aktuell" = the live project_event_choices state (no active scenario).
• Click chip → set as active → SmartTimeline + Akte-Fristenrechner re-render.
• "+ Neu" modal: name + base (Leer / vom aktuellen Stand / abstrakte Vorlage importieren).
• Per-scenario "Bearbeiten" affordance opens the same per-card choice surface filtered to that scenario's spec.

/tools/verfahrensablauf (abstract):

• Existing variant chips + per-card choices continue to drive a "live" abstract scenario carried in URL state.
• New "Speichern als Vorlage" button → modal: name → POST /api/scenarios (project_id=NULL).
• Sidebar list "Meine Vorlagen" lets the user reload a saved abstract scenario into the URL state.
• Existing share-via-URL stays — abstract scenarios are also shareable URLs; saving is opt-in for stickiness.

Library-side neutrality

The package never sees the scenario. paliad's request builder unpacks the spec and calls Calculate with vanilla CalcOptions. youpc.org doesn't need scenarios at all (it stays on URL state). The scenarios feature is 100% paliad-side; the package stays clean.

What the spec is NOT

• Not a place to inject user-authored rules. m's clarification: "users should not add their own rules." The spec references existing rules by submission_code; it cannot create new ones.
• Not a place to add user-authored proceeding types. Same logic — the code field must resolve to an existing active paliad.proceeding_types row.
• Not a SmartTimeline event store. SmartTimeline reads actuals from paliad.deadlines / appointments / project_events as today; scenarios only influence the projected future.

Multi-proceeding peer compose — v2 path (m's "goal")

m: "Usually it would be 1 — but 2 is the goal. So people can create more complex scenarios."

v2 lifts the engine to multi-peer:

1. Frontend: the "+ Verfahren hinzufügen" button on the scenario editor adds a new entry to proceedings[] with role: "peer", picks a proceeding code, optionally sets a trigger_date_override.
2. Backend: ProjectionService.For (or the request builder) iterates proceedings[], calls Calculate per entry, tags each timeline event with its origin proceeding (new Origin field on TimelineEntry), and merges + sorts by date.
3. SmartTimeline renders peers as parallel lanes (reuses the existing lane infrastructure from t-paliad-175 Slice 4 — LaneInfo already supports parallel tracks).
4. No package change — the package processes one proceeding per call as today; multi-peer is a paliad-side orchestration.

v2 is OUT OF SCOPE for v1 implementation but IN SCOPE for the spec/storage design. v1 silently ignores any proceedings[] entry with role: "peer"; v2 honours them.

---

§6 User-authored rules design — REMOVED by m's 2026-05-26 decision

m's clarification: "users should not add their own rules. I want them to setup a scenario with different existing proceeding types / submissions that trigger sequences."

The original Q2 (a) per-project rule additions via paliad.deadline_rules.project_id is dropped. No project_id column lands on paliad.deadline_rules. The corpus stays admin-curated (Slice 11 rule editor) — users compose, they don't author. §5 above replaces this design pillar: the scenario spec is the user's expression surface.

The original §6 body is preserved below as historical context (struck-through) for future readers who want to understand what was considered and why it was rejected.

---

### m's framing

we can add proceeding types or specific submissions and then get the whole sequence with options for the steps

Two scopes hidden in one sentence:

(a) Per-project rule additions — "on this specific case, we filed an unusual motion X with deadline Y for response". Common enough that a lawyer wants to type it once and have it ride the timeline.

(b) New proceeding TYPES — entirely new flows (e.g. Spanish patent litigation, Australian Federal Court). Much bigger surface; would need an editor for proceeding-type metadata too.

Recommended (R) — (a) for v1, defer (b)

Schema

-- Slice E migration (paliad-side).
ALTER TABLE paliad.deadline_rules
  ADD COLUMN project_id uuid NULL REFERENCES paliad.projects(id) ON DELETE CASCADE;

CREATE INDEX deadline_rules_project_id_idx
  ON paliad.deadline_rules(project_id, proceeding_type_id, sequence_order)
  WHERE project_id IS NOT NULL;

-- Existing rules (231 rows) all have project_id IS NULL → global.
-- New project-scoped rules have project_id NOT NULL.
-- Pre-existing UNIQUE constraints on (proceeding_type_id, submission_code)
-- continue to apply because they don't include project_id; we add a
-- supplementary constraint that allows project-scoped rules to use any
-- submission_code namespace independent of global rules:
ALTER TABLE paliad.deadline_rules
  DROP CONSTRAINT IF EXISTS deadline_rules_unique_proceeding_submission;
ALTER TABLE paliad.deadline_rules
  ADD CONSTRAINT deadline_rules_unique_proceeding_submission
    UNIQUE NULLS NOT DISTINCT (proceeding_type_id, submission_code, project_id);

Catalog merge

paliad's DeadlineRuleService.List learns the project hint:

func (s *DeadlineRuleService) ListForProceeding(ctx context.Context, ptID int, hint litigationplanner.ProjectHint) ([]models.DeadlineRule, error) {
    if hint.ProjectID == uuid.Nil {
        // Knowledge-tool / abstract surface: global rules only.
        return s.list(ctx, ptID, nil)
    }
    // Per-project surface (SmartTimeline + Akte-mode Fristenrechner):
    // global rules + this project's scoped rules, merged on sequence_order.
    return s.list(ctx, ptID, &hint.ProjectID)
}

The merge ordering uses sequence_order — project-scoped rules pick their own slot via the rule-editor UI. Parent-child chains across the boundary work (a project-scoped rule can have parent_id pointing at a global rule, but not vice-versa — DB CHECK enforces).

Rule-editor UI

Slice 11 of t-paliad-181 (the admin rule editor, partially shipped) is the natural anchor. Extend it with:

• A "Add project-scoped rule" affordance on the project page: opens the same editor scoped to ?project=<id> → writes with project_id set + created_by = current user.
• Visibility: project-scoped rules show with a "Akte-spezifisch" badge in admin views; non-admin users only see them on the project they belong to.
• Reuses the rule editor's lifecycle (draft → published → archived) so users can iterate.

Why (a) for v1, not (b)

• (a) adds ONE column. (b) would need user-authored proceeding_types (5 new columns), code-namespace coordination, fristenrechner-vs-archived category routing, and the cascade taxonomy (event_categories) backfilling for the new type. Much bigger.
• m's strong-signal use case is "filed an unusual motion" — that's (a), not (b).
• (b) can be added on top of (a) when the demand surfaces (e.g. a Spanish jurisdiction expansion). No design dead-end.

Library-side neutrality

The package's Catalog.Proceeding(ctx, code, hint) signature already passes ProjectHint. paliad's catalog respects it; youpc's catalog ignores it. No package change beyond making the hint field exist (which Slice B does as part of the interface).

User-authored rules NEVER leak to youpc.org

The snapshot generator filters on project_id IS NULL (§4). Per-project rules are paliad-owned business data; youpc.org gets the public-knowledge UPC subset only.

Escalation to head (Q2)

The package design works for any of (a) / (a)+(b) / (c) defer. Recommendation = (a). If m wants (b) in scope, we add a Slice E2 for user-authored proceeding types — but I'd argue defer until a real demand surfaces.

---

§7 youpc.org integration plan

Repo split discipline

• paliad repo (m/paliad) — owns the package, owns the generator, owns the snapshot. Every paliad release tag is a snapshot vintage.
• youpc repo (m/youpc.org) — owns the youpc-side UI, imports the package via Go module.
• No cross-repo coupling at runtime. youpc.org talks to its own DB; never reaches into paliad's DB.

Import path

import (
    lp "mgit.msbls.de/m/paliad/pkg/litigationplanner"
    upc "mgit.msbls.de/m/paliad/pkg/litigationplanner/embedded/upc"
)

youpc's go.mod pins a specific paliad version:

require mgit.msbls.de/m/paliad v0.42.0

Updates are explicit — go get -u mgit.msbls.de/m/paliad@v0.43.0 is the only way to pick up new rules.

UPC-only restriction

The restriction is structural: youpc imports embedded/upc and only embedded/upc. The catalog only knows about UPC proceeding codes; asking for de.inf.lg returns ErrUnknownProceedingType. The restriction isn't an enforcement flag in the engine; it's a property of the snapshot binding.

If youpc.org ever needs EPA, a separate embedded/epa ships and youpc imports it explicitly. Two snapshots, two imports, two surface scopes.

UX on youpc.org

Scope:

• A new public route, e.g. /laws/upc/fristenrechner, that renders the same Fristenrechner UX (variant chips + flat result list + per-card choices).
• A new public route, e.g. /laws/upc/verfahrensablauf, that renders the abstract Verfahrensablauf (compare two timelines side-by-side, variant chips).

Both routes share the package's Calculate entry; only the chrome differs. youpc.org's existing visual language drives the rendering — design lift from paliad/frontend is OUT OF SCOPE for this design (covered by a separate task on the youpc repo, Slice F).

Persistence

youpc.org doesn't persist anything related to the planner — no projects, no scenarios, no user-authored rules. URL state IS the state. This matches the existing youpc model where /laws is a knowledge surface, not a workspace.

Auth

The Catalog API is anonymous. youpc.org can put the route behind a login if it wants (premium-beta gate, etc.), but the package itself doesn't gate.

Telemetry

youpc.org can wrap lp.Calculate in its own telemetry shim. The package doesn't emit telemetry directly — keeps the dependency chain clean.

---

§8 Migration plan (Q4: atomic move)

Why atomic, not duplicate-then-DRY

The current internal/services/fristenrechner.go body IS the package's reason to exist. Duplicating its logic into pkg/litigationplanner while leaving the original in place creates two compute paths that will drift the moment a Wave 3 rule shape lands. The risk of drift outweighs the risk of a single bigger PR.

Slice A is atomic. After Slice A:

• pkg/litigationplanner/*.go — full body, exported.
• internal/services/fristenrechner.go — ~60 lines, the shell.
• internal/services/deadline_calculator.go — ~30 lines, the shell (or deleted entirely once DeadlineCalculator is just litigationplanner.Calculator).
• internal/services/event_deadline_service.go — uses litigationplanner.Calculate(...) with TriggerEventIDFilter set.
• All tests still pass.

File-move map (Slice A, illustrative — coder will adjust)

From	To	Notes
internal/services/deadline_calculator.go	pkg/litigationplanner/durations.go	Plus addWorkingDays + applyDuration from fristenrechner.go.
internal/services/fristenrechner.go Calculate body (lines 270–780)	pkg/litigationplanner/engine.go	Renamed litigationplanner.Calculate.
internal/services/fristenrechner.go CalculateRule body	pkg/litigationplanner/engine.go	Renamed litigationplanner.CalculateRule.
internal/services/fristenrechner.go evalConditionExpr	pkg/litigationplanner/expr.go	Already pure.
internal/services/proceeding_mapping.go (entirety)	pkg/litigationplanner/proceeding_mapping.go	Pure.
internal/services/proceeding_mapping.go SubTrackRoutings	pkg/litigationplanner/subtrack.go	Pure registry.
internal/services/deadline_search_service.go FormatLegalSourceDisplay + BuildLegalSourceURL	pkg/litigationplanner/legal_source.go	Both pure.
internal/services/fristenrechner.go UIResponse, UIDeadline, CalcOptions, CalcRuleParams, AdjustmentReason	pkg/litigationplanner/types.go	Renamed Timeline / TimelineEntry / CalcOptions / RuleCalcParams / AdjustmentReason. paliad keeps type aliases for back-compat.
internal/services/holidays.go HolidayService	(stays, becomes Catalog impl)	Plus the package gets the interface.
internal/services/courts.go CourtService	(stays, becomes Catalog impl)	Same.
internal/services/deadline_rule_service.go DeadlineRuleService	(stays, becomes Catalog impl)	Same.

Test discipline

• All current tests under internal/services/fristenrechner_test.go, deadline_calculator_test.go, projection_service_test.go, event_deadline_service_test.go continue to run unchanged in paliad — they test the paliad-side wrappers which delegate to the package.
• The package gets its own pkg/litigationplanner/*_test.go with fixture-driven tests: input JSON → expected output JSON, covering every rule shape (composite, alt-swap, anchor-override, sub-track, condition_expr, court-set indirect, choice-skip, choice-include-CCR, …).
• pkg/litigationplanner/embedded/upc/snapshot_test.go is a golden test: run the engine against the snapshot for every (proceeding, trigger_date) fixture, assert byte-equality with the expected output. This is the regression net for the snapshot generator.

Rollback

Slice A is one PR. Revert = revert. Once Slice C lands and youpc.org takes a dep on the snapshot (Slice F), revert means coordinating the youpc.org module pin — but that's a normal multi-repo coordination, not a one-way door.

Slice ordering hard constraints

• A blocks B: B introduces the Catalog interface; A must put types into the package first.
• B blocks C: C populates the snapshot via the Catalog interface.
• D + E are independent of A-C but should land after at least Slice B so paliad's catalog is the merge point.
• F (youpc) blocks on C at minimum. Ideally also on D + E so the snapshot is stable.

---

§9 Versioning + release process (Q5)

Semver discipline on the package

• v0.x.y — pre-1.0. The package is intentionally below the 1.0 stability bar until paliad-internal + youpc-internal usage is settled (probably 2-3 months of co-existence).
• v1.0.0 — declare API frozen; new fields are additive only; removals require a major bump.

What counts as a breaking change?

• Rename a public function / type / field → breaking.
• Change the JSON tags of Rule / ProceedingType / Timeline → breaking (the snapshot file shape changes too).
• Change the meaning of a function (e.g. CountryRegime now returns an error on unknown court) → breaking.
• Drop a Catalog / HolidayCalendar / CourtRegistry method → breaking.

What is additive (non-breaking)?

• Add a new field to Rule / Timeline / CalcOptions → additive (struct fields are open).
• Add a new constant / helper / sub-package → additive.
• Add a new optional field on CalcRequest → additive if zero-value is back-compat.
• Add a new entry to SubTrackRoutings → additive (data, not API).
• Add a new proceeding type to the snapshot → additive (data).
• Add new rules to existing proceeding types in the snapshot → additive (data).

Snapshot versioning vs API versioning

Two clocks:

• API version — bumped on package API change. Lives in pkg/litigationplanner/doc.go (const Version = "...").
• Snapshot vintage — bumped on every regeneration. Lives in pkg/litigationplanner/embedded/upc/VERSION (auto-set to the paliad git tag at generator time).

A breaking schema addition (e.g. a new column on paliad.deadline_rules that the snapshot ships) is API-version-additive (struct gains a field) but snapshot-vintage-bumping. youpc.org sees it on its next go get -u.

A deletion of a column (rare) is API-version-breaking — requires a major bump.

Release flow

1. paliad merge to main bumps the package version when it touches pkg/litigationplanner/.
2. Snapshot regeneration is triggered MANUALLY by the operator after material rule changes (rule editor Slice 11b, batch migrations, etc.). Process: go run ./pkg/litigationplanner/scripts/snapshot → review diff → commit → tag → push.
3. youpc.org's CI runs go get -u weekly (or on-demand) and opens a PR with the new dep version. Human reviews + merges.

Drift detection

A test on paliad's side compares the snapshot at HEAD against the live DB and fails if the rule set has diverged without a snapshot bump:

# pkg/litigationplanner/scripts/snapshot/check.sh — runs in paliad CI
DATABASE_URL=$PALIAD_DB go run ./pkg/litigationplanner/scripts/snapshot \
    --jurisdiction=UPC --dry-run --diff-against=./pkg/litigationplanner/embedded/upc

If the diff is non-empty, the build fails with "snapshot drift — regenerate after reviewing". This catches accidental forgetting; nothing prevents intentional drift.

Why semver, not date-stamped versions

Go modules need semver. v0.42.0 slots into require; v2026-05-26 doesn't. The snapshot VERSION file can carry both (semver + date) for human readability.

---

§10 Slice plan

Each slice is independently shippable on the paliad side. Slice F is a separate PR on the youpc.org repo.

Slice A — extract calc + types into pkg/litigationplanner (no behaviour change)

Scope — paliad-side extraction. Move:

• Rule / ProceedingType / Court / Holiday types into pkg/litigationplanner/types.go.
• applyDuration, addWorkingDays, DeadlineCalculator body into pkg/litigationplanner/durations.go.
• evalConditionExpr + hasConditionExpr into pkg/litigationplanner/expr.go.
• MapLitigationToFristenrechner + code constants into pkg/litigationplanner/proceeding_mapping.go.
• SubTrackRoutings + LookupSubTrackRouting into pkg/litigationplanner/subtrack.go.
• FormatLegalSourceDisplay + BuildLegalSourceURL into pkg/litigationplanner/legal_source.go.
• DefaultsForJurisdiction into pkg/litigationplanner/courts.go.
• Calculate + CalculateRule bodies into pkg/litigationplanner/engine.go — using the Catalog / HolidayCalendar / CourtRegistry interfaces.
• Type aliases in internal/services/fristenrechner.go so call-sites continue to import services.UIResponse etc.

Test discipline — all existing tests under internal/services/*_test.go continue to pass unchanged. Add package-side tests for the pure functions (which are mostly already there as table-driven tests; move them across).

Exit criteria:

• go build ./... clean.
• go test ./... green, no regressions.
• internal/services/fristenrechner.go is < 100 lines and consists of the type aliases + thin Calculate/CalculateRule shells.

~1700 LoC moved, ~60 LoC remaining on the paliad side.

Slice B — Catalog / HolidayCalendar / CourtRegistry interfaces + paliad's default loaders

Scope — define the three interfaces in the package; have paliad's existing DeadlineRuleService, HolidayService, CourtService implement them with shim methods. Slice A already calls Calculate against the interfaces, so this is purely about wiring the production paths.

Files:

• pkg/litigationplanner/catalog.go — Catalog + ProjectHint.
• pkg/litigationplanner/holidays.go — HolidayCalendar.
• pkg/litigationplanner/courts.go — CourtRegistry.
• internal/services/deadline_rule_service.go — add Proceeding(ctx, code, hint) method satisfying Catalog.
• internal/services/holidays.go — already has IsNonWorkingDay / AdjustForNonWorkingDays; add AdjustForNonWorkingDaysBackward shim if not exposed.
• internal/services/courts.go — CountryRegime already exists, satisfies CourtRegistry.

Exit criteria: paliad's wire-up uses the interfaces; no behaviour change.

Slice C — embedded UPC snapshot + generator script

Scope — write the generator + emit the first snapshot + the snapshot consumer.

Files:

• pkg/litigationplanner/scripts/snapshot/main.go — generator (CLI binary).
• pkg/litigationplanner/scripts/snapshot/README.md — operator runbook.
• pkg/litigationplanner/embedded/upc/catalog.go + .json + holidays.go + .json + courts.go + .json + VERSION.
• pkg/litigationplanner/embedded/upc/snapshot_test.go — golden tests.

Exit criteria:

• go run ./pkg/litigationplanner/scripts/snapshot --jurisdiction=UPC emits a non-empty snapshot.
• lp.Calculate(ctx, req, upc.NewCatalog(), upc.NewHolidayCalendar(), upc.NewCourtRegistry()) returns the same Timeline for every fixture as the paliad-side Catalog does.
• A snapshot-drift test fails on intentional drift to prove the detector works.

Slice D — scenarios persistence: per-project (REVISED per m's 2026-05-26 picks)

Scope — paliad.scenarios table + jsonb spec + project-page UI.

Files:

• internal/db/migrations/134_scenarios.up.sql + .down.sql — create paliad.scenarios (project_id, name, spec jsonb, created_by, …) + paliad.projects.active_scenario_id FK + RLS via paliad.can_see_project.
• internal/services/scenario_service.go (new) — Create/List/Get/Patch/Clone/SetActive/Delete + JSON-schema validation of spec (every code/submission resolves; flags known).
• internal/handlers/scenarios.go (new) — wire the REST endpoints from §5.
• internal/services/projection_service.go — when project.active_scenario_id is set, build CalcOptions from the scenario's spec.primary entry instead of paliad.project_event_choices.
• internal/services/event_choice_service.go — unchanged (still owns the un-named "current" state); a TODO comment notes the v2 collapse if scenarios fully replace ad-hoc choices.
• frontend/src/components/ScenarioChips.tsx (new) + frontend/src/client/projects-detail.ts — chip group + create/edit modal + active switch.
• frontend/src/components/ScenarioEditor.tsx (new) — per-card choices + flags + anchor-overrides editor scoped to the scenario.

Exit criteria:

• Project page renders scenario chips; create/switch/delete works.
• SmartTimeline + Akte-Fristenrechner respect the active scenario.
• "Aktuell" (no active scenario) preserves today's behaviour reading from project_event_choices.
• Per-card choice editor writes into the scenario's spec.anchor_overrides / per_card_choices / skip_rules / flags.

Slice E — abstract scenarios on /tools/verfahrensablauf (NEW, replaces ex-Slice E)

Scope — abstract scenarios surface; reuses the same paliad.scenarios table with project_id IS NULL.

Files:

• internal/services/scenario_service.go — Slice D code already supports abstract scenarios; Slice E adds the created_by-scoped list endpoint + the clone-abstract-to-project / clone-project-to-abstract flows.
• internal/handlers/scenarios.go — extend with ?abstract=true filter on List.
• frontend/src/verfahrensablauf.tsx + client/verfahrensablauf.ts — "Speichern als Vorlage" button + sidebar list "Meine Vorlagen" + load-saved-template → URL state.

Exit criteria:

• /tools/verfahrensablauf gains save + list-my-templates affordances.
• A saved abstract scenario reloaded into URL state reproduces the live timeline byte-identically.
• Project page "+ Neu" modal supports "abstrakte Vorlage importieren" — copies the abstract scenario into the project's scope.

v2 — multi-proceeding peer compose (DEFERRED, no slice in this design)

m's "goal": "2 is the goal. So people can create more complex scenarios." The spec already carries proceedings[] as an array; v2 lifts the engine + UI to honour role: "peer" entries. Out of scope for v1 — but the design holds because the schema doesn't need migration to support it.

Slice F — youpc.org integration (separate repo)

Scope — youpc-side import + UI + routes. This is a youpc repo PR; out-of-scope for this paliad task. Document the integration contract here so the youpc-side worker has a clean handover.

Contract:

• go get mgit.msbls.de/m/paliad@<tag> in youpc.org.
• Boot-time wire: catalog = upc.NewCatalog() (sync.Once-protected init).
• One handler per knowledge surface (Fristenrechner, Verfahrensablauf). Each calls lp.Calculate(...).
• UX lift from paliad's frontend out of scope of the package; youpc.org's design system drives the UI.
• youpc's CI sets up a weekly Renovate-style PR for paliad version bumps.

Out of scope of this design — youpc's UX, youpc's auth gate, youpc's analytics, youpc's i18n. Those belong to a sibling task on the youpc.org repo.

Slice ordering (revised)

A → B → C → F (youpc integration on C)
            ↘
       D → E (paliad-only; E builds on D's table + schema)

A is the prerequisite for everything. B is the prerequisite for C and D. C is the prerequisite for F. D + E are sequential (E reuses D's table) but can ship as one PR if a worker prefers.

Old "Slice E user-authored rules" is dropped per m's 2026-05-26 clarification (§6). New Slice E is the abstract scenarios surface on /tools/verfahrensablauf.

---

§11 Risk assessment + rollback

Risks

1. Slice A regression risk. Moving 1700 LoC across a package boundary while preserving behaviour is the biggest single-PR risk in this work. Mitigation: every existing test must keep passing; add a regression suite at the package boundary before moving anything; the type-alias bridge means call-sites need no edits.

2. Snapshot drift between paliad and youpc. A paliad-side rule change that the operator forgets to snapshot leaves youpc stale. Mitigation: snapshot-drift CI check (§9) fails the build on un-snapshotted drift. Operator regenerates manually; one-line command.

3. API churn during pre-1.0. Sub-1.0 means breaking changes are allowed, and youpc.org will pick them up on go get -u. Mitigation: every breaking change is called out in pkg/litigationplanner/CHANGELOG.md; youpc.org pins exact versions during pre-1.0.

4. Catalog merge ambiguity (Slice E). A project-scoped rule with the same submission_code as a global rule — does it override or coexist? Mitigation: the unique constraint (proceeding_type_id, submission_code, project_id) NULLS NOT DISTINCT allows ONE global + N project-scoped to coexist. The catalog returns both; the engine sees both rows. Ordering by sequence_order decides which renders first. Document this explicitly in the rule-editor UX (no silent override).

5. Scenarios spec validation drift. Per m's revised design (§5), the spec jsonb references proceeding_type.code + submission_code + flag strings — all of which can be renamed by future migrations. A scenario saved against upc.inf.cfi.inf.reply would silently break if the submission_code changes. Mitigation: validate-on-load (not just on-write): when paliad reads a scenario, the service resolves every code/submission against the current corpus and surfaces a "Vorlage benötigt Aktualisierung" banner if anything's gone stale. The user can edit + re-save against the current corpus; the old spec is preserved until they do.

6. youpc.org snapshot binary footprint. ~110KB embedded JSON in youpc's binary. Mitigation: trivial. Not a risk in practice.

7. Spawn cycle guard ownership. Today ProjectionService.expandCrossProceedingSpawns carries the visited-set + maxSpawnDepth cycle guard. After the move, the guard lives in the package (it's part of Calculate). Mitigation: lift the test fixtures along with the code; the cycle-guard test stays green by construction.

Rollback

• Slice A: revert the PR. paliad runs against the pre-move code; no DB change, no consumer impact.
• Slice B: revert the PR. Calls to interfaces fall back to direct calls on services.
• Slice C: revert the PR. paliad unaffected; youpc.org not yet integrated.
• Slice D: revert + run the down-migration. project_event_choices loses scenario_name, projects loses active_scenario; user data preserved (one row per choice).
• Slice E: revert + run the down-migration. Project-scoped rules become orphaned (column drop wipes them — coder should snapshot to a sidecar table before drop if any user has authored rules). Alternatively roll forward with bug fix.
• Slice F: youpc.org pins a previous paliad version. Trivial.

---

§12 Out of scope

• youpc.org UX, layout, design-system lift — separate task on the youpc repo (Slice F's content).
• Cross-firm rule sharing (one firm's user-authored rules visible to another firm). Defer until the firm-multitenancy story is real.
• Multi-jurisdiction snapshots (embedded/de/, embedded/epa/). The generator gains a --jurisdiction flag in Slice C; the additional snapshots are a follow-up task per jurisdiction when demand surfaces.
• Re-architecting ProjectionService to live in the package. It speaks Postgres directly to load project + counterclaim children + actuals, which IS paliad-specific business logic. Only its single Calculate(...) call crosses the boundary.
• Replacing the existing rule editor UX. Slice E extends it for project-scoped rules; no redesign.
• Live cross-repo CI integration (auto-PR on paliad release tagging youpc.org). Manual go get -u workflow for now; automation deferred.
• Anthropic/Paliadin AI integration with the planner (e.g. natural-language scenario creation). Out of scope.
• Frontend type generation from the package's Go types. The TS interfaces in frontend/src/types.ts already match the JSON shape; preserve manually until a generator is worth the effort.
• Snapshot signing / provenance attestation. youpc.org trusts paliad's release tag; cryptographic integrity is a follow-up.

---

§13 Open questions — RESOLVED 2026-05-26

Originally Q1 + Q2 were escalated via mai instruct head. m switched to AskUserQuestion-mode mid-session; answers folded into §0.5. Original Q1+Q2 framings preserved below as historical context.

Q1 — Scenarios storage model (material) — ANSWERED §0.5-Q4

m picked new paliad.scenarios table with jsonb spec (option B in the original framing). Original recommendation (column extension) was retracted in favour of jsonb spec because m's Q1-Q3 picks (multi-proceeding peer compose as goal, per-project + abstract scope) made the jsonb shape strictly better.

Q2 — User-authored rules scope (material) — REJECTED §0.5

m clarified: "users should not add their own rules." Original Slice E dropped. New Slice E = abstract scenarios surface on /tools/verfahrensablauf. Composition replaces authoring.

Q3 — Locked by m

Package-within-project. Embedded snapshot with generator. Recommendation honoured.

Q4 — Locked by inventor (matches brief default)

Atomic move from internal/services into pkg/litigationplanner. No m gate needed; head approves the engineering plan.

Q5 — Locked by inventor (matches brief default)

Semver discipline, additive-by-default API, snapshot-vintage separate from API version. No m gate needed; head approves.

Q6 — Snapshot regeneration cadence (tactical)

Manual operator command vs CI cron? Recommendation: manual during pre-1.0; revisit after 3 months of usage. Head decides.

Q7 — Snapshot drift policy on paliad CI (tactical)

Fail the build on un-snapshotted drift, or warn? Recommendation: warn during pre-1.0 so paliad-side rule edits don't block development; fail starting at v1.0. Head decides.

Q8 — Package version cadence (tactical)

Bump on every PR that touches pkg/litigationplanner/, or batch into milestone releases? Recommendation: bump on every PR, since semver is cheap and the operator burden is one line. Head decides.

Q9 — Rule-editor extension for Slice E (tactical, depends on Q2)

If Q2 = (a), where does the "Akte-spezifische Frist" affordance live in the project page? Recommendation: a small "+ Frist hinzufügen" button under the SmartTimeline header, opens the existing rule editor scoped to the project. Head decides (UX placement).

Q10 — youpc.org module pin strategy (tactical, advisory)

require mgit.msbls.de/m/paliad v0.x.y — exact, ^-ranged, or auto-updating? Recommendation: exact pin through pre-1.0; tilde-ranged at v1.x. Head decides + flags to the youpc-side worker.

Q11 — Snapshot-bound proceeding scope (tactical)

The brief says "youpc UPC-restricted". The 9 UPC proceeding types are explicit. But: should the snapshot also include epa.grant.exa (EP grant publication is UPC-relevant for priority-date math)? Recommendation: start with UPC only; if a UPC visitor's deadline depends on EPA rules, surface a stub error that points them at paliad.de. Head decides.

---

§14 m's decisions (placeholder — will be filled after head returns answers)

This section will be added when paliad/head relays m's answers to Q1, Q2, and any escalated tactical Qs. Per inventor protocol, the design doc gets an addendum here; the rest of the doc is the historical record.

For now, the inventor's picks (R) stand as proposed; the design holds together with any of the alternative pickings on Q1 / Q2 because the package shape is decoupled from the persistence choices.

---

§15 Recommended implementer

Slice A is the biggest mechanical lift; recommend a pattern-fluent Sonnet coder with deep paliad-go-services familiarity. Cronus (this inventor) has carried t-paliad-133, t-paliad-291, and the design context here, so a same-worker shift to coder mode is one of the head's options for Slice A.

Slices B + C + D + E are smaller and parallel-friendly. Different coders can pick them up after A lands.

Slice F is a youpc-side task; it needs a worker with youpc-go familiarity (a separate hire on the youpc.org project).

---

§16 Trade-offs flagged

• Atomic Slice A vs incremental — atomic carries one large-PR regression risk; incremental carries drift risk. Picked atomic. §8 justifies.
• Embedded snapshot vs read-replica access from youpc — snapshot wins on independence + offline use, loses on freshness. Picked snapshot. §4 justifies.
• scenario_name PK extension vs new scenarios table — column extension wins on simplicity + back-compat. Picked column. §5 justifies.
• Per-project rules nullable project_id vs separate table — nullable column wins on merge simplicity (one SELECT, two WHERE clauses). Picked nullable. §6 justifies.
• Type aliases (UIResponse = Timeline) vs full rename — aliases keep call-sites byte-identical; rename forces a separate noise-PR. Picked aliases. §3 justifies.
• Snapshot in package vs separate paliad-snapshots repo — in-package wins on simplicity; separate repo wins on release independence. Picked in-package per m's lock. §4 justifies.
• Public surface (UPC subset only) vs full multi-jurisdiction snapshot — UPC-only matches the brief; multi-jurisdiction is opt-in via generator flag. Compatible.

---

§17 Files of note for future workers

Anchor files (read these before touching anything):

• internal/services/fristenrechner.go (1505 LoC) — the body to extract. Slice A moves most of it.
• internal/services/deadline_calculator.go (175 LoC) — already library-shaped.
• internal/services/projection_service.go (2214 LoC) — STAYS in internal/services (paliad-specific). Slice A makes it import from the package.
• internal/services/deadline_rule_service.go (352 LoC) — Slice B turns this into a Catalog impl.
• internal/services/holidays.go (413 LoC) — Slice B turns this into a HolidayCalendar impl.
• internal/services/courts.go (~150 LoC) — Slice B turns this into a CourtRegistry impl.
• internal/services/proceeding_mapping.go (191 LoC) — Slice A moves it.
• internal/services/event_deadline_service.go — uses Calculate(... TriggerEventIDFilter ...). Slice A updates the import path.
• internal/services/rule_editor_service.go — Slice E extends with project_id writes.
• internal/services/event_choice_service.go — Slice D extends with scenario_name reads/writes.

Design doc cross-references:

• docs/audit-fristen-logic-2026-05-13.md (pauli, t-paliad-157) — the audit that justified the Phase 2 unification.
• docs/design-fristen-phase2-2026-05-15.md (pauli, t-paliad-181) — the unified rule model, partially / largely shipped.
• docs/design-smart-timeline-2026-05-08.md (lagrange, t-paliad-169) — ProjectionService design.
• docs/design-tools-cleanup-2026-05-12.md (kelvin, t-paliad-178) — Fristenrechner vs Verfahrensablauf split.
• docs/design-determinator-row-cascade-2026-05-13.md (pauli, t-paliad-166) — Determinator cascade — paliad-side UI, unaffected by this design.
• docs/design-event-card-choices-2026-05-25.md — per-card choice surface; the CalcOptions extension that this design preserves verbatim.

---

§18 Slice B — Catalog Interface + Unifications (2026-05-26)

Slice A landed atomically at d1d0cf9. Before Slice B's coder shift begins, three additional decisions m confirmed today need to be folded into the package design:

• §18.1 — Berufung unification. Collapse the 3 active UPC appeal proceeding_types (upc.apl.merits, upc.apl.cost, upc.apl.order) into ONE upc.apl proceeding type + an appeal_target discriminator.
• §18.2 — Multi-axis catalog query API. New Catalog.LookupEvents method taking any subset of {jurisdiction, proceeding_type_id, party, event_category_id} axes + a depth control (next / all-following).
• §18.3 — primary_party enum tightening. Convert the free-text paliad.deadline_rules.primary_party column to a CHECK constraint matching the four-value vocabulary claimant / defendant / court / both.

Each subsection follows the same shape: motivation → schema impact → API shape → acceptance criteria.

§18.0 Live state on main (audit summary)

Confirmed via Supabase before drafting (mai/cronus/inventor-litigation-slice-b branch off main):

• 9 active UPC proceeding_types: upc.inf.cfi (25 rules), upc.rev.cfi (17), upc.pi.cfi (7), upc.dmgs.cfi (8), upc.disc.cfi (4), upc.ccr.cfi (0 — sub-track), upc.apl.merits (7), upc.apl.cost (2), upc.apl.order (7).
• 3 appeal-flavoured proceeding_types = 16 rules across 3 codes. Schadensbemessung + Bucheinsicht are SEPARATE first-instance proceedings today (upc.dmgs.cfi, upc.disc.cfi), NOT appeal sub-tracks.
• paliad.deadline_rules.primary_party value distribution: claimant=26, defendant=26, court=38, both=63, NULL=78. The 78 NULL rows are ALL proceeding_type_id IS NULL orphans (cross-cutting concept seeds: Wiedereinsetzung, Versäumnisurteil-Einspruch, Schriftsatznachreichung, Weiterbehandlung — 8 distinct concepts × N rules). Every proceeding-bound rule already has a four-value primary_party.
• paliad.event_categories.party column shape: text[] (array). Live distinct values: {claimant}, {defendant}, NULL. No court or both in event_categories.party today. The semantic is "from whose perspective is this event triggered?" — narrower than primary_party which is "who files this submission".

§18.1 Berufung unification

Motivation

m's framing (2026-05-26 09:55, t-paliad-298 instructions): "the Verfahrensablauf event picker has 4-5 separate proceeding_types … plus Berufung Schadensbemessung and Berufung Bucheinsicht variants. m doesn't like the pre-separation. He wants ONE 'Berufung' entry in the picker, and the user then picks what the appeal is directed AT … the system derives the correct frist sequence from that target."

Today's 3 codes (upc.apl.merits, upc.apl.cost, upc.apl.order) are a leaky abstraction of "appeal" — the user has to know whether it's a merits/cost/order appeal BEFORE they enter the picker, even though that branching question is "what's being appealed?" not "what kind of appeal?". Schadensbemessung + Bucheinsicht aren't in the appeal taxonomy at all today; appeals against those decisions silently fall into upc.apl.merits, blurring the rule sequence (RoP.220 vs RoP.221 vs RoP.224 timing).

The five appeal-target kinds are:

Target	Source decision	Typical RoP track	Current proceeding code
Endentscheidung	Final merits decision (UPC.RoP.118.1 / 219)	2-month notice + 4-month grounds (R.224.1.a / R.224.2.a)	upc.apl.merits
Kostenentscheidung	Cost decision (R.150 / R.221.1)	15-day leave-to-appeal (R.221.1)	upc.apl.cost
Anordnung	Order during proceedings (R.220)	15-day track (R.220.2 / R.220.3 / R.224.2.b)	upc.apl.order
Schadensbemessung	Damages-determination decision (R.118.4 + R.140.2.b damages award)	Same merits track (2/4 month), but conceptually distinct anchor	(today maps to upc.apl.merits, silently)
Bucheinsicht	Lay-open-books decision (R.142)	15-day track (R.220.2 — order-flavoured) OR merits track depending on the underlying decision shape	(today maps to upc.apl.merits, silently)

Schema impact

Migration plan (single 134_berufung_unification.up.sql):

1. Add column paliad.proceeding_types.appeal_target text NULL — discriminator on the unified upc.apl row.
2. Add CHECK on appeal_target: NULL OR one of endentscheidung | kostenentscheidung | anordnung | schadensbemessung | bucheinsicht. Slugged in English-lowercase to match the package's English-identifier rule; the user-facing label is i18n'd in frontend.
3. Insert a new unified row upc.apl (name="Berufungsverfahren", name_en="Appeal", jurisdiction="UPC", category="fristenrechner", appeal_target=NULL).
4. Re-target rule rows by appeal_target:
   • Today's 7 upc.apl.merits rules → keep proceeding_type_id pointing at the new upc.apl row, set a NEW column on paliad.deadline_rules called applies_to_target text NULL (CHECK matching the five-value vocab) to 'endentscheidung'.
   • Today's 2 upc.apl.cost rules → applies_to_target='kostenentscheidung'.
   • Today's 7 upc.apl.order rules → applies_to_target='anordnung'.
   • The 7 merits rules ALSO carry the implicit "applies to Schadensbemessung" semantic (the merits track is shared) — explicit duplication or a multi-value applies_to_target array? See §18.1 "Open question" below.
5. Archive the 3 old proceeding_types — set category='archived', is_active=false. Keep the rows for FK integrity (project_event_choices, etc. may reference them historically; the archive flag stops them surfacing in the picker).
6. Add 5 stable proceeding-type alias rows OR just emit one chip per appeal_target in the frontend. Recommended (see API shape below): emit chips from the package's catalog, no DB row per target.

Two new columns added by this migration:

• paliad.proceeding_types.appeal_target text NULL (CHECK on 5 slugs OR NULL — NULL means "not an appeal").
• paliad.deadline_rules.applies_to_target text[] NULL (CHECK each element ∈ the 5 slugs — array because the merits track applies to BOTH endentscheidung AND schadensbemessung today).

Migration audit pass first: before running step 4 the migration should RAISE NOTICE for any rule row whose applies_to_target derivation is ambiguous (e.g. an old upc.apl.merits rule that has a condition_flag that doesn't fit any target). In practice the 16 rules all map cleanly, but the audit pattern matches Phase 2 Step E discipline (see docs/design-fristen-phase2-2026-05-15.md §3.E).

Down-migration: re-insert the 3 archived proceeding_types, restore proceeding_type_id on rules from the saved applies_to_target, drop the two new columns. Standard down-symmetry per docs/design-fristen-phase2-2026-05-15.md.

API shape

The package's existing Catalog.LoadProceeding(ctx, code, hint) already returns a ProceedingType + []Rule. The Berufung unification fits cleanly:

• LoadProceeding(ctx, "upc.apl", hint) returns the unified Berufung proceeding + ALL appeal rules across the 5 targets.
• A new optional field on the request narrows by target: extend CalcOptions with AppealTarget string. When non-empty, the engine filters the returned rule list to rules whose applies_to_target contains the requested target.
• The package exposes the 5 target slugs as constants:

const (
    AppealTargetEndentscheidung    = "endentscheidung"
    AppealTargetKostenentscheidung = "kostenentscheidung"
    AppealTargetAnordnung          = "anordnung"
    AppealTargetSchadensbemessung  = "schadensbemessung"
    AppealTargetBucheinsicht       = "bucheinsicht"
)

// AppealTargets is the canonical ordered list for UI chip rendering.
var AppealTargets = []string{
    AppealTargetEndentscheidung,
    AppealTargetKostenentscheidung,
    AppealTargetAnordnung,
    AppealTargetSchadensbemessung,
    AppealTargetBucheinsicht,
}

• ProceedingType gains a field: AppealTarget *string db:"appeal_target" json:"appealTarget,omitempty"`` (per-row tag for clarity; redundant with the unified row's code='upc.apl' but useful for non-appeal proceedings that may carry NULL).
• Rule gains a field: AppliesToTarget []string db:"applies_to_target" json:"appliesToTarget,omitempty"`` (per-row applies-to set).

Frontend logic:

• Verfahrensablauf picker shows one "Berufung" entry (the upc.apl proceeding).
• After picking Berufung, a chip group renders the 5 AppealTargets slugs (i18n labels in frontend/src/client/i18n.ts).
• Selecting a target sets ?target=<slug> query param → backend includes opts.AppealTarget=<slug> in the request → engine filters.

Acceptance criteria (Slice B sub-tasks for this fold-in)

1. Migration 134_berufung_unification.up.sql + paired .down.sql apply cleanly against a fresh paliad DB.
2. After migration, SELECT code FROM paliad.proceeding_types WHERE jurisdiction='UPC' AND is_active=true AND category='fristenrechner' returns one less row (the 3 old appeal codes collapsed to 1 new code).
3. Catalog.LoadProceeding(ctx, "upc.apl", hint) returns the merged 16-rule set; with opts.AppealTarget="endentscheidung" it returns exactly 7 rules.
4. Verfahrensablauf renders one "Berufung" picker entry. The 5 target chips render below it post-pick; switching chips re-renders the timeline.
5. Existing project rows that referenced the old upc.apl.merits / upc.apl.cost / upc.apl.order codes still load (the FK integrity is preserved via the archived old rows).
6. The paliad.proceeding_type_history follow-up (not in scope here) can later migrate those project FKs to the new upc.apl + appeal_target field — that's a follow-up.

Open question for m (escalate via mai instruct head)

Q18.1.1 — Is Schadensbemessung-as-appeal a duplicate of Endentscheidung, or a distinct set?

Three interpretations:

• A. Shared rule set: appeal of a Schadensbemessung uses the SAME rules as appeal of an Endentscheidung (both run the 2/4-month merits track). applies_to_target=['endentscheidung','schadensbemessung'] on each rule. (R) — simplest, matches what the live upc.apl.merits corpus does today (no explicit target distinction).
• B. Distinct rule set: Schadensbemessung-appeal has its own anchor + sequence (different trigger event, different timing). Would need 7 new rule rows specifically for applies_to_target=['schadensbemessung']. No live evidence for this today.
• C. Defer: ship Berufung unification with only 3 targets (endentscheidung / kostenentscheidung / anordnung) for v1; add Schadensbemessung + Bucheinsicht as a follow-up.

Recommendation: A — share rules, multi-valued applies_to_target array. Frontend renders all 5 chips from day 1; the merits 7 rules show under endentscheidung + schadensbemessung; the order 7 rules show under anordnung + bucheinsicht (the 15-day track DOES apply to Bucheinsicht under R.142+R.220.2). No new rule rows needed.

Q18.1.2 — User-facing label for "appeal_target": "Worauf richtet sich die Berufung?" (DE) / "Appeal against:" (EN)?

Recommendation: yes, those exact strings; defer i18n decisions to the coder shift.

§18.2 Multi-axis catalog query API

Motivation

The current Catalog interface (added in Slice A) supports proceeding-code lookups only. The new scenarios surface (Slice D) + the Determinator cascade (t-paliad-166) + a future "show me all next-step events when I'm in state X" need a generalised query that takes any subset of axes and returns matching events.

m's brief (2026-05-26 13:33): "any subset of these axes (all optional): jurisdiction, proceeding_type_id, party, event_category_id. Returns matching events with the priority flag and a sequence-depth control: caller picks 'next' (1 hop downstream) or 'all-following' (full chain)."

Today the cascade reconstructs this client-side via fanned-out calls to /api/tools/fristenrechner etc. — fragile + duplicated logic. The new method centralises the graph walk in the package.

Schema impact

None new. The query reads existing tables:

• paliad.proceeding_types (jurisdiction, id, code)
• paliad.deadline_rules (parent_id, sequence_order, primary_party, priority, event_category_id via concept_id → event_category_concepts)
• paliad.event_categories (id, party, parent_id for the cascade hierarchy)
• paliad.event_category_concepts (junction; concept_id → event_category_id)

The depth control is a runtime graph walk — next returns one hop from the matched parent, all-following walks parent_id recursively until leaves.

The audit found one schema gap worth flagging but NOT changing in Slice B:

• paliad.deadline_rules has no direct event_category_id column — it goes through concept_id → deadline_concepts → event_category_concepts → event_categories. The join is well-trodden but introduces an extra hop. v1 of the catalog API uses the join; a future denormalisation (paliad.deadline_rules.event_category_id cached column) is out of scope.

API shape

// EventLookupAxes carries the optional filter axes for LookupEvents. All
// fields are optional; the empty value is "no filter on this axis". When
// multiple axes are set the engine applies them as AND (a rule must
// match ALL non-zero axes).
type EventLookupAxes struct {
    Jurisdiction      string    // "UPC" | "DE" | "EPA" | "DPMA" — empty = any
    ProceedingTypeID  *int      // narrow to one proceeding — nil = any
    Party             string    // "claimant" | "defendant" | "court" | "both" — empty = any
    EventCategoryID   *uuid.UUID // narrow to one event_categories row — nil = any
    AppealTarget      string    // §18.1 fold-in — empty = any
}

// EventLookupDepth controls the sequence-depth of the returned events.
type EventLookupDepth string

const (
    // EventLookupDepthNext returns immediate children of the matched
    // anchor (1 hop downstream). Default for "what comes next from
    // this point?" queries.
    EventLookupDepthNext EventLookupDepth = "next"
    // EventLookupDepthAllFollowing returns the entire downstream
    // chain (parent_id walk to leaves). Default for "show me the
    // whole sequence from here onward" queries.
    EventLookupDepthAllFollowing EventLookupDepth = "all-following"
)

// EventMatch is one result row from LookupEvents.
type EventMatch struct {
    Rule             Rule             `json:"rule"`              // full rule row
    ProceedingType   ProceedingType   `json:"proceedingType"`    // owning proceeding
    Priority         string           `json:"priority"`          // mandatory|recommended|optional|informational
    DepthFromAnchor  int              `json:"depthFromAnchor"`   // 1 = next, 2+ = deeper
    // ParentRuleID populated when the match has a parent_id in the
    // returned set (so the frontend can render a tree).
    ParentRuleID     *uuid.UUID       `json:"parentRuleId,omitempty"`
}

// LookupEvents on the Catalog interface returns events matching any
// subset of axes, at the requested sequence depth. Returns an empty
// slice (NOT an error) when no events match.
//
// Implementation must respect the catalog's "published + active" rule
// gate that LoadProceeding already enforces.
type Catalog interface {
    // ... existing methods (LoadProceeding, LoadProceedingByID, ...)

    LookupEvents(ctx context.Context, axes EventLookupAxes, depth EventLookupDepth) ([]EventMatch, error)
}

paliad's paliadCatalog impl builds one SQL query with optional WHERE clauses + the existing deadline_concept_event_types JOIN for the event_category_id axis. youpc.org's embedded snapshot impl runs the same axis-filter pass on the in-memory rule slice.

Acceptance criteria (Slice B sub-tasks)

1. Catalog.LookupEvents exists on the interface + has both a paliad-side impl (SQL) and a stub for the future embedded/upc snapshot impl.
2. Round-trip test: LookupEvents(ctx, EventLookupAxes{Jurisdiction:"UPC"}, EventLookupDepthAllFollowing) returns all 77 UPC rules (matches the count from §0).
3. Combined-axis test: EventLookupAxes{Jurisdiction:"UPC", Party:"claimant"} returns the claimant-perspective subset.
4. Depth test: with a specific ProceedingTypeID + Party:"defendant", EventLookupDepthNext returns only 1-hop children of the proceeding's root; EventLookupDepthAllFollowing returns the full chain.
5. New axis-driven endpoint at GET /api/tools/lookup-events?… proxies the call (separate slice — out of scope for the package-side acceptance, but listed for the coder).

§18.3 primary_party enum tightening

Motivation

Today paliad.deadline_rules.primary_party is free-text. The live values confirm a stable four-value vocabulary (claimant=26, defendant=26, court=38, both=63, NULL=78) but nothing prevents a future rule editor from typing clamant or Court and silently breaking the appellant-context propagation in engine.go.

m's brief: "Tighten to a check constraint matching event_categories.party's allowed values: claimant/defendant/court/both. Migration must audit + clean existing rows first; surface dirty rows to m if any don't fit the four-value vocabulary."

Note: event_categories.party is a text[] (array) with current live values {claimant}, {defendant}, NULL. It does NOT carry court or both today. The brief's "matching event_categories.party's allowed values" is taken to mean the SEMANTIC vocabulary (claimant/defendant/court/both), not the literal current rows of event_categories.party. The package owns the canonical list.

Schema impact

Migration 135_primary_party_check.up.sql:

1. Audit pass (DO $$ block): COUNT rules where proceeding_type_id IS NOT NULL AND primary_party NOT IN ('claimant', 'defendant', 'court', 'both', NULL). RAISE NOTICE for each non-matching row's (id, name, primary_party). If COUNT > 0, RAISE EXCEPTION 'dirty rows — see notice; manual cleanup required'.
2. Add CHECK constraint: ALTER TABLE paliad.deadline_rules ADD CONSTRAINT deadline_rules_primary_party_chk CHECK (primary_party IS NULL OR primary_party IN ('claimant', 'defendant', 'court', 'both')).
3. No data change — every proceeding-bound rule already has a valid four-value value; the 78 NULL rows are orphan concept seeds and stay NULL.
4. Down-migration: ALTER TABLE paliad.deadline_rules DROP CONSTRAINT deadline_rules_primary_party_chk. No data revert needed.

Why NULL stays valid:

• The 78 NULL rows are cross-cutting concept seeds (Wiedereinsetzung, Versäumnisurteil-Einspruch, Schriftsatznachreichung, Weiterbehandlung) that have NO proceeding binding. They're not in the calculator's path; loosening the CHECK to IS NULL OR IN (...) keeps them valid without further schema gymnastics.
• A stricter "NOT NULL when proceeding_type_id is NOT NULL" partial constraint would be cleaner but adds a multi-column rule that's harder to maintain. The simpler form suffices given today's invariant.

Should the same vocabulary be propagated to paliad.event_categories.party?

Recommendation: NO, not in this migration. event_categories.party is array-shaped (a category can apply to multiple perspectives) and today carries only {claimant} / {defendant} per its narrower semantic ("from whose perspective is this category triggered?"). Tightening it to require court/both would force backfill of rows where neither perspective is the trigger. Out of scope for Slice B; flag as a follow-up.

API shape

The package's Rule.PrimaryParty field (already *string) stays as-is — the type doesn't change. A new package-level set of constants:

const (
    PrimaryPartyClaimant  = "claimant"
    PrimaryPartyDefendant = "defendant"
    PrimaryPartyCourt     = "court"
    PrimaryPartyBoth      = "both"
)

// PrimaryParties is the canonical ordered list for validation +
// admin-UI rendering.
var PrimaryParties = []string{
    PrimaryPartyClaimant,
    PrimaryPartyDefendant,
    PrimaryPartyCourt,
    PrimaryPartyBoth,
}

// IsValidPrimaryParty returns true for empty (NULL-equivalent) or any
// of the four canonical values. Used by the rule-editor (Slice E2 if
// ever revisited) to validate writes before they hit the CHECK.
func IsValidPrimaryParty(s string) bool { … }

The rule-editor service (internal/services/rule_editor_service.go) gains a validation call against lp.IsValidPrimaryParty before any UPDATE — surfaces a user-friendly 400 before the DB CHECK fires with the less-pretty error.

Acceptance criteria (Slice B sub-tasks)

1. Migration 135_primary_party_check.up.sql + paired .down.sql apply cleanly against a fresh paliad DB.
2. Pre-migration audit pass surfaces zero dirty rows on the current live corpus (verified via Supabase audit before migration drafted).
3. Post-migration, attempting to UPDATE a rule's primary_party to 'foo' raises a DB CHECK violation.
4. The package exposes the four constants + the PrimaryParties slice + the IsValidPrimaryParty predicate.
5. Rule-editor service surfaces 400 with a clear message when a write violates the constraint (instead of leaking the raw PG error).

§18 Summary table

§	Topic	Schema delta	API delta	Migration
18.1	Berufung unification	+2 columns (proceeding_types.appeal_target + deadline_rules.applies_to_target[]); collapse 3→1 active appeal codes	Catalog returns merged proceeding + Rule.AppliesToTarget; CalcOptions.AppealTarget filter; AppealTargets[] constants	134_berufung_unification.up.sql
18.2	Multi-axis catalog query	None new (uses existing joins)	Catalog.LookupEvents(axes, depth) new method + EventLookupAxes / EventMatch types	None
18.3	primary_party enum	+CHECK constraint on deadline_rules.primary_party	PrimaryParties[] constants + IsValidPrimaryParty() predicate	135_primary_party_check.up.sql

§18.4 Slice plan refinement (revises §10 for Slice B)

The original §10 listed Slice B as "Catalog / HolidayCalendar / CourtRegistry interfaces + paliad's default loaders." Slice A already folded those interfaces in (the engine.Calculate signature accepts them). Slice B's revised scope:

1. Slice B1 — Berufung unification (§18.1): migration 134 + package constants + appeal_target field on ProceedingType + applies_to_target[] on Rule + CalcOptions.AppealTarget filter. Frontend updates (verfahrensablauf chip group) follow in the same PR.
2. Slice B2 — Multi-axis catalog query API (§18.2): Catalog.LookupEvents method + paliad impl + tests. New GET /api/tools/lookup-events endpoint optional (slice C may want it earlier).
3. Slice B3 — primary_party enum tightening (§18.3): migration 135 + package constants + rule-editor validation hook.

B1 / B2 / B3 are independently shippable and can land in any order. B1 has the most user-facing impact (the picker change is what m flagged); B3 is the smallest hardening; B2 is the largest API surface.

§18.5 Open questions escalated to head

• §18.1 Q1 — Schadensbemessung-as-appeal: shared vs distinct vs deferred (R: shared, multi-valued applies_to_target).
• §18.1 Q2 — i18n label for "Worauf richtet sich die Berufung?" (R: yes, defer to coder).
• §18.3 — Should event_categories.party be tightened in the same migration? (R: no, separate follow-up.)

No AskUserQuestion per inventor protocol; head escalates to m if material.

---

End of design doc.