# Structured operation results and deep links

Date: 2026-07-31
Scope: local repository implementation and controlled contract validation
External writes: none
Commit, push or deployment: none

## Outcome

The remaining mission-control mutation surfaces now return one structured
result contract. The browser presents that contract in one global result tray
and resolves its entity references into registered, selectable destinations.
This closes the result-navigation follow-up recorded by the Performance-V2
checkpoint without introducing a second workflow or routing authority.

OpenClaw remains the runtime authority. Nexus still owns policy, approval,
audit, durable workflow state and presentation. This checkpoint did not relax
the production write gate for an unsupported external Nexus client identity.

## Backend contract

`OperationResultFactory` creates the common response metadata:

- operation/correlation ID;
- operation status;
- non-negative resource revision;
- one optional primary `EntityRefDto`;
- de-duplicated affected references; and
- trace ID or validated `traceparent` when available.

Caller-provided correlation IDs are accepted only when they are non-empty,
contain no control characters and are at most 128 characters. The selected ID
is returned in `X-Correlation-ID`. Frontend URLs are deliberately not emitted
by the backend.

The contract is emitted from:

- dashboard and versioned task create, update, state, approval, rejection,
  delete, stale-reset and activity mutations;
- task bridge and Nexus MCP task mutation responses;
- project create, update, archive and delete;
- notification read and read-all, including an honest `noop` when an item was
  already read;
- OpenClaw task cancel, session abort/model patch, cron create/update/delete/
  run and approval resolution, including blocked, invalid, stale, replayed,
  in-doubt and idempotency-conflict paths;
- OpenClaw agent-file writes; and
- schema-controlled OpenClaw config patches.

Task and project delete endpoints now return the deleted/archived DTO with its
operation result instead of an empty `204`, so clients can navigate and audit
the outcome. Generated OpenAPI and TypeScript contracts reflect this response
shape.

Legacy Nexus resources that do not yet own a concurrency revision use
revision `0`. Notification changes use revision `1`/`0`; OpenClaw and proposal/
run domains retain their existing revision semantics. A synthetic revision was
not invented from timestamps.

## Frontend result handling

The global authenticated shell now contains a dismissible, keyboard-visible
operation result tray. It normalizes generated number/string revisions and
shows status, primary/affected entities, revision and trace metadata.

The central resolver supports:

| Reference | Destination behavior |
|---|---|
| `task` | durable Task Detail route |
| `project` | durable Project Detail route |
| `run` | durable Run Detail route |
| `cron` | Calendar opens the addressed job detail |
| `openclaw-task` | Run Control selects the runtime task |
| `session` | Run Control selects the session |
| `approval` | Run Control prioritizes, scrolls to and focuses the approval |
| `agent-file` | Agent Detail opens the addressed live file tab |
| `config` | Settings scrolls to and focuses the OpenClaw config editor |
| `notification` | Notifications prioritizes and focuses the item |
| `activity` | Activity opens the addressed event detail |
| `task-board` | Task Board index |

Existing agent, proposal, incident, document and event-stream mappings remain
registered. The backend continues to emit entity identity rather than route
strings.

Task Board, Task Detail, legacy ModuleView task actions, projects,
notifications, OpenClaw cron/control commands, agent model changes,
agent-file writes and config patches all consume the result contract. Failed
OpenClaw responses report their structured result before the existing recovery
message is raised.

## Automated acceptance

| Gate | Result |
|---|---|
| .NET 10 backend tests | **Passed: 362; failed: 0; skipped: 5; total: 367** |
| Frontend typecheck | **Passed** |
| Frontend unit tests | **Passed: 12 files, 30 tests** |
| Frontend production build | **Passed: 1,988 modules transformed** |
| Playwright controlled contract suite | **Passed: 24 tests** |
| Core-route geometry | **Passed at 375, 768, 1024, 1440 and 1920 px** |
| Task mutation result journey | **Passed: drag/drop -> operation tray -> Task Detail** |
| OpenAPI generation | **Passed**; backend document and generated schema updated |

The five skipped backend tests remain explicitly Docker-gated: three
PostgreSQL provisioning tests, one Toxiproxy provisioning test and one
PostgreSQL operation-claim concurrency test. They were not executed and are
not counted as passing evidence.

## Boundaries and next gates

This checkpoint does not prove:

1. live pairing or management writes against Bao's OpenClaw;
2. an end-to-end `Nexus -> OpenClaw -> OpenAI -> Nexus` production run;
3. PostgreSQL/Toxiproxy concurrency behavior in a running Docker environment;
4. k6 board thresholds or archived SQL execution plans;
5. live Promptfoo/MCP 2.0 negotiation; or
6. production OTLP/`pg_stat_statements` operation.

The next release gate remains official external Nexus/generic-operator
Client-ID support followed by read-only inventory acceptance. Docker-backed
concurrency and measured board performance should be run before making scale
or p95 claims. No Redis, broker, workflow engine or second agent runtime is
justified by this result-contract slice.
