rosterops 0.1.0__py3-none-any.whl

rosterops/__init__.py

@@ -0,0 +1,24 @@
+"""rosterops — deterministic, configurable pharma roster processing and validation."""
+
+from __future__ import annotations
+
+from rosterops.config import RosterConfig
+from rosterops.engine import RosterResult
+from rosterops.engine.api import RosterEngine
+from rosterops.exceptions import ConfigError, InputError, ReconstructionError, RosterOpsError
+from rosterops.interop import is_pandas_dataframe, to_pandas, to_polars
+from rosterops.version import __version__
+
+__all__ = [
+    "ConfigError",
+    "InputError",
+    "ReconstructionError",
+    "RosterConfig",
+    "RosterEngine",
+    "RosterOpsError",
+    "RosterResult",
+    "__version__",
+    "is_pandas_dataframe",
+    "to_pandas",
+    "to_polars",
+]

rosterops/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m rosterops``."""
+
+from __future__ import annotations
+
+import sys
+
+from rosterops.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rosterops/cli.py

@@ -0,0 +1,279 @@
+"""Command-line interface for rosterops.
+
+Exit codes (REQUIREMENTS §13): 0 = success, 1 = completed with error-severity
+findings or reconciliation failures, 2 = the run could not be performed
+(invalid configuration, unreadable required input, impossible reconstruction,
+or a command not yet available).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from rosterops.config import RosterConfig
+from rosterops.exceptions import ConfigError
+from rosterops.rules import all_rules, get_rule
+from rosterops.version import __version__
+
+__all__ = ["build_parser", "main"]
+
+
+def _configure_std_streams() -> None:
+    """Force UTF-8 stdio so rule names (§8) render regardless of console codepage.
+
+    Windows consoles default to a legacy codepage (cp1252) that cannot encode
+    characters such as ``≥``, ``≠``, or the minus sign used verbatim in the rule
+    catalogue. Reconfiguring the streams keeps output identical across locales.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the full command-line parser (subcommands per REQUIREMENTS §13)."""
+    parser = argparse.ArgumentParser(
+        prog="rosterops",
+        description=(
+            "Deterministic roster processing and validation for pharma commercial operations."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"rosterops {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    process = subparsers.add_parser(
+        "process",
+        help="Reconstruct the roster as of a date from a baseline and event files",
+    )
+    process.add_argument("--baseline", required=True, help="Baseline roster file")
+    process.add_argument(
+        "--baseline-date", required=True, help="Baseline snapshot date (YYYY-MM-DD)"
+    )
+    process.add_argument("--as-of", required=True, help="Reconstruction date (YYYY-MM-DD)")
+    process.add_argument("--transfers", help="Transfer events file")
+    process.add_argument("--promotions", help="Promotion events file")
+    process.add_argument("--terminations", help="Termination events file")
+    process.add_argument("--leaves", help="Leave-of-absence events file")
+    process.add_argument("--returns", help="Return-from-leave events file")
+    process.add_argument("--hires", help="New-hire events file")
+    process.add_argument("--rehires", help="Rehire events file")
+    process.add_argument("--coverage", help="Temporary coverage events file")
+    process.add_argument("--territories", help="Territory master file")
+    process.add_argument("--managers", help="Manager master file")
+    process.add_argument("--config", required=True, help="Configuration YAML file")
+    process.add_argument("--output-dir", required=True, help="Directory for reports")
+    process.add_argument(
+        "--overwrite", action="store_true", help="Allow overwriting the output dir"
+    )
+    process.add_argument(
+        "--fail-on-warning",
+        action="store_true",
+        help="Exit 1 when any warning-severity finding exists",
+    )
+
+    validate = subparsers.add_parser(
+        "validate",
+        help="Validate a single consolidated roster snapshot",
+    )
+    validate.add_argument("--snapshot", required=True, help="Consolidated roster file")
+    validate.add_argument("--as-of", required=True, help="Effective date (YYYY-MM-DD)")
+    validate.add_argument("--territories", help="Territory master file")
+    validate.add_argument("--config", required=True, help="Configuration YAML file")
+    validate.add_argument("--output-dir", required=True, help="Directory for reports")
+    validate.add_argument(
+        "--overwrite", action="store_true", help="Allow overwriting the output dir"
+    )
+    validate.add_argument(
+        "--fail-on-warning",
+        action="store_true",
+        help="Exit 1 when any warning-severity finding exists",
+    )
+
+    validate_inputs = subparsers.add_parser(
+        "validate-inputs",
+        help="Validate configuration and inputs without reconstructing",
+    )
+    validate_inputs.add_argument("--config", required=True, help="Configuration YAML file")
+
+    rules = subparsers.add_parser("rules", help="Inspect validation rules")
+    rules_sub = rules.add_subparsers(dest="rules_command")
+    rules_sub.add_parser("list", help="List all rules")
+    describe = rules_sub.add_parser("describe", help="Describe one rule")
+    describe.add_argument("rule_id", help="Rule ID, e.g. TRF-002")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point returning the documented process exit code."""
+    _configure_std_streams()
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "rules":
+        return _rules_command(args)
+    if args.command == "validate-inputs":
+        return _validate_inputs_command(args)
+    if args.command == "process":
+        return _process_command(args)
+    if args.command == "validate":
+        return _validate_command(args)
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+_EVENT_FLAGS = (
+    ("transfers", "transfers"),
+    ("promotions", "promotions"),
+    ("terminations", "terminations"),
+    ("leaves", "leaves"),
+    ("returns", "returns"),
+    ("hires", "hires"),
+    ("rehires", "rehires"),
+    ("coverage", "coverage"),
+)
+
+_MASTER_FLAGS = (("territories", "territories"), ("managers", "managers"))
+
+
+def _load_config(args: argparse.Namespace) -> RosterConfig | None:
+    try:
+        return RosterConfig.from_file(args.config)
+    except ConfigError as exc:
+        print(f"configuration error: {exc}", file=sys.stderr)
+        return None
+
+
+def _process_command(args: argparse.Namespace) -> int:
+    from rosterops.engine.api import RosterEngine
+    from rosterops.exceptions import RosterOpsError
+    from rosterops.outputs import console_report, write_outputs
+
+    config = _load_config(args)
+    if config is None:
+        return 2
+
+    sources: dict[str, str] = {"baseline": args.baseline}
+    for attr, role in (*_EVENT_FLAGS, *_MASTER_FLAGS):
+        value = getattr(args, attr, None)
+        if value:
+            sources[role] = value
+
+    try:
+        result = RosterEngine(config).process(
+            **sources,  # type: ignore[arg-type]
+            baseline_date=args.baseline_date,
+            as_of=args.as_of,
+        )
+    except RosterOpsError as exc:
+        print(f"run failed: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        report = write_outputs(
+            result,
+            args.output_dir,
+            input_paths=[p for p in sources.values() if isinstance(p, str)],
+            overwrite=args.overwrite,
+        )
+    except RosterOpsError as exc:
+        print(f"output error: {exc}", file=sys.stderr)
+        return 2
+
+    print(console_report(result, report))
+    return result.exit_code(fail_on_warning=args.fail_on_warning)
+
+
+def _validate_command(args: argparse.Namespace) -> int:
+    from rosterops.engine.api import RosterEngine
+    from rosterops.exceptions import RosterOpsError
+    from rosterops.outputs import console_report, write_outputs
+
+    config = _load_config(args)
+    if config is None:
+        return 2
+
+    sources: dict[str, str] = {"snapshot": args.snapshot}
+    if getattr(args, "territories", None):
+        sources["territories"] = args.territories
+
+    try:
+        result = RosterEngine(config).validate_snapshot(
+            **sources,  # type: ignore[arg-type]
+            as_of=args.as_of,
+        )
+    except RosterOpsError as exc:
+        print(f"run failed: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        report = write_outputs(
+            result,
+            args.output_dir,
+            input_paths=[p for p in sources.values() if isinstance(p, str)],
+            overwrite=args.overwrite,
+        )
+    except RosterOpsError as exc:
+        print(f"output error: {exc}", file=sys.stderr)
+        return 2
+
+    print(console_report(result, report))
+    return result.exit_code(fail_on_warning=args.fail_on_warning)
+
+
+def _rules_command(args: argparse.Namespace) -> int:
+    if args.rules_command == "describe":
+        try:
+            spec = get_rule(args.rule_id)
+        except KeyError as exc:
+            print(str(exc), file=sys.stderr)
+            return 2
+        print(f"{spec.id} — {spec.name}")
+        print(f"  group:          {spec.group}")
+        print(f"  default severity: {spec.default_severity.label}")
+        print(f"  modes:          {', '.join(spec.mode_labels)}")
+        if spec.params:
+            declared = ", ".join(f"{k}: {t.__name__}" for k, t in sorted(spec.params.items()))
+            print(f"  parameters:     {declared}")
+        else:
+            print("  parameters:     none")
+        print(f"  description:    {spec.description}")
+        return 0
+
+    # Default: list (also covers `rules` with no subcommand).
+    print(f"{'ID':<10} {'GROUP':<15} {'SEVERITY':<9} {'MODES':<18} NAME")
+    for spec in all_rules():
+        print(
+            f"{spec.id:<10} {spec.group:<15} {spec.default_severity.label:<9} "
+            f"{','.join(spec.mode_labels):<18} {spec.name}"
+        )
+    print(f"\n{len(all_rules())} rules")
+    return 0
+
+
+def _validate_inputs_command(args: argparse.Namespace) -> int:
+    try:
+        config = RosterConfig.from_file(args.config)
+    except ConfigError as exc:
+        print(f"configuration error: {exc}", file=sys.stderr)
+        return 2
+    print(f"configuration OK: {args.config}")
+    print(f"  version: {config.version}")
+    print(f"  grain:   {config.data.grain.value}")
+    print(f"  inputs:  {len(config.inputs)} role(s) configured")
+    print(f"  rules:   {len(config.rules)} override(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rosterops/config.py

@@ -0,0 +1,380 @@
+"""Strict, versioned configuration for rosterops.
+
+Separates source mapping from business policy. Parsed with ``yaml.safe_load``
+only — configuration can never execute code, shell commands, or imports.
+Precedence: built-in defaults < config file < CLI overrides (merged as raw
+layers by :meth:`RosterConfig.from_layers` before validation).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from rosterops.exceptions import ConfigError
+from rosterops.models import (
+    BASELINE_FIELDS,
+    KNOWN_CONFLICT_POLICIES,
+    KNOWN_INPUT_ROLES,
+    ROLE_FIELDS,
+    Grain,
+    Severity,
+    TerminationDateSemantics,
+)
+from rosterops.rules import all_rule_ids, get_rule
+
+__all__ = ["RosterConfig"]
+
+
+class InputDateSemantics(BaseModel):
+    """Per-source date convention overrides."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    interval_end: Literal["exclusive", "inclusive"] = "exclusive"
+
+
+class InputRoleConfig(BaseModel):
+    """Mapping of one input role's source file onto canonical fields."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str | None = None
+    format: Literal["csv", "excel", "parquet"] | None = None
+    sheet_name: str | None = None
+    header_row: int = Field(default=0, ge=0)
+    required: bool = True
+    columns: dict[str, str] = Field(default_factory=dict)
+    aliases: dict[str, list[str]] = Field(default_factory=dict)
+    date_semantics: InputDateSemantics = Field(default_factory=InputDateSemantics)
+    null_tokens: list[str] | None = None
+    date_formats: dict[str, list[str]] = Field(default_factory=dict)
+    value_maps: dict[str, dict[str, str]] = Field(default_factory=dict)
+    allowed_values: dict[str, list[str]] = Field(default_factory=dict)
+
+
+class DataConfig(BaseModel):
+    """Declared input grain (decision D1)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    grain: Grain = Grain.EMPLOYEE_TERRITORY
+    grain_keys: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_grain_keys(self) -> DataConfig:
+        if self.grain is Grain.CUSTOM:
+            if not self.grain_keys:
+                raise ValueError(
+                    "data.grain_keys must list at least one column when grain is 'custom'"
+                )
+        elif self.grain_keys:
+            raise ValueError("data.grain_keys is only allowed when data.grain is 'custom'")
+        unknown = sorted(set(self.grain_keys) - BASELINE_FIELDS)
+        if unknown:
+            raise ValueError(
+                f"data.grain_keys contains unknown canonical field(s): {', '.join(unknown)}"
+            )
+        return self
+
+
+class DatesConfig(BaseModel):
+    """Global effective-date conventions."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    interval_convention: Literal["half_open"] = "half_open"
+    baseline_includes_effective_date: bool = True
+    default_date_format: str = "%Y-%m-%d"
+    termination_date_semantics: TerminationDateSemantics = (
+        TerminationDateSemantics.LAST_WORKING_DAY_INCLUSIVE
+    )
+
+    @field_validator("default_date_format")
+    @classmethod
+    def _valid_strftime(cls, value: str) -> str:
+        try:
+            datetime(2000, 1, 1).strftime(value)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(f"invalid strftime format {value!r}: {exc}") from exc
+        return value
+
+
+class LeavePolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    retains_employment_status: bool = True
+    retains_home_assignment: bool = True
+    coverage_required_by_default: bool = False
+    allow_overlapping_leave_types: bool = False
+
+
+class VacancyPolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    derive_only_for_required_owner_territories: bool = True
+    count_leave_as_vacancy: bool = False
+
+
+class EventPolicy(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    reject_events_on_or_before_baseline_date: bool = True
+    resolve_conflicting_same_date_events: bool | str = False
+
+    @field_validator("resolve_conflicting_same_date_events")
+    @classmethod
+    def _known_policy(cls, value: bool | str) -> bool | str:
+        if value is True:
+            raise ValueError(
+                "resolve_conflicting_same_date_events must be false or an explicit "
+                f"policy name; known policies: {', '.join(KNOWN_CONFLICT_POLICIES)}"
+            )
+        if isinstance(value, str) and value not in KNOWN_CONFLICT_POLICIES:
+            raise ValueError(
+                f"unknown conflict policy {value!r}; known policies: "
+                f"{', '.join(KNOWN_CONFLICT_POLICIES)}"
+            )
+        return value
+
+
+class Policies(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    allow_multiple_active_territories: bool = True
+    max_primary_territories_per_employee: int = Field(default=1, ge=1)
+    require_active_manager: bool = True
+    allow_unassigned_active_employees: bool = True
+    leave: LeavePolicy = Field(default_factory=LeavePolicy)
+    vacancy: VacancyPolicy = Field(default_factory=VacancyPolicy)
+    events: EventPolicy = Field(default_factory=EventPolicy)
+
+
+class RuleOverride(BaseModel):
+    """Auditable per-rule policy decision from configuration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    enabled: bool = True
+    severity: Severity | None = None
+    params: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("id")
+    @classmethod
+    def _known_rule(cls, value: str) -> str:
+        if value not in all_rule_ids():
+            raise ValueError(f"unknown rule id {value!r} (see 'rosterops rules list')")
+        return value
+
+    @field_validator("severity", mode="before")
+    @classmethod
+    def _normalize_severity(cls, value: object) -> object:
+        if isinstance(value, str):
+            return value.lower()
+        return value
+
+
+def _default_formats() -> list[Literal["csv", "parquet", "json", "excel"]]:
+    return ["csv", "parquet", "json"]
+
+
+class OutputsConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    formats: list[Literal["csv", "parquet", "json", "excel"]] = Field(
+        default_factory=_default_formats
+    )
+    excel_row_cap: int = Field(default=50_000, ge=1, le=1_048_576)
+    fail_on_warning: bool = False
+
+    @field_validator("formats")
+    @classmethod
+    def _unique_formats(cls, value: list[str]) -> list[str]:
+        if len(value) != len(set(value)):
+            raise ValueError("outputs.formats contains duplicates")
+        return value
+
+
+class MetaConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    allow_unknown_fields: bool = False
+
+
+class RosterConfig(BaseModel):
+    """Root configuration document (``version: 1``)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    version: Literal[1] = 1
+    data: DataConfig = Field(default_factory=DataConfig)
+    dates: DatesConfig = Field(default_factory=DatesConfig)
+    policies: Policies = Field(default_factory=Policies)
+    rules: list[RuleOverride] = Field(default_factory=list)
+    inputs: dict[str, InputRoleConfig] = Field(default_factory=dict)
+    outputs: OutputsConfig = Field(default_factory=OutputsConfig)
+    meta: MetaConfig = Field(default_factory=MetaConfig)
+
+    @model_validator(mode="after")
+    def _cross_validate(self) -> RosterConfig:
+        unknown = set(self.__pydantic_extra__ or {})
+        if unknown and not self.meta.allow_unknown_fields:
+            raise ValueError(
+                f"unknown configuration field(s): {', '.join(sorted(unknown))} "
+                "(set meta.allow_unknown_fields: true to permit forward-compatible fields)"
+            )
+
+        for role, cfg in self.inputs.items():
+            if role not in KNOWN_INPUT_ROLES:
+                raise ValueError(
+                    f"unknown input role {role!r}; known roles: {', '.join(KNOWN_INPUT_ROLES)}"
+                )
+            allowed = ROLE_FIELDS[role]
+            for label, keys in (
+                ("columns", cfg.columns),
+                ("aliases", cfg.aliases),
+                ("value_maps", cfg.value_maps),
+                ("allowed_values", cfg.allowed_values),
+            ):
+                bad = sorted(set(keys) - allowed)
+                if bad:
+                    raise ValueError(
+                        f"inputs.{role}.{label}: unknown canonical field(s) for this role: "
+                        f"{', '.join(bad)}"
+                    )
+
+        seen: set[str] = set()
+        for override in self.rules:
+            if override.id in seen:
+                raise ValueError(f"duplicate rule override for {override.id!r}")
+            seen.add(override.id)
+            _validate_rule_params(override)
+        return self
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> RosterConfig:
+        """Build a config from a plain mapping, wrapping validation errors."""
+        if not isinstance(data, Mapping):
+            raise ConfigError(f"configuration root must be a mapping, got {type(data).__name__}")
+        try:
+            return cls.model_validate(dict(data))
+        except Exception as exc:  # pydantic ValidationError and validator ValueErrors
+            raise ConfigError(_format_validation_error(exc)) from exc
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> RosterConfig:
+        """Load a YAML configuration file with ``yaml.safe_load`` only."""
+        file_path = Path(path)
+        try:
+            text = file_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            raise ConfigError(f"configuration file not found: {file_path}") from None
+        except OSError as exc:
+            raise ConfigError(f"configuration file not readable: {file_path}: {exc}") from exc
+        except UnicodeDecodeError:
+            raise ConfigError(f"configuration file is not valid UTF-8: {file_path}") from None
+        try:
+            loaded = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise ConfigError(f"invalid YAML in {file_path}: {exc}") from exc
+        if loaded is None:
+            raise ConfigError(f"configuration file is empty: {file_path}")
+        if not isinstance(loaded, Mapping):
+            raise ConfigError(
+                f"configuration root must be a mapping, got {type(loaded).__name__}: {file_path}"
+            )
+        return cls.from_dict(loaded)
+
+    @classmethod
+    def from_layers(cls, *layers: Mapping[str, Any]) -> RosterConfig:
+        """Merge raw configuration layers left-to-right (later wins), then validate.
+
+        Precedence: built-in defaults are applied by the schema itself, so the
+        first layer is the config file and subsequent layers are CLI overrides.
+        """
+        merged: dict[str, Any] = {}
+        for layer in layers:
+            merged = _merge_dicts(merged, dict(layer))
+        return cls.from_dict(merged)
+
+    def resolved_dict(self) -> dict[str, Any]:
+        """JSON-serializable view of the fully resolved configuration."""
+        return self.model_dump(mode="json")
+
+    def rule_overrides(self) -> dict[str, RuleOverride]:
+        """Rule overrides indexed by rule ID."""
+        return {override.id: override for override in self.rules}
+
+    def severity_for(self, rule_id: str) -> Severity:
+        """Effective severity for a rule (override or default)."""
+        override = self.rule_overrides().get(rule_id)
+        if override is not None and override.severity is not None:
+            return override.severity
+        return get_rule(rule_id).default_severity
+
+    def is_enabled(self, rule_id: str) -> bool:
+        """Effective enabled state for a rule (override or default)."""
+        override = self.rule_overrides().get(rule_id)
+        if override is not None:
+            return override.enabled
+        return True
+
+
+def _validate_rule_params(override: RuleOverride) -> None:
+    spec = get_rule(override.id)
+    for key, value in override.params.items():
+        if key not in spec.params:
+            raise ValueError(
+                f"rule {override.id}: unknown parameter {key!r} "
+                f"(declared: {', '.join(sorted(spec.params)) or 'none'})"
+            )
+        expected = spec.params[key]
+        if not _matches_type(value, expected):
+            raise ValueError(
+                f"rule {override.id}: parameter {key!r} must be "
+                f"{getattr(expected, '__name__', expected)}, got {type(value).__name__}"
+            )
+
+
+def _matches_type(value: object, expected: type) -> bool:
+    if expected is bool:
+        return isinstance(value, bool)
+    if expected is int:
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected is float:
+        return isinstance(value, int | float) and not isinstance(value, bool)
+    if expected is str:
+        return isinstance(value, str)
+    return True
+
+
+def _merge_dicts(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    """Recursive merge; nested dicts merge, all other values replace."""
+    result = dict(base)
+    for key, value in override.items():
+        existing = result.get(key)
+        if isinstance(existing, Mapping) and isinstance(value, Mapping):
+            result[key] = _merge_dicts(dict(existing), value)
+        else:
+            result[key] = value
+    return result
+
+
+def _format_validation_error(exc: Exception) -> str:
+    """Compact pydantic errors into actionable single-line messages."""
+    errors = getattr(exc, "errors", None)
+    if callable(errors):
+        parts = []
+        for err in errors():
+            location = ".".join(str(item) for item in err.get("loc", ()))
+            message = err.get("msg", str(exc))
+            parts.append(f"{location}: {message}" if location else message)
+        if parts:
+            return "; ".join(parts)
+    return str(exc)

rosterops/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain primitives: intervals, employment episodes, and date semantics."""