Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 31 additions & 4 deletions arbora/deployment/production_ops.py
Original file line number Diff line number Diff line change
Expand Up @@ -414,14 +414,25 @@ async def _provision_semantic_content(served_url: str) -> dict[str, Any]:


async def _onboard_fleet(
served_url: str, allow_mass_withdrawal: frozenset[str] = frozenset()
served_url: str,
allow_mass_withdrawal: frozenset[str] = frozenset(),
*,
sandbox: bool = False,
) -> dict[str, Any]:
"""Run one full fleet onboarding pass under Arbora's process session.

``allow_mass_withdrawal`` names the servers whose import the operator
approved to withdraw more than half of the published pack surface.
``sandbox`` selects the declared sandbox fleet profile: only its
connectors are onboarded, and only their failures (or a shared
infrastructure failure) fail the run (ARBORA-FLEET-R085, R085.1).
"""

from arbora.deployment.sandbox_fleet import (
load_sandbox_profile,
onboarding_ok,
select_endpoints,
)
from arbora.fleet.declarations import Declarations
from arbora.fleet.onboarding import (
FleetOnboarding,
Expand All @@ -434,6 +445,10 @@ async def _onboard_fleet(
from arbora.security.actor_context import use_actor
from arbora.security.session import use_session

profile = load_sandbox_profile() if sandbox else None
endpoints = configured_fleet_endpoints(exclude=self_served_connectors())
if profile is not None:
endpoints = select_endpoints(endpoints, profile)
session = runtime._mint_process_session("http")
with use_actor(session.actor), use_session(session):
engine = runtime._get_engine()
Expand All @@ -448,13 +463,13 @@ async def _onboard_fleet(
action_policies=ActionPolicies(),
allow_mass_withdrawal=allow_mass_withdrawal,
),
configured_fleet_endpoints(exclude=self_served_connectors()),
endpoints,
served_url=served_url,
)
# Failure detail can name endpoints; the CLI prints only each error type.
return {
"operation": "onboard-fleet",
"ok": not report.failed,
"ok": onboarding_ok(report.failed, profile),
**report.as_dict(private=True),
}

Expand Down Expand Up @@ -580,6 +595,14 @@ def _parser() -> argparse.ArgumentParser:
" half of the published surface (repeatable, or comma-separated)."
),
)
onboard.add_argument(
"--sandbox",
action="store_true",
help=(
"Onboard only the declared sandbox fleet profile; only its failures"
" fail the run."
),
)
_served_url_argument(
subparsers.add_parser(
"check-fleet-coverage",
Expand Down Expand Up @@ -608,7 +631,11 @@ def _provision(args: argparse.Namespace) -> dict[str, Any]:
),
"provision-semantic-content": _provision,
"onboard-fleet": lambda args: asyncio.run(
_onboard_fleet(args.served_url, _server_names(args.allow_mass_withdrawal))
_onboard_fleet(
args.served_url,
_server_names(args.allow_mass_withdrawal),
sandbox=args.sandbox,
)
),
"check-fleet-coverage": lambda args: asyncio.run(_check_fleet_coverage()),
}
Expand Down
4 changes: 4 additions & 0 deletions arbora/deployment/sandbox_fleet.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"version": 1,
"connectors": ["sql-mcp", "vector-mcp", "audio-transcriber-mcp"]
}
77 changes: 77 additions & 0 deletions arbora/deployment/sandbox_fleet.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
"""The sandbox fleet profile: a closed, declared set of local connectors.

The profile applies only when the operator selects the sandbox
(ARBORA-FLEET-R085). It is read-only data in one declarative file. A
connector name is data here, never a branch in code. The fixture-serving
mode that makes each connector run without credentials belongs to the
connector SDK; this module implements none of it.
"""

import json
from collections.abc import Collection, Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Any

PROFILE_PATH = Path(__file__).with_name("sandbox_fleet.json")
PROFILE_VERSION = 1

#: Failure keys the onboarding pass uses for shared infrastructure, not for one
#: connector. They always fail the run, in every mode.
INFRASTRUCTURE_KEYS = frozenset({"child-auth", "registry"})


class SandboxProfileError(ValueError):
"""The profile file is missing, malformed or not the supported version."""


@dataclass(frozen=True, slots=True)
class SandboxFleetProfile:
"""The closed set of connectors the sandbox declares."""

connectors: frozenset[str]


def load_sandbox_profile(path: Path | None = None) -> SandboxFleetProfile:
"""Read and validate the profile; a malformed file refuses, never defaults."""
target = path or PROFILE_PATH
try:
raw: Any = json.loads(target.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise SandboxProfileError("sandbox fleet profile unreadable") from exc
if not isinstance(raw, dict) or raw.get("version") != PROFILE_VERSION:
raise SandboxProfileError("sandbox fleet profile version unsupported")
names = raw.get("connectors")
if (
not isinstance(names, list)
or not names
or not all(isinstance(n, str) and n for n in names)
or len(set(names)) != len(names)
):
raise SandboxProfileError("sandbox fleet profile needs a closed name list")
return SandboxFleetProfile(connectors=frozenset(names))


def select_endpoints[T](
endpoints: Collection[T], profile: SandboxFleetProfile
) -> tuple[T, ...]:
"""Keep only the declared connectors, in the order given."""
return tuple(e for e in endpoints if getattr(e, "name", None) in profile.connectors)


def sandbox_ok(failed: Mapping[str, str], profile: SandboxFleetProfile) -> bool:
"""True when no declared connector and no shared infrastructure step failed.

A failure outside the declared set stays in the report and does not fail
the run (ARBORA-FLEET-R085.1).
"""
return not any(
name in profile.connectors or name in INFRASTRUCTURE_KEYS for name in failed
)


def onboarding_ok(
failed: Mapping[str, str], profile: SandboxFleetProfile | None
) -> bool:
"""The one exit rule: any failure fails a production run; a sandbox run follows the profile."""
return not failed if profile is None else sandbox_ok(failed, profile)
4 changes: 2 additions & 2 deletions specs/fleet-catalog-and-tools/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -317,8 +317,8 @@ Live agent browser requests must carry host-bound agent/run provenance for the l
| `ARBORA-FLEET-R083.4` | **Delete the other scorers.** Stage: removal. Delete `_cosine`, `_lexical_score`, `_relevance`, `LexicalRanker` (moved into the floor) and every other function that scores a tool, skill, action or operation by overlap, rarity or cosine. A repository scan finds no function named `*score*`, `*rank*` or `*relevance*` in `fleet`, `api/mcp` and `mcp_server/backing` outside `lexical_floor.py` and `ranking.py`. Caller chain: none. Shape: deletions and one scan test. Depends: ARBORA-FLEET-R083.2, ARBORA-FLEET-R083.3. | Test: `tests/architecture/test_single_ranking_floor.py::test_no_scoring_function_exists_outside_the_floor` (L2). |
| `ARBORA-FLEET-R083.5` | **Ranking served proof and degradation evidence.** Stage: proof. With a loopback medulla engine that serves the four `Rank` catalog entries, `find` returns the engine's order. With the engine stopped, `find` returns the floor order and the response carries `ranking: "floor"` and the reason `decision_unavailable`. A call never fails because the ranking is unavailable. Evidence: a metric `arbora_ranking_total{source=medulla|floor}`. Caller chain: `find` -> `discover_tools` -> `MedullaRanking`. Shape: one served test and one counter in `observability`. Depends: ARBORA-FLEET-R083.3, MEDULLA-DECISION-ENGINE-R829.1. | Test: `tests/fleet/test_ranking_served.py::test_find_uses_the_engine_order_and_degrades_to_the_floor` (L3). |
| `ARBORA-FLEET-R084` | **The fleet serves the city layout read.** Subsystem: fleet catalog. Entry: the served `ask` operation `fleet.city.layout` (effect `READ`, scope `fleet:read`). arbora serves the spatial layout of the fleet tenant from the Medulla world view: districts, buildings, rooms, streets, the relations `locatedIn`, `position` and `hasInterior`, and the active manual overrides. arbora invokes the engine's one spatial query method as the bound actor (`MEDULLA-WORLD-VIEW-R003`) and serves its stable envelope; it adds no placement logic and no second registry. A connector added to the catalog appears in the layout on the next read without a write, and a stored override for a removed connector is reported stale, never applied. Refusals: `UNAVAILABLE` when the engine world view is not bound; the engine's typed unknown-tenant and unknown-layout refusals are preserved in arbora's closed error enum. Writes: none. Caller chain: `arbora/api/http/app.py:208` -> `arbora/api/http/routes.py:122` -> `arbora/api/invoke/pipeline.py:1021` -> (planned) `arbora/api/ops/fleet_city.py::handle_city_layout` -> the engine spatial query; over MCP, `arbora/api/mcp/serving.py:29` -> `arbora/api/mcp/verbs.py` (`ask`) -> the same handler. Shape: one handler that builds the params and maps the engine envelope into the result model; no new store. Depends on: `MEDULLA-WORLD-VIEW-R003`. | Test: `tests/fleet/test_city_layout_served.py::test_city_layout_serves_the_engine_envelope_and_refuses_unbound` (L3) planned in `test-spec.md`. |
| `ARBORA-FLEET-R085` | **A sandbox fleet profile fills the catalog without external credentials (rollup).** Subsystem: fleet catalog, sandbox profile. Caller chain: `arbora-sandbox up` (`ARBORA-DEPLOY-R019`) -> `arbora-production-ops onboard-fleet` (`arbora/deployment/production_ops.py::_onboard_fleet`) -> `configured_fleet_endpoints` -> `FleetOnboarding.onboard`. Rule: a sandbox fleet profile declares a closed set of connectors. Each runs locally, needs no external credential, and serves from self-contained fixture data. The profile lives in one declarative file in the arbora package. The sandbox start reads it and nothing else decides the set. After onboarding, `fleet.catalog.list` must return those connectors and their tools, in addition to the 45 items that Arbora serves itself (29 prompts, 15 skills, 1 resource). The profile applies only when the operator selects the sandbox. A production profile ignores it. Arbora implements no fixture mode. It consumes the connector fixture-serving mode of the connector SDK. Depends: `SCION-CONNECTOR-CONTROL-R931` (the explicit fixture serving mode). This row builds on the existing fleet onboarding rollup. Shape: `arbora/deployment/sandbox_fleet.py` (planned) holds the typed profile loader; `production_ops.py::_onboard_fleet` takes the endpoint set from it when the sandbox is active. | Test: `tests/fleet/test_sandbox_fleet_served.py::test_catalog_list_returns_sandbox_connectors_and_tools` (planned, L3). It starts the sandbox, runs `onboard-fleet` and asserts `fleet.catalog.list` returns each declared connector with at least one tool. It asserts no external network call and no credential read. |
| `ARBORA-FLEET-R085.1` | **`onboard-fleet` reports each connector and exits non-zero only for the declared set.** Subsystem: fleet onboarding, operator command. Caller chain: `arbora-production-ops onboard-fleet` -> `_onboard_fleet` (`arbora/deployment/production_ops.py:416`) -> `_exit_status`. Rule: the report lists one entry per connector with its state, error type and message. Today `ok` is false when any connector fails. In sandbox mode, `ok` is false only when a connector of the declared sandbox set fails. A failure outside that set appears in the report and leaves the exit code at zero. Outside sandbox mode, behavior stays as it is. A failed connector never hides the others. Refusals: the report names the failing connector, its error type and a bounded message. It never prints a secret or an endpoint credential. Writes: none beyond onboarding. Depends: none in this repository. This row extends the existing onboarding refusal behavior. Shape: extend `report.as_dict` consumers and the `ok` computation in `_onboard_fleet`; no new command. | Test: `tests/fleet/test_onboard_fleet_report.py::test_exit_status_follows_the_declared_sandbox_set` (planned, L2). It fails one declared and one undeclared connector in turn. It asserts the exit code, the per-connector entries and that production mode keeps its current exit rule. |
| `ARBORA-FLEET-R085` | **A sandbox fleet profile fills the catalog without external credentials (rollup).** Subsystem: fleet catalog, sandbox profile. Caller chain: `arbora-sandbox up` (`ARBORA-DEPLOY-R019`) -> `arbora-production-ops onboard-fleet` (`arbora/deployment/production_ops.py::_onboard_fleet`) -> `configured_fleet_endpoints` -> `FleetOnboarding.onboard`. Rule: a sandbox fleet profile declares a closed set of connectors. Each runs locally, needs no external credential, and serves from self-contained fixture data. The profile lives in one declarative file in the arbora package. The sandbox start reads it and nothing else decides the set. After onboarding, `fleet.catalog.list` must return those connectors and their tools, in addition to the 45 items that Arbora serves itself (29 prompts, 15 skills, 1 resource). The profile applies only when the operator selects the sandbox. A production profile ignores it. Arbora implements no fixture mode. It consumes the connector fixture-serving mode of the connector SDK. Depends: `SCION-CONNECTOR-CONTROL-R931` (the explicit fixture serving mode). This row builds on the existing fleet onboarding rollup. Shape: `arbora/deployment/sandbox_fleet.py` holds the typed profile loader and the exit rule (landed with R085.1); `production_ops.py::_onboard_fleet` takes the endpoint set from it when `--sandbox` is passed. The profile file is `arbora/deployment/sandbox_fleet.json`. The rollup stays planned until the connector SDK's fixture mode and the `arbora-sandbox` command land. | Test: `tests/fleet/test_sandbox_fleet_served.py::test_catalog_list_returns_sandbox_connectors_and_tools` (planned, L3). It starts the sandbox, runs `onboard-fleet` and asserts `fleet.catalog.list` returns each declared connector with at least one tool. It asserts no external network call and no credential read. |
| `ARBORA-FLEET-R085.1` | **`onboard-fleet` reports each connector and exits non-zero only for the declared set.** Subsystem: fleet onboarding, operator command. Caller chain: `arbora-production-ops onboard-fleet` -> `_onboard_fleet` (`arbora/deployment/production_ops.py:416`) -> `_exit_status`. Rule: the report lists one entry per connector with its state, error type and message. Today `ok` is false when any connector fails. In sandbox mode, `ok` is false only when a connector of the declared sandbox set fails. A failure outside that set appears in the report and leaves the exit code at zero. Outside sandbox mode, behavior stays as it is. A failed connector never hides the others. Refusals: the report names the failing connector, its error type and a bounded message. It never prints a secret or an endpoint credential. Writes: none beyond onboarding. Depends: none in this repository. This row extends the existing onboarding refusal behavior. Shape: extend `report.as_dict` consumers and the `ok` computation in `_onboard_fleet`; no new command. | Test: `tests/fleet/test_onboard_fleet_report.py::test_exit_status_follows_the_declared_sandbox_set` (L2). It fails one declared and one undeclared connector in turn. It asserts the exit code, the per-connector entries and that production mode keeps its current exit rule. |
| `ARBORA-FLEET-R086` | **The fleet serves graph neighbourhoods as city chunks.** Subsystem: fleet catalog. Entry: the served `ask` operation `fleet.city.chunk` (effect `READ`, scope `fleet:read`). arbora forwards the tenant, a cell range or anchor node and an opaque cursor to the engine world-view chunk read as the bound actor, and serves the bounded chunk envelope unchanged, with each element's provenance. It adds no placement logic and no second registry. Any cache is keyed by the verified principal and tenant. Refusals: `UNAVAILABLE` when the engine world view is not bound; the engine's typed unknown-tenant and unknown-range refusals are preserved in arbora's closed error enum. Writes: none. Caller chain: `arbora/api/http/app.py:208` -> `arbora/api/http/routes.py:122` -> `arbora/api/invoke/pipeline.py:1021` -> (planned) `arbora/api/ops/fleet_city.py::handle_city_chunk` -> the engine chunk read. Shape: one handler beside `handle_city_layout`. Depends on: `ARBORA-FLEET-R084`, `MEDULLA-WORLD-VIEW-R007`. | Test: `tests/fleet/test_city_chunk_served.py::test_chunk_read_serves_the_engine_envelope_and_refuses_unbound` (planned, L3). |
| `ARBORA-FLEET-R087` | **The fleet serves the city edit layer.** Subsystem: fleet catalog. Entry: the served operations `fleet.city.edit_layer.get` (effect `READ`, scope `fleet:read`) and `fleet.city.edit_layer.put` (effect `WRITE`, scope `fleet:write`). The write previews first and runs through the standard plan flow. The engine validates it (collisions, stale edits) and records the verified actor. A refusal carries the engine's typed reason. A read returns the layer version. arbora stores nothing. Refusals: `UNAVAILABLE` when the engine world view is not bound; `PIN_COLLISION` and `STALE_EDIT` as the engine reports them. Writes: one edit-layer version in the engine. Caller chain: `arbora/api/http/routes.py:122` -> `arbora/api/invoke/pipeline.py:1021` -> (planned) `arbora/api/ops/fleet_city.py::handle_edit_layer_get` and `handle_edit_layer_put`. Shape: two handlers that map the engine envelope into result models. Depends on: `ARBORA-FLEET-R084`, `MEDULLA-WORLD-VIEW-R006`. | Test: `tests/fleet/test_city_edit_layer_served.py::test_edit_layer_round_trips_with_actor_and_refuses_collisions` (planned, L3). |
| `ARBORA-FLEET-R088` | **The fleet serves the city mapping registry, growth rules and seed.** Subsystem: fleet catalog. Entry: the served `ask` operation `fleet.city.rules` (effect `READ`, scope `fleet:read`). arbora reads the tenant's class-to-archetype registry, the declared growth rules and the seed from the engine world view and serves them, so a client can evaluate the pure mapping and growth. arbora hard-codes none of them. Refusals: `UNAVAILABLE` when the engine world view is not bound. Writes: none. Caller chain: `arbora/api/invoke/pipeline.py:1021` -> (planned) `arbora/api/ops/fleet_city.py::handle_city_rules` -> the engine spatial query. Shape: one handler. Depends on: `ARBORA-FLEET-R084`, `MEDULLA-WORLD-VIEW-R004`, `MEDULLA-WORLD-VIEW-R005`. | Test: `tests/fleet/test_city_rules_served.py::test_rules_serve_registry_growth_and_seed_from_the_engine` (planned, L3). |
2 changes: 1 addition & 1 deletion specs/fleet-catalog-and-tools/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -539,7 +539,7 @@ The WebUI bridge is configured by the host and discovered through the existing p
- [ ] T271 [US1] ARBORA-FLEET-R015.6 A connector's destructive declaration decides at the door; no argument lifts the plan requirement. Size: XS, 1 PR, 1 hour.
- [ ] T272 [US1] ARBORA-FLEET-R084 The fleet serves the city layout read from the engine world view. Size: S, 1 PR, 2 hours.
- [ ] T273 [US1] ARBORA-FLEET-R085 A sandbox fleet profile fills the catalog without external credentials (rollup). Size: L, 2 PRs, 1 day.
- [ ] T274 [US1] ARBORA-FLEET-R085.1 The fleet onboarding command reports each connector and exits non-zero only for the declared set. Size: S, 1 PR, 2 hours.
- [x] T274 [US1] ARBORA-FLEET-R085.1 The fleet onboarding command reports each connector and exits non-zero only for the declared set. Size: S, 1 PR, 2 hours.
- [ ] T275 [US1] ARBORA-FLEET-R086 The fleet serves graph neighbourhoods as city chunks. Size: S, 1 PR, 2 hours.
- [ ] T276 [US1] ARBORA-FLEET-R087 The fleet serves the city edit layer. Size: S, 1 PR, 2 hours.
- [ ] T277 [US1] ARBORA-FLEET-R088 The fleet serves the city mapping registry, growth rules and seed. Size: S, 1 PR, 2 hours.
Loading
Loading