# Module Descriptor Specification

## Purpose
This document defines the minimum descriptor every BloxCore module must expose so the platform can identify, validate, and manage it safely.

## Goals
- provide deterministic module discovery
- support compatibility checks before activation
- enforce power and thermal policy
- expose a stable software contract for BloxOS services

## Descriptor Format
The transport encoding may change by hardware generation, but the logical schema must remain stable and versioned.

```json
{
  "descriptor_version": 1,
  "vendor_id": "0x1201",
  "product_id": "0x0007",
  "module_class": "camera",
  "module_name": "Wide Camera Gen1",
  "hardware_revision": "A",
  "firmware_version": "1.0.0",
  "protocol_version": 1,
  "power": {
    "nominal_w": 1.8,
    "peak_w": 3.2,
    "startup_inrush_w": 4.0
  },
  "thermal": {
    "max_surface_c": 52,
    "throttle_start_c": 45
  },
  "dependencies": [
    {
      "type": "compute_capability",
      "value": "camera-pipeline-v1"
    }
  ],
  "capabilities": [
    "camera.wide",
    "camera.flash-sync"
  ],
  "security": {
    "signed_firmware": true,
    "attestation_required": false
  }
}
```

## Required Fields
- `descriptor_version`: schema version
- `vendor_id`: manufacturer identifier
- `product_id`: product identifier
- `module_class`: one of `power`, `compute`, `camera`, `sensor`, `connectivity`, `io`
- `module_name`: human-readable module name
- `hardware_revision`: physical revision code
- `firmware_version`: loaded firmware version
- `protocol_version`: supported BloxLink protocol version
- `power`: nominal, peak, and startup budget
- `thermal`: thermal guardrail values
- `dependencies`: required capabilities or adjacent modules
- `capabilities`: software-visible capabilities
- `security`: attestation and signing requirements

## Validation Rules
The platform must reject or degrade a module if:

1. `descriptor_version` is unsupported
2. `module_class` is unknown
3. `protocol_version` is incompatible with the core controller
4. peak or inrush power exceeds available budget
5. required dependencies are missing
6. required security checks fail

## State Integration
The descriptor is consumed at these lifecycle stages:

1. `Detected`: transport presence only
2. `ElectricallyQualified`: power and physical readiness confirmed
3. `Authenticated`: security checks applied
4. `Enumerated`: descriptor parsed and validated
5. `DriverBound`: capability-specific service started

## Versioning Policy
- increment `descriptor_version` only for schema changes
- increment `protocol_version` for wire-level or controller-level compatibility changes
- keep `firmware_version` module-specific
- BloxOS must support a compatibility table, not a single hardcoded version

## Design Notes
- descriptors must be small enough for fast enumeration
- descriptors must not require network access to validate
- optional vendor extensions must live under a namespaced extension field in future revisions