Priority Scoring Algorithms: Ranking Filing Obligations by Penalty Exposure, Proximity, and Entity Criticality #

This guide is part of the Deadline Tracking & Routing Engines discipline, sitting at the prioritization stage between timezone-aware deadline resolution and dispatch. Its job is narrow and load-bearing: take the flat set of resolved, dated obligations a portfolio owes and turn it into an ordered work list, so that when capacity is constrained the engine acts on a Delaware franchise-tax cliff before a $25 informational report — deterministically, and with an audit trail explaining every rank.

A scoring algorithm exists because a calendar does not encode urgency. Two filings due the same morning can differ by three orders of magnitude in consequence: one carries a flat late fee that is annoying but survivable, the other triggers administrative dissolution and loss of good standing. Sorting purely by due date treats them identically. The scoring layer fixes that by collapsing penalty exposure, temporal proximity, and entity criticality into a single comparable number, then mapping that number onto routing tiers the rest of the system already understands.

Statutory and Regulatory Context #

The score is only defensible if its inputs trace back to statute. Penalty exposure — the dominant signal — is computed upstream and quantifies what each jurisdiction does when a deadline lapses; the scoring layer consumes that work through Calculating Penalty Risk Scores Based on State Grace Periods, which encodes the relevant code sections directly. Delaware franchise tax accrues a $200 late penalty plus 1.5% monthly interest under DGCL § 502; California assesses a $250 penalty for a late Statement of Information under Corp. Code § 1502 and moves entities toward suspension; Texas applies a compounding surcharge under BOC § 4.002 with administrative dissolution at 90 days; New York recognizes no grace window on the biennial statement under BCL § 408. These are not interchangeable buffers, and a scorer that flattens them into “days late” discards the exact information that should drive routing.

Proximity is governed by the statutory due-date formula itself, which the State Filing Deadline Calendars layer resolves in each jurisdiction’s own timezone with weekend and holiday roll-forward. The scorer never recomputes a date; it consumes the timezone-aware deadline and measures distance from now. Entity criticality is sourced from the Entity Taxonomy & Classification layer — a revenue-bearing parent or a regulated subsidiary outranks a dormant shell of equal deadline proximity, because the blast radius of a missed filing is a function of the entity, not just the statute.

Architecture and Design Model #

The scorer is a pure transformation: typed obligations in, scored-and-tiered obligations out, with no side effects and no I/O on the hot path. That purity is the design’s central decision. Because scoring is deterministic over its inputs, a score can be recomputed from a persisted input vector during an audit and must reproduce bitwise. Three further decisions follow from it:

• Normalize before weighting. Penalty magnitude, days-to-deadline, and criticality live on incompatible scales (dollars, days, an ordinal tier). Each is normalized to [0, 1] against the current batch before the weighted sum, so no single raw unit silently dominates and weights mean what they say.
• Weights are configuration, not code. The relative pull of penalty vs. proximity vs. criticality is a risk-appetite decision owned by compliance, not engineering. Weights live in a config object, must sum to 1.0, and are validated at construction.
• Score maps to tiers, tiers map to routing. The continuous [0, 100] score is preserved for ordering, but a small set of thresholds projects it onto CRITICAL / HIGH / MEDIUM / LOW. The router downstream reasons about tiers, not floats, which keeps dispatch logic legible and the decision boundary immutable: one score, one tier, one action.

Prerequisites and Dependencies #

Step-by-Step Implementation #

Phase 1 — Type the inputs and the scoring configuration #

Model the obligation and the weights as validated, frozen structures. Weights that do not sum to 1.0 are a configuration error, not a runtime surprise, so they fail at construction.

from __future__ import annotations

import logging
from dataclasses import dataclass, field

import numpy as np
import pandas as pd

logger = logging.getLogger("compliance.priority_scorer")


class ScoringConfigError(ValueError):
    """Raised when scoring weights or thresholds are internally inconsistent."""


@dataclass(frozen=True)
class ScoringConfig:
    w_penalty: float = 0.50      # statutory consequence dominates
    w_proximity: float = 0.30    # how soon the clock runs out
    w_criticality: float = 0.20  # blast radius of the entity
    critical_at: float = 85.0
    high_at: float = 65.0
    medium_at: float = 40.0
    proximity_horizon_days: int = 45  # beyond this, proximity contributes ~0

    def __post_init__(self) -> None:
        total = self.w_penalty + self.w_proximity + self.w_criticality
        if not np.isclose(total, 1.0, atol=1e-6):
            raise ScoringConfigError(f"weights must sum to 1.0, got {total:.6f}")
        if not (self.critical_at > self.high_at > self.medium_at > 0):
            raise ScoringConfigError("tier thresholds must be strictly descending")

Phase 2 — Normalize each signal to a common [0, 1] scale #

Penalty risk arrives pre-normalized on [0, 100]. Proximity is an inverse-distance signal bounded by a configurable horizon, so a deadline three months out does not crowd out one due tomorrow. Criticality is already an ordinal tier in [0, 1].

def _normalize_signals(df: pd.DataFrame, cfg: ScoringConfig) -> pd.DataFrame:
    out = df.copy()

    # Penalty risk: supplied 0-100 by the grace-period scorer -> 0-1.
    out["n_penalty"] = (out["penalty_risk"].clip(0, 100) / 100.0)

    # Proximity: timezone-aware days-to-deadline, floored at 0 (overdue == 0 days).
    now = pd.Timestamp.now(tz="UTC")
    days = (pd.to_datetime(out["due_date"], utc=True) - now).dt.total_seconds() / 86_400.0
    days = days.clip(lower=0.0)
    # Linear decay to zero at the horizon; overdue and today both score 1.0.
    out["n_proximity"] = (1.0 - (days / cfg.proximity_horizon_days)).clip(0.0, 1.0)

    # Criticality: already an ordinal tier in [0, 1] from entity taxonomy.
    out["n_criticality"] = out["entity_tier"].clip(0.0, 1.0)
    return out

Phase 3 — Compute the composite score and project onto tiers #

The weighted sum runs as a single vectorized operation over the whole portfolio, then np.select assigns tiers from the thresholds. No row-by-row Python loop touches the hot path.

def score_obligations(df: pd.DataFrame, cfg: ScoringConfig) -> pd.DataFrame:
    required = {"entity_id", "jurisdiction", "due_date", "penalty_risk", "entity_tier"}
    missing = required - set(df.columns)
    if missing:
        raise ScoringConfigError(f"missing required columns: {sorted(missing)}")

    out = _normalize_signals(df, cfg)
    out["priority_score"] = (
        cfg.w_penalty * out["n_penalty"]
        + cfg.w_proximity * out["n_proximity"]
        + cfg.w_criticality * out["n_criticality"]
    ) * 100.0

    conditions = [
        out["priority_score"] >= cfg.critical_at,
        out["priority_score"] >= cfg.high_at,
        out["priority_score"] >= cfg.medium_at,
    ]
    out["routing_tier"] = np.select(conditions, ["CRITICAL", "HIGH", "MEDIUM"], default="LOW")

    for row in out.itertuples():
        logger.info(
            "obligation scored",
            extra={
                "entity_id": row.entity_id,
                "jurisdiction": row.jurisdiction,
                "priority_score": round(row.priority_score, 4),
                "routing_tier": row.routing_tier,
                "n_penalty": round(row.n_penalty, 4),
                "n_proximity": round(row.n_proximity, 4),
                "n_criticality": round(row.n_criticality, 4),
            },
        )
    return out.sort_values("priority_score", ascending=False, kind="stable")

Phase 4 — Adaptive weighting past the statutory cliff #

A static weight set under-prioritizes an obligation the moment it crosses a grace boundary and penalty exposure starts compounding. Re-derive a per-obligation weight set that lets penalty dominate once the deadline is breached, without ever violating the sum-to-one invariant.

def adaptive_weights(days_to_deadline: float, base: ScoringConfig) -> ScoringConfig:
    """Shift weight toward penalty as a deadline crosses zero, renormalized to 1.0."""
    if days_to_deadline > 0:
        return base
    boosted_penalty = min(0.80, base.w_penalty + 0.25)
    remaining = 1.0 - boosted_penalty
    prox = base.w_proximity / (base.w_proximity + base.w_criticality) * remaining
    crit = remaining - prox
    return ScoringConfig(
        w_penalty=boosted_penalty,
        w_proximity=prox,
        w_criticality=crit,
        critical_at=base.critical_at,
        high_at=base.high_at,
        medium_at=base.medium_at,
        proximity_horizon_days=base.proximity_horizon_days,
    )

A CRITICAL result is then handed to the dispatcher as a single atomic action: scored obligations flow into Multi-Entity Batch Orchestration in score order, while assignment of the responsible filer is resolved through Registered Agent Assignment Logic and the resulting alerts are pushed by the Calendar Sync & Notification Pipelines.

Edge Cases and Jurisdiction-Specific Gotchas #

The proximity signal is jurisdiction-neutral, but the penalty signal it is summed with is not — and that asymmetry produces non-obvious ranking behavior near each state’s grace boundary.

Two further traps are not jurisdictional. A naive day count is timezone-sensitive: an obligation “due tomorrow” in Pacific time can already be overdue in UTC, so due_date must arrive timezone-aware and proximity must be computed in a single reference frame. And missing upstream metadata must fail safe — an absent penalty_risk should be treated as maximum risk, never silently zeroed, or the engine will deprioritize exactly the obligations it knows least about.

Verification and Testing #

Scoring is deterministic, which makes it unusually testable: pin the inputs, assert the rank. The properties worth locking down are monotonicity (more penalty or less time can only raise a score), the sum-to-one invariant, and stable ordering for ties.

import pandas as pd
import pytest

from scorer import ScoringConfig, ScoringConfigError, score_obligations


def _frame(**over) -> pd.DataFrame:
    base = {
        "entity_id": ["A"], "jurisdiction": ["DE"],
        "due_date": ["2026-07-15T00:00:00Z"],
        "penalty_risk": [50.0], "entity_tier": [0.5],
    }
    base.update({k: [v] for k, v in over.items()})
    return pd.DataFrame(base)


def test_weights_must_sum_to_one() -> None:
    with pytest.raises(ScoringConfigError):
        ScoringConfig(w_penalty=0.6, w_proximity=0.6, w_criticality=0.2)


def test_higher_penalty_never_lowers_score() -> None:
    cfg = ScoringConfig()
    low = score_obligations(_frame(penalty_risk=10.0), cfg)["priority_score"].iloc[0]
    high = score_obligations(_frame(penalty_risk=90.0), cfg)["priority_score"].iloc[0]
    assert high >= low


def test_no_grace_jurisdiction_reaches_critical_when_overdue() -> None:
    cfg = ScoringConfig()
    overdue = _frame(jurisdiction="NY", due_date="2020-01-01T00:00:00Z", penalty_risk=100.0)
    assert score_obligations(overdue, cfg)["routing_tier"].iloc[0] == "CRITICAL"

For integration coverage, feed a fixed 50-entity multi-jurisdiction frame through score_obligations and snapshot the resulting (entity_id, routing_tier) ordering; a diff in that snapshot on an unrelated change is the signal that a normalization or weighting regression slipped in.

Troubleshooting #

Operational Checklist #

• Scoring weights are loaded from configuration, validated to sum to 1.0 at construction, and owned by compliance — not hardcoded in the scorer.
• Every signal is normalized to [0, 1] before the weighted sum; raw dollars and raw days never enter the composite directly.
• due_date is timezone-aware and proximity is computed against a single UTC reference clock.
• penalty_risk is consumed from the grace-period scorer, never recomputed here, and invalidated whenever a deadline crosses a statutory grace boundary.
• Missing upstream metadata fails safe to maximum risk with a logged WARNING, never a silent zero.
• Adaptive weighting lets penalty exposure dominate once an obligation is overdue, without violating the sum-to-one invariant.
• Every scored obligation emits a structured JSON log record (input vector, composite score, tier) for replay against audit.
• Tier thresholds map to exactly one routing action each; the decision boundary is immutable and unit-tested.

Frequently Asked Questions #

Related #

• Deadline Tracking & Routing Engines
• Calculating Penalty Risk Scores Based on State Grace Periods
• Multi-Entity Batch Orchestration
• Registered Agent Assignment Logic
• Calendar Sync & Notification Pipelines