Files
canina/frontend/admin-panel/V4_PANEL_COMPLETION_CONTRACT.md

5.3 KiB

Admin v4 completion integration contract

Frontend-only slice based on 5507fbc. No deployment or runtime writes. The historical read-only integration document does not authorize enabling routes. Backend policy remains the authority; UI adds deny-only safety restrictions, never permissions.

Workflow (existing routes retained)

  • GET /admin/orchestration/overview: ResourceSnapshot with items, ISO measuredAt, capabilities:{mutations:boolean,chat:boolean,runtime:boolean}. Missing/failed capability read defaults false.
  • GET /admin/orchestration/tasks: Task[] (or {success:true,data:Task[]}).
  • GET /admin/orchestration/tasks/:id: Task. Required identity/version/state/mode/budget and server-computed availableActions; optional scope/acceptance metadata, runs/artifacts, immutable decisions, events and budgetLedger. Missing actions means no permission. Include structured redacted scope metadata for a useful Gate1 review; no secrets or arbitrary event payloads.
  • POST /admin/orchestration/tasks: existing CreateTaskInput {key,title,department,operationMode,budgetLimitCents,metadata:{scope,acceptanceCriteria:string[]}}. UI allows OBSERVE/PREPARE only, not Production. Key is unique business identity; after an ambiguous create, reconcile key before resubmission. Success locks the form to prevent accidental duplicate submission.
  • PUT /admin/orchestration/tasks/:id/transition: TransitionDto {toState,expectedVersion,idempotencyKey,reason}.
  • POST /admin/orchestration/tasks/:id/gates/:gate/decide: GateDecisionDto {decision:'APPROVED'|'REJECTED',expectedVersion,idempotencyKey,expiresAt,notes}; Gate2 approval additionally binds {runId,artifactHash,commitSha,environment} from a registered SUCCEEDED run, never editable commit/environment. Gate1 is bounded work, not release permission.
  • ServerAction {id,label,toState? ,gate?:1|2,decision?:'APPROVED'|'REJECTED',disabledReason?}. Exactly one of transition or gate decision. All role/policy/kill/version checks remain backend-side. Browser identity fields are never posted; actor must derive from verified JWT. HOLD/request changes only appear if advertised as supported transitions. EDIT_AND_APPROVE is unavailable without a separately reviewed DTO; no guessed mutation endpoint.
  • HTTP409 stale version/idempotency mismatch, 410 expired, 401/403 denied and other 4xx permanently lock that dialog; refresh and review afresh. Network/5xx ambiguous failures allow only identical payload/key. Inputs and navigation are locked after first attempt; authoritative refresh invalidates selection and pending detail reads. No optimistic status update.
  • Production task actions and release transitions remain disabled even if advertised. Gate2 evidence inspection is not deployment authorization. Server still enforces TTL; browser time is a usability check, not trusted authorization.

Runtime read API (aligned by read-only inspection with runtime sibling)

Uses existing JWT Axios client, never upstream Hermes paths or tokens. No automatic runtime mutations. Tab is explicitly selected; failed auth/config/routes show unavailable.

  • GET /admin/orchestration/runtime/health -> {ok:boolean,version:string,commit:string,auth_required:true}. Any false/missing authentication flag is rejected.
  • GET /admin/orchestration/runtime/profiles -> {name:string,is_default:boolean,gateway_running:boolean}[], already filtered to principal grants.
  • GET /admin/orchestration/runtime/status?profile=<authorized> -> {version,gateway_running,overall,active_agents,gateway_state:string|null}.
  • GET /admin/orchestration/runtime/sessions?profile=<authorized>&limit=20&offset=0 -> {total:number,sessions:{id,profile,source,is_active}[]}. UI paginates; profile mismatch is rejected.
  • GET /admin/orchestration/runtime/usage?profile=<authorized>&days=30 -> {period_days:number,totals:{total_input,total_output,total_sessions,total_estimated_cost}}.

Runtime client explicitly projects known fields; unknown secret fields are discarded. Numeric zero survives. Cost is labelled upstream estimate, unspecified currency, not settled billing and never added to overlapping 9router totals. Client observation time is not server heartbeat/freshness. Profile gateway flags and active agent count are source observations, not invented readiness/department counts. Generic Resources for existing agents/model-policy/schedules/releases remain unchanged; unavailable contracts stay visibly unavailable. Runtime schedules/model-info may exist backend-side but are not guessed into generic Resources.

Verification

Runner: disposable node:22-bookworm, --userns=host --network none; source and dependency donor read-only, private copies in /work. No donor/source build writes. Required final gates: tsc --noEmit -p tsconfig.app.json, npm run build, npm test -- --maxWorkers=2. Logs under /opt/services/canina/validation/v4-panel-completion/ (outside discovery). Earlier RED proves 7 workflow failures and 2 selection/idempotency failures; runtime RED is missing new component. Existing test fixtures migrated from invented VERIFIED run status to backend SUCCEEDED status. No tests skipped or permissions inferred.

Not claimed: live backend browser acceptance, real authenticated runtime availability, Stage publication, CI evidence authority or Production execution. Parent owns integration and publication.