propose · Umwelt docs

Reference/Commands/propose

proposecommandsince 0.1

Holds a commit for review instead of applying it.

Command lineTypeScript.NET

Request

umwelt call story.umw propose '{
  "projectId": "ball",
  "event": {
    "id": "confession",
    "type": "scene",
    "title": "The confession",
    "position": { "tick": 10 },
    "participants": ["bob", "duchess"],
    "provenance": { "origin": { "kind": "human" } }
  },
  "records": [
    {
      "kind": "holding",
      "id": "duchess-knows",
      "position": { "tick": 10 },
      "provenance": { "origin": { "kind": "human" } },
      "holder": "duchess",
      "attitude": "knows",
      "confidence": 1,
      "accessibility": "available",
      "acquisition": {
        "kind": "told-by",
        "sourceHolderId": "bob",
        "sourceRecordId": "bob-did",
        "intent": "honest"
      },
      "claim": {
        "subject": "bob",
        "predicate": "stole",
        "object": { "kind": "entity", "id": "necklace" },
        "polarity": true
      }
    }
  ],
  "transitions": [
    {
      "targetRecordId": "duchess-told",
      "status": "superseded",
      "supersededBy": "duchess-knows",
      "position": { "tick": 10 },
      "provenance": { "origin": { "kind": "human" } }
    }
  ]
}'

Request

const result = await client.propose({
  projectId: 'ball',
  event: {
    id: 'confession',
    type: 'scene',
    title: 'The confession',
    position: { tick: 10 },
    participants: ['bob', 'duchess'],
    provenance: provenance,
  },
  records: [
    {
      kind: 'holding',
      id: 'duchess-knows',
      position: { tick: 10 },
      provenance: provenance,
      holder: 'duchess',
      attitude: 'knows',
      confidence: 1,
      accessibility: 'available',
      acquisition: {
        kind: 'told-by',
        sourceHolderId: 'bob',
        sourceRecordId: 'bob-did',
        intent: 'honest',
      },
      claim: theft,
    },
  ],
  transitions: [
    {
      targetRecordId: 'duchess-told',
      status: 'superseded',
      supersededBy: 'duchess-knows',
      position: { tick: 10 },
      provenance: provenance,
    },
  ],
});

Request

var result = engine.Propose(new ProposeInput
{
    ProjectId = "ball",
    Event = new EventInput
    {
        Id = "confession",
        Type = "scene",
        Title = "The confession",
        Position = new Position { Tick = 10 },
        Participants = new() { "bob", "duchess" },
        Provenance = provenance,
    },
    Records = new()
    {
        new RecordInput.Holding
        {
            Id = "duchess-knows",
            Position = new Position { Tick = 10 },
            Provenance = provenance,
            Holder = "duchess",
            Attitude = Attitude.Knows,
            Confidence = 1.0,
            Accessibility = Accessibility.Available,
            Acquisition = new Acquisition.ToldBy
            {
                SourceHolderId = "bob",
                SourceRecordId = "bob-did",
                Intent = Intent.Honest,
            },
            Claim = theft,
        },
    },
    Transitions = new()
    {
        new TransitionInput
        {
            TargetRecordId = "duchess-told",
            Status = TransitionStatus.Superseded,
            SupersededBy = "duchess-knows",
            Position = new Position { Tick = 10 },
            Provenance = provenance,
        },
    },
});

Response

{
  "id": "01a1cbd8-63fc-7ec1-aac1-c0b733797443",
  "status": "pending",
  "input": {
    "projectId": "ball",
    "event": {
      "id": "confession",
      "title": "The confession",
      "position": { "tick": 10 },
      "evidence": [],
      "participants": ["bob", "duchess"],
      "provenance": { "origin": { "kind": "human" } },
      "type": "scene"
    },
    "records": [
      {
        "kind": "holding",
        "id": "duchess-knows",
        "holder": "duchess",
        "claim": {
          "subject": "bob",
          "predicate": "stole",
          "object": { "kind": "entity", "id": "necklace" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "knows",
        "confidence": 1.0,
        "accessibility": "available",
        "acquisition": {
          "kind": "told-by",
          "intent": "honest",
          "sourceHolderId": "bob",
          "sourceRecordId": "bob-did"
        },
        "position": { "tick": 10 },
        "provenance": { "origin": { "kind": "human" } }
      }
    ],
    "transitions": [
      {
        "status": "superseded",
        "position": { "tick": 10 },
        "provenance": { "origin": { "kind": "human" } },
        "supersededBy": "duchess-knows",
        "targetRecordId": "duchess-told"
      }
    ]
  },
  "reviews": []
}

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`event`required	EventInput	The event the records are written in: its type, title and position, and optionally its participants, location, evidence and positions on other axes.
`records`	RecordInput[]default []	The records proposed.
`transitions`	TransitionInput[]default []	The transitions proposed.
`timelineId`	stringdefault "main"	The timeline to write to.
`expectedVersion`	integer	Fails the write with `VERSION_CONFLICT` unless the timeline’s head is still this version.

Result

Field	Type	Description
`status`always	"pending" \| "applied" \| "partially-applied" \| "rejected"	`pending`, for a new proposal.
`id`always	string	The proposal’s id.
`input`always	ProposeInput	The commit it holds: the event, records and transitions, as proposed.
`reviews`	ProposalReview[]	Every review so far, oldest first. The latest one for an operation decides it.
`rejectionRationale`	string	Why it was rejected, when it was.

Rules

Operations are numbered. Records first, then transitions, from 0. Reviews name them by that index.

Nothing is written yet. The proposal is checked when it is rebased or applied, against the timeline as it is then.

Errors

VALIDATION_FAILEDThe payload is malformed.

NOT_FOUNDThe project does not exist.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also