"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
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.pyindex 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_jobif 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_MESSAGEkwargs: Dict[str, Any] = {"variables": variables or {},diff --git a/agent/src/api/scheduled_guards.py b/agent/src/api/scheduled_guards.pynew file mode 100644index 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.pyindex 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 annotationsimport logging-import reimport sys as _sysimport timeimport 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_executorif _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_duefrom 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_mutationfrom src.scheduled_research.executor import next_duefrom 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.pyindex 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 thescheduler 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 invalidvalue ("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 VALIDedited 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 defaultdiff --git a/agent/src/scheduled_research/executor.py b/agent/src/scheduled_research/executor.pyindex 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.pyindex 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 theexecutor'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()`` neverwaits 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.pyindex 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_kindlogger = 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] = Noneend_at: Optional[int] = Nonenext_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.pyindex 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 reimport sysimport timeimport uuid@@ -21,13 +20,7 @@ from src.scheduled_research.models import ()from src.scheduled_research.playbooks import get_playbookfrom 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_iddef 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__.pyindex 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 absorbedfrom 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 loopwith ``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: anexplicit module-level dict mapping literal registry keys to zero-argsync/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 enablementpredicate) and ``ensure_system_jobs`` — the idempotent startup- seed/repair pass (tamper correction, (α) status reset, (β) schedule-trust+ seed/repair pass (tamper correction, status reset, schedule-trustboundary, repair-replay, flag-off halt) called from the lifespan beforethe 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.pyindex 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 loggingimport timefrom typing import Optional-from src.scheduling.types import (- AdvanceFn,- IsDueFn,- JobErrorFn,- NowFn,- OnTickFn,-)+from src.scheduling.types import NowFn, OnTickFnlogger = 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_msself._retry_max_delay_ms = retry_max_delay_msself._on_tick = on_tick- self._is_due_fn = is_due_fn- self._advance_fn = advance_fn- self._on_job_error = on_job_errorself._task_name = task_nameself._loop: asyncio.AbstractEventLoop | None = Noneself._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 ------------------------------------------------------------@propertydiff --git a/agent/src/scheduling/registry.py b/agent/src/scheduling/registry.pyindex 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 surfaceis 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 areoffloaded through ``asyncio.to_thread``, async callables are awaiteddirectly, 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 annotationsimport refrom 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.pyindex 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: itsrow in the scheduled-research store is seeded and repaired by this module atstartup, 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 itthrough 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 crashstartup; the fix is "correct + log" (the executor's lifecycle-writeconvention — ``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 isre-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 annotationsimport logging+import reimport timefrom dataclasses import dataclass, fieldfrom typing import Callable, Optional, Sequence@@ -82,15 +98,34 @@ from src.scheduled_research.models import ()from src.scheduled_research.store import ScheduledResearchJobStorefrom src.scheduling.triggers import is_interval_schedule, next_due+from src.scheduling.types import ExecutorKindlogger = 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) resolvedthrough :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] = Noneprompt: str = ""source_type: str = "system"- executor_kind: str = "internal"+ executor_kind: ExecutorKind = "internal"enabled_predicate: EnabledPredicate = field(default=_always_enabled)+ schedule_fn: Optional[ScheduleFn] = Nonedef __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 landshere 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-runconvention: 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.timezoneif 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.PENDINGjob.end_at = None+ job.consecutive_failures = 0+ job.last_error = None+ job.failure_kind = Noneelif 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 = Noneelif 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.CANCELLEDreturn 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())continuenotes = _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.pyindex 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 anagent 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.pyindex 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_rdef 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_callableregister_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.pyindex bba8d900d..e606be7b9 100644--- a/agent/tests/scheduling/test_kernel.py+++ b/agent/tests/scheduling/test_kernel.py@@ -14,8 +14,6 @@ import asyncioimport itertoolsimport threadingimport time-from dataclasses import dataclass-from datetime import datetime, timezoneimport 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_errassert kernel.tick_interval_ms == 1234assert kernel.max_consecutive_failures == 5assert (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.pyindex 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.pyindex 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 Noneassert "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.pyindex 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-writtenor 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 Falseassert _SAFE_PATH_PARAM_RE.match(SYSTEM_ID) is Noneassert 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.pyindex 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 aprompt-dispatchable row even while the feature flag is off."""diff --git a/agent/tests/test_br_data.py b/agent/tests/test_br_data.pyindex 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_syncfrom src.scheduled_research.models import JobStatusfrom src.scheduling.registry import is_registered, resolve_internalfrom 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_enabledassert 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 Noneassert 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):