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

# formation.decision/v0.1

Frontmatter fields of a `decision` 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.decision/v0.1`
- `kind` (required): exactly `decision`
- `created_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
- `visibility` (required): one of `private`, `public`
- `action` (required): one of `recommend`, `retain_baseline`, `insufficient_evidence`, `no_feasible_candidate`, `unsupported`
- `recommended_execution_lock` (required): null or sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `baseline_execution_lock` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `confidence` (required): map (fields listed below)
- `confidence.method` (required): null or one of `task_cluster_bootstrap`, `repository_cluster_bootstrap`, `binomial_wilson`
- `confidence.interval` (required): null or map (fields listed below)
- `confidence.reason` (required): null or identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `limitations` (required): array of 0 to 32 items, each identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `next_action` (required): map (fields listed below)
- `next_action.type` (required): one of `none`, `read_document`, `fix_request`, `retry_later`, `request_evaluation_plan`, `start_evaluation`, `start_registered_runner`, `poll_status`, `fetch_evidence`, `fetch_decision`, `request_owner_approval`
- `next_action.path` (optional): resource path, pattern `^\/[A-Za-z0-9._~/-]{0,255}$`, at most 256 characters
- `next_action.starts_work` (optional): boolean
- `evidence_snapshot` (optional): null or sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `qualifying_unique_tasks` (optional): integer from 0 to 1000000000
- `exploratory` (optional): boolean
- `objective` (optional): one of `minimize_mean_total_episode_cost`
- `constraints` (optional): map (fields listed below)
- `constraints.minimum_success_rate` (required): number from 0 to 1
- `constraints.maximum_p95_latency_seconds` (required): integer from 1 to 2678400
- `constraints.maximum_episode_cost_usd_micros` (required): integer from 0 to 1000000000000000
- `reliability_qualification` (optional): one of `absolute_lower_bound`, `paired_non_inferiority`, `both`
- `alternatives_considered` (optional): array of 0 to 16 items, each map (fields listed below)
- `alternatives_considered[].execution_lock` (required): sha256 digest, pattern `^sha256:[0-9a-f]{64}$`, at most 71 characters
- `alternatives_considered[].status` (required): one of `qualified`, `excluded`
- `alternatives_considered[].exclusion_reasons` (required): array of 0 to 10 items, each one of `revoked`, `unpinned`, `unsupported_capability`, `over_budget`, `unauthorized`, `reliability_below_requirement`, `latency_above_requirement`, `cost_above_requirement`, `insufficient_evidence`, `environment_mismatch`
- `observed_effect` (optional): map (fields listed below)
- `observed_effect.success_rate_difference` (required): null or number from -1 to 1
- `observed_effect.episode_cost_difference_usd_micros` (required): null or integer from -1000000000000000 to 1000000000000000
- `projected_usage` (optional): map (fields listed below)
- `projected_usage.monthly_episodes` (required): integer from 0 to 1000000000
- `projected_usage.assumption_source` (required): one of `customer_provided`
- `projected_usage.projected_monthly_gross_savings_usd_micros` (required): null or integer from -1000000000000000 to 1000000000000000
- `projected_usage.projected_monthly_net_value_usd_micros` (required): null or integer from -1000000000000000 to 1000000000000000
- `projected_usage.recurring_service_fee_usd_micros` (required): null or integer from 0 to 1000000000000000
- `projected_usage.amortized_evaluation_cost_usd_micros` (required): null or integer from 0 to 1000000000000000
- `projected_usage.customer_estimated_switching_cost_usd_micros` (required): null or integer from 0 to 1000000000000000
- `evidence_age_seconds` (optional): integer from 0 to 9007199254740991
- `expires_at` (optional): 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
- `review_conditions` (optional): array of 0 to 32 items, each identifier, pattern `^[a-z][a-z0-9_]{0,63}$`, at most 64 characters
- `analysis_version` (optional): version label, pattern `^[a-z0-9][a-z0-9._/-]{0,63}$`, at most 64 characters
- `decision_policy_version` (optional): version label, pattern `^[a-z0-9][a-z0-9._/-]{0,63}$`, at most 64 characters
- `evidence_provenance` (optional): map (fields listed below)
- `evidence_provenance.evidence_class` (required): one of `tenant_controlled`, `registry_controlled`, `self_reported`
- `evidence_provenance.execution_source` (required): one of `registry_controlled`, `customer_controlled`, `self_reported`
- `evidence_provenance.identity_verification` (required): one of `signature_verified`, `authenticated_only`, `unverified`
- `evidence_provenance.validator_provenance` (required): one of `registered_deterministic_validator`, `registered_rubric`, `self_asserted`, `unknown`
- `evidence_provenance.assignment_design` (required): one of `controlled_comparison`, `observational`, `unknown`
- `evidence_provenance.environment_conformance` (required): one of `matched`, `deviated`, `unknown`
- `evidence_provenance.synthetic` (required): boolean