What a Human-Readable Model-Routing Decision Record Should Contain

A human-readable model-routing decision record should identify the routing event, state which route was selected, list the alternatives eligible at that moment, show which governance rules applied and how each evaluated, and explain how their combined effects produced the final choice. It should also preserve policy and configuration versions, material constraints, uncertainty, fallbacks, and overrides—without storing unnecessary sensitive payloads or exposing hidden model chain-of-thought.

The short answer: record the selected route, the contributing rules, and how they combined

The purpose of a decision record is to help a governance, operations, security, or infrastructure reviewer reconstruct the basis of a routing decision. It is more than an event saying that traffic went to a particular model endpoint.

A useful record answers three questions in order:

1. What happened? Identify the request context, selected route, decision time, and execution status.
2. Why was that route selected? Connect relevant input facts to the governance rules that required, preferred, penalized, or excluded particular routes.
3. How did multiple rules produce one outcome? Describe precedence, weighting where applicable, conflict resolution, exceptions, and fallback behavior.

The record should use a two-layer format. Start with a short plain-language summary for business, governance, and operations readers. Follow it with structured rule-level detail for technical investigation and change review.

For example, a summary might say:

Route private-text-standard was selected because the request was classified as containing restricted business data, the requester was authorized for private inference, and the private route was available. The data-boundary rule excluded managed external routes. A cost-preference rule supported a lower-cost eligible route but was not decisive because the data-boundary rule had higher precedence.

This summary communicates the result without collapsing the decision into a generic reason code or an unexplained score.

What makes a decision record human-readable

Human-readable does not mean prose-only. A long narrative can be difficult to compare across decisions, while a raw object can hide the practical meaning of individual fields. The strongest format combines a concise explanation with consistent structured data.

The summary should state:

• The selected route and its role in the serving workflow.
• The most important facts available at decision time.
• The decisive rule or rules.
• Any conflicts, exceptions, missing inputs, or fallback conditions.
• Whether the computed result was subsequently overridden.

The detailed layer should preserve stable identifiers and normalized statuses. Reviewers should be able to distinguish rules that were decisive from rules that merely supported the same result. They should also be able to see rules that were evaluated but overridden, could not be evaluated, failed during execution, or did not apply.

A practical status vocabulary might include:

• Decisive: materially determined the route.
• Supporting: favored the selected route but was not necessary to reach it.
• Overridden: produced a result that lost because of precedence, an exception, or an authorized override.
• Non-applicable: was considered but did not apply to the recorded facts.
• Indeterminate: could not produce a result because a required input was unavailable or ambiguous.
• Failed: encountered a rule-engine or dependency error.

These labels are implementation guidance rather than a universal standard. What matters is that each status has a stable definition and is applied consistently.

Why a raw trace or generic reason code is not enough

A raw execution log is designed primarily for machines and operators. It may contain timestamps and component messages, but it often does not explain policy meaning, rule authority, or the relationship between multiple evaluations. Conversely, a reason such as POLICY_ROUTE_12 may be easy to store but insufficient for a reviewer who cannot see which policy version it represents.

A decision record should therefore link operational events to governance context. It should identify the rules, versions, input attributes, and combination method that were relevant at the time.

The record should not attempt to capture a model's private chain-of-thought. Model-routing governance can be explained through observable facts, explicit rule evaluations, configuration state, and deterministic combination logic. These are more suitable for repeatable operational review than hidden reasoning or a generated retrospective explanation.

Identify the decision and the routes available at decision time

A routing record must be anchored to the specific event it describes. Without a unique identity and time-bounded context, reviewers may mistakenly compare the decision against policies, endpoints, or availability conditions that changed later.

Record ID, timestamp, execution context, and trace reference

At minimum, consider capturing:

• A unique decision-record ID.
• The decision timestamp, including a consistent time zone.
• The environment or execution context, such as production, staging, business unit, region, or deployment boundary where relevant.
• A correlation or trace identifier linking the routing decision to related operational telemetry.
• The application, service, workflow, or agent that requested the route.
• The routing component and version that executed the decision.
• The route-configuration version used for evaluation.

The decision ID identifies the governance artifact. The trace ID connects it to execution events. Keeping these concepts separate helps teams investigate a request spanning several services without treating every log event as part of the formal rationale.

Selected route, eligible alternatives, and material constraints

Record the route that was selected and the alternatives that were actually eligible at decision time. Do not infer eligibility from a general model catalog after the event. A model may have existed but been unavailable to that user, environment, data class, region, workload, or deployment path.

For each relevant route, useful fields can include:

• A stable route ID and configuration version.
• The model or endpoint identifier used by that route.
• Eligibility status at decision time.
• The reason an alternative remained eligible or was excluded.
• Availability or operational state if it materially influenced the decision.

Material constraints should only be included when they affected the choice. Depending on the workflow, these might include data-handling classifications, access permissions, deployment boundaries, model allowlists, workload requirements, capacity state, or an operational limit.

This distinction matters because a decision record should explain the actual decision—not reproduce every piece of metadata available to the platform.

Reference sensitive inputs without storing full payloads by default

Governance rules may depend on request attributes, but a readable record does not need to duplicate the full prompt or payload. Storing that content by default can unnecessarily reproduce personal information, proprietary context, credentials, or secrets.

Instead, a record can use:

• A reference to the source request under the applicable retention and access policy.
• A classification such as restricted-business-data.
• Redacted or normalized attributes used by the rules.
• A hash when it supports integrity or correlation requirements.
• A boolean or categorical result, such as private-route-required: true.

The record should show which evaluated fact influenced which rule. For example, it is more informative to say that a data-classification attribute caused a rule to exclude two routes than to save the entire underlying document.

Show every applicable rule and its evaluated effect

Each rule entry should make the rule recognizable beyond the immediate routing component. A stable rule ID alone is not sufficient if its meaning or implementation can change over time.

For every evaluated rule, consider recording:

• Rule ID and version: Stable identifiers for the exact logic evaluated.
• Name and purpose: A short human-readable description.
• Owner or authority: The team, policy owner, or authorized source responsible for the rule.
• Effective date: Where relevant to policy lifecycle management.
• Evaluated inputs: Only the facts or attributes material to the result.
• Evaluation result: Pass, fail, match, no match, indeterminate, or another defined result.
• Routing effect: Required, preferred, penalized, excluded, or no effect.
• Affected routes: The routes to which the effect applied.
• Contribution status: Decisive, supporting, overridden, non-applicable, indeterminate, or failed.
• Explanation: A concise statement connecting the input fact to the rule result.

A rule-level explanation might read: “Request data class was restricted; policy DATA-BOUNDARY-04 version 3.2 therefore excluded routes outside the approved private deployment boundary.” The explanation exposes the evaluated relationship, not hidden reasoning.

Rules that did not produce the final outcome can still be material. If a cost preference favored one route but a higher-priority deployment rule excluded it, both facts belong in the record. Otherwise, a reviewer cannot see whether the cost rule was ignored, misconfigured, or correctly overridden.

Explain how the rules jointly produced one route

When several governance rules apply, listing their individual results is only half the record. The reader must also be able to understand the combination logic.

Document the mechanism actually used, including:

• Precedence: Whether one rule category takes priority over another.
• Priority: The ordering among rules at the same level.
• Weighting: How scores were calculated and what thresholds were applied, if scoring was used.
• Conflict resolution: What happens when two rules require incompatible outcomes.
• Exceptions: Which authorized exception changed normal evaluation and why.
• Defaults: The route selected when no preference rule produces a result.
• Fallbacks: The route or action used when a required route is unavailable or evaluation is degraded.

Avoid reducing the explanation to a final score such as 82. If scoring contributes to the result, preserve the components and explain how hard exclusions or mandatory requirements interact with that score. A high preference score should not appear to overcome an exclusion unless the configured policy explicitly permits that behavior.

A concise combination explanation could say:

Hard eligibility and data-boundary rules were applied first. They removed two routes. Access policy then confirmed that the requester could use the remaining private routes. Of those routes, a workload preference selected the standard text route. No exception or manual override was used.

This tells the reader both the order of operations and the role of each rule class.

Capture uncertainty, errors, fallbacks, and overrides

A decision made with incomplete information should not look identical to one made under normal conditions. Make uncertainty and degraded behavior visible.

Record whether:

• A required input was missing, stale, or ambiguous.
• A policy evaluation returned an indeterminate result.
• A rule engine or external dependency failed.
• The system used cached policy state or a default configuration.
• A fallback route was selected because the preferred route was unavailable.
• The request was blocked rather than routed.
• A human or authorized system changed the computed result.

For an override, capture the original computed route separately from the final route. Include the override timestamp, actor or authorized system identity, authority used, reason, and any approval reference. This preserves the distinction between “the rules selected this route” and “an authorized intervention selected a different route.”

Fallbacks deserve the same clarity. The record should say what triggered fallback behavior, which fallback rule applied, and whether the result was degraded, blocked, queued, or sent to another eligible route.

Preserve provenance and keep later outcomes separate

Policy definitions, route configurations, model endpoints, and serving conditions change. A decision record should therefore preserve enough provenance to interpret the historical choice against the state that existed at the time.

Useful provenance includes the policy bundle version, individual rule versions, route-configuration version, relevant model or endpoint identifiers, executing component version, and references to the source of material attributes.

The original rationale should remain stable. Later facts belong in separate fields or linked records, including:

• Whether route execution succeeded.
• Which endpoint ultimately served the request.
• Retry or failover events after the decision.
• Model-output evaluation results.
• User feedback or business outcomes.
• A later incident, appeal, or governance review.

These facts can be important, but they were not part of the original rationale unless they were available when the route was selected. Separating them prevents hindsight from rewriting the historical basis of the decision.

Replayability should also be defined carefully. A record may let a reviewer reconstruct why the historical result followed from the recorded facts and versions. It does not necessarily mean rerunning the current system will produce the same result after models, dependencies, configurations, or operational conditions have changed.

Generic illustrative schema for a routing decision record

The following fictional YAML shows one way to organize the information. It is generic implementation guidance, not a Token Forge Cloud output format or documented interface.

decision:
  record_id: "dr-2026-004281"
  decided_at: "2026-09-06T14:22:31Z"
  environment: "production-private"
  trace_id: "trace-fictional-8821"
  requesting_service: "document-assistant"
  executing_component: "route-controller-v5"

summary:
  selected_route: "private-text-standard"
  rationale: >
    Restricted data classification excluded managed external routes.
    The requester was authorized for private inference, and the selected
    route was eligible and available. A cost preference was supporting,
    not decisive.
  decision_state: "normal"

routes:
  selected:
    route_id: "private-text-standard"
    config_version: "routes-18"
    endpoint_ref: "endpoint-private-a"
  alternatives:
    - route_id: "managed-text-fast"
      status: "excluded"
      reason: "deployment-boundary rule"
    - route_id: "private-text-large"
      status: "eligible-not-selected"
      reason: "lower-priority workload preference"

material_facts:
  data_class: "restricted"
  access_private_inference: true
  workload_class: "interactive-text"
  sensitive_payload_ref: "request-store/ref-7712"

rules:
  - rule_id: "DATA-BOUNDARY-04"
    version: "3.2"
    owner: "data-governance"
    effect: "exclude"
    affected_routes: ["managed-text-fast"]
    contribution: "decisive"
    explanation: "Restricted data requires the configured private boundary."
  - rule_id: "ACCESS-PRIVATE-02"
    version: "2.0"
    owner: "identity-governance"
    effect: "permit"
    contribution: "decisive"
    explanation: "Requester was authorized for private inference."
  - rule_id: "WORKLOAD-PREF-07"
    version: "1.4"
    owner: "ai-platform"
    effect: "prefer"
    contribution: "supporting"
    explanation: "Interactive text workload preferred the standard route."

combination:
  method: "ordered-policy-evaluation"
  precedence:
    - "hard exclusions"
    - "access requirements"
    - "workload preferences"
    - "cost preferences"
  conflict_resolution: "higher-precedence effect wins"
  default_used: false
  fallback_used: false

uncertainty:
  missing_inputs: []
  indeterminate_rules: []
  evaluation_errors: []

override:
  applied: false

post_decision:
  execution_status_ref: "execution/ref-004281"
  outcome_evaluation_ref: null

In a real implementation, field names, retention, access, and granularity should reflect the organization's architecture, risk model, and jurisdiction-specific obligations. The schema itself does not establish legal or regulatory sufficiency.

Applying this guidance to enterprise model routing

Enterprise model routing can involve workload policy, access conditions, deployment boundaries, endpoint eligibility, availability, and serving-layer constraints. Different workload types—such as latency-sensitive chat, batch enrichment, and agentic workflows—can require different serving policies. A readable record helps teams see which conditions were decisive rather than assuming every route was evaluated on the same basis.

Token Forge Cloud Private LLM Inference supports private deployment and serving-layer optimization for enterprise AI workloads, with relevant capabilities including model routing, policy-aware access, audit telemetry, semantic caching, quantization, and GPU scheduling. Token Forge Cloud also supports private deployment paths where models, prompts, and telemetry remain in the customer's controlled environment.

For teams validating demand before moving to private deployment, Token Forge Cloud Managed Model APIs provides an API-first model-access path with usage data. The appropriate governance-record design still depends on the organization's routing policies, data classifications, approval model, telemetry architecture, and review needs.

Use the field list and example above as a design framework for discussing those needs, rather than as a description of a built-in Token Forge Cloud decision-record schema. During implementation planning, teams should define which decision facts must be readable, which sensitive inputs should remain referenced rather than duplicated, and how policy changes will be connected to historical routing events.

Next step

Contact Token Forge Cloud to discuss API access, private deployment, and LLM inference cost control.