Enhancement: Court Planner + Recommendations workflow (Planner, Court Report, Herald Script, Recs Manager, notifications, pass-to-local)

[baltinerdist]

Court Planner + Recommendations workflow

A complete workflow for planning royal courts and managing award recommendations.

Court Planner

• Plan kingdom/park courts: schedule, add awards + contributing artisans, drag-reorder, scroll/regalia tracking, and grant directly from the plan
• Stage → finalize: granting at court captures giver/reason/date/rank and marks the line staged; it does not touch the permanent record. A single Finalize (folded into Complete Court) batch-commits every staged grant, so undo before finalize is free. The idempotency key is the court line — an atomic staged→given claim means a line commits at most once, and finalize is throw-safe (a failed AddAward reverts that row to staged and the court will not complete until it is clear)
• Run vs Plan is a stored court mode. Run mode shows a granted row as Given with an Undo for the one-tap ceremony flow; Plan mode keeps the explicit staged framing. Both share the identical pipeline
• Optimistic concurrency (row_version) plus a presence heartbeat, so several reeves can run one court live without silently clobbering each other
• Court Report (public): per-kingdom/park court history with awards given
• Herald script generation for reading court
• Responsive/mobile layout for running court from a phone

Recommendations Manager

• Dedicated management page, server-side paginated (500-row batches + infinite scroll), grouping parallel recommendations into one row per (recipient, award, rank) cluster
• Server-side filter/sort; Park and Rank columns; CSV export of the full filtered set
• Grant Award modal — pre-filled from the recommendation, with rank pills (green = already held), officer quick-pick chips (Monarch/Regent), and a park/kingdom/event location picker
• Granting a recommendation that already sits on a court plan is reconciled server-side in the same request, scoped to courts the officer can manage and never to a completed court, so a later finalize cannot re-grant it. The officer's "leave on court" / "remove from court" choice is carried as CourtAction and applied in the domain layer
• Snooze-to-next-monarchy, pass-to-local delegation, and second/support a recommendation
• Anonymous recommendations (recommender masked per viewer, never cached across viewers)
• In-app notifications to advocates when a recommendation is granted

Architecture

DB work lives in system/lib/ork3/ (Court + Report libs); controllers stay thin and reach the domain layer through orkui/model/model.Court.php.

Migrations

Ten migrations under db-migrations/ — court tables, stage/finalize + grant-safety columns, recommendation snooze / pass-to-local, the notification table, and an idempotent repair for ork_session.user_agent/ip. Apply before deploy.

The session repair is unrelated to court but ships here because the branch surfaced it: the device-metadata columns were added by editing the original 2026-07-13-add-ork-session-table.sql in place. That file leads with CREATE TABLE IF NOT EXISTS, so re-running it on a database built from the pre-metadata version adds nothing, CreateSession() then inserts columns the table does not have, and every password login fails. Fresh installs were never affected.

Review

The branch went through two rounds of adversarial review (hostile multi-agent panels; findings kept only if they survived an organized attempt to refute them), the second run after a layering refactor moved the Court Planner behind a model. Everything found in both rounds is fixed.

Round 2 — the ledger and the public record

• One honor could reach the permanent record many times. The add-to-court dedup keyed on the recommendation id, but the honor is the cluster (recipient + award + rank). Several people recommending the same person for the same award is routine — production data has clusters of fifteen — and the picker emitted a row per recommendation, so each added its own court line and each finalized independently. The dedup now matches the cluster, the picker groups by honor with a support count, and finalize refuses to commit the same honor twice.
• The cross-path reconcile rewrote courts it had no business touching. Its UPDATE matched a global recommendation id or the cluster key with no court join — no scope, no authority check, no court-status check. Because "Leave As-Is and Close" legitimately leaves planned lines on a completed court, a grant months later flipped a finalized court's line to given and published an honor on the login-free Court Report for a ceremony where it was never announced. Candidates are now filtered per row through canManage against that row's own court, and completed courts are excluded.
• Anonymous recommenders were unmasked to the wrong people. Masking was folded into a response cached for 300s under a key with no viewer dimension, so whoever warmed the cache decided what everyone saw. Masking now happens per request — which also restores the ability of someone who filed an anonymous recommendation to edit their own reason.
• A withdrawn grant could still be committed (un-stage left the giver and citation behind while staged stayed client-settable), Run mode never delivered the one-tap grant the mode exists for, and a dead status-sync block was removed.

Round 1 — the grant seam

• The Recs-Manager grant left the recommendation unresolved and invited a retry that would double-grant; internal officer notes could become the public citation; clients could force a line to given without linking an award id; concurrent adds returned the wrong row id (LAST_INSERT_ID vs a "highest id" re-query); a double-click could put one recommendation on two court lines; the award autocomplete could submit a different award than the one displayed; reordering under the Printing List filter corrupted the running order; and the CSV export was open to formula injection via player-written text.

Verification

PHP lint clean across changed files; ork-db migration coverage passes; end-to-end HTTP + DB checks on every fix and on grant (both court actions), stage/finalize, add/dedup, snooze, pass-to-local, dismiss, pagination, filters/sorts and export. Not covered: PHPUnit was not run (no composer in the dev container), and no concurrency was exercised — the multi-reeve and atomic-claim guarantees are reasoned from the SQL shape, not reproduced under load.

🤖 Generated with Claude Code

[baltinerdist]

Updated with the Court Planner grant-safety + workflow/UX implementation (commit 748e3df6):

Records integrity

• Single idempotent grant sink (Court::commitStagedAward) — court-line identity is the idempotency key; Player::AddAward now returns the real inserted id (date-heuristic removed); throw-safe finalize (revert-on-throw, re-runnable).
• Server-side cross-path reconcile so a Recs-Manager grant can't be re-granted at finalize; update_court_status rejects complete; remove/skip/setStatus guard given rows.

Concurrency

• ork_court_award.row_version optimistic lock (stale → non-destructive reload), full-field heartbeat reconcile, presence roster + honest sync indicator.

Workflow / mobile / a11y

• Run-mode "Grant" + auto-finalize on Complete; walk-on adds while published; inline un-skip; mobile stacked-card layout so Grant/Skip are reachable on a phone; a11y additive pass; native confirm/alert removed.

Ceremony polish

• WCAG-AA rank-pill ramp; functional status (Cancelled → Skipped); expanded-row highlight; flags/type tooltips; ad-hoc add split into Add Award / Add Title with typeable autocompletes grouped exactly like the player Add Award modal (rank pills replacing the number box).

Verified end-to-end against a live instance (6/6 functional + 4/4 fix re-tests; all data-integrity SQL invariants at 0). Migrations: 2026-07-11-court-stage-finalize.sql, 2026-07-12-court-grant-safety.sql.

🤖 Generated with Claude Code

[baltinerdist]

Branch brought current with master

Synced up to master @ 6ab028a3 (merge commit 8cb99dc5). This branch was 263 commits behind; it's now 0 behind / 130 ahead.

Conflicts: 3 files, resolved. All three were upstream's domain-migration work landing on top of Court Planner additions.

1. orkui/model/model.Award.php — upstream's R-10 migration gutted this model into a thin pass-through (fetch_award_option_list() → Award::GetAwardOptionListHtml(), plus an _award() helper). This branch had added a Court-Planner-only fetch_award_option_groups() for the ad-hoc Add Award/Title autocompletes, and otherwise only reformatted fetch_award_option_list (confirmed via git diff -w base..HEAD — no logic change on the branch side).

Resolved to upstream's thin version plus this branch's fetch_award_option_groups() and compareAwardsByName() kept verbatim. Note the deliberate choice: fetch_award_option_groups() was not rewritten on top of upstream's new Award::GetAwardOptionGroups(), because the two return different shapes — this branch returns ordered [{label, options:[…]}] with per-group IsTitle and Custom split into "Custom Award"/"Custom Title" groups, while upstream returns Groups/StandaloneOptions with raw award rows. Adapting one to the other mid-merge would have risked a silent behavior change in the Court picker.

2. orkui/model/model.Player.php — upstream PSR-12'd the file and added reset_waivers()/add_player_recommendation(); this branch added four Court/Recs methods in the same region. Kept upstream's structure and re-added all four (resolve_player_recommendation_cluster, snooze_recommendation, unsnooze_recommendation, set_recommendation_passed_to_local) in upstream's PSR-12 style. Verified no duplicate declarations, and that the corresponding lib methods on class.Player.php all survived the auto-merge.

3. orkui/controller/controller.KingdomAjax.php — upstream (R-18) replaced the inline geteventtemplates SQL with $this->Event->get_event_templates_for_kingdom(); this branch had inserted snoozerecommendation/unsnoozerecommendation handlers immediately above it. Kept upstream's model call and both branch handlers. Event::GetEventTemplatesForKingdom() was checked to return the identical shape (EventId/Name/ParkId/ParkName) the JS consumes, so no client-side breakage.

Method: git merge upstream/master, not a rebase — this branch has 130 commits behind prior merge commits, and a linear rebase would replay all of them against the new base.

Verification: no conflict markers; php -l clean on all 270 changed .php/.tpl; duplicate-method scan across 239 changed PHP files found none; class.Authorization.php untouched by both sides with no bypass. Feature spot-checks post-merge: the stage/finalize state machine in class.Court.php is intact ('staged' -> 'given' atomic claim + revert paths), and Recs Manager is still server-paginated ('Limit' => 500 + NextOffset, infinite scroll in Recommendations_manage.tpl) — independently re-confirmed on the pushed branch.

---

Worth a maintainer's eye:

1. ⚠️ The snoozerecommendation / unsnoozerecommendation handlers have no controller-level auth guard, unlike the adjacent restorerecommendation block which returns status 5. That's how they shipped on this branch — presumably auth lives in the lib — and it was preserved as-is rather than hardened mid-merge. Worth confirming the lib really does gate them.
2. Award classification logic is now duplicated between Model_Award::fetch_award_option_groups() and upstream's Award::GetAwardOptionGroups(). A consolidation follow-up, out of scope for a merge.
3. Unrelated upstream change to be aware of: upstream's new GetAwardOptionListHtml() emits Custom options after the optgroups, where the pre-merge code emitted them between Ladder and the rest (upstream commit 6d06e4c0). Not introduced here, but it changes picker ordering.
4. The two snooze handlers were re-indented from tabs to spaces and their one-line if (!valid_id(...)) {…} guards expanded, to match the now-PSR-12 file. No logic changed; no php-cs-fixer was run.

PR now shows MERGEABLE / CLEAN.

🤖 Generated with Claude Code

[baltinerdist]

Follow-up: snooze guards verified, Court model layer added

Two items from the sync comment above, resolved.

1. Snooze handlers are authorized — no guard added, and none needed

I asked for evidence before adding anything, and the evidence says the lib enforces it. Model_Player::snooze_recommendation / unsnooze_recommendation (model.Player.php:235,240) are bare pass-throughs to class.Player.php, which does a two-stage check.

Player::SnoozeAwardRecommendation (class.Player.php:3954):

if (($mundane_id = Ork3::$Lib->authorization->IsAuthorized($request['Token'])) == 0) {
    return NoAuthorization();
}
...
// Auth: must be park admin for recipient's park
$recipientInfo = $this->player_info($awardRec->mundane_id);
if (!Ork3::$Lib->authorization->HasAuthority($mundane_id, AUTH_PARK, $recipientInfo['ParkId'], AUTH_EDIT)) {
    return NoAuthorization();
}

UnsnoozeAwardRecommendation (:3999) carries the identical pair.

The important detail: the scope is derived from the loaded recommendation's recipient ($awardRec->mundane_id → their ParkId), never from a request parameter — so it cannot be spoofed by passing someone else's kingdom_id. That makes it stricter than restorerecommendation's controller-level AUTH_KINGDOM/AUTH_CREATE check, not weaker. No IDOR. Independently re-confirmed on the pushed branch.

Same applies to the identical unguarded pair at controller.ParkAjax.php:427,439 — covered by the same lib enforcement.

2. Court model layer (fb1c2888)

69 call sites converted across 7 controllers — noticeably more than the ~44 estimated: CourtAjax 45, Court 11, Kingdom/Park/Recommendations/Reports 3 each, PlayerAjax 1. grep -rn 'Lib->court->' now returns nothing repo-wide (verified post-push).

New orkui/model/model.Court.php: 39 thin pass-through methods, zero SQL, zero logic (confirmed by grep). It follows model.QualTest.php — the closest analogue on this branch, also fronting a camelCase lib with snake_case wrappers and a private accessor. (The two models I'd suggested as templates, model.RBACService.php and model.OfficerPosition.php, don't exist on this branch — they're on #475.)

Name resolution is auto-wired, no registration needed: Model::__construct splits Model_Court on _ and takes Court; startup.php:52-56 has already require_once'd every DIR_ORK3/class.*.php, so Court is defined before any model instantiates.

Two decisions beyond the mechanical:

• load_model('Court') placement — constructor for the Court-centric controllers (Court, CourtAjax, Recommendations, where nearly every action needs it and Recommendations uses it inside the shared resolveContext()); per-action for Kingdom, Park, PlayerAjax, Reports, matching each file's local convention.
• Param/return types deliberately omitted on the model methods — the Court lib methods are untyped, and adding declarations would introduce coercion that could change behavior.

controller.Reports.php is tab-indented (60 tab lines) while the rest are spaces; edits there were surgical and tab-preserving rather than running php-cs-fixer over an otherwise-untouched file.

Verification: php -l clean on all 8 files; a static cross-check confirmed all 39 model methods forward to a real Court method with matching total and required arity, and all 69 call sites pass an argument count within range. A stub harness then instantiated Model_Court against a capturing Court stub and invoked all 39 public methods by reflection — 39 dispatched, 0 failures, each forwarding the full parameter list including defaults.

Not runtime-tested in the app — the worktree isn't what the local Docker instance serves. Verification is static plus that isolated dispatch harness.

🤖 Generated with Claude Code