appecosystem-hub 0.1.0__tar.gz

appecosystem_hub-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Smart Industries LLC (Mikel Smart)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

appecosystem_hub-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: appecosystem-hub
+Version: 0.1.0
+Summary: Embedded/sidecar Hub runtime, single-host lock, capability registry, and durable offline outbox for appEcosystem
+Author: Mikel Smart
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/M1K31/appEcosystem
+Project-URL: Source, https://github.com/M1K31/appEcosystem
+Project-URL: Issues, https://github.com/M1K31/appEcosystem/issues
+Keywords: appecosystem,service-mesh,capabilities,notifications,embedded-hub
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: appecosystem-auth>=0.4.0
+Requires-Dist: appecosystem-client>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# `appecosystem-hub` (`ecosystem_hub`)
+
+App-embeddable Hub lifecycle manager, single-host lock, capability registry, and SQLite durable notification outbox for `appEcosystem`.
+
+## Role Modes (`ECOSYSTEM_HUB_ROLE`)
+
+- `auto` *(default)*: Discovers an existing Hub (`registry → mDNS → static`); if none responds and the device is at least Tier 1 (`>= 4 GB` RAM), acquires a single-host advisory file lock and launches a managed Hub sidecar.
+- `host`: Explicitly hosts the Hub on this device (falling back to `join` if another local app already holds the single-host lock and passes `/health`).
+- `join`: Joins an existing Hub when reachable; degrades gracefully to local standalone operation + durable SQLite outbox when offline.
+- `off`: Pure standalone operation with zero network discovery or hosting.
+

appecosystem_hub-0.1.0/README.md

@@ -0,0 +1,11 @@
+# `appecosystem-hub` (`ecosystem_hub`)
+
+App-embeddable Hub lifecycle manager, single-host lock, capability registry, and SQLite durable notification outbox for `appEcosystem`.
+
+## Role Modes (`ECOSYSTEM_HUB_ROLE`)
+
+- `auto` *(default)*: Discovers an existing Hub (`registry → mDNS → static`); if none responds and the device is at least Tier 1 (`>= 4 GB` RAM), acquires a single-host advisory file lock and launches a managed Hub sidecar.
+- `host`: Explicitly hosts the Hub on this device (falling back to `join` if another local app already holds the single-host lock and passes `/health`).
+- `join`: Joins an existing Hub when reachable; degrades gracefully to local standalone operation + durable SQLite outbox when offline.
+- `off`: Pure standalone operation with zero network discovery or hosting.
+

appecosystem_hub-0.1.0/appecosystem_hub.egg-info/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: appecosystem-hub
+Version: 0.1.0
+Summary: Embedded/sidecar Hub runtime, single-host lock, capability registry, and durable offline outbox for appEcosystem
+Author: Mikel Smart
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/M1K31/appEcosystem
+Project-URL: Source, https://github.com/M1K31/appEcosystem
+Project-URL: Issues, https://github.com/M1K31/appEcosystem/issues
+Keywords: appecosystem,service-mesh,capabilities,notifications,embedded-hub
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: appecosystem-auth>=0.4.0
+Requires-Dist: appecosystem-client>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# `appecosystem-hub` (`ecosystem_hub`)
+
+App-embeddable Hub lifecycle manager, single-host lock, capability registry, and SQLite durable notification outbox for `appEcosystem`.
+
+## Role Modes (`ECOSYSTEM_HUB_ROLE`)
+
+- `auto` *(default)*: Discovers an existing Hub (`registry → mDNS → static`); if none responds and the device is at least Tier 1 (`>= 4 GB` RAM), acquires a single-host advisory file lock and launches a managed Hub sidecar.
+- `host`: Explicitly hosts the Hub on this device (falling back to `join` if another local app already holds the single-host lock and passes `/health`).
+- `join`: Joins an existing Hub when reachable; degrades gracefully to local standalone operation + durable SQLite outbox when offline.
+- `off`: Pure standalone operation with zero network discovery or hosting.
+

appecosystem_hub-0.1.0/appecosystem_hub.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+appecosystem_hub.egg-info/PKG-INFO
+appecosystem_hub.egg-info/SOURCES.txt
+appecosystem_hub.egg-info/dependency_links.txt
+appecosystem_hub.egg-info/requires.txt
+appecosystem_hub.egg-info/top_level.txt
+ecosystem_hub/__init__.py
+ecosystem_hub/capabilities.py
+ecosystem_hub/lock.py
+ecosystem_hub/outbox.py
+ecosystem_hub/runtime.py

appecosystem_hub-0.1.0/appecosystem_hub.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

appecosystem_hub-0.1.0/appecosystem_hub.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx>=0.24.0
+appecosystem-auth>=0.4.0
+appecosystem-client>=0.4.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

appecosystem_hub-0.1.0/appecosystem_hub.egg-info/top_level.txt

@@ -0,0 +1 @@
+ecosystem_hub

appecosystem_hub-0.1.0/ecosystem_hub/__init__.py

@@ -0,0 +1,19 @@
+"""App-embeddable HubRuntime, SingleHostLock, CapabilityRegistry, and DurableOutbox."""
+from .capabilities import CapabilityRegistry, CapabilityResolution
+from .lock import SingleHostLock, default_hub_lock_path
+from .outbox import DurableOutbox, default_outbox_path
+from .runtime import HubRole, HubRuntime
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CapabilityRegistry",
+    "CapabilityResolution",
+    "DurableOutbox",
+    "HubRole",
+    "HubRuntime",
+    "SingleHostLock",
+    "default_hub_lock_path",
+    "default_outbox_path",
+]
+

appecosystem_hub-0.1.0/ecosystem_hub/capabilities.py

@@ -0,0 +1,225 @@
+"""Project-contributed capability registry with explicit withdrawal & unavailability reasons."""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ecosystem_client.contracts import assert_valid_schema
+
+
+@dataclass(frozen=True)
+class CapabilityResolution:
+    """Result of resolving a capability name for an automation, UI control, or voice intent."""
+
+    capability: str
+    available: bool
+    providers: list[dict[str, Any]] = field(default_factory=list)
+    unavailable_reason: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "capability": self.capability,
+            "available": self.available,
+            "providers": self.providers,
+            "unavailable_reason": self.unavailable_reason,
+        }
+
+
+class CapabilityRegistry:
+    """Stores validated capability-manifest.v1 entries and tracks provider availability.
+
+    Invariant: when a provider deregisters, withdraws, or fails health checks, dependent
+    capabilities report `available=False` with an explicit `unavailable_reason` rather
+    than silently disappearing or granting another provider expanded authority.
+    """
+
+    def __init__(self, persistence_path: str | Path | None = None):
+        self._path = Path(persistence_path) if persistence_path else None
+        self._lock = threading.RLock()
+        # Keyed by f"{capability}::{provider.app}::{provider.device_id}"
+        self._records: dict[str, dict[str, Any]] = {}
+        if self._path:
+            self._load()
+
+    @staticmethod
+    def _key(capability: str, app: str, device_id: str) -> str:
+        return f"{capability}::{app}::{device_id}"
+
+    def _load(self) -> None:
+        if not self._path or not self._path.is_file():
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                self._records = data
+        except Exception:
+            self._records = {}
+
+    def _persist(self) -> None:
+        if not self._path:
+            return
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(
+            dir=str(self._path.parent),
+            prefix=".capabilities.",
+            suffix=".tmp",
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(self._records, fh, indent=2)
+            try:
+                os.chmod(tmp, 0o600)
+            except OSError:
+                pass
+            os.replace(tmp, self._path)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+
+    def register(self, manifest: dict[str, Any]) -> dict[str, Any]:
+        """Validate against capability-manifest.v1 and upsert as an active capability."""
+        assert_valid_schema(manifest, "capability-manifest.v1")
+        cap = manifest["capability"]
+        provider = manifest["provider"]
+        app = provider["app"]
+        device_id = provider["device_id"]
+        now = time.time()
+
+        with self._lock:
+            k = self._key(cap, app, device_id)
+            prev = self._records.get(k)
+            record = {
+                "manifest": dict(manifest),
+                "capability": cap,
+                "app": app,
+                "device_id": device_id,
+                "action_class": manifest["action_class"],
+                "status": "active",
+                "unavailable_reason": None,
+                "registered_at": prev["registered_at"] if prev else now,
+                "updated_at": now,
+            }
+            self._records[k] = record
+            self._persist()
+            return dict(record)
+
+    def register_many(self, manifests: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return [self.register(m) for m in manifests]
+
+    def withdraw(
+        self,
+        capability: str,
+        app: str,
+        *,
+        device_id: str | None = None,
+        reason: str | None = None,
+    ) -> int:
+        """Mark matching capability record(s) withdrawn with a clear reason."""
+        now = time.time()
+        count = 0
+        with self._lock:
+            for rec in self._records.values():
+                if rec["capability"] != capability or rec["app"] != app:
+                    continue
+                if device_id is not None and rec["device_id"] != device_id:
+                    continue
+                if rec["status"] != "withdrawn":
+                    rec["status"] = "withdrawn"
+                    rec["unavailable_reason"] = (
+                        reason or f"Capability '{capability}' withdrawn by provider '{app}'"
+                    )
+                    rec["updated_at"] = now
+                    count += 1
+            if count:
+                self._persist()
+        return count
+
+    def withdraw_provider(
+        self,
+        app: str,
+        *,
+        device_id: str | None = None,
+        reason: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Withdraw all active capabilities owned by a deregistering or unhealthy provider."""
+        now = time.time()
+        affected: list[dict[str, Any]] = []
+        with self._lock:
+            for rec in self._records.values():
+                if rec["app"] != app:
+                    continue
+                if device_id is not None and rec["device_id"] != device_id:
+                    continue
+                if rec["status"] == "active":
+                    rec["status"] = "withdrawn"
+                    rec["unavailable_reason"] = (
+                        reason or f"Provider '{app}' ({rec['device_id']}) is offline or deregistered"
+                    )
+                    rec["updated_at"] = now
+                    affected.append(dict(rec))
+            if affected:
+                self._persist()
+        return affected
+
+    def list_capabilities(
+        self,
+        *,
+        action_class: str | None = None,
+        app: str | None = None,
+        capability: str | None = None,
+        active_only: bool = True,
+    ) -> list[dict[str, Any]]:
+        with self._lock:
+            out: list[dict[str, Any]] = []
+            for rec in self._records.values():
+                if active_only and rec["status"] != "active":
+                    continue
+                if action_class and rec["action_class"] != action_class:
+                    continue
+                if app and rec["app"] != app:
+                    continue
+                if capability and rec["capability"] != capability:
+                    continue
+                out.append(dict(rec))
+            return sorted(out, key=lambda r: (r["capability"], r["app"], r["device_id"]))
+
+    def resolve(self, capability: str) -> CapabilityResolution:
+        """Resolve healthy providers for `capability` or explain why it is unavailable."""
+        with self._lock:
+            matching = [r for r in self._records.values() if r["capability"] == capability]
+            if not matching:
+                return CapabilityResolution(
+                    capability=capability,
+                    available=False,
+                    providers=[],
+                    unavailable_reason=f"No installed project has registered capability '{capability}'",
+                )
+            active = [dict(r) for r in matching if r["status"] == "active"]
+            if active:
+                return CapabilityResolution(
+                    capability=capability,
+                    available=True,
+                    providers=active,
+                    unavailable_reason=None,
+                )
+            reasons = sorted(
+                {
+                    r.get("unavailable_reason") or f"Provider '{r['app']}' unavailable"
+                    for r in matching
+                }
+            )
+            return CapabilityResolution(
+                capability=capability,
+                available=False,
+                providers=[],
+                unavailable_reason="; ".join(reasons),
+            )
+

appecosystem_hub-0.1.0/ecosystem_hub/lock.py

@@ -0,0 +1,152 @@
+"""Cross-platform single-host advisory lock preventing duplicate local Hub instances."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+def default_hub_lock_path() -> Path:
+    override = (os.environ.get("ECOSYSTEM_HUB_LOCK_FILE") or "").strip()
+    if override:
+        return Path(override)
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+        return base / "Ecosystem" / "hub-host.lock"
+    return Path.home() / ".local" / "share" / "ecosystem" / "hub-host.lock"
+
+
+def _try_flock(fd: int) -> bool:
+    if sys.platform == "win32":
+        import msvcrt
+
+        try:
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            return True
+        except OSError:
+            return False
+    else:
+        import fcntl
+
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return True
+        except OSError:
+            return False
+
+
+def _unlock_fd(fd: int) -> None:
+    if sys.platform == "win32":
+        import msvcrt
+
+        try:
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+    else:
+        import fcntl
+
+        try:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        except OSError:
+            pass
+
+
+class SingleHostLock:
+    """Process-bound advisory file lock ensuring at most one embedded Hub per machine."""
+
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path is not None else default_hub_lock_path()
+        self._fd: int | None = None
+        self._metadata: dict[str, Any] | None = None
+
+    @property
+    def is_held(self) -> bool:
+        return self._fd is not None
+
+    @property
+    def metadata(self) -> dict[str, Any] | None:
+        return dict(self._metadata) if self._metadata else None
+
+    def acquire(
+        self,
+        *,
+        app_name: str,
+        hub_url: str,
+        priority: int = 0,
+        pid: int | None = None,
+    ) -> bool:
+        """Attempt to acquire the single-host lock without blocking."""
+        if self._fd is not None:
+            return True
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        flags = os.O_CREAT | os.O_RDWR
+        fd = os.open(str(self.path), flags, 0o600)
+        if not _try_flock(fd):
+            os.close(fd)
+            return False
+
+        meta = {
+            "app_name": app_name,
+            "pid": os.getpid() if pid is None else int(pid),
+            "priority": int(priority),
+            "hub_url": hub_url,
+            "acquired_at": time.time(),
+        }
+        payload = json.dumps(meta, indent=2).encode("utf-8")
+        try:
+            os.ftruncate(fd, 0)
+            os.lseek(fd, 0, os.SEEK_SET)
+            os.write(fd, payload)
+            os.fsync(fd)
+        except OSError:
+            pass
+
+        self._fd = fd
+        self._metadata = meta
+        return True
+
+    def release(self) -> None:
+        """Release the advisory lock if currently held by this instance."""
+        if self._fd is None:
+            return
+        fd = self._fd
+        self._fd = None
+        self._metadata = None
+        try:
+            os.ftruncate(fd, 0)
+        except OSError:
+            pass
+        _unlock_fd(fd)
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+
+    def inspect_owner(self) -> dict[str, Any] | None:
+        """Read current lock owner metadata without blocking (or None if unlocked/empty)."""
+        if self._metadata is not None:
+            return dict(self._metadata)
+        try:
+            if not self.path.is_file():
+                return None
+            raw = self.path.read_text(encoding="utf-8").strip()
+            if not raw:
+                return None
+            parsed = json.loads(raw)
+            return parsed if isinstance(parsed, dict) else None
+        except Exception:
+            return None
+
+    def __enter__(self) -> SingleHostLock:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()
+

appecosystem_hub-0.1.0/ecosystem_hub/outbox.py

@@ -0,0 +1,191 @@
+"""SQLite-backed offline notification & deferred payload outbox for standalone/disconnected nodes."""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+from ecosystem_client.contracts import assert_valid_schema
+
+
+def default_outbox_path(app_name: str) -> Path:
+    safe = "".join(ch if ch.isalnum() or ch in ("-", "_") else "_" for ch in app_name) or "app"
+    override = (os.environ.get("ECOSYSTEM_OUTBOX_DIR") or "").strip()
+    if override:
+        return Path(override) / f"outbox-{safe}.db"
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+        return base / "Ecosystem" / f"outbox-{safe}.db"
+    return Path.home() / ".local" / "share" / "ecosystem" / f"outbox-{safe}.db"
+
+
+class DurableOutbox:
+    """Bounded SQLite WAL queue storing pending `notify.*` envelopes while the Hub is unreachable."""
+
+    def __init__(self, db_path: str | Path, *, max_items: int = 1000):
+        self.db_path = Path(db_path)
+        self.max_items = max(10, int(max_items))
+        self._lock = threading.RLock()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.db_path), timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._lock, self._connect() as conn:
+            conn.execute("PRAGMA journal_mode=WAL;")
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS notification_outbox (
+                    id TEXT PRIMARY KEY,
+                    dedupe_key TEXT NOT NULL,
+                    envelope_json TEXT NOT NULL,
+                    status TEXT NOT NULL DEFAULT 'pending',
+                    attempts INTEGER NOT NULL DEFAULT 0,
+                    last_error TEXT,
+                    created_at REAL NOT NULL,
+                    updated_at REAL NOT NULL
+                );
+                """
+            )
+            conn.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_outbox_status_created
+                ON notification_outbox(status, created_at);
+                """
+            )
+            conn.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_outbox_dedupe_pending
+                ON notification_outbox(dedupe_key, status);
+                """
+            )
+        try:
+            os.chmod(self.db_path, 0o600)
+        except OSError:
+            pass
+
+    def enqueue(self, envelope: dict[str, Any]) -> bool:
+        """Enqueue a NotificationEnvelope if no pending item shares its dedupe_key.
+
+        Returns True if newly enqueued, False if deduplicated against a pending item.
+        """
+        assert_valid_schema(envelope, "notification-envelope.v1")
+        nid = envelope["id"]
+        dedupe_key = envelope["dedupe_key"]
+        now = time.time()
+        payload = json.dumps(envelope, separators=(",", ":"), sort_keys=True)
+
+        with self._lock, self._connect() as conn:
+            existing = conn.execute(
+                "SELECT id FROM notification_outbox WHERE dedupe_key = ? AND status = 'pending' LIMIT 1",
+                (dedupe_key,),
+            ).fetchone()
+            if existing is not None:
+                return False
+
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO notification_outbox
+                (id, dedupe_key, envelope_json, status, attempts, last_error, created_at, updated_at)
+                VALUES (?, ?, ?, 'pending', 0, NULL, ?, ?)
+                """,
+                (nid, dedupe_key, payload, now, now),
+            )
+            self._prune(conn)
+            return True
+
+    def _prune(self, conn: sqlite3.Connection) -> None:
+        total_row = conn.execute("SELECT COUNT(*) AS c FROM notification_outbox").fetchone()
+        total = int(total_row["c"]) if total_row else 0
+        if total <= self.max_items:
+            return
+        excess = total - self.max_items
+        # Evict delivered items first, then oldest pending items to strictly cap disk usage.
+        conn.execute(
+            """
+            DELETE FROM notification_outbox
+            WHERE id IN (
+                SELECT id FROM notification_outbox
+                ORDER BY CASE WHEN status = 'delivered' THEN 0 ELSE 1 END, created_at ASC
+                LIMIT ?
+            )
+            """,
+            (excess,),
+        )
+
+    def pending(self, limit: int = 50) -> list[dict[str, Any]]:
+        with self._lock, self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT envelope_json FROM notification_outbox
+                WHERE status = 'pending'
+                ORDER BY created_at ASC
+                LIMIT ?
+                """,
+                (int(limit),),
+            ).fetchall()
+        return [json.loads(r["envelope_json"]) for r in rows]
+
+    def pending_count(self) -> int:
+        with self._lock, self._connect() as conn:
+            row = conn.execute(
+                "SELECT COUNT(*) AS c FROM notification_outbox WHERE status = 'pending'"
+            ).fetchone()
+            return int(row["c"]) if row else 0
+
+    def mark_delivered(self, notification_id: str) -> None:
+        now = time.time()
+        with self._lock, self._connect() as conn:
+            conn.execute(
+                "UPDATE notification_outbox SET status = 'delivered', updated_at = ? WHERE id = ?",
+                (now, notification_id),
+            )
+
+    def record_failure(self, notification_id: str, error: str) -> None:
+        now = time.time()
+        with self._lock, self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE notification_outbox
+                SET attempts = attempts + 1, last_error = ?, updated_at = ?
+                WHERE id = ?
+                """,
+                (error[:500], now, notification_id),
+            )
+
+    async def flush(
+        self,
+        deliver_fn: Callable[[dict[str, Any]], Awaitable[bool]],
+        *,
+        batch_size: int = 50,
+    ) -> dict[str, int]:
+        """Deliver pending notifications via `deliver_fn`. Stops early on transport failure."""
+        items = self.pending(limit=batch_size)
+        delivered = 0
+        failed = 0
+        for env in items:
+            nid = env["id"]
+            try:
+                ok = await deliver_fn(env)
+            except Exception as exc:
+                self.record_failure(nid, repr(exc))
+                failed += 1
+                break
+            if ok:
+                self.mark_delivered(nid)
+                delivered += 1
+            else:
+                self.record_failure(nid, "delivery rejected or hub unreachable")
+                failed += 1
+                break
+        return {"delivered": delivered, "failed": failed, "remaining": self.pending_count()}
+

appecosystem_hub-0.1.0/ecosystem_hub/runtime.py

@@ -0,0 +1,458 @@
+"""Embeddable HubRuntime supporting `host | join | auto | off` across ecosystem projects."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import subprocess
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+import httpx
+
+from ecosystem_auth.tokens import sign_request
+from ecosystem_client import EcosystemClient
+from ecosystem_client.config import EcosystemConfig
+from ecosystem_client.contracts import build_notification_envelope
+from ecosystem_client.ulid import resolve_device_id
+
+from .capabilities import CapabilityRegistry, CapabilityResolution
+from .lock import SingleHostLock
+from .outbox import DurableOutbox, default_outbox_path
+
+logger = logging.getLogger(__name__)
+
+
+class HubRole(str, Enum):
+    HOST = "host"
+    JOIN = "join"
+    AUTO = "auto"
+    OFF = "off"
+
+
+def _parse_role(value: str | HubRole | None) -> HubRole:
+    raw = (value.value if isinstance(value, HubRole) else (value or os.environ.get("ECOSYSTEM_HUB_ROLE") or "auto")).strip().lower()
+    for member in HubRole:
+        if member.value == raw:
+            return member
+    logger.warning("Unknown ECOSYSTEM_HUB_ROLE %r — defaulting to 'auto'", raw)
+    return HubRole.AUTO
+
+
+class HubRuntime:
+    """Lifecycle coordinator enabling any eligible app to host, join, or run standalone.
+
+    Guarantees:
+    - Single-host lock (`SingleHostLock`) prevents duplicate embedded Hubs on one device.
+    - Hardware-tier awareness declines auto-hosting on `T0_MINIMAL` (<4 GB RAM) devices
+      unless `role='host'` or `allow_minimal_host=True` is explicitly configured.
+    - Capabilities work locally when standalone and sync to `/capabilities/register` when joined.
+    - `notify()` delivers to `/notifications/publish` when connected or buffers in a
+      SQLite `DurableOutbox` when offline, flushing automatically on reconnection.
+    """
+
+    def __init__(
+        self,
+        app_name: str,
+        *,
+        service_port: int = 0,
+        priority: int = 0,
+        role: str | HubRole | None = None,
+        capabilities: list[dict[str, Any]] | None = None,
+        subscriptions: list[str] | None = None,
+        health_endpoint: str = "/health",
+        config: EcosystemConfig | None = None,
+        lock_path: str | Path | None = None,
+        outbox_path: str | Path | None = None,
+        allow_minimal_host: bool = False,
+        sync_interval: float = 20.0,
+        host_spawner: Callable[[str, int], subprocess.Popen[Any]] | None = None,
+    ):
+        self.app_name = app_name
+        self.service_port = int(service_port)
+        self.priority = int(priority)
+        self.role = _parse_role(role)
+        self.health_endpoint = health_endpoint
+        self.device_id = resolve_device_id()
+
+        self.config = config or EcosystemConfig.from_env()
+        if priority:
+            self.config.priority = priority
+
+        self.local_capabilities = CapabilityRegistry()
+        self._initial_capabilities = list(capabilities or [])
+        self._subscriptions = list(subscriptions or [])
+        self._lock = SingleHostLock(lock_path)
+        self.outbox = DurableOutbox(outbox_path or default_outbox_path(app_name))
+        self._allow_minimal_host = allow_minimal_host
+        self._sync_interval = max(1.0, float(sync_interval))
+        self._host_spawner = host_spawner
+
+        self._client: EcosystemClient | None = None
+        self._sidecar_proc: subprocess.Popen[Any] | None = None
+        self._hosting = False
+        self._joined = False
+        self._effective_mode = "standalone"
+        self._started = False
+        self._bg_task: asyncio.Task[None] | None = None
+
+    @property
+    def effective_mode(self) -> str:
+        """One of `'hosting'`, `'joined'`, or `'standalone'`."""
+        return self._effective_mode
+
+    @property
+    def is_hosting(self) -> bool:
+        return self._hosting
+
+    @property
+    def is_joined(self) -> bool:
+        return self._joined
+
+    @property
+    def client(self) -> EcosystemClient | None:
+        return self._client
+
+    def _normalize_manifest(self, partial: dict[str, Any]) -> dict[str, Any]:
+        """Fill default provider `{app, device_id}` and `schema_version` if omitted."""
+        m = dict(partial)
+        m.setdefault("schema_version", 1)
+        m.setdefault("provider", {"app": self.app_name, "device_id": self.device_id})
+        return m
+
+    def _can_auto_host(self) -> bool:
+        if self.priority <= 0:
+            return False
+        if self._allow_minimal_host:
+            return True
+        try:
+            from ecosystem_ai.hardware import CapabilityTier, probe, tier_for
+
+            hw = probe()
+            if tier_for(hw) == CapabilityTier.T0_MINIMAL:
+                logger.info(
+                    "HubRuntime(%s): Tier T0_MINIMAL (<4 GB RAM) detected; preferring join/standalone over auto-hosting",
+                    self.app_name,
+                )
+                return False
+        except Exception:
+            pass
+        return True
+
+    async def _probe_hub_health(self, timeout: float = 1.5) -> bool:
+        url = f"{self.config.registry_url.rstrip('/')}/health"
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as http:
+                resp = await http.get(url)
+                return resp.status_code == 200
+        except Exception:
+            return False
+
+    def _default_spawn_sidecar(self, bind_host: str, port: int) -> subprocess.Popen[Any]:
+        repo_root = Path(__file__).resolve().parents[3]
+        env = os.environ.copy()
+        py_paths = [
+            str(repo_root),
+            str(repo_root / "auth" / "python"),
+            str(repo_root / "packages" / "ecosystem-ai"),
+            str(repo_root / "packages" / "ecosystem-client"),
+            str(repo_root / "packages" / "ecosystem-hub"),
+            str(repo_root / "packages" / "ecosystem-policy"),
+        ]
+        existing_py = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = os.pathsep.join(py_paths + ([existing_py] if existing_py else []))
+        cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            "registry.app:app",
+            "--host",
+            bind_host,
+            "--port",
+            str(port),
+            "--log-level",
+            "warning",
+        ]
+        creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if sys.platform == "win32" else 0
+        return subprocess.Popen(
+            cmd,
+            cwd=str(repo_root),
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=creationflags,
+        )
+
+    async def _try_start_host(self) -> bool:
+        parsed = urlparse(self.config.registry_url)
+        bind_host = parsed.hostname or "127.0.0.1"
+        port = parsed.port or 8500
+
+        if not self._lock.acquire(
+            app_name=self.app_name,
+            hub_url=self.config.registry_url,
+            priority=self.priority,
+        ):
+            # Another local app holds the lock — wait briefly for its /health to come up.
+            for _ in range(10):
+                if await self._probe_hub_health(timeout=0.5):
+                    return False
+                await asyncio.sleep(0.25)
+            return False
+
+        spawner = self._host_spawner or self._default_spawn_sidecar
+        try:
+            self._sidecar_proc = spawner(bind_host, port)
+        except Exception as exc:
+            logger.warning("HubRuntime(%s): failed to launch Hub sidecar: %r", self.app_name, exc)
+            self._lock.release()
+            return False
+
+        for _ in range(25):
+            if self._sidecar_proc.poll() is not None:
+                break
+            if await self._probe_hub_health(timeout=0.5):
+                self._hosting = True
+                return True
+            await asyncio.sleep(0.2)
+
+        # Failed health startup — clean up sidecar and release lock.
+        self._terminate_sidecar()
+        self._lock.release()
+        return False
+
+    def _terminate_sidecar(self) -> None:
+        proc = self._sidecar_proc
+        self._sidecar_proc = None
+        if proc is None:
+            return
+        try:
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=3.0)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+        except Exception:
+            pass
+
+    def _signed_headers(self, method: str, url: str, body: Any = None) -> dict[str, str]:
+        secret = self.config.hmac_secret
+        if not secret:
+            return {}
+        return sign_request(method, url, secret, body=body)
+
+    async def _sync_capabilities_to_hub(self) -> bool:
+        manifests = [
+            rec["manifest"]
+            for rec in self.local_capabilities.list_capabilities(app=self.app_name, active_only=True)
+        ]
+        if not manifests:
+            return True
+        url = f"{self.config.registry_url.rstrip('/')}/capabilities/register"
+        body = {"capabilities": manifests}
+        headers = self._signed_headers("POST", url, body)
+        try:
+            async with httpx.AsyncClient(timeout=self.config.request_timeout) as http:
+                resp = await http.post(url, json=body, headers=headers)
+                return resp.status_code < 400
+        except Exception as exc:
+            logger.debug("HubRuntime(%s): capability sync deferred: %r", self.app_name, exc)
+            return False
+
+    async def _withdraw_capabilities_from_hub(self) -> None:
+        url = f"{self.config.registry_url.rstrip('/')}/capabilities/{self.app_name}"
+        headers = self._signed_headers("DELETE", url)
+        try:
+            async with httpx.AsyncClient(timeout=2.5) as http:
+                await http.delete(url, headers=headers)
+        except Exception:
+            pass
+
+    async def _deliver_notification_to_hub(self, envelope: dict[str, Any]) -> bool:
+        url = f"{self.config.registry_url.rstrip('/')}/notifications/publish"
+        headers = self._signed_headers("POST", url, envelope)
+        async with httpx.AsyncClient(timeout=self.config.request_timeout) as http:
+            resp = await http.post(url, json=envelope, headers=headers)
+            return resp.status_code < 400
+
+    async def _join_reachable_hub(self) -> None:
+        if self.service_port > 0 and self._client is None:
+            self._client = EcosystemClient(
+                service_name=self.app_name,
+                service_port=self.service_port,
+                health_endpoint=self.health_endpoint,
+                subscriptions=self._subscriptions,
+                config=self.config,
+                priority=self.priority,
+            )
+            await self._client.start()
+
+        self._joined = True
+        self._effective_mode = "hosting" if self._hosting else "joined"
+        await self._sync_capabilities_to_hub()
+        await self.outbox.flush(self._deliver_notification_to_hub)
+
+    async def start(self) -> str:
+        """Start the HubRuntime according to `role`, returning `effective_mode`."""
+        if self._started:
+            return self._effective_mode
+
+        for raw_cap in self._initial_capabilities:
+            self.local_capabilities.register(self._normalize_manifest(raw_cap))
+
+        self._started = True
+
+        if self.role == HubRole.OFF:
+            self._effective_mode = "standalone"
+            return self._effective_mode
+
+        if await self._probe_hub_health():
+            await self._join_reachable_hub()
+        elif self.role == HubRole.HOST or (self.role == HubRole.AUTO and self._can_auto_host()):
+            hosted = await self._try_start_host()
+            if hosted or await self._probe_hub_health():
+                await self._join_reachable_hub()
+            else:
+                self._effective_mode = "standalone"
+        else:
+            self._effective_mode = "standalone"
+
+        self._bg_task = asyncio.create_task(self._background_loop())
+        return self._effective_mode
+
+    async def _background_loop(self) -> None:
+        while self._started:
+            await asyncio.sleep(self._sync_interval)
+            try:
+                alive = await self._probe_hub_health()
+                if alive:
+                    if not self._joined:
+                        await self._join_reachable_hub()
+                    else:
+                        await self._sync_capabilities_to_hub()
+                        if self.outbox.pending_count() > 0:
+                            await self.outbox.flush(self._deliver_notification_to_hub)
+                else:
+                    if self._joined and not self._hosting:
+                        self._joined = False
+                        self._effective_mode = "standalone"
+            except Exception as exc:
+                logger.debug("HubRuntime(%s) background sync error: %r", self.app_name, exc)
+
+    async def stop(self) -> None:
+        """Orderly shutdown: withdraw capabilities, close client, stop hosted sidecar, release lock."""
+        self._started = False
+        if self._bg_task:
+            self._bg_task.cancel()
+            try:
+                await self._bg_task
+            except asyncio.CancelledError:
+                pass
+            self._bg_task = None
+
+        if self._joined and not self._hosting:
+            await self._withdraw_capabilities_from_hub()
+
+        if self._client is not None:
+            try:
+                await self._client.stop()
+            except Exception:
+                pass
+            self._client = None
+
+        if self._hosting:
+            self._terminate_sidecar()
+            self._hosting = False
+
+        self._lock.release()
+        self._joined = False
+        self._effective_mode = "standalone"
+
+    async def register_capability(self, manifest: dict[str, Any]) -> dict[str, Any]:
+        norm = self._normalize_manifest(manifest)
+        rec = self.local_capabilities.register(norm)
+        if self._joined:
+            await self._sync_capabilities_to_hub()
+        return rec
+
+    async def withdraw_capability(self, capability: str, *, reason: str | None = None) -> int:
+        count = self.local_capabilities.withdraw(
+            capability,
+            self.app_name,
+            device_id=self.device_id,
+            reason=reason,
+        )
+        if self._joined:
+            url = f"{self.config.registry_url.rstrip('/')}/capabilities/{self.app_name}/{capability}"
+            headers = self._signed_headers("DELETE", url)
+            try:
+                async with httpx.AsyncClient(timeout=2.5) as http:
+                    await http.delete(url, headers=headers)
+            except Exception:
+                pass
+        return count
+
+    def resolve_capability(self, capability: str) -> CapabilityResolution:
+        return self.local_capabilities.resolve(capability)
+
+    async def notify(
+        self,
+        notify_type: str,
+        severity: str,
+        title: str,
+        body: str,
+        *,
+        dedupe_key: str,
+        actions: list[dict[str, Any]] | None = None,
+        privacy: str = "redacted",
+        ttl: str = "24h",
+        deep_link: str | None = None,
+    ) -> dict[str, Any]:
+        """Build a signed NotificationEnvelope and deliver to Hub or queue in DurableOutbox."""
+        envelope = build_notification_envelope(
+            notify_type=notify_type,
+            source_app=self.app_name,
+            severity=severity,
+            title=title,
+            body=body,
+            dedupe_key=dedupe_key,
+            device_id=self.device_id,
+            actions=actions,
+            privacy=privacy,
+            ttl=ttl,
+            deep_link=deep_link,
+            secret=self.config.hmac_secret or None,
+        )
+        if self._joined:
+            try:
+                if await self._deliver_notification_to_hub(envelope):
+                    return {"status": "delivered", "id": envelope["id"]}
+            except Exception:
+                pass
+
+        queued = self.outbox.enqueue(envelope)
+        return {
+            "status": "queued_offline" if queued else "deduplicated_offline",
+            "id": envelope["id"],
+        }
+
+    def status(self) -> dict[str, Any]:
+        return {
+            "app_name": self.app_name,
+            "device_id": self.device_id,
+            "role": self.role.value,
+            "effective_mode": self._effective_mode,
+            "hosting": self._hosting,
+            "joined": self._joined,
+            "hub_url": self.config.registry_url,
+            "lock_owner": self._lock.inspect_owner(),
+            "registered_capabilities": [
+                r["capability"]
+                for r in self.local_capabilities.list_capabilities(app=self.app_name, active_only=True)
+            ],
+            "pending_outbox": self.outbox.pending_count(),
+        }

appecosystem_hub-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "appecosystem-hub"
+version = "0.1.0"
+description = "Embedded/sidecar Hub runtime, single-host lock, capability registry, and durable offline outbox for appEcosystem"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Mikel Smart" }]
+keywords = ["appecosystem", "service-mesh", "capabilities", "notifications", "embedded-hub"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "appecosystem-auth>=0.4.0",
+    # 0.4.0 is the first client release with ecosystem_client.contracts and .ulid.
+    "appecosystem-client>=0.4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://github.com/M1K31/appEcosystem"
+Source = "https://github.com/M1K31/appEcosystem"
+Issues = "https://github.com/M1K31/appEcosystem/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ecosystem_hub*"]
+

appecosystem_hub-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+