Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(scheduling): add allowlist registry for internal callables

shadowinlife05fa89c1ef2a
diff --git a/agent/src/api/scheduled_routes.py b/agent/src/api/scheduled_routes.py
index 70eee738c..233b786fd 100644
--- a/agent/src/api/scheduled_routes.py
+++ b/agent/src/api/scheduled_routes.py
@@ -90,6 +90,22 @@ 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.
@@ -170,6 +186,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,
)
return _scheduled_research_executor
diff --git a/agent/src/scheduled_research/executor.py b/agent/src/scheduled_research/executor.py
index bf8566030..1216902c7 100644
--- a/agent/src/scheduled_research/executor.py
+++ b/agent/src/scheduled_research/executor.py
@@ -10,6 +10,12 @@ backoff — is delegated to :class:`src.scheduling.kernel.SchedulerKernel`
(scheduler unification). This module keeps the scheduled-research domain: the
tick composition (stale recovery, expiry, due dispatch, delivery sweep), the
job state machine, the delivery outbox and verdict recording.
+
+``executor_kind == "internal"`` jobs are dispatched non-blockingly through
+:class:`src.scheduled_research.internal_dispatch.InternalRunSupervisor`:
+registry-resolved callables run in fire-and-forget background tasks (sync
+ones off the loop via ``asyncio.to_thread``) that own the terminal write, so
+an hours-long internal run never freezes the serialized tick.
"""
from __future__ import annotations
@@ -21,6 +27,10 @@ from typing import Awaitable, Callable, Optional
from src.config.accessor import get_env_config
from src.channels.bus.events import DeliveryReceipt
+from src.scheduled_research.internal_dispatch import (
+ InternalDispatchCallback,
+ InternalRunSupervisor,
+)
from src.scheduled_research.models import (
DeliveryRecord,
DeliveryStatus,
@@ -157,7 +167,7 @@ class ScheduledResearchExecutor:
briefing_reader: "BriefingReader | None" = None,
channel_sender: "ChannelSender | None" = None,
delivery_lease_ms: int = DEFAULT_DELIVERY_LEASE_MS,
- internal_dispatcher: "DispatchCallback | None" = None,
+ internal_dispatcher: "InternalDispatchCallback | None" = None,
) -> None:
"""Initialize the executor.
@@ -179,11 +189,14 @@ class ScheduledResearchExecutor:
delivery_lease_ms: How long a claimed row stays claimed before a
later sweep may take it over. Too short duplicates a slow
send; too long strands a briefing behind a dead process.
- internal_dispatcher: Async callable invoked for jobs whose
- ``executor_kind`` is ``"internal"``. ``None`` (the default)
- leaves internal jobs without a runner, so their firings take
- the existing dispatch-failure path; the registry-backed
- implementation is wired separately.
+ internal_dispatcher: Callable resolving one ``executor_kind ==
+ "internal"`` job to its registered zero-arg callable — in
+ production the exact-key allowlist lookup in
+ :mod:`src.scheduling.registry`. ``None`` (the default) keeps
+ internal jobs fail-closed: their firings take the existing
+ dispatch-failure path. The resolved callable never runs on
+ the tick loop; :class:`InternalRunSupervisor` owns the
+ non-blocking run and its terminal write.
Raises:
ValueError: If the retry policy is invalid.
@@ -231,6 +244,12 @@ class ScheduledResearchExecutor:
is_due_fn=is_due,
task_name="scheduled-research-executor",
)
+ self._internal = InternalRunSupervisor(
+ store=store,
+ dispatcher=internal_dispatcher,
+ finish_run=self._finish_run,
+ now_fn=now_fn,
+ )
self._recovered_stale_running = False
@property
@@ -254,8 +273,17 @@ class ScheduledResearchExecutor:
Idempotent. When disabled or not started, this is a no-op. The kernel
sets the wakeup so a sleeping loop returns at once, and cancels the
task as a fallback so shutdown never blocks for a full tick.
+
+ In-flight internal runs are then cancelled at the asyncio-task level,
+ never at the thread level (pinned semantics, see
+ :mod:`src.scheduled_research.internal_dispatch`): a sync callable
+ already inside ``asyncio.to_thread`` finishes harmlessly with its
+ result discarded, and its job stays RUNNING in the store for
+ ``recover_stale_running`` on the next start. ``stop()`` does not wait
+ for those threads, so it stays bounded however long a callable blocks.
"""
await self._kernel.stop()
+ await self._internal.cancel_all()
async def tick(self, now_ms: int | None = None) -> None:
"""Run one poll/dispatch pass.
@@ -375,6 +403,14 @@ class ScheduledResearchExecutor:
self._persist_completion(job)
return
+ if job.executor_kind == "internal":
+ # Non-blocking internal dispatch: resolve → RUNNING → a
+ # fire-and-forget background task owns the callable and the
+ # terminal write. Awaiting the run here would freeze the
+ # serialized tick loop for hours (see internal_dispatch.py).
+ self._internal.launch(job, now_ms)
+ return
+
job.status = JobStatus.RUNNING
# Lifecycle writes bypass validation: this record is already persisted,
# and a write that cannot land would strand the job mid-flight.
@@ -382,7 +418,7 @@ class ScheduledResearchExecutor:
dispatch_error: Exception | None = None
try:
- session_id = await self._dispatch_job(job)
+ session_id = await self._dispatch(job)
if isinstance(session_id, str) and session_id:
if job.delivery_channel:
# Arm the outbox in the same write that records the firing.
@@ -413,6 +449,18 @@ class ScheduledResearchExecutor:
else:
job.consecutive_failures = 0
+ self._finish_run(job, dispatch_error, now_ms)
+
+ def _finish_run(
+ self, job: ScheduledResearchJob, dispatch_error: Exception | None, now_ms: int
+ ) -> None:
+ """Record one attempt's outcome and persist the terminal state.
+
+ Shared by the prompt path — *now_ms* is the firing time, dispatch
+ returns at enqueue — and the internal background path, which passes
+ the COMPLETION time so a run longer than its own schedule interval
+ advances past completion instead of re-firing immediately.
+ """
job.last_run_at = now_ms
try:
scheduled_next_run = next_due(job.schedule, now_ms, job.timezone)
@@ -453,23 +501,6 @@ class ScheduledResearchExecutor:
)
self._persist_completion(job)
- async def _dispatch_job(self, job: ScheduledResearchJob) -> Optional[str]:
- """Route one firing to its executor kind.
-
- ``"prompt"`` jobs (every job persisted before scheduler unification)
- go through the injected ``dispatch`` callback exactly as before.
- ``"internal"`` jobs go through ``internal_dispatcher``; while no
- dispatcher is wired, raising here routes the firing into the existing
- dispatch-failure path (``failure_kind="dispatch"``, bounded retries)
- rather than silently skipping it.
- """
- if job.executor_kind == "internal":
- dispatcher = self._internal_dispatcher
- if dispatcher is None:
- raise RuntimeError("internal dispatcher is not configured")
- return await dispatcher(job)
- return await self._dispatch(job)
-
def _delivery_is_eligible(self, job: ScheduledResearchJob, now_ms: int) -> bool:
"""Whether this row is a sweep's to take.
diff --git a/agent/src/scheduled_research/internal_dispatch.py b/agent/src/scheduled_research/internal_dispatch.py
new file mode 100644
index 000000000..c293e572c
--- /dev/null
+++ b/agent/src/scheduled_research/internal_dispatch.py
@@ -0,0 +1,169 @@
+"""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
+executor's internal-dispatch contract:
+
+* Resolve synchronously through the injected dispatcher — in production an
+ exact-key allowlist lookup in :mod:`src.scheduling.registry`. A missing
+ dispatcher, an unregistered name or a tampered ``internal_callable``
+ raises, and the firing routes into the executor's existing
+ dispatch-failure path (``failure_kind="dispatch"``, bounded retries)
+ without the job ever going RUNNING.
+* Never block the serialized tick loop: a resolved callable runs in a
+ background ``asyncio`` task — sync callables through ``asyncio.to_thread``,
+ async callables awaited directly — because registry callables (the first
+ ``br_data`` sync, memory consolidation) can block for hours. Awaiting
+ inside the tick would freeze every other due job and the delivery sweep
+ until the 5-minute outbox lease expires.
+* The background task owns the terminal write: it calls the executor's
+ shared ``finish_run`` bookkeeping (COMPLETED/FAILED, ``next_run_at``
+ advance, reload-skip in ``_persist_completion``, ``consecutive_failures``
+ rules) with the COMPLETION time, so a run longer than its own interval
+ advances past completion instead of re-firing immediately.
+* PINNED shutdown semantics: :meth:`InternalRunSupervisor.cancel_all`
+ cancels the asyncio TASK, never the thread underneath ``to_thread`` — a
+ sync callable already running in its thread finishes harmlessly and its
+ result is discarded — and NO terminal write happens on cancel: the job
+ stays RUNNING in the store, so the next process start's
+ ``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.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Callable, Optional
+
+from src.scheduled_research.models import JobStatus, ScheduledResearchJob
+from src.scheduled_research.store import ScheduledResearchJobStore
+from src.scheduling.registry import InternalRunnable
+
+logger = logging.getLogger(__name__)
+
+#: (job, error-or-None, reference-time-ms) -> terminal persistence. Bound to
+#: the executor's ``_finish_run``; ``None`` error means success.
+FinishRunFn = Callable[[ScheduledResearchJob, Optional[Exception], int], None]
+#: Resolves one internal job to its registered callable; raises on any
+#: unregistered/tampered name (allowlist lookup, never string parsing).
+InternalDispatchCallback = Callable[[ScheduledResearchJob], InternalRunnable]
+
+
+class InternalRunSupervisor:
+ """Owns the non-blocking run lifecycle of ``executor_kind="internal"`` jobs.
+
+ The executor keeps every scheduling decision; this class only moves the
+ blocking work off the tick loop and hands the outcome back through
+ *finish_run*. See the module docstring for the full contract, including
+ the pinned cancel-not-kill shutdown semantics.
+ """
+
+ def __init__(
+ self,
+ *,
+ store: ScheduledResearchJobStore,
+ dispatcher: Optional[InternalDispatchCallback],
+ finish_run: FinishRunFn,
+ now_fn: Callable[[], int],
+ ) -> None:
+ """Initialize the supervisor.
+
+ Args:
+ store: Durable job store (RUNNING mark before the run starts).
+ dispatcher: Registry resolver, or ``None`` to keep internal jobs
+ fail-closed through the dispatch-failure path.
+ finish_run: The executor's shared terminal-write bookkeeping.
+ now_fn: Injectable wall-clock source returning epoch milliseconds.
+ """
+ self._store = store
+ self._dispatcher = dispatcher
+ self._finish_run = finish_run
+ self._now_fn = now_fn
+ self._tasks: set[asyncio.Task] = set()
+
+ def resolve(self, job: ScheduledResearchJob) -> InternalRunnable:
+ """Return the registered callable for *job*, or raise.
+
+ ``None`` dispatcher keeps the fail-closed default wired in T4: the
+ RuntimeError lands in the dispatch-failure path exactly as before the
+ registry existed. Resolution itself is the dispatcher's allowlist
+ lookup; this class never resolves names by string parsing.
+ """
+ dispatcher = self._dispatcher
+ if dispatcher is None:
+ raise RuntimeError("internal dispatcher is not configured")
+ runnable = dispatcher(job)
+ if not callable(runnable):
+ raise TypeError("internal dispatcher returned a non-callable")
+ return runnable
+
+ def launch(self, job: ScheduledResearchJob, now_ms: int) -> None:
+ """Mark *job* RUNNING and hand its callable to a background task.
+
+ Synchronous and non-blocking: returns as soon as the task exists (or
+ the resolve failure has been persisted). The caller — the executor's
+ ``_run_job`` — returns to the tick immediately afterwards.
+ """
+ try:
+ runnable = self.resolve(job)
+ except asyncio.CancelledError:
+ raise
+ except Exception as exc:
+ logger.error("internal dispatch failed for job %s", job.id, exc_info=True)
+ job.consecutive_failures += 1
+ self._finish_run(job, exc, now_ms)
+ return
+
+ job.status = JobStatus.RUNNING
+ # Lifecycle writes bypass validation: this record is already persisted,
+ # and a write that cannot land would strand the job mid-flight.
+ self._store.upsert(job, validate=False)
+ task = asyncio.create_task(
+ self._run_to_terminal(job, runnable),
+ name=f"scheduled-research-internal-{job.id}",
+ )
+ self._tasks.add(task)
+ task.add_done_callback(self._tasks.discard)
+
+ async def _run_to_terminal(self, job: ScheduledResearchJob, runnable: InternalRunnable) -> None:
+ """Run the callable off the loop, then own the terminal write.
+
+ Sync callables go through ``asyncio.to_thread`` (they may block for
+ hours), async callables are awaited directly. On cancellation the
+ pinned shutdown semantics apply (module docstring): log, leave the
+ job RUNNING, re-raise — no terminal write, no failure count.
+ """
+ try:
+ if asyncio.iscoroutinefunction(runnable):
+ await runnable()
+ else:
+ await asyncio.to_thread(runnable)
+ except asyncio.CancelledError:
+ logger.warning(
+ "internal job %s cancelled at shutdown; left RUNNING for stale-recovery", job.id
+ )
+ raise
+ except Exception as exc:
+ logger.error("internal job %s failed", job.id, exc_info=True)
+ job.consecutive_failures += 1
+ self._finish_run(job, exc, self._now_fn())
+ else:
+ job.consecutive_failures = 0
+ self._finish_run(job, None, self._now_fn())
+
+ async def cancel_all(self) -> None:
+ """Cancel every in-flight internal task; bounded (module docstring).
+
+ Cancellation lands at the task's await point on the next loop pass
+ and the handler above does no I/O, so the gather returns promptly
+ even while a ``to_thread`` thread keeps running underneath. Threads
+ are never killed: their callables finish harmlessly, results
+ discarded, jobs left RUNNING for stale-recovery.
+ """
+ tasks = list(self._tasks)
+ for task in tasks:
+ task.cancel()
+ if tasks:
+ await asyncio.gather(*tasks, return_exceptions=True)
diff --git a/agent/src/scheduling/__init__.py b/agent/src/scheduling/__init__.py
index 909364a12..4e4475caf 100644
--- a/agent/src/scheduling/__init__.py
+++ b/agent/src/scheduling/__init__.py
@@ -12,11 +12,15 @@ in the repo can adopt:
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 (nothing is wired to it yet).
+ clock and callback seams for domain logic (consumed by the scheduled
+ research executor since T4).
+* :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).
-Later todos of the scheduler-unification plan add ``registry.py`` (internal
-callable allowlist) and ``system_jobs.py`` (protected system jobs) beside
-these modules.
+Later todos of the scheduler-unification plan add ``system_jobs.py``
+(protected system jobs) beside these modules.
"""
from src.scheduling.kernel import (
@@ -27,6 +31,14 @@ from src.scheduling.kernel import (
DEFAULT_TASK_NAME,
SchedulerKernel,
)
+from src.scheduling.registry import (
+ InternalCallableError,
+ InternalRunnable,
+ is_registered,
+ list_internal,
+ register_internal,
+ resolve_internal,
+)
from src.scheduling.triggers import (
CRON_BOUNDS,
CRON_SEARCH_LIMIT_DAYS,
@@ -70,6 +82,8 @@ __all__ = [
"ONCE_SPEC",
"AdvanceFn",
"ExecutorKind",
+ "InternalCallableError",
+ "InternalRunnable",
"IsDueFn",
"JobErrorFn",
"JobLike",
@@ -80,11 +94,15 @@ __all__ = [
"day_matches",
"is_executor_kind",
"is_interval_schedule",
+ "is_registered",
+ "list_internal",
"local_wall_time_to_epoch_ms",
"next_cron_due",
"next_due",
"next_once_due",
"parse_cron_field",
+ "register_internal",
+ "resolve_internal",
"trigger_interval_ms",
"validate_schedule",
"validate_timezone",
diff --git a/agent/src/scheduling/registry.py b/agent/src/scheduling/registry.py
new file mode 100644
index 000000000..a9da579cf
--- /dev/null
+++ b/agent/src/scheduling/registry.py
@@ -0,0 +1,144 @@
+"""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"):
+
+* Keys are literal strings registered in THIS module. The production surface
+ is the explicit ``_INTERNAL_CALLABLES`` dict at the bottom, populated by
+ module edit only. Nothing in a request path (HTTP body, job file free
+ text, environment variable) may ever register a callable;
+ :func:`register_internal` exists for module edits and tests.
+* Resolution is an exact-key dict lookup. There is NO dynamic resolution of
+ any kind: names are never parsed as import paths, never turned into code,
+ and never walked through attribute chains. A name that happens to be a
+ real import path (a stdlib process-spawning function, say) resolves to
+ nothing unless that exact string is a registered key — the registry's
+ name space and Python's import space are fully isolated.
+* Malformed names are rejected before any lookup: the shape allowlist
+ (dotted identifiers only) fails every separator, ``..``, whitespace and
+ shell-metacharacter form by construction.
+* Values are callables taking no required arguments, sync or async. The run
+ contract lives on the executor side (see
+ :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.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Awaitable, Callable
+
+#: 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.
+InternalRunnable = Callable[..., Awaitable[None] | None]
+
+#: Dotted-identifier shape allowlist, e.g. ``memory.consolidate``. Being an
+#: allowlist (not a denylist) is the point: path separators, ``..``, ``:``,
+#: whitespace and shell metacharacters (``; | & $ < > ( )`` and backtick)
+#: fail the shape check by construction and never reach the dict.
+_VALID_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+class InternalCallableError(KeyError):
+ """A name cannot be resolved to a registered internal callable.
+
+ Subclasses :class:`KeyError` so consumers may catch either; ``__str__``
+ is overridden because :class:`KeyError` would otherwise ``repr()`` the
+ message and quote it.
+ """
+
+ def __str__(self) -> str:
+ return str(self.args[0]) if self.args else ""
+
+
+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):
+ raise InternalCallableError(
+ f"internal callable name {name!r} is rejected: only dotted identifiers "
+ "(letters, digits, '_', single '.' separators) are allowed"
+ )
+ return name
+
+
+def register_internal(name: str, fn: InternalRunnable, *, replace: bool = False) -> None:
+ """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``.
+
+ Args:
+ name: Literal registry key (dotted-identifier shape).
+ fn: Zero-required-arg callable, sync or async.
+ replace: Allow overwriting an existing key. Off by default so a
+ production entry is never silently clobbered.
+
+ Raises:
+ InternalCallableError: *name* is malformed, or already registered
+ without ``replace=True``.
+ TypeError: *fn* is not callable.
+ """
+ key = _check_name(name)
+ if not callable(fn):
+ raise TypeError(f"internal callable {key!r} requires a callable, got {type(fn).__name__}")
+ if not replace and key in _INTERNAL_CALLABLES:
+ raise InternalCallableError(f"internal callable {key!r} is already registered")
+ _INTERNAL_CALLABLES[key] = fn
+
+
+def resolve_internal(name: str) -> InternalRunnable:
+ """Return the callable registered under the EXACT key *name*.
+
+ Exact-key dict lookup only — never a prefix match, never a parse, never
+ a fallback to Python's import machinery.
+
+ Args:
+ name: Registry key from a job's ``internal_callable`` field.
+
+ Returns:
+ The registered callable object (identity preserved).
+
+ Raises:
+ InternalCallableError: *name* is malformed (rejected before lookup)
+ or is not a registered key; the message for an unregistered
+ well-formed name lists every registered name.
+ """
+ key = _check_name(name)
+ try:
+ return _INTERNAL_CALLABLES[key]
+ except KeyError:
+ raise InternalCallableError(
+ f"internal callable {key!r} is not registered; registered names: {list_internal()}"
+ ) from None
+
+
+def list_internal() -> tuple[str, ...]:
+ """Return every registered key, sorted."""
+ return tuple(sorted(_INTERNAL_CALLABLES))
+
+
+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
+
+
+# ---------------------------------------------------------------------------
+# Production allowlist — the ONLY name→callable surface (module docstring).
+#
+# Scheduler-unification T8/T9 append entries HERE by module edit, e.g.:
+#
+# from src.memory.lifecycle import consolidate as _consolidate
+# _INTERNAL_CALLABLES["memory.consolidate"] = _consolidate
+#
+# Rules: literal keys only; values are imported callable objects, never
+# import-path strings; nothing populates this dict from runtime input.
+# Seeded EMPTY by T5 — until T6+ registers system jobs, every internal
+# firing fail-closes into the executor's dispatch-failure path
+# (``failure_kind="dispatch"``), which is the intended behavior.
+# ---------------------------------------------------------------------------
+_INTERNAL_CALLABLES: dict[str, InternalRunnable] = {}
diff --git a/agent/tests/scheduling/conftest.py b/agent/tests/scheduling/conftest.py
new file mode 100644
index 000000000..deaefce2a
--- /dev/null
+++ b/agent/tests/scheduling/conftest.py
@@ -0,0 +1,22 @@
+"""Shared fixtures for scheduling tests."""
+
+from __future__ import annotations
+
+import pytest
+
+from src.scheduling.registry import _INTERNAL_CALLABLES
+
+
+def clean_registry():
+ """Snapshot/restore the internal-callable registry.
+
+ Test registrations must never leak into other tests or into the
+ production (empty-until-T8/T9) allowlist surface.
+ """
+ saved = dict(_INTERNAL_CALLABLES)
+ try:
+ yield _INTERNAL_CALLABLES
+ finally:
+ _INTERNAL_CALLABLES.clear()
+ _INTERNAL_CALLABLES.update(saved)
diff --git a/agent/tests/scheduling/test_internal_dispatch.py b/agent/tests/scheduling/test_internal_dispatch.py
new file mode 100644
index 000000000..e4a323418
--- /dev/null
+++ b/agent/tests/scheduling/test_internal_dispatch.py
@@ -0,0 +1,530 @@
+"""Internal-dispatch execution semantics (scheduler unification T5).
+
+Proves the plan's acceptance criteria (a)-(f) mechanically, with injected
+clocks and Event-driven stuck callables (no real sleeps > 1s):
+
+(a) a stuck internal run never blocks the serialized tick — other due jobs
+ are still dispatched and ``sweep_deliveries`` still runs;
+(b) the running job stays RUNNING and is not re-dispatched across ticks;
+(c) the background task owns the terminal write (COMPLETED/FAILED,
+ ``next_run_at`` advance, reload-skip, failure cap) and crash-restart
+ interplay with ``recover_stale_running``;
+(d) ``stop()`` is bounded against an in-flight ``to_thread`` task and the
+ pinned cancel-not-kill semantics leave the job RUNNING;
+(f) the production singleton from ``_get_scheduled_research_executor()``
+ routes internal jobs through the registry branch (``failure_kind`` is
+ not ``"dispatch"``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from pathlib import Path
+
+import pytest
+from src.scheduled_research.executor import ScheduledResearchExecutor
+from src.scheduled_research.models import JobStatus, ScheduledResearchJob
+from src.scheduled_research.store import ScheduledResearchJobStore
+from src.scheduling.registry import InternalCallableError, register_internal, resolve_internal
+
+
+def _store(tmp_path: Path) -> ScheduledResearchJobStore:
+ return ScheduledResearchJobStore(path=tmp_path / "jobs.json")
+
+
+def _internal_job(
+ job_id: str = "slow",
+ *,
+ callable_name: str = "test.slow",
+ schedule: str = "1000",
+ next_run_at: int = 1000,
+ created_at: int = 0,
+ **overrides: object,
+) -> ScheduledResearchJob:
+ return ScheduledResearchJob(
+ id=job_id,
+ prompt="",
+ schedule=schedule,
+ next_run_at=next_run_at,
+ created_at=created_at,
+ executor_kind="internal",
+ internal_callable=callable_name,
+ **overrides, # type: ignore[arg-type]
+ )
+
+
+def _resolver(job: ScheduledResearchJob):
+ """Production-shaped dispatcher: exact-key registry lookup, may raise."""
+ return resolve_internal(job.internal_callable)
+
+
+class _StuckCallable:
+ """Sync callable that blocks a to_thread worker until released."""
+
+ def __init__(self) -> None:
+ self.started = threading.Event()
+ self.release = threading.Event()
+ self.finished = threading.Event()
+ self.calls = 0
+
+ def __call__(self) -> None:
+ self.calls += 1
+ self.started.set()
+ self.release.wait(10)
+ self.finished.set()
+
+
+async def _drain(executor: ScheduledResearchExecutor) -> None:
+ """Await every in-flight internal background task (test-only reach-in)."""
+ tasks = list(executor._internal._tasks)
+ if tasks:
+ await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=10)
+
+
+# ---------------------------------------------------------------------------
+# (a)+(b)+(c) non-blocking dispatch, no re-dispatch, background terminal write
+# ---------------------------------------------------------------------------
+
+
+def test_stuck_internal_run_does_not_block_tick_and_terminal_written_by_background(
+ tmp_path: Path, clean_registry
+) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("a-slow", callable_name="test.slow", next_run_at=1000))
+ store.upsert(
+ ScheduledResearchJob(
+ id="b-other", prompt="p", schedule="1000", next_run_at=1000, created_at=0
+ )
+ )
+ stuck = _StuckCallable()
+ register_internal("test.slow", stuck)
+ prompt_calls: list[str] = []
+ clock = [1500]
+
+ async def dispatch(job: ScheduledResearchJob) -> None:
+ prompt_calls.append(job.id)
+
+ sweep_results: list[int] = []
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, dispatch, internal_dispatcher=_resolver, now_fn=lambda: clock[0]
+ )
+ original_sweep = executor.sweep_deliveries
+
+ async def counting_sweep() -> int:
+ result = await original_sweep()
+ sweep_results.append(result)
+ return result
+
+ executor.sweep_deliveries = counting_sweep # type: ignore[method-assign]
+ try:
+ # Tick 1: spawns the stuck internal run AND dispatches the other
+ # due job AND sweeps — all in the same tick, without waiting.
+ await executor.tick(1500)
+ assert await asyncio.to_thread(stuck.started.wait, 5), "to_thread worker never started"
+ assert prompt_calls == ["b-other"], "tick was blocked by the internal run"
+ assert len(sweep_results) == 1, "sweep_deliveries did not run in tick 1"
+ running = store.get("a-slow")
+ assert running is not None and running.status == JobStatus.RUNNING
+ assert running.last_run_at is None # terminal write not due yet
+
+ # Tick 2 while still stuck: (b) no re-dispatch of the RUNNING job.
+ await executor.tick(2500)
+ assert stuck.calls == 1, "RUNNING internal job was re-dispatched"
+ assert len(sweep_results) == 2, "sweep_deliveries did not run in tick 2"
+ assert store.get("a-slow").status == JobStatus.RUNNING
+
+ # (c) release: the BACKGROUND task owns the terminal write.
+ clock[0] = 4000
+ stuck.release.set()
+ await _drain(executor)
+ finally:
+ stuck.release.set()
+
+ asyncio.run(scenario())
+
+ assert stuck.finished.is_set()
+ saved = store.get("a-slow")
+ assert saved is not None
+ assert saved.status == JobStatus.COMPLETED
+ assert saved.failure_kind is None
+ assert saved.last_error is None
+ assert saved.consecutive_failures == 0
+ # Completion-time bookkeeping: last_run_at/advance use the completion
+ # clock (4000), so a run longer than its interval cannot re-fire at once.
+ assert saved.last_run_at == 4000
+ assert saved.next_run_at == 5000
+ # Internal runs produce no session: the delivery outbox is never armed.
+ assert not saved.delivery.session_id
+ assert prompt_calls == ["b-other", "b-other"] # tick 2 fired b-other again
+
+
+def test_async_internal_callable_is_awaited_directly(tmp_path: Path, clean_registry) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("async-job", callable_name="test.async"))
+ done = asyncio.Event()
+ calls: list[str] = []
+
+ async def fake_async() -> None:
+ calls.append("ran")
+ done.set()
+
+ register_internal("test.async", fake_async)
+ clock = [1500]
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: clock[0]
+ )
+ await executor.tick(1500)
+ await asyncio.wait_for(done.wait(), timeout=5)
+ await _drain(executor)
+
+ asyncio.run(scenario())
+
+ assert calls == ["ran"]
+ saved = store.get("async-job")
+ assert saved is not None and saved.status == JobStatus.COMPLETED
+ assert saved.next_run_at == 2500
+
+
+# ---------------------------------------------------------------------------
+# (c) failure bookkeeping: retry, cap, success-resets
+# ---------------------------------------------------------------------------
+
+
+def test_internal_failure_retries_then_caps_like_the_prompt_path(
+ tmp_path: Path, clean_registry
+) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("bad", callable_name="test.bad"))
+
+ def boom() -> None:
+ raise RuntimeError("boom")
+
+ register_internal("test.bad", boom)
+ clock = [1500]
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store,
+ lambda _j: None,
+ internal_dispatcher=_resolver,
+ now_fn=lambda: clock[0],
+ max_consecutive_failures=2,
+ retry_base_delay_ms=1000,
+ retry_max_delay_ms=100_000,
+ )
+ await executor.tick(1500)
+ await _drain(executor)
+
+ first = store.get("bad")
+ assert first is not None
+ assert first.status == JobStatus.PENDING # retryable, 1/2
+ assert first.failure_kind == "dispatch"
+ assert first.consecutive_failures == 1
+ assert "boom" in (first.last_error or "")
+ # max(next_due=2500, completion 1500 + retry delay 1000) = 2500
+ assert first.next_run_at == 2500
+
+ clock[0] = first.next_run_at
+ await executor.tick(clock[0])
+ await _drain(executor)
+
+ asyncio.run(scenario())
+
+ second = store.get("bad")
+ assert second is not None
+ assert second.status == JobStatus.FAILED # cap reached, terminal
+ assert second.failure_kind == "dispatch"
+ assert second.consecutive_failures == 2
+
+
+def test_internal_success_resets_consecutive_failures(tmp_path: Path, clean_registry) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("flaky", callable_name="test.ok", consecutive_failures=1))
+ register_internal("test.ok", lambda: None)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ await executor.tick(1500)
+ await _drain(executor)
+
+ asyncio.run(scenario())
+
+ saved = store.get("flaky")
+ assert saved is not None
+ assert saved.status == JobStatus.COMPLETED
+ assert saved.consecutive_failures == 0
+ assert saved.failure_kind is None
+
+
+# ---------------------------------------------------------------------------
+# Fail-closed: missing dispatcher / tampered name → dispatch-failure path
+# ---------------------------------------------------------------------------
+
+
+def test_internal_job_without_dispatcher_fails_closed(tmp_path: Path) -> None:
+ """T4 default preserved: None dispatcher → dispatch-failure path."""
+ store = _store(tmp_path)
+ store.upsert(_internal_job("orphan", callable_name="test.whatever"))
+ prompt_calls: list[str] = []
+
+ async def dispatch(job: ScheduledResearchJob) -> None:
+ prompt_calls.append(job.id)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(store, dispatch, now_fn=lambda: 1500)
+ await executor.tick(1500)
+ assert not executor._internal._tasks # resolve failed synchronously
+
+ asyncio.run(scenario())
+
+ saved = store.get("orphan")
+ assert saved is not None
+ assert saved.status == JobStatus.PENDING
+ assert saved.failure_kind == "dispatch"
+ assert "internal dispatcher is not configured" in (saved.last_error or "")
+ assert prompt_calls == [] # prompt dispatch never called for internal jobs
+
+
+def test_tampered_callable_name_takes_dispatch_failure_path(
+ tmp_path: Path, clean_registry
+) -> None:
+ """Break-probe as a test: a job file tampered to name a real import path
+ (a stdlib process-spawning function) is rejected by the allowlist; the
+ prompt dispatch is never called and nothing outside the registry runs."""
+ store = _store(tmp_path)
+ store.upsert(_internal_job("tampered", callable_name="os.system"))
+ prompt_calls: list[str] = []
+
+ async def dispatch(job: ScheduledResearchJob) -> None:
+ prompt_calls.append(job.id)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, dispatch, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ await executor.tick(1500)
+
+ asyncio.run(scenario())
+
+ saved = store.get("tampered")
+ assert saved is not None
+ assert saved.status == JobStatus.PENDING
+ assert saved.failure_kind == "dispatch"
+ assert "not registered" in (saved.last_error or "")
+ assert prompt_calls == []
+
+
+# ---------------------------------------------------------------------------
+# (c) reload-skip semantics + crash-restart interplay
+# ---------------------------------------------------------------------------
+
+
+def test_internal_job_deleted_while_running_is_not_resurrected(
+ tmp_path: Path, clean_registry
+) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("doomed", callable_name="test.slow"))
+ stuck = _StuckCallable()
+ register_internal("test.slow", stuck)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ await executor.tick(1500)
+ assert await asyncio.to_thread(stuck.started.wait, 5)
+ jobs = store.load()
+ jobs.pop("doomed")
+ store.save(jobs) # user DELETE while the run is in flight
+ stuck.release.set()
+ await _drain(executor)
+
+ try:
+ asyncio.run(scenario())
+ finally:
+ stuck.release.set()
+
+ assert stuck.finished.is_set()
+ assert store.get("doomed") is None # completion write skipped, no resurrection
+
+
+def test_internal_job_replaced_while_running_skips_completion_write(
+ tmp_path: Path, clean_registry
+) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("replaced", callable_name="test.slow", created_at=0))
+ stuck = _StuckCallable()
+ register_internal("test.slow", stuck)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ await executor.tick(1500)
+ assert await asyncio.to_thread(stuck.started.wait, 5)
+ store.upsert(
+ _internal_job(
+ "replaced",
+ callable_name="test.slow",
+ created_at=999,
+ status=JobStatus.PENDING,
+ next_run_at=10**15,
+ )
+ )
+ stuck.release.set()
+ await _drain(executor)
+
+ try:
+ asyncio.run(scenario())
+ finally:
+ stuck.release.set()
+
+ saved = store.get("replaced")
+ assert saved is not None
+ assert saved.created_at == 999 # the replacement owns its lifecycle
+ assert saved.status == JobStatus.PENDING
+ assert saved.last_run_at is None
+
+
+def test_crash_midrun_recovers_running_on_next_start(tmp_path: Path, clean_registry) -> None:
+ store = _store(tmp_path)
+ store.upsert(_internal_job("crashed", callable_name="test.slow"))
+ stuck = _StuckCallable()
+ register_internal("test.slow", stuck)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ await executor.tick(1500)
+ assert await asyncio.to_thread(stuck.started.wait, 5)
+ # Simulate the process dying mid-run: cancel the task (as stop() does)
+ # WITHOUT any terminal write, then let the thread finish harmlessly.
+ await asyncio.wait_for(executor.stop(), timeout=2)
+ stuck.release.set()
+ assert await asyncio.to_thread(stuck.finished.wait, 5)
+ # The discarded thread result must NOT have written a terminal state.
+ abandoned = store.get("crashed")
+ assert abandoned is not None and abandoned.status == JobStatus.RUNNING
+ assert abandoned.last_run_at is None
+
+ try:
+ asyncio.run(scenario())
+ finally:
+ stuck.release.set()
+
+ # Restart: a fresh executor recovers the stale RUNNING row to PENDING.
+ executor2 = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ assert executor2.recover_stale_running() == 1
+ recovered = store.get("crashed")
+ assert recovered is not None and recovered.status == JobStatus.PENDING
+
+
+# ---------------------------------------------------------------------------
+# (d) bounded stop() with an in-flight to_thread task
+# ---------------------------------------------------------------------------
+
+
+def test_stop_is_bounded_and_leaves_inflight_job_running(tmp_path: Path, clean_registry) -> None:
+ """Pinned shutdown semantics: cancel the asyncio TASK, never the thread.
+
+ ``stop()`` returns within the wait_for bound while the sync callable is
+ still blocked in its to_thread worker; the job is left RUNNING (no
+ terminal write, no failure count) for stale-recovery on the next start,
+ and the thread later finishes harmlessly without changing the store.
+ """
+ store = _store(tmp_path)
+ store.upsert(_internal_job("stuck", callable_name="test.slow"))
+ stuck = _StuckCallable()
+ register_internal("test.slow", stuck)
+
+ async def scenario() -> None:
+ executor = ScheduledResearchExecutor(
+ store, lambda _j: None, internal_dispatcher=_resolver, now_fn=lambda: 1500
+ )
+ await executor.tick(1500)
+ assert await asyncio.to_thread(stuck.started.wait, 5)
+ await asyncio.wait_for(executor.stop(), timeout=2.0) # bounded
+ assert not executor._internal._tasks # task cancelled and drained
+ assert not stuck.finished.is_set() # thread still running, unharmed
+ stuck.release.set()
+ assert await asyncio.to_thread(stuck.finished.wait, 5) # finishes harmlessly, result discarded
+
+ try:
+ asyncio.run(scenario())
+ finally:
+ stuck.release.set()
+
+ saved = store.get("stuck")
+ assert saved is not None
+ assert saved.status == JobStatus.RUNNING
+ assert saved.last_run_at is None
+ assert saved.consecutive_failures == 0
+
+
+# ---------------------------------------------------------------------------
+# (f) production wiring: the singleton executor runs registry callables
+# ---------------------------------------------------------------------------
+
+
+def test_production_resolver_resolves_registered_and_rejects_tampered(clean_registry) -> None:
+ from src.api.scheduled_routes 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)
+ tampered = _internal_job("j", callable_name="os.system")
+ with pytest.raises(InternalCallableError):
+ _resolve_scheduled_internal_callable(tampered)
+
+
+def test_production_singleton_routes_internal_jobs_through_registry(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, clean_registry
+) -> None:
+ """(f) Mechanical proof the production construction site is wired.
+
+ The executor is obtained ONLY through ``_get_scheduled_research_executor()``
+ (the singleton the API server uses), with the store redirected to a temp
+ file; an internal job must go through the registry branch and its
+ ``failure_kind`` must not be ``"dispatch"``.
+ """
+ from src.api import scheduled_routes
+
+ isolated = ScheduledResearchJobStore(path=tmp_path / "prod_jobs.json")
+ monkeypatch.setattr(scheduled_routes, "_scheduled_research_store", isolated)
+ monkeypatch.setattr(scheduled_routes, "_scheduled_research_executor", None)
+
+ calls: list[str] = []
+
+ def prod_callable() -> None:
+ calls.append("ran")
+
+ register_internal("test.prod", prod_callable)
+ now = int(time.time() * 1000)
+ isolated.upsert(_internal_job("prod-job", callable_name="test.prod", next_run_at=now - 1000))
+
+ executor = scheduled_routes._get_scheduled_research_executor()
+ assert executor._internal_dispatcher is not None # grep-gate companion
+
+ async def scenario() -> None:
+ await executor.tick(now)
+ await _drain(executor)
+
+ asyncio.run(scenario())
+
+ assert calls == ["ran"]
+ saved = isolated.get("prod-job")
+ assert saved is not None
+ assert saved.status == JobStatus.COMPLETED
+ assert saved.failure_kind != "dispatch"
+ assert saved.failure_kind is None
diff --git a/agent/tests/scheduling/test_registry.py b/agent/tests/scheduling/test_registry.py
new file mode 100644
index 000000000..ec361a41f
--- /dev/null
+++ b/agent/tests/scheduling/test_registry.py
@@ -0,0 +1,227 @@
+"""Allowlist registry security + resolution contract (scheduler unification T5).
+
+The registry is the ONLY name→callable surface for ``executor_kind ==
+"internal"`` jobs. These tests pin: exact-key resolution, the malformed-name
+rejection table (separators, ``..``, whitespace, shell metacharacters), the
+name-space/import-space isolation (a real import path resolves to nothing
+unless literally registered), and the mechanical no-dynamic-resolution guard
+mirroring the CI grep gates.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+import src.scheduling.registry as registry
+from src.scheduling.registry import (
+ InternalCallableError,
+ _INTERNAL_CALLABLES,
+ is_registered,
+ list_internal,
+ register_internal,
+ resolve_internal,
+)
+
+
+def _fake_sync() -> None:
+ pass
+
+
+async def _fake_async() -> None:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Happy path
+# ---------------------------------------------------------------------------
+
+
+def test_registered_name_resolves_to_the_same_object(clean_registry) -> None:
+ register_internal("test.fake", _fake_sync)
+ assert resolve_internal("test.fake") is _fake_sync
+ assert is_registered("test.fake")
+ assert "test.fake" in list_internal()
+
+
+def test_sync_and_async_callables_are_both_accepted(clean_registry) -> None:
+ register_internal("test.sync", _fake_sync)
+ register_internal("test.async", _fake_async)
+ assert resolve_internal("test.sync") is _fake_sync
+ assert resolve_internal("test.async") is _fake_async
+
+
+def test_list_internal_is_a_sorted_tuple(clean_registry) -> None:
+ register_internal("test.b", _fake_sync)
+ register_internal("test.a", _fake_async)
+ listed = list_internal()
+ assert isinstance(listed, tuple)
+ assert listed == tuple(sorted(listed))
+ assert {"test.a", "test.b"} <= set(listed)
+
+
+def test_resolve_is_exact_key_only_no_prefix_or_suffix_match(clean_registry) -> None:
+ register_internal("a.b", _fake_sync)
+ with pytest.raises(InternalCallableError):
+ resolve_internal("a")
+ with pytest.raises(InternalCallableError):
+ resolve_internal("a.b.c")
+ assert not is_registered("a")
+ assert not is_registered("a.b.c")
+
+
+# ---------------------------------------------------------------------------
+# Unregistered names
+# ---------------------------------------------------------------------------
+
+
+def test_unregistered_name_error_lists_registered_names(clean_registry) -> None:
+ register_internal("test.known", _fake_sync)
+ with pytest.raises(InternalCallableError) as excinfo:
+ resolve_internal("test.unknown")
+ message = str(excinfo.value)
+ assert "test.unknown" in message
+ assert "not registered" in message
+ assert "test.known" in message
+
+
+def test_error_is_a_key_error_with_readable_str(clean_registry) -> None:
+ with pytest.raises(KeyError):
+ resolve_internal("test.absent")
+ try:
+ resolve_internal("test.absent")
+ except InternalCallableError as exc:
+ # KeyError.__str__ would repr() the message; ours must not be quoted.
+ assert str(exc) == exc.args[0]
+ assert not str(exc).startswith("'")
+
+
+ "name",
+ [
+ # Real, dangerous import paths — well-formed dotted identifiers, but
+ # NOT registered: the name space is isolated from the import space.
+ "os.system",
+ "src.br_data.sync.run_sync",
+ "shutil.rmtree",
+ ],
+)
+def test_real_import_paths_are_rejected_when_not_registered(clean_registry, name: str) -> None:
+ with pytest.raises(InternalCallableError) as excinfo:
+ resolve_internal(name)
+ assert "not registered" in str(excinfo.value)
+ assert not is_registered(name)
+ # Isolation proof: rejecting the name never touched the import machinery,
+ # so nothing new appeared in the registry either.
+ assert name not in _INTERNAL_CALLABLES
+
+
+# ---------------------------------------------------------------------------
+# Malformed-name rejection table
+# ---------------------------------------------------------------------------
+
+
+ "name",
+ [
+ "../../etc/passwd",
+ "a:b",
+ "a/b",
+ "a\\b",
+ "a; rm -rf /",
+ "a|b",
+ "a$(x)",
+ "a`x`",
+ " a ",
+ "",
+ "a b",
+ "a&&b",
+ "a>b",
+ "a<b",
+ "a(b)",
+ "..",
+ ".",
+ "a..b",
+ ".a",
+ "a.",
+ "a\nb",
+ "a\tb",
+ "os.system; ls",
+ "memory.consolidate --force",
+ ],
+)
+def test_malformed_names_are_rejected_before_any_lookup(clean_registry, name: str) -> None:
+ register_internal("test.known", _fake_sync)
+ with pytest.raises(InternalCallableError) as excinfo:
+ resolve_internal(name)
+ assert "rejected" in str(excinfo.value)
+ assert not is_registered(name)
+
+
[email protected]("name", [None, 123, b"os.system", ("os", "system")])
+def test_non_string_names_are_rejected(clean_registry, name: object) -> None:
+ with pytest.raises(InternalCallableError):
+ resolve_internal(name) # type: ignore[arg-type]
+ assert not is_registered(name)
+
+
+def test_is_registered_never_raises(clean_registry) -> None:
+ for name in ("", " a ", "a/b", None, 123, "os.system", "test.known"):
+ assert isinstance(is_registered(name), bool)
+
+
+# ---------------------------------------------------------------------------
+# register_internal validation (module/test-only surface)
+# ---------------------------------------------------------------------------
+
+
+def test_register_rejects_malformed_names_and_non_callables(clean_registry) -> None:
+ with pytest.raises(InternalCallableError):
+ register_internal("a/b", _fake_sync)
+ with pytest.raises(InternalCallableError):
+ register_internal("", _fake_sync)
+ with pytest.raises(TypeError):
+ register_internal("test.not_callable", "src.memory.consolidate") # type: ignore[arg-type]
+ assert list_internal() == () or "test.not_callable" not in list_internal()
+
+
+def test_register_rejects_silent_overwrite_without_replace(clean_registry) -> None:
+ register_internal("test.dup", _fake_sync)
+ with pytest.raises(InternalCallableError):
+ register_internal("test.dup", _fake_async)
+ assert resolve_internal("test.dup") is _fake_sync
+ register_internal("test.dup", _fake_async, replace=True)
+ assert resolve_internal("test.dup") is _fake_async
+
+
+def test_test_registrations_do_not_leak_between_tests() -> None:
+ # No clean_registry fixture here: whatever previous tests registered must
+ # already be gone (the fixture restores the snapshot on teardown).
+ assert not is_registered("test.fake")
+ assert not is_registered("test.dup")
+
+
+# ---------------------------------------------------------------------------
+# Mechanical guards (mirror the CI grep gates inside the test suite)
+# ---------------------------------------------------------------------------
+
+
+def test_registry_source_has_no_dynamic_resolution_tokens() -> None:
+ source = Path(registry.__file__).read_text(encoding="utf-8")
+ for token in ("import_module", "__import__", "eval(", "getattr("):
+ assert token not in source, f"registry.py must never contain {token!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"):
+ assert token not in source, f"registry.py must never contain {token!r}"
+
+
+def test_register_internal_is_documented_module_and_test_only() -> None:
+ # Invariant guard: runtime string registration is not a production
+ # 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__