compare · Umwelt docs

Reference/Queries/compare

comparequerysince 0.1

What two holders hold side by side: what they share, what only one holds and where they disagree.

Command lineTypeScript.NET

Request

umwelt call story.umw compare '{
  "projectId": "ball",
  "a": "ana",
  "b": "duchess",
  "at": { "tick": 3 }
}'

Request

const result = await client.compare({ projectId: 'ball', a: 'ana', b: 'duchess', at: { tick: 3 } });

Request

var result = engine.Compare(new ComparePayload
{
    ProjectId = "ball",
    A = "ana",
    B = "duchess",
    At = new At { Tick = 3 },
});

Response

{
  "conflicting": [
    {
      "a": {
        "kind": "holding",
        "id": "ana-saw",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "scene-1",
        "holder": "ana",
        "claim": {
          "subject": "bob",
          "predicate": "stole",
          "object": { "kind": "entity", "id": "necklace" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "knows",
        "confidence": 1.0,
        "accessibility": "available",
        "acquisition": { "kind": "witnessed", "eventId": "scene-1" },
        "position": { "tick": 1 },
        "provenance": { "origin": { "kind": "human" } },
        "recordedAt": 2
      },
      "b": {
        "kind": "holding",
        "id": "duchess-told",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "01a1cbd8-63e1-79d0-b8d5-e4ba0f31c843",
        "holder": "duchess",
        "claim": {
          "subject": "bob",
          "predicate": "stole",
          "object": { "kind": "entity", "id": "necklace" },
          "polarity": false,
          "qualifiers": {}
        },
        "attitude": "believes",
        "confidence": 0.8,
        "accessibility": "available",
        "acquisition": {
          "kind": "told-by",
          "intent": "unknown",
          "sourceHolderId": "bob",
          "sourceRecordId": "bob-did"
        },
        "position": { "tick": 3 },
        "provenance": { "origin": { "kind": "system", "name": "umwelt:transmit" } },
        "recordedAt": 4
      },
      "claimKey": "9190cc6f09646e8a3c8a74744d3e40477182a00d36dfdaa214b9fcdb99b0f5dd"
    }
  ],
  "counts": { "conflicting": 1, "onlyA": 0, "onlyB": 1, "shared": 0 },
  "onlyA": [],
  "onlyB": [
    {
      "b": {
        "kind": "holding",
        "id": "duchess-mask",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "arrivals",
        "holder": "duchess",
        "claim": {
          "subject": "bob",
          "predicate": "umwelt:alias",
          "object": { "kind": "value", "value": "the masked guest" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "knows",
        "confidence": 1.0,
        "accessibility": "available",
        "acquisition": { "kind": "witnessed", "eventId": "arrivals" },
        "position": { "tick": 0 },
        "provenance": { "origin": { "kind": "human" } },
        "recordedAt": 1
      },
      "claimKey": "ec0cdc2f805f03411aefd12cb5d01d96239a761fa236c7378686a8815b92cb56"
    }
  ],
  "shared": []
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`a`required	string	The first holder.
`b`required	string	The second holder.
`at`	Atdefault {}	Where both are read, and where `a` is read when `atB` is given.
`atB`	At	Where `b` is read. Defaults to `at`, and may be on another axis.
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`shared`always	CompareEntry[]	Claims both hold with the same polarity.
`onlyA`always	CompareEntry[]	Claims only `a` holds.
`onlyB`always	CompareEntry[]	Claims only `b` holds.
`conflicting`always	CompareEntry[]	Claims both hold with opposite polarities.
`counts`always	CompareCounts	How many entries each list has.

Each entry carries the claimKey and the Holding of each side that has one.

Rules

Two clocks. With atB, each holder is read at their own position, so a reader in chapter 12 can be compared with a character at story tick 10.

Nothing is merged. Each side is read from its own Holdings only.

Errors

VALIDATION_FAILEDThe payload is malformed.

NOT_FOUNDThe project, a holder or the timeline does not exist, or the draft read was purged.

INVALID_STATEThe timeline read is a draft that was promoted. details.promotedInto names the timeline to read instead.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also