---
schema: formation.doc/v0.1
kind: doc
visibility: public
canonical_url: https://topologyindex.com/docs/schemas/run/v0.1.md
document_kind: run
document_schema: formation.run/v0.1
max_document_bytes: 16384
path: /docs/schemas/run/v0.1.md
product_api_version: v1
schema_version: v0.1
title: formation.run/v0.1
---

# formation.run/v0.1

Frontmatter fields of a `run` document. Every security-, cost- and execution-relevant
value is a typed field; prose in the body can explain a rule but never override it. Undeclared
fields are rejected.

## Fields

- `schema` (required): exactly `formation.run/v0.1`
- `kind` (required): exactly `run`
- `reported_at` (required): ISO 8601 UTC timestamp, pattern `^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$`, at most 30 characters
- `identity` (required): map (fields listed below)
- `identity.job_id` (required): resource identifier, pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`, at most 128 characters
- `identity.episode_id` (required): resource identifier, pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`, at most 128 characters
- `identity.attempt_id` (required): resource identifier, pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`, at most 128 characters
- `identity.runner_id` (required): resource identifier, pattern `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`, at most 128 characters
- `identity.report_revision` (required): integer from 1 to 1000
- `identity.fencing_generation` (required): integer from 0 to 9007199254740991
- `correction` (required): null or map (fields listed below)
- `configuration` (required): map (fields listed below)
- `configuration.formation_digest` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `configuration.execution_lock` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `configuration.harness_version` (required): pinned version, pattern `^[0-9A-Za-z][0-9A-Za-z._+-]{0,63}$`, at most 64 characters
- `configuration.adapter_version` (required): pinned version, pattern `^[0-9A-Za-z][0-9A-Za-z._+-]{0,63}$`, at most 64 characters
- `configuration.effective_model_ids` (required): array of 1 to 16 items, each model identifier, pattern `^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,127}$`, at most 128 characters
- `task` (required): map (fields listed below)
- `task.pseudonym` (required): task pseudonym, pattern `^[A-Za-z0-9_-]{16,128}$`, at most 128 characters
- `task.suite` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `task.split` (required): one of `development`, `selection`, `final_holdout`
- `task.repetition` (required): integer from 1 to 100
- `task.feature_buckets` (required): map (fields listed below)
- `task.feature_buckets.repository_size_bucket` (required): one of `xs`, `s`, `m`, `l`, `xl`, `unknown`
- `task.feature_buckets.dependency_depth_bucket` (required): one of `shallow`, `moderate`, `deep`, `unknown`
- `validation` (required): map (fields listed below)
- `validation.validator_digest` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `validation.result` (required): one of `pass`, `fail`, `inconclusive`
- `validation.reason_code` (required): one of `acceptance_checks_passed`, `acceptance_checks_failed`, `candidate_output_missing`, `validator_error`, `validator_timeout`, `validator_not_run`
- `usage` (required): map (fields listed below)
- `usage.input_tokens` (required): integer from 0 to 1000000000000
- `usage.output_tokens` (required): integer from 0 to 1000000000000
- `usage.cache_read_tokens` (required): integer from 0 to 1000000000000
- `usage.cache_write_tokens` (required): integer from 0 to 1000000000000
- `usage.model_calls` (required): integer from 0 to 1000000000
- `usage.tool_calls` (required): array of 0 to 32 items, each map (fields listed below)
- `usage.tool_calls[].tool` (required): tool identifier, pattern `^[a-z][a-z0-9_]{0,31}\.[a-z][a-z0-9_]{0,31}$`, at most 64 characters
- `usage.tool_calls[].calls` (required): integer from 0 to 1000000000
- `usage.reported_cost_usd_micros` (required): null or integer from 0 to 1000000000000000
- `usage.provider_derived_cost_usd_micros` (required): null or integer from 0 to 1000000000000000
- `usage.pricing_snapshot_digest` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `timing` (required): map (fields listed below)
- `timing.scheduled_at` (required): ISO 8601 UTC timestamp, pattern `^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$`, at most 30 characters
- `timing.claimed_at` (required): ISO 8601 UTC timestamp, pattern `^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$`, at most 30 characters
- `timing.started_at` (required): null or ISO 8601 UTC timestamp, pattern `^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$`, at most 30 characters
- `timing.ended_at` (required): null or ISO 8601 UTC timestamp, pattern `^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$`, at most 30 characters
- `timing.elapsed_milliseconds` (required): null or integer from 0 to 2678400000
- `timing.waiting_milliseconds` (required): null or integer from 0 to 2678400000
- `outcome` (required): one of `completed`, `failed`, `infrastructure_failure`, `cancelled`, `budget_exhausted`, `lease_lost`, `unknown`
- `diagnostics` (required): map (fields listed below)
- `diagnostics.handoffs` (required): integer from 0 to 1000000000
- `diagnostics.role_invocations` (required): integer from 0 to 1000000000
- `diagnostics.internal_retries` (required): integer from 0 to 1000000000
- `diagnostics.infrastructure_retries` (required): integer from 0 to 1000000000
- `diagnostics.observations` (required): array of 0 to 32 items, each map (fields listed below)
- `diagnostics.observations[].code` (required): one of `budget.exhausted`, `time.exhausted`, `tool.unavailable`, `validator.failed`, `lease.lost`, `provider.error`, `coordination.repeated_handoff`, `cause.supervisor_bottleneck`, `cause.duplicate_work`, `cause.unknown`
- `diagnostics.observations[].classification` (required): one of `observation`, `hypothesis`, `unknown`
- `diagnostics.observations[].count` (required): integer from 1 to 1000000
- `diagnostics.observations[].source` (required): one of `supervisor`, `adapter`, `validator`, `local_analysis`
- `diagnostics.observations[].confidence` (required): one of `observed`, `inferred`, `unknown`
- `diagnostics.observations[].diagnostic_method_version` (optional): version label, pattern `^[a-z0-9][a-z0-9._/-]{0,63}$`, at most 64 characters
- `provenance` (required): map (fields listed below)
- `provenance.execution_source` (required): one of `registry_controlled`, `customer_controlled`, `self_reported`
- `provenance.runner_signature` (required): one of `signature_verified`, `authenticated_only`, `unverified`
- `provenance.collection_mode` (required): one of `official_runner`, `customer_harness`
- `provenance.environment_conformance` (required): one of `matched`, `deviated`, `unknown`