> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/reference/rulesets-and-severity.md).

# Rulesets and Severity

Design Rule Check states, severity levels, what gets validated, and how results appear in Board Review and on the canvas.

Protoboard's Design Rule Check (DRC) engine validates every connection, resource allocation, and part-level constraint in your board. This page is the reference for what gets checked, what the result states mean, and how severity controls the build/ship decision.

***

## DRC Configuration States

Every interface link in a harness is in exactly one of four states. These states drive the color coding you see on canvas edges and handles.

| State                     | Color          | Meaning                                                                                              |
| ------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| **CONFIGURED**            | Green          | All required functions are allocated and all constraints pass. The connection is fully valid.        |
| **PARTIALLY\_CONFIGURED** | Yellow / Amber | Some but not all required functions have been allocated. The link exists but is incomplete.          |
| **NOT\_CONFIGURED**       | Gray           | The interface link exists in the harness but no resource allocation has been performed yet.          |
| **INCOMPATIBLE**          | Red            | The two interfaces cannot connect. Protocol mismatch, role conflict, or a hard constraint violation. |

{% hint style="info" %}
A harness between two parts can contain interface links in **different** states simultaneously. For example, the power link might be CONFIGURED while an I2C link is still PARTIALLY\_CONFIGURED because one of the two required function mappings has not been completed.
{% endhint %}

***

## Severity Levels

When the DRC finds a problem, it assigns one of two severity levels:

{% columns %}
{% column %}

#### Error

**Blocks the board from passing review.**

Errors represent hard failures that would cause the physical system to not work or to be unsafe. They must be resolved before the board is considered valid.

Examples:

* Protocol type mismatch between linked interfaces
* Role incompatibility (both sides are `master`)
* Required function cannot be allocated (no available resource)
* Voltage domain mismatch when `requires_matching_voltage_domain` is true
* Resource over-allocation (same resource claimed by two exclusive interfaces)
  {% endcolumn %}

{% column %}

#### Warning

**Does not block review, but flags for human attention.**

Warnings highlight conditions that are technically valid but may cause problems in practice. Reviewers should evaluate each warning and decide whether to accept or address it.

Examples:

* A power output is near its maximum current budget
* No pull-up resistors specified on an I2C bus
* A part's `design_rules` note is potentially violated by the current configuration
* A `warnings` entry from the part definition applies to the current usage
* An interface is linked but has more connections than typical for the protocol
  {% endcolumn %}
  {% endcolumns %}

***

## What the DRC Checks

The DRC runs checks at multiple scopes, from individual resources up to the full board.

{% stepper %}
{% step %}

#### Resource-Level Checks

* **Exclusive allocation:** A resource claimed by one interface cannot be claimed by another unless `shareable_with` allows it.
* **Function availability:** The required function name must exist on the resource.
* **Power domain assignment:** Resources referencing a `power_domain_id` must match a declared power domain.
  {% endstep %}

{% step %}

#### Interface-Level Checks

* **Protocol match:** Both sides of a link must have identical `protocol.type`.
* **Role compatibility:** Roles must form a recognized pair (e.g., `master`/`slave`, `output`/`input`).
* **Function completeness:** Every entry in the `requires` array must be satisfied by an allocated resource on the owning part.
* **Constraint satisfaction:** `max_connections`, `requires_matching_voltage_domain`, `requires_impedance_matching`, `requires_connector_type`, and any other constraint fields must be met.
  {% endstep %}

{% step %}

#### Harness-Level Checks

* **At least one interface link:** A harness with zero linked interfaces is flagged.
* **Cross-domain consistency:** When a protocol spans domains (e.g., PoE), both domain allocations must be present and consistent.
  {% endstep %}

{% step %}

#### Part-Level Checks

* **`design_rules` evaluation:** String-based rules from the part definition are surfaced to the user for manual review (e.g., "Maximum 40mA per I/O pin").
* **Total current budget:** Aggregate current draw across all allocated power outputs is checked against the power domain's `max_current_mA`.
* **Pin count sanity:** Total allocated resources should not exceed `pin_count` (when specified).
  {% endstep %}

{% step %}

#### Board-Level Checks

* **Unconnected parts:** Parts placed on the canvas with no harnesses are flagged as warnings.
* **Isolated subgraphs:** Groups of parts not connected to the rest of the design are noted.
* **Global power budget:** Aggregate power consumption vs. available supply.
  {% endstep %}
  {% endstepper %}

***

## Board Review

Board Review is the UI where all DRC results are presented. It aggregates every check across every harness and part into a single pass/fail summary.

### Review Structure

| Section        | Contents                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Summary**    | Overall status (Pass / Fail), total error count, total warning count.                                               |
| **By Harness** | Each harness listed with its interface links and their individual states (CONFIGURED, PARTIALLY\_CONFIGURED, etc.). |
| **By Part**    | Each part listed with its resource utilization, unallocated interfaces, and applicable design rules.                |
| **Errors**     | Flat list of all errors with the affected harness, interface, and resource identified.                              |
| **Warnings**   | Flat list of all warnings, grouped by category.                                                                     |

### Pass / Fail Criteria

| Condition          | Result                                              |
| ------------------ | --------------------------------------------------- |
| Zero errors        | **Pass** (warnings may still be present).           |
| One or more errors | **Fail**; the board cannot be considered validated. |

***

## Visual Feedback on Canvas

The canvas provides real-time visual cues so you can spot issues without opening Board Review.

### Edge Colors (Harness Lines)

| Color              | Meaning                                                            |
| ------------------ | ------------------------------------------------------------------ |
| **Green**          | All interface links in the harness are CONFIGURED.                 |
| **Yellow / Amber** | At least one link is PARTIALLY\_CONFIGURED; none are INCOMPATIBLE. |
| **Gray**           | All links are NOT\_CONFIGURED (no allocation yet).                 |
| **Red**            | At least one link is INCOMPATIBLE.                                 |

### Handle Colors (Interface Attachment Points)

Interface handles on each part node follow the same color scheme as the link they belong to. A part with multiple harnesses may show different-colored handles for different connections.

### Part Node Indicators

Parts themselves may display a small badge or outline tint when:

* They have **unconnected interfaces** that could be linked (informational).
* A **design rule** from their definition is potentially violated (warning badge).
* A **resource is over-allocated** or a hard constraint fails (error badge).

***

## Ruleset Scopes

Rules in Protoboard can attach at any level of the hierarchy:

| Scope              | Example Rule                                                       |
| ------------------ | ------------------------------------------------------------------ |
| **Resource**       | "This pin cannot exceed 40 mA."                                    |
| **Resource Group** | "Only one of these GPIO pins can serve as hardware I2C at a time." |
| **Interface**      | "Max 8 connections on this I2C bus."                               |
| **Harness**        | "Total current through this cable must not exceed 2 A."            |
| **Part**           | "VIN must be 7-12V when using external power."                     |
| **Board**          | "Total power consumption must not exceed PSU budget."              |

Rules can be **hard errors** (blocking) or **warnings** (advisory). When a rule includes a suggested fix (e.g., "insert external regulator" or "move device to a different bus"), that suggestion appears alongside the diagnostic in Board Review.

***

## Compatibility Scoring

Beyond pass/fail, Protoboard evaluates compatibility along three axes:

{% columns %}
{% column %}

#### Architectural (Static)

Based on definitions, capabilities, and constraints. Voltage levels, connector matches, protocol compatibility.

Score: 0 to 1.
{% endcolumn %}

{% column %}

#### Behavioral (Dynamic)

Based on runtime performance in context. Bandwidth, timing margins, bus load, current headroom.

Score: 0 to 1.
{% endcolumn %}

{% column %}

#### Sentimental (Human)

Based on community feedback, user reports, application notes, and reliability data. The system tracks evidence sources (datasheets, documentation, reviews, project logs) and user decisions (accepting autofixes, rejecting connections) to refine recommendations over time.

Score: 0 to 1.
{% endcolumn %}
{% endcolumns %}

These three scores combine into an overall compatibility score with configurable weights. **A hard failure in the architectural check caps the total score regardless of the other axes.** Physics constraints always override sentiment.

### Allocation and verification flow

When you connect two parts and configure the harness, Protoboard follows this sequence:

1. **Connect**: link two parts via a single harness
2. **Select**: identify which interfaces to link within the harness
3. **Match**: locate candidate resources that satisfy each interface function
4. **Assign**: bind and reserve resources (manually or via auto-allocate)
5. **Validate**: execute rulesets from resource scope upward through interface, harness, part, and board levels
6. **Score**: combine architectural, behavioral, and sentimental evaluations
7. **Report**: output pass/fail status, warnings, diagnostics, and correction suggestions
8. **Commit**: lock valid connections; offer autofix options for invalid ones

***

## Quick Reference

| Term                      | Definition                                                    |
| ------------------------- | ------------------------------------------------------------- |
| **DRC**                   | Design Rule Check, the automated validation pass.             |
| **Error**                 | A hard failure that blocks board validation.                  |
| **Warning**               | An advisory flag for human review.                            |
| **CONFIGURED**            | All functions allocated, all constraints pass.                |
| **PARTIALLY\_CONFIGURED** | Some functions allocated, link is incomplete.                 |
| **NOT\_CONFIGURED**       | Link exists but no allocation performed.                      |
| **INCOMPATIBLE**          | Connection is impossible (protocol/role/constraint mismatch). |
| **Board Review**          | The UI that presents aggregated DRC results.                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.protoboard.xyz/reference/rulesets-and-severity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.