perspective · Umwelt docs

Reference/Queries/perspective

perspectivequerysince 0.1

Everything a holder holds, is aware of and feels at a position: their whole point of view in one read.

Command lineTypeScript.NET

Request

umwelt call story.umw perspective '{
  "projectId": "ball",
  "holder": "duchess",
  "at": { "tick": 3 }
}'

Request

const result = await client.perspective({ projectId: 'ball', holder: 'duchess', at: { tick: 3 } });

Request

var result = engine.Perspective(new PerspectivePayload
{
    ProjectId = "ball",
    Holder = "duchess",
    At = new At { Tick = 3 },
});

Response

{
  "holder": {
    "id": "duchess",
    "projectId": "ball",
    "name": "The duchess",
    "aliases": [],
    "typeId": "person",
    "archived": false,
    "createdAt": { "tick": 0 },
    "fields": {}
  },
  "awareness": [
    {
      "kind": "awareness",
      "id": "duchess-sees-bob",
      "projectId": "ball",
      "timelineId": "main",
      "eventId": "arrivals",
      "holder": "duchess",
      "target": "bob",
      "position": { "tick": 0 },
      "provenance": { "origin": { "kind": "human" } },
      "recordedAt": 1
    }
  ],
  "dispositions": [],
  "holdings": [
    {
      "acquisition": { "kind": "witnessed", "eventId": "arrivals" },
      "record": {
        "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
      }
    },
    {
      "acquisition": {
        "kind": "told-by",
        "intent": "unknown",
        "sourceHolderId": "bob",
        "sourceRecordId": "bob-did"
      },
      "record": {
        "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
      }
    }
  ],
  "memberships": [],
  "withheldCount": 0
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`holder`required	string	The agent or group asked about.
`at`	Atdefault {}	Where to read: `tick`, an optional `axis`, and `asOfVersion`. Defaults to the latest.
`page`	Pagedefault {"limit":100}	Pages the Holdings: `limit` (1 to 1000) and `cursor`.
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`holder`always	Entity	The holder.
`holdings`always	HoldingItem[]	Their Holdings, each with its acquisition, one page at a time.
`awareness`always	Record[]	The entities they know exist.
`dispositions`always	Record[]	How they stand toward others: trust, fear, affection.
`memberships`always	Record[]	The groups they belong to at the position: active `umwelt:member-of` Facts about them.
`withheldCount`always	integer	Suppressed or inaccessible Holdings left out.

Rules

Canon never appears here. A perspective holds only the holder’s own records. The single exception is their memberships, which say which groups they belong to, not what those groups know.

A group knows only its own Holdings. What its members hold is never added to it.

The teller’s intent is not shown. A Holding the holder was told reads intent: "unknown", even when the telling was recorded as deceptive: the holder does not know they were lied to. See transmit.

Errors

VALIDATION_FAILEDThe payload is malformed, or the page limit is outside 1 to 1000.

NOT_FOUNDThe project, holder 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