85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
## MODIFIED Requirements
|
|
|
|
### Requirement: Task submission and status via the SDK
|
|
The system SHALL allow an external integrator to submit a task (goal or
|
|
workflow reference plus constraints and an optional explicit Host/Device
|
|
target) through the platform SDK's API, and to query that task's current
|
|
status by id, backed by the `task-scheduler` capability. A Device target MUST
|
|
include its owning Host, and the status representation SHALL expose any
|
|
explicit target separately from the eventual assignment.
|
|
|
|
#### Scenario: Submit a task via the API
|
|
- **WHEN** an integrator calls the task-submission endpoint with a valid goal
|
|
and optional constraints
|
|
- **THEN** the API returns a task id that can be used to poll status, and the
|
|
underlying `task-scheduler` records a new `queued` `ScheduledTask`
|
|
|
|
#### Scenario: Submit a task for one Host and Device
|
|
- **WHEN** a `tasks:submit` principal submits a valid target containing an
|
|
eligible Host and Device it is permitted to use
|
|
- **THEN** the API records that exact target and the scheduler cannot assign
|
|
the task outside it
|
|
|
|
#### Scenario: Device target lacks its Host
|
|
- **WHEN** an integrator submits a Device target without an owning Host
|
|
- **THEN** the API rejects the request before creating a task
|
|
|
|
#### Scenario: Query status of a known task
|
|
- **WHEN** an integrator requests status for a task id that exists
|
|
- **THEN** the API returns that task's current status (`queued`, `assigned`,
|
|
`dispatched`, `done`, or `failed`) and its explicit target when present
|
|
|
|
#### Scenario: Query status of an unknown task
|
|
- **WHEN** an integrator requests status for a task id that does not exist
|
|
- **THEN** the API returns a not-found response rather than an unhandled server
|
|
error
|
|
|
|
### Requirement: Python SDK client mirrors the REST API
|
|
The system SHALL provide a Python client (`CloudClient`) exposing methods
|
|
corresponding to every `/v1/...` resource, user-authentication,
|
|
user-administration, and governance route, including targeted task submission
|
|
and read-only Host AI-usage access, so integrators do not need to
|
|
hand-construct HTTP requests.
|
|
|
|
#### Scenario: Client submits a targeted task and retrieves status
|
|
- **WHEN** a caller uses `CloudClient` to submit a task with an explicit target
|
|
and then fetches status by the returned id
|
|
- **THEN** the client produces the same target and lifecycle result as direct
|
|
REST calls
|
|
|
|
#### Scenario: Client administers governance with a scoped bearer
|
|
- **WHEN** a caller configures `CloudClient` with `governance:admin` and
|
|
invokes a policy operation
|
|
- **THEN** the client sends that authentication and returns the corresponding
|
|
non-secret policy representation
|
|
|
|
### Requirement: Public API operations enforce scopes
|
|
The public platform API SHALL require operation-specific scopes for task
|
|
submission, task reading, pool reading, plugin reading, plugin
|
|
administration, user administration, governance reading, and governance
|
|
administration, regardless of whether the principal came from a bearer
|
|
credential or user session.
|
|
|
|
#### Scenario: Submit principal has task scope
|
|
- **WHEN** a bearer or user principal with `tasks:submit` calls the
|
|
task-submission endpoint
|
|
- **THEN** the request is authorized subject to normal task validation and
|
|
any effective user-submission policy
|
|
|
|
#### Scenario: Non-admin principal attempts plugin registration
|
|
- **WHEN** an authenticated principal without `plugins:admin` calls plugin
|
|
registration
|
|
- **THEN** the API rejects the request before resolving or loading the plugin
|
|
target
|
|
|
|
#### Scenario: Non-admin principal attempts user administration
|
|
- **WHEN** an authenticated principal without `users:admin` calls a
|
|
user-administration endpoint
|
|
- **THEN** the API rejects the request before reading or changing protected
|
|
user state
|
|
|
|
#### Scenario: Principal lacks governance administration scope
|
|
- **WHEN** an authenticated principal without `governance:admin` changes a
|
|
user or Host policy
|
|
- **THEN** the API rejects the request before changing policy or usage state
|