AiRun `ai.run@1`

Generated at 2026-09-23 23:26:36 UTC from openvibe-contracts v0.33.0 and openvibe-sdk v0.5.0.

Version: 1.0.0
Owner: ai
Visibility: first-party
Status: active
Compatibility: backward
Decision: ADR-015
Schema: https://openvibe.network/contracts/ai/run.v1.json

A workflow run on OpenVibe.AI (ADR-015; server/runs.js decode): the `run` member of every run response (POST /api/v1/runs and the direct operations, GET /api/v1/runs/:id, cancel, retry) and each item of GET /api/v1/runs { runs }. Output is attributable to workflow + version + template version + route version + provider/model + run id, never to a person. A draft stays a draft: products store it with ai/ai_assisted authorship and publish nothing until a person reviews it. input keeps no inline media (replaced by data_url_sha256 and data_url_bytes) and no passthrough prompt ({ not_retained }); output is null until the run succeeded or was served from cache and then matches the workflow version's output_schema. requester is the token principal (service, app or mod). A run interrupted by a restart or shutdown ends failed with error.code run.interrupted.

Fields

Field	Type	Required	Description	Constraints
`id`	string	yes		`pattern ^run_[0-9A-HJKMNP-TV-Z]{26}$`
`status`	enum	yes	Terminal: succeeded, failed, cancelled, cached (a scoped cache hit, no provider call; provenance.cached_from names the run it reused).	`one of "queued", "running", "succeeded", "failed", "cancelled", "cached"`
`workflow`	object	yes		`no other fields`
`workflow.key`	string	yes
`workflow.version`	integer	yes		`minimum 1`
`template`	object \| null	yes	The prompt template of the workflow's llm step; null for workflows without one.
`route`	object \| null	yes	Provider route; version null while the route is unresolved or disabled.
`requester`	identity.subject-ref	yes
`on_behalf_of`	one of	yes
`attribution`	one of	yes
`source_service`	string \| null	yes	The requester's service id when the requester is a service.
`target`	one of	yes
`input`	object	yes	The retained input (see the description).
`output`	object \| null	yes	Workflow output, or null.
`error`	object \| null	yes
`synthetic`	boolean	yes	Produced by the stub provider; never served to production callers and never cached.
`provenance`	object	yes		`no other fields`
`provenance.origin`	const	yes		`= "ai"`
`provenance.workflow`	string	yes
`provenance.workflow_version`	integer	yes		`minimum 1`
`provenance.template_version`	integer \| null	yes
`provenance.route`	string \| null	yes
`provenance.route_version`	integer \| null	yes
`provenance.provider`	string \| null	yes
`provenance.model`	string \| null	yes
`provenance.fallback_used`	boolean	yes	The primary provider was degraded and the run fell back (ADR-015: fallbacks are recorded).
`provenance.run_id`	string	yes		`pattern ^run_[0-9A-HJKMNP-TV-Z]{26}$`
`provenance.cached_from`	string \| null	yes		`pattern ^run_[0-9A-HJKMNP-TV-Z]{26}$`
`provenance.synthetic`	boolean	yes
`usage`	object	yes		`no other fields`
`usage.tokens_in`	integer	yes		`minimum 0`
`usage.tokens_out`	integer	yes		`minimum 0`
`usage.cost_usd`	number	yes		`minimum 0`
`usage.attempts`	integer	yes	Provider calls made (skipped routes not counted).	`minimum 0`
`citations_count`	integer	yes	Citations stored for the run (GET /api/v1/runs/:id/citations): the sources the workflow was given, and any the requester attached later.	`minimum 0`
`retry_of`	string \| null	yes		`pattern ^run_[0-9A-HJKMNP-TV-Z]{26}$`
`idempotency_key`	string \| null	yes
`trace_id`	string \| null	yes
`created_at`	string	yes		`format date-time`
`started_at`	string \| null	yes		`format date-time`
`finished_at`	string \| null	yes		`format date-time`

Examples

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

Valid: queued-passthrough

{
  "id": "run_01JAB2C3D4E5F6G7H8J9K0MNPR",
  "status": "queued",
  "workflow": {
    "key": "news.summarize_story",
    "version": 2
  },
  "template": null,
  "route": {
    "key": "live.{stream}.vision",
    "version": null
  },
  "requester": {
    "type": "service",
    "id": "news"
  },
  "on_behalf_of": null,
  "attribution": null,
  "source_service": "news",
  "target": {
    "service": "news",
    "type": "story",
    "id": "sty_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "input": {
    "not_retained": "passthrough prompt; see input_hash"
  },
  "output": null,
  "error": null,
  "synthetic": false,
  "provenance": {
    "origin": "ai",
    "workflow": "news.summarize_story",
    "workflow_version": 2,
    "template_version": 3,
    "route": "default.text",
    "route_version": 1,
    "provider": null,
    "model": null,
    "fallback_used": false,
    "run_id": "run_01JAB2C3D4E5F6G7H8J9K0MNPR",
    "cached_from": null,
    "synthetic": false
  },
  "usage": {
    "tokens_in": 0,
    "tokens_out": 0,
    "cost_usd": 0,
    "attempts": 0
  },
  "citations_count": 0,
  "retry_of": null,
  "idempotency_key": null,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "created_at": "2026-09-23T10:00:00.000Z",
  "started_at": null,
  "finished_at": null
}

Valid: succeeded

{
  "id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "status": "succeeded",
  "workflow": {
    "key": "news.summarize_story",
    "version": 2
  },
  "template": {
    "key": "news.summarize_story",
    "version": 3
  },
  "route": {
    "key": "default.text",
    "version": 1
  },
  "requester": {
    "type": "service",
    "id": "news"
  },
  "on_behalf_of": null,
  "attribution": null,
  "source_service": "news",
  "target": {
    "service": "news",
    "type": "story",
    "id": "sty_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "input": {
    "topic": "Transit strike",
    "sources": [
      {
        "source_type": "news.item",
        "source_id": "itm_42"
      }
    ]
  },
  "output": {
    "headline": "Transit strike begins",
    "summary": "Workers walked out.",
    "citations": [
      0
    ],
    "gaps": []
  },
  "error": null,
  "synthetic": false,
  "provenance": {
    "origin": "ai",
    "workflow": "news.summarize_story",
    "workflow_version": 2,
    "template_version": 3,
    "route": "default.text",
    "route_version": 1,
    "provider": "anthropic",
    "model": "claude-sonnet",
    "fallback_used": true,
    "run_id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
    "cached_from": null,
    "synthetic": false
  },
  "usage": {
    "tokens_in": 1200,
    "tokens_out": 300,
    "cost_usd": 0.0081,
    "attempts": 2
  },
  "citations_count": 1,
  "retry_of": null,
  "idempotency_key": null,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "created_at": "2026-09-23T10:00:00.000Z",
  "started_at": "2026-09-23T10:00:00.050Z",
  "finished_at": "2026-09-23T10:00:04.200Z"
}

Rejected: no-usage

{
  "id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "status": "succeeded",
  "workflow": {
    "key": "news.summarize_story",
    "version": 2
  },
  "template": {
    "key": "news.summarize_story",
    "version": 3
  },
  "route": {
    "key": "default.text",
    "version": 1
  },
  "requester": {
    "type": "service",
    "id": "news"
  },
  "on_behalf_of": null,
  "attribution": null,
  "source_service": "news",
  "target": {
    "service": "news",
    "type": "story",
    "id": "sty_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "input": {
    "topic": "Transit strike",
    "sources": [
      {
        "source_type": "news.item",
        "source_id": "itm_42"
      }
    ]
  },
  "output": {
    "headline": "Transit strike begins",
    "summary": "Workers walked out.",
    "citations": [
      0
    ],
    "gaps": []
  },
  "error": null,
  "synthetic": false,
  "provenance": {
    "origin": "ai",
    "workflow": "news.summarize_story",
    "workflow_version": 2,
    "template_version": 3,
    "route": "default.text",
    "route_version": 1,
    "provider": "anthropic",
    "model": "claude-sonnet",
    "fallback_used": true,
    "run_id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
    "cached_from": null,
    "synthetic": false
  },
  "citations_count": 1,
  "retry_of": null,
  "idempotency_key": null,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "created_at": "2026-09-23T10:00:00.000Z",
  "started_at": "2026-09-23T10:00:00.050Z",
  "finished_at": "2026-09-23T10:00:04.200Z"
}

Rejected: unknown-status

{
  "id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "status": "done",
  "workflow": {
    "key": "news.summarize_story",
    "version": 2
  },
  "template": {
    "key": "news.summarize_story",
    "version": 3
  },
  "route": {
    "key": "default.text",
    "version": 1
  },
  "requester": {
    "type": "service",
    "id": "news"
  },
  "on_behalf_of": null,
  "attribution": null,
  "source_service": "news",
  "target": {
    "service": "news",
    "type": "story",
    "id": "sty_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "input": {
    "topic": "Transit strike",
    "sources": [
      {
        "source_type": "news.item",
        "source_id": "itm_42"
      }
    ]
  },
  "output": {
    "headline": "Transit strike begins",
    "summary": "Workers walked out.",
    "citations": [
      0
    ],
    "gaps": []
  },
  "error": null,
  "synthetic": false,
  "provenance": {
    "origin": "ai",
    "workflow": "news.summarize_story",
    "workflow_version": 2,
    "template_version": 3,
    "route": "default.text",
    "route_version": 1,
    "provider": "anthropic",
    "model": "claude-sonnet",
    "fallback_used": true,
    "run_id": "run_01JAB2C3D4E5F6G7H8J9K0MNPQ",
    "cached_from": null,
    "synthetic": false
  },
  "usage": {
    "tokens_in": 1200,
    "tokens_out": 300,
    "cost_usd": 0.0081,
    "attempts": 2
  },
  "citations_count": 1,
  "retry_of": null,
  "idempotency_key": null,
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "created_at": "2026-09-23T10:00:00.000Z",
  "started_at": "2026-09-23T10:00:00.050Z",
  "finished_at": "2026-09-23T10:00:04.200Z"
}

Validate

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

AiRun ai.run@1

Fields

Examples

Validate

AiRun `ai.run@1`