arc-kernel 0.1.0__py3-none-any.whl

arc/codec.py

@@ -0,0 +1,72 @@
+"""
+arc.codec
+-----------------
+The Kernel's sole codec (Architecture §4: msgspec — orjson deliberately
+dropped as redundant). Stateless: no project binding needed, works even
+before arc.boot(). One shared implementation so plugins stop reinventing
+serialization each their own way — gateway called msgspec directly in three
+places, psqldb used stdlib json for its jsonb columns; both now route
+through here instead of duplicating it.
+
+    import arc
+    arc.codec.encode(value)                 -> bytes
+    arc.codec.decode(data)                  -> Any
+    arc.codec.decode(data, type=MyStruct)   -> MyStruct, validated
+    arc.codec.validate(obj, type=MyStruct)  -> MyStruct, validated (obj is
+                                                already-decoded, e.g. a dict)
+    arc.codec.schema(MyStruct)              -> JSON Schema dict
+
+decode()/validate() always raise CodecError, never a raw msgspec exception
+— callers never need `import msgspec` themselves just to catch a failure.
+`Struct` is re-exported so a plugin can declare a schema type without that
+import either.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+import msgspec
+from msgspec import Struct  # noqa: F401 - re-exported: arc.codec.Struct
+
+T = TypeVar("T")
+
+
+class CodecError(ValueError):
+    """A decode/validate call failed — bad JSON, or data that doesn't match
+    the given type. The one exception type every caller needs to know
+    about, regardless of which underlying codec library is doing the work."""
+
+
+def encode(value: Any) -> bytes:
+    return msgspec.json.encode(value)
+
+
+def decode(data: bytes | str, *, type: type[T] | None = None) -> T:
+    """Decode raw JSON bytes/str. With `type`, decodes AND validates in one
+    step (msgspec's core strength — no separate parse-then-validate pass)."""
+    try:
+        if type is None:
+            return msgspec.json.decode(data)
+        return msgspec.json.decode(data, type=type)
+    except msgspec.ValidationError as exc:  # must come first: it subclasses DecodeError
+        raise CodecError(f"validation failed: {exc}") from exc
+    except msgspec.DecodeError as exc:
+        raise CodecError(f"malformed JSON: {exc}") from exc
+
+
+def validate(obj: Any, *, type: type[T]) -> T:
+    """Validate/coerce an already-decoded object (e.g. a plain dict — the
+    shape a schema/patch file or a psqldb row arrives as) against `type`.
+    msgspec has no separate "validate this in-memory object" entry point;
+    this is msgspec.convert(), named to match decode()/encode() here."""
+    try:
+        return msgspec.convert(obj, type=type)
+    except msgspec.ValidationError as exc:
+        raise CodecError(f"validation failed: {exc}") from exc
+
+
+def schema(type: Any) -> dict:
+    """JSON Schema for `type` — gateway.openapi's only remaining call site
+    for this is arc.codec.schema() now, not msgspec.json.schema() directly."""
+    return msgspec.json.schema(type)

arc/doctor.py

@@ -0,0 +1,107 @@
+"""
+arc.doctor
+-----------------
+`arc doctor` — a true dry run of arc.boot()'s resolution phase.
+
+Shows exactly what boot WOULD do — load order, skipped plugins, warnings —
+or exactly why it would fail, without importing a single line of plugin code
+and without starting anything. Powered by the same pure function
+(arc.resolver.resolve) that boot() executes, so doctor can never drift from
+reality.
+
+Output: rich tables for humans, `--json` for machines (answers the open
+"text vs JSON" question with: both).
+
+Wiring into the CLI is two lines in arc/cli.py:
+
+    from .doctor import doctor as _doctor_command
+    app.command(name="doctor")(_doctor_command)
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import resolver
+from .registry import load_lock
+from .runtime import BootError, find_project_root
+
+console = Console()
+err_console = Console(stderr=True, style="bold red")
+
+
+def doctor(
+    as_json: bool = typer.Option(
+        False, "--json", help="Emit machine-readable JSON instead of tables."
+    ),
+) -> None:
+    """
+    Dry-run boot resolution: show what arc.boot() would load, skip, and warn
+    about — or why it would fail — without importing any plugin code.
+    """
+    try:
+        root = find_project_root()
+    except BootError as exc:  # e.g. $ARC_PROJECT_ROOT points somewhere invalid
+        _fail(str(exc), as_json)
+        return  # unreachable; _fail raises typer.Exit
+    if root is None:
+        _fail(
+            "Not inside an ARC project — no .arc/arc.toml found in the current "
+            "directory or any parent.",
+            as_json,
+        )
+        return
+
+    lock_doc = load_lock(root / ".arc" / "plugins.lock")
+    try:
+        plan = resolver.resolve(root, lock_doc=lock_doc)
+    except resolver.ResolutionError as exc:
+        _fail(str(exc), as_json)
+        return
+
+    if as_json:
+        print(json.dumps(plan.to_dict(), indent=2))
+        return
+
+    if not plan.load_order:
+        console.print(
+            "[dim]No enabled plugins — arc.boot() would start with an empty "
+            "capability registry.[/dim]"
+        )
+    else:
+        table = Table(title="arc.boot() load order")
+        table.add_column("#", justify="right")
+        table.add_column("plugin")
+        table.add_column("capability")
+        table.add_column("version")
+        table.add_column("requires")
+        table.add_column("optional")
+        for position, spec in enumerate(plan.load_order, start=1):
+            table.add_row(
+                str(position),
+                spec.name,
+                spec.capability,
+                spec.version,
+                ", ".join(spec.requires) or "-",
+                ", ".join(spec.optional_requires) or "-",
+            )
+        console.print(table)
+
+    for skipped in plan.skipped:
+        console.print(f"[yellow]skipped:[/yellow] {skipped.name} — {skipped.reason}")
+    for warning in plan.warnings:
+        console.print(f"[yellow]warning:[/yellow] {warning}")
+
+    console.print("[bold green]Boot resolution OK.[/bold green]")
+
+
+def _fail(message: str, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps({"ok": False, "error": message}, indent=2))
+    else:
+        err_console.print(f"Boot would FAIL: {message}")
+    raise typer.Exit(code=1)

arc/health.py

@@ -0,0 +1,55 @@
+"""
+arc.health
+-----------------
+Aggregated health across every currently-registered capability — the
+Kernel-level home for what used to be a gateway-only "working preview"
+(its own docstring called it that). Any process that has called
+arc.boot() can ask this now, not just one serving HTTP — a background
+worker or a bare CLI command gets the same answer without booting Gateway
+just to get it.
+
+Mechanism (duck-typed, domain-blind per §3.1): a capability MAY expose an
+`async def health() -> dict`. check() calls whichever ones do and collects
+the results; anything without one is silently skipped — the Kernel never
+needs to know what "psqldb" or "redix" even are, only that the attribute
+might exist.
+
+    import arc
+    arc.boot()
+    results = await arc.health.check()
+    # {"psqldb": {"ok": True, "version": "..."}, "redix": {"ok": True}}
+    arc.health.all_ok(results)   -> bool
+"""
+
+from __future__ import annotations
+
+from . import _state
+from .kernel import KernelError
+
+
+class HealthError(KernelError):
+    """arc.health.check() was called before arc.boot() — no active kernel,
+    so no capabilities exist yet to check."""
+
+
+async def check() -> dict[str, dict]:
+    kernel = _state.get_kernel()
+    if kernel is None:
+        raise HealthError(
+            "arc.health.check() requires arc.boot() first — there is no "
+            "active kernel, so no capabilities to check."
+        )
+    results: dict[str, dict] = {}
+    for name, cap in kernel.capabilities().items():
+        health_fn = getattr(cap.instance, "health", None)
+        if not callable(health_fn):
+            continue
+        try:
+            results[name] = await health_fn()
+        except Exception as exc:
+            results[name] = {"ok": False, "error": f"{exc.__class__.__name__}: {exc}"}
+    return results
+
+
+def all_ok(results: dict[str, dict]) -> bool:
+    return all(r.get("ok", True) for r in results.values())

arc/healthcmd.py

@@ -0,0 +1,85 @@
+"""
+arc.healthcmd
+-----------------
+`arc health` — a CLI view onto arc.health.check(), the same way `arc doctor`
+is a CLI view onto arc.resolver.resolve(). Named healthcmd.py (not health.py)
+so it never collides with the real arc.health module this wraps.
+
+Opens every capability that has an open() first (short-lived — same idea as
+gateway's own ASGI lifespan open/close, just scoped to one CLI invocation
+instead of a running server) so a check actually exercises real
+connections, not just "constructed, never started".
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import warnings
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+err_console = Console(stderr=True, style="bold red")
+
+
+def health(
+    as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON instead of a table."),
+) -> None:
+    """Boot, open every capability, run arc.health.check() across all of
+    them, then close back down. Exits non-zero if anything reported unhealthy."""
+    import arc
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", arc.ArcAdvisory)
+        try:
+            kernel = arc.boot()
+        except arc.BootError as exc:
+            _fail(str(exc), as_json)
+            return  # unreachable; _fail raises typer.Exit
+
+    results = asyncio.run(_check(kernel))
+
+    if as_json:
+        print(json.dumps({"ok": arc.health.all_ok(results), "results": results}, indent=2, default=str))
+    else:
+        table = Table(title="arc.health.check()")
+        table.add_column("capability")
+        table.add_column("ok")
+        table.add_column("detail")
+        for name, result in sorted(results.items()):
+            ok = bool(result.get("ok", True))
+            detail = ", ".join(f"{k}={v}" for k, v in result.items() if k != "ok")
+            table.add_row(name, "[green]yes[/green]" if ok else "[bold red]no[/bold red]", detail)
+        console.print(table)
+
+    if not arc.health.all_ok(results):
+        raise typer.Exit(code=1)
+
+
+async def _check(kernel) -> dict:
+    import arc
+
+    opened = []
+    for name, cap in kernel.capabilities().items():
+        open_fn = getattr(cap.instance, "open", None)
+        if callable(open_fn):
+            await open_fn()
+            opened.append(cap.instance)
+    try:
+        return await arc.health.check()
+    finally:
+        for instance in opened:
+            close_fn = getattr(instance, "close", None)
+            if callable(close_fn):
+                await close_fn()
+
+
+def _fail(message: str, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps({"ok": False, "error": message}, indent=2))
+    else:
+        err_console.print(f"Health check FAILED: {message}")
+    raise typer.Exit(code=1)

arc/kernel.py

@@ -0,0 +1,290 @@
+"""
+arc.kernel
+-----------------
+The runtime capability registry — the object every plugin's `register(kernel)`
+function talks to, and what `arc.boot()` returns.
+
+This is NOT arc/registry.py. That module is the CLI's bookkeeping for
+`.arc/plugins.lock` (what is installed and enabled *on disk*). This module is
+the in-process registry that exists only for the lifetime of a booted process.
+
+Domain-blind by design (Architecture §3.1): the Kernel only ever sees a string
+name, an instance, a `requires` list, and an `optional_requires` list. It
+never defines what a capability *is* — no typed Protocols, no domain
+knowledge. Adding a new capability type must cost zero kernel code changes,
+permanently.
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+import warnings as _warnings
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Iterable, Mapping
+
+if typing.TYPE_CHECKING:
+    from .resolver import BootPlan, PluginSpec
+    from .settings import SettingsManager
+
+
+class ArcAdvisory(UserWarning):
+    """
+    A non-fatal boot/runtime advisory (Architecture §3.5): something worth
+    knowing that must never block startup — e.g. "local-file secrets in use".
+    Emitted via warnings.warn() and also collected on Kernel.advisories.
+    Placeholder channel until arc.health exists as a real runtime API.
+    """
+
+
+class KernelError(RuntimeError):
+    """Base class for all runtime kernel failures."""
+
+
+class ExportError(KernelError):
+    """A plugin's export was invalid — always a hard boot failure."""
+
+
+# Capability names that can never be exported. Anything here would be found
+# by normal attribute lookup on the `arc` module *before* PEP 562
+# __getattr__ ever fires, silently shadowing the capability. The static set
+# covers the kernel's own submodules and public API; is_reserved_capability_name()
+# additionally checks the live `arc` module namespace so nothing slips through.
+RESERVED_CAPABILITY_NAMES = frozenset({
+    # kernel submodules
+    "cli", "kernel", "registry", "resolver", "runtime", "secrets", "settings",
+    "doctor", "plugin_cli", "codec", "health",
+    # public API re-exported on the arc package
+    "boot", "shutdown", "find_project_root",
+    "Kernel", "Capability", "KernelError", "ExportError",
+    "BootError", "ResolutionError", "ArcAdvisory",
+    "BootPlan", "PluginSpec",
+    "__version__",
+})
+
+
+def is_reserved_capability_name(name: str) -> bool:
+    if name in RESERVED_CAPABILITY_NAMES:
+        return True
+    arc_module = sys.modules.get("arc")
+    # vars() reads the module dict directly — it does NOT trigger the
+    # package's __getattr__, so booted capabilities never look "reserved".
+    return arc_module is not None and name in vars(arc_module)
+
+
+def capability_name_problem(name: object) -> str | None:
+    """Return a human-readable problem with a proposed capability name, or None if valid."""
+    if not isinstance(name, str) or not name:
+        return "capability name must be a non-empty string"
+    if not name.isidentifier():
+        return (
+            f"'{name}' is not a valid Python identifier — a capability becomes "
+            f"the attribute `arc.{name}`, so it must be importable as one"
+        )
+    if name.startswith("_"):
+        return f"'{name}' starts with an underscore, which is reserved for arc internals"
+    if is_reserved_capability_name(name):
+        return (
+            f"'{name}' collides with the arc module's own namespace (a kernel "
+            f"submodule or public API attribute) and would be shadowed — "
+            f"pick a different capability name"
+        )
+    return None
+
+
+@dataclass(frozen=True)
+class Capability:
+    """One exported capability: exactly what §3.1 says the kernel may know."""
+    name: str
+    instance: Any
+    requires: tuple[str, ...]
+    optional_requires: tuple[str, ...]
+    plugin: str  # which plugin exported it ("<direct export>" outside boot)
+
+
+class Kernel:
+    """
+    The runtime capability registry.
+
+    Created by arc.boot(); plugins receive it as the sole argument to their
+    register(kernel) function and call kernel.export(...) exactly once.
+    Can also be constructed directly (tests, embedding) — spec cross-checks
+    are then skipped, but name validation and duplicate/require enforcement
+    still apply.
+    """
+
+    def __init__(
+        self,
+        project_root: Path | None = None,
+        *,
+        settings: "SettingsManager | None" = None,
+        plan: "BootPlan | None" = None,
+    ) -> None:
+        self.project_root = project_root
+        #: The project-bound SettingsManager (or None when constructed
+        #: directly outside a project). `arc.settings.get/set/...` at module
+        #: level proxy to this — one call site, secret or not (§3.5).
+        self.settings = settings
+        self.advisories: list[str] = []
+        self._plan = plan
+        self._caps: dict[str, Capability] = {}
+        self._current_spec: "PluginSpec | None" = None
+        self._current_export_count = 0
+
+    # ------------------------------------------------------------------ #
+    # The registration surface plugins see (§3.1)
+    # ------------------------------------------------------------------ #
+    def export(
+        self,
+        name: str,
+        instance: Any,
+        requires: Iterable[str] = (),
+        optional_requires: Iterable[str] = (),
+    ) -> None:
+        """
+        Export `instance` as the capability `name` — reachable as arc.<name>
+        after boot. Hard `requires` must already be registered (boot's
+        topological order guarantees this when manifests are accurate).
+        """
+        requires = tuple(requires or ())
+        optional_requires = tuple(optional_requires or ())
+
+        problem = capability_name_problem(name)
+        if problem:
+            who = f"plugin '{self._current_spec.name}'" if self._current_spec else "a direct export"
+            raise ExportError(f"invalid capability export from {who}: {problem}.")
+
+        if name in self._caps:
+            raise ExportError(
+                f"capability '{name}' is already exported by plugin "
+                f"'{self._caps[name].plugin}' — two plugins exporting the same "
+                f"name is a hard boot failure (§3.1); rename one."
+            )
+
+        spec = self._current_spec
+        if spec is not None:
+            if self._current_export_count >= 1:
+                raise ExportError(
+                    f"plugin '{spec.name}' attempted to export a second "
+                    f"capability ('{name}') — each plugin exports exactly one "
+                    f"namespace under arc.<capability> (§2)."
+                )
+            if name != spec.capability:
+                raise ExportError(
+                    f"plugin '{spec.name}' exported capability '{name}', but its "
+                    f"manifest (plugin.toml, via plugins.lock) declares "
+                    f"capability = \"{spec.capability}\". Align register() and "
+                    f"plugin.toml, then run `arc build` to refresh the lock."
+                )
+            if set(requires) != set(spec.requires) or set(optional_requires) != set(
+                spec.optional_requires
+            ):
+                self.advise(
+                    f"manifest drift in plugin '{spec.name}': register() declared "
+                    f"requires={sorted(requires)} / optional_requires="
+                    f"{sorted(optional_requires)}, but plugins.lock has "
+                    f"requires={sorted(spec.requires)} / optional_requires="
+                    f"{sorted(spec.optional_requires)}. Load order was computed "
+                    f"from the lock — update plugin.toml and run `arc build`."
+                )
+
+        for req in requires:
+            if req not in self._caps:
+                raise ExportError(self._missing_requirement_message(name, spec, req))
+
+        self._caps[name] = Capability(
+            name=name,
+            instance=instance,
+            requires=requires,
+            optional_requires=optional_requires,
+            plugin=spec.name if spec else "<direct export>",
+        )
+        self._current_export_count += 1
+
+    # ------------------------------------------------------------------ #
+    # Lookup — what arc/__init__'s PEP 562 __getattr__ resolves against
+    # ------------------------------------------------------------------ #
+    def get(self, name: str) -> Any:
+        """Return the instance exported as `name`."""
+        try:
+            return self._caps[name].instance
+        except KeyError:
+            raise KernelError(
+                f"no capability named '{name}' is registered "
+                f"(registered: {sorted(self._caps) or 'none'})."
+            ) from None
+
+    def has(self, name: str) -> bool:
+        return name in self._caps
+
+    def capabilities(self) -> Mapping[str, Capability]:
+        """Read-only view of every exported capability, keyed by name."""
+        return MappingProxyType(self._caps)
+
+    def current_plugin(self) -> str | None:
+        """The name of the plugin whose register(kernel) is currently
+        executing, or None outside of one. Lets a provider (e.g. psqldb)
+        attribute something a caller declares — a set of schema files, say
+        — to whichever plugin declared it, without that caller having to
+        pass its own name by hand. Still just a string (§3.1): the kernel
+        doesn't know or care what the provider does with it."""
+        return self._current_spec.name if self._current_spec else None
+
+    def advise(self, message: str) -> None:
+        """Record a non-fatal advisory (§3.5) — collected AND warned, never raised."""
+        self.advisories.append(message)
+        _warnings.warn(message, ArcAdvisory, stacklevel=3)
+
+    # ------------------------------------------------------------------ #
+    # Internal — called by arc.runtime around each register() invocation
+    # ------------------------------------------------------------------ #
+    def _begin_plugin(self, spec: "PluginSpec") -> None:
+        self._current_spec = spec
+        self._current_export_count = 0
+
+    def _finish_plugin(self, spec: "PluginSpec") -> None:
+        try:
+            if self._current_export_count == 0:
+                raise ExportError(
+                    f"plugin '{spec.name}' register() completed without exporting "
+                    f"its capability '{spec.capability}' — register(kernel) must "
+                    f"call kernel.export(...) exactly once."
+                )
+        finally:
+            self._current_spec = None
+            self._current_export_count = 0
+
+    def _missing_requirement_message(
+        self, name: str, spec: "PluginSpec | None", req: str
+    ) -> str:
+        base = (
+            f"capability '{name}' declares a hard require on '{req}', "
+            f"which is not registered"
+        )
+        plan = self._plan
+        if plan is not None:
+            later = next((s for s in plan.load_order if s.capability == req), None)
+            if later is not None:
+                return (
+                    base
+                    + f" yet — plugin '{later.name}' provides it but loads later. "
+                    f"The requirement is missing from the manifest that load "
+                    f"order was computed from: add '{req}' to `requires` in "
+                    f"plugin.toml and run `arc build`."
+                )
+            skipped = next(
+                (sk for sk in plan.skipped if sk.capability == req), None
+            )
+            if skipped is not None:
+                return (
+                    base
+                    + f" — plugin '{skipped.name}' provides it but was skipped "
+                    f"({skipped.reason})."
+                )
+        return (
+            base
+            + ". No plugin in this boot provides it — install one "
+            "(`arc install <git-url>`) or drop the requirement."
+        )