troubleshooter

Diagnose an authorized redacted error

Install

docsloth component add @docsloth/troubleshooter@1.0.0

Live package: sha256:cc7e3d2eb1477955fbf83cf9c13259694d866a527aff89adc764974179b19498 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/troubleshooter.schema.json.

Example props generated from this schema:

{
  "title": "example-title",
  "error_catalog_ref": "example-error_catalog_ref",
  "scope": {
    "publication_id": "00000000-0000-4000-8000-000000000000",
    "fact_ids": [
      "00000000-0000-4000-8000-000000000000"
    ],
    "evidence_ids": [
      "00000000-0000-4000-8000-000000000000"
    ]
  },
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "allow_log_upload": true
}

Required props: error_catalog_ref, scope, allow_log_upload.

Example

Example document IR (the block the renderer consumes):

{
  "type": "troubleshooter",
  "props": {
    "title": "example-title",
    "error_catalog_ref": "example-error_catalog_ref",
    "scope": {
      "publication_id": "00000000-0000-4000-8000-000000000000",
      "fact_ids": [
        "00000000-0000-4000-8000-000000000000"
      ],
      "evidence_ids": [
        "00000000-0000-4000-8000-000000000000"
      ]
    },
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "allow_log_upload": true
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-block ds-troubleshooter" data-component="troubleshooter" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>Error catalog</dt>
<dd>
<code>example-error_catalog_ref</code>
</dd>
</div>
<div>
<dt>Log upload</dt>
<dd>Allowed</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Diagnosing an error needs the live documentation site.</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/troubleshooter.md.

Contract

Production props are normative in ../contracts/component-props/troubleshooter.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

Redact error/log text before submission, match versioned error catalog, show diagnosis uncertainty.

Failure and fallback

Unknown error offered as hypothesis, not confirmed root cause.

Required acceptance cases

PII fixture is masked; proposed dangerous remediation cannot execute automatically. 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.

React implementation

The release-scoped ComponentContentProvider.errorCatalogs map binds error_catalog_ref to an already authorized catalog with an exact publication_id, immutable version, and plain-text entries. Each entry has id, title, literal match terms, hypothesis, manual checks, fact_ids and evidence_ids. The renderer includes only entries within the production scope; this filtering does not replace host audience authorization. Restricted/loading/missing bindings have explicit states. Catalog browsing and manual checks are readable without JavaScript.

Hydration enables local text entry, optional local file reading when allow_log_upload is true, and an explicit redacted-text review before literal catalog matching. Common email, numeric identifier, IP, credential-header/assignment, key and user-path patterns are masked. Arbitrary personal names and unusual secrets are not guaranteed to be detected. No text is submitted by this component, stored in browser persistence, copied automatically, or sent to an executor/model. File reading is local, not a connected upload service. Host telemetry must separately respect sensitive input. Results remain hypotheses; checks are escaped prose and never commands to run.

Inputs are limited to 32,768 characters and files to 65,536 bytes. Catalogs allow 200 entries, eight 128-character literal terms per entry, ten 1,000-character checks, and 500,000 combined characters including provenance IDs. At most five matching hypotheses are shown. Release, catalog-version or allowed-entry changes reset local text, and late file reads cannot restore cleared/replaced text. Resource and agent execution integration remains a host responsibility.

Package manifest

Protocol fixture: packages/contracts/component-fixtures/troubleshooter.json.

Sources