147 lines
8.6 KiB
Markdown
147 lines
8.6 KiB
Markdown
# 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 seven 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 29,487,544
|
||
bytes with SHA-256
|
||
`1ccbd11baf69372d76767c419b59319447ecf088bc0ae83ce1640709f6507ad0`,
|
||
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 29,487,544 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 uses a dedicated avatar, controlled land, and an
|
||
operator-supplied OpenAI-compatible endpoint configured in the private
|
||
platform `config.yml`. There are no action-specific environment switches.
|
||
Authorization follows the production policy model:
|
||
|
||
| Origin | Available behavior |
|
||
| --- | --- |
|
||
| Everyone/public chat | Informational responses and explicitly public-safe tools. |
|
||
| Ordinary IM | Private conversation without privileged mutation. |
|
||
| UUID listed in `authorized_avatar_uuids` | Policy-gated privileged tools, with approval where required. |
|
||
| Local operator/control role | Pause, approve/cancel, reconnect, configuration, and shutdown controls. |
|
||
|
||
Landmarks, scripts, builds, cleanup, and visual questions are capabilities,
|
||
not configuration modes. They remain governed by tool origin, authenticated
|
||
UUID, land/ownership checks, bounded resources, and approval policy.
|
||
|
||
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. As a privileged user, deliver a script 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. As a privileged user, 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. Create and catalog a current-location landmark, accept a controlled landmark
|
||
offer, use a short bounded folder schedule, teleport, then disable the
|
||
schedule. Set and reset a bounded camera view, capture the reconstructed 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 endpoint's image capability. Live evidence is only
|
||
credible when an operator 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.
|