# org.simocracy.ballot

> Published by [gainforest.earth](https://lexicon.garden/identity/did:plc:qoti4acfmc5wg6zzmtix6hse)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:qoti4acfmc5wg6zzmtix6hse/org.simocracy.ballot)
- [Documentation](https://lexicon.garden/lexicon/did:plc:qoti4acfmc5wg6zzmtix6hse/org.simocracy.ballot/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:qoti4acfmc5wg6zzmtix6hse/org.simocracy.ballot/examples)

## Definitions

### `org.simocracy.ballot`

**Type**: `record`

One sim's elicited ballot in a funding-mechanism run (S-Process, Quadratic Voting, …). Ballots are the public, replayable elicitation layer of a run: anyone can recompute the outcome by feeding a run's ballots through the mechanism's deterministic aggregator. The `payload` union carries the mechanism-specific ballot shape; new mechanisms extend the union without breaking existing readers. Written by the run initiator; the sim that cast the ballot is attributed via `simUri`. Fixed-point convention: fields ending in `Milli` store real numbers ×1000 (lexicons have no float type).

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `run` | `string` | Yes | Run identifier this ballot belongs to. Matches the run's org.simocracy.history `hearingId` and the published decision's `runId`. |
| `round` | `integer` | No | Deliberation round this ballot was cast in (0-based). Omitted for single-round runs. |
| `simUri` | `string` | Yes | AT-URI of the org.simocracy.sim that cast this ballot. |
| `payload` | `union` | Yes | Mechanism-specific ballot content. |
| `simName` | `string` | No | Display name of the sim at cast time (denormalised for cheap rendering). |
| `createdAt` | `string` (datetime) | Yes |  |
| `mechanism` | `string` | Yes | Versioned mechanism id that elicited this ballot, e.g. "s-process@1" or "quadratic-voting@1". |
| `gatheringUri` | `string` | Yes | Scope identifier: usually the AT-URI of an org.simocracy.gathering record; a sentinel string for built-in scopes (e.g. "ftc-sf:tower"). |

### `org.simocracy.ballot#mvfPoint`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `dollars` | `integer` | Yes | Funding level in whole USD. |
| `marginalValueMilli` | `integer` | Yes | Value-per-dollar of the next dollar at this funding level, ×1000 (fixed-point: 1500 = 1.5). |

### `org.simocracy.ballot#mvfBallot`

**Type**: `object`

S-Process ballot: one marginal-value function per proposal.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `evaluations` | `array` | Yes |  |
| `outsideOptionMilli` | `integer` | No | Marginal value of keeping a dollar for future rounds, ×1000 (fixed-point: 500 = 0.5). |

### `org.simocracy.ballot#creditEntry`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `credits` | `integer` | Yes | Voice credits spent on this proposal (integer, whole credits). |
| `proposal` | `string` | Yes | AT-URI of the proposal (org.hypercerts.claim.activity), or a "title:<title>" fallback key. |
| `proposalTitle` | `string` | No | Display title at cast time. |

### `org.simocracy.ballot#creditsBallot`

**Type**: `object`

Quadratic Voting ballot: voice credits spent per proposal. Effective votes are the square root of credits; a sim spends at most 100 credits per run.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `credits` | `array` | Yes |  |
| `reasoning` | `string` | No | The sim's in-character reasoning for this spread. |

### `org.simocracy.ballot#mvfEvaluation`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `mvf` | `array` | Yes | Piecewise-linear marginal value function, points sorted ascending by dollars. |
| `proposal` | `string` | Yes | AT-URI of the evaluated proposal (org.hypercerts.claim.activity), or a "title:<title>" fallback key when the URI could not be resolved. |
| `reasoning` | `string` | No | The sim's in-character reasoning for this curve. |
| `proposalTitle` | `string` | No | Display title at cast time. |

## Raw Schema

```json
{
  "id": "org.simocracy.ballot",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "run",
          "mechanism",
          "gatheringUri",
          "simUri",
          "payload",
          "createdAt"
        ],
        "properties": {
          "run": {
            "type": "string",
            "maxLength": 64,
            "description": "Run identifier this ballot belongs to. Matches the run's org.simocracy.history `hearingId` and the published decision's `runId`."
          },
          "round": {
            "type": "integer",
            "minimum": 0,
            "description": "Deliberation round this ballot was cast in (0-based). Omitted for single-round runs."
          },
          "simUri": {
            "type": "string",
            "description": "AT-URI of the org.simocracy.sim that cast this ballot."
          },
          "payload": {
            "refs": [
              "#mvfBallot",
              "#creditsBallot"
            ],
            "type": "union",
            "description": "Mechanism-specific ballot content."
          },
          "simName": {
            "type": "string",
            "maxLength": 200,
            "description": "Display name of the sim at cast time (denormalised for cheap rendering)."
          },
          "createdAt": {
            "type": "string",
            "format": "datetime"
          },
          "mechanism": {
            "type": "string",
            "maxLength": 64,
            "description": "Versioned mechanism id that elicited this ballot, e.g. \"s-process@1\" or \"quadratic-voting@1\"."
          },
          "gatheringUri": {
            "type": "string",
            "description": "Scope identifier: usually the AT-URI of an org.simocracy.gathering record; a sentinel string for built-in scopes (e.g. \"ftc-sf:tower\")."
          }
        }
      },
      "description": "One sim's elicited ballot in a funding-mechanism run (S-Process, Quadratic Voting, …). Ballots are the public, replayable elicitation layer of a run: anyone can recompute the outcome by feeding a run's ballots through the mechanism's deterministic aggregator. The `payload` union carries the mechanism-specific ballot shape; new mechanisms extend the union without breaking existing readers. Written by the run initiator; the sim that cast the ballot is attributed via `simUri`. Fixed-point convention: fields ending in `Milli` store real numbers ×1000 (lexicons have no float type)."
    },
    "mvfPoint": {
      "type": "object",
      "required": [
        "dollars",
        "marginalValueMilli"
      ],
      "properties": {
        "dollars": {
          "type": "integer",
          "minimum": 0,
          "description": "Funding level in whole USD."
        },
        "marginalValueMilli": {
          "type": "integer",
          "minimum": 0,
          "description": "Value-per-dollar of the next dollar at this funding level, ×1000 (fixed-point: 1500 = 1.5)."
        }
      }
    },
    "mvfBallot": {
      "type": "object",
      "required": [
        "evaluations"
      ],
      "properties": {
        "evaluations": {
          "type": "array",
          "items": {
            "ref": "#mvfEvaluation",
            "type": "ref"
          },
          "maxLength": 100
        },
        "outsideOptionMilli": {
          "type": "integer",
          "minimum": 0,
          "description": "Marginal value of keeping a dollar for future rounds, ×1000 (fixed-point: 500 = 0.5)."
        }
      },
      "description": "S-Process ballot: one marginal-value function per proposal."
    },
    "creditEntry": {
      "type": "object",
      "required": [
        "proposal",
        "credits"
      ],
      "properties": {
        "credits": {
          "type": "integer",
          "maximum": 100,
          "minimum": 0,
          "description": "Voice credits spent on this proposal (integer, whole credits)."
        },
        "proposal": {
          "type": "string",
          "description": "AT-URI of the proposal (org.hypercerts.claim.activity), or a \"title:<title>\" fallback key."
        },
        "proposalTitle": {
          "type": "string",
          "maxLength": 500,
          "description": "Display title at cast time."
        }
      }
    },
    "creditsBallot": {
      "type": "object",
      "required": [
        "credits"
      ],
      "properties": {
        "credits": {
          "type": "array",
          "items": {
            "ref": "#creditEntry",
            "type": "ref"
          },
          "maxLength": 100
        },
        "reasoning": {
          "type": "string",
          "maxLength": 10000,
          "description": "The sim's in-character reasoning for this spread.",
          "maxGraphemes": 5000
        }
      },
      "description": "Quadratic Voting ballot: voice credits spent per proposal. Effective votes are the square root of credits; a sim spends at most 100 credits per run."
    },
    "mvfEvaluation": {
      "type": "object",
      "required": [
        "proposal",
        "mvf"
      ],
      "properties": {
        "mvf": {
          "type": "array",
          "items": {
            "ref": "#mvfPoint",
            "type": "ref"
          },
          "maxLength": 20,
          "description": "Piecewise-linear marginal value function, points sorted ascending by dollars."
        },
        "proposal": {
          "type": "string",
          "description": "AT-URI of the evaluated proposal (org.hypercerts.claim.activity), or a \"title:<title>\" fallback key when the URI could not be resolved."
        },
        "reasoning": {
          "type": "string",
          "maxLength": 10000,
          "description": "The sim's in-character reasoning for this curve.",
          "maxGraphemes": 5000
        },
        "proposalTitle": {
          "type": "string",
          "maxLength": 500,
          "description": "Display title at cast time."
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```