`abc report`

Researcher-productivity summary read entirely from ~/.abc/db/local.db. No network calls — abc report is a seed-tier-native command.

Usage

abc report                      # personal YTD summary, default text mode
abc report --since=2026-01-01 --until=2026-04-30
abc report --show-rate-card     # append the full per-rate provenance block
abc report --json               # machine-readable; metric IDs as keys
abc report --json --by=investigation
abc report --technical          # metric IDs replace human Titles

abc report runs                 # per-run cost + emissions table (subverb)
abc report runs --full          # forensic per-row block (run_id, nomad job, …)

Flags

Flag	Default	Description
`--since=YYYY-MM-DD`	Jan 1 of current year	Window start (UTC)
`--until=YYYY-MM-DD`	now	Window end (inclusive end-of-day)
`--by=<axis>`	unset	Aggregation axis: `investigation` / `project` / `pipeline` / `user`. JSON-only in v1; text mode rejects with a "deferred to v2" message.
`--show-rate-card`	`false`	Append the detailed per-rate provenance block (currency, CPU/GPU/memory/storage cost rates, all emissions coefficients) + override hints. Hidden by default — the headline already carries a "rates are suggestive default values" disclaimer.
`--json`	`false`	Emit the structured JSON contract documented below
`--technical`	`false`	Replace human Titles with metric IDs in the text headline (useful for reproducible doc snippets)
`--all-contexts`	`false`	Cross-context aggregation. Phase 2: rejects with `--all-contexts requires abc-controller-svc; not available in this context.` (gated until the controller service is deployed)

Default output is cost + emissions only (2026-05-27). The "Research time saved" heuristic block was removed from the default render pending real measurement (see the "Research time saved" section below). The detailed rate card moved behind --show-rate-card.

Two-layer metric naming

Every metric has a stable technical ID (frozen at first ship; used in JSON keys, --by flag values, SQL view names, and manuscript scripts) plus a revisable user-facing Title and Gloss (revisable without an ADR).

`ID`	`Title`	`Gloss`
`mttfs`	First-success time	How long from first attempt to first working run
`failure_to_result_ratio`	Failed runs per result	How many tries it took to get a usable answer
`retry_depth`	Tries before success	Attempts before the run worked
`mttr_failure`	Recovery time	How fast you got back on track after a failure
`stabilisation_runs`	Runs to settle	Submissions before the pipeline ran reliably
`queue_wait_fraction`	Waiting in queue	Share of total time spent waiting, not running
`active_engagement_hours`	Hands-on time	Hours actually at the terminal
`spectator_hours`	Watching time	Hours spent monitoring runs
`async_job_fraction`	Walked-away runs	Runs you submitted and didn't babysit
`cognitive_overhead_score`	Tools per workflow	Distinct commands touched to get one result
`workflows_unattended`	Hands-off completions	Pipelines that finished without you stepping in
`submission_source`	Submission source	How the run was authored: template / handwritten / rerun
`resource_fit`	Right-sized requests	How close requested CPU/RAM matched what was used
`cost_per_investigation`	Spend per question	ZAR per investigation, resolved via `internal/accounting` rate card
`emissions_per_investigation`	Carbon per question	kg CO₂e attributed to each investigation, resolved via `internal/emissions`
`spend_zar`	Total spend	Window-wide ZAR aggregate, computed via the shared `internal/accounting` rate-card resolver
`emissions_kgco2e`	Total emissions	Window-wide kg CO₂e, computed via the shared emissions resolver
`hours_saved`	Research time saved	Headline composite: estimated busywork avoided

Adding a metric requires populating all four fields (ID, Title, Gloss, Unit) in the same patch. The ID contract is enforced by tests; titles are capped at 32 characters.

Research time saved (heuristic; JSON / `--show-rate-card` only)

Removed from default text output (2026-05-27). The hours_saved family is a set of compile-time heuristics (counts of auto-retries, accepted defaults, etc. × hardcoded minute-multipliers) not yet backed by real measurement, so presenting it as a headline number was misleading at the seedling tier. The default abc report now shows only cost + emissions. The metric is still computed and exposed in the JSON contract (metrics.hours_saved) for downstream consumers; a future instrumented version may return to the text view behind its own flag.

The hours_saved heuristic is the sum of five compile-time constants:

Constant	Minutes saved per applicable run	Source
`AutoRetrySavedMinutes`	15	brainstorm §5.10; manual re-submit round-trip
`SmartDefaultSavedMinutes`	10	resource_fit metric rationale
`FailureSummarySavedMinutes`	30	structured failure summary vs. log diving
`TemplateReuseSavedMinutes`	60	template / rerun vs. setup from scratch
`AsyncRunSpectatorAvoidedMin`	30	spectator_hours; median observed monitoring session

One ledger, one read-side command

abc report is the canonical read-side surface over the local SQLite runs ledger. The Layer-0/1/2 rate-card resolver (internal/accounting) and the grid-intensity resolver are consumed directly here; the prior abc accounting report and abc emissions [report] commands were folded into this single closed-loop output (spec cli-verb-tree-restructure).

abc report --since=… --until=…

produces spend, emissions, and postdoc-hours-returned together, with per-investigation rollups.

Subcommands

abc report also hosts the dedicated environmental-footprint reports, folded in from former top-level verbs on 2026-06-05:

Command	Was	Purpose
`abc report emissions`	`abc emissions`	CO₂e report (Cloud Carbon Footprint v3 coefficients)
`abc report water`	`abc water`	freshwater report (Green Grid Program-WUE formula)
`abc report runs`	—	per-run cost + emissions ledger
`abc report compliance`	—	compliance status from the ABC API

All share the same Layer-0/1/2 rate-card resolver, so energy/cost/CO₂e/water figures stay consistent. Rate-card inputs are configured under abc config emissions (coefficients) and abc config accounting (cost rates) — distinct from the read-side reports here.

Sample output

Default — cost + emissions headline only:

$ abc report
Your 2026 so far:
────────────────────────────────────────────────────
Questions explored (investigations):  3
Pipeline runs:                        12  (10 worked, 2 retried)
Total compute:                        47 CPU-hrs, 0 GPU-hrs

Spend this period:                    R 1,420
Emissions this period:                47.3 kg CO₂e

These rates are suggestive based on the reasonable default values,
the real-time rates are coming soon.

With --show-rate-card — appends the full per-rate provenance block:

$ abc report --show-rate-card
[ … headline blocks as above … ]

Rate card (effective):
  currency                            ZAR       built-in    (SA market default)
  cost.cpu_hour                       0.5       built-in    (abc-cluster-cli vX — SA on-prem indicative)
  cost.gpu_hour                       9         built-in    (abc-cluster-cli vX — SA on-prem indicative)
  cost.memory_gb_hour                 0.05      built-in    (abc-cluster-cli vX — SA on-prem indicative)
  cost.storage_scratch_gb_hour        0.0001    built-in    (amortised enterprise NVMe + power)
  cost.postdoc_per_hour               350       built-in    (HSRC 2025 SA postdoctoral compensation guidance)
  emissions.grid_factor_gco2_per_kwh  900       built-in    (Eskom Integrated Annual Report 2023)
  emissions.cpu_w                     12        built-in    (Cloud Carbon Footprint v3 coefficient set)
  emissions.gpu_w                     250       built-in    (Cloud Carbon Footprint v3 coefficient set)
  emissions.memory_gb_w               0.3725    built-in    (Cloud Carbon Footprint v3 coefficient set)
  emissions.pue                       1.5       built-in    (Uptime Institute 2023 — generic on-prem average)
  emissions.storage_scratch_w_per_tb  8         built-in    (Samsung PM9A3 envelope amortised)

These rates are suggestive based on the reasonable default values,
the real-time rates are coming soon. To override locally:
  abc config accounting set cost.postdoc_per_hour=400
  abc config emissions set pue=1.27 grid_factor_gco2_per_kwh=950

The provenance footer is generated from the resolved rate card — every value carries its layer (built-in / local / flag) and citation. A Layer-1 override in ~/.abc/config.yaml (e.g. cost.postdoc_per_hour: 525) flows through the same resolver abc accounting uses. One ledger, two lenses (abc report for showback, abc accounting for budget caps).

`abc report runs` — per-run cost + emissions

Lists one row per submitted job/pipeline with cost + emissions derived from the stored resources × the rate card. Jobs sort first (most-recent within), then pipelines. Reads ~/.abc/db/local.db; re-probes Nomad for runs whose completion watcher died (the CLI exits seconds after submission, but jobs take minutes) unless --no-reconcile is passed.

abc report runs                       # last 30d, 20 rows, jobs first
abc report runs --since=7d --limit=50
abc report runs --verb=job            # jobs only (no pipeline footnote)
abc report runs --verb=pipeline       # pipelines only
abc report runs --full                # per-row forensic block
abc report runs --json                # machine-readable
abc report runs --no-reconcile        # skip the Nomad re-probe (faster offline)

$ abc report runs --since=30m
Runs · 2026-05-27 → 2026-05-27
────────────────────────────────────────────────────────────────────────────
TIME (UTC)        VERB      WORKLOAD              CPU·hr    COST(R)   CO₂e (kg)  STATUS
2026-05-27 13:30  job       cpu-burn.sh             0.33       0.17        0.01  completed
2026-05-27 13:25  job       timed-30.sh             0.01       0.00        0.00  completed
2026-05-27 13:30  pipeline  nextflow-io/hello       0.02          —           —  completed

(—) Pipeline cost/emissions are pending: the head-orchestrator's
    resources alone undercount the real pipeline by 10-100×, so the
    numbers are intentionally blank until the per-task cache aggregator
    ships. Job rows are computed directly from Nomad alloc resources
    and are honest.

Jobs are honest; pipelines are head-only today. A job is a single Nomad alloc — the watcher reads its resources and the cost is accurate. A pipeline is a head orchestrator that dispatches many worker jobs the watcher doesn't yet sum, so pipeline cost/emissions cells render — until the Nextflow-cache aggregator lands. --full adds a per-row vertical block surfacing run_id, nomad_job_id, namespace, exit_code, exit_reason, project / investigation attachments, and (for pipelines) workdir_root — useful for tracing a row to its Nomad job (abc job show <nomad_job_id>).

JSON schema

{
  "window":       {"since": "<RFC3339>", "until": "<RFC3339>"},
  "context_name": "abc-dev",
  "metrics": {
    "<metric-id>": {
      "id":         "<metric-id>",
      "label":      "<human Title>",
      "gloss":      "<one-line gloss>",
      "unit":       "hours|count|percent|currency",
      "value":      <number | object>,
      "computable": true,
      "reason":     "(present only when computable=false)"
    }
  },
  "rate_card": {
    "currency":                          {"value": "ZAR",   "source": "built-in", "citation": "SA market default"},
    "cost.cpu_hour":                     {"value": 0.5,     "source": "built-in", "citation": "abc-cluster-cli vX — SA on-prem indicative"},
    "cost.gpu_hour":                     {"value": 9,       "source": "built-in", "citation": "..."},
    "cost.memory_gb_hour":               {"value": 0.05,    "source": "built-in", "citation": "..."},
    "cost.storage_scratch_gb_hour":      {"value": 0.0001,  "source": "built-in", "citation": "..."},
    "cost.postdoc_per_hour":             {"value": 350,     "source": "built-in", "citation": "HSRC 2025 SA postdoctoral compensation guidance"},
    "emissions.grid_factor_gco2_per_kwh": {"value": 900,    "source": "built-in", "citation": "Eskom IAR 2023"},
    "emissions.cpu_w":                   {"value": 12,      "source": "built-in", "citation": "CCF v3"},
    "emissions.gpu_w":                   {"value": 250,     "source": "built-in", "citation": "CCF v3"},
    "emissions.memory_gb_w":             {"value": 0.3725,  "source": "built-in", "citation": "CCF v3"},
    "emissions.pue":                     {"value": 1.5,     "source": "built-in", "citation": "Uptime Institute 2023"},
    "emissions.storage_scratch_w_per_tb": {"value": 8,      "source": "built-in", "citation": "Samsung PM9A3 envelope"}
  },
  "groups": [          // present only when --by=<axis> set
    {
      "by":      "investigation",
      "key":     "inv-abc",
      "metrics": { "<metric-id>": { ... } }
    }
  ]
}

Required substrate (migrations)

abc report reads existing columns where available and gracefully degrades to "n/a (reason)" otherwise.

Migration	Adds	Unlocks metric
`0008_runs_queue_wait`	`pending_seconds`	`queue_wait_fraction`
`0009_runs_resource_request`	`cpu_request`, `mem_request_gb`	`resource_fit`
`0010_runs_submission_source`	`submission_source`	`submission_source`, contributes to `hours_saved`

Run abc localdb migrate to apply pending migrations. abc localdb status lists feature flags advertised through the capability layer.

No network guarantee

abc report declares Required{ AllOf: [{Service: "local-state"}] } — the local-state pseudo-service derived from the migration framework. The command makes zero outbound HTTP calls in any code path. A test in cmd/report/report_test.go swaps http.DefaultTransport for a tripwire and asserts zero RoundTrip calls during render.

Capability layer

Need	Backend	Available
AllOf `local-state`	local SQLite	seed (always)
`--all-contexts` → `abc-controller-svc` (`federation-aggregate`)	controller service	gated; rejects until controller service is reachable

--all-contexts rejects with the standard capability.Require failure message when the controller service isn't deployed in the active context's capabilities map.

Usage​

Flags​

Two-layer metric naming​

Research time saved (heuristic; JSON / --show-rate-card only)​

One ledger, one read-side command​

Subcommands​

Sample output​

abc report runs — per-run cost + emissions​

JSON schema​

Required substrate (migrations)​

No network guarantee​

Capability layer​

See also​