work_queue_manage.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/scripts/work_queue_manage.py
 
# OCT-LINT: disable=tests_exist reason="Wiring shim; covered by oc_chat/tests/unit/test_271_queue_shims.py"
"""
The queue's operator surface — moved to :mod:`oc_orchestrator.work_queue_manage`.
 
Purpose
-------
Plan 271 P3. The CLI now lives in the standalone ``oc_orchestrator``
package. This file keeps ``oc_chat.scripts.work_queue_manage`` working —
the path ``MULTI_AGENT_WORKFLOW.md`` §6.1 and every orchestrator command
have always named — and supplies the two defaults that are oc_chat's and
not the package's:
 
- **the program name.** ``--help`` must print exactly what it printed
  before the split, and ``prog`` is the only line in it that could differ.
- **the registry backend.** The package declares ``--backend registry``
  as a plugin point and holds no registry to fill it; oc_chat has one, so
  this is where the factory is built. ``--backend registry`` therefore
  behaves byte for byte as it did before the split, and the four lazy
  registry imports that used to sit inside the package's
  ``_build_backend`` sit here instead — which is precisely the seam the
  plan-258 receipt modelled as a named ``--cut``.
 
Unlike the two ``core/`` queue shims this module is NOT a rebinding,
because it has behaviour of its own: those two defaults. Every other name
is delegated by :func:`__getattr__`.
 
Responsibilities
----------------
- :func:`main` — the package's CLI with oc_chat's ``prog`` and factory.
- :func:`_registry_backend` — the registry arm, verbatim from the pre-271
  module's ``_build_backend``.
- :func:`__getattr__` — every other name, delegated unchanged.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (which backend was built)
    L3 - semantic details
    L4 - deep tracing (delegated name lookups)
 
Contracts
---------
- Output is byte-identical to the pre-271 module for every sub-command,
  and so are the rows a registry-mode round trip lands in the registry.
- The registry imports stay LAZY, inside the factory: the file backend is
  the default, and a ``work_queue_manage list`` against it must not drag
  the registry's auth, signing and checkpoint stack into the process.
- Retirement rule (plan 271 P3): this path stays until an explicit
  retirement plan retargets the workflow doc. New code names
  ``oc_orchestrator.work_queue_manage`` directly.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_orchestrator.work_queue_manage (the moved module this path wraps)
- oc_chat.registry (lazy; Registry, which wraps the storage the registry queue backend writes to)
- oc_orchestrator.work_queue (QueueBackend, the factory's return type, and QueueBackendError, raised when no operator slot is active)
- oc_chat.registry.backends.sqlite (lazy; SQLiteBackend, the registry storage and its active operator slot)
- oc_chat.registry.discovery (lazy; discover_registry_location, which finds the registry file)
- oc_chat.registry.queue_backend (lazy; RegistryQueueBackend, the registry-backed queue the factory returns)
"""
 
from __future__ import annotations
 
import argparse
import sys
from typing import Any
 
from oc_diagnostics import _dbg
 
from oc_orchestrator import work_queue_manage as _moved
from oc_orchestrator.work_queue import QueueBackend, QueueBackendError
 
#: The program name this path has always printed in ``--help``.
PROG = "python -m oc_chat.scripts.work_queue_manage"
 
_dbg(
    "OC_CHAT.MAIN",
    "module",
    "work_queue_manage shim -> oc_orchestrator.work_queue_manage",
    4,
)
 
 
def __getattr__(name: str) -> Any:
    """Delegate every name this shim does not define to the moved module."""
    return getattr(_moved, name)
 
 
def _registry_backend(args: argparse.Namespace) -> QueueBackend:
    """Build the registry-backed queue (plan 271 P2's consumer factory).
 
    Lifted verbatim from the registry arm of the pre-271
    ``work_queue_manage._build_backend``. The package declares the seam
    and names no registry; this is the consumer that fills it, so the
    four imports the plan-258 receipt cut as a named edge now live on
    oc_chat's side of the split, where they always belonged.
 
    Raises:
        QueueBackendError: EXTERNAL_ERROR (L2 for the caller) — the
            registry holds no active operator slot, so there is no actor
            to attribute the operations to.
    """
    func = "_registry_backend"
    # Imported here, not at module scope: the file backend is the
    # default, and a `work_queue_manage list` against it must not drag the
    # registry's auth, signing and checkpoint stack into the process.
    from oc_chat.registry import Registry
    from oc_chat.registry.backends.sqlite import SQLiteBackend
    from oc_chat.registry.discovery import discover_registry_location
    from oc_chat.registry.queue_backend import RegistryQueueBackend
 
    location = discover_registry_location(registry_path=args.registry)
    storage = SQLiteBackend(location.registry_path)
    actor_slot = args.actor_slot or storage.active_operator_slot()
    if actor_slot is None:
        raise QueueBackendError("no active operator slot found in the registry")
    _dbg("OC_CHAT.MAIN", func, f"registry backend as {actor_slot}", 2)
    return RegistryQueueBackend(
        Registry(storage),
        slot=args.slot or actor_slot,
        actor_slot=actor_slot,
    )
 
 
def main(argv: list[str] | None = None) -> int:
    """Run one sub-command with oc_chat's program name and registry backend."""
    return _moved.main(argv, prog=PROG, backend_factory=_registry_backend)
 
 
if __name__ == "__main__":
    sys.exit(main())