flowchart LR
  config["Repo: KDL presentation bindings"] --> collect["Luci: validate and collect"]
  job["Job: compute and write JSON"] --> collect
  collect --> report["Immutable report"]
  collect --> assessment{"Valid eligible assessment?"}
  assessment -->|Yes| inbox["Reconcile scoped inbox"]
  assessment -->|No| retain["Preserve items; expose assessment condition"]
  report --> views["UI and CLI"]
  inbox --> views
  retain --> views

stateDiagram-v2
  [*] --> Open: Valid assessment introduces key
  Open --> Open: Key remains present
  Open --> Acknowledged: Authorized operator acknowledges
  Acknowledged --> Acknowledged: Same observation repeats
  Acknowledged --> Open: Material observation changes
  Open --> Resolved: Newer complete assessment omits key
  Acknowledged --> Resolved: Newer complete assessment omits key
  Resolved --> Open: Newer assessment reports key again

---
id: BB-SPEC-O7YWOJ6Z
type: spec
title: Luci reports and action inbox
---

# Luci reports and action inbox

## Boundary

Jobs compute observations; reports preserve evidence; inbox preserves unresolved work.
Repos decide what dependencies, versions, vulnerabilities, and remedies mean.
Luci owns provenance, validation, reconciliation, freshness, and presentation.

This extends the [Luci CI service](../BB-SPEC-251EC85B-luci-ci-service/index.md).
Action inbox ≠ execution-request queue.
No dependency database, registry adapters, vulnerability engine, mandatory SBOM/SARIF, automatic Git changes, deployment, or notification delivery.
Dynamic workflows are outside this contract.

## Repo → job → Luci

Job-level KDL declares named reports: generated JSON source, presentation bindings, optional named inbox projections.
Report names are stable and unique within each job.
Repo programs write ordinary JSON; no generated KDL, helper, custom image, injected executable, credentials, or upload API required.

One job can build, check, report, and update inbox.
Ordered commands share its child container and workspace.
Separate schedules are optional: unchanged source can be reassessed against fresh external evidence.

Runner supplies repo, exact revision, parent run, child, job, matrix identity, and observation time; producer data cannot override them.
Generated files live in disposable workspace; accepted evidence survives cleanup as immutable reports.
Collection runs after successful or failed execution, before cleanup.
Interrupted or timed-out jobs with missing outputs remain incomplete.
Publishing stays separate and success-gated.

The same execution feeds immutable evidence and persistent attention.

```mermaid
flowchart LR
  config["Repo: KDL presentation bindings"] --> collect["Luci: validate and collect"]
  job["Job: compute and write JSON"] --> collect
  collect --> report["Immutable report"]
  collect --> assessment{"Valid eligible assessment?"}
  assessment -->|Yes| inbox["Reconcile scoped inbox"]
  assessment -->|No| retain["Preserve items; expose assessment condition"]
  report --> views["UI and CLI"]
  inbox --> views
  retain --> views
```

## Presentation contract

KDL binds named fields and collections to text, scalar facts, tables, literal code, links, and collected artifacts.
Shallow sections have stable IDs.
Values retain JSON types; missing, empty, and explicitly permitted null are distinct.
Each referenced value must fit its presentation type.

Omitted column binding means exact, case-sensitive lookup by column argument.
Humanized headings never change field identity; explicit bindings separate labels from keys.
Timestamp, duration, and size formatting require explicit types, not string guessing.

Inbox collections contain actionable items already selected by repo code.
Each item has a stable key, title, summary, priority, recommendation, facts, and evidence references.
References identify named reports and sections from the same execution.
Priority is producer-reported, not Luci verification.

No `when`, expressions, programmable loops, conditional commands, or template language.
Producers filter and transform; renderers display collections.
Empty arrays are valid data.

Invalid declarations fail before execution where detectable.
Missing required fields, wrong types, duplicate item keys, and invalid references reject ingestion without defaults.
Diagnostics name report, binding, field, and expected type without exposing raw sensitive payloads.
Local validation and runtime ingestion share the same contract.
Inbox updates are atomic: validate the whole assessment before changing items.

## Reconciliation

Item identity: repo + default-branch producer + job + report + inbox name + matrix identity + item key.
Sibling jobs, matrix children, and separate assessments cannot resolve each other's items.
Producer renaming cannot silently resolve old items.

Only eligible default-branch assessments update persistent inbox.
Other revisions retain reports without closing default-branch items.
Older results cannot overwrite newer accepted assessments, regardless of completion order.
Repeated ingestion is idempotent.

Completeness is explicit, independent of command exit status:

- Complete: all current actions in scope are enumerated; omitted keys resolve, including an empty collection.
- Partial: listed observations can add/update items; omissions resolve nothing.
- Missing/malformed: preserve items; expose incomplete assessment.

A failed CI gate can still produce a complete assessment with findings.
Build color never determines item lifecycle.

```mermaid
stateDiagram-v2
  [*] --> Open: Valid assessment introduces key
  Open --> Open: Key remains present
  Open --> Acknowledged: Authorized operator acknowledges
  Acknowledged --> Acknowledged: Same observation repeats
  Acknowledged --> Open: Material observation changes
  Open --> Resolved: Newer complete assessment omits key
  Acknowledged --> Resolved: Newer complete assessment omits key
  Resolved --> Open: Newer assessment reports key again
```

Acknowledged ≠ fixed; evidence and history remain intact.
Changed title, priority, recommendation, or substantive evidence can require renewed attention; timestamps alone cannot.
Freshness, execution health, and item lifecycle remain separate.
Missing producers, overdue refreshes, and failed checkers never make old evidence look current.
Freshness expectations are explicit; unscheduled producers get no invented expiry.

## UI and CLI

`luci status` surfaces run health and inbox attention independently.
`luci inbox` lists, filters, and inspects items in human-readable and machine-readable forms.
Reports and evidence are accessible through both interfaces.
Passing builds cannot hide open items or stale/incomplete assessments.

[Visual study](report-inbox.html): information hierarchy and state distinctions, not binding pixel styling.
Attention → recommendation → facts → evidence → provenance/history.
Open, acknowledged, resolved, incomplete, and stale states use text, not color alone.
Human-friendly scalars expose exact raw values on hover/focus and copy on activation, including touch.
Commands and long evidence remain inspectable and copyable, never executable UI actions.
Code/log highlighting is safe; narrow/wide layouts, light/dark themes, keyboard access, and copy feedback remain usable.

Reports and inbox are public-readable.
Acknowledgement requires explicit operator authorization; public read access grants no mutation authority.

## Safety

Escape untrusted text; never interpret producer HTML, CSS, scripts, or UI plugins.
Links use safe schemes; no automatic fetching or embedding.
Artifact collection follows service limits and rejects traversal, symlinks, devices, sockets, and workspace escapes.
Document bytes, nesting, collection lengths, scalar sizes, and rendering work have documented finite limits.
Limit violations reject ingestion, never silently drop actions.
Active-content artifacts are downloads or isolated previews, never executable content on Luci's main origin.
Rendering and masking do not make secret-bearing reports safe.