aria-code 0.52.0__py3-none-any.whl

aria_code/packs/__init__.py

@@ -0,0 +1,85 @@
+"""Domain packs — subject areas that plug into a domain-neutral core.
+
+The core knows about code, documents, data, and conversation.  Everything that
+belongs to a subject area — the identifiers it uses, the tools that act on
+them, the guidance a model needs to reason about them — lives in a pack and is
+switched on only when the user's message names something that pack recognises.
+
+Adding a domain means adding a pack.  It does not mean adding a branch to a
+router, an intent label to the classifier, or a handler to a chain that every
+message walks.
+
+See ``aria_code.packs.base`` for the contract and ``aria_code.packs.registry``
+for the activation rule.
+"""
+
+from __future__ import annotations
+
+from aria_code.packs.base import (
+    DEFAULT_ACTIVATION_THRESHOLD,
+    BaseDomainPack,
+    DomainPack,
+    EntityMatch,
+    PackActivation,
+)
+from aria_code.packs.registry import (
+    activate_packs,
+    active_acceptance_commands,
+    active_handlers,
+    active_prompt_fragments,
+    active_tool_names,
+    clear_registry,
+    get_pack,
+    register_pack,
+    registered_packs,
+    unregister_pack,
+)
+
+_BUILTIN_LOADED = False
+
+
+def load_builtin_packs() -> tuple[str, ...]:
+    """Register the packs that ship with Aria.  Idempotent.
+
+    Finance is a built-in for continuity, not for precedence — it registers
+    through the same contract any third-party pack would use, and so do the
+    rest. Each is loaded in its own try/except because the cost of one broken
+    pack must be that pack, not the session.
+    """
+    global _BUILTIN_LOADED
+    if not _BUILTIN_LOADED:
+        for module in ("finance", "logistics", "payments", "realty"):
+            try:
+                __import__(f"aria_code.packs.{module}", fromlist=["register"]).register()
+            except Exception:  # pragma: no cover - a broken pack must not block startup
+                pass
+        _BUILTIN_LOADED = True
+    return tuple(getattr(p, "name", "") for p in registered_packs())
+
+
+def reset_builtin_packs() -> None:
+    """Clear the registry and allow built-ins to load again (tests)."""
+    global _BUILTIN_LOADED
+    clear_registry()
+    _BUILTIN_LOADED = False
+
+
+__all__ = [
+    "DEFAULT_ACTIVATION_THRESHOLD",
+    "BaseDomainPack",
+    "DomainPack",
+    "EntityMatch",
+    "PackActivation",
+    "activate_packs",
+    "active_acceptance_commands",
+    "active_handlers",
+    "active_prompt_fragments",
+    "active_tool_names",
+    "clear_registry",
+    "get_pack",
+    "load_builtin_packs",
+    "register_pack",
+    "registered_packs",
+    "reset_builtin_packs",
+    "unregister_pack",
+]

aria_code/packs/base.py

@@ -0,0 +1,168 @@
+"""The domain pack contract.
+
+A domain pack bundles everything Aria needs to serve one subject area —
+finance, logistics, clinical, accounting — behind a single interface, so the
+core never learns any of them.
+
+Why this exists
+---------------
+Finance was not a layer in this codebase; it was the substrate.  ``finance``
+and ``analysis`` were core intent labels, ~8,000 lines of ticker tables and
+market handlers sat under ``apps/cli``, and the deterministic chain ran the
+strategy, realty, and stock-chart handlers against *every* message before the
+model saw it.  The costs were concrete: a question about this repository was
+answered with a MongoDB stock quote (the string "MongoDB" in a previous reply
+resolved to the ticker MDB), and a message containing the word "行情" blocked
+the REPL for tens of seconds downloading the full A-share and HK symbol
+universe.  A logistics or clinical user would have paid exactly the same tax.
+
+The rule that prevents all of it
+--------------------------------
+**A pack activates only when it resolves a concrete entity from the user's own
+message.**  Domain vocabulary alone never activates a pack.  "分析" is ordinary
+Chinese; "AAPL" is a ticker.  Only the second may switch on the finance pack,
+and nothing a *previous assistant reply* said can switch on anything.
+
+That single rule is what makes packs composable: an inactive pack contributes
+no handlers, no tools, and no prompt text, so N domains cost O(N) to maintain
+and O(1) at request time rather than N×M branches in one router.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, Sequence, runtime_checkable
+
+# A pack must clear this to activate.  Resolvers report how sure they are that
+# the surface text really names an entity of their kind; a bare uppercase word
+# that merely *looks* like a ticker should score below it.
+DEFAULT_ACTIVATION_THRESHOLD = 0.5
+
+
+@dataclass(frozen=True)
+class EntityMatch:
+    """One concrete thing a pack recognised in a message.
+
+    ``value`` is the canonical identifier the pack's tools accept (a ticker, a
+    waybill number, an ICD code).  ``surface`` is the text as the user actually
+    wrote it, kept so the UI can show what was matched and the user can correct
+    a wrong resolution.
+    """
+
+    pack: str
+    kind: str
+    value: str
+    surface: str = ""
+    position: int = 0
+    confidence: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not self.pack:
+            raise ValueError("EntityMatch.pack is required")
+        if not self.kind:
+            raise ValueError("EntityMatch.kind is required")
+        if not self.value:
+            raise ValueError("EntityMatch.value is required")
+
+
+@dataclass(frozen=True)
+class PackActivation:
+    """A pack that claimed the message, with what it claimed."""
+
+    pack: str
+    entities: tuple[EntityMatch, ...] = field(default_factory=tuple)
+
+    @property
+    def confidence(self) -> float:
+        return max((e.confidence for e in self.entities), default=0.0)
+
+    @property
+    def primary(self) -> EntityMatch | None:
+        """Highest-confidence entity, earliest in the message on a tie."""
+        if not self.entities:
+            return None
+        return sorted(self.entities, key=lambda e: (-e.confidence, e.position))[0]
+
+
+@runtime_checkable
+class DomainPack(Protocol):
+    """What a subject area must provide to plug into Aria.
+
+    Every method is optional beyond ``name`` and ``resolve_entities`` — a pack
+    that only teaches Aria to recognise its identifiers is already useful,
+    because recognition is what gates everything else.
+    """
+
+    name: str
+
+    def resolve_entities(self, message: str) -> Sequence[EntityMatch]:
+        """Return the entities this pack recognises in *message*.
+
+        Must be cheap and must not perform blocking network I/O: this runs on
+        every message, for every registered pack.  Resolve from local tables or
+        a warm cache and return nothing when unsure — a missed activation is
+        recoverable, a wrong one silently answers the wrong question.
+        """
+        ...
+
+    def handlers(self) -> Sequence[object]:
+        """Deterministic handlers, run only while this pack is active."""
+        ...
+
+    def tool_names(self) -> Sequence[str]:
+        """Tools to expose to the model only while this pack is active."""
+        ...
+
+    def prompt_fragment(self, activation: PackActivation) -> str:
+        """Domain guidance to add to the system prompt while active."""
+        ...
+
+    def acceptance_commands(self, activation: PackActivation) -> Sequence[str]:
+        """Commands that decide whether work in this domain is *correct*.
+
+        This is the pack's connection to the acceptance gate, and it is the
+        reason the pack contract scales past software.  Every domain defines
+        "right" differently, but they all express it the same way: a command
+        that exits non-zero when the work is wrong.  Software says
+        ``pytest -q``; a logistics pack says "run the reconciliation script,
+        it exits non-zero when the ledger does not balance"; a data pack says
+        "validate against the schema".
+
+        So a pack does not have to teach the core its subject.  It only has to
+        say what green looks like, and the closed loop it gets in return is
+        the same one the software case gets.
+
+        Returning nothing is the normal case: inference from the workspace
+        then decides, exactly as before.
+        """
+        ...
+
+
+class BaseDomainPack:
+    """Convenience base implementing the optional half of the protocol."""
+
+    name: str = ""
+
+    def resolve_entities(self, message: str) -> Sequence[EntityMatch]:
+        raise NotImplementedError
+
+    def handlers(self) -> Sequence[object]:
+        return ()
+
+    def tool_names(self) -> Sequence[str]:
+        return ()
+
+    def prompt_fragment(self, activation: PackActivation) -> str:
+        return ""
+
+    def acceptance_commands(self, activation: PackActivation) -> Sequence[str]:
+        return ()
+
+
+__all__ = [
+    "DEFAULT_ACTIVATION_THRESHOLD",
+    "BaseDomainPack",
+    "DomainPack",
+    "EntityMatch",
+    "PackActivation",
+]

aria_code/packs/finance/__init__.py

@@ -0,0 +1,250 @@
+"""Finance as a domain pack — the contract's first consumer.
+
+This does not reimplement anything.  It wraps the existing symbol resolution
+and deterministic handlers so finance stops being the substrate and becomes one
+pack among peers.  Behaviour is intended to be unchanged; the regression suites
+in tests/test_market_history_inheritance.py and tests/test_intent_signals.py
+are the safety net for that claim.
+
+What changes is *reach*.  Previously the strategy, realty, and stock-chart
+handlers ran against every message in the deterministic chain, before the model
+saw it.  Behind the contract they run only when this pack has resolved a real
+financial entity from the user's message, so a logistics or clinical question
+never touches them.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from aria_code.packs.base import BaseDomainPack, EntityMatch, PackActivation
+
+PACK_NAME = "finance"
+
+# Tools this pack owns.  Exposed to the model only while the pack is active, so
+# a code session is not offered a quote tool it can misfire (which is how a
+# repository question became a MongoDB stock lookup).
+# The tools this pack owns, derived from the registries that register them
+# rather than hand-listed. A hand-written tuple drifts the moment a tool is
+# added or renamed, and both failure directions are silent: a tool left out
+# stays exposed on every turn, and a tool named wrongly promises a capability
+# that does not exist (this list said "run_backtest"; the registered name is
+# "backtest_strategy").
+_EXTRA_FINANCE_TOOLS = (
+    # Registered by the static schema block and the broker/market modules
+    # rather than by LOCAL_FINANCE_TOOL_REGISTRY.
+    "get_market_data",
+    "get_market_history",
+    "broker_query",
+    "broker_order",
+    "get_broker_portfolio",
+    "analyze_news",
+)
+
+
+def _finance_tool_names() -> tuple[str, ...]:
+    names: list[str] = []
+    try:
+        from aria_code.tools.local_finance_tools import LOCAL_FINANCE_TOOL_REGISTRY
+
+        names.extend(LOCAL_FINANCE_TOOL_REGISTRY)
+    except Exception:
+        pass
+    for name in _EXTRA_FINANCE_TOOLS:
+        if name not in names:
+            names.append(name)
+    return tuple(names)
+
+
+FINANCE_TOOLS = _finance_tool_names()
+
+# A bare uppercase run merely *looks* like a ticker — "EMS", "ESB", and "MDB"
+# all appeared in an architecture diagram in the incident that motivated this
+# contract.  Resolution against a real symbol table scores high; a shape-only
+# guess scores below the activation threshold and therefore does not switch the
+# pack on by itself.
+_RESOLVED_CONFIDENCE = 0.95
+_SHAPE_ONLY_CONFIDENCE = 0.3
+
+
+def _resolve_symbols(message: str) -> list[tuple[str, str, int]]:
+    """Return (canonical, surface, position) for symbols named in *message*."""
+    try:
+        from aria_code.apps.cli.market_universe import resolve_market_mentions
+    except Exception:
+        return []
+    try:
+        hits = resolve_market_mentions(message, limit=6)
+    except Exception:
+        return []
+    out: list[tuple[str, str, int]] = []
+    for position, item in hits:
+        symbol = str(getattr(item, "symbol", "") or "").strip()
+        if symbol:
+            out.append((symbol.upper(), str(getattr(item, "name", "") or ""), position))
+    return out
+
+
+# Bare uppercase runs are resolved against an ALLOWLIST, not a blocklist.
+# market_detect takes the opposite approach — it rejects known non-tickers like
+# BUY and SELL — which is why "MongoDB" in an architecture sentence resolved to
+# the ticker MDB: nothing had thought to forbid it.  An allowlist fails closed:
+# an unknown uppercase word scores below the activation threshold, so the worst
+# case is a missed activation the user can force with "$MDB".
+_KNOWN_TICKERS = frozenset({
+    # US mega/large cap
+    "AAPL", "MSFT", "GOOG", "GOOGL", "AMZN", "META", "TSLA", "NVDA", "AVGO",
+    "BRK.A", "BRK.B", "JPM", "V", "MA", "UNH", "XOM", "WMT", "JNJ", "PG",
+    "HD", "COST", "ORCL", "CRM", "AMD", "INTC", "CSCO", "ADBE", "NFLX",
+    "PEP", "KO", "MCD", "NKE", "DIS", "BA", "CAT", "GE", "GS", "MS",
+    "BAC", "WFC", "C", "T", "VZ", "PFE", "MRK", "ABBV", "LLY", "TMO",
+    "PLTR", "SNOW", "UBER", "ABNB", "COIN", "SHOP", "SQ", "PYPL", "SMCI",
+    "MU", "QCOM", "TXN", "AMAT", "LRCX", "KLAC", "ARM", "TSM", "ASML",
+    # Common ETFs
+    "SPY", "QQQ", "IWM", "DIA", "VOO", "VTI", "GLD", "SLV", "USO", "TLT",
+    "ARKK", "XLF", "XLE", "XLK", "SOXL", "TQQQ", "SQQQ", "HYG", "EEM",
+    # China ADRs
+    "BABA", "JD", "PDD", "NIO", "LI", "XPEV", "BIDU", "TME", "BILI", "NTES",
+})
+
+
+def _bare_uppercase_runs(message: str) -> list[tuple[str, str, int, float]]:
+    """Uppercase runs, scored by whether they are recognised or merely shaped.
+
+    A recognised ticker activates the pack.  An unrecognised run is still
+    reported, at a confidence below the activation threshold, so the CLI can
+    offer "did you mean $MDB?" without answering a code question with a stock
+    quote on its own initiative.
+    """
+    import re
+
+    out: list[tuple[str, str, int, float]] = []
+    for match in re.finditer(r"(?<![A-Za-z0-9$])([A-Z]{1,5})(?![A-Za-z0-9])", message or ""):
+        candidate = match.group(1)
+        confidence = (
+            _RESOLVED_CONFIDENCE if candidate in _KNOWN_TICKERS else _SHAPE_ONLY_CONFIDENCE
+        )
+        out.append((candidate, candidate, match.start(), confidence))
+    return out
+
+
+def _explicit_ticker(message: str) -> list[tuple[str, str, int]]:
+    """Tickers written in a form that states the intent explicitly.
+
+    ``$AAPL`` and a bare A-share code are unambiguous.  A bare uppercase word
+    is not, and is deliberately excluded here.
+    """
+    import re
+
+    out: list[tuple[str, str, int]] = []
+    for match in re.finditer(r"\$([A-Za-z]{1,5})(?![A-Za-z0-9])", message or ""):
+        out.append((match.group(1).upper(), match.group(0), match.start()))
+    for match in re.finditer(r"(?<!\d)((?:60|68|00|30)\d{4})(?!\d)", message or ""):
+        out.append((match.group(1), match.group(0), match.start()))
+    return out
+
+
+class FinancePack(BaseDomainPack):
+    """Recognises tradable instruments and owns the market workflows."""
+
+    name = PACK_NAME
+
+    def resolve_entities(self, message: str) -> Sequence[EntityMatch]:
+        if not (message or "").strip():
+            return ()
+
+        seen: set[str] = set()
+        entities: list[EntityMatch] = []
+
+        for value, surface, position in _explicit_ticker(message):
+            if value in seen:
+                continue
+            seen.add(value)
+            entities.append(EntityMatch(
+                pack=PACK_NAME, kind="instrument", value=value,
+                surface=surface, position=position,
+                confidence=_RESOLVED_CONFIDENCE,
+            ))
+
+        for value, surface, position, confidence in _bare_uppercase_runs(message):
+            if value in seen:
+                continue
+            seen.add(value)
+            entities.append(EntityMatch(
+                pack=PACK_NAME, kind="instrument", value=value,
+                surface=surface, position=position,
+                confidence=confidence,
+            ))
+
+        for value, surface, position in _resolve_symbols(message):
+            if value in seen:
+                continue
+            seen.add(value)
+            entities.append(EntityMatch(
+                pack=PACK_NAME, kind="instrument", value=value,
+                surface=surface or value, position=position,
+                confidence=_RESOLVED_CONFIDENCE,
+            ))
+
+        return tuple(entities)
+
+    def handlers(self) -> Sequence[object]:
+        """The entity-dependent handlers, reachable only when active.
+
+        ``handle_stock_chart_analysis`` takes two keyword-only collaborators
+        and cannot be called as ``handler(message)``. Returning it bare made
+        every finance-activated turn die with a TypeError inside the
+        deterministic chain — the chain calls handlers uniformly, so a handler
+        that does not fit that shape is not a handler. Bound here, the way
+        ``deterministic._handle_stock_chart_analysis`` already bound it before
+        the pack layer took the call over.
+        """
+        try:
+            from aria_code.apps.cli.handlers.chart_handlers import (
+                handle_stock_chart_analysis,
+            )
+            from aria_code.apps.cli.utils.market_detect import (
+                _extract_market_symbol,
+                _is_stock_chart_analysis_request,
+            )
+        except Exception:
+            return ()
+
+        def _chart(message: str) -> dict:
+            return handle_stock_chart_analysis(
+                message,
+                is_chart_request=_is_stock_chart_analysis_request,
+                extract_symbol=_extract_market_symbol,
+            )
+
+        # Only the chart handler. handle_strategy_advice does not belong
+        # behind the entity gate — see deterministic._SELF_GATED_HANDLERS.
+        return (_chart,)
+
+    def tool_names(self) -> Sequence[str]:
+        return FINANCE_TOOLS
+
+    def prompt_fragment(self, activation: PackActivation) -> str:
+        primary = activation.primary
+        if primary is None:
+            return ""
+        symbols = ", ".join(sorted({e.value for e in activation.entities}))
+        return (
+            f"金融标的已识别：{symbols}。\n"
+            "使用工具取回的数据回答，不要凭记忆给出价格或指标；"
+            "标注数据来源与时间戳；输出不构成投资建议。"
+        )
+
+
+FINANCE_PACK = FinancePack()
+
+
+def register() -> FinancePack:
+    """Register the finance pack.  Idempotent."""
+    from aria_code.packs.registry import register_pack
+
+    register_pack(FINANCE_PACK)
+    return FINANCE_PACK
+
+
+__all__ = ["FINANCE_PACK", "FINANCE_TOOLS", "PACK_NAME", "FinancePack", "register"]

aria_code/packs/logistics/__init__.py

@@ -0,0 +1,169 @@
+"""Logistics — waybills, containers, carriers.
+
+What makes this pack safe to have switched on is that every identifier it
+recognises is *verifiable*, not merely shaped right.  A bare run of twelve
+digits appears in invoices, timestamps, phone numbers and order IDs; a
+container number carries a check digit that can be recomputed, and a UPS or SF
+tracking number carries a prefix that nothing else uses.
+
+So the resolver reports both kinds and scores them differently: verified
+identifiers activate the pack, shape-only matches are reported below the
+activation threshold so the CLI can offer "did you mean this waybill?" without
+answering a code question with a shipment lookup on its own initiative.  That
+asymmetry is the contract's rule applied to a domain whose identifiers are
+almost all digits.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Sequence
+
+from aria_code.packs.base import BaseDomainPack, EntityMatch, PackActivation
+
+PACK_NAME = "logistics"
+
+LOGISTICS_TOOLS = (
+    "analyze_logistics_data",
+)
+
+_VERIFIED = 0.95
+_SHAPE_ONLY = 0.3
+
+# Carrier prefixes that no other identifier uses.
+_CARRIER_PATTERNS: tuple[tuple[str, re.Pattern], ...] = (
+    # UPS: 1Z + 6-char shipper + 2-char service + 8-digit sequence.
+    ("ups", re.compile(r"\b(1Z[0-9A-Z]{16})\b", re.I)),
+    # SF Express domestic waybill.
+    ("sf", re.compile(r"\b(SF\d{12,15})\b", re.I)),
+    # DHL express, 'JD' + 20 digits (also used on some waybill labels).
+    ("dhl", re.compile(r"\b(JD\d{18,20})\b")),
+)
+
+# ISO 6346 container: 4 letters (owner + category) + 6 digits + check digit.
+_CONTAINER = re.compile(r"\b([A-Z]{4}\d{7})\b")
+
+# Bare numeric runs — the shape most domestic waybills take, and also the shape
+# of an order id, an invoice number and a unix timestamp in milliseconds.
+_BARE_DIGITS = re.compile(r"(?<!\d)(\d{10,15})(?!\d)")
+
+# ISO 6346 letter values: A=10, then ascending, skipping every multiple of 11.
+def _iso6346_letter_values() -> dict[str, int]:
+    values: dict[str, int] = {}
+    value = 10
+    for index in range(26):
+        while value % 11 == 0:
+            value += 1
+        values[chr(ord("A") + index)] = value
+        value += 1
+    return values
+
+
+_LETTER_VALUES = _iso6346_letter_values()
+
+
+def is_valid_container(code: str) -> bool:
+    """True when *code* satisfies the ISO 6346 check digit.
+
+    This is what separates a container number from four capitals followed by
+    seven digits, which is also the shape of plenty of part numbers and
+    internal SKUs. Recomputing the check digit turns a guess into a
+    resolution — the distinction the pack contract is built on.
+    """
+    text = (code or "").strip().upper()
+    if len(text) != 11 or not text[:4].isalpha() or not text[4:].isdigit():
+        return False
+    total = 0
+    for position, char in enumerate(text[:10]):
+        value = _LETTER_VALUES[char] if char.isalpha() else int(char)
+        total += value * (2 ** position)
+    return (total % 11) % 10 == int(text[10])
+
+
+class LogisticsPack(BaseDomainPack):
+    """Recognises shipment identifiers and owns the freight workflows."""
+
+    name = PACK_NAME
+
+    def resolve_entities(self, message: str) -> Sequence[EntityMatch]:
+        text = message or ""
+        if not text.strip():
+            return ()
+
+        seen: set[str] = set()
+        claimed: list[tuple[int, int]] = []
+        entities: list[EntityMatch] = []
+
+        def _add(value: str, kind: str, surface: str, span: tuple[int, int], confidence: float) -> None:
+            if value in seen:
+                return
+            seen.add(value)
+            claimed.append(span)
+            entities.append(EntityMatch(
+                pack=PACK_NAME, kind=kind, value=value,
+                surface=surface, position=span[0], confidence=confidence,
+            ))
+
+        for carrier, pattern in _CARRIER_PATTERNS:
+            for match in pattern.finditer(text):
+                _add(match.group(1).upper(), f"waybill:{carrier}",
+                     match.group(1), match.span(1), _VERIFIED)
+
+        for match in _CONTAINER.finditer(text):
+            code = match.group(1)
+            _add(code, "container", code, match.span(1),
+                 _VERIFIED if is_valid_container(code) else _SHAPE_ONLY)
+
+        # Bare digit runs last, and only outside what a verified identifier
+        # already claimed: the digits inside `1Z999AA10123456784` are not a
+        # second, weaker waybill, and reporting them as one would let the UI
+        # offer a "did you mean" for a number the user never wrote.
+        for match in _BARE_DIGITS.finditer(text):
+            start, end = match.span(1)
+            if any(start >= c_start and end <= c_end for c_start, c_end in claimed):
+                continue
+            _add(match.group(1), "waybill", match.group(1), match.span(1), _SHAPE_ONLY)
+
+        return tuple(entities)
+
+    def tool_names(self) -> Sequence[str]:
+        return LOGISTICS_TOOLS
+
+    def prompt_fragment(self, activation: PackActivation) -> str:
+        kinds = sorted({e.kind for e in activation.entities})
+        ids = ", ".join(sorted({e.value for e in activation.entities}))
+        return (
+            f"物流标识已识别（{', '.join(kinds)}）：{ids}。\n"
+            "用工具取回的运单/箱单数据回答，不要凭记忆编造承运商、时效或费率；"
+            "标注数据来源与时间戳。金额与账期以对账结果为准。"
+        )
+
+    def acceptance_commands(self, activation: PackActivation) -> Sequence[str]:
+        # Looked up through the module rather than a name bound at import, so
+        # what this workspace declares is read when the turn runs — a .ariarc
+        # edited mid-session takes effect on the next message, not the next
+        # process.
+        from aria_code.packs import rules
+
+        return rules.acceptance_commands_for(PACK_NAME)
+
+
+LOGISTICS_PACK = LogisticsPack()
+
+
+def register() -> LogisticsPack:
+    """Register the logistics pack.  Idempotent."""
+    from aria_code.packs.registry import register_pack
+
+    register_pack(LOGISTICS_PACK)
+    return LOGISTICS_PACK
+
+
+__all__ = [
+    "LOGISTICS_PACK",
+    "LOGISTICS_TOOLS",
+    "PACK_NAME",
+    "LogisticsPack",
+    "is_valid_container",
+    "register",
+]