arp-jarvis-runstore 0.3.5__tar.gz

arp_jarvis_runstore-0.3.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agent Runtime Protocol 
+
+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.

arp_jarvis_runstore-0.3.5/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: arp-jarvis-runstore
+Version: 0.3.5
+Summary: JARVIS Run Store internal service for Run and NodeRun persistence.
+Author: Agent Runtime Protocol
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: arp-standard-model==0.3.5
+Requires-Dist: arp-standard-server==0.3.5
+Requires-Dist: uvicorn>=0.29.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: httpx>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# JARVIS Run Store
+
+Internal JARVIS service that persists `Run` and `NodeRun` state for the Coordinator.
+This is a JARVIS-only contract (not part of the ARP Standard).
+
+## Requirements
+
+- Python >= 3.11
+
+## Install
+
+```bash
+python3 -m pip install -e .
+```
+
+## Run
+
+```bash
+python3 -m pip install -e .
+arp-jarvis-runstore
+```
+
+> [!TIP]
+> Use `bash src/scripts/dev_server.sh --host ... --port ... --reload` for dev convenience.
+
+## Configuration
+
+Environment variables:
+- `JARVIS_RUN_STORE_DB_URL` (default `sqlite:///./runs/jarvis_run_store.sqlite`)
+- `JARVIS_RUN_STORE_MAX_SIZE_MB` (optional guardrail)
+- `ARP_AUTH_*` (JWT auth settings, shared across JARVIS services)
+
+Auth is enabled by default (JWT). To disable for local dev, set `ARP_AUTH_PROFILE=dev-insecure`
+or `ARP_AUTH_MODE=disabled`. Health/version endpoints are always exempt.
+If no `ARP_AUTH_*` env vars are set, the service defaults to the dev Keycloak issuer.
+
+## API (v0.3.5)
+
+Health/version:
+- `GET /v1/health`
+- `GET /v1/version`
+
+Runs:
+- `POST /v1/runs` -> `{ run: Run }`
+- `GET /v1/runs/{run_id}`
+- `PUT /v1/runs/{run_id}` -> `{ run: Run }`
+
+NodeRuns:
+- `POST /v1/node-runs` -> `{ node_run: NodeRun }`
+- `GET /v1/node-runs/{node_run_id}`
+- `PUT /v1/node-runs/{node_run_id}` -> `{ node_run: NodeRun }`
+- `GET /v1/runs/{run_id}/node-runs?limit=100&page_token=...`
+
+Idempotency:
+- `POST` endpoints accept `idempotency_key` and will return the existing record if the key matches.
+
+## Notes
+
+- The store is owned by the Coordinator; no cross-component DB access.
+- Uses SQLite by default for v0.3.5.

arp_jarvis_runstore-0.3.5/README.md

@@ -0,0 +1,60 @@
+# JARVIS Run Store
+
+Internal JARVIS service that persists `Run` and `NodeRun` state for the Coordinator.
+This is a JARVIS-only contract (not part of the ARP Standard).
+
+## Requirements
+
+- Python >= 3.11
+
+## Install
+
+```bash
+python3 -m pip install -e .
+```
+
+## Run
+
+```bash
+python3 -m pip install -e .
+arp-jarvis-runstore
+```
+
+> [!TIP]
+> Use `bash src/scripts/dev_server.sh --host ... --port ... --reload` for dev convenience.
+
+## Configuration
+
+Environment variables:
+- `JARVIS_RUN_STORE_DB_URL` (default `sqlite:///./runs/jarvis_run_store.sqlite`)
+- `JARVIS_RUN_STORE_MAX_SIZE_MB` (optional guardrail)
+- `ARP_AUTH_*` (JWT auth settings, shared across JARVIS services)
+
+Auth is enabled by default (JWT). To disable for local dev, set `ARP_AUTH_PROFILE=dev-insecure`
+or `ARP_AUTH_MODE=disabled`. Health/version endpoints are always exempt.
+If no `ARP_AUTH_*` env vars are set, the service defaults to the dev Keycloak issuer.
+
+## API (v0.3.5)
+
+Health/version:
+- `GET /v1/health`
+- `GET /v1/version`
+
+Runs:
+- `POST /v1/runs` -> `{ run: Run }`
+- `GET /v1/runs/{run_id}`
+- `PUT /v1/runs/{run_id}` -> `{ run: Run }`
+
+NodeRuns:
+- `POST /v1/node-runs` -> `{ node_run: NodeRun }`
+- `GET /v1/node-runs/{node_run_id}`
+- `PUT /v1/node-runs/{node_run_id}` -> `{ node_run: NodeRun }`
+- `GET /v1/runs/{run_id}/node-runs?limit=100&page_token=...`
+
+Idempotency:
+- `POST` endpoints accept `idempotency_key` and will return the existing record if the key matches.
+
+## Notes
+
+- The store is owned by the Coordinator; no cross-component DB access.
+- Uses SQLite by default for v0.3.5.

arp_jarvis_runstore-0.3.5/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arp-jarvis-runstore"
+version = "0.3.5"
+description = "JARVIS Run Store internal service for Run and NodeRun persistence."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Agent Runtime Protocol" }]
+dependencies = [
+  "fastapi>=0.110.0",
+  "pydantic>=2.6.0",
+  "arp-standard-model==0.3.5",
+  "arp-standard-server==0.3.5",
+  "uvicorn>=0.29.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pyright>=1.1.0",
+  "pytest>=7",
+  "pytest-cov>=4",
+  "httpx>=0.23.0",
+]
+
+[project.scripts]
+arp-jarvis-runstore = "jarvis_run_store.__main__:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

arp_jarvis_runstore-0.3.5/setup.cfg

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

arp_jarvis_runstore-0.3.5/src/arp_jarvis_runstore.egg-info/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: arp-jarvis-runstore
+Version: 0.3.5
+Summary: JARVIS Run Store internal service for Run and NodeRun persistence.
+Author: Agent Runtime Protocol
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: arp-standard-model==0.3.5
+Requires-Dist: arp-standard-server==0.3.5
+Requires-Dist: uvicorn>=0.29.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: httpx>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# JARVIS Run Store
+
+Internal JARVIS service that persists `Run` and `NodeRun` state for the Coordinator.
+This is a JARVIS-only contract (not part of the ARP Standard).
+
+## Requirements
+
+- Python >= 3.11
+
+## Install
+
+```bash
+python3 -m pip install -e .
+```
+
+## Run
+
+```bash
+python3 -m pip install -e .
+arp-jarvis-runstore
+```
+
+> [!TIP]
+> Use `bash src/scripts/dev_server.sh --host ... --port ... --reload` for dev convenience.
+
+## Configuration
+
+Environment variables:
+- `JARVIS_RUN_STORE_DB_URL` (default `sqlite:///./runs/jarvis_run_store.sqlite`)
+- `JARVIS_RUN_STORE_MAX_SIZE_MB` (optional guardrail)
+- `ARP_AUTH_*` (JWT auth settings, shared across JARVIS services)
+
+Auth is enabled by default (JWT). To disable for local dev, set `ARP_AUTH_PROFILE=dev-insecure`
+or `ARP_AUTH_MODE=disabled`. Health/version endpoints are always exempt.
+If no `ARP_AUTH_*` env vars are set, the service defaults to the dev Keycloak issuer.
+
+## API (v0.3.5)
+
+Health/version:
+- `GET /v1/health`
+- `GET /v1/version`
+
+Runs:
+- `POST /v1/runs` -> `{ run: Run }`
+- `GET /v1/runs/{run_id}`
+- `PUT /v1/runs/{run_id}` -> `{ run: Run }`
+
+NodeRuns:
+- `POST /v1/node-runs` -> `{ node_run: NodeRun }`
+- `GET /v1/node-runs/{node_run_id}`
+- `PUT /v1/node-runs/{node_run_id}` -> `{ node_run: NodeRun }`
+- `GET /v1/runs/{run_id}/node-runs?limit=100&page_token=...`
+
+Idempotency:
+- `POST` endpoints accept `idempotency_key` and will return the existing record if the key matches.
+
+## Notes
+
+- The store is owned by the Coordinator; no cross-component DB access.
+- Uses SQLite by default for v0.3.5.

arp_jarvis_runstore-0.3.5/src/arp_jarvis_runstore.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/arp_jarvis_runstore.egg-info/PKG-INFO
+src/arp_jarvis_runstore.egg-info/SOURCES.txt
+src/arp_jarvis_runstore.egg-info/dependency_links.txt
+src/arp_jarvis_runstore.egg-info/entry_points.txt
+src/arp_jarvis_runstore.egg-info/requires.txt
+src/arp_jarvis_runstore.egg-info/top_level.txt
+src/jarvis_run_store/__init__.py
+src/jarvis_run_store/__main__.py
+src/jarvis_run_store/app.py
+src/jarvis_run_store/config.py
+src/jarvis_run_store/errors.py
+src/jarvis_run_store/service.py
+src/jarvis_run_store/sqlite.py
+src/jarvis_run_store/utils.py
+tests/test_cli.py
+tests/test_run_store_errors.py
+tests/test_run_store_smoke.py

arp_jarvis_runstore-0.3.5/src/arp_jarvis_runstore.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

arp_jarvis_runstore-0.3.5/src/arp_jarvis_runstore.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arp-jarvis-runstore = jarvis_run_store.__main__:main

arp_jarvis_runstore-0.3.5/src/arp_jarvis_runstore.egg-info/requires.txt

@@ -0,0 +1,11 @@
+fastapi>=0.110.0
+pydantic>=2.6.0
+arp-standard-model==0.3.5
+arp-standard-server==0.3.5
+uvicorn>=0.29.0
+
+[dev]
+pyright>=1.1.0
+pytest>=7
+pytest-cov>=4
+httpx>=0.23.0

arp_jarvis_runstore-0.3.5/src/arp_jarvis_runstore.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+jarvis_run_store
+scripts

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.5"

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/__main__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import argparse
+import uvicorn
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Start the JARVIS Run Store server.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8091)
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload (dev only).")
+    args = parser.parse_args()
+
+    if args.reload:
+        uvicorn.run("jarvis_run_store.app:app", host=args.host, port=args.port, reload=True)
+        return
+
+    from .app import create_app
+
+    app = create_app()
+    uvicorn.run(app, host=args.host, port=args.port, reload=False)
+
+
+if __name__ == "__main__":
+    main()

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/app.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .service import create_app
+
+app = create_app()

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/config.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class RunStoreConfig:
+    db_url: str
+    max_size_mb: int | None
+
+    @property
+    def db_path(self) -> Path:
+        return Path(_sqlite_path(self.db_url))
+
+
+def run_store_config_from_env() -> RunStoreConfig:
+    db_url = os.getenv("JARVIS_RUN_STORE_DB_URL", "sqlite:///./runs/jarvis_run_store.sqlite")
+    max_size_raw = os.getenv("JARVIS_RUN_STORE_MAX_SIZE_MB")
+    max_size = int(max_size_raw) if max_size_raw else None
+    return RunStoreConfig(db_url=db_url, max_size_mb=max_size)
+
+
+def _sqlite_path(db_url: str) -> str:
+    prefix = "sqlite:///"
+    if not db_url.startswith(prefix):
+        raise ValueError("Only sqlite:/// URLs are supported for JARVIS Run Store.")
+    path = db_url[len(prefix) :]
+    if not path:
+        raise ValueError("SQLite URL must include a file path.")
+    return path

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/errors.py

@@ -0,0 +1,14 @@
+class RunStoreError(Exception):
+    pass
+
+
+class NotFoundError(RunStoreError):
+    pass
+
+
+class ConflictError(RunStoreError):
+    pass
+
+
+class StorageFullError(RunStoreError):
+    pass

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/service.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import logging
+from typing import Annotated
+from datetime import datetime, timezone
+
+from arp_standard_model import Health, NodeRun, Run, Status, VersionInfo
+from arp_standard_server import AuthSettings
+from arp_standard_server.auth import register_auth_middleware
+from fastapi import FastAPI, HTTPException, Query
+from pydantic import BaseModel
+
+from . import __version__
+from .config import RunStoreConfig, run_store_config_from_env
+from .errors import ConflictError, NotFoundError, StorageFullError
+from .sqlite import ListNodeRunsResult, SqliteRunStore
+from .utils import (
+    auth_settings_from_env_or_dev_secure,
+    decode_page_token,
+    encode_page_token,
+    now,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CreateRunRequest(BaseModel):
+    run: Run
+    idempotency_key: str | None = None
+
+
+class RunResponse(BaseModel):
+    run: Run
+
+
+class CreateNodeRunRequest(BaseModel):
+    node_run: NodeRun
+    idempotency_key: str | None = None
+
+
+class NodeRunResponse(BaseModel):
+    node_run: NodeRun
+
+
+class ListNodeRunsResponse(BaseModel):
+    items: list[NodeRun]
+    next_token: str | None = None
+
+
+def create_app(
+    config: RunStoreConfig | None = None,
+    auth_settings: AuthSettings | None = None,
+) -> FastAPI:
+    cfg = config or run_store_config_from_env()
+    store = SqliteRunStore(cfg)
+    logger.info("Run Store config (db_path=%s, max_size_mb=%s)", cfg.db_path, cfg.max_size_mb)
+
+    app = FastAPI(title="JARVIS Run Store", version=__version__)
+    auth_settings = auth_settings or auth_settings_from_env_or_dev_secure()
+    logger.info(
+        "Run Store auth settings (mode=%s, issuer=%s)",
+        getattr(auth_settings, "mode", None),
+        getattr(auth_settings, "issuer", None),
+    )
+    register_auth_middleware(app, settings=auth_settings)
+
+    @app.get("/v1/health", response_model=Health)
+    async def health() -> Health:
+        return Health(status=Status.ok, time=datetime.now(timezone.utc))
+
+    @app.get("/v1/version", response_model=VersionInfo)
+    async def version() -> VersionInfo:
+        return VersionInfo(
+            service_name="arp-jarvis-runstore",
+            service_version=__version__,
+            supported_api_versions=["v1"],
+        )
+
+    @app.post("/v1/runs", response_model=RunResponse)
+    async def create_run(request: CreateRunRequest) -> RunResponse:
+        logger.info(
+            "Run create requested (run_id=%s, idempotency=%s)",
+            request.run.run_id,
+            bool(request.idempotency_key),
+        )
+        try:
+            run = store.create_run(request.run, idempotency_key=request.idempotency_key)
+        except ConflictError as exc:
+            logger.warning("Run create conflict (run_id=%s)", request.run.run_id)
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        except StorageFullError as exc:
+            logger.warning("Run store full (run_id=%s)", request.run.run_id)
+            raise HTTPException(status_code=507, detail=str(exc)) from exc
+        logger.info("Run created (run_id=%s, state=%s)", run.run_id, run.state)
+        return RunResponse(run=run)
+
+    @app.get("/v1/runs/{run_id}", response_model=RunResponse)
+    async def get_run(run_id: str) -> RunResponse:
+        logger.info("Run fetch requested (run_id=%s)", run_id)
+        try:
+            run = store.get_run(run_id)
+        except NotFoundError as exc:
+            logger.warning("Run not found (run_id=%s)", run_id)
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return RunResponse(run=run)
+
+    @app.put("/v1/runs/{run_id}", response_model=RunResponse)
+    async def update_run(run_id: str, request: RunResponse) -> RunResponse:
+        logger.info("Run update requested (run_id=%s)", run_id)
+        try:
+            run = store.update_run(run_id, request.run)
+        except NotFoundError as exc:
+            logger.warning("Run update missing (run_id=%s)", run_id)
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except ConflictError as exc:
+            logger.warning("Run update conflict (run_id=%s)", run_id)
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        logger.info("Run updated (run_id=%s, state=%s)", run.run_id, run.state)
+        return RunResponse(run=run)
+
+    @app.post("/v1/node-runs", response_model=NodeRunResponse)
+    async def create_node_run(request: CreateNodeRunRequest) -> NodeRunResponse:
+        logger.info(
+            "NodeRun create requested (node_run_id=%s, run_id=%s, idempotency=%s)",
+            request.node_run.node_run_id,
+            request.node_run.run_id,
+            bool(request.idempotency_key),
+        )
+        try:
+            node_run = store.create_node_run(request.node_run, idempotency_key=request.idempotency_key)
+        except ConflictError as exc:
+            logger.warning("NodeRun create conflict (node_run_id=%s)", request.node_run.node_run_id)
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        except StorageFullError as exc:
+            logger.warning("NodeRun store full (node_run_id=%s)", request.node_run.node_run_id)
+            raise HTTPException(status_code=507, detail=str(exc)) from exc
+        logger.info("NodeRun created (node_run_id=%s, state=%s)", node_run.node_run_id, node_run.state)
+        return NodeRunResponse(node_run=node_run)
+
+    @app.get("/v1/node-runs/{node_run_id}", response_model=NodeRunResponse)
+    async def get_node_run(node_run_id: str) -> NodeRunResponse:
+        logger.info("NodeRun fetch requested (node_run_id=%s)", node_run_id)
+        try:
+            node_run = store.get_node_run(node_run_id)
+        except NotFoundError as exc:
+            logger.warning("NodeRun not found (node_run_id=%s)", node_run_id)
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return NodeRunResponse(node_run=node_run)
+
+    @app.put("/v1/node-runs/{node_run_id}", response_model=NodeRunResponse)
+    async def update_node_run(node_run_id: str, request: NodeRunResponse) -> NodeRunResponse:
+        logger.info("NodeRun update requested (node_run_id=%s)", node_run_id)
+        try:
+            node_run = store.update_node_run(node_run_id, request.node_run)
+        except NotFoundError as exc:
+            logger.warning("NodeRun update missing (node_run_id=%s)", node_run_id)
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except ConflictError as exc:
+            logger.warning("NodeRun update conflict (node_run_id=%s)", node_run_id)
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        logger.info("NodeRun updated (node_run_id=%s, state=%s)", node_run.node_run_id, node_run.state)
+        return NodeRunResponse(node_run=node_run)
+
+    @app.get("/v1/runs/{run_id}/node-runs", response_model=ListNodeRunsResponse)
+    async def list_node_runs(
+        run_id: str,
+        limit: Annotated[int, Query(ge=1, le=500)] = 100,
+        page_token: str | None = None,
+    ) -> ListNodeRunsResponse:
+        logger.info("NodeRun list requested (run_id=%s, limit=%s, page_token=%s)", run_id, limit, bool(page_token))
+        if page_token:
+            try:
+                offset = decode_page_token(page_token)
+            except ValueError as exc:
+                raise HTTPException(status_code=422, detail=str(exc)) from exc
+        else:
+            offset = 0
+        result: ListNodeRunsResult = store.list_node_runs(run_id, limit=limit, offset=offset)
+        next_token = encode_page_token(result.next_offset) if result.next_offset is not None else None
+        logger.info(
+            "NodeRun list resolved (run_id=%s, count=%s, next_token=%s)",
+            run_id,
+            len(result.items),
+            bool(next_token),
+        )
+        return ListNodeRunsResponse(items=result.items, next_token=next_token)
+
+    return app

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/sqlite.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import dataclass
+from collections.abc import Sequence
+from typing import Iterator
+
+from arp_standard_model import NodeRun, Run
+
+from .config import RunStoreConfig
+from .errors import ConflictError, NotFoundError, StorageFullError
+from .utils import now
+
+
+@dataclass(frozen=True)
+class ListNodeRunsResult:
+    items: list[NodeRun]
+    next_offset: int | None
+
+
+class SqliteRunStore:
+    def __init__(self, config: RunStoreConfig) -> None:
+        self._db_path = config.db_path
+        self._max_size_mb = config.max_size_mb
+        self._ensure_db_dir()
+        self._init_db()
+
+    def create_run(self, run: Run, *, idempotency_key: str | None = None) -> Run:
+        self._check_size()
+        run_json = _encode_model(run)
+        timestamp = now()
+        with self._connect() as conn:
+            if idempotency_key:
+                existing = _fetch_one(conn, "SELECT run_id, run_json FROM runs WHERE idempotency_key = ?", (idempotency_key,))
+                if existing:
+                    existing_run = _decode_run(existing["run_json"])
+                    if existing_run.run_id != run.run_id:
+                        raise ConflictError("Idempotency key already used for a different run_id.")
+                    return existing_run
+            try:
+                conn.execute(
+                    "INSERT INTO runs (run_id, run_json, idempotency_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
+                    (run.run_id, run_json, idempotency_key, timestamp, timestamp),
+                )
+            except sqlite3.IntegrityError as exc:
+                raise ConflictError("Run already exists.") from exc
+        return run
+
+    def get_run(self, run_id: str) -> Run:
+        with self._connect() as conn:
+            row = _fetch_one(conn, "SELECT run_json FROM runs WHERE run_id = ?", (run_id,))
+        if not row:
+            raise NotFoundError("Run not found.")
+        return _decode_run(row["run_json"])
+
+    def update_run(self, run_id: str, run: Run) -> Run:
+        if run.run_id != run_id:
+            raise ConflictError("run_id path parameter does not match payload.")
+        run_json = _encode_model(run)
+        timestamp = now()
+        with self._connect() as conn:
+            cursor = conn.execute(
+                "UPDATE runs SET run_json = ?, updated_at = ? WHERE run_id = ?",
+                (run_json, timestamp, run_id),
+            )
+        if cursor.rowcount == 0:
+            raise NotFoundError("Run not found.")
+        return run
+
+    def create_node_run(self, node_run: NodeRun, *, idempotency_key: str | None = None) -> NodeRun:
+        self._check_size()
+        node_run_json = _encode_model(node_run)
+        timestamp = now()
+        with self._connect() as conn:
+            if idempotency_key:
+                existing = _fetch_one(
+                    conn,
+                    "SELECT node_run_id, node_run_json FROM node_runs WHERE idempotency_key = ?",
+                    (idempotency_key,),
+                )
+                if existing:
+                    existing_node_run = _decode_node_run(existing["node_run_json"])
+                    if existing_node_run.node_run_id != node_run.node_run_id:
+                        raise ConflictError("Idempotency key already used for a different node_run_id.")
+                    return existing_node_run
+            try:
+                conn.execute(
+                    "INSERT INTO node_runs (node_run_id, run_id, node_run_json, idempotency_key, created_at, updated_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (node_run.node_run_id, node_run.run_id, node_run_json, idempotency_key, timestamp, timestamp),
+                )
+            except sqlite3.IntegrityError as exc:
+                raise ConflictError("NodeRun already exists.") from exc
+        return node_run
+
+    def get_node_run(self, node_run_id: str) -> NodeRun:
+        with self._connect() as conn:
+            row = _fetch_one(conn, "SELECT node_run_json FROM node_runs WHERE node_run_id = ?", (node_run_id,))
+        if not row:
+            raise NotFoundError("NodeRun not found.")
+        return _decode_node_run(row["node_run_json"])
+
+    def update_node_run(self, node_run_id: str, node_run: NodeRun) -> NodeRun:
+        if node_run.node_run_id != node_run_id:
+            raise ConflictError("node_run_id path parameter does not match payload.")
+        node_run_json = _encode_model(node_run)
+        timestamp = now()
+        with self._connect() as conn:
+            cursor = conn.execute(
+                "UPDATE node_runs SET node_run_json = ?, updated_at = ? WHERE node_run_id = ?",
+                (node_run_json, timestamp, node_run_id),
+            )
+        if cursor.rowcount == 0:
+            raise NotFoundError("NodeRun not found.")
+        return node_run
+
+    def list_node_runs(self, run_id: str, *, limit: int, offset: int) -> ListNodeRunsResult:
+        with self._connect() as conn:
+            rows = list(
+                conn.execute(
+                    "SELECT node_run_json FROM node_runs WHERE run_id = ? ORDER BY created_at, node_run_id LIMIT ? OFFSET ?",
+                    (run_id, limit, offset),
+                )
+            )
+        items = [_decode_node_run(row["node_run_json"]) for row in rows]
+        next_offset = offset + len(items) if len(items) == limit else None
+        return ListNodeRunsResult(items=items, next_offset=next_offset)
+
+    @contextmanager
+    def _connect(self) -> Iterator[sqlite3.Connection]:
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def _ensure_db_dir(self) -> None:
+        if self._db_path.parent:
+            self._db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _init_db(self) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS runs ("
+                "run_id TEXT PRIMARY KEY, "
+                "run_json TEXT NOT NULL, "
+                "idempotency_key TEXT, "
+                "created_at TEXT NOT NULL, "
+                "updated_at TEXT NOT NULL"
+                ")"
+            )
+            conn.execute(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_idempotency ON runs(idempotency_key) "
+                "WHERE idempotency_key IS NOT NULL"
+            )
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS node_runs ("
+                "node_run_id TEXT PRIMARY KEY, "
+                "run_id TEXT NOT NULL, "
+                "node_run_json TEXT NOT NULL, "
+                "idempotency_key TEXT, "
+                "created_at TEXT NOT NULL, "
+                "updated_at TEXT NOT NULL"
+                ")"
+            )
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_node_runs_run_id ON node_runs(run_id)")
+            conn.execute(
+                "CREATE UNIQUE INDEX IF NOT EXISTS idx_node_runs_idempotency ON node_runs(idempotency_key) "
+                "WHERE idempotency_key IS NOT NULL"
+            )
+
+    def _check_size(self) -> None:
+        if self._max_size_mb is None or not self._db_path.exists():
+            return
+        size_mb = self._db_path.stat().st_size / (1024 * 1024)
+        if size_mb > self._max_size_mb:
+            raise StorageFullError("Run store exceeds configured max size.")
+
+
+def _fetch_one(conn: sqlite3.Connection, query: str, params: Sequence[object]) -> sqlite3.Row | None:
+    cursor = conn.execute(query, params)
+    return cursor.fetchone()
+
+
+def _encode_model(model: Run | NodeRun) -> str:
+    payload = model.model_dump(mode="json")
+    return json.dumps(payload, separators=(",", ":"), ensure_ascii=True)
+
+
+def _decode_run(raw: str) -> Run:
+    return Run.model_validate(json.loads(raw))
+
+
+def _decode_node_run(raw: str) -> NodeRun:
+    return NodeRun.model_validate(json.loads(raw))

arp_jarvis_runstore-0.3.5/src/jarvis_run_store/utils.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import base64
+import os
+from datetime import datetime, timezone
+
+from arp_standard_server import AuthSettings
+
+DEFAULT_DEV_KEYCLOAK_ISSUER = "http://localhost:8080/realms/arp-dev"
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def encode_page_token(offset: int) -> str:
+    return base64.urlsafe_b64encode(str(offset).encode()).decode()
+
+
+def decode_page_token(token: str) -> int:
+    try:
+        raw = base64.urlsafe_b64decode(token.encode()).decode()
+        return int(raw)
+    except Exception as exc:
+        raise ValueError("Invalid page_token.") from exc
+
+
+def _has_auth_env() -> bool:
+    return any(key.startswith("ARP_AUTH_") for key in os.environ)
+
+
+def auth_settings_from_env_or_dev_secure() -> AuthSettings:
+    if _has_auth_env():
+        return AuthSettings.from_env()
+    return AuthSettings(mode="required", issuer=DEFAULT_DEV_KEYCLOAK_ISSUER)

arp_jarvis_runstore-0.3.5/tests/test_cli.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import importlib
+import sys
+from types import SimpleNamespace
+from typing import Any
+
+from fastapi import FastAPI
+
+from jarvis_run_store import __main__ as main_mod
+
+
+class _CallCapture:
+    def __init__(self) -> None:
+        self.args: tuple[Any, ...] = ()
+        self.kwargs: dict[str, Any] = {}
+
+
+def test_main_reload(monkeypatch) -> None:
+    calls = _CallCapture()
+
+    def _run(*args, **kwargs):  # type: ignore[no-untyped-def]
+        calls.args = args
+        calls.kwargs = kwargs
+
+    monkeypatch.setattr(main_mod, "uvicorn", SimpleNamespace(run=_run))
+    monkeypatch.setenv("ARP_AUTH_MODE", "disabled")
+    monkeypatch.setattr(sys, "argv", ["prog", "--reload", "--host", "0.0.0.0", "--port", "9000"])
+
+    main_mod.main()
+
+    assert calls.args[0] == "jarvis_run_store.app:app"
+    assert calls.kwargs["reload"] is True
+    assert calls.kwargs["host"] == "0.0.0.0"
+    assert calls.kwargs["port"] == 9000
+
+
+def test_main_no_reload(monkeypatch) -> None:
+    calls = _CallCapture()
+
+    def _run(*args, **kwargs):  # type: ignore[no-untyped-def]
+        calls.args = args
+        calls.kwargs = kwargs
+
+    monkeypatch.setattr(main_mod, "uvicorn", SimpleNamespace(run=_run))
+    monkeypatch.setenv("ARP_AUTH_MODE", "disabled")
+    monkeypatch.setattr(sys, "argv", ["prog", "--host", "127.0.0.1", "--port", "9001"])
+
+    main_mod.main()
+
+    assert isinstance(calls.args[0], FastAPI)
+    assert calls.kwargs["reload"] is False
+    assert calls.kwargs["host"] == "127.0.0.1"
+    assert calls.kwargs["port"] == 9001
+
+
+def test_app_module(monkeypatch) -> None:
+    monkeypatch.setenv("ARP_AUTH_MODE", "disabled")
+    sys.modules.pop("jarvis_run_store.app", None)
+    module = importlib.import_module("jarvis_run_store.app")
+    assert hasattr(module, "app")

arp_jarvis_runstore-0.3.5/tests/test_run_store_errors.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+from fastapi.testclient import TestClient
+
+from arp_standard_model import NodeRun, NodeRunState, NodeTypeRef, Run, RunState
+from arp_standard_server import AuthSettings
+from jarvis_run_store.config import RunStoreConfig, run_store_config_from_env
+from jarvis_run_store.errors import ConflictError, NotFoundError, StorageFullError
+from jarvis_run_store.service import create_app
+from jarvis_run_store.sqlite import SqliteRunStore
+from jarvis_run_store.utils import (
+    DEFAULT_DEV_KEYCLOAK_ISSUER,
+    auth_settings_from_env_or_dev_secure,
+    decode_page_token,
+)
+
+
+def _make_run(run_id: str = "run_1", root_node_run_id: str = "node_1") -> Run:
+    return Run(run_id=run_id, root_node_run_id=root_node_run_id, state=RunState.running)
+
+
+def _make_node_run(node_run_id: str = "node_1", run_id: str = "run_1") -> NodeRun:
+    return NodeRun(
+        node_run_id=node_run_id,
+        run_id=run_id,
+        state=NodeRunState.running,
+        node_type_ref=NodeTypeRef(node_type_id="jarvis.core.echo", version="0.3.5"),
+    )
+
+
+def test_invalid_sqlite_url() -> None:
+    config = RunStoreConfig(db_url="postgres://db", max_size_mb=None)
+    with pytest.raises(ValueError):
+        _ = config.db_path
+
+
+def test_missing_sqlite_path() -> None:
+    config = RunStoreConfig(db_url="sqlite:///", max_size_mb=None)
+    with pytest.raises(ValueError):
+        _ = config.db_path
+
+
+def test_config_from_env(monkeypatch, tmp_path) -> None:
+    monkeypatch.setenv("JARVIS_RUN_STORE_DB_URL", f"sqlite:///{tmp_path / 'runs.sqlite'}")
+    monkeypatch.setenv("JARVIS_RUN_STORE_MAX_SIZE_MB", "5")
+    config = run_store_config_from_env()
+    assert config.db_url.endswith("runs.sqlite")
+    assert config.max_size_mb == 5
+
+
+def test_auth_settings_default(monkeypatch) -> None:
+    for key in list(os.environ):
+        if key.startswith("ARP_AUTH_"):
+            monkeypatch.delenv(key, raising=False)
+    settings = auth_settings_from_env_or_dev_secure()
+    assert settings.mode == "required"
+    assert settings.issuer == DEFAULT_DEV_KEYCLOAK_ISSUER
+
+
+def test_auth_settings_from_env(monkeypatch) -> None:
+    monkeypatch.setenv("ARP_AUTH_MODE", "disabled")
+    settings = auth_settings_from_env_or_dev_secure()
+    assert settings.mode == "disabled"
+
+
+def test_decode_page_token_invalid() -> None:
+    with pytest.raises(ValueError):
+        decode_page_token("not-base64")
+
+
+def test_idempotency_conflicts(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    store = SqliteRunStore(config)
+
+    run_one = _make_run(run_id="run_1")
+    store.create_run(run_one, idempotency_key="key-1")
+    existing = store.create_run(run_one, idempotency_key="key-1")
+    assert existing.run_id == "run_1"
+
+    run_two = _make_run(run_id="run_2")
+    with pytest.raises(ConflictError):
+        store.create_run(run_two, idempotency_key="key-1")
+
+    with pytest.raises(ConflictError):
+        store.create_run(run_one)
+
+
+def test_missing_run_and_node_run(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    store = SqliteRunStore(config)
+
+    with pytest.raises(NotFoundError):
+        store.get_run("missing")
+
+    with pytest.raises(NotFoundError):
+        store.get_node_run("missing")
+
+
+def test_update_id_mismatch(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    store = SqliteRunStore(config)
+
+    run = _make_run(run_id="run_1")
+    store.create_run(run)
+
+    with pytest.raises(ConflictError):
+        store.update_run("run_2", run)
+
+    with pytest.raises(NotFoundError):
+        store.update_run("missing", _make_run(run_id="missing"))
+
+    node_run = _make_node_run(node_run_id="node_1")
+    store.create_node_run(node_run)
+
+    with pytest.raises(ConflictError):
+        store.update_node_run("node_2", node_run)
+
+    with pytest.raises(NotFoundError):
+        store.update_node_run("missing", _make_node_run(node_run_id="missing", run_id="run_1"))
+
+
+def test_storage_full(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=0)
+    store = SqliteRunStore(config)
+
+    with pytest.raises(StorageFullError):
+        store.create_run(_make_run())
+
+
+def test_invalid_page_token_returns_422(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    app = create_app(config, auth_settings=AuthSettings(mode="disabled"))
+    client = TestClient(app)
+
+    resp = client.get("/v1/runs/run_1/node-runs", params={"page_token": "bad-token"})
+    assert resp.status_code == 422
+
+
+def test_service_conflict_and_not_found(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    app = create_app(config, auth_settings=AuthSettings(mode="disabled"))
+    client = TestClient(app)
+
+    run = _make_run(run_id="run_1")
+    create_resp = client.post("/v1/runs", json={"run": run.model_dump(mode="json")})
+    assert create_resp.status_code == 200
+
+    conflict_resp = client.put(
+        "/v1/runs/run_1",
+        json={"run": _make_run(run_id="run_2").model_dump(mode="json")},
+    )
+    assert conflict_resp.status_code == 409
+
+    missing_resp = client.put(
+        "/v1/runs/missing",
+        json={"run": _make_run(run_id="missing").model_dump(mode="json")},
+    )
+    assert missing_resp.status_code == 404
+
+    node_run = _make_node_run(node_run_id="node_1", run_id="run_1")
+    client.post("/v1/node-runs", json={"node_run": node_run.model_dump(mode="json")})
+
+    node_conflict = client.put(
+        "/v1/node-runs/node_1",
+        json={"node_run": _make_node_run(node_run_id="node_2", run_id="run_1").model_dump(mode="json")},
+    )
+    assert node_conflict.status_code == 409
+
+    node_missing = client.put(
+        "/v1/node-runs/missing",
+        json={"node_run": _make_node_run(node_run_id="missing", run_id="run_1").model_dump(mode="json")},
+    )
+    assert node_missing.status_code == 404
+
+
+def test_service_storage_full_returns_507(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=0)
+    app = create_app(config, auth_settings=AuthSettings(mode="disabled"))
+    client = TestClient(app)
+
+    run = _make_run(run_id="run_1")
+    resp = client.post("/v1/runs", json={"run": run.model_dump(mode="json")})
+    assert resp.status_code == 507
+
+    node_run = _make_node_run(node_run_id="node_1", run_id="run_1")
+    resp = client.post("/v1/node-runs", json={"node_run": node_run.model_dump(mode="json")})
+    assert resp.status_code == 507

arp_jarvis_runstore-0.3.5/tests/test_run_store_smoke.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from arp_standard_model import NodeRun, NodeRunState, NodeTypeRef, Run, RunState
+from arp_standard_server import AuthSettings
+from jarvis_run_store.config import RunStoreConfig
+from jarvis_run_store.service import create_app
+
+
+def _make_run(run_id: str = "run_1", root_node_run_id: str = "node_1") -> Run:
+    return Run(run_id=run_id, root_node_run_id=root_node_run_id, state=RunState.running)
+
+
+def _make_node_run(node_run_id: str = "node_1", run_id: str = "run_1") -> NodeRun:
+    return NodeRun(
+        node_run_id=node_run_id,
+        run_id=run_id,
+        state=NodeRunState.running,
+        node_type_ref=NodeTypeRef(node_type_id="jarvis.core.echo", version="0.3.5"),
+    )
+
+
+def test_run_store_roundtrip(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    app = create_app(config, auth_settings=AuthSettings(mode="disabled"))
+    client = TestClient(app)
+
+    run = _make_run()
+    create_resp = client.post("/v1/runs", json={"run": run.model_dump(mode="json")})
+    assert create_resp.status_code == 200
+    assert create_resp.json()["run"]["run_id"] == "run_1"
+
+    get_resp = client.get("/v1/runs/run_1")
+    assert get_resp.status_code == 200
+
+    update_run = _make_run()
+    update_resp = client.put("/v1/runs/run_1", json={"run": update_run.model_dump(mode="json")})
+    assert update_resp.status_code == 200
+
+
+def test_node_run_listing_with_pagination(tmp_path) -> None:
+    config = RunStoreConfig(db_url=f"sqlite:///{tmp_path / 'run_store.sqlite'}", max_size_mb=None)
+    app = create_app(config, auth_settings=AuthSettings(mode="disabled"))
+    client = TestClient(app)
+
+    run = _make_run()
+    client.post("/v1/runs", json={"run": run.model_dump(mode="json")})
+
+    node_one = _make_node_run(node_run_id="node_1")
+    node_two = _make_node_run(node_run_id="node_2")
+    client.post("/v1/node-runs", json={"node_run": node_one.model_dump(mode="json")})
+    client.post("/v1/node-runs", json={"node_run": node_two.model_dump(mode="json")})
+
+    first_page = client.get("/v1/runs/run_1/node-runs", params={"limit": 1})
+    assert first_page.status_code == 200
+    payload = first_page.json()
+    assert len(payload["items"]) == 1
+    assert payload["next_token"]
+
+    second_page = client.get(
+        "/v1/runs/run_1/node-runs",
+        params={"limit": 1, "page_token": payload["next_token"]},
+    )
+    assert second_page.status_code == 200
+    assert len(second_page.json()["items"]) == 1