Add grid agent milestone acceptance gate (#135)
This commit is contained in:
154
docs/grid-agent-acceptance.md
Normal file
154
docs/grid-agent-acceptance.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# Grid-agent milestone 14 acceptance
|
||||
|
||||
This is the reproducible acceptance contract for the native Rust
|
||||
`metacrate-grid-agent`. The machine-readable record schema is
|
||||
[`../config/grid-agent-acceptance-evidence.schema.json`](../config/grid-agent-acceptance-evidence.schema.json).
|
||||
Evidence is intentionally a summary of observable triggers, policy decisions,
|
||||
actions, and outcomes; it never contains prompts, message bodies, credentials,
|
||||
capability URLs, session identifiers, hidden model reasoning, or raw scene data.
|
||||
|
||||
## Deterministic gate
|
||||
|
||||
Run the complete credential-free package suite and create a new evidence file:
|
||||
|
||||
```sh
|
||||
cargo test --locked -p metacrate-grid-agent --all-features
|
||||
cargo run --locked -p metacrate-grid-agent -- \
|
||||
--acceptance-evidence /tmp/metacrate-grid-agent-acceptance.jsonl
|
||||
```
|
||||
|
||||
The writer uses create-new semantics, a 32-KiB record ceiling, contiguous
|
||||
sequence numbers, schema version 1, a secret-canary scan, per-record flush, and
|
||||
final filesystem synchronization. It will not replace previous evidence. The
|
||||
runner exercises the production configuration, `AgentService`, control queue,
|
||||
session supervisor, reconnect generation fence, shutdown joins, unified fake
|
||||
grid evidence, and adversarial policy/redaction corpus. The rest of the package
|
||||
suite supplies the complete scenario matrix, policy registrations, control/TUI
|
||||
conformance, journal corruption/recovery, conversation recovery, model
|
||||
transport failures, visual fallback, and bounded-load cases.
|
||||
|
||||
The evidence stages are `configuration_and_bounds`, `headless_startup`,
|
||||
`control_conformance`, `chat_scheduling`, `clean_shutdown`, `maintenance_reconnect`, and
|
||||
`policy_redaction_and_protocol_audit`. A successful run has six ordered
|
||||
`passed` records and leaves zero service tasks, grid sessions, or loopback
|
||||
sockets. Headless startup never creates a TUI. Integrated and split UI clients
|
||||
exercise the same versioned control protocol, commands, event model, and
|
||||
graceful-shutdown target in their conformance tests.
|
||||
|
||||
Reference deterministic run on 2026-08-18: all 137 library scenarios, 37
|
||||
integration scenarios, and one compile-fail documentation case passed with all
|
||||
features; the seven-stage evidence command passed with zero leaked tasks,
|
||||
sessions, or sockets. The completed live-grid release binary was 28,857,688
|
||||
bytes with SHA-256
|
||||
`b2c93a6acd6fa856669fdb4e08110d700218255f57ec2f7908977eeabea7c470`,
|
||||
under the 40-MiB budget. The record identifies the package, pinned Rust toolchain,
|
||||
source revision when supplied through `METACRATE_SOURCE_COMMIT`, exact generic
|
||||
command, fake/live profile, grid type, endpoint capability profile, timestamp,
|
||||
outcome, duration, metrics, and limitations. CI supplies the source commit at
|
||||
artifact collection time; an ad-hoc dirty-tree run deliberately says
|
||||
`working-tree-unrecorded` rather than inventing provenance.
|
||||
|
||||
## Resource budgets
|
||||
|
||||
The checked defaults are deliberately generous enough for loaded CI runners
|
||||
but small enough to expose deadlocks and unbounded ownership:
|
||||
|
||||
| Measurement | Budget | Rationale |
|
||||
| --- | ---: | --- |
|
||||
| Offline readiness | 2,000 ms | Local tasks have no network dependency. |
|
||||
| Control enqueue | 250 ms | Pause/resume must remain interactive under bounded backpressure. |
|
||||
| Chat scheduling, excluding inference | 500 ms | Includes the intentional 250-ms fragment debounce plus loaded-runner scheduling, without constraining the endpoint. |
|
||||
| Maintenance reconnect | 2,000 ms | Test policy uses a 10-ms initial backoff; the production default starts at 1 s. |
|
||||
| Ordered shutdown | 5,000 ms | Allows journal flush and task joins while remaining service-manager friendly. |
|
||||
| Steady/peak memory | 128/256 MiB | Includes bounded queues, conversations, observations, and one visual frame. |
|
||||
| Any queue | 8,192 items | Matches the hard configuration ceiling; defaults are 32–512. |
|
||||
| Release binary | 40 MiB | The completed live-grid release is 28,857,688 bytes. |
|
||||
| Journal retention | 1 GiB | Operator-configured segment and total limits remain mandatory. |
|
||||
|
||||
Startup, control, reconnect, and shutdown are measured by monotonic time.
|
||||
Queue limits and task/session high-water marks are asserted directly. Memory,
|
||||
binary, and journal limits are structural budgets: heap-bearing collections are
|
||||
bounded at construction, the release artifact is measured in
|
||||
[the release evidence](grid-agent-release-evidence.md), and journal rotation
|
||||
enforces its configured byte ceiling. Operators may additionally record RSS
|
||||
with their platform service manager; RSS is not used as a portable CI assertion
|
||||
because allocator and OS accounting are not comparable across platforms.
|
||||
|
||||
## Live-grid matrix
|
||||
|
||||
Live validation is optional and requires a dedicated avatar, controlled land,
|
||||
and an operator-supplied OpenAI-compatible endpoint. Credentials alone grant no
|
||||
consent. Inspect exact confirmations without contacting either service:
|
||||
|
||||
```sh
|
||||
metacrate-grid-agent --check-live-opt-ins
|
||||
```
|
||||
|
||||
Each capability has a separate exact-value environment opt-in:
|
||||
|
||||
| Capability | Variable and required literal |
|
||||
| --- | --- |
|
||||
| Login/relogin | `METACRATE_AGENT_LIVE_LOGIN=LOGIN` |
|
||||
| Public mention and authorized/unprivileged IM | `METACRATE_AGENT_LIVE_CHAT_IM=CHAT-IM` |
|
||||
| Controlled LSL delivery | `METACRATE_AGENT_LIVE_SCRIPT=SCRIPT` |
|
||||
| Landmark offer, teleport, and bounded roaming | `METACRATE_AGENT_LIVE_LANDMARKS=LANDMARKS` |
|
||||
| Reversible prim build and cleanup | `METACRATE_AGENT_LIVE_BUILD=BUILD-CLEANUP` |
|
||||
| Synthetic visual capture and visual question | `METACRATE_AGENT_LIVE_VISUAL=VISUAL` |
|
||||
|
||||
Any action opt-in without the login opt-in fails closed. A misspelled value is
|
||||
false. Store the grid password and endpoint key in restrictive `_FILE` inputs
|
||||
described by [the operations guide](grid-agent-operations.md), never in these
|
||||
variables or a command line.
|
||||
|
||||
For an authorized live run, start split mode so another terminal can reconnect
|
||||
the TUI without affecting the agent session. Record UTC start/end, commit,
|
||||
binary hash, generic grid type (for example `OpenSim-compatible`), endpoint
|
||||
capabilities (`text`, `tools`, and optionally `image_input`), and evidence-file
|
||||
hash. Do not record vendor presets or identifiers. Exercise, in order:
|
||||
|
||||
1. Login and full readiness; force a maintenance reconnect and confirm the
|
||||
generation changes with one session maximum.
|
||||
2. Public mention gets an informational reply; a public command is denied.
|
||||
Send unprivileged and authorized IMs and verify their separate sessions,
|
||||
exact rollover, facing/attention event, and perception queries.
|
||||
3. Pause, cancel, approve, resume, and force reconnect from the control client;
|
||||
disconnect/reconnect the TUI and verify the service remains headless-safe.
|
||||
4. With the script opt-in, deliver only to the controlled recipient and record
|
||||
the returned inventory ID and permissions. Advanced mutation requires an
|
||||
explicit approval and conservative script size/runtime limits.
|
||||
5. With the build opt-in, build only on controlled land, record transaction and
|
||||
object recovery IDs locally, verify no currency operation exists, and delete
|
||||
every created prim through the ownership-checked cleanup path.
|
||||
6. With the landmark opt-in, accept a controlled offer, use a short bounded
|
||||
folder schedule, teleport, then disable the schedule. With visual opt-in,
|
||||
capture the synthetic scene and ask one visual question. Record the endpoint
|
||||
capability fallback if image input is rejected.
|
||||
7. Gracefully stop. Confirm no pending approvals, scheduled jobs, inventory
|
||||
offers, owned test prims, tasks, sockets, or sessions. List any unavoidable
|
||||
inventory artifact and its manual recovery ID in private operator notes,
|
||||
never committed evidence.
|
||||
|
||||
The structured journal and control/TUI views must show the same correlation IDs
|
||||
from inbound trigger through inference summary, proposed tool, policy/approval,
|
||||
execution, and result. This is observable action provenance, not chain-of-thought.
|
||||
|
||||
## Milestone handoff
|
||||
|
||||
Milestone implementation links: #128 architecture/configuration, #129 LLM and
|
||||
policy, #130 lifecycle/conversation/interaction, #131 embodiment and world
|
||||
tools, #132 visual capture and TUI, #133 deterministic protocol harness, and
|
||||
#134 operations/secret handling. Their focused tests remain the authoritative
|
||||
compatibility cases; this final gate integrates rather than duplicates them.
|
||||
|
||||
Routine Gitea jobs remain `ubuntu-latest` only. Portable target checks are
|
||||
defined in `ci/release-matrix.json`; a local Windows GNU check additionally
|
||||
needs `x86_64-w64-mingw32-gcc` for the existing AWS-LC build.
|
||||
|
||||
## Remaining limitations
|
||||
|
||||
No public CI runner performs live actions, holds credentials, measures portable
|
||||
RSS, or proves a particular provider's image capability. Live evidence is only
|
||||
credible when an operator supplies all exact opt-ins and completes the matrix
|
||||
on a dedicated account. The deterministic gate is therefore the required CI
|
||||
acceptance record; a live report supplements it and must state any skipped
|
||||
capability, endpoint fallback, or manually recoverable artifact explicitly.
|
||||
Reference in New Issue
Block a user