check.utterance · Umwelt docs

Reference/Queries/check.utterance

check.utterancequerysince 0.1

Checks claims a holder says or thinks against what they hold, and tells canon apart.

Command lineTypeScript.NET

Request

umwelt call story.umw check.utterance '{
  "projectId": "ball",
  "holder": "ana",
  "at": { "tick": 1 },
  "claims": [
    {
      "subject": "bob",
      "predicate": "stole",
      "object": { "kind": "entity", "id": "necklace" },
      "polarity": true
    },
    {
      "subject": "necklace",
      "predicate": "hidden-in",
      "object": { "kind": "entity", "id": "garden" },
      "polarity": true
    }
  ]
}'

Request

const result = await client.checkUtterance({
  projectId: 'ball',
  holder: 'ana',
  at: { tick: 1 },
  claims: [
    theft,
    {
      subject: 'necklace',
      predicate: 'hidden-in',
      object: { kind: 'entity', id: 'garden' },
      polarity: true,
    },
  ],
});

Request

var result = engine.CheckUtterance(new CheckUtteranceInput
{
    ProjectId = "ball",
    Holder = "ana",
    At = new At { Tick = 1 },
    Claims = new()
    {
        theft,
        new Claim
        {
            Subject = "necklace",
            Predicate = "hidden-in",
            Object = new ClaimObject.Entity { Id = "garden" },
            Polarity = true,
        },
    },
});

Response

{
  "consistent": false,
  "items": [
    {
      "verdict": "holds",
      "canon": "agrees",
      "attitude": "knows",
      "confidence": 1.0,
      "recordId": "ana-saw",
      "canonRecordId": "theft",
      "claimKey": "9190cc6f09646e8a3c8a74744d3e40477182a00d36dfdaa214b9fcdb99b0f5dd"
    },
    {
      "verdict": "future",
      "canon": "no-canon",
      "recordId": "ana-heard",
      "claimKey": "fb7e886399ca844e9184785a9752971231623a58d64e7bf37c9116cfa4089328"
    }
  ]
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`holder`required	string	The agent or group asked about.
`claims`required	Claim[]	The claims to check, from your application or a model it runs. The engine never reads free text.
`at`	Atdefault {}	Where to read: `tick`, an optional `axis`, and `asOfVersion`. Defaults to the latest.
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`consistent`always	boolean	True when every claim has the verdict `holds`.
`items`always	UtteranceCheck[]	One verdict per claim, in order.

Each item has the verdict, the canon status (agrees, contradicts or no-canon) with canonRecordId, and the holder’s recordId, attitude and confidence when a Holding is behind the verdict.

Rules

Six verdicts. holds, holds-opposite, holds-other-value (another value in a functional slot), withheld (held but suppressed or inaccessible), future (held only later: an anachronism) and unknown.

Canon is reported, never granted. A claim canon agrees with is still unknown when the holder does not hold it.

Errors

VALIDATION_FAILEDThe payload is malformed, or a claim is.

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