commit · Umwelt docs

Reference/Commands/commit

commitcommandsince 0.1

Writes one event with its records and transitions, atomically: all of it or nothing.

Command lineTypeScript.NET

Request

umwelt call story.umw commit '{
  "projectId": "ball",
  "attemptId": "scene-1",
  "event": {
    "id": "scene-1",
    "type": "scene",
    "title": "The ball",
    "position": { "tick": 1 },
    "participants": ["ana", "bob", "duchess"],
    "provenance": { "origin": { "kind": "human" } }
  },
  "records": [
    {
      "kind": "fact",
      "id": "theft",
      "position": { "tick": 1 },
      "provenance": { "origin": { "kind": "human" } },
      "claim": {
        "subject": "bob",
        "predicate": "stole",
        "object": { "kind": "entity", "id": "necklace" },
        "polarity": true
      }
    },
    {
      "kind": "holding",
      "id": "ana-saw",
      "position": { "tick": 1 },
      "provenance": { "origin": { "kind": "human" } },
      "holder": "ana",
      "attitude": "knows",
      "confidence": 1,
      "accessibility": "available",
      "acquisition": { "kind": "witnessed", "eventId": "scene-1" },
      "claim": {
        "subject": "bob",
        "predicate": "stole",
        "object": { "kind": "entity", "id": "necklace" },
        "polarity": true
      }
    },
    {
      "kind": "holding",
      "id": "bob-did",
      "position": { "tick": 1 },
      "provenance": { "origin": { "kind": "human" } },
      "holder": "bob",
      "attitude": "knows",
      "confidence": 1,
      "accessibility": "available",
      "acquisition": { "kind": "witnessed", "eventId": "scene-1" },
      "claim": {
        "subject": "bob",
        "predicate": "stole",
        "object": { "kind": "entity", "id": "necklace" },
        "polarity": true
      }
    }
  ]
}'

Request

const result = await client.commit({
  projectId: 'ball',
  attemptId: 'scene-1',
  event: {
    id: 'scene-1',
    type: 'scene',
    title: 'The ball',
    position: { tick: 1 },
    participants: ['ana', 'bob', 'duchess'],
    provenance: provenance,
  },
  records: [
    {
      kind: 'fact',
      id: 'theft',
      position: { tick: 1 },
      provenance: provenance,
      claim: theft,
    },
    {
      kind: 'holding',
      id: 'ana-saw',
      position: { tick: 1 },
      provenance: provenance,
      holder: 'ana',
      attitude: 'knows',
      confidence: 1,
      accessibility: 'available',
      acquisition: { kind: 'witnessed', eventId: 'scene-1' },
      claim: theft,
    },
    {
      kind: 'holding',
      id: 'bob-did',
      position: { tick: 1 },
      provenance: provenance,
      holder: 'bob',
      attitude: 'knows',
      confidence: 1,
      accessibility: 'available',
      acquisition: { kind: 'witnessed', eventId: 'scene-1' },
      claim: theft,
    },
  ],
});

Request

var result = engine.Commit(new CommitInput
{
    ProjectId = "ball",
    AttemptId = "scene-1",
    Event = new EventInput
    {
        Id = "scene-1",
        Type = "scene",
        Title = "The ball",
        Position = new Position { Tick = 1 },
        Participants = new() { "ana", "bob", "duchess" },
        Provenance = provenance,
    },
    Records = new()
    {
        new RecordInput.Fact
        {
            Id = "theft",
            Position = new Position { Tick = 1 },
            Provenance = provenance,
            Claim = theft,
        },
        new RecordInput.Holding
        {
            Id = "ana-saw",
            Position = new Position { Tick = 1 },
            Provenance = provenance,
            Holder = "ana",
            Attitude = Attitude.Knows,
            Confidence = 1.0,
            Accessibility = Accessibility.Available,
            Acquisition = new Acquisition.Witnessed { EventId = "scene-1" },
            Claim = theft,
        },
        new RecordInput.Holding
        {
            Id = "bob-did",
            Position = new Position { Tick = 1 },
            Provenance = provenance,
            Holder = "bob",
            Attitude = Attitude.Knows,
            Confidence = 1.0,
            Accessibility = Accessibility.Available,
            Acquisition = new Acquisition.Witnessed { EventId = "scene-1" },
            Claim = theft,
        },
    },
});

Response

{
  "eventId": "scene-1",
  "recordIds": ["theft", "ana-saw", "bob-did"],
  "transitionIds": [],
  "version": 2,
  "warnings": []
}

Payload

Field	Type	Description
`projectId`required	string	The project to write to.
`attemptId`required	string	Makes a retry safe: the same request with the same attempt id is applied once.
`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 the event writes: Facts, Holdings, Awareness and Dispositions.
`transitions`	TransitionInput[]default []	Status changes of existing records: `retracted`, `revoked`, `forgotten`, `abandoned` or `superseded`.
`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
`eventId`always	string	The event written, with the id given or generated.
`recordIds`always	string[]	The records written, in order.
`transitionIds`always	string[]	The transitions written, in order.
`version`always	integer	The version this commit received. Reads at an earlier `asOfVersion` do not see it.
`warnings`	Warning[]	`UNKNOWN_PREDICATE` (open vocabulary) or `SECRET_BREACH`. Warnings never block a write.

Rules

All of it or nothing. One invalid record refuses the whole commit, and nothing is written.

The same attempt is applied once. Sending the same request again with the same attemptId returns the stored outcome.

At least one record or transition. An event alone is refused.

Being present grants nothing. Participants of the event hold nothing unless a Holding of theirs is written.

Errors

VALIDATION_FAILEDThe payload is malformed, a reference does not exist, a predicate is undefined in a strict project, or the commit carries no record or transition.

NOT_FOUNDThe project or timeline does not exist.

VERSION_CONFLICTexpectedVersion is no longer the head of the timeline.

CONFLICTThe attemptId was already used with a different request.

CONFLICTAn event, record or transition id already exists.

INVALID_STATEThe timeline is a draft that was promoted or discarded, and accepts no more writes.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also