Skip to content
Draft
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
1 change: 1 addition & 0 deletions specs/fleet-catalog-and-tools/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -316,3 +316,4 @@ Live agent browser requests must carry host-bound agent/run provenance for the l
| `ARBORA-FLEET-R083.3` | **Fleet discovery, catalog items and connector operations ask the port.** Stage: discovery. `MCPMultiplexer.discover_tools` (after the split into `fleet/tool_discovery.py`, `ARBORA-HOST-R038.9`) ranks probed tool and skill rows with `catalog.tool_rank` and `catalog.skill_rank`; the `_cosine` and the ranking block at `multiplexer.py:6515-6575` are deleted because medulla owns the semantic score. `fleet/catalog_items.py::_rank` uses `catalog.catalog_item_rank`. `connector_surface.rank_operations` uses `catalog.operation_rank`. On a fleet of tens of thousands of rows the candidate set is first narrowed by the existing name and description prefilter to at most 2000 candidates before the call (knob `fleet.rank.max_candidates`, starting value 2000), so the request stays bounded. Caller chain: served `find(intent=...)` -> `discover_tools` -> `RankingPort`. Shape: edits in `fleet/tool_discovery.py`, `fleet/catalog_items.py`, `mcp_server/backing/connector_surface.py`. Depends: ARBORA-FLEET-R083.1, ARBORA-HOST-R038.9. | Test: `tests/fleet/test_large_tool_catalogs.py::test_find_ranks_the_named_system_and_object_first_through_the_port` and `tests/fleet/test_large_tool_catalogs.py::test_candidate_set_is_bounded_before_the_port_call` (L2). |
| `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`. |
1 change: 1 addition & 0 deletions specs/fleet-catalog-and-tools/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,7 @@ An operator checks that every registered connector is multiplexed and serves too
- **FR-001**: A caller pins and unpins tools through `manage`, with durable per-principal storage and a separate cap. Rows: `ARBORA-FLEET-R059`.
- **FR-002**: Every registered connector is mounted and serves tools, and a served check names each one that does not. Rows: `ARBORA-FLEET-R060`.
- **FR-003**: A caller loads and unloads the tools of one connector group. Rows: `ARBORA-FLEET-R061`.
- **FR-004**: The fleet serves the city layout read from the engine world view, with no placement logic or second registry in arbora. Rows: `ARBORA-FLEET-R084`.

## Success Criteria

Expand Down
1 change: 1 addition & 0 deletions specs/fleet-catalog-and-tools/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -537,3 +537,4 @@ The WebUI bridge is configured by the host and discovered through the existing p
- [ ] T268 [US1] ARBORA-FLEET-R083.5 Ranking served proof and degradation evidence. Size: S, 1 PR, 3 hours.
- [ ] T269 [US1] ARBORA-FLEET-R015.5 An allowed decision whose audit write failed is refused with that cause. Size: XS, 1 PR, 1 hour.
- [ ] 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.
1 change: 1 addition & 0 deletions specs/fleet-catalog-and-tools/test-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -621,3 +621,4 @@ Each test below is named by its requirement row, has no running implementation y
| PT-182 | ARBORA-FLEET-R083.3 | `tests/fleet/test_large_tool_catalogs.py::test_find_ranks_the_named_system_and_object_first_through_the_port` and `tests/fleet/test_large_tool_catalogs.py::test_candidate_set_is_bounded_before_the_port_call` (L2). | The result the row states holds. | Each refusal the row states is returned. |
| PT-183 | ARBORA-FLEET-R083.4 | `tests/architecture/test_single_ranking_floor.py::test_no_scoring_function_exists_outside_the_floor` (L2). | The result the row states holds. | Each refusal the row states is returned. |
| PT-184 | ARBORA-FLEET-R083.5 | `tests/fleet/test_ranking_served.py::test_find_uses_the_engine_order_and_degrades_to_the_floor` (L3). | The result the row states holds. | Each refusal the row states is returned. |
| PT-186 | ARBORA-FLEET-R084 | `tests/fleet/test_city_layout_served.py::test_city_layout_serves_the_engine_envelope_and_refuses_unbound` (planned) | The result the row states holds. | Each refusal the row states is returned. |
2 changes: 2 additions & 0 deletions specs/hosted-api-operations/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -457,3 +457,5 @@ The following rows retain their original IDs, requirements and verification crit
| `ARBORA-OPS-R912` | **Agent library, prompts and goal operations.** Subsystem: agent library. The tenant Agent Library is in medulla (`ARBORA-DEPLOY-R601` publishes into it). Operations: `agents.library.list|get`: `{id?, kind?: agent|tool|suggestion}` -> `{items[]}`; `agents.library.create|update`: `{item, expected_revision?}` -> `{item, revision}`; `agents.library.delete`: `{id}`; `agents.library.a2a`: `{id}` -> `{agent_card}`; `agents.library.summary` -> `{counts}` (the config summary). `prompts.list|get|create|update`: `{name|id}`; `prompts.versions`: `{id}` -> `{versions[{version_id, created_at, author}]}`; `prompts.rollback`: `{id, version_id}`; `prompts.diff`: `{id, a, b}` -> `{diff}`. Prompt versions are append-only records; rollback writes a new version that copies the old one. `agents.goals.run|list|iterations|cancel`: `{goal_id}`. A goal is a run of `ARBORA-OPS-R042` family and uses the run state machine, not a flag. Scopes `agents:read`, `agents:write`, `prompts:read`, `prompts:write`, `runs:control`. Refusals: `NOT_FOUND`, `REVISION_CONFLICT`, `SCOPE_REQUIRED`. Caller chain: browser -> `invoke` -> `arbora/api/ops/agent_library.py`, `prompts.py`, `goals.py`. Shape: three modules over the library port, the memory port and the run port. Depends: ARBORA-DEPLOY-R601. | Test: `tests/api/test_agent_library_ops.py::test_create_update_delete_with_revision_conflict`, `tests/api/test_prompt_ops.py::test_rollback_appends_a_version_and_diff_matches` and `tests/api/test_goal_ops.py::test_cancel_goal_uses_the_run_machine` (L2). |
| `ARBORA-OPS-R913` | **Fleet management, schedule, maintenance, workflow, code, command and resource operations.** Subsystem: operator operations for the web interface. `fleet.servers.register|update|remove` (`{name, config}`, `Effect.ADMIN`, scope `fleet:admin`, plan confirmation) and `fleet.servers.config.get` (`{name}` -> secrets as references); `fleet.skills.toggle` and `fleet.tools.toggle` (`{id, enabled}`) over the existing pin operations; `schedule.tasks.read`: `{from, to}` -> `{entries[], logs[]}` (calendar and logs, scope `ops:read`); `ops.maintenance.status|run` over `eg.graph.Maintain` (`run` is `Effect.ADMIN`); `ingest.pipeline.status|run` as thin names over `ingest.jobs.list|status` and `ingest.submissions.create`; `workflows.list|create|run`: `{workflow_id, inputs}` -> `{run_id}` served through the business-process connector by `fleet.call`, state in the run machine; `code.context.read`: `{action: nav|instances, symbol?}` -> `{items[]}` over `source.*` and the code index; `commands.execute`: `{command, args}` -> `{result}` and `commands.autocomplete`: `{prefix}` -> `{commands[]}` from the registry of served operations only (a command is an operation id; the host has no second list); `resources.list` and `resources.spawn` over `capacity.throttle.status` and `agents.run`. Scopes `fleet:admin`, `ops:read`, `ops:admin`, `workflows:run`, `code:read`. Caller chain: browser -> `invoke` -> `arbora/api/ops/fleet_admin.py`, `schedule.py`, `workflows.py`, `commands.py`. Shape: four modules; every handler delegates and holds no state. Depends: ARBORA-OPS-R904. | Test: `tests/api/test_fleet_admin_ops.py::test_register_server_needs_plan_confirmation_and_hides_secret_values`, `tests/api/test_command_ops.py::test_commands_are_exactly_the_served_operations` and `tests/api/test_workflow_ops.py::test_run_returns_a_run_id_in_the_run_machine` (L2). |
| `ARBORA-OPS-R914` | **Ecosystem widgets and media transcription.** Subsystem: ecosystem views. `ecosystem.widgets.read`: params `{widget: <a widget name the ecosystem widget registry serves>, params?: object}`; result `{rows[], source, degraded: bool, fetched_at}`; scope `ecosystem:read`. Each widget is a projection class in `arbora/gateway/widgets/` (the package already holds `base.py` and `ollama.py`) that calls its connector through `fleet.call` under the caller's identity and projects rows. `services` reads `fleet.status` and reads `children`, not `servers`. A connector that is down gives `degraded: true` and the cached rows; it does not fail the call. `media.transcribe`: params `{blob_ref|content_base64 (max 25 MiB), language?}`; result `{text, segments[]}`; scope `media:write`; bound to `eg.ingestion.Asr`; the browser uploads the audio as a blob first (`workspace.files.write`) and passes `blob_ref`. Caller chain: browser -> `invoke` -> `handle_widget_read` in `arbora/api/ops/ecosystem.py`. Shape: one op module and one class per widget in the existing package. Depends: ARBORA-OPS-R009. | Test: `tests/api/test_ecosystem_widget_ops.py::test_each_widget_projects_rows_from_its_connector_call`, `tests/api/test_ecosystem_widget_ops.py::test_down_connector_gives_degraded_cached_rows` and `tests/api/test_media_transcribe.py::test_blob_ref_goes_to_asr` (L2). (planned: the named test file does not exist yet) |
| `ARBORA-OPS-R915` | **Agent presence is served on one channel with a bounded update rate.** Stage: served operations. Arbora serves agent presence for the tenant's runs through one served operation: a snapshot read, not a stream of per-frame positions. The snapshot interval is explicit: presence is computed at a fixed interval (`presence.snapshot_interval_s`, default 5) and the read returns the last snapshot with its interval and its computed-at time. The update rate is bounded: a consumer polling faster than the interval receives the same snapshot flagged `fresh: false`, not a new computation. Per-frame movement is never durable: the engine stores run-trace facts, not positions at arbitrary times, and interpolation between snapshots is a presentation concern of the consumer, never an arbora or engine fact. Caller chain: `invoke` -> (planned) `arbora/api/ops/presence.py::handle_presence_snapshot` -> the engine run-trace read (`MEDULLA-ORCH-VOCAB-R803`) mapped into the presence shape; over MCP, the `ask` verb reaches the same handler. Shape: one handler and one result model; no position store. Refusals: `UNAVAILABLE` when the engine is not bound; an unknown run or a foreign tenant is a subject-read refusal per the registry caller chain. Writes: none. Depends on: `MEDULLA-ORCH-VOCAB-R803`. | Test (planned): `tests/api/test_presence_ops_served.py::test_presence_serves_one_snapshot_at_a_bounded_interval` (L3: HTTP and MCP). |
| `ARBORA-OPS-R916` | **The activity stream is served from run-trace provenance.** Stage: served operations. Arbora serves the tenant's agent activity as the engine's run-trace facts, not as a synthesized feed. The stream is a cursor-paged read over run-trace step records (`MEDULLA-ORCH-VOCAB-R803`); each entry carries the run, the step, the request, argument and result digests, and the provenance of the trace. An event the engine has not recorded is not served, and arbora invents no activity. Caller chain: `invoke` -> (planned) `arbora/api/ops/activity.py::handle_activity_stream` -> the engine run-trace read; over MCP, the `ask` verb reaches the same handler. The read is tenant-scoped through the caller's verified session; a caller without run read access on the tenant's runs gets a subject-read refusal per the registry caller chain. Shape: one handler (planned) `arbora/api/ops/activity.py::handle_activity_stream` mapping run-trace step records into the activity result model; cursor pagination reuses the registry cursor envelope. Refusals: `UNAVAILABLE` when the engine is not bound; an unknown or foreign run is a subject-read refusal; a malformed cursor is `INVALID_ARGUMENT`. Depends on: `MEDULLA-ORCH-VOCAB-R803`. | Test (planned): `tests/api/test_activity_ops_served.py::test_activity_serves_run_trace_facts_with_cursor_and_refuses_unrecorded` (L3: HTTP and MCP). |
2 changes: 2 additions & 0 deletions specs/hosted-api-operations/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,8 @@ As an operator, I run a stored process workflow through one served operation. A
- **FR-009**: Merge arming must need an owner receipt on the head commit, and every delivery write must be a governed effect. Rows: `ARBORA-OPS-R896.10`, `ARBORA-OPS-R896.11`.
- **FR-010**: A stored process workflow must run as one admitted agent DAG with served approvals and engine-decided branches. Rows: `ARBORA-OPS-R898`.
- **FR-011**: Every prompt entry point must accept audio and other media parts, turn them into text through one modality seam (audio through the fleet's speech-to-text capability), keep the original as an attachment linked to its derived text, and refuse with a typed code when no capability is reachable or a limit is exceeded. Rows: `ARBORA-OPS-R899`.
- **FR-012**: Agent presence is served on one channel with an explicit snapshot interval and a bounded update rate; per-frame movement is never durable. Rows: `ARBORA-OPS-R915`.
- **FR-013**: The activity stream is served from run-trace provenance; arbora invents no activity. Rows: `ARBORA-OPS-R916`.

## Success Criteria

Expand Down
2 changes: 2 additions & 0 deletions specs/hosted-api-operations/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -491,3 +491,5 @@ Each line below names one active row that no earlier task covers. The descriptio
- [ ] T417 [US1] ARBORA-OPS-R913 Fleet management, schedule, maintenance, workflow, code, command and resource operations. Size: L, 4 PRs, 1.5 days.
- [ ] T418 [US1] ARBORA-OPS-R914 Ecosystem widgets and media transcription. Size: M, 2 PRs, 5 hours.
- [ ] T420 ARBORA-OPS-R024.5.1 Model list read for ordinary users.
- [ ] T421 [US1] ARBORA-OPS-R915 Agent presence is served on one channel with a bounded update rate. Size: S, 1 PR, 2 hours.
- [ ] T422 [US1] ARBORA-OPS-R916 The activity stream is served from run-trace provenance. Size: S, 1 PR, 2 hours.
2 changes: 2 additions & 0 deletions specs/hosted-api-operations/test-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -571,3 +571,5 @@ Each entry below names a row whose proof is the verification text of that row in
| `ARBORA-OPS-R913` | Test: `tests/api/test_fleet_admin_ops.py::test_register_server_needs_plan_confirmation_and_hides_secret_values`, `tests/api/test_command_ops.py::test_commands_are_exactly_the_served_operations` and `tests/api/test_workflow_ops.py::test_run_returns_a_run_id_in_the_run_machine` (L2). |
| `ARBORA-OPS-R914` | Test: `tests/api/test_ecosystem_widget_ops.py::test_each_widget_projects_rows_from_its_connector_call`, `tests/api/test_ecosystem_widget_ops.py::test_down_connector_gives_degraded_cached_rows` and `tests/api/test_media_transcribe.py::test_blob_ref_goes_to_asr` (L2). (planned: the named test file does not exist yet) |
| `ARBORA-OPS-R844.2` | Test: `tests/test_served_operation_api.py::test_node_and_batch_writes_mask_secret_bearing_properties` (L2). |
| `ARBORA-OPS-R915` | Test: `tests/api/test_presence_ops_served.py::test_presence_serves_one_snapshot_at_a_bounded_interval` (planned, L3). |
| `ARBORA-OPS-R916` | Test: `tests/api/test_activity_ops_served.py::test_activity_serves_run_trace_facts_with_cursor_and_refuses_unrecorded` (planned, L3). |
Loading