decision-layer 0.1.0a1__py3-none-any.whl

decision_layer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a1"

decision_layer/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

decision_layer/api/app.py

@@ -0,0 +1,94 @@
+"""FastAPI assembly and lifecycle. Routes live beside this file by resource."""
+from __future__ import annotations
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from .. import __version__
+from ..i18n import negotiate, set_locale
+from ..core.errors import DecisionLayerError
+from ..core.models import CallerInfo
+from ..semantic.provider import SemanticProvider
+from ..sources.config import SourceConfigManager
+from ..sources.provider import ConfiguredSemanticProvider
+from ..sources.store import open_source_store
+from ..recipes.loader import RecipeStore
+from ..runs.engine import RunEngine
+from ..runs.jobs import JobRunner
+from ..runs.store import RunStore, open_store
+from ..settings import Settings
+from .dependencies import Caller
+
+def create_app(settings: Settings | None = None, provider: SemanticProvider | None = None,
+               store: RunStore | None = None, recipes: RecipeStore | None = None) -> FastAPI:
+    settings = settings or Settings()
+    settings.validate_deployment()
+    source_manager = SourceConfigManager(open_source_store(settings.database_url), settings)
+    provider = provider or ConfiguredSemanticProvider(source_manager)
+    from ..methods.loading import configured_registry
+    registry = configured_registry(settings)
+    from ..methods.assets import MethodAssets
+    assets = MethodAssets(settings.method_assets_dir, registry)
+    recipes = recipes or RecipeStore(settings.recipes_dir, provider.name, provider.instance, registry=registry)
+    recipes.registry = registry
+    engine = RunEngine(provider, recipes, store or open_store(settings.database_url),
+                       jobs=JobRunner(settings.job_workers), policy=settings.execution_policy, registry=registry)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        await source_manager.effective(resolve_secret=False)
+        await engine.recover()
+        yield
+        engine.jobs.shutdown()
+
+    app = FastAPI(title="Decision Layer", version=__version__, lifespan=lifespan)
+
+    @app.middleware("http")
+    async def locale(request: Request, call_next):
+        from urllib.parse import urlsplit
+        try:
+            host = urlsplit("//" + request.headers.get("host", "")).hostname
+            origin = request.headers.get("origin")
+            parsed_origin = urlsplit(origin) if origin else None
+        except ValueError:
+            return JSONResponse(status_code=403, content={"error": {"code": "LOCAL_HTTP_ORIGIN_DENIED"}})
+        if host not in settings.http_allowed_hosts or (parsed_origin and (
+                parsed_origin.scheme not in ("http", "https") or parsed_origin.hostname not in settings.http_allowed_hosts)):
+            return JSONResponse(status_code=403, content={"error": {
+                "code": "LOCAL_HTTP_ORIGIN_DENIED", "message": "Host or Origin is not allowed for this local deployment."}})
+        set_locale(negotiate(request.headers.get("accept-language"), settings.locale))
+        response = await call_next(request)
+        response.headers["Content-Language"] = negotiate(request.headers.get("accept-language"), settings.locale)
+        return response
+    app.state.method_assets = assets
+    app.state.settings = settings
+    app.state.provider = provider
+    app.state.source_manager = source_manager
+
+    @app.exception_handler(DecisionLayerError)
+    async def _app_error(_request: Request, exc: DecisionLayerError) -> JSONResponse:
+        return JSONResponse(status_code=exc.http_status, content={"error": exc.to_dict()})
+
+    @app.get("/health")
+    async def health() -> dict:
+        await source_manager.effective(resolve_secret=False)
+        return {"status": "ok", "version": __version__, "provider": provider.name, "instance": provider.instance}
+
+    @app.get("/me", response_model=CallerInfo)
+    async def me(caller: Caller) -> CallerInfo:
+        """The identity runs are stored under for this caller."""
+        return caller
+
+    from .sources import create_router as sources_router
+    app.include_router(sources_router(settings, provider, source_manager))
+    from .semantic import create_router as semantic_router
+    app.include_router(semantic_router(provider, engine))
+    from .methods import create_router as methods_router
+    app.include_router(methods_router(settings, engine))
+    from .recipes import create_router as recipes_router
+    app.include_router(recipes_router(settings, provider, recipes, engine))
+    from .runs import create_router as runs_router
+    app.include_router(runs_router(settings, provider, recipes, engine))
+    return app
+
+
+app = create_app()

decision_layer/api/dependencies.py

@@ -0,0 +1,113 @@
+"""Authentication and shared HTTP response helpers."""
+from __future__ import annotations
+from typing import Annotated, Literal
+from fastapi import Depends, Header, Request
+from fastapi.responses import JSONResponse
+from ..auth import credentials, identify
+from ..i18n import _
+from ..core.errors import DecisionLayerError
+from ..core.models import CallerInfo, MethodManifest, Run
+from ..semantic.credentials import AnonymousServiceCredentials, RequestCredentials, ServiceCredentials
+from ..sources.config import EffectiveSource
+from ..sources.provider import ConfiguredSemanticProvider
+from ..settings import Settings
+from ..i18n import _
+
+PREVIEW_ROWS = 1000
+MAX_WAIT_SECONDS = 300
+
+
+def run_origin(request: Request) -> Literal["api", "web", "mcp"]:
+    hint = request.headers.get("X-Decision-Layer-Client")
+    return hint if hint in ("web", "mcp") else "api"
+
+
+class JobFailed(DecisionLayerError):
+    """The run's last background job raised; code/message are the recorded ones."""
+    http_status = 422
+
+    def __init__(self, error: dict) -> None:
+        super().__init__(error.get("message", ""))
+        self.code = error.get("code", "JOB_FAILED")
+
+
+class NoResult(DecisionLayerError):
+    code = "NO_RESULT"
+    http_status = 404
+
+
+class SourceAdminRequired(DecisionLayerError):
+    code = "SOURCE_ADMIN_REQUIRED"
+    http_status = 403
+
+
+class RecipePermissionRequired(DecisionLayerError):
+    code = "RECIPE_PERMISSION_REQUIRED"
+    http_status = 403
+
+
+def require_recipe_permission(settings: Settings, caller: CallerInfo, *, publish: bool = False) -> None:
+    # Explicit local service access belongs to the person operating this runtime.
+    # It is never a multi-user identity; shared mode is rejected at startup.
+    local_owner = settings.allow_service_credentials and caller.authentication == "local_service" and caller.subject in (
+        "service:decision-layer", "service:local-development")
+    subjects = settings.recipe_publishers if publish else (*settings.recipe_editors, *settings.recipe_publishers)
+    if not local_owner and caller.subject not in subjects:
+        raise RecipePermissionRequired("Recipe publication requires publisher permission." if publish
+                                       else "Recipe changes require editor permission.")
+
+
+class MethodPermissionRequired(DecisionLayerError):
+    code = "METHOD_PERMISSION_REQUIRED"
+    http_status = 403
+
+
+def require_method_permission(settings: Settings, caller: CallerInfo, *, publish: bool = False):
+    local_owner = settings.allow_service_credentials and caller.authentication == "local_service" and caller.subject in (
+        "service:decision-layer", "service:local-development")
+    subjects = settings.method_publishers if publish else (*settings.method_editors, *settings.method_publishers)
+    if not local_owner and caller.subject not in subjects:
+        raise MethodPermissionRequired("Method publication and Python import checks require a Method publisher." if publish
+                                       else "Method drafts require a Method editor.")
+
+
+async def get_credentials(request: Request, authorization: Annotated[str | None, Header()] = None):
+    """The caller's bearer token is passed through to the provider (ADR-024); service credentials
+    are a local/dev fallback that must be switched on explicitly (ADR-029)."""
+    settings: Settings = request.app.state.settings
+    source: EffectiveSource = await request.app.state.source_manager.effective(resolve_secret=False)
+    if source.auth_method == "api_secret" and not authorization:
+        source = await request.app.state.source_manager.effective()
+    if isinstance(request.app.state.provider, ConfiguredSemanticProvider):
+        request.app.state.provider.bind(source)
+    return credentials(authorization, allow_service=settings.allow_service_credentials,
+                       secret=source.api_secret, groups=source.service_groups, auth_method=source.auth_method)
+
+
+Creds = Annotated[RequestCredentials | ServiceCredentials | AnonymousServiceCredentials, Depends(get_credentials)]
+
+
+async def get_caller(request: Request, creds: Creds) -> CallerInfo:
+    return await identify(request.app.state.provider, creds)
+
+
+Caller = Annotated[CallerInfo, Depends(get_caller)]
+
+
+def localized(m: MethodManifest) -> MethodManifest:
+    """Manifest texts are English in code; serve them in the request's language."""
+    return m.model_copy(update={
+        "description": _(m.description),
+        "label": _(m.label),
+        "roles": {k: r.model_copy(update={"description": _(r.description), "label": _(r.label)}) for k, r in m.roles.items()},
+        "parameters": {k: p.model_copy(update={"description": _(p.description), "label": _(p.label)}) for k, p in m.parameters.items()},
+    })
+
+
+def waited(settings: Settings, wait: float | None) -> float:
+    return max(0.0, min(settings.request_wait_seconds if wait is None else wait, MAX_WAIT_SECONDS))
+
+def accepted(run: Run) -> JSONResponse:
+    return JSONResponse(status_code=202, content={
+        "run_id": run.id, "status": "running", "running": run.running.model_dump(mode="json") if run.running else None,
+        "poll": f"/runs/{run.id}/result"})

decision_layer/api/methods.py

@@ -0,0 +1,124 @@
+"""Methods HTTP routes; analytical work stays in the canonical engine."""
+from __future__ import annotations
+from fastapi import Request
+from ..core.models import MethodManifest, PlanStep, Result
+from ..methods.discovery import MethodSearchRequest, find_methods
+from ..methods.context import ExecutionContext
+from ..service import MethodRunRequest
+from ..methods.assets import DraftRequest, RevisionRequest
+from ..core.errors import DecisionLayerError
+from ..methods.invocation import invocation_inputs
+from fastapi import APIRouter
+from .dependencies import Caller, Creds, accepted, localized, run_origin, waited
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FormatRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    content: str = Field(min_length=1, max_length=150_000)
+
+def create_router(settings, engine):
+    registry = engine.registry
+    router = APIRouter()
+    @router.get("/methods", response_model=list[MethodManifest])
+    async def methods() -> list[MethodManifest]:
+        return [localized(m) for m in registry.manifests()]
+
+    @router.post("/methods:search")
+    async def method_search(req: MethodSearchRequest, creds: Creds, caller: Caller):
+        catalog = await engine.provider.discover(creds)
+        report = find_methods(registry, ExecutionContext(engine.provider, creds, catalog), req)
+        for candidate in report["candidates"]:
+            candidate["manifest"] = localized(MethodManifest.model_validate(candidate["manifest"])).model_dump(mode="json")
+        return report
+
+    @router.get("/method-guides/{name}")
+    async def authoring_guide(name: str):
+        from ..methods.skills import get_authoring_guide
+        return get_authoring_guide(name)
+
+    def permitted(caller, publish=False):
+        from .dependencies import require_method_permission
+        from ..methods.assets import AssetError
+        if not settings.allow_method_editing or not settings.method_assets_dir:
+            raise AssetError("Method editing is disabled by the operator")
+        require_method_permission(settings, caller, publish=publish)
+
+    @router.get("/methods/{name}/source")
+    async def source(name: str, caller: Caller, request: Request):
+        asset = registry.get(name)
+        store = request.app.state.method_assets
+        can_edit = can_publish = False
+        try:
+            permitted(caller);can_edit = True
+            permitted(caller, True);can_publish = True
+        except DecisionLayerError:
+            pass
+        skill = asset.manifest.implementation == "skill"
+        snapshot = None if skill else getattr(asset, "source_snapshot", None)
+        return {"name":name, "version":asset.manifest.version,"implementation":asset.manifest.implementation,
+                "content":asset.source_text if skill else snapshot.editor_content if snapshot else None,
+                "code":snapshot,"permissions":{"edit":can_edit,"publish":can_publish},
+                "draft":store.draft(name) if can_edit else None,
+                "history":[{key:value for key,value in entry.items() if key in ("version","published_by","published_at")}
+                           for entry in store.history(name)]}
+
+    @router.put("/methods/{name}/draft")
+    async def save_draft(name: str, req: DraftRequest, caller: Caller, request: Request):
+        permitted(caller)
+        return request.app.state.method_assets.save(name, req, caller.subject)
+
+    @router.post("/methods/{name}/source:format")
+    async def format_source(name: str, req: FormatRequest, caller: Caller):
+        from starlette.concurrency import run_in_threadpool
+        from ..methods.assets import AssetError
+        from ..methods.formatting import format_python
+
+        permitted(caller)
+        if registry.get(name).manifest.implementation != "python":
+            raise AssetError("Formatting is available for Python Methods only")
+        content = await run_in_threadpool(format_python, req.content)
+        return {"content": content, "changed": content != req.content}
+
+    @router.post("/methods/{name}/draft:check")
+    async def check_draft(name: str, req: RevisionRequest, caller: Caller, request: Request):
+        python = registry.get(name).manifest.implementation == "python"
+        permitted(caller, python)
+        if python and not req.reviewed:
+            from ..methods.assets import AssetError
+            raise AssetError("Review and trust this Python module before executing registration checks")
+        return await request.app.state.method_assets.check(name, req.revision)
+
+    @router.post("/methods/{name}/draft:publish")
+    async def publish_draft(name: str, req: RevisionRequest, caller: Caller, request: Request):
+        permitted(caller, True)
+        entry = request.app.state.method_assets.publish(name, req, caller.subject)
+        return {"name":name,"version":entry["version"],"published_at":entry["published_at"]}
+
+    @router.get("/methods/{name}/guide")
+    async def method_guide(name: str):
+        from ..methods.skills import SkillMethod
+        from ..methods.registry import InvalidBinding
+        asset = registry.get(name)
+        if not isinstance(asset, SkillMethod):
+            raise InvalidBinding("This is an executable Python Method, not a Skill")
+        return asset.guide
+
+    @router.get("/methods/{name}", response_model=MethodManifest)
+    async def method(name: str, version: str | None = None) -> MethodManifest:
+        return localized(registry.get(name, version).manifest)
+
+    @router.post("/methods/{name}:run", response_model=Result, responses={202: {"description": "still running"}})
+    async def method_run(name: str, req: MethodRunRequest, creds: Creds, caller: Caller, request: Request,
+                         wait: float | None = None):
+        """Ad-hoc Method run, stored as a single-step Run owned by the caller. Answers the Result when it
+        finishes within `wait` seconds, else 202 {run_id, poll} — then poll GET /runs/{run_id}/result."""
+        bindings = invocation_inputs(registry.get(name, req.method_version).manifest, bindings=req.bindings,
+                                     measures=req.measures, dimensions=req.dimensions, entity=req.entity)
+        scope = req.scope.as_dict()
+        scope["filters"] = [*(scope.get("filters") or []), *[item.model_dump(mode="json") for item in req.filters]]
+        run, result = await engine.adhoc(creds, caller, PlanStep(method=name, method_version=req.method_version, bindings=bindings, params=req.params),
+                                         scope, wait=waited(settings, wait), origin=run_origin(request), question=req.question, author=req.author)
+        return result if result is not None else accepted(run)
+
+    return router

decision_layer/api/recipes.py

@@ -0,0 +1,128 @@
+"""Recipes HTTP routes; analytical work stays in the canonical engine."""
+from __future__ import annotations
+import yaml
+from fastapi import Query, Request
+from fastapi.responses import JSONResponse, Response
+from ..i18n import _
+from ..core.models import Recipe, Run
+from ..recipes.loader import parse_recipe
+from ..service import RecipeSearchRequest, RecipeConfigureRequest, RecipePreviewRequest, RecipePublishRequest, RecipeSaveRequest, RecipeYamlRequest
+from ..i18n import _
+from fastapi import APIRouter
+from .dependencies import Caller, Creds, run_origin, waited, require_recipe_permission
+
+from ..recipes.authoring import check_recipe_semantics
+
+def create_router(settings, provider, recipes, engine):
+    registry = engine.registry
+    router = APIRouter()
+    @router.get("/recipes", response_model=list[Recipe])
+    async def recipes_list(_caller: Caller) -> list[Recipe]:
+        return recipes.list()
+
+    @router.post("/recipes:search")
+    async def recipe_search(req: RecipeSearchRequest, creds: Creds, caller: Caller):
+        from ..recipes.routing import search_recipes
+        return await search_recipes(recipes, provider, creds, req.question, req.goals, req.inputs, req.limit)
+
+    @router.get("/recipes:drafts", response_model=list[Recipe])
+    async def recipe_drafts(_caller: Caller) -> list[Recipe]:
+        require_recipe_permission(settings, _caller)
+        return recipes.list_drafts()
+
+    @router.post("/recipes:configure-step", response_model=Recipe)
+    async def configure_recipe_step(req: RecipeConfigureRequest, caller: Caller, creds: Creds):
+        from ..recipes.configuration import configure_step
+        from ..recipes.authoring import RecipeEditError
+        try:
+            catalog = None
+            if 0 <= req.step_index < len(req.recipe.steps):
+                manifest = registry.get(req.recipe.steps[req.step_index].method).manifest
+                if any(role.default_binding == "unit_count" for role in manifest.roles.values()):
+                    catalog = await provider.discover(creds)
+            recipe = configure_step(req.recipe, req.step_index, req.reset_parameters, catalog=catalog, registry=registry)
+            for spec in recipe.inputs.values():
+                spec.label = _(spec.label)
+            return recipe
+        except (ValueError, KeyError) as exc:
+            raise RecipeEditError(str(exc), field="steps") from exc
+
+    @router.post("/recipes:format")
+    async def recipe_format(recipe: Recipe, _caller: Caller) -> dict[str, str]:
+        recipes.validate(recipe)
+        return {"yaml": yaml.safe_dump(recipe.model_dump(mode="json"), allow_unicode=True, sort_keys=False)}
+
+    @router.post("/recipes:parse", response_model=Recipe)
+    async def recipe_parse(req: RecipeYamlRequest, _caller: Caller) -> Recipe:
+        from ..recipes.authoring import RecipeEditError
+
+        try:
+            document = yaml.safe_load(req.yaml)
+            if not isinstance(document, dict):
+                raise RecipeEditError(_("Recipe YAML must be a mapping."))
+            parsed = parse_recipe(document, provider.name, provider.instance)
+        except yaml.YAMLError as error:
+            raise RecipeEditError(_("Recipe YAML syntax is invalid: {error}", error=error)) from error
+        except ValueError as error:
+            raise RecipeEditError(_("Recipe YAML structure is invalid: {error}", error=error)) from error
+        recipes.validate(parsed)
+        return parsed
+
+    @router.post("/recipes:validate")
+    async def recipe_validate(recipe: Recipe, _caller: Caller, creds: Creds, live: bool = False) -> dict[str, bool]:
+        """Validate the shared static contract and, optionally, caller-visible semantic references."""
+        recipes.validate(recipe)
+        if live:
+            await check_recipe_semantics(recipe, provider, creds)
+        return {"valid": True, "semantic_checked": live}
+
+    @router.post("/recipes:preview", response_model=Run, responses={202: {"description": "preview still running"}})
+    async def recipe_preview(req: RecipePreviewRequest, creds: Creds, caller: Caller, request: Request, wait: float | None = None):
+        """Execute an unsaved pipeline prefix with normal validation, access and query limits."""
+        recipes.validate(req.recipe)
+        run = await engine.preview(creds, caller, req.recipe, req.step_index, req.scope.as_dict(), wait=waited(settings, wait), origin=run_origin(request))
+        return JSONResponse(status_code=202, content=run.model_dump(mode="json")) if run.running else run
+
+    @router.get("/recipes/{name}/edit", response_model=Recipe)
+    async def recipe_edit(name: str, _caller: Caller) -> Recipe:
+        require_recipe_permission(settings, _caller)
+        return recipes.get(name, include_drafts=True)
+
+    @router.post("/recipes/{name}/publish", response_model=Recipe)
+    async def recipe_publish(name: str, req: RecipePublishRequest, _caller: Caller, creds: Creds) -> Recipe:
+        require_recipe_permission(settings, _caller, publish=True)
+        draft = recipes.get(name, req.base_version, include_drafts=True)
+        recipes.validate(draft)
+        await check_recipe_semantics(draft, provider, creds)
+        return recipes.publish(name, req.base_version, actor=_caller.subject)
+
+    @router.get("/recipes/{name}/reuse")
+    async def recipe_reuse(name: str, _caller: Caller):
+        from ..recipes.routing import reuse_contract
+        return reuse_contract(recipes.get(name), registry=registry)
+
+    @router.get("/recipes/{name}", response_model=Recipe)
+    async def recipe_get(name: str, _caller: Caller) -> Recipe:
+        return recipes.get(name)
+
+    @router.put("/recipes/{name}", response_model=Recipe)
+    async def recipe_save(name: str, req: RecipeSaveRequest, _caller: Caller) -> Recipe:
+        require_recipe_permission(settings, _caller, publish=req.recipe.status == "published")
+        from ..recipes.authoring import RecipeEditError
+
+        if req.recipe.name != name:
+            raise RecipeEditError("Recipe name must match the URL.")
+        return recipes.save(req.recipe, req.base_version, actor=_caller.subject)
+
+    @router.delete("/recipes/{name}", status_code=204)
+    async def recipe_delete(name: str, _caller: Caller, base_version: str = Query(...)) -> Response:
+        require_recipe_permission(settings, _caller, publish=True)
+        recipes.delete(name, base_version, actor=_caller.subject)
+        return Response(status_code=204)
+
+    @router.post("/recipes/{name}/restore", response_model=Recipe)
+    async def recipe_restore(name: str, req: RecipePublishRequest, caller: Caller) -> Recipe:
+        require_recipe_permission(settings, caller, publish=True)
+        return recipes.restore(name, req.base_version, actor=caller.subject)
+
+    return router

decision_layer/api/runs.py

@@ -0,0 +1,173 @@
+"""Runs HTTP routes; analytical work stays in the canonical engine."""
+from __future__ import annotations
+from ..runs.skills import SkillQueryRequest, SkillFinishRequest
+from fastapi import Query, Request
+from fastapi.responses import JSONResponse, Response
+from ..i18n import _
+from ..core.models import PlanStep, Recipe, Result, Run
+from ..methods.invocation import invocation_inputs
+from ..recipes.from_run import RecipeCandidate, RunPromotionError, candidate_from_run, runtime_recipe_from_run
+from ..service import MethodProposalRequest, RunCompleteRequest, RunRecipeRequest, RunScopeRequest, RunShareRequest, RunStartRequest, RunStepRequest, RunUseRecipeRequest
+from ..service import BlockedAnalysisRequest, RemediationCreateRequest, RemediationReviewRequest, RemediationCheckRequest, RemediationRetryRequest
+from ..runs import remediation
+from ..i18n import _
+from fastapi import APIRouter
+from .dependencies import Caller, Creds, JobFailed, NoResult, accepted, run_origin, waited, require_recipe_permission
+
+from ..recipes.authoring import check_recipe_semantics
+
+def create_router(settings, provider, recipes, engine):
+    registry = engine.registry
+    router = APIRouter()
+    @router.post("/runs", response_model=Run, responses={202: {"description": "pipeline still running"}})
+    async def run_start(req: RunStartRequest, creds: Creds, caller: Caller, request: Request, wait: float | None = None):
+        """Start a Run. A pipeline Recipe executes right away (202 with the run while it is still running);
+        an investigation Recipe waits for steps."""
+        run = await engine.start(creds, caller, recipe=req.recipe, question=req.question, scope=req.scope.as_dict(),
+                                 wait=waited(settings, wait), origin=run_origin(request), author=req.author,
+                                 goals=req.goals, recipe_selection=req.recipe_selection,
+                                 recipe_review=req.recipe_review, interactive=req.interactive, guide=req.guide)
+        return JSONResponse(status_code=202, content=run.model_dump(mode="json")) if run.running else run
+
+    @router.get("/runs", response_model=list[Run])
+    async def runs_list(caller: Caller, limit: int = 50, recipe: str | None = None) -> list[Run]:
+        """The caller's own runs, newest first."""
+        return await engine.list(caller, limit, recipe)
+
+    @router.post("/analyses:blocked", response_model=Run)
+    async def analysis_blocked(req: BlockedAnalysisRequest, caller: Caller, request: Request):
+        """Record an unanswered question and proposed improvements, without executing a query."""
+        return await remediation.record_blocked(engine, caller, req, run_origin(request))
+
+    @router.post("/runs/{run_id}/method-proposal")
+    async def run_method_proposal(run_id: str, req: MethodProposalRequest, caller: Caller):
+        from ..runs.proposals import method_proposal
+        run = await engine._owned(run_id, caller)
+        return method_proposal(run, req, settings.issue_repository)
+
+    @router.post("/runs/{run_id}:use-recipe", response_model=Run)
+    async def run_use_recipe(run_id: str, req: RunUseRecipeRequest, creds: Creds, caller: Caller, wait: float | None = None):
+        run = await engine.use_recipe(creds, caller, run_id, req.recipe, req.selection, req.inputs, waited(settings, wait))
+        return JSONResponse(status_code=202, content=run.model_dump(mode="json")) if run.running else run
+
+    @router.get("/runs/{run_id}/recipe-candidate", response_model=RecipeCandidate)
+    async def run_recipe_candidate(run_id: str, creds: Creds, caller: Caller, indices: list[int] = Query(...)) -> RecipeCandidate:
+        run = await engine._owned(run_id, caller)
+        require_recipe_permission(settings, caller)
+        candidate = candidate_from_run(run, indices, registry=registry)
+        await check_recipe_semantics(candidate.recipe, provider, creds)
+        return candidate
+
+    @router.post("/runs/{run_id}/recipe", response_model=Recipe)
+    async def run_recipe_register(run_id: str, creds: Creds, caller: Caller, body: RunRecipeRequest = RunRecipeRequest()) -> Recipe:
+        run = await engine._owned(run_id, caller)
+        require_recipe_permission(settings, caller, publish=body.reviewed)
+        if body.reviewed and body.recipe is None:
+            raise RunPromotionError("Submit the reviewed Recipe explicitly before publication.")
+        if run.status != "completed" or run.running:
+            raise RunPromotionError("Complete the analysis before registering its procedure.")
+        from ..recipes.loader import UnknownRecipe
+        name = f"analysis-from-{run.id.lower()}"
+        if body.recipe is None:
+            try:
+                existing = recipes.get(name, include_drafts=True)
+            except UnknownRecipe:
+                existing = None
+            if existing and existing.origin_runs == [run.id]:
+                await check_recipe_semantics(existing, provider, creds)
+                return existing
+        recipe = (body.recipe or runtime_recipe_from_run(run, registry=registry)).model_copy(update={
+            "name": name, "origin_runs": [run.id], "status": "published" if body.reviewed else "draft"})
+        from ..recipes.authoring import validate_recipe
+        validate_recipe(recipe, registry=registry)
+        for step in recipe.steps:
+            if step.method_version and registry.get(step.method, step.method_version).manifest.version != step.method_version:
+                raise RunPromotionError("The recorded Method version is not installed. Edit the candidate before registering it.")
+        await check_recipe_semantics(recipe, provider, creds)
+        # A repeated click returns the same version instead of making another Recipe.
+        from ..recipes.loader import UnknownRecipe
+        try:
+            existing = recipes.get(recipe.name, include_drafts=True)
+        except UnknownRecipe:
+            return recipes.save(recipe, None, actor=caller.subject)
+        if existing.origin_runs != [run.id]:
+            from ..recipes.authoring import RecipeConflict
+            raise RecipeConflict("A different Recipe already uses this name.")
+        if existing.model_dump() != recipe.model_dump():
+            from ..recipes.authoring import RecipeConflict
+            raise RecipeConflict("This Run already has a different Recipe. Save changes as a new version in the editor.")
+        return existing
+
+    @router.get("/runs/{run_id}", response_model=Run)
+    async def run_get(run_id: str, creds: Creds, caller: Caller) -> Run:
+        return await engine.get(creds, caller, run_id)
+
+    @router.post("/runs/{run_id}/remediations", response_model=Run)
+    async def remediation_create(run_id: str, req: RemediationCreateRequest, caller: Caller):
+        return await remediation.create(engine, caller, run_id, req)
+
+    @router.put("/runs/{run_id}/remediations/{item_id}", response_model=Run)
+    async def remediation_review(run_id: str, item_id: str, req: RemediationReviewRequest, caller: Caller):
+        return await remediation.review(engine, caller, run_id, item_id, req)
+
+    @router.post("/runs/{run_id}/remediations/{item_id}:check", response_model=Run)
+    async def remediation_check(run_id: str, item_id: str, req: RemediationCheckRequest, creds: Creds, caller: Caller):
+        return await remediation.recheck(engine, creds, caller, run_id, item_id, req)
+
+    @router.post("/runs/{run_id}/remediations/{item_id}:retry", response_model=Run)
+    async def remediation_retry(run_id: str, item_id: str, req: RemediationRetryRequest, creds: Creds,
+                                caller: Caller, request: Request, wait: float | None = None):
+        run = await remediation.retry(engine, creds, caller, run_id, item_id, req, run_origin(request), waited(settings, wait))
+        return JSONResponse(status_code=202, content=run.model_dump(mode="json")) if run.running else run
+
+    @router.put("/runs/{run_id}/scope", response_model=Run)
+    async def run_scope(run_id: str, req: RunScopeRequest, creds: Creds, caller: Caller, wait: float | None = None):
+        run = await engine.set_scope(creds, caller, run_id, req.scope.as_dict(), req.base_revision, waited(settings, wait))
+        return JSONResponse(status_code=202, content=run.model_dump(mode="json")) if run.running else run
+
+    @router.delete("/runs/{run_id}", status_code=204)
+    async def run_delete(run_id: str, caller: Caller) -> Response:
+        await engine.delete(caller, run_id)
+        return Response(status_code=204)
+
+    @router.get("/runs/{run_id}/result", response_model=Result, responses={202: {"description": "still running"}})
+    async def run_result(run_id: str, creds: Creds, caller: Caller):
+        """The latest step's Result — 202 while a job runs, the recorded error if the job failed."""
+        run = await engine.get(creds, caller, run_id)
+        if run.running:
+            return accepted(run)
+        if run.error:
+            raise JobFailed(run.error)
+        if run.needs_input:
+            return Result(status="needs_input", run_id=run.id, needs_input={**run.needs_input, "scope_revision": run.scope_revision})
+        if not run.steps:
+            raise NoResult(_("No step has run yet"), run_id=run_id)
+        return run.steps[-1].result
+
+    @router.post("/runs/{run_id}/steps", response_model=Result, responses={202: {"description": "still running"}})
+    async def run_step(run_id: str, req: RunStepRequest, creds: Creds, caller: Caller, wait: float | None = None):
+        values = req.model_dump(exclude={"author", "measures", "dimensions", "entity"})
+        maps = {"measures": req.measures, "dimensions": req.dimensions, "entity": req.entity} if req.measures or req.dimensions or req.entity else None
+        run, result = await engine.step(creds, caller, run_id, PlanStep(**values), wait=waited(settings, wait), author=req.author, input_maps=maps)
+        return result if result is not None else accepted(run)
+
+    @router.post("/runs/{run_id}/steps/{step_id}/queries")
+    async def skill_query(run_id: str, step_id: str, req: SkillQueryRequest, creds: Creds, caller: Caller, wait: float | None = None):
+        run, query = await engine.skill_query(creds, caller, run_id, step_id, req, wait=waited(settings, wait))
+        return query if query is not None else accepted(run)
+
+    @router.post("/runs/{run_id}/steps/{step_id}:finish", response_model=Run)
+    async def finish_skill(run_id: str, step_id: str, req: SkillFinishRequest, creds: Creds, caller: Caller, wait: float | None = None):
+        run = await engine.finish_skill(creds, caller, run_id, step_id, req, wait=waited(settings, wait))
+        return JSONResponse(status_code=202, content=run.model_dump(mode="json")) if run.running else run
+
+    @router.post("/runs/{run_id}:complete", response_model=Run)
+    async def run_complete(run_id: str, req: RunCompleteRequest, caller: Caller) -> Run:
+        return await engine.complete(caller, run_id, req.summary, req.conclusion, req.author)
+
+    @router.post("/runs/{run_id}:share", response_model=Run)
+    async def run_share(run_id: str, req: RunShareRequest, caller: Caller) -> Run:
+        """Owner only. Replaces the read-only share list; "*" = any authenticated caller."""
+        return await engine.share(caller, run_id, req.subjects)
+
+    return router