# The device profile format

*Reference for the Stringer skill. Read `embodiments.md` first — that is the how.
This is the machine-readable what: the format a device profile is written in, so
tools, manufacturers and other agents can produce and consume them.*

A **device profile** is what one person learned about one model of hardware,
written down so the next owner of that model spends minutes rather than a day.

---

## §0. Where the profiles are

```
GET /v0/reference/profiles.json                    the catalogue
GET /v0/reference/profiles/<id>.json               one profile
```

The catalogue carries, for each profile, its `id`, `vendor`, `model`, the
capability names it claims, and a **`recognise_by`** block — the handful of facts
that let you decide *is this my machine* before downloading anything: what
`/proc/device-tree/model` says, the architecture, the OS, which I²C address ACKs,
what the camera offers.

Match on those, not on the model name. Vendors reuse names across revisions, and
the same board ships under several. If nothing matches, you are the first person
here with that hardware — `embodiments.md` is the how, and writing a profile
afterwards is what makes you the last person to spend a day on it.

**A recorded result is evidence about somebody else's machine.** Run the probes
on your own unit regardless of how confidently a profile speaks.

## §1. The one rule that makes a shared catalogue safe

**A profile contains declarations and human-readable procedure. It never contains
executable code.**

We cannot enforce this. A profile is a file, your robot is your machine, and
there is no runtime we control on either. So the format is designed so that
enforcement is not what protects you:

* A profile that could ship a script to run on your robot would be a supply-chain
  attack with a friendly name — one malicious entry reaching every owner who
  imports it, with their own privileges, on a machine with motors.
* A profile that ships only claims and prose has a worst case of **lying about
  what the hardware can do**, which your own probes catch on first contact.

So a profile may **name** a driver (`some_package.adapters.thing:make_driver`)
and **describe** what to build. It may not carry either. Two habits that cost
nothing and are not enforcement: record **provenance** (who characterised this,
when, against which firmware), and **run the probes yourself** rather than
trusting recorded results. A probe run on your own machine is the only evidence
about your own machine.

## §2. Shape

```jsonc
{
  "identity":    { },   // how to recognise this model on the machine
  "provenance":  { },   // who characterised it, when, on what
  "claims":      { },   // the manifest: verbs, consent_tiers, sensing, mobility, expressive
  "what_the_claims_do_not_mean": { },   // REQUIRED. See §4.
  "evidence":    [ ],   // per claim: which probe, when, what it returned
  "environment": { },   // autostart entries, device holders, vendor limits
  "prerequisites": { }, // per CAPABILITY, with disk costs and what breaks without
  "build":       { },   // what had to be written, and where it lives
  "live":        { },   // REQUIRED if you claim live_video. See §4c of embodiments.md
  "hazards":     { },   // slug -> free text, symptom first
  "known_gaps":  { },   // slug -> what this unit cannot do, and why
  "human_confirmations": [ ]  // things no machine can decide. See §5.
}
```

## §3. JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Stringer device profile",
  "type": "object",
  "required": ["identity", "provenance", "claims",
               "what_the_claims_do_not_mean", "evidence", "prerequisites",
               "build", "hazards"],
  "properties": {
    "identity": {
      "type": "object",
      "required": ["vendor", "model", "recognise_by"],
      "properties": {
        "vendor": { "type": "string" },
        "model": { "type": "string" },
        "recognise_by": {
          "type": "object",
          "description": "Observable facts that identify this model on a machine."
        }
      }
    },
    "provenance": {
      "type": "object",
      "required": ["characterised_by", "characterised_on"],
      "properties": {
        "characterised_by": { "type": "string" },
        "characterised_on": { "type": "string", "format": "date" },
        "firmware": { "type": "string" },
        "unit": { "type": "string" }
      }
    },
    "claims": {
      "type": "object",
      "description": "The manifest, exactly as the driver declares it.",
      "properties": {
        "verbs": {
          "type": "array",
          "items": { "enum": ["observe", "goto", "inspect"] }
        },
        "consent_tiers": {
          "type": "array",
          "items": { "type": "integer", "enum": [0, 1, 2] }
        },
        "free_text_steerable": { "type": "boolean" },
        "sensing": {
          "type": "object",
          "additionalProperties": { "enum": ["none", "basic", "full"] }
        },
        "mobility": {
          "type": "object",
          "required": ["traverse", "obstacle_avoidance", "bounded_by", "live_steer"],
          "description": "ALL FOUR keys or omit the block entirely. A partial block would be stored as an invented claim about motion in somebody's home.",
          "properties": {
            "traverse": { "enum": ["none", "bounded", "free"] },
            "obstacle_avoidance": {
              "enum": ["none", "ranged", "mapped"],
              "description": "What the machine DOES. `none` includes 'has a sensor nobody reads'."
            },
            "bounded_by": { "type": "string" },
            "live_steer": { "type": "boolean" }
          }
        },
        "expressive": {
          "type": "object",
          "required": ["motion", "light", "sound"],
          "description": "All three keys or omit."
        },
        "name_detection": {
          "type": "object",
          "required": ["level"],
          "description": "Needs OCR AND a tagger -- one capability, not two. A tagger answers with offsets inside a string and has nothing to read without OCR.",
          "properties": {
            "level": { "enum": ["none", "basic", "full"] },
            "engine": { "type": "string", "maxLength": 64 }
          }
        }
      }
    },
    "what_the_claims_do_not_mean": {
      "type": "object",
      "description": "REQUIRED. Per claim, the honest limits. See §4.",
      "minProperties": 1,
      "additionalProperties": { "type": "string" }
    },
    "evidence": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["claim", "probe", "when", "result"],
        "properties": {
          "claim": { "type": "string" },
          "probe": { "type": "string", "description": "What was RUN. Not an argument." },
          "when": { "type": "string", "format": "date" },
          "result": { "type": "string", "description": "What it returned, with numbers." }
        }
      }
    },
    "environment": {
      "type": "object",
      "description": "A one-shot at boot and a continuous fight look identical from ONE observation.",
      "properties": {
        "autostart": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["entry", "runs", "effect"],
            "properties": {
              "entry": { "type": "string" },
              "runs": { "type": "string" },
              "effect": { "type": "string" }
            }
          }
        },
        "device_holders": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["device", "held_by", "blocking"],
            "properties": {
              "device": { "type": "string" },
              "held_by": { "type": "string" },
              "blocking": { "type": "boolean" },
              "note": { "type": "string" }
            }
          }
        },
        "vendor_limits": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["what", "stated_in", "enforced_by_vendor"],
            "properties": {
              "what": { "type": "string" },
              "stated_in": { "type": "string" },
              "enforced_by_vendor": { "type": "boolean" },
              "why_not": { "type": "string" },
              "reimplemented_at": {
                "type": "string",
                "description": "Where WE enforce it. A limit the vendor states and does not apply must be re-implemented on our side."
              }
            }
          }
        }
      }
    },
    "prerequisites": {
      "type": "object",
      "required": ["by_capability"],
      "properties": {
        "venv": { "type": "object" },
        "by_capability": {
          "type": "array",
          "description": "PER CAPABILITY, never a blanket list -- that is what lets an owner decline a capability and skip its dependency.",
          "items": {
            "type": "object",
            "required": ["capability", "package", "source", "disk_mb", "without_it"],
            "properties": {
              "capability": { "type": "string" },
              "package": { "type": "string" },
              "source": { "type": "string" },
              "disk_mb": { "type": "integer", "minimum": 0 },
              "without_it": {
                "type": "string",
                "description": "What BREAKS. 'no sealed delivery' is checkable; 'needed for crypto' is not."
              }
            }
          }
        }
      }
    },
    "build": {
      "type": "object",
      "required": ["driver_factory", "files"],
      "properties": {
        "driver_factory": {
          "type": "string",
          "description": "A NAME, never code. module:callable."
        },
        "media_delivery_factory": { "type": "string" },
        "robot_specific_files": {
          "type": "array",
          "description": "What the NEXT body would have to write. Everything else is inherited."
        },
        "inherited_unchanged": { "type": "array" },
        "files": { "type": "array", "items": { "type": "string" } }
      }
    },
    "live": {
      "type": "object",
      "description": "REQUIRED WHEN claims.redaction.live IS ANYTHING BUT none -- that IS how a body claims the live lane; there is no separate media or kinds field, and a cold reader of this schema on 2026-09-05 found the old wording ('if this body claims live_video') pointed at a field that does not exist. Added 2026-09-03: five of the seven failures on the reference robot were live-lane failures and NOTHING in this schema could express any of them. See embodiments.md 4c.",
      "required": ["publish_resolution", "detect_measured_at", "frame_budget_ms",
                   "topology", "max_fps", "detector"],
      "properties": {
        "publish_resolution": {
          "type": "string",
          "description": "WxH the lane actually publishes, e.g. \"1280x720\".",
          "pattern": "^[0-9]+x[0-9]+$"
        },
        "detect_measured_at": {
          "type": "string",
          "description": "WxH the detection cost below was measured at. IT MUST EQUAL publish_resolution. A body declared 5 fps and delivered 2.1 because 121 ms was measured at 640x480 for a lane running 1280x720 -- four times the pixels, internally consistent, and consistent about the wrong frame size. Every slot it could not fill was published black.",
          "pattern": "^[0-9]+x[0-9]+$"
        },
        "frame_budget_ms": {
          "type": "object",
          "description": "Measured on REAL frames, not noise -- a cascade early-rejects on noise and crawls on structure. The profile keeps the three parts; the MANIFEST carries their SUM as one integer, redaction.frame_budget_ms, beside max_fps -- the number the watcher's screen is built from (embodiments.md 4c rule 3).",
          "required": ["capture", "detect", "encode"],
          "properties": {
            "capture": { "type": "number" },
            "detect": { "type": "number" },
            "encode": { "type": "number" }
          }
        },
        "topology": {
          "type": "string",
          "enum": ["colocated", "remote"],
          "description": "A remote sidecar stops paying for the encode, which moves the rate by ~50%. A body whose sidecar moves must re-declare."
        },
        "max_fps": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "DERIVED from frame_budget_ms and topology, never chosen. Declaring a rate the body cannot reach is not optimism: every missed slot is a black frame."
        },
        "missed_slot_policy": {
          "type": "string",
          "enum": ["hold_last_frame", "black"],
          "description": "hold_last_frame re-sends the last ALREADY-REDACTED picture for a bounded window. black is what this body did and it is why an owner watched a stream that was 58% black while every counter climbed -- black frames decode perfectly."
        },
        "detector": {
          "type": "object",
          "description": "A tag says a detector RAN. It does not say a face was destroyed.",
          "required": ["name", "recall_measured_on"],
          "properties": {
            "name": { "type": "string", "description": "e.g. \"yunet\", \"haar_frontal\"." },
            "model": { "type": "string", "description": "File and version, if it has weights." },
            "recall_measured_on": {
              "type": "string",
              "description": "HOW ground truth was obtained, and it must not be the detector itself. A recall figure built from 'frames the detector agreed contained a face' can never discover a face class the detector never sees -- which is exactly the class that shipped."
            }
          }
        }
      }
    },
    "hazards": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": { "type": "string", "description": "Symptom first, with what it cost." },
      "description": "Keyed by a short slug, so a hazard can be CITED. An array of prose has no handle: you cannot say 'the it_cannot_see_a_drop hazard' about element 3, and nothing stops the same hazard being written twice."
    },
    "known_gaps": {
      "type": "object",
      "additionalProperties": { "type": "string" },
      "description": "Keyed by slug, for the same reason as hazards."
    },
    "human_confirmations": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "who", "when", "answer"],
        "properties": {
          "id": { "type": "string" },
          "who": { "type": "string" },
          "when": { "type": "string", "format": "date" },
          "answer": { "type": "string" }
        }
      }
    }
  }
}
```

## §4. Why `what_the_claims_do_not_mean` is required

A capability word is a promise, and the useful half is usually the limit. Real
examples from a real profile:

* **`obstacle_avoidance: ranged`** — *one forward-facing cone. It sees a wall
  ahead. It does NOT see a chair leg to the side, a cat, or a step down.* The
  reference robot drove under a chair while its sensor read 0.408 m clear,
  because chair legs are thin and the seat is above sensor height. That is
  `ranged` behaving exactly as specified.
* **`consent_tiers: [0, 2]`** — *video at ~1 fps with **no audio track***,
  because the only speech recognition on that machine is cloud-based.
* **face redaction** — *frontal only. A face turned away is not detected and is
  therefore not blurred.* `best_effort` is the accurate word, not a formality.

A profile without this section is advertising. **The schema requires at least one
entry.**

## §5. Human confirmations: what no machine can decide

Some questions have no automated answer, and inventing a heuristic for them is
worse than leaving them open — it converts a loud unknown into a quiet wrong.
The canonical one:

> **Has a person looked at a captured frame from this body and confirmed it shows
> what a mission would need to see?**

No count answers that. A profile records the answer with **who** and **when** —
*who* because it is testimony, *when* because firmware and rooms both change. A
confirmation without both does not count.

## §6. Variants, not edits

If your unit differs — different firmware, a missing sensor, a vendor app version
that clamps a servo range — **the profile gains a variant. It is not edited into a
lie.** The probes are what tell you which you have, and they are the reason the
format carries `provenance` and `evidence` rather than bare claims.
