# 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:** https://mgit.msbls.de/m/paliad/issues/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 ```go // 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 ```go 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 ```go // 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 ```go // 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 ```go // 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 ```go 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) ```go // 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): ```go // 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.). ```bash # 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: ```go 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 ```sql -- 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. ```json { "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 ```sql -- 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: ```go 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=` → 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 ```go 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: ```bash # 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@` 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: ```go 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=` query param → backend includes `opts.AppealTarget=` 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. #### m's answer on Q18.1.1 (2026-05-26 13:40) > Schadensbemessung-as-appeal is a NEW appeal target. Model it as a first-class entry in the appeal_target enum with its own rule set (no shared inheritance from upc.apl.merits). The rules don't exist yet in the catalog; for now the appeal_target value is defined and `CalcOptions.AppealTarget="schadensbemessung"` returns an empty sequence until rules are seeded. → **Option B wins (m overrode inventor's R=A).** Migration 134 still ships the schema + the 5 enum values + the chip group + the engine filter. Existing rules: - 7 `upc.apl.merits` rules → `applies_to_target=['endentscheidung']` (Endentscheidung only — NOT also Schadensbemessung). - 2 `upc.apl.cost` rules → `applies_to_target=['kostenentscheidung']`. - 7 `upc.apl.order` rules → `applies_to_target=['anordnung']`. - **Schadensbemessung + Bucheinsicht get NO rules in this migration.** `applies_to_target='schadensbemessung'` and `'bucheinsicht'` are valid enum values but no rule row carries them yet. **Frontend behaviour with empty rule sets:** - All 5 target chips still render (the picker promises the user a complete vocabulary). - Picking Schadensbemessung or Bucheinsicht returns an empty timeline with a banner: "Frist-Sequenz für diesen Berufungstyp ist noch nicht hinterlegt — bitte über /admin/rules einpflegen oder Migrations-Follow-up abwarten." - Picking the 3 populated targets renders normally. **Rule-seeding follow-up (TODO, separate slice):** - Schadensbemessung-appeal rules: anchor on R.118.4 (Folgeentscheidung Schadensbemessung) decision; conjecture 2/4-month track but distinct legal basis. - Bucheinsicht-appeal rules: anchor on R.142 (Lay-open-books decision); conjecture 15-day track per R.220.2 + R.224.2.b. - Can pair with `t-paliad-193` orphan-concept-seed if m wants a combined seeding pass. - Either path: editorial via `/admin/rules` (rule-editor service, Slice 11a) so the lawyer team can author + audit. **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 ```go // 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: ```go 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. --- ## §19 Slice C — embedded UPC snapshot + generator (2026-05-26) Slice A landed the package, Slice B added the catalog API surface. Slice C lays the foundation for the youpc.org cross-repo integration: an in-package UPC subset of paliad's deadline corpus, embedded as JSON, that youpc.org can use to run the engine without any paliad DB access. ### §19.1 Goals 1. **Zero DB dependency for snapshot consumers.** youpc.org imports `pkg/litigationplanner/embedded/upc` and gets a working Catalog / HolidayCalendar / CourtRegistry without ever touching paliad's Postgres. 2. **Reproducible regeneration.** A generator binary (`cmd/gen-upc-snapshot`) reads paliad's live DB and produces the JSON. Idempotent — same DB state in, same JSON out. 3. **Versioned snapshots.** Each snapshot carries a `version` + `generated_at` so consumers can detect regeneration and decide whether to bump their go.mod. 4. **Stays in lockstep with paliad's engine.** The embedded data conforms to the same `Rule` / `ProceedingType` Go types the engine consumes — no schema drift, no parallel-vocab risk. ### §19.2 Embedding format **Pick: `//go:embed` of JSON.** Three candidates considered: - A. **`//go:embed` of JSON files** — generator emits human-readable JSON; package reads at boot via `embed.FS`. Diff-friendly in git; youpc.org sees the bytes change in code review. - B. **Generated Go const literals** — generator emits a `.go` file with the rule slice inlined. Type-safe at compile; harder to diff (big generated files); pollutes `git log -p` with mechanical changes. - C. **External resource fetched at runtime** — youpc.org would HTTP-GET the snapshot from a paliad endpoint. Adds runtime coupling between the two services; defeats the "zero DB dependency" goal. **(R) = A**. JSON is the wire shape paliad's API already serves; the package's `Rule` struct already has compatible `json:` tags from Slice A. The generated bytes survive `git diff` cleanly. youpc.org can also vendor the JSON via go-module if they want fully reproducible builds. ### §19.3 File layout ``` pkg/litigationplanner/embedded/upc/ embed.go ← //go:embed *.json + package metadata snapshot.go ← SnapshotCatalog struct + Load() helper snapshot_test.go ← unit tests against the embedded data rules.json ← generator output: all UPC rules proceeding_types.json ← generator output: all UPC proceeding types trigger_events.json ← generator output: UPC-referenced trigger events holidays.json ← generator output: DE + UPC regime holidays courts.json ← generator output: UPC courts meta.json ← generator output: {version, generated_at, paliad_commit, source_db_label} cmd/gen-upc-snapshot/ main.go ← generator entry point README.md ← operator runbook ``` `pkg/litigationplanner/embedded/upc` is the public consumer surface. youpc.org imports it as: ```go import upc "mgit.msbls.de/m/paliad/pkg/litigationplanner/embedded/upc" cat, _ := upc.NewCatalog() hc, _ := upc.NewHolidayCalendar() cr, _ := upc.NewCourtRegistry() timeline, err := lp.Calculate(ctx, "upc.inf.cfi", "2026-05-26", lp.CalcOptions{...}, cat, hc, cr) ``` ### §19.4 Snapshot data shape The five data files (`rules.json`, `proceeding_types.json`, `trigger_events.json`, `holidays.json`, `courts.json`) are each a top-level JSON array of the corresponding type. The package's `Rule` / `ProceedingType` / `TriggerEvent` structs deserialise directly (their `json:` tags align with paliad's wire shape). `holidays.json` and `courts.json` use minimal structures defined in the embedded sub-package (the package's core API only requires `HolidayCalendar` / `CourtRegistry` interfaces — no struct contract). `meta.json` carries the versioning block: ```json { "version": "2026-05-26-1", "generated_at": "2026-05-26T15:01:00Z", "paliad_commit": "932b177", "source_db_label": "paliad-dev-supabase", "rule_count": 81, "proceeding_count": 9, "trigger_event_count": 2, "holiday_count": 142, "court_count": 18 } ``` `version` uses a date-stamped scheme (`YYYY-MM-DD-N` where N starts at 1 and increments for same-day regenerations) — simple, sortable, no merge conflicts on regen. ### §19.5 Generator `cmd/gen-upc-snapshot/main.go` runs as: ```sh DATABASE_URL=postgres://... \ go run ./cmd/gen-upc-snapshot \ -output ./pkg/litigationplanner/embedded/upc ``` Flow: 1. Connect to `DATABASE_URL` (paliad's live DB). 2. Apply migrations first (`db.ApplyMigrations(url)`) — ensures the snapshot matches schema HEAD. 3. SELECT all `paliad.proceeding_types` WHERE `jurisdiction = 'UPC'` AND `is_active = true`. (After B1 the unified `upc.apl` is the only appeal proceeding — the 3 archived old codes are filtered out.) 4. SELECT all `paliad.deadline_rules` for those proceeding ids WHERE `lifecycle_state = 'published'` AND `is_active = true`. 5. SELECT `paliad.trigger_events` referenced by any rule's `trigger_event_id`. 6. SELECT `paliad.holidays` filtered to `country = 'DE' OR regime = 'UPC'` (the union UPC procedures need). 7. SELECT `paliad.courts` filtered to `regime = 'UPC' OR court_type LIKE 'upc%'` (UPC court hierarchy). 8. Write each result set to `/.json` (pretty-printed for diff-friendliness). 9. Compute meta — current paliad commit (via `git rev-parse --short HEAD`), timestamp, row counts. 10. Write `meta.json`. **Versioning rule**: the generator never overwrites a meta.json with `version` equal to an existing one. If today's date is already used (suffix `-1`), the generator bumps to `-2`. This keeps regenerations within a day distinguishable. Operator can pass `-version ` to override. ### §19.6 Regeneration trigger Manual. Three entry points: - **`make snapshot-upc`** — Make target invokes the generator with `DATABASE_URL` from env. Documented in `cmd/gen-upc-snapshot/README.md`. - **`go generate ./pkg/litigationplanner/embedded/upc`** — `//go:generate` directive on a stub in the package. Same effect; lets contributors discover the regen path from the package they're modifying. - **Operator runs the command directly** — power-user path. **No CI regeneration in v1.** The snapshot is operator-controlled. Future slice can add a nightly CI job that opens a PR with the regenerated snapshot if drift is detected (out of scope here). ### §19.7 SnapshotCatalog implementation In `pkg/litigationplanner/embedded/upc/snapshot.go`: ```go type SnapshotCatalog struct { proceedings []litigationplanner.ProceedingType rules []litigationplanner.Rule triggerEvents map[int64]litigationplanner.TriggerEvent rulesByProc map[int][]litigationplanner.Rule // for LoadProceeding rulesByID map[uuid.UUID]litigationplanner.Rule procByID map[int]litigationplanner.ProceedingType procByCode map[string]litigationplanner.ProceedingType } func NewCatalog() (*SnapshotCatalog, error) // parses embedded JSON ``` All 7 Catalog interface methods (`LoadProceeding`, `LoadProceedingByID`, `LoadRuleByID`, `LoadRuleByCode`, `LoadRulesByTriggerEvent`, `LoadTriggerEventsByIDs`, `LookupEvents`) implemented against the in-memory maps. Lookup methods are O(1) on the indexed maps; `LookupEvents` does a linear scan of `rules` (the UPC subset is < 100 rows; no index needed). `ProjectHint` is ignored on the snapshot side (youpc.org has no projects). `applies_to_target` filter for B1 works identically — the rules carry the same array. `HolidayCalendar` impl mirrors paliad's `HolidayService` but reads from the embedded holiday slice instead of paliad.holidays. Same `AdjustForNonWorkingDaysWithReason` semantics. `CourtRegistry` impl mirrors `CourtService.CountryRegime`. UPC courts only. ### §19.8 Tests `snapshot_test.go` exercises: - Snapshot loads without error - `meta.json` parses + has non-zero counts - `LoadProceeding(ctx, "upc.inf.cfi", ProjectHint{})` returns the expected proceeding + > 0 rules - `LookupEvents(ctx, EventLookupAxes{Jurisdiction:"UPC"}, EventLookupDepthAllFollowing)` returns all rules - A golden compute: `Calculate(ctx, "upc.inf.cfi", "2026-01-15", CalcOptions{}, cat, hc, cr)` produces a non-empty timeline with a known root rule (Klageerhebung) All tests run without a DB (zero `os.Getenv("TEST_DATABASE_URL")` checks). ### §19.9 Acceptance criteria 1. `cmd/gen-upc-snapshot` exists + builds + runs against the live paliad DB. 2. `pkg/litigationplanner/embedded/upc/*.json` checked in with the first generated snapshot. 3. `embedded/upc.NewCatalog()` (+ `NewHolidayCalendar` + `NewCourtRegistry`) return ready-to-use implementations of the package interfaces. 4. Unit tests in `embedded/upc` pass without `TEST_DATABASE_URL` (no DB roundtrip). 5. `make snapshot-upc` regenerates the snapshot. 6. `go build ./...` + `go test ./...` all green. ### §19.10 Out of scope (deferred to follow-up) - Snapshot signing / integrity attestation. v1 is plain JSON; future slice can ship a `meta.sig` next to `meta.json` for tamper detection. - DE/EPA/DPMA snapshots. v1 only ships the UPC subset (matches youpc.org's scope). Future jurisdictions add as sibling packages: `embedded/de`, `embedded/epa`, etc. - CI regeneration cron. Operator-driven only in v1. - Snapshot diff tooling. v1 relies on `git diff` of the JSON files. --- *End of design doc.*