Module catalog 

Catalog-backed startup API for keeping handlers, job definitions, schedules, and workflow steps aligned.

JobCatalog is the primary facade. Applications register handlers once, sync the catalog’s definition defaults to PostgreSQL, and use the catalog helpers to build enqueue, schedule, and workflow inputs with job-type validation at the call site.

Catalog defaults apply to every registered entry unless a job is registered with job-specific definition overrides.

Schedule APIs

Choose a schedule API by who owns the schedule definition:

• Use JobCatalog::schedule plus JobCatalog::sync_schedules for static schedules registered in the worker catalog next to their handler.
• Use JobCatalog::sync_schedules_with for schedule specs assembled at startup from config, feature flags, tenants, or another source outside the builder chain.
• Use JobCatalog::sync_schedules_exact or JobCatalog::sync_schedules_exact_with when this deployment owns a bounded schedule-name scope and missing schedules in that scope should be deactivated. Exact sync takes a bounded table lock so overlapping startup syncs do not interleave their active sets; scheduler claims and fire-cursor updates can briefly wait behind the same lock. During rolling deploys, keep scopes narrow enough that old and new workers do not deactivate each other’s schedules unintentionally, and keep owned scopes deployment-stable. Feature-flagged schedules should usually remain registered with is_active: false rather than disappear from the scope.
• Use JobCatalog::job_schedule plus runledger_postgres::jobs::upsert_job_schedule for one-off setup, migrations, admin tools, or schedules that should not be catalog-owned. Call runledger_postgres::jobs::set_job_schedule_active separately to change active state on an existing lower-level schedule.

JobCatalog::schedule_sync_scope derives an exact-sync scope from schedules registered on the catalog, so startup code does not need to repeat those names. If a deployment needs both registered schedules and dynamic startup specs in one exact source-of-truth set, build one explicit spec list and scope for JobCatalog::sync_schedules_exact_with; Runledger does not provide an implicit union helper because that can hide ownership mistakes.

Structs

CatalogJobEnqueueInput

Input for building a JobEnqueue from a catalog-backed job type.

CatalogJobScheduleInput

Input for building a one-off JobScheduleUpsert from a catalog-backed job type.

CatalogJobScheduleSpec

Catalog-owned cron schedule definition synced to job_schedules at startup.

CatalogWorkflowDagBuilder

Workflow DAG builder that validates job types against a JobCatalog.

JobCatalog

Single-source registry of job handlers, definition defaults, schedules, and enqueue helpers.

JobCatalogDefaults

Default values applied when syncing catalog jobs to job_definitions.

JobCatalogDefinitionOverrides

Per-job definition values that override JobCatalogDefaults.

JobCatalogExactSyncReport

Result returned by JobCatalog::sync_definitions_exact.

JobCatalogScheduleSyncReport

Result returned by catalog schedule sync methods.

JobCatalogScheduleSyncScope

Explicit owned schedule-name scope used by exact catalog schedule sync.

JobCatalogSyncReport

Result returned by JobCatalog::sync_definitions.

JobCatalogSyncScope

Explicit owned job-type scope used by JobCatalog::sync_definitions_exact.

Enums

CatalogError

Error returned by super::JobCatalog validation, sync, and helper methods.