---
title: "actor.wait@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/actor.wait"
updated: null
---

# actor.wait@1 · OpenVibe.Services

HTML: [actor.wait@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/actor.wait)

# ActorWait `actor.wait@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: actor
- Visibility: public
- Status: active
- Compatibility: backward
- Decision: [ADR-044](/docs/adr/ADR-044)
- Schema: [`https://openvibe.network/contracts/actor/wait.v1.json`](/docs/contracts/actor.wait.json)

actor.wait@1: one wait (plan A2, Watch mode): the task and the step it belongs to, whose it is, what wakes it (until), the deadline, what happens when nothing comes (on\_timeout) and the short line the person reads. A wait is a record, not a running loop: while a task waits, no model runs, its desk is released and its budget clock stops. The event that woke it is untrusted input: woken\_by names the event, never its payload.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string | yes |  | - `pattern ^wai_[0-9A-HJKMNP-TV-Z]{26}$` |
| `task_id` | string | yes |  | - `pattern ^tsk_[0-9A-HJKMNP-TV-Z]{26}$` |
| `requester` | string | yes |  | - `pattern ^(user\|app\|agent\|service):[a-z]+_[0-9A-HJKMNP-TV-Z]{26}$` |
| `kind` | enum | yes |  | - `one of "event", "watch", "time"` |
| `until` | `https://openvibe.network/contracts/actor/wait.v1.json#/$defs/until` | yes |  |  |
| `filter` | object |  | The bounded matcher: a path (payload.a.b, subject.id, subject.type, actor.id, trace\_id) and the value (or one of the values) the event must carry there. At most eight clauses; a filter is a matcher, not a query. |  |
| `deadline_at` | string | yes |  | - `format date-time` |
| `on_timeout` | enum | yes |  | - `one of "ask", "retry", "fail"` |
| `line` | string | yes |  | - `minLength 1`<br>- `maxLength 200` |
| `status` | enum | yes |  | - `one of "waiting", "woken", "timed_out", "cancelled", "failed"` |
| `woken_by` | `https://openvibe.network/contracts/actor/wait.v1.json#/$defs/wokenBy` |  |  |  |
| `created_at` | string | yes |  | - `format date-time` |
| `updated_at` | string | yes |  | - `format date-time` |
| `finished_at` | string |  |  | - `format date-time` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: event-wait

~~~~
{
  "id": "wai_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "task_id": "tsk_01K6R3A1B2C3D4E5F6G7H8J9KB",
  "requester": "user:usr_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "kind": "event",
  "until": {
    "topic": "codes.task.succeeded",
    "from": "2026-10-30T16:00:00.000Z"
  },
  "filter": {
    "payload.repo": "OpenVibers/OpenVibe.Actor",
    "subject.id": "usr_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4"
  },
  "deadline_at": "2026-10-30T22:00:00.000Z",
  "on_timeout": "ask",
  "line": "waiting for your Codes task on OpenVibers/OpenVibe.Actor to finish",
  "status": "waiting",
  "created_at": "2026-10-30T16:00:00.000Z",
  "updated_at": "2026-10-30T16:00:00.000Z"
}
~~~~

Valid: woken-by-a-person

~~~~
{
  "id": "wai_01K6R3A1B2C3D4E5F6G7H8J9KC",
  "task_id": "tsk_01K6R3A1B2C3D4E5F6G7H8J9KB",
  "requester": "user:usr_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "kind": "event",
  "until": {
    "topic": "run.job.succeeded"
  },
  "filter": {
    "payload.job_id": "job_01K6R3A1B2C3D4E5F6G7H8J9KD"
  },
  "deadline_at": "2026-10-30T22:00:00.000Z",
  "on_timeout": "fail",
  "line": "waiting for your run to finish",
  "status": "woken",
  "woken_by": {
    "event_id": "evt_01K6R3A1B2C3D4E5F6G7H8J9KE",
    "event_type": "run.job.succeeded",
    "at": "2026-10-30T16:12:00.000Z",
    "by": "person"
  },
  "created_at": "2026-10-30T16:00:00.000Z",
  "updated_at": "2026-10-30T16:12:00.000Z",
  "finished_at": "2026-10-30T16:12:00.000Z"
}
~~~~

Rejected: no-line

~~~~
{
  "id": "wai_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "task_id": "tsk_01K6R3A1B2C3D4E5F6G7H8J9KB",
  "requester": "user:usr_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "kind": "event",
  "until": {
    "topic": "codes.task.succeeded"
  },
  "deadline_at": "2026-10-30T22:00:00.000Z",
  "on_timeout": "ask",
  "status": "waiting",
  "created_at": "2026-10-30T16:00:00.000Z",
  "updated_at": "2026-10-30T16:00:00.000Z"
}
~~~~

Rejected: two-kinds-of-until

~~~~
{
  "id": "wai_01K6R3A1B2C3D4E5F6G7H8J9KA",
  "task_id": "tsk_01K6R3A1B2C3D4E5F6G7H8J9KB",
  "requester": "user:usr_01K6R2Z8C4V7M9Q3T5W1X2Y3Z4",
  "kind": "event",
  "until": {
    "topic": "codes.task.succeeded",
    "watch_id": "wch_01K6R3A1B2C3D4E5F6G7H8J9KF"
  },
  "deadline_at": "2026-10-30T22:00:00.000Z",
  "on_timeout": "ask",
  "line": "waiting",
  "status": "waiting",
  "created_at": "2026-10-30T16:00:00.000Z",
  "updated_at": "2026-10-30T16:00:00.000Z"
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('actor.wait@1', value);   // { valid, errors: [{ path, message }] }
~~~~