witness · Umwelt docs

Reference/Commands/witness

witnesscommandsince 0.1

Everyone at a scene sees the same claims: one commit, one Holding per witness and claim.

Command lineTypeScript.NET

Request

umwelt call story.umw witness '{
  "projectId": "ball",
  "attemptId": "search",
  "event": {
    "id": "search",
    "type": "scene",
    "title": "The search of the garden",
    "position": { "tick": 4 },
    "participants": ["maid", "butler"],
    "provenance": { "origin": { "kind": "human" } }
  },
  "claims": [
    {
      "claim": {
        "subject": "necklace",
        "predicate": "hidden-in",
        "object": { "kind": "entity", "id": "garden" },
        "polarity": true
      }
    }
  ],
  "witnesses": [
    { "holder": "maid", "recordIds": ["maid-found"] },
    { "holder": "butler", "recordIds": ["butler-found"] }
  ]
}'

Request

const result = await client.witness({
  projectId: 'ball',
  attemptId: 'search',
  event: {
    id: 'search',
    type: 'scene',
    title: 'The search of the garden',
    position: { tick: 4 },
    participants: ['maid', 'butler'],
    provenance: provenance,
  },
  claims: [
    {
      claim: {
        subject: 'necklace',
        predicate: 'hidden-in',
        object: { kind: 'entity', id: 'garden' },
        polarity: true,
      },
    },
  ],
  witnesses: [
    { holder: 'maid', recordIds: ['maid-found'] },
    { holder: 'butler', recordIds: ['butler-found'] },
  ],
});

Request

var result = engine.Witness(new WitnessInput
{
    ProjectId = "ball",
    AttemptId = "search",
    Event = new EventInput
    {
        Id = "search",
        Type = "scene",
        Title = "The search of the garden",
        Position = new Position { Tick = 4 },
        Participants = new() { "maid", "butler" },
        Provenance = provenance,
    },
    Claims = new()
    {
        new WitnessedClaim
        {
            Claim = new Claim
            {
                Subject = "necklace",
                Predicate = "hidden-in",
                Object = new ClaimObject.Entity { Id = "garden" },
                Polarity = true,
            },
        },
    },
    Witnesses = new()
    {
        new Witness { Holder = "maid", RecordIds = new() { "maid-found" } },
        new Witness
        {
            Holder = "butler",
            RecordIds = new() { "butler-found" },
        },
    },
});

Response

{
  "eventId": "search",
  "recordIds": ["maid-found", "butler-found"],
  "transitionIds": [],
  "version": 5,
  "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.
`claims`required	WitnessedClaim[]	What was seen. With `canon: true`, a claim is also recorded as a Fact, with `factId` as its id.
`witnesses`required	Witness[]	Who saw it: `holder`, and optionally `attitude` (default `knows`), `confidence` (default 1), `accessibility` (default `available`) and `recordIds`, one per claim.
`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

Acquired as witnessed. Every Holding is acquired witnessed at the event.

Retries are recognized. The attempt fingerprint comes from the request, so a retry is recognized even when ids were generated.

Only witnesses hold. Other participants of the event hold nothing.

Errors

VALIDATION_FAILEDThe payload is malformed, a witness appears twice, or gives a number of recordIds other than one per claim.

NOT_FOUNDThe project, a holder or the timeline does not exist.

VERSION_CONFLICTexpectedVersion is no longer the head of the timeline.

CONFLICTThe attemptId was already used with a different request.

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