org.simocracy.ballot

Documentation

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).

main record

Record Key tid Timestamp-based ID

Properties

createdAt string datetime Required

An RFC 3339 formatted timestamp.

gatheringUri string Required

Scope identifier: usually the AT-URI of an org.simocracy.gathering record; a sentinel string for built-in scopes (e.g. "ftc-sf:tower").

mechanism string Required

Versioned mechanism id that elicited this ballot, e.g. "s-process@1" or "quadratic-voting@1".

maxLength: 64 bytes

payload union Required

Mechanism-specific ballot content.

Known types:

#mvfBallot
#creditsBallot

round integer Optional

Deliberation round this ballot was cast in (0-based). Omitted for single-round runs.

minimum: 0

run string Required

Run identifier this ballot belongs to. Matches the run's org.simocracy.history `hearingId` and the published decision's `runId`.

maxLength: 64 bytes

simName string Optional

Display name of the sim at cast time (denormalised for cheap rendering).

maxLength: 200 bytes

simUri string Required

AT-URI of the org.simocracy.sim that cast this ballot.

View raw schema

{
  "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)."
}

creditEntry object

No description available.

Properties

credits integer Required

Voice credits spent on this proposal (integer, whole credits).

minimum: 0maximum: 100

proposal string Required

AT-URI of the proposal (org.hypercerts.claim.activity), or a "title:<title>" fallback key.

proposalTitle string Optional

Display title at cast time.

maxLength: 500 bytes

View raw schema

{
  "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 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.

Properties

credits array of ref#creditEntry Required

No description available.

maxLength: 100 items

reasoning string Optional

The sim's in-character reasoning for this spread.

maxLength: 10000 bytesmaxGraphemes: 5000 graphemes

View raw schema

{
  "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."
}

mvfBallot object

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

Properties

evaluations array of ref#mvfEvaluation Required

No description available.

maxLength: 100 items

outsideOptionMilli integer Optional

Marginal value of keeping a dollar for future rounds, ×1000 (fixed-point: 500 = 0.5).

minimum: 0

View raw schema

{
  "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."
}

mvfEvaluation object

No description available.

Properties

mvf array of ref#mvfPoint Required

Piecewise-linear marginal value function, points sorted ascending by dollars.

maxLength: 20 items

proposal string Required

AT-URI of the evaluated proposal (org.hypercerts.claim.activity), or a "title:<title>" fallback key when the URI could not be resolved.

proposalTitle string Optional

Display title at cast time.

maxLength: 500 bytes

reasoning string Optional

The sim's in-character reasoning for this curve.

maxLength: 10000 bytesmaxGraphemes: 5000 graphemes

View raw schema

{
  "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."
    }
  }
}

mvfPoint object

No description available.

Properties

dollars integer Required

Funding level in whole USD.

minimum: 0

marginalValueMilli integer Required

Value-per-dollar of the next dollar at this funding level, ×1000 (fixed-point: 1500 = 1.5).

minimum: 0

View raw schema

{
  "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)."
    }
  }
}