context.admit · Umwelt docs

Reference/Queries/context.admit

context.admitquerysince 0.1

Decides which records and events may enter a context for a perspective, within a budget, with a reason for every refusal.

Command lineTypeScript.NET

Request

umwelt call story.umw context.admit '{
  "projectId": "ball",
  "holder": "ana",
  "at": { "tick": 3 },
  "budget": 3,
  "candidates": [
    { "id": "c1", "recordId": "ana-saw", "cost": 2, "priority": 2 },
    { "id": "c2", "eventId": "scene-1", "cost": 1, "priority": 1 },
    { "id": "c3", "recordId": "theft" },
    { "id": "c4", "recordId": "bob-hid" }
  ]
}'

Request

const result = await client.contextAdmit({
  projectId: 'ball',
  holder: 'ana',
  at: { tick: 3 },
  budget: 3,
  candidates: [
    { id: 'c1', recordId: 'ana-saw', cost: 2, priority: 2 },
    { id: 'c2', eventId: 'scene-1', cost: 1, priority: 1 },
    { id: 'c3', recordId: 'theft' },
    { id: 'c4', recordId: 'bob-hid' },
  ],
});

Request

var result = engine.ContextAdmit(new ContextAdmitInput
{
    ProjectId = "ball",
    Holder = "ana",
    At = new At { Tick = 3 },
    Budget = 3,
    Candidates = new()
    {
        new ContextCandidate
        {
            Id = "c1",
            RecordId = "ana-saw",
            Cost = 2,
            Priority = 2,
        },
        new ContextCandidate
        {
            Id = "c2",
            EventId = "scene-1",
            Cost = 1,
            Priority = 1,
        },
        new ContextCandidate { Id = "c3", RecordId = "theft" },
        new ContextCandidate { Id = "c4", RecordId = "bob-hid" },
    },
});

Response

{
  "admitted": [
    { "id": "c1", "recordId": "ana-saw", "cost": 2, "priority": 2 },
    { "id": "c2", "eventId": "scene-1", "cost": 1, "priority": 1 }
  ],
  "rejected": [
    { "id": "c3", "recordId": "theft", "reason": "not-held" },
    { "id": "c4", "recordId": "bob-hid", "reason": "not-held" }
  ],
  "usedBudget": 3
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`holder`	string	Whose perspective. Absent: the narrator’s, who sees everything visible at the position.
`budget`	integer	The total cost allowed. Absent: no limit.
`candidates`required	ContextCandidate[]	What you would like to include: your own `id`, exactly one of `recordId` and `eventId`, a `cost` (default 1), a `priority` (default 0) and an optional `classification`.
`authorizedNarrator`	booleandefault false	Confirms the caller may see withheld knowledge.
`excludeClassifications`	string[]default []	Classifications to refuse, such as `spoiler`.
`includeWithheld`	booleandefault false	Admit suppressed and inaccessible Holdings. Requires `authorizedNarrator`.
`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
`admitted`always	ContextAdmitted[]	Admitted candidates, highest priority first (ties keep input order).
`rejected`always	ContextRejected[]	Refused candidates, in input order, each with its `reason`.
`usedBudget`always	integer	The cost of what was admitted.

Rules

Checks run in order. A refused candidate reports the first one it fails: invalid-candidate, not-in-project, future, not-on-axis, inactive, not-held, withheld, excluded-classification, duplicate, over-budget.

Being present grants nothing. An event is admitted for a holder only when they hold a Holding witnessed there. Facts are never in a holder’s perspective.

The budget is filled by priority. Survivors are taken by priority while they fit; a smaller candidate later in the list may still fit.

Errors

VALIDATION_FAILEDThe payload is malformed, or includeWithheld is asked without authorizedNarrator.

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