Ops & Status v1 Product Brief

This brief captures the first implementation target for the CareerVector operations cockpit after the auth spike was set aside. It is the product contract for the first useful version, not a complete observability platform.

Current tab contract: Ops uses the shared operating-model tabs Anomalies | Events | Infra | Inspector | Sysadmin. Earlier names in this brief such as "Services & Quotas", "Live", and "Analytics" are lenses or panels inside those tabs, not primary tabs. The canonical tab grammar lives in wiki/content/working-memory/ops-qa-product-operating-model.md and is mirrored by ops/ui/src/routes/+layout.svelte.

The central idea is simple: the dashboard, MCP tools, and future assistant all read the same normalized operations API. Vendor APIs and log providers are implementation details behind that API. The visual cockpit must not know whether a worker runs on Cloudflare, Render, Railway, Koyeb, Deno Deploy, or a future host. It should see a service, a budget, a status, a source endpoint, and an explanation.

Goal

Give the operator a truthful, low-maintenance way to answer:

  • Is the system healthy right now?
  • Are quotas and spend trending toward a problem before the limit is hit?
  • Which workspace, service, provider, or queue is causing the signal?
  • What API endpoint or MCP tool should be queried next?
  • What bounded recovery action exists, if any?

The first version should prefer boring, correct aggregation over complex business logic. A conservative burn-rate warning such as "20k of 30k monthly budget spent by day 10" is more valuable than an ambitious assistant with unreliable data.

Non-goals

  • No user support CRM. CareerVector does not need enterprise support tooling for this surface.
  • No dependency on user email, user hash, or billing identity.
  • No direct vendor coupling in the UI. Cloudflare, Axiom, OpenAI, Anthropic, and future hosts are adapters behind API contracts.
  • No autonomous remediation in v1. Recovery actions stay explicit and audit-logged.
  • No invented telemetry. Missing credentials or unavailable vendor APIs must show as not_configured or unknown, not as guessed numbers.

Five Ops Tabs

Anomalies

Anomalies are harmful expectation mismatches that need operator attention. They are the canonical place for "something is wrong" records before or after they become incidents.

Sources:

  • GET /anomalies/summary
  • GET /anomalies/search
  • POST /anomalies

It should answer which expectation failed, how severe it is, what evidence backs it, and which event, infra object, workspace, source, or provider it attaches to.

Events

Events are meaningful operational occurrences, not raw logs. The live stream, queue mix, journals, and promoted records live here.

Sources:

  • GET /events/summary
  • GET /events/search
  • POST /events
  • GET /journals/summary
  • GET /journals/search
  • POST /journals
  • GET /changes/stream
  • GET /queue-mix
  • GET /claim-mix

It should answer what happened, what is happening now, what queue or claim class is involved, and which anomalies or journals interpret the event.

Infra

Infra is the substrate view. Services, quotas, costs, connectors, provider health, GraphDB readiness, and IaC drift are Infra lenses rather than separate tabs.

Sources:

  • GET /services/summary
  • GET /health
  • GET /quota
  • GET /finops/summary
  • GET /connectors/summary
  • GET /infra/summary
  • POST /infra/sync

It should answer whether every bound service runs, whether request and provider budgets are safe, whether configured connectors are trustworthy, and whether the file-backed infra catalog matches observed reality. Vendor details stay behind normalized API contracts.

Inspector

Inspector is the drill-down workbench. In CareerVector it is workspace-centered; in JobCache it is source/ad/role/device-centered. It composes domain payload, semantic edges, backing evidence, provider observations, related QA/Ops/Wiki context, and suggested machine actions.

Sources:

  • GET /workspace-rollups
  • GET /workspaces/:id
  • GET /workspaces/:id/inspector
  • GET /provider-activity
  • GET /compute-lock-contention

It should show operational state, telemetry tier or object trust, queue state, recent requests/events, and tier-gated or product-gated detail. The green/yellow/red operational state is separate from telemetry tier, device trust, or corpus trust.

Sysadmin

Sysadmin is the agentic operator bench. It starts as rule-based triage plus allowlisted action proposals, not autonomous remediation.

Sources:

  • GET /status/summary
  • GET /finops/summary
  • GET /audit
  • POST /sysadmin/chat
  • POST /sysadmin/actions/execute

End-state direction: an integrated assistant that can investigate with MCP, cite the readings it used, and suggest bounded operator actions. V1 stops at truthful summaries and source-linked findings.

API Contract

The API is the product boundary:

  • UI reads the API.
  • MCP wraps the API.
  • Any future assistant reads the API through MCP or direct internal calls.
  • Vendor integrations live behind adapters.

This keeps the cockpit replaceable and prevents vendor details from spreading through components. Adding a new host or provider should mean implementing a normalizer that returns the existing service/quota/finding shapes, not rewriting dashboard panels.

The first shared summary endpoint is:

GET /status/summary

It returns the five Ops tabs, their state, headline, facts, source endpoints, and top findings. It should be treated as the machine-readable index for the cockpit tabs and the MCP "what should I inspect first?" tool.

The primary Infra detail endpoint is:

GET /services/summary

It returns service checks, budget forecasts, provider-cost readiness, server-key readiness, and findings without exposing vendor-specific APIs or secret values.

The visual cockpit's first paint uses:

GET /cockpit/snapshot

This is a UI convenience envelope. It performs the expensive fanout once and returns the raw panel payloads plus the same normalized status summary. MCP tools should prefer the smaller, purpose-specific endpoints unless they need a full dashboard snapshot.

User Stories

  • As an operator, I can open Infra and see whether all critical services are operational and whether any budget is forecast to exceed its monthly limit.
  • As an operator, I can see that Cloudflare request usage is safe today but projected to exceed the monthly budget at the current burn rate.
  • As an operator, I can inspect AI usage from internal ledgers and reconcile it with provider cost APIs when admin keys are configured.
  • As an operator, I can see that a provider is rate-limiting or dominating recent activity, then move to Events or Inspector for context.
  • As an operator, I can open a workspace from a red rollup and inspect queue state, sub-doc clocks, and tier-appropriate process-request details.
  • As an operator, I can use MCP to ask for the same status summary the UI uses, including the source endpoint for each finding.
  • As an operator, I can distinguish "not configured" from "healthy" so missing credentials are visible and do not create false confidence.
  • As an operator, I can perform bounded recovery actions and later see those actions in the audit log.

MVP Reading List

Use this brief together with:

Source: wiki/content/studies/cockpit-vision/ops-status-v1.md