# Selected knowledge sources

> Capture internal Blop run aggregates and link user-authored requirement revisions to independently recorded evidence without claiming compliance.

These sources use [organization memory](/cloud/organization-memory/), its existing permissions and explicit publication. They never upload local notes automatically.

## Internal analytics snapshots

Supported metrics are `run_count` and `run_pass_rate`, definition version 1. They read retained Blop control-plane runs, not local traces or external analytics providers. Pass rate is the percentage of **all** matching runs whose status is `passed`; queued/running/failed rows remain in the denominator.

Canonical operations are `analytics.source.status`, `.select`, `.capture` and `.observation`. Native APIs use `/api/projects/PROJECT_ID/analytics/source`: GET/PUT selection, POST/GET `/observations`. Discover their current schemas with `blop cloud operations --profile work --json`.

An owner reviews selection input through the existing approval flow:

```json
{
  "params": { "projectId": "PROJECT_UUID" },
  "body": { "expectedSelectionId": null, "metricId": "run_pass_rate" }
}
```

Save that input as `selection.json` and call:

```bash
blop cloud call analytics.source.select --input selection.json --profile work --json
```

Pending approval is not selection. After approval, read status for its selection UUID. A member with `blop:write` can deliberately capture:

```json
{
  "params": { "projectId": "PROJECT_UUID" },
  "body": {
    "requestId": "NEW_REQUEST_UUID",
    "selectionId": "APPROVED_SELECTION_UUID",
    "window": {
      "from": "2026-11-01T00:00:00.000Z",
      "to": "2026-11-02T00:00:00.000Z"
    }
  }
}
```

Use `analytics.source.capture` with that file. Windows are UTC, half-open `[from,to)`, nonfuture and at most 400 days. Each bounded scalar observation includes definition hash, unit, project, window, capture time, sample count, value and `data`/`no_data`. Empty count is zero; empty rate is null. A measured zero rate is data.

Request UUID replay returns the original snapshot; changed input conflicts. Late-ingested or edited runs can change a new capture of the same window. No polling or graph insertion occurs. Deliberately authored findings may cite its exact `blop.analytics` reference. The reference uses the retained UUID, full observation SHA-256 and native path. Snapshots expire after 24 hours; project ownership, grants, app enablement and selection are rechecked. Reselection/disable hides old references without deleting authored text. Retention follows project lifetime, independently of graph purge.

Disable with `metricId: null` and the current `expectedSelectionId`, through owner review.

Capture replay and recorded-action inspection recheck server-side source authorization.
While it remains authorized, replay returns the exact retained result without
refreshing capture time, observation identity, hash or citation. Otherwise, an
inspectable completed action keeps its status but replaces `data` with an explicit
content-free receipt:

```json
{
  "kind": "analytics-source-receipt/v1",
  "redacted": true,
  "actionId": "ACTION_UUID",
  "operationId": "analytics.source.capture",
  "requestId": "ORIGINAL_REQUEST_UUID",
  "selectionId": "ORIGINAL_SELECTION_UUID",
  "contentHash": "ORIGINAL_OBSERVATION_SHA256"
}
```

That receipt has no observation body, source UUID, path or usable citation. The
original action and idempotency binding remain retained. Loss of the originating
grant can deny the request or action entirely; a receipt never grants access.

Producer `/api/ingest` reserves the whole `blop.analytics` source, including future
event types. It responds with HTTP 422 and `code: "reserved_source"`, naming that
source, and writes no event. Internal owner-approved writers remain supported.
If an older malformed selection journal exists, reads stay unavailable; they do
not fall back to older consent. An owner can approve a **new** `.select` action,
using the last valid selection UUID as `expectedSelectionId` (or null after a
valid disable/no valid selection). The preceding owner action retains that
identity. Wrong identities still conflict. Recovery appends new consent, preserves
malformed audit rows and never revives captures from the older selection.

## User-authored requirement evidence

Select one hosted document or published Markdown section revision as one requirement. In **Memory**, open it and use **Selected requirement coverage**. Nothing interprets other documents, frontmatter or operation approval as policy.

Read once with `[]` to obtain the exact reference pin. Independently save a finding through existing memory writes, with a `supports` relation targeting that document. Its `sources` contain the `blop.requirement` pin **and** independent evidence references. The pin is linkage metadata, never evidence. It binds document ID/revision plus SHA-256 of UTF-8 canonical JSON:

```json
{"schemaVersion":"blop.requirement-content/v1","title":"Exact title","body":"Exact full body"}
```

Field order is exactly as shown, with compact JSON and no Unicode normalization or trimming. Publication strips local relationships; hosted associations require a separate deliberate write. A new requirement revision invalidates old pins, even if text is restored.

The existing memory family exposes the same read through CLI and hosted MCP:

```json
{
  "nodeId": "REQUIREMENT_NODE_ID",
  "revision": 1,
  "projectId": "PROJECT_UUID",
  "evidenceNodeIds": ["FINDING_NODE_ID"]
}
```

Call `blop cloud call memory.requirements.coverage --input coverage.json --profile work --json`. Select at most 20 unique findings. Complete oversized results are rejected, not silently truncated.

| State | Meaning within the explicit selection |
| --- | --- |
| `supported_evidence` | An exact authored association has accessible reference metadata. Relevance and satisfaction are **not assessed**. |
| `missing` | No evidence records selected; not a claim that none exist. |
| `expired` | Selected evidence references have expired. |
| `inaccessible` | Selected references are unavailable or local-only. |
| `unknown` | Unsupported/inexact/redacted references, stale pins or inactive knowledge. |

Coverage preserves provenance and always reports satisfaction `not_assessed`. No evidence bodies are assessed. Denied references contribute no identifiers or hidden counts. Configured assessment failures remain fail-closed. Local edit/deletion/detach does not unpublish a deliberately shared hosted snapshot; use hosted edit/retire/purge.

## Unsupported external sources

This contract provides no live Mixpanel, Amplitude, Vanta, Drata or SOC 2/standards-provider connector. It neither fetches standards text nor certifies compliance. Existing selected Linear/Jira/GitHub sources retain their own contracts; internal analytics and user-authored requirements do not qualify external authentication, live providers or model quality.