Skip to main content

Module runner

cortex_memory::decay

Module runner 

Source
Expand description

Phase 4.D decay job runner.

§Contract

  • Atomic: the Pending -> InProgress claim and the InProgress -> Completed | Failed settle happen via DecayJobRepo::update_state calls. The substrate refuses no-op updates (no matching row → hard error), so a stale claim surfaces rather than silently dropping. The substrate does NOT today CAS on prior state; the runner protects against double-claim by only proceeding when it has just observed Pending (loaded then immediately transitioned).
  • Idempotent: re-running a terminal (Completed, Failed, Cancelled) job is a no-op (run_specific_job returns Ok without re-dispatching). The Pending surface (run_next_pending_job) returns Ok(None) when the queue is empty.
  • Fail-closed: any error inside the dispatched method transitions the job to Failed with the error’s stable invariant (when one exists) or its Display text otherwise. The runner never leaves a job stuck in InProgress on a normal error path.
  • Observable: every stage emits a diagnostic line on stderr under a stable prefix (cortex_memory::decay::runner) so operators can tail logs without parsing JSON envelopes.

§Why “now” is a parameter

The runner takes an explicit now: DateTime<Utc> for the scheduling window. The CLI and dispatcher both pass Utc::now() in production; tests pass a frozen timestamp so the pending-pickup query is deterministic.

Functions§

run_next_pending_job
Run the next pending decay job whose scheduled_for <= now, if any.
run_next_pending_job_with_attestation
Variant of run_next_pending_job that allows the caller to supply an operator-attestation path for the next-pending LLM-summary job. The dequeue path itself does not select on summary method, so the attestation is only consumed if the next picked job turns out to be an LLM-summary job; deterministic jobs ignore it.
run_specific_job
Run a specific decay job by id.
run_specific_job_with_attestation
Variant of run_specific_job that allows the caller to supply an operator-attestation path for the dispatched job. Required when the resolved job is an LLM-summary job; deterministic jobs ignore it.