source-evidence

Expose audience-safe verification evidence

Install

docsloth component add @docsloth/source-evidence@1.0.0

Live package: sha256:91585e02b9857ea171bd85a49520fd59109b6d4190ca3c4b2a521c28e0f7e972 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/source-evidence.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "fact_id": "00000000-0000-4000-8000-000000000000",
  "show_commit": true,
  "show_test_status": true,
  "allow_source_excerpt": true
}

Required props: fact_id, show_commit, show_test_status, allow_source_excerpt.

Example

Example document IR (the block the renderer consumes):

{
  "type": "source-evidence",
  "props": {
    "title": "example-title",
    "fact_id": "00000000-0000-4000-8000-000000000000",
    "show_commit": true,
    "show_test_status": true,
    "allow_source_excerpt": true
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-source-evidence" data-component="source-evidence" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>Shows</dt>
<dd>source commit, test status, source excerpt</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Evidence is not available in this static view. The host must supply audience-permitted evidence for this fact.</p>
</section>

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/source-evidence.md.

Contract

Production props are normative in ../contracts/component-props/source-evidence.schema.json. The corresponding component-fixtures manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated component-package.json manifest plus props.schema.json (the production props schema, copied byte-for-byte) and spec.md (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

Intended behavior

Show audience-permitted evidence and exact verification method/status.

Failure and fallback

Private source returns public-safe evidence category only.

Current React behavior

The component uses production fact_id to read the optional evidence map from ComponentContentProvider (@docsloth/official-components/host). Hosts supply only evidence already authorized for this audience and release. Available records contain a public category, optional summary, exact verification status/method, commit, excerpt and independently authorized source link. Restricted records contain only a public-safe category. Missing records are explicitly unavailable; not_run, failed, unsupported and unknown results never become verified. Display flags control commit, verification and excerpt presentation. They grant no access and do not make private fields safe to serialize to a browser. The host must omit unauthorized bytes. Complete escaped excerpts use native details/summary and remain usable without JavaScript; unsafe or credential-bearing links stay text-only. The static IR reports unavailable evidence instead of promising it exists elsewhere. This package does not fetch evidence, run verification, authorize source destinations or dispatch agent tools; those integrations remain host work.

Required acceptance cases

Claim not_run never shown verified, link ACL independent. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/source-evidence.json.

Sources