trace · Umwelt docs

Reference/Queries/trace

tracequerysince 0.1

How a record came to be: its event, its transitions, and every link of who told whom, back to the source.

Command lineTypeScript.NET

Request

umwelt call story.umw trace '{
  "projectId": "ball",
  "recordId": "maid-heard"
}'

Request

const result = await client.trace({ projectId: 'ball', recordId: 'maid-heard' });

Request

var result = engine.Trace(new RecordId { ProjectId = "ball", RecordIdValue = "maid-heard" });

Response

{
  "chain": [
    {
      "acquisition": {
        "kind": "told-by",
        "intent": "honest",
        "sourceHolderId": "ana",
        "sourceRecordId": "ana-saw"
      },
      "record": {
        "kind": "holding",
        "id": "maid-heard",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "01a1cbd8-63e8-77c0-bd7b-9f83f9bfaff7",
        "holder": "maid",
        "claim": {
          "subject": "bob",
          "predicate": "stole",
          "object": { "kind": "entity", "id": "necklace" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "believes",
        "confidence": 0.9,
        "accessibility": "available",
        "acquisition": {
          "kind": "told-by",
          "intent": "honest",
          "sourceHolderId": "ana",
          "sourceRecordId": "ana-saw"
        },
        "position": { "tick": 5 },
        "provenance": { "origin": { "kind": "system", "name": "umwelt:transmit" } },
        "recordedAt": 7
      }
    },
    {
      "acquisition": { "kind": "witnessed", "eventId": "scene-1" },
      "record": {
        "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
      }
    }
  ],
  "event": {
    "id": "01a1cbd8-63e8-77c0-bd7b-9f83f9bfaff7",
    "projectId": "ball",
    "timelineId": "main",
    "title": "Transmission",
    "position": { "tick": 5 },
    "evidence": [],
    "participants": ["ana", "maid"],
    "provenance": { "origin": { "kind": "system", "name": "umwelt:transmit" } },
    "recordedAt": 7,
    "type": "umwelt:transmit"
  },
  "record": {
    "kind": "holding",
    "id": "maid-heard",
    "projectId": "ball",
    "timelineId": "main",
    "eventId": "01a1cbd8-63e8-77c0-bd7b-9f83f9bfaff7",
    "holder": "maid",
    "claim": {
      "subject": "bob",
      "predicate": "stole",
      "object": { "kind": "entity", "id": "necklace" },
      "polarity": true,
      "qualifiers": {}
    },
    "attitude": "believes",
    "confidence": 0.9,
    "accessibility": "available",
    "acquisition": {
      "kind": "told-by",
      "intent": "honest",
      "sourceHolderId": "ana",
      "sourceRecordId": "ana-saw"
    },
    "position": { "tick": 5 },
    "provenance": { "origin": { "kind": "system", "name": "umwelt:transmit" } },
    "recordedAt": 7
  },
  "transitions": [],
  "truncated": false
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`recordId`required	string	The record to trace.
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`record`always	Record	The record traced.
`event`always	Event	The event it was written in.
`transitions`always	Transition[]	Every transition of the record, in order.
`status`	"retracted" \| "revoked" \| "forgotten" \| "abandoned" \| "superseded"	The status of its latest transition, if it has one.
`chain`always	ChainLink[]	The record, then the record it was told from, and so on: each link with its acquisition.
`truncated`always	boolean	True when the chain stopped at 32 links or found a loop.

Rules

The chain follows `told-by`. Each link is the sourceRecordId of the one before. It ends at a Holding acquired another way: witnessed, from evidence, inferred or authored.

No position. A trace reads the whole timeline, with the same visibility as other reads but without at.

Errors

VALIDATION_FAILEDThe payload is malformed.

NOT_FOUNDThe project, record or 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