Skip to content

"Vibe-Trading: Your Personal Trading Agent"

refactor(scheduling): tighten kernel package and guard surfaces after review

shadowinlife9f31df1244e3
diff --git a/agent/cli/commands/research_playbook.py b/agent/cli/commands/research_playbook.py
index 1c2adbc33..4b1f4acf0 100644
--- a/agent/cli/commands/research_playbook.py
+++ b/agent/cli/commands/research_playbook.py
@@ -49,11 +49,6 @@ _HELP_TOKENS = frozenset({"help", "-h", "--help", "?"})
_LIST_TOKENS = frozenset({"list", "ls", "all"})
_VAR_TOKEN_RE = re.compile(r"^([A-Za-z0-9_]+)=(.*)$")
-# Mirrors ``_SAFE_JOB_ID_RE`` in src/api/scheduled_routes.py, which the REST
-# playbook route enforces on a caller-supplied id. The CLI writes the store
-# directly and bypasses every route, so the same rule has to be enforced here.
-_SAFE_JOB_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
-
# Defensive ceilings. ``ResearchPlaybook.render`` already caps a single
# substituted value at 4000 chars; these bound the *number* of tokens and the
# raw argument string so a paste accident cannot make the CLI do silly work
@@ -198,17 +193,21 @@ def build_job_from_playbook(
from src.scheduled_research.playbooks import build_job
if job_id:
- from src.scheduling.system_jobs import is_system_job_id
+ # The CLI writes the store directly and bypasses every route, so the
+ # shared id rule the REST surfaces enforce has to be enforced here.
+ from src.scheduling.system_jobs import (
+ JOB_ID_RULE_MESSAGE,
+ is_safe_job_id,
+ is_system_job_id,
+ )
if is_system_job_id(job_id):
return None, (
f"job id {job_id!r} is reserved for protected system jobs; "
"the 'system:' prefix cannot be authored"
)
- if not _SAFE_JOB_ID_RE.fullmatch(job_id):
- return None, (
- "job id must be 1-128 characters of letters, digits, '_' or '-'"
- )
+ if not is_safe_job_id(job_id):
+ return None, JOB_ID_RULE_MESSAGE
kwargs: Dict[str, Any] = {
"variables": variables or {},
diff --git a/agent/src/api/scheduled_guards.py b/agent/src/api/scheduled_guards.py
new file mode 100644
index 000000000..f3eaaeb4d
--- /dev/null
+++ b/agent/src/api/scheduled_guards.py
@@ -0,0 +1,63 @@
+"""HTTP guards for the scheduled-runs routes (scheduler unification).
+
+Extracted from ``scheduled_routes.py`` so the system-job mutation rules and
+the authorable-job-id rule live in one module instead of growing the routes
+file (which is already over the repo's 800-line hard cap). Each guard raises
+the ``HTTPException`` the route would have raised; the routes stay thin
+one-line calls. The domain predicates and the shared id grammar come from
+:mod:`src.scheduling.system_jobs` — this module adds only the HTTP mapping.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import HTTPException
+
+from src.scheduling.system_jobs import JOB_ID_RULE_MESSAGE, is_safe_job_id, is_system_job_id
+
+
+def ensure_authorable_job_id(job_id: Optional[str]) -> None:
+ """Reject a caller-supplied job id the address-based routes could not serve.
+
+ A job whose id the delete/patch routes would refuse (anything outside
+ :data:`~src.scheduling.system_jobs.SAFE_JOB_ID_RE`, including every
+ ``system:``-prefixed id) can never be cancelled or edited through the
+ API, so the id is held to that same rule at creation rather than at
+ first attempted delete. ``None`` (no explicit id) is accepted.
+
+ Raises:
+ HTTPException: 422 when *job_id* is present and not authorable.
+ """
+ if job_id is not None and not is_safe_job_id(job_id):
+ raise HTTPException(status_code=422, detail=JOB_ID_RULE_MESSAGE)
+
+
+def guard_system_job_mutation(job_id: str, source_type: str) -> None:
+ """Refuse to modify a protected system job.
+
+ Defense in depth for non-REST callers (CLI, internal services, future
+ entry points). UNREACHABLE via REST: every system job id carries ':'
+ (SYSTEM_JOB_ID_PREFIX), which the host path-parameter validation rejects
+ with a 400 before the store is even read — the REST-visible behavior for
+ a system job is that 400, not this 403.
+
+ Raises:
+ HTTPException: 403 when the row is a system job by id or source.
+ """
+ if is_system_job_id(job_id) or source_type == "system":
+ raise HTTPException(status_code=403, detail="system jobs cannot be modified")
+
+
+def guard_system_job_deletion(job_id: str) -> None:
+ """Refuse to delete a protected system job.
+
+ Defense in depth, same contract as :func:`guard_system_job_mutation`:
+ via REST the ':' in every system id already fails path-parameter
+ validation with a 400 before this guard runs.
+
+ Raises:
+ HTTPException: 403 when *job_id* is a system job id.
+ """
+ if is_system_job_id(job_id):
+ raise HTTPException(status_code=403, detail="system jobs cannot be deleted")
diff --git a/agent/src/api/scheduled_routes.py b/agent/src/api/scheduled_routes.py
index 1ef07d551..eef64155e 100644
--- a/agent/src/api/scheduled_routes.py
+++ b/agent/src/api/scheduled_routes.py
@@ -6,7 +6,6 @@ Mounted by ``agent/api_server.py`` via ``register_scheduled_routes(app, ...)``.
from __future__ import annotations
import logging
-import re
import sys as _sys
import time
import uuid
@@ -32,11 +31,6 @@ logger = logging.getLogger(__name__)
_SCHEDULED_RESEARCH_SCHEDULER_ENV = "VIBE_TRADING_ENABLE_SCHEDULER"
_SCHEDULED_RESEARCH_TRUE_VALUES = {"1", "true", "yes", "on"}
-# Mirrors ``_SAFE_PATH_PARAM_RE`` in src/api/helpers.py, which the delete route
-# enforces on the job id. Kept in sync so a job can never be created under an
-# id the delete route refuses.
-_SAFE_JOB_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
-
# ---------------------------------------------------------------------------
# Module-level state
@@ -90,22 +84,6 @@ async def _dispatch_scheduled_research_job(job) -> Optional[str]:
return session.session_id
-def _resolve_scheduled_internal_callable(job: "ScheduledResearchJob"):
- """Resolve one internal job's callable through the registry allowlist.
-
- Production ``internal_dispatcher`` for the singleton executor: a pure
- exact-key lookup in :mod:`src.scheduling.registry` — no import paths, no
- string parsing, no shell. Any failure (unregistered or tampered
- ``internal_callable`` name, malformed shape) raises and routes the
- firing into the executor's dispatch-failure path. The executor runs the
- returned zero-arg callable off the tick loop (``asyncio.to_thread`` when
- sync, direct await when async) in a fire-and-forget background task.
- """
- from src.scheduling.registry import resolve_internal
-
- return resolve_internal(job.internal_callable)
-
-
def _read_scheduled_briefing(session_id: str) -> Optional[tuple[str, str]]:
"""Return ``(terminal status, briefing text)`` once a run has finished.
@@ -179,6 +157,7 @@ def _get_scheduled_research_executor():
global _scheduled_research_executor
if _scheduled_research_executor is None:
from src.scheduled_research.executor import ScheduledResearchExecutor
+ from src.scheduled_research.internal_dispatch import resolve_scheduled_internal_callable
_scheduled_research_executor = ScheduledResearchExecutor(
_get_scheduled_research_store(),
@@ -186,7 +165,7 @@ def _get_scheduled_research_executor():
enabled=_scheduled_research_scheduler_enabled(),
briefing_reader=_read_scheduled_briefing,
channel_sender=_send_scheduled_briefing,
- internal_dispatcher=_resolve_scheduled_internal_callable,
+ internal_dispatcher=resolve_scheduled_internal_callable,
)
return _scheduled_research_executor
@@ -194,20 +173,10 @@ def _get_scheduled_research_executor():
def _start_scheduled_research_executor() -> None:
"""Start scheduled research execution when explicitly enabled.
- Single-writer invariant (scheduler-unification T12): the FastAPI lifespan
- (``api_server._run_startup_preflight``) is the SOLE owner of this call —
- the executor's kernel task is started exactly once per process, and the
- store behind it has exactly one writer. Multi-process concurrent writes
- are not supported (see the ``src/scheduled_research/store.py`` module
- docstring); a duplicate ``start()`` in the same process is a no-op.
-
- Startup order fulfills the system-job timing contract (i)
- (:mod:`src.scheduling.system_jobs`): ``ensure_system_jobs`` reconciles
- every enabled protected system job into the store BEFORE ``start()``
- creates the kernel task, so the first tick can never observe a store
- missing its system rows. When the master flag is off this early-returns
- before any write: CRUD keeps working, nothing executes, and no system
- row is seeded or store file created.
+ Single-writer invariant: the FastAPI lifespan is the SOLE owner of this
+ call (``src/scheduled_research/store.py``); a duplicate ``start()`` is a
+ no-op. ``ensure_system_jobs`` runs BEFORE ``start()`` (timing contract in
+ :mod:`src.scheduling.system_jobs`); master flag off early-returns.
"""
if not _scheduled_research_scheduler_enabled():
return
@@ -516,6 +485,8 @@ def register_scheduled_routes(
The job is persisted immediately. No execution is triggered.
"""
+ from src.api.scheduled_guards import ensure_authorable_job_id
+ from src.scheduled_research.executor import next_due
from src.scheduled_research.models import (
JobStatus,
ScheduledResearchJob,
@@ -525,19 +496,7 @@ def register_scheduled_routes(
validate_timezone_shape,
)
- from src.scheduled_research.executor import next_due
-
- # A job whose id the delete route rejects can never be cancelled
- # through the API, so the id is held to that same rule at creation
- # rather than at first attempted delete.
- if request.id is not None and not _SAFE_JOB_ID_RE.fullmatch(request.id):
- raise HTTPException(
- status_code=422,
- detail=(
- "job id must be 1-128 characters of letters, digits, "
- "'_' or '-'"
- ),
- )
+ ensure_authorable_job_id(request.id)
if contains_pdf_password(request.config):
raise HTTPException(status_code=422, detail="config must not include pdf_password")
@@ -692,6 +651,7 @@ def register_scheduled_routes(
request: UpdateScheduledRunRequest,
) -> ScheduledRunResponse:
"""Update future configuration without deleting the job or its history."""
+ from src.api.scheduled_guards import guard_system_job_mutation
from src.scheduled_research.executor import next_due
from src.scheduled_research.models import (
DeliveryRecord,
@@ -703,8 +663,6 @@ def register_scheduled_routes(
validate_timezone_shape,
)
- from src.scheduling.system_jobs import is_system_job_id
-
_host_validate_path_param(job_id, "job_id")
store = _get_scheduled_research_store()
job = store.get(job_id)
@@ -712,15 +670,7 @@ def register_scheduled_routes(
raise HTTPException(
status_code=404, detail=f"scheduled run {job_id} not found"
)
- # Defense in depth for non-REST callers (CLI, internal services,
- # future entry points). UNREACHABLE via REST: every system job id
- # carries ':' (SYSTEM_JOB_ID_PREFIX), which _validate_path_param
- # above rejects with a 400 before the store is even read — the
- # REST-visible behavior for a system job is that 400, not this 403.
- if is_system_job_id(job.id) or job.source_type == "system":
- raise HTTPException(
- status_code=403, detail="system jobs cannot be modified"
- )
+ guard_system_job_mutation(job.id, job.source_type)
if job.status == JobStatus.RUNNING or job.delivery.status == DeliveryStatus.SENDING:
raise HTTPException(
status_code=409,
@@ -893,18 +843,10 @@ def register_scheduled_routes(
)
async def delete_scheduled_run(job_id: str) -> Response:
"""Cancel (delete) a scheduled research job by id."""
- from src.scheduling.system_jobs import is_system_job_id
+ from src.api.scheduled_guards import guard_system_job_deletion
_host_validate_path_param(job_id, "job_id")
- # Defense in depth for non-REST callers (CLI, internal services,
- # future entry points). UNREACHABLE via REST: every system job id
- # carries ':' (SYSTEM_JOB_ID_PREFIX), which _validate_path_param
- # above rejects with a 400 before this guard runs — the REST-visible
- # behavior for a system job is that path-parameter 400, not this 403.
- if is_system_job_id(job_id):
- raise HTTPException(
- status_code=403, detail="system jobs cannot be deleted"
- )
+ guard_system_job_deletion(job_id)
removed = _get_scheduled_research_store().delete(job_id)
if not removed:
raise HTTPException(
diff --git a/agent/src/br_data/scheduling.py b/agent/src/br_data/scheduling.py
index 54fc10f25..cb0eab483 100644
--- a/agent/src/br_data/scheduling.py
+++ b/agent/src/br_data/scheduling.py
@@ -1,7 +1,7 @@
-"""Scheduled Brazilian dataset sync (scheduler-unification T9).
+"""Scheduled Brazilian dataset sync (scheduler unification).
Thin domain surface consumed by the scheduler, mirroring
-:mod:`src.memory.consolidation` (T8): it adds NO sync semantics of its own —
+:mod:`src.memory.consolidation`: it adds NO sync semantics of its own —
every behavior lives in :mod:`src.br_data.sync` and this module only decides
*whether* and *when* the protected system job runs:
@@ -11,21 +11,25 @@ every behavior lives in :mod:`src.br_data.sync` and this module only decides
:func:`src.config.accessor.get_env_config` — the sanctioned config path.
The flag defaults to ``False`` and belongs to no preset, so turning the
scheduler on never silently seeds a daily network-sync job.
-* :func:`daily_cron_from_env` derives the spec's 5-field cron schedule from
- the pre-existing ``VIBE_BR_SYNC_TIME`` (``DataConfig.vibe_br_sync_time``,
- "HH:MM" on the ``sync.TZ`` São Paulo wall clock; default "21:30" →
- ``"30 21 * * *"``), parsed by ``sync._next_run`` — the "HH:MM"→cron-field
- parser repurposed from the retired daemon. It NEVER raises: an invalid
+* :func:`daily_cron_from_env` is the spec's ``schedule_fn``: it derives the
+ 5-field cron schedule from the pre-existing ``VIBE_BR_SYNC_TIME``
+ (``DataConfig.vibe_br_sync_time``, "HH:MM" on the ``sync.TZ`` São Paulo
+ wall clock; default "21:30" → ``"30 21 * * *"``), parsed by
+ ``sync._next_run`` — the "HH:MM"→cron-field parser repurposed from the
+ retired daemon. It is evaluated lazily inside ``ensure_system_jobs`` (at
+ lifespan startup, after dotenv load) — never at import time, which would
+ freeze the value before ``.env`` is read. It NEVER raises: an invalid
value ("25:99" / "" / "abc") falls back to :data:`DEFAULT_DAILY_CRON` with
- a warning (plan T9, pinned choice), because it is evaluated at
- ``system_jobs`` module-build time and an import-time crash would take the
- whole API server down over one typo'd env var.
+ a warning, so one typo'd env var can never take the API server down.
Seed-time-only contract: ``ensure_system_jobs`` seeds a row once and a VALID
edited schedule/timezone on that row is trusted afterwards (the system_jobs
-(β) boundary), so ``VIBE_BR_SYNC_TIME`` drives the FIRST seed only — later
-changes need a PATCH of the stored row (or deleting it and restarting), not
-just an env edit.
+local-trust boundary), so ``VIBE_BR_SYNC_TIME`` drives the FIRST seed only.
+The row is a protected system job — REST/CLI PATCH and DELETE refuse it — so
+retiming an existing seed means editing the ``schedule`` field of the stored
+row in the store JSON file (a valid edited schedule is trusted at the next
+startup), or deleting the row from that file and restarting to re-seed from
+the env value.
The runnable itself is ``sync.run_sync``, registered under the literal key
``"br_data.run_sync"`` in :mod:`src.scheduling.registry`. It is SYNC by
@@ -64,10 +68,10 @@ def sync_job_enabled() -> bool:
def daily_cron_from_env() -> str:
"""Derive the daily cron (``"M H * * *"``) from ``VIBE_BR_SYNC_TIME``.
- Evaluated at ``system_jobs`` module-build time, so it must NEVER raise:
- any value ``sync._next_run`` cannot parse as an in-range "HH:MM" falls
- back to :data:`DEFAULT_DAILY_CRON` with a warning (plan T9 pinned
- choice).
+ Evaluated lazily at ``ensure_system_jobs`` time (the spec's
+ ``schedule_fn``), so it must NEVER raise: any value ``sync._next_run``
+ cannot parse as an in-range "HH:MM" falls back to
+ :data:`DEFAULT_DAILY_CRON` with a warning.
Returns:
A 5-field cron string, e.g. ``"30 21 * * *"`` for the default
diff --git a/agent/src/scheduled_research/executor.py b/agent/src/scheduled_research/executor.py
index 1216902c7..698c45667 100644
--- a/agent/src/scheduled_research/executor.py
+++ b/agent/src/scheduled_research/executor.py
@@ -241,7 +241,6 @@ class ScheduledResearchExecutor:
retry_base_delay_ms=self._retry_base_delay_ms,
retry_max_delay_ms=self._retry_max_delay_ms,
on_tick=self._on_kernel_tick,
- is_due_fn=is_due,
task_name="scheduled-research-executor",
)
self._internal = InternalRunSupervisor(
diff --git a/agent/src/scheduled_research/internal_dispatch.py b/agent/src/scheduled_research/internal_dispatch.py
index c293e572c..053f73b03 100644
--- a/agent/src/scheduled_research/internal_dispatch.py
+++ b/agent/src/scheduled_research/internal_dispatch.py
@@ -1,7 +1,7 @@
"""Fire-and-forget supervision for registry-backed internal jobs.
-Extracted beside the scheduled-research executor (scheduler unification T5)
-so ``executor.py`` stays under its 800-line cap; the semantics ARE the
+Extracted beside the scheduled-research executor (scheduler unification) so
+``executor.py`` stays under its 800-line cap; the semantics ARE the
executor's internal-dispatch contract:
* Resolve synchronously through the injected dispatcher — in production an
@@ -29,6 +29,15 @@ executor's internal-dispatch contract:
``recover_stale_running`` resets it to PENDING for a fresh firing.
Internal callables must therefore be safe to re-run. ``stop()`` never
waits for those threads, so it stays bounded.
+* HONEST process-exit caveat: ``asyncio.to_thread`` runs on the loop's
+ default ``ThreadPoolExecutor``, whose non-daemon worker threads are joined
+ during interpreter finalization. A sync internal run still in flight (an
+ hours-long ``br_data`` sync, say) can therefore stall graceful process
+ exit past ``stop()`` until the orchestrator's kill timeout (compose's
+ ``stop_grace_period``) escalates to SIGKILL. That is safe by the contract
+ above — the job stays RUNNING for stale-recovery, store writes are atomic
+ (tmp + ``os.replace``) and the sync's SQLite writes are crash-safe — but
+ "bounded stop" covers ``stop()`` itself, not interpreter finalization.
"""
from __future__ import annotations
@@ -51,6 +60,23 @@ FinishRunFn = Callable[[ScheduledResearchJob, Optional[Exception], int], None]
InternalDispatchCallback = Callable[[ScheduledResearchJob], InternalRunnable]
+def resolve_scheduled_internal_callable(job: ScheduledResearchJob) -> InternalRunnable:
+ """Resolve one internal job's callable through the registry allowlist.
+
+ Production ``internal_dispatcher`` for the singleton executor (wired in
+ ``src/api/scheduled_routes.py``): a pure exact-key lookup in
+ :mod:`src.scheduling.registry` — no import paths, no string parsing, no
+ shell. Any failure (unregistered or tampered ``internal_callable`` name,
+ malformed shape) raises and routes the firing into the executor's
+ dispatch-failure path. The supervisor runs the returned zero-arg callable
+ off the tick loop (``asyncio.to_thread`` when sync, direct await when
+ async) in a fire-and-forget background task.
+ """
+ from src.scheduling.registry import resolve_internal
+
+ return resolve_internal(job.internal_callable)
+
+
class InternalRunSupervisor:
"""Owns the non-blocking run lifecycle of ``executor_kind="internal"`` jobs.
diff --git a/agent/src/scheduled_research/models.py b/agent/src/scheduled_research/models.py
index 25ddd1d1c..68e3352f3 100644
--- a/agent/src/scheduled_research/models.py
+++ b/agent/src/scheduled_research/models.py
@@ -27,6 +27,7 @@ from src.scheduling.triggers import (
validate_timezone as validate_timezone,
validate_timezone_shape as validate_timezone_shape,
)
+from src.scheduling.types import ExecutorKind, is_executor_kind
logger = logging.getLogger(__name__)
@@ -245,7 +246,7 @@ class ScheduledResearchJob:
# quarantines the whole file as ``.corrupt-<ts>`` (data preserved, not
# loaded). Downgrading to a version before scheduler-unification requires
# removing system job rows first.
- executor_kind: str = "prompt"
+ executor_kind: ExecutorKind = "prompt"
internal_callable: Optional[str] = None
end_at: Optional[int] = None
next_run_at: int = field(default_factory=lambda: int(time.time() * 1000))
@@ -383,7 +384,7 @@ class ScheduledResearchJob:
# dispatching the (possibly empty) prompt.
executor_kind = data.get("executor_kind", "prompt")
internal_callable = data.get("internal_callable")
- if executor_kind not in {"prompt", "internal"}:
+ if not is_executor_kind(executor_kind):
raise ValueError("'executor_kind' must be 'prompt' or 'internal'")
if internal_callable is not None and not isinstance(internal_callable, str):
raise TypeError("'internal_callable' must be a string or null")
diff --git a/agent/src/scheduled_research/service.py b/agent/src/scheduled_research/service.py
index 867f87353..b8cd8de6e 100644
--- a/agent/src/scheduled_research/service.py
+++ b/agent/src/scheduled_research/service.py
@@ -2,7 +2,6 @@
from __future__ import annotations
-import re
import sys
import time
import uuid
@@ -21,13 +20,7 @@ from src.scheduled_research.models import (
)
from src.scheduled_research.playbooks import get_playbook
from src.scheduled_research.store import ScheduledResearchJobStore
-from src.scheduling.system_jobs import is_system_job_id
-
-# Mirrors ``_SAFE_JOB_ID_RE`` in src/api/scheduled_routes.py (and the
-# ``_SAFE_PATH_PARAM_RE`` the DELETE/PATCH routes enforce on the job id).
-# A draft id outside this rule — including every ``system:``-prefixed id —
-# could be persisted but never addressed, deleted or edited through the API.
-_SAFE_JOB_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+from src.scheduling.system_jobs import JOB_ID_RULE_MESSAGE, is_safe_job_id, is_system_job_id
def public_job(job: ScheduledResearchJob) -> dict[str, Any]:
@@ -155,10 +148,8 @@ def build_job_from_draft(
f"job id {draft_id!r} is reserved for protected system jobs; "
"the 'system:' prefix cannot be authored"
)
- if not _SAFE_JOB_ID_RE.fullmatch(draft_id):
- raise ValueError(
- "job id must be 1-128 characters of letters, digits, '_' or '-'"
- )
+ if not is_safe_job_id(draft_id):
+ raise ValueError(JOB_ID_RULE_MESSAGE)
title = str(draft.get("title") or "").strip()
if not title:
raise ValueError("title is required")
diff --git a/agent/src/scheduling/__init__.py b/agent/src/scheduling/__init__.py
index 4f7d75774..a4428d31b 100644
--- a/agent/src/scheduling/__init__.py
+++ b/agent/src/scheduling/__init__.py
@@ -7,23 +7,21 @@ in the repo can adopt:
(interval-ms + 5-field cron + IANA timezones with the DST gap-skip /
fold=0 policy) and next-run math, plus the ``once`` trigger kind absorbed
from the live runtime scheduler (provided for future adoption; not wired).
-* :mod:`src.scheduling.types` — the shared vocabulary: ``ExecutorKind``,
- the minimal ``JobLike`` protocol, ``TriggerSpec`` and the kernel callback
- type aliases.
+* :mod:`src.scheduling.types` — the shared vocabulary: ``ExecutorKind`` with
+ its closed runtime domain, and the kernel callback type aliases.
* :mod:`src.scheduling.kernel` — ``SchedulerKernel``: the generic tick loop
with ``asyncio.Event`` wakeup, bounded exponential backoff, an injectable
- clock and callback seams for domain logic (consumed by the scheduled
- research executor since T4).
+ clock and the ``on_tick`` seam for domain logic (consumed by the scheduled
+ research executor).
* :mod:`src.scheduling.registry` — the internal-callable allowlist: an
explicit module-level dict mapping literal registry keys to zero-arg
sync/async callables, with exact-key resolution only (no dynamic import,
- no string parsing, no shell).
-
+ no string parsing, no shell) and deferred domain imports.
* :mod:`src.scheduling.system_jobs` — protected system jobs: the
``SystemJobSpec`` surface (``system:`` id prefix, ``source_type="system"``,
``executor_kind="internal"``, registry-key callable, per-spec enablement
predicate) and ``ensure_system_jobs`` — the idempotent startup
- seed/repair pass (tamper correction, (α) status reset, (β) schedule-trust
+ seed/repair pass (tamper correction, status reset, schedule-trust
boundary, repair-replay, flag-off halt) called from the lifespan before
the executor starts.
"""
@@ -63,21 +61,14 @@ from src.scheduling.triggers import (
)
from src.scheduling.types import (
EXECUTOR_KINDS,
- AdvanceFn,
ExecutorKind,
- IsDueFn,
- JobErrorFn,
- JobLike,
NowFn,
OnTickFn,
- TriggerSpec,
is_executor_kind,
)
__all__ = [
"CRON_BOUNDS",
- "EnabledPredicate",
- "EnsureSystemJobsReport",
"CRON_SEARCH_LIMIT_DAYS",
"DEFAULT_MAX_CONSECUTIVE_FAILURES",
"DEFAULT_RETRY_BASE_DELAY_MS",
@@ -87,24 +78,14 @@ __all__ = [
"DEFAULT_TRIGGER_INTERVAL_MS",
"EXECUTOR_KINDS",
"ONCE_SPEC",
- "AdvanceFn",
"ExecutorKind",
"InternalCallableError",
"InternalRunnable",
- "IsDueFn",
- "JobErrorFn",
- "JobLike",
"NowFn",
"OnTickFn",
- "SYSTEM_JOB_ID_PREFIX",
"SchedulerKernel",
- "SpecGate",
- "SystemJobSpec",
- "TriggerSpec",
"day_matches",
- "ensure_system_jobs",
"is_executor_kind",
- "is_system_job_id",
"is_interval_schedule",
"is_registered",
"list_internal",
@@ -115,11 +96,22 @@ __all__ = [
"parse_cron_field",
"register_internal",
"resolve_internal",
- "system_job_specs",
"trigger_interval_ms",
"validate_schedule",
"validate_timezone",
"validate_timezone_shape",
+ # Lazily resolved (PEP 562) — see the comment below.
+ "EnabledPredicate",
+ "EnsureSystemJobsReport",
+ "JOB_ID_RULE_MESSAGE",
+ "SAFE_JOB_ID_RE",
+ "SYSTEM_JOB_ID_PREFIX",
+ "SpecGate",
+ "SystemJobSpec",
+ "ensure_system_jobs",
+ "is_safe_job_id",
+ "is_system_job_id",
+ "system_job_specs",
]
# --- lazy re-export: src.scheduling.system_jobs (PEP 562) -------------------
@@ -132,12 +124,15 @@ __all__ = [
# while breaking the import-time cycle in every import order.
_SYSTEM_JOBS_EXPORTS = frozenset(
{
+ "JOB_ID_RULE_MESSAGE",
+ "SAFE_JOB_ID_RE",
"SYSTEM_JOB_ID_PREFIX",
"EnabledPredicate",
"EnsureSystemJobsReport",
"SpecGate",
"SystemJobSpec",
"ensure_system_jobs",
+ "is_safe_job_id",
"is_system_job_id",
"system_job_specs",
}
@@ -151,4 +146,3 @@ def __getattr__(name: str):
return getattr(system_jobs, name)
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
diff --git a/agent/src/scheduling/kernel.py b/agent/src/scheduling/kernel.py
index 26ad53e00..e46bcda5e 100644
--- a/agent/src/scheduling/kernel.py
+++ b/agent/src/scheduling/kernel.py
@@ -1,12 +1,11 @@
"""Generic scheduler kernel: tick loop, wakeup, backoff, injectable clock.
-Extracted (scheduler-unification T2) from the loop machinery of
-``src/scheduled_research/executor.py`` so every scheduler in the repo can
-share one tick/wakeup/backoff implementation. The kernel is strictly
-generic: it knows nothing about delivery outboxes, verdicts, briefings or
-playbooks — domain logic attaches through the constructor's callback seams
-(``on_tick`` / ``is_due_fn`` / ``advance_fn`` / ``on_job_error``) and stays
-in the consumer's module.
+Extracted from the loop machinery of ``src/scheduled_research/executor.py``
+(scheduler unification) so every scheduler in the repo can share one
+tick/wakeup/backoff implementation. The kernel is strictly generic: it knows
+nothing about delivery outboxes, verdicts, briefings or playbooks — domain
+logic attaches through the constructor's ``on_tick`` callback and stays in
+the consumer's module.
Responsibilities (the complete list):
@@ -40,13 +39,7 @@ import logging
import time
from typing import Optional
-from src.scheduling.types import (
- AdvanceFn,
- IsDueFn,
- JobErrorFn,
- NowFn,
- OnTickFn,
-)
+from src.scheduling.types import NowFn, OnTickFn
logger = logging.getLogger(__name__)
@@ -78,12 +71,9 @@ class SchedulerKernel:
propagates so :meth:`stop` stays bounded), then sleeps
``tick_interval_ms`` unless a :meth:`request_wake` shortens the sleep.
- ``is_due_fn`` / ``advance_fn`` / ``on_job_error`` are stored injection
- seams, exposed as read-only properties: the kernel never interprets them
- itself, but carrying the full callback set on one instance lets a
- consumer compose its ``on_tick`` chain (due-job pass, per-job isolation,
- error recording) against a single wiring point without reaching into
- kernel internals.
+ Due-ness, next-run advancement and per-job error recording are the
+ consumer's own ``on_tick`` composition — the kernel stores the retry
+ policy and exposes it read-only, but never interprets jobs itself.
"""
def __init__(
@@ -96,9 +86,6 @@ class SchedulerKernel:
retry_base_delay_ms: int = DEFAULT_RETRY_BASE_DELAY_MS,
retry_max_delay_ms: int = DEFAULT_RETRY_MAX_DELAY_MS,
on_tick: Optional[OnTickFn] = None,
- is_due_fn: Optional[IsDueFn] = None,
- advance_fn: Optional[AdvanceFn] = None,
- on_job_error: Optional[JobErrorFn] = None,
task_name: str = DEFAULT_TASK_NAME,
) -> None:
"""Initialize the kernel.
@@ -113,9 +100,6 @@ class SchedulerKernel:
retry_base_delay_ms: Base delay for exponential retry backoff.
retry_max_delay_ms: Upper bound for exponential retry backoff.
on_tick: Async callable invoked once per tick with ``now_ms``.
- is_due_fn: ``(job, now_ms) -> bool`` due-ness predicate seam.
- advance_fn: ``(job, from_ms) -> next_run_at | None`` seam.
- on_job_error: ``(job, now_ms, exc)`` per-job failure hook seam.
task_name: Name of the background ``asyncio`` task.
Raises:
@@ -134,9 +118,6 @@ class SchedulerKernel:
self._retry_base_delay_ms = retry_base_delay_ms
self._retry_max_delay_ms = retry_max_delay_ms
self._on_tick = on_tick
- self._is_due_fn = is_due_fn
- self._advance_fn = advance_fn
- self._on_job_error = on_job_error
self._task_name = task_name
self._loop: asyncio.AbstractEventLoop | None = None
self._task: asyncio.Task | None = None
@@ -180,21 +161,6 @@ class SchedulerKernel:
"""Return the injected per-tick callback (the only one the loop calls)."""
return self._on_tick
- @property
- def is_due_fn(self) -> Optional[IsDueFn]:
- """Return the injected due-ness predicate seam."""
- return self._is_due_fn
-
- @property
- def advance_fn(self) -> Optional[AdvanceFn]:
- """Return the injected next-run advancement seam."""
- return self._advance_fn
-
- @property
- def on_job_error(self) -> Optional[JobErrorFn]:
- """Return the injected per-job error hook seam."""
- return self._on_job_error
-
# -- lifecycle ------------------------------------------------------------
@property
diff --git a/agent/src/scheduling/registry.py b/agent/src/scheduling/registry.py
index 706ac0ff8..5c555d4db 100644
--- a/agent/src/scheduling/registry.py
+++ b/agent/src/scheduling/registry.py
@@ -1,8 +1,8 @@
"""Allowlist registry for internal scheduled callables (scheduler unification).
The ONLY name→callable mapping available to ``executor_kind == "internal"``
-jobs. Security contract (plan D4, user-confirmed — this is the safety
-bedrock, "no arbitrary shell, no dynamic import"):
+jobs. Security contract — this is the safety bedrock, "no arbitrary shell,
+no dynamic import":
* Keys are literal strings registered in THIS module. The production surface
is the explicit ``_INTERNAL_CALLABLES`` dict at the bottom, populated by
@@ -23,6 +23,15 @@ bedrock, "no arbitrary shell, no dynamic import"):
:mod:`src.scheduled_research.internal_dispatch`): sync callables are
offloaded through ``asyncio.to_thread``, async callables are awaited
directly, always in a background task — never on the serialized tick loop.
+* Domain imports are DEFERRED: each production entry is a literal zero-arg
+ wrapper whose body imports the domain callable at first firing. This
+ module is imported by the generic :mod:`src.scheduling` package (and,
+ through it, by ``scheduled_research.models``), so a top-level domain
+ import here would drag the whole ``br_data``/``memory`` stack into every
+ process that merely touches the scheduling vocabulary — and invert the
+ dependency direction of the generic kernel. The wrappers keep the dict
+ literal-keyed and exact-match-only; the deferred import is a fixed module
+ statement inside a function body, never a name-driven resolution.
"""
from __future__ import annotations
@@ -30,9 +39,6 @@ from __future__ import annotations
import re
from typing import Awaitable, Callable
-from src.br_data.sync import run_sync as _br_data_run_sync
-from src.memory.consolidation import consolidate as _memory_consolidate
-
#: A registered internal callable: invoked with no arguments, either sync
#: (return value discarded) or async. ``...`` tolerates defaulted/optional
#: parameters; the run contract above is what the executor guarantees.
@@ -59,7 +65,7 @@ class InternalCallableError(KeyError):
def _check_name(name: object) -> str:
"""Return *name* if it has the dotted-identifier shape, else reject it."""
- if not isinstance(name, str) or not _VALID_NAME_RE.match(name):
+ if not isinstance(name, str) or not _VALID_NAME_RE.fullmatch(name):
raise InternalCallableError(
f"internal callable name {name!r} is rejected: only dotted identifiers "
"(letters, digits, '_', single '.' separators) are allowed"
@@ -71,9 +77,9 @@ def register_internal(name: str, fn: InternalRunnable, *, replace: bool = False)
"""Register *fn* under the literal key *name*.
MODULE/TEST-ONLY: the production surface is the explicit dict entries at
- the bottom of this module, added by module edit (scheduler-unification
- T8/T9). No runtime input may reach this function — the invariant is
- documented here and guarded by ``test_registry.py``.
+ the bottom of this module, added by module edit. No runtime input may
+ reach this function — the invariant is documented here and guarded by
+ ``test_registry.py``.
Args:
name: Literal registry key (dotted-identifier shape).
@@ -127,25 +133,52 @@ def list_internal() -> tuple[str, ...]:
def is_registered(name: object) -> bool:
"""Whether *name* is a well-formed AND registered key. Never raises."""
- return isinstance(name, str) and bool(_VALID_NAME_RE.match(name)) and name in _INTERNAL_CALLABLES
+ return isinstance(name, str) and bool(_VALID_NAME_RE.fullmatch(name)) and name in _INTERNAL_CALLABLES
+
+
+# ---------------------------------------------------------------------------
+# Production entries — literal zero-arg wrappers with a deferred domain
+# import inside the function body (module docstring, "Domain imports are
+# DEFERRED"). The wrapper is the registered callable object; the import it
+# performs is a fixed statement, never derived from the registry key.
+# ---------------------------------------------------------------------------
+
+
+def _memory_consolidate() -> None:
+ """Run one scheduled memory-consolidation pass (deferred domain import).
+
+ Backs the ``memory.consolidate`` key: daily archive-only consolidation,
+ opt-in via ``VT_MEMORY_CONSOLIDATION`` and an honest no-op unless
+ ``VT_MEMORY_GC`` is on too (see :mod:`src.memory.consolidation`).
+ """
+ from src.memory.consolidation import consolidate
+
+ consolidate()
+
+
+def _br_data_run_sync() -> None:
+ """Run one Brazilian official-dataset sync (deferred domain import).
+
+ Backs the ``br_data.run_sync`` key: daily sync, opt-in via
+ ``VIBE_BR_SYNC_ENABLED``; replaces the retired ``src.br_data`` daemon —
+ per-source failures are reported in ``run_sync``'s return value, not
+ raised (see :mod:`src.br_data.scheduling`).
+ """
+ from src.br_data.sync import run_sync
+
+ run_sync()
# ---------------------------------------------------------------------------
# Production allowlist — the ONLY name→callable surface (module docstring).
#
-# Scheduler-unification T8/T9 appended the entries below by module edit; a
-# new entry is ONE top-level import of the callable object plus ONE literal
-# key here. Rules: literal keys only; values are imported callable objects,
+# A new entry is ONE literal wrapper function above plus ONE literal key
+# here. Rules: literal keys only; values are the wrapper callable objects,
# never import-path strings; nothing populates this dict from runtime input.
# An internal firing whose key is missing fail-closes into the executor's
# dispatch-failure path (``failure_kind="dispatch"``).
# ---------------------------------------------------------------------------
_INTERNAL_CALLABLES: dict[str, InternalRunnable] = {
- # T8: daily archive-only memory consolidation (opt-in via
- # VT_MEMORY_CONSOLIDATION; honest no-op unless VT_MEMORY_GC is on too).
"memory.consolidate": _memory_consolidate,
- # T9: daily Brazilian official-dataset sync (opt-in via
- # VIBE_BR_SYNC_ENABLED; replaces the retired ``src.br_data`` daemon —
- # per-source failures are reported in the return value, not raised).
"br_data.run_sync": _br_data_run_sync,
}
diff --git a/agent/src/scheduling/system_jobs.py b/agent/src/scheduling/system_jobs.py
index 7fb9c0a5c..550eb6d8b 100644
--- a/agent/src/scheduling/system_jobs.py
+++ b/agent/src/scheduling/system_jobs.py
@@ -1,72 +1,88 @@
-"""Protected system jobs: definitions and idempotent registration (T6).
+"""Protected system jobs: definitions and idempotent registration.
A *system job* is a built-in scheduled task the product owns end to end: its
row in the scheduled-research store is seeded and repaired by this module at
startup, it executes an in-process callable through the registry allowlist
-(:mod:`src.scheduling.registry`) — never a prompt dispatch — and, with T7's
-route/proposal/CLI guards landed, users cannot delete, rewrite or forge it
+(:mod:`src.scheduling.registry`) — never a prompt dispatch — and the
+route/proposal/CLI guards keep users from deleting, rewriting or forging it
through any API surface.
-Contracts implemented here (scheduler-unification plan todo 6, ③b):
+Contracts implemented here:
-* **(i) Timing** — :func:`ensure_system_jobs` runs from the ``api_server``
- lifespan BEFORE the executor's ``start()`` (T12 wires it), so every enabled
- system job is in the store before the first tick can run.
-* **(ii) Idempotence** — an existing row is never re-seeded: runtime fields
+* **Timing** — :func:`ensure_system_jobs` runs from the ``api_server``
+ lifespan BEFORE the executor's ``start()``, so every enabled system job is
+ in the store before the first tick can run.
+* **Idempotence** — an existing row is never re-seeded: runtime fields
(next_run_at/last_run_at/consecutive_failures/last_error/failure_kind/
created_at/config/title/prompt/delivery*) and a live status
(PENDING/RUNNING/COMPLETED) are left as they are; tampered spec-owned
- fields (source_type/executor_kind/internal_callable) ARE corrected.
-* **(ii-c) schedule trust boundary — plan choice (β), local trust** — a
- syntactically VALID user-edited ``schedule``/``timezone`` is LEFT ALONE:
- whoever can edit the store file could equally flip the env flags off, so
- local tampering is not a security boundary (win32 no-lock reasoning). An
- INVALID one IS repaired to the spec default: the validate=False repair
- write (ii-b) would otherwise persist garbage the executor could only mark
- FAILED (``failure_kind="schedule"``) — repair keeps "protected" functional.
-* **(α) status reset** — a system row found in CANCELLED or EXPIRED is reset
- to PENDING with ``end_at`` cleared. WHY safe: after T7 no API path (REST
- DELETE/PATCH, proposals, playbook/CLI) can put a system job there, so those
- states can only come from a manual store-file edit (or this module's own
- flag-off halt) — resetting makes "protected" true at the local-file layer.
- An enabled row's ``end_at`` is cleared even while PENDING: specs define no
- end boundary, and a hand-added future ``end_at`` would be honoured by
- ``_expire_elapsed_jobs`` mid-life — same tamper class. (For CHANGELOG/T13:
- manual file-edit cancellation is undone at the next startup.)
-* **(ii-b) repair writes** — every repair/halt write uses
+ fields (source_type/executor_kind/internal_callable) ARE corrected. The
+ one deliberate exception is the retry-budget reset below, which clears
+ ``consecutive_failures``/``last_error``/``failure_kind`` together with a
+ FAILED status it would be inconsistent to keep.
+* **Schedule trust boundary (local trust)** — a syntactically VALID
+ user-edited ``schedule``/``timezone`` is LEFT ALONE: whoever can edit the
+ store file could equally flip the env flags off, so local tampering is not
+ a security boundary (the same reasoning as the win32 no-lock memory
+ contract). An INVALID one IS repaired to the spec default: the
+ ``validate=False`` repair write would otherwise persist garbage the
+ executor could only mark FAILED (``failure_kind="schedule"``) — repair
+ keeps "protected" functional.
+* **Startup status reset** — a system row found in CANCELLED or EXPIRED is
+ reset to PENDING with ``end_at`` cleared. WHY safe: no API path (REST
+ DELETE/PATCH, proposals, playbook/CLI) can put a system job there, so
+ those states can only come from a manual store-file edit (or this module's
+ own flag-off halt) — resetting makes "protected" true at the local-file
+ layer. An enabled row's ``end_at`` is cleared even while PENDING: specs
+ define no end boundary, and a hand-added future ``end_at`` would be
+ honoured by ``_expire_elapsed_jobs`` mid-life — same tamper class.
+* **Retry-budget reset** — a system row found in FAILED (the executor's
+ terminal state after ``max_consecutive_failures`` consecutive dispatch
+ failures) is reset to PENDING with ``end_at`` cleared and
+ ``consecutive_failures``/``last_error``/``failure_kind`` zeroed, but ONLY
+ for an enabled spec. Without this, a transient multi-day outage would
+ permanently brick a product-owned job that no API surface may resurrect
+ (PATCH/DELETE refuse system ids by design). The reset is bounded: a
+ genuinely broken callable simply re-fails into FAILED within its retry
+ budget, and the reset itself happens once per process start. A DISABLED
+ spec leaves FAILED untouched — it is already never-due.
+* **Repair writes** — every repair/halt write uses
``store.upsert(job, validate=False)`` so a tampered row can never crash
startup; the fix is "correct + log" (the executor's lifecycle-write
convention — ``store.py`` upsert docstring).
-* **(iii) repair-replay** — a system job deleted from the store by hand is
+* **Repair-replay** — a system job deleted from the store by hand is
re-seeded at the next startup, else "protected" would be vacuous.
-* **(iv) DOUBLE-gate enablement chain** — a system job executes only when
- BOTH gates hold: the master switch ``VIBE_TRADING_ENABLE_SCHEDULER``
- (without it the executor never starts — ``scheduled_routes`` early-return)
- AND the job's own flag as the spec's ``enabled_predicate`` (T8/T9 bind
- predicates reading the env flags they declare; THIS MODULE READS NO
- ENVIRONMENT ITSELF — predicates are injected, keeping the env surface
- owned by the domain modules and the AST gate clean). Flag-off direction: a
- DISABLED spec with an existing row is halted — a runnable status
- (PENDING/RUNNING/COMPLETED) becomes CANCELLED so the never-due set excludes
- it; terminal statuses are untouched, and re-enabling undoes the halt via
- the (α) reset. A disabled spec with NO row writes nothing (plan QA (a)).
+* **DOUBLE-gate enablement chain** — a system job executes only when BOTH
+ gates hold: the master switch ``VIBE_TRADING_ENABLE_SCHEDULER`` (without
+ it the executor never starts — ``scheduled_routes`` early-return) AND the
+ job's own flag as the spec's ``enabled_predicate`` (the domain modules
+ bind predicates reading the env flags they declare; THIS MODULE READS NO
+ ENVIRONMENT ITSELF — predicates and schedule derivations are injected,
+ keeping the env surface owned by the domain modules and the AST gate
+ clean). Flag-off direction: a DISABLED spec with an existing row is
+ halted — a runnable status (PENDING/RUNNING/COMPLETED) becomes CANCELLED
+ so the never-due set excludes it; terminal statuses are untouched, and
+ re-enabling undoes the halt via the startup status reset. A disabled spec
+ with NO row writes nothing.
* **Registry independence** — seeding does NOT require ``internal_callable``
- to be registered. A seeded job whose key is unregistered fails at EXECUTION
- time in the supervisor's resolve step, recorded as
- ``failure_kind="dispatch"`` with a readable ``last_error`` (plan QA (c)) —
- never silently skipped, never prompt-dispatched.
-
-ID convention (T7): every system job id starts with ``system:`` — the colon
-is deliberately part of the convention because ``_SAFE_JOB_ID_RE``
-(``^[A-Za-z0-9_-]{1,128}$``, enforced on POST/playbook routes and in
-``_validate_path_param``) rejects ``:``, so forging or path-addressing a
-system id through those surfaces is structurally impossible.
-:func:`is_system_job_id` is the single prefix predicate T7's guards consume.
+ to be registered. A seeded job whose key is unregistered fails at
+ EXECUTION time in the supervisor's resolve step, recorded as
+ ``failure_kind="dispatch"`` with a readable ``last_error`` — never
+ silently skipped, never prompt-dispatched.
+
+ID convention: every system job id starts with ``system:`` — the colon is
+deliberately part of the convention because :data:`SAFE_JOB_ID_RE` (the
+single job-id shape rule every create/mutate surface enforces, matching the
+``_SAFE_PATH_PARAM_RE`` the host routes apply to path parameters) rejects
+``:``, so forging or path-addressing a system id through those surfaces is
+structurally impossible. :func:`is_system_job_id` is the single prefix
+predicate the guards consume.
"""
from __future__ import annotations
import logging
+import re
import time
from dataclasses import dataclass, field
from typing import Callable, Optional, Sequence
@@ -82,15 +98,34 @@ from src.scheduled_research.models import (
)
from src.scheduled_research.store import ScheduledResearchJobStore
from src.scheduling.triggers import is_interval_schedule, next_due
+from src.scheduling.types import ExecutorKind
logger = logging.getLogger(__name__)
-#: Mandatory id prefix. Contains ``:`` on purpose — ``_SAFE_JOB_ID_RE``
-#: rejects every id carrying it (module-docstring ID convention, T7).
+#: Mandatory id prefix. Contains ``:`` on purpose — :data:`SAFE_JOB_ID_RE`
+#: rejects every id carrying it (module-docstring ID convention).
SYSTEM_JOB_ID_PREFIX = "system:"
-#: Per-spec enablement gate (T8/T9 bind these to the env flags they declare).
+#: The single job-id shape rule, shared by every surface that authors or
+#: addresses a job id (REST create, playbook route, service drafts, CLI) and
+#: identical to the ``_SAFE_PATH_PARAM_RE`` the host routes enforce on path
+#: parameters, so a job can never be created under an id the address-based
+#: routes would refuse. Rejecting ``:`` is what makes
+#: :data:`SYSTEM_JOB_ID_PREFIX` unforgeable through user-facing surfaces.
+SAFE_JOB_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+#: Single home of the user-facing job-id rule wording (the REST 422 detail,
+#: the service ``ValueError`` and the CLI error string all quote it).
+JOB_ID_RULE_MESSAGE = "job id must be 1-128 characters of letters, digits, '_' or '-'"
+
+#: Per-spec enablement gate (the domain modules bind these to the env flags
+#: they declare).
EnabledPredicate = Callable[[], bool]
+#: Lazy per-spec schedule derivation, evaluated at :func:`ensure_system_jobs`
+#: time — after dotenv load — instead of at module import (same rationale as
+#: :data:`EnabledPredicate`; must return a schedule passing
+#: :func:`validate_schedule`).
+ScheduleFn = Callable[[], str]
#: Caller-level override gate for :func:`ensure_system_jobs`; receives the
#: spec, returns enablement.
SpecGate = Callable[["SystemJobSpec"], bool]
@@ -100,11 +135,21 @@ NowFn = Callable[[], int]
#: Statuses that keep a row executable by the tick loop (``is_due``'s
#: complement of the never-due set); a disabled spec halts exactly these.
_RUNNABLE_STATUSES = frozenset({JobStatus.PENDING, JobStatus.RUNNING, JobStatus.COMPLETED})
-#: Statuses only reachable (post-T7) via manual file edits or this module's
-#: own flag-off halt; (α) resets them when the spec is enabled again.
+#: Statuses only reachable via manual file edits or this module's own
+#: flag-off halt; the startup reset restores them when the spec is enabled.
_TAMPER_TERMINAL_STATUSES = frozenset({JobStatus.CANCELLED, JobStatus.EXPIRED})
+def is_safe_job_id(job_id: object) -> bool:
+ """Whether *job_id* is authorable through user-facing surfaces.
+
+ The single shape predicate behind every create/mutate guard; never
+ raises, non-strings are ``False``. Every ``system:``-prefixed id fails
+ by construction (the pattern rejects ``:``).
+ """
+ return isinstance(job_id, str) and bool(SAFE_JOB_ID_RE.fullmatch(job_id))
+
+
def _always_enabled() -> bool:
"""Default spec gate: enabled; production specs bind env-flag readers."""
return True
@@ -121,36 +166,45 @@ class SystemJobSpec:
Attributes:
id: Stable, predictable job id; MUST start with
- :data:`SYSTEM_JOB_ID_PREFIX` (the convention T7's guards and
- ``_SAFE_JOB_ID_RE`` interplay depend on).
- schedule: Default schedule (interval-ms string or 5-field cron).
- Seeded verbatim; on an existing row a VALID edited schedule is
- trusted (β) and only an INVALID one is repaired back to this.
+ :data:`SYSTEM_JOB_ID_PREFIX` (the convention the guards and
+ :data:`SAFE_JOB_ID_RE` interplay depend on).
+ schedule: Static default schedule (interval-ms string or 5-field
+ cron), validated at authoring time. Mutually exclusive with
+ ``schedule_fn``. Seeded verbatim; on an existing row a VALID
+ edited schedule is trusted (local-trust boundary) and only an
+ INVALID one is repaired back to this.
+ schedule_fn: Lazy schedule derivation evaluated inside
+ :func:`ensure_system_jobs` (never at import time), for specs
+ whose default comes from environment configuration — evaluating
+ at import would freeze the value before dotenv load and make the
+ wrong seed permanent under the schedule-trust boundary. Must
+ return a schedule passing :func:`validate_schedule`.
internal_callable: Registry KEY name (never an import path) resolved
through :mod:`src.scheduling.registry` at execution time.
title: Human-readable label seeded with the row.
timezone: IANA key for cron schedules, ``None`` for UTC/interval.
- prompt: Always ``""`` — internal/system jobs carry no prompt (plan
- ③b(i); ``from_dict`` accepts that since T3).
+ prompt: Always ``""`` — internal/system jobs carry no prompt
+ (``from_dict`` accepts that).
source_type: Fixed ``"system"``.
executor_kind: Fixed ``"internal"``.
enabled_predicate: Zero-arg callable deciding the spec's own gate —
- the second half of the double-gate chain (module docstring (iv)).
+ the second half of the double-gate chain (module docstring).
This dataclass never reads the environment itself.
"""
id: str
- schedule: str
- internal_callable: str
+ schedule: str = ""
+ internal_callable: str = ""
title: str = ""
timezone: Optional[str] = None
prompt: str = ""
source_type: str = "system"
- executor_kind: str = "internal"
+ executor_kind: ExecutorKind = "internal"
enabled_predicate: EnabledPredicate = field(default=_always_enabled)
+ schedule_fn: Optional[ScheduleFn] = None
def __post_init__(self) -> None:
- """Fail fast on spec-authoring bugs (T8/T9 append specs by hand)."""
+ """Fail fast on spec-authoring bugs (specs are appended by hand)."""
if not isinstance(self.id, str) or not self.id.startswith(SYSTEM_JOB_ID_PREFIX):
raise ValueError(f"system job id {self.id!r} must start with {SYSTEM_JOB_ID_PREFIX!r}")
if len(self.id) <= len(SYSTEM_JOB_ID_PREFIX):
@@ -163,23 +217,39 @@ class SystemJobSpec:
raise ValueError(f"system job spec {self.id!r} requires an internal_callable registry key")
if not callable(self.enabled_predicate):
raise TypeError(f"system job spec {self.id!r} requires a callable enabled_predicate")
- # Spec-owned defaults must be valid at authoring time; seeding uses
+ if bool(self.schedule) == (self.schedule_fn is not None):
+ raise ValueError(
+ f"system job spec {self.id!r} requires exactly one of schedule / schedule_fn"
+ )
+ if self.schedule_fn is not None and not callable(self.schedule_fn):
+ raise TypeError(f"system job spec {self.id!r} requires a callable schedule_fn")
+ # A static default must be valid at authoring time; seeding uses
# validate=True so a bad spec surfaces in CI, never at a user startup.
- validate_schedule(self.schedule)
+ # A schedule_fn result is validated by the same store write at seed
+ # time (the derivation itself is contractually never-raising).
+ if self.schedule:
+ validate_schedule(self.schedule)
validate_timezone_shape(self.timezone)
+ def resolved_schedule(self) -> str:
+ """Return the effective default schedule (static or lazily derived)."""
+ if self.schedule_fn is not None:
+ return self.schedule_fn()
+ return self.schedule
+
# ---------------------------------------------------------------------------
# Production spec surface
# ---------------------------------------------------------------------------
-#: The production specs (T8 memory consolidation, T9 br_data sync). Each job
-#: is ONE literal here plus ONE registry entry in ``registry.py``'s
-#: ``_INTERNAL_CALLABLES`` block; ensure_system_jobs, the guards (T7) and the
-#: lifespan wiring (T12) consume this tuple generically. Predicates and
-#: schedule derivation live in the DOMAIN modules (src.memory.consolidation,
+#: The production specs (memory consolidation, br_data sync). Each job is ONE
+#: literal here plus ONE registry entry in ``registry.py``'s
+#: ``_INTERNAL_CALLABLES`` block; ensure_system_jobs, the guards and the
+#: lifespan wiring consume this tuple generically. Predicates and schedule
+#: derivation live in the DOMAIN modules (src.memory.consolidation,
#: src.br_data.scheduling) so THIS module keeps reading zero env. A valid
-#: edited schedule/timezone on a seeded row is trusted per (β).
+#: edited schedule/timezone on a seeded row is trusted per the local-trust
+#: boundary.
_SYSTEM_JOB_SPECS: tuple[SystemJobSpec, ...] = (
SystemJobSpec(
id="system:memory-consolidation",
@@ -189,12 +259,13 @@ _SYSTEM_JOB_SPECS: tuple[SystemJobSpec, ...] = (
title="Memory consolidation",
enabled_predicate=_memory_consolidation_enabled,
),
- # T9: daily Brazilian official-dataset sync on the São Paulo wall clock
- # (sync.TZ key). The cron derives from VIBE_BR_SYNC_TIME at module build
- # and drives the FIRST seed only — (β) trusts an edited row afterwards.
+ # Daily Brazilian official-dataset sync on the São Paulo wall clock
+ # (sync.TZ key). The cron derives from VIBE_BR_SYNC_TIME lazily — at
+ # ensure time, after dotenv load — and drives the FIRST seed only: the
+ # local-trust boundary accepts an edited row afterwards.
SystemJobSpec(
id="system:br-data-sync",
- schedule=_br_data_daily_cron(),
+ schedule_fn=_br_data_daily_cron,
timezone="America/Sao_Paulo",
internal_callable="br_data.run_sync",
title="Brazilian dataset sync",
@@ -211,10 +282,10 @@ def system_job_specs() -> tuple[SystemJobSpec, ...]:
def is_system_job_id(job_id: object) -> bool:
"""Whether *job_id* carries the protected ``system:`` prefix.
- The single predicate T7's guards consume. Pure prefix test — never
- raises, non-strings are ``False``. The prefix contains ``:``, which
- ``_SAFE_JOB_ID_RE`` rejects, so a user-facing create path can never mint
- an id this function returns ``True`` for.
+ The single predicate the mutation guards consume. Pure prefix test —
+ never raises, non-strings are ``False``. The prefix contains ``:``,
+ which :data:`SAFE_JOB_ID_RE` rejects, so a user-facing create path can
+ never mint an id this function returns ``True`` for.
"""
return isinstance(job_id, str) and job_id.startswith(SYSTEM_JOB_ID_PREFIX)
@@ -223,12 +294,13 @@ def is_system_job_id(job_id: object) -> bool:
class EnsureSystemJobsReport:
"""Per-outcome id lists from one :func:`ensure_system_jobs` pass.
- ``seeded``: missing rows created (enabled specs; repair-replay (iii) lands
+ ``seeded``: missing rows created (enabled specs; repair-replay lands
here too). ``repaired``: enabled rows rewritten (tamper correction,
- invalid-schedule repair, (α) reset, ``end_at`` clearing). ``unchanged``:
- conformant enabled rows, NOT written. ``skipped_disabled``: disabled specs
- with no row. ``halted``: disabled specs with an existing row (made
- non-runnable/corrected, or already terminal, no write needed).
+ invalid-schedule repair, startup status/retry-budget reset, ``end_at``
+ clearing). ``unchanged``: conformant enabled rows, NOT written.
+ ``skipped_disabled``: disabled specs with no row. ``halted``: disabled
+ specs with an existing row (made non-runnable/corrected, or already
+ terminal, no write needed).
"""
seeded: tuple[str, ...] = ()
@@ -241,13 +313,14 @@ class EnsureSystemJobsReport:
def _seed_job(spec: SystemJobSpec, now_ms: int) -> ScheduledResearchJob:
"""Build a fresh row for *spec* (mirrors ``build_job_from_draft``'s next-run
convention: cron-with-tz waits for its next slot; interval/UTC-cron due now)."""
+ schedule = spec.resolved_schedule()
next_run_at = now_ms
- if spec.timezone is not None and not is_interval_schedule(spec.schedule):
- next_run_at = next_due(spec.schedule, now_ms, spec.timezone)
+ if spec.timezone is not None and not is_interval_schedule(schedule):
+ next_run_at = next_due(schedule, now_ms, spec.timezone)
return ScheduledResearchJob(
id=spec.id,
prompt=spec.prompt,
- schedule=spec.schedule,
+ schedule=schedule,
title=spec.title,
source_type=spec.source_type,
executor_kind=spec.executor_kind,
@@ -261,9 +334,10 @@ def _seed_job(spec: SystemJobSpec, now_ms: int) -> ScheduledResearchJob:
def _schedule_shape_ok(schedule: str, timezone: Optional[str]) -> bool:
"""Whether *schedule*/*timezone* pass the store's syntactic validation —
- exactly the check ``store.upsert(validate=True)`` applies, so the (β)
- boundary uses the system-wide grammar: valid-but-different is trusted
- local editing; invalid is garbage a ``validate=False`` write must not keep.
+ exactly the check ``store.upsert(validate=True)`` applies, so the
+ local-trust boundary uses the system-wide grammar: valid-but-different is
+ trusted local editing; invalid is garbage a ``validate=False`` write must
+ not keep.
"""
try:
validate_schedule(schedule)
@@ -277,10 +351,13 @@ def _reconcile(job: ScheduledResearchJob, spec: SystemJobSpec, *, enabled: bool)
"""Mutate *job* toward *spec* in place; return human-readable change notes.
Touches ONLY spec-owned fields (source_type / executor_kind /
- internal_callable, invalid schedule/timezone, the (α) status reset,
- ``end_at``, and the flag-off halt). Runtime fields — next_run_at,
- last_run_at, consecutive_failures, last_error, failure_kind, created_at,
- config, title, prompt, delivery* — are never modified here.
+ internal_callable, invalid schedule/timezone, the startup status and
+ retry-budget resets, ``end_at``, and the flag-off halt). Other runtime
+ fields — next_run_at, last_run_at, created_at, config, title, prompt,
+ delivery* — are never modified here; consecutive_failures/last_error/
+ failure_kind are cleared ONLY together with a FAILED-status reset (an
+ enabled spec's retry-budget reset — keeping the failure counters without
+ the terminal status would immediately re-terminalize the row).
"""
notes: list[str] = []
if job.source_type != spec.source_type:
@@ -292,34 +369,49 @@ def _reconcile(job: ScheduledResearchJob, spec: SystemJobSpec, *, enabled: bool)
if job.internal_callable != spec.internal_callable:
notes.append(f"internal_callable {job.internal_callable!r} -> {spec.internal_callable!r}")
job.internal_callable = spec.internal_callable
- # (ii-c)/(β): a VALID edited schedule/timezone is trusted and left alone;
- # an INVALID one is repaired to the spec default — the validate=False
- # repair write below would otherwise persist garbage.
+ # Local-trust boundary: a VALID edited schedule/timezone is trusted and
+ # left alone; an INVALID one is repaired to the spec default — the
+ # validate=False repair write below would otherwise persist garbage.
if not _schedule_shape_ok(job.schedule, job.timezone):
notes.append(
f"invalid schedule/timezone ({job.schedule!r}, {job.timezone!r}) "
- f"-> spec default ({spec.schedule!r}, {spec.timezone!r})"
+ f"-> spec default ({spec.resolved_schedule()!r}, {spec.timezone!r})"
)
- job.schedule = spec.schedule
+ job.schedule = spec.resolved_schedule()
job.timezone = spec.timezone
if enabled:
- # (α): post-T7 these statuses can only come from manual file edits
- # (or our own flag-off halt), so resetting them is safe and keeps the
- # "protected" claim true at the local-file layer.
+ # Startup status reset: no API path can put a system job in these
+ # statuses, so they can only come from manual file edits (or our own
+ # flag-off halt); resetting them keeps the "protected" claim true at
+ # the local-file layer.
if job.status in _TAMPER_TERMINAL_STATUSES:
- notes.append(f"status {job.status.value!r} -> 'pending' (alpha reset), end_at cleared")
+ notes.append(f"status {job.status.value!r} -> 'pending' (startup reset), end_at cleared")
+ job.status = JobStatus.PENDING
+ job.end_at = None
+ elif job.status is JobStatus.FAILED:
+ # Retry-budget reset (module docstring): FAILED IS reachable at
+ # runtime through the executor's own retry exhaustion, and no API
+ # surface may resurrect a system row — without this reset a
+ # transient outage would permanently brick a product-owned job.
+ notes.append(
+ f"status 'failed' -> 'pending' (retry budget reset at startup), "
+ f"end_at cleared, {job.consecutive_failures} consecutive failure(s) cleared"
+ )
job.status = JobStatus.PENDING
job.end_at = None
+ job.consecutive_failures = 0
+ job.last_error = None
+ job.failure_kind = None
elif job.end_at is not None:
# Specs define no end boundary; a hand-added future end_at would
- # silently expire the job mid-life (same tamper class as alpha).
+ # silently expire the job mid-life (same tamper class).
notes.append(f"end_at {job.end_at} -> None (system jobs do not expire)")
job.end_at = None
elif job.status in _RUNNABLE_STATUSES:
- # (iv) enablement chain, flag-off direction: the row must not keep
- # firing after its flag turned off. CANCELLED is terminal in is_due,
- # non-destructive (runtime fields preserved) and undone by the (alpha)
- # reset when the flag comes back on.
+ # Enablement chain, flag-off direction: the row must not keep firing
+ # after its flag turned off. CANCELLED is terminal in is_due,
+ # non-destructive (runtime fields preserved) and undone by the
+ # startup status reset when the flag comes back on.
notes.append(f"status {job.status.value!r} -> 'cancelled' (spec flag disabled)")
job.status = JobStatus.CANCELLED
return notes
@@ -334,19 +426,20 @@ def ensure_system_jobs(
) -> EnsureSystemJobsReport:
"""Seed/repair every enabled system job into *store* (idempotent).
- Call at lifespan startup BEFORE ``executor.start()`` (contract (i), T12
- wires it). Running it twice changes nothing the second time: conformant
- rows are not rewritten at all, so runtime state and store bytes survive.
+ Call at lifespan startup BEFORE ``executor.start()`` (timing contract,
+ module docstring). Running it twice changes nothing the second time:
+ conformant rows are not rewritten at all, so runtime state and store
+ bytes survive.
Args:
store: The scheduled-research job store to reconcile against.
enabled_predicate: Optional caller-level gate override receiving each
- spec; production (T12) passes nothing so each spec's own
- ``enabled_predicate`` decides (double-gate chain (iv)). Primarily
- an injection seam for tests and uniform external gating.
+ spec; production passes nothing so each spec's own
+ ``enabled_predicate`` decides (double-gate chain). Primarily an
+ injection seam for tests and uniform external gating.
specs: Optional explicit spec sequence; defaults to
- :func:`system_job_specs` (the production tuple T8/T9 appended
- to). Tests inject framework specs here.
+ :func:`system_job_specs` (the production tuple). Tests inject
+ framework specs here.
now_fn: Injectable wall clock (epoch ms) for seeded timestamps.
Returns:
@@ -355,7 +448,7 @@ def ensure_system_jobs(
Raises:
ValueError: Only when a SEEDED spec default fails store validation —
a spec-authoring bug that must crash CI (repairs never raise;
- they use ``validate=False`` per (ii-b)).
+ they use ``validate=False`` per the repair-write contract).
"""
active_specs = tuple(system_job_specs() if specs is None else specs)
now = _now_ms() if now_fn is None else int(now_fn())
@@ -370,22 +463,23 @@ def ensure_system_jobs(
existing = store.get(spec.id)
if existing is None:
if not enabled:
- # QA (a): disabled + no row -> nothing is written at all.
+ # Disabled + no row -> nothing is written at all.
skipped.append(spec.id)
continue
- # (iii) repair-replay shares this path: a hand-deleted job is
- # re-seeded at the next startup. validate=True on purpose — the
- # spec defaults are ours, checked in __post_init__.
+ # Repair-replay shares this path: a hand-deleted job is re-seeded
+ # at the next startup. validate=True on purpose — the spec
+ # defaults are ours, checked in __post_init__ (static) or by this
+ # write (lazily derived).
store.upsert(_seed_job(spec, now))
seeded.append(spec.id)
- logger.info("system job %s seeded (schedule=%r)", spec.id, spec.schedule)
+ logger.info("system job %s seeded (schedule=%r)", spec.id, spec.resolved_schedule())
continue
notes = _reconcile(existing, spec, enabled=enabled)
if not notes:
(unchanged if enabled else halted).append(spec.id)
continue
- # (ii-b): repair/halt writes must always land — a row whose schedule
- # no longer validates must still be correctable without a crash.
+ # Repair/halt writes must always land — a row whose schedule no
+ # longer validates must still be correctable without a crash.
store.upsert(existing, validate=False)
(repaired if enabled else halted).append(spec.id)
logger.info("system job %s reconciled at startup: %s", spec.id, "; ".join(notes))
diff --git a/agent/src/scheduling/types.py b/agent/src/scheduling/types.py
index 42c3a0db6..22e36cc0f 100644
--- a/agent/src/scheduling/types.py
+++ b/agent/src/scheduling/types.py
@@ -1,46 +1,27 @@
-"""Shared vocabulary types for the scheduling kernel (scheduler-unification T2).
+"""Shared vocabulary types for the scheduling kernel (scheduler unification).
-Three pieces live here, all pure and domain-free:
+Two pieces live here, both pure and domain-free:
* :data:`ExecutorKind` — how a job is executed (``"prompt"`` dispatches an
agent session; ``"internal"`` runs a registered in-process callable). The
- value domain is defined here once so job models and registries cannot
- drift apart.
-* :class:`JobLike` — the structural job surface a generic scheduler may rely
- on. Deliberately minimal: delivery / verdict / briefing / playbook fields
- belong to the ``scheduled_research`` domain and are NOT part of this
- protocol.
-* :class:`TriggerSpec` — one trigger specification (schedule string plus the
- IANA timezone a cron schedule is evaluated in) behind a single value
- object, unifying the scheduled-research grammar with the ``once`` kind
- absorbed from the live runtime (see :mod:`src.scheduling.triggers`).
-
-The callback type aliases at the bottom are the injection seams of
-:class:`src.scheduling.kernel.SchedulerKernel`; they are declared here so the
-kernel module stays free of domain imports.
+ value domain is defined here once, and the job model validates against it
+ (:func:`is_executor_kind`), so model and registry cannot drift apart.
+* The kernel callback aliases (:data:`NowFn`, :data:`OnTickFn`) — the
+ injection seams of :class:`src.scheduling.kernel.SchedulerKernel`,
+ declared here so the kernel module stays free of domain imports.
"""
from __future__ import annotations
-from dataclasses import dataclass
-from typing import Awaitable, Callable, Literal, Optional, Protocol, runtime_checkable
-
-from src.scheduling.triggers import (
- ONCE_SPEC,
- next_due,
- next_once_due,
- validate_schedule,
- validate_timezone,
-)
+from typing import Awaitable, Callable, Literal
# ---------------------------------------------------------------------------
# Executor kind
# ---------------------------------------------------------------------------
-#: How a job is executed: ``"prompt"`` dispatches an agent session (the only
-#: kind that exists today), ``"internal"`` runs a callable from the explicit
-#: in-process registry (added by later todos of the scheduler-unification
-#: plan; nothing consumes it yet).
+#: How a job is executed: ``"prompt"`` dispatches an agent session,
+#: ``"internal"`` runs a callable from the explicit in-process registry
+#: (:mod:`src.scheduling.registry`).
ExecutorKind = Literal["prompt", "internal"]
#: The closed value domain of :data:`ExecutorKind`, for runtime validation.
@@ -52,101 +33,6 @@ def is_executor_kind(value: object) -> bool:
return value in EXECUTOR_KINDS
-# ---------------------------------------------------------------------------
-# Job protocol
-# ---------------------------------------------------------------------------
-
-
-@runtime_checkable
-class JobLike(Protocol):
- """The structural job surface the kernel and its callbacks may rely on.
-
- Only the attributes a generic scheduler needs to decide due-ness, advance
- the next run and reason about retries are required here. Domain fields
- (delivery outbox, verdict records, briefing text, playbook provenance)
- stay in ``scheduled_research`` — consumers that need them accept the
- concrete job type in their own callbacks.
-
- ``isinstance`` checks work structurally (``runtime_checkable`` verifies
- attribute presence, not types), so existing dataclass jobs satisfy this
- protocol without inheriting from it.
- """
-
- #: Stable job identifier.
- id: str
- #: Epoch-millisecond timestamp of the next intended run.
- next_run_at: int
- #: Lifecycle status. Domain status enums are ``str``-valued and satisfy
- #: this annotation without the kernel importing them.
- status: str
- #: Trigger schedule string (see :mod:`src.scheduling.triggers`).
- schedule: str
- #: IANA timezone key a cron schedule is evaluated in, or ``None`` (UTC).
- timezone: Optional[str]
- #: Consecutive dispatch failures, driving retry backoff.
- consecutive_failures: int
-
-
-# ---------------------------------------------------------------------------
-# Trigger specification
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True, slots=True)
-class TriggerSpec:
- """One trigger specification: a schedule string plus its timezone.
-
- Wraps the two trigger kinds of the shared vocabulary behind a single
- value object:
-
- * the scheduled-research grammar — a bare ``"<ms>"`` interval string or a
- simplified 5-field cron expression evaluated on the wall clock of
- ``timezone`` (UTC when ``None``);
- * the ``once`` kind absorbed from the live runtime — fires exactly once
- and has no next run, so :meth:`next_due_after` returns ``None``.
-
- The live runtime's ``"interval:<ms>"`` spelling is intentionally out of
- scope for this value object; callers that need it use
- :func:`src.scheduling.triggers.next_once_due` directly.
-
- Construction is tolerant (no implicit validation), mirroring the repo's
- forgiving ``from_dict`` philosophy; call :meth:`validate` explicitly to
- reject an unusable spec.
- """
-
- schedule: str
- timezone: Optional[str] = None
-
- @property
- def is_once(self) -> bool:
- """Return whether this is the one-shot ``once`` kind."""
- return self.schedule.strip().lower() == ONCE_SPEC
-
- def validate(self) -> None:
- """Raise when the spec cannot be used to compute next runs.
-
- Delegates to :func:`src.scheduling.triggers.validate_schedule` and
- :func:`src.scheduling.triggers.validate_timezone` for the research
- grammar. The ``once`` kind carries no grammar to validate and is
- always accepted (its timezone is ignored, as for interval schedules).
- """
- if self.is_once:
- return
- validate_schedule(self.schedule)
- validate_timezone(self.timezone)
-
- def next_due_after(self, after_ms: int) -> Optional[int]:
- """Return the next due epoch-ms strictly after *after_ms*.
-
- ``None`` means the trigger never fires again (the one-shot ``once``
- kind). Cron window exhaustion propagates the ``ValueError`` raised by
- :func:`src.scheduling.triggers.next_due` rather than being swallowed.
- """
- if self.is_once:
- return next_once_due(self.schedule, after_ms)
- return next_due(self.schedule, after_ms, self.timezone)
-
-
# ---------------------------------------------------------------------------
# Kernel callback seams
# ---------------------------------------------------------------------------
@@ -158,19 +44,3 @@ NowFn = Callable[[], int]
#: kernel isolates exceptions per tick (one failing tick never kills the
#: loop); ``asyncio.CancelledError`` propagates so ``stop()`` stays bounded.
OnTickFn = Callable[[int], Awaitable[None]]
-
-#: ``(job, now_ms) -> due?`` Pure predicate deciding whether *job* should
-#: fire at *now_ms*. The domain owns the gates (terminal statuses, end
-#: boundaries, in-flight deliveries); the kernel never interprets them.
-IsDueFn = Callable[[JobLike, int], bool]
-
-#: ``(job, from_ms) -> next_run_at | None`` Pure computation of the next run
-#: epoch-ms strictly after *from_ms*, or ``None`` when the trigger does not
-#: fire again. Grammar errors (e.g. cron window exhaustion) surface as
-#: ``ValueError`` for the domain's error hook to record.
-AdvanceFn = Callable[[JobLike, int], Optional[int]]
-
-#: ``(job, now_ms, exc)`` Hook for per-job failures, invoked by the domain's
-#: tick composition inside its per-job isolation. Synchronous by contract:
-#: it records (log / persist) and must not re-raise.
-JobErrorFn = Callable[[JobLike, int, Exception], None]
diff --git a/agent/tests/scheduling/test_internal_dispatch.py b/agent/tests/scheduling/test_internal_dispatch.py
index e4a323418..a656412a0 100644
--- a/agent/tests/scheduling/test_internal_dispatch.py
+++ b/agent/tests/scheduling/test_internal_dispatch.py
@@ -478,14 +478,14 @@ def test_stop_is_bounded_and_leaves_inflight_job_running(tmp_path: Path, clean_r
def test_production_resolver_resolves_registered_and_rejects_tampered(clean_registry) -> None:
- from src.api.scheduled_routes import _resolve_scheduled_internal_callable
+ from src.scheduled_research.internal_dispatch import resolve_scheduled_internal_callable
register_internal("test.prod", lambda: None)
job = _internal_job("j", callable_name="test.prod")
- assert resolve_internal("test.prod") is _resolve_scheduled_internal_callable(job)
+ assert resolve_internal("test.prod") is resolve_scheduled_internal_callable(job)
tampered = _internal_job("j", callable_name="os.system")
with pytest.raises(InternalCallableError):
- _resolve_scheduled_internal_callable(tampered)
+ resolve_scheduled_internal_callable(tampered)
def test_production_singleton_routes_internal_jobs_through_registry(
diff --git a/agent/tests/scheduling/test_kernel.py b/agent/tests/scheduling/test_kernel.py
index bba8d900d..e606be7b9 100644
--- a/agent/tests/scheduling/test_kernel.py
+++ b/agent/tests/scheduling/test_kernel.py
@@ -14,8 +14,6 @@ import asyncio
import itertools
import threading
import time
-from dataclasses import dataclass
-from datetime import datetime, timezone
import pytest
@@ -26,8 +24,6 @@ from src.scheduling.kernel import (
)
from src.scheduling.types import (
EXECUTOR_KINDS,
- JobLike,
- TriggerSpec,
is_executor_kind,
)
@@ -363,22 +359,13 @@ def test_ctor_rejects_invalid_retry_policy() -> None:
SchedulerKernel(retry_base_delay_ms=1000, retry_max_delay_ms=999)
-# ---- callback seams and policy surface ------------------------------------------
+# ---- callback seam and policy surface -------------------------------------------
-def test_callback_seams_and_knobs_are_exposed_read_only() -> None:
+def test_callback_and_knobs_are_exposed_read_only() -> None:
async def on_tick(now_ms: int) -> None:
return None
- def is_due(job, now_ms: int) -> bool:
- return True
-
- def advance(job, from_ms: int) -> int | None:
- return None
-
- def on_err(job, now_ms: int, exc: Exception) -> None:
- return None
-
kernel = SchedulerKernel(
tick_interval_ms=1234,
enabled=False,
@@ -386,16 +373,10 @@ def test_callback_seams_and_knobs_are_exposed_read_only() -> None:
retry_base_delay_ms=10,
retry_max_delay_ms=20,
on_tick=on_tick,
- is_due_fn=is_due,
- advance_fn=advance,
- on_job_error=on_err,
task_name="k",
)
assert kernel.on_tick is on_tick
- assert kernel.is_due_fn is is_due
- assert kernel.advance_fn is advance
- assert kernel.on_job_error is on_err
assert kernel.tick_interval_ms == 1234
assert kernel.max_consecutive_failures == 5
assert (kernel.retry_base_delay_ms, kernel.retry_max_delay_ms) == (10, 20)
@@ -405,7 +386,15 @@ def test_callback_seams_and_knobs_are_exposed_read_only() -> None:
kernel.tick_interval_ms = 1 # read-only property
-# ---- types: ExecutorKind / JobLike / TriggerSpec --------------------------------
+def test_kernel_rejects_the_removed_speculative_seams() -> None:
+ # The kernel's only callback is on_tick; due-ness/advance/error seams were
+ # dead storage and are gone — a caller passing them must fail loudly.
+ for removed_kwarg in ("is_due_fn", "advance_fn", "on_job_error"):
+ with pytest.raises(TypeError):
+ SchedulerKernel(**{removed_kwarg: lambda *a, **k: None}) # type: ignore[arg-type]
+
+
+# ---- types: ExecutorKind ----------------------------------------------------------
def test_executor_kind_domain_is_closed() -> None:
@@ -415,51 +404,3 @@ def test_executor_kind_domain_is_closed() -> None:
assert not is_executor_kind("shell")
assert not is_executor_kind(None)
assert not is_executor_kind("")
-
-
-def test_joblike_matches_structurally_and_rejects_partial_jobs() -> None:
- @dataclass
- class DummyJob:
- id: str
- next_run_at: int
- status: str
- schedule: str
- timezone: str | None
- consecutive_failures: int
-
- assert isinstance(DummyJob("j1", 1000, "pending", "5000", None, 0), JobLike)
-
- class Partial:
- id = "x"
- next_run_at = 0
-
- assert not isinstance(Partial(), JobLike)
-
-
-def test_trigger_spec_once_has_no_next_run() -> None:
- spec = TriggerSpec("once")
- assert spec.is_once
- spec.validate() # the once kind is always accepted
- assert spec.next_due_after(5000) is None
- assert TriggerSpec(" ONCE ").is_once # compared stripped + case-insensitively
-
-
-def test_trigger_spec_interval_and_cron_next_due() -> None:
- assert TriggerSpec("5000").next_due_after(1000) == 6000
-
- spec = TriggerSpec("0 4 * * *", "UTC")
- spec.validate()
- after = 1_760_000_000_000 # 2025-10-09T08:53:20Z
- nxt = spec.next_due_after(after)
- assert nxt is not None and nxt > after
- fired = datetime.fromtimestamp(nxt / 1000, tz=timezone.utc)
- assert (fired.hour, fired.minute) == (4, 0)
-
-
-def test_trigger_spec_validate_rejects_bad_grammar_and_timezone() -> None:
- with pytest.raises(ValueError):
- TriggerSpec("bogus").validate()
- with pytest.raises(ValueError):
- TriggerSpec("0 4 * * *", "Mars/Olympus_Mons").validate()
- # Construction itself stays tolerant; only validate() rejects.
- TriggerSpec("bogus")
diff --git a/agent/tests/scheduling/test_memory_consolidation_job.py b/agent/tests/scheduling/test_memory_consolidation_job.py
index b56cf9831..166f7b84d 100644
--- a/agent/tests/scheduling/test_memory_consolidation_job.py
+++ b/agent/tests/scheduling/test_memory_consolidation_job.py
@@ -162,9 +162,18 @@ def test_production_spec_shape() -> None:
assert spec.enabled_predicate is consolidation_enabled
-def test_registry_production_entry_resolves_to_consolidate() -> None:
+def test_registry_production_entry_delegates_to_consolidate(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
assert is_registered("memory.consolidate") is True
- assert resolve_internal("memory.consolidate") is consolidate
+ # The registered entry is a literal wrapper with a deferred domain import:
+ # calling it must delegate to the real consolidation entry point.
+ calls = []
+ monkeypatch.setattr(
+ "src.memory.consolidation.consolidate", lambda *a, **k: calls.append("fired")
+ )
+ resolve_internal("memory.consolidate")()
+ assert calls == ["fired"]
# ---------------------------------------------------------------------------
diff --git a/agent/tests/scheduling/test_registry.py b/agent/tests/scheduling/test_registry.py
index ec361a41f..ae594f58c 100644
--- a/agent/tests/scheduling/test_registry.py
+++ b/agent/tests/scheduling/test_registry.py
@@ -213,6 +213,28 @@ def test_registry_source_has_no_dynamic_resolution_tokens() -> None:
assert token not in source, f"registry.py must never contain {token!r}"
+def test_registry_has_no_top_level_domain_imports() -> None:
+ """The generic scheduling package must not eagerly pull in domain stacks.
+
+ Mechanical pin of the deferred-import contract: every top-level import in
+ registry.py is stdlib/typing — the ``src.br_data`` / ``src.memory``
+ imports live INSIDE the literal wrapper bodies and run at first firing,
+ not at kernel-package import.
+ """
+ import ast
+
+ tree = ast.parse(Path(registry.__file__).read_text(encoding="utf-8"))
+ for node in tree.body:
+ if isinstance(node, ast.Import):
+ for alias in node.names:
+ assert not alias.name.startswith("src."), f"top-level import {alias.name!r}"
+ elif isinstance(node, ast.ImportFrom):
+ module = node.module or ""
+ assert module.startswith("src.scheduling") or not module.startswith("src."), (
+ f"top-level domain import {module!r}"
+ )
+
+
def test_registry_source_has_no_shell_tokens() -> None:
source = Path(registry.__file__).read_text(encoding="utf-8")
for token in ("subprocess", "os.system", "shell=True"):
@@ -224,4 +246,4 @@ def test_register_internal_is_documented_module_and_test_only() -> None:
# surface — production entries are explicit dict edits at module bottom.
assert register_internal.__doc__ is not None
assert "MODULE/TEST-ONLY" in register_internal.__doc__
- assert "T8/T9" in register_internal.__doc__
+ assert "module edit" in register_internal.__doc__
diff --git a/agent/tests/scheduling/test_system_job_protection.py b/agent/tests/scheduling/test_system_job_protection.py
index b0e900c42..c1c22fbed 100644
--- a/agent/tests/scheduling/test_system_job_protection.py
+++ b/agent/tests/scheduling/test_system_job_protection.py
@@ -11,7 +11,7 @@ modify, create or replace one. The six entries audited here:
defense in depth for non-REST callers.
2. ``PATCH /scheduled-runs/{job_id}`` — same 400-before-handler reality.
3. ``propose_create`` / ``build_job_from_draft`` — a draft id that is
- ``system:``-prefixed or outside ``_SAFE_JOB_ID_RE`` is refused at propose.
+ ``system:``-prefixed or outside ``SAFE_JOB_ID_RE`` is refused at propose.
4. ``commit_proposal`` — the AUTHORITATIVE guard: proposal files live under
``<runtime root>/scheduled_research/proposals/`` and can be hand-written
or edited between propose and commit, so commit re-reads the store and
@@ -168,13 +168,24 @@ def _run_cli(argv: List[str]) -> int:
def test_safe_job_id_regex_rejects_system_ids() -> None:
from src.api.helpers import _SAFE_PATH_PARAM_RE
+ from src.scheduling.system_jobs import SAFE_JOB_ID_RE, is_safe_job_id
- assert scheduled_routes._SAFE_JOB_ID_RE.match(SYSTEM_ID) is None
- assert scheduled_routes._SAFE_JOB_ID_RE.fullmatch(SYSTEM_ID) is None
+ assert SAFE_JOB_ID_RE.match(SYSTEM_ID) is None
+ assert SAFE_JOB_ID_RE.fullmatch(SYSTEM_ID) is None
+ assert is_safe_job_id(SYSTEM_ID) is False
assert _SAFE_PATH_PARAM_RE.match(SYSTEM_ID) is None
assert is_system_job_id(SYSTEM_ID) is True
+def test_shared_job_id_rule_cannot_drift_from_host_path_param_rule() -> None:
+ # The structural anti-forgery guarantee holds only while BOTH grammars
+ # reject ':' — pin them to the same pattern so a one-sided edit fails.
+ from src.api.helpers import _SAFE_PATH_PARAM_RE
+ from src.scheduling.system_jobs import SAFE_JOB_ID_RE
+
+ assert SAFE_JOB_ID_RE.pattern == _SAFE_PATH_PARAM_RE.pattern
+
+
def test_route_registration_order_keeps_static_paths_before_job_id() -> None:
scheduled = [
(index, route)
diff --git a/agent/tests/scheduling/test_system_jobs.py b/agent/tests/scheduling/test_system_jobs.py
index 440931706..81a047a99 100644
--- a/agent/tests/scheduling/test_system_jobs.py
+++ b/agent/tests/scheduling/test_system_jobs.py
@@ -114,7 +114,7 @@ def test_is_system_job_id_false_for_everything_else(job_id: object) -> None:
def test_prefix_constant_contains_colon_for_safe_id_re_interplay() -> None:
- """T7 ②b: the prefix MUST contain ':' so _SAFE_JOB_ID_RE (^[A-Za-z0-9_-]{1,128}$)
+ """the prefix MUST contain ':' so SAFE_JOB_ID_RE (^[A-Za-z0-9_-]{1,128}$)
rejects every system id at POST/path-param level — structural anti-forgery."""
assert SYSTEM_JOB_ID_PREFIX == "system:"
assert ":" in SYSTEM_JOB_ID_PREFIX
@@ -447,6 +447,41 @@ def test_disabled_flag_leaves_terminal_rows_untouched(tmp_path: Path) -> None:
assert store.path.read_bytes() == before # FAILED is already never-due
+def test_enabled_spec_resets_failed_row_and_clears_retry_budget(tmp_path: Path) -> None:
+ """Retry-budget reset: FAILED is reachable at runtime through the
+ executor's own retry exhaustion, and no API surface may resurrect a
+ system row — the startup reset is the only recovery path, so a transient
+ multi-day outage cannot permanently brick a product-owned job."""
+ store = _store(tmp_path)
+ spec = _spec()
+ ensure_system_jobs(store, specs=[spec], now_fn=lambda: 1000)
+ _mutate_row(
+ store,
+ spec.id,
+ status=JobStatus.FAILED,
+ consecutive_failures=3,
+ last_error="boom",
+ failure_kind="dispatch",
+ end_at=12345,
+ )
+
+ report = ensure_system_jobs(store, specs=[spec], now_fn=lambda: 2000)
+ assert report.repaired == (spec.id,)
+ job = store.get(spec.id)
+ assert job.status == JobStatus.PENDING
+ assert job.end_at is None
+ assert job.consecutive_failures == 0
+ assert job.last_error is None
+ assert job.failure_kind is None
+ assert job.next_run_at == 1000 # other runtime fields still untouched
+
+ # Idempotent: the conformant PENDING row is not rewritten on a second pass.
+ before = store.path.read_bytes()
+ report2 = ensure_system_jobs(store, specs=[spec], now_fn=lambda: 3000)
+ assert report2.unchanged == (spec.id,)
+ assert store.path.read_bytes() == before
+
+
def test_disabled_flag_still_corrects_tampered_fields(tmp_path: Path) -> None:
"""A disabled row tampered to executor_kind='prompt' must not stay a
prompt-dispatchable row even while the feature flag is off."""
diff --git a/agent/tests/test_br_data.py b/agent/tests/test_br_data.py
index 70662a939..03e7a8907 100644
--- a/agent/tests/test_br_data.py
+++ b/agent/tests/test_br_data.py
@@ -431,7 +431,6 @@ def test_sync_flag_defaults_false_and_gates_seeding(monkeypatch, tmp_path):
def test_flag_on_seeds_br_sync_row_with_spec_fields(monkeypatch, tmp_path):
from src.br_data.scheduling import sync_job_enabled
- from src.br_data.sync import run_sync
from src.scheduled_research.models import JobStatus
from src.scheduling.registry import is_registered, resolve_internal
from src.scheduling.system_jobs import ensure_system_jobs
@@ -449,7 +448,14 @@ def test_flag_on_seeds_br_sync_row_with_spec_fields(monkeypatch, tmp_path):
assert spec.prompt == ""
assert spec.enabled_predicate is sync_job_enabled
assert is_registered("br_data.run_sync") is True
- assert resolve_internal("br_data.run_sync") is run_sync
+ # The registered entry is a literal wrapper with a deferred domain import:
+ # calling it must delegate to the real sync entry point.
+ calls = []
+ monkeypatch.setattr(
+ "src.br_data.sync.run_sync", lambda *a, **k: calls.append("fired") or {}
+ )
+ resolve_internal("br_data.run_sync")()
+ assert calls == ["fired"]
store = _br_store(tmp_path)
report = ensure_system_jobs(store, now_fn=lambda: 1000)
@@ -459,11 +465,11 @@ def test_flag_on_seeds_br_sync_row_with_spec_fields(monkeypatch, tmp_path):
assert job.source_type == "system"
assert job.executor_kind == "internal"
assert job.internal_callable == "br_data.run_sync"
- assert job.schedule == spec.schedule
+ assert job.schedule == spec.resolved_schedule()
assert job.timezone == "America/Sao_Paulo"
assert job.status == JobStatus.PENDING
# cron + tz seeds the NEXT São Paulo slot, not "now"
- assert job.next_run_at == next_due(spec.schedule, 1000, spec.timezone)
+ assert job.next_run_at == next_due(spec.resolved_schedule(), 1000, spec.timezone)
assert job.next_run_at > 1000
@@ -529,7 +535,7 @@ def test_due_internal_job_calls_run_sync_exactly_once(tmp_path, monkeypatch):
assert saved.failure_kind is None
assert saved.last_run_at == 1500 # completion time (internal path)
spec = _production_br_spec()
- assert saved.next_run_at == next_due(spec.schedule, 1500, spec.timezone)
+ assert saved.next_run_at == next_due(spec.resolved_schedule(), 1500, spec.timezone)
def test_run_sync_exception_lands_in_dispatch_failure_path(tmp_path, monkeypatch):