ProtoPart Definition System

How domains, resources, functions, interfaces, harnesses, and rulesets model parts and score compatibility.

A ProtoPart is any device or component that can operate in one or more domains (electrical, mechanical, pneumatic, etc.). It contains Resources, Interfaces, and Rulesets that describe what it can do and how it can connect to other parts. Each ProtoPart is versioned, carries metadata (manufacturer, datasheet, tags), and can include presets for common interfaces (for example, a “3-wire servo connection”).

Why not just call them components? Because the word “component” is already taken by everything. ProtoParts give this system a distinct identity. Self-aware? A little. Useful? Very.

---

Domain

A Domain defines the scope of meaning for capabilities and constraints.

Examples:

• Electrical (voltage, current, signals)

• Mechanical (torque, shafts, mounting patterns)

• Pneumatic (pressure, flow, ports)

• Network (protocols, bitrates, addresses)

Domains ensure properties are measured with consistent units and checked with the right rules.

---

Resource

A Resource is an endpoint within a ProtoPart. It can be a pin, port, shaft, mounting hole, communication channel, or a software topic.

Each Resource has:

• A Domain (electrical, pneumatic, etc.)

• Capabilities (max voltage, torque rating, flow rate, protocol support)

• Shareability (can it be shared or is it exclusive)

• Cardinality (how many functions it can serve at once)

• Optional Resource Groups for bulk rules (e.g., all pins in the same GPIO bank)

---

Function

A Function is a specific purpose a Resource can serve, such as “power supply at 5 V,” “ground return,” “PWM signal,” or “air inlet.”

Functions are tied to a Domain and usually carry parameters (like frequency for PWM or required flow rate for pneumatic). When building a system, Functions are assigned to Resources to fulfill interface requirements.

---

Interface

An Interface is a defined connection between two ProtoParts. Think “a bundle of functions with extra parameters.”

It requires one or more Functions and ensures that Resources on each part are mapped to those Functions.

Example servo interface requires:

• A power function (5 V supply at 0.6 A)

• A ground return function

• A PWM signal function

Interfaces also capture topology (point-to-point, bus, star) and may include constraints like address uniqueness or bandwidth requirements.

Protocol and role

Protocol is the “type” and “role” an interface declares to determine compatibility. These come from a protocol specification file that defines allowed protocol types and roles. Use only types from this allowlist. Adding a brand-new type is possible, but it starts out incompatible with existing parts until others adopt it.

Protocol example (JSON):

{
  "id": "analog_input",
  "protocol": {
    "type": "analog",
    "role": "receiver"
  },
  "requires": [
    { "function": "analog_input", "count": 1 }
  ],
  "constraints": {
    "max_connections": 1,
    "requires_matching_voltage_domain": true
  },
  "description": "Analog input interface",
  "name": "Analog Input"
}

---

Harness

A Harness is the single logical “cable” or connection bundle between parts. It groups multiple Interfaces into one carrier.

To the user, it may appear as a single line in a diagram. Under the hood it carries mapped signals, power rails, or pneumatic channels. Harnesses can include physical constraints (length, wire gauge, connector type, bend radius) and can specify a consolidated pinout.

---

Resource Group

A Resource Group is a logical grouping of Resources, typically for shared constraints.

Example: all GPIO pins in a single microcontroller bank. Rules can apply to the group, such as “only one of these pins can be used for hardware I²C at a time.”

---

Ruleset

A Ruleset defines constraints, compatibility checks, and budgets. Scope can be a Resource, Resource Group, Interface, Harness, ProtoPart, or the entire project.

Examples:

• “The 5 V regulator must not exceed its total current budget.”

• “Two I²C devices cannot use the same address on the same bus.”

• “Hose diameter must support required airflow for given length.”

Rulesets can be hard errors or warnings and may include suggested fixes (“insert external regulator” or “move device to different bus”). Not lava, but still hot.

---

Board

A Board is the collection of all ProtoParts, Interfaces, Harnesses, and Rulesets in a single design. It also stores user feedback, verification outcomes, and proposed fixes. This is the project scope where everything is validated.

---

Compatibility and Scoring

The system uses deterministic rules plus an LLM-based agent layer.

Three axes, one scoreboard:

Axis	What it checks	Examples
Architectural	Static fit from definitions, capabilities, rules	Voltage levels, torque ratings, connector matches
Behavioral (Flow)	Dynamic fit in context	Bandwidth, timing, bus load, current headroom, airflow margins
Sentimental	Human feedback and community signal	Reviews, user reports, app notes, reliability anecdotes

Each axis yields a score between 0 and 1. Scores combine with configurable weights. Hard architectural failures cap the total score. Feelings don’t override physics.

---

Evidence and Feedback

The system tracks evidence sources: datasheets, documentation, reviews, project logs. Evidence can boost confidence or flag issues. User actions (accepting an autofix or rejecting a connection) feed the sentiment layer to improve future recommendations. Your taste becomes training data, minus the coffee breath.

---

Allocation and Verification Flow

1. Connect — Link two parts with a single harness.

2. Select — Choose the specific interfaces that should be linked.

3. Match — Candidate Resources are found that satisfy the interface functions.

4. Assign — Resources are bound and reserved.

5. Validate — Rulesets run from lowest scope (resources) up to highest (project).

6. Score — Architectural, Behavioral, and Sentimental evaluations are combined.

7. Report — System outputs pass/fail, warnings, diagnostics, and suggested fixes.

8. Commit — Valid connections are locked in; invalid ones prompt autofix options.