Decision Passport

Decision Passport is a bounded, machine-readable projection returned inside an existing Customer Grounding report when requested.

It is designed for teams that already need role-level evidence, review, and routing signals, and want one explicit output object that ties the decision outcome to traceable inputs.

The released Level 1 capability is for POST /api/v1/grounding/role-intelligence/reports.

Avelin Decision Layer showing workforce evidence and customer context flowing into explainable decision support.

Why a Passport vs. only a score

Scores and confidence fields are useful, but they are not enough for governed workflow decisions.

They do not by themselves describe what evidence was selected.
They do not express missing evidence conditions.
They do not consistently separate customer scope, decision scope, and review requirements.

Decision Passport adds a compact, explainable envelope around those same outputs so downstream systems can keep automation conservative and explicit.

Availability and request behavior

The endpoint is POST /api/v1/grounding/role-intelligence/reports.
Include include_passport: true to request the projection.
Omit include_passport or set it to false for the historical response shape.
No new endpoint is introduced; Passport is embedded in the same Customer Grounding report response.
The feature is the first Level 1 Decision Passport slice for Customer-Grounded Role Intelligence.

Passport identity and contract version

Each Passport has:

passport_id in format dp_[a-f0-9]{32}.
schema_version currently 1.0.0.

The passport_id is opaque and stable for the same decision plus schema combination.

What the Passport means

decision identity and scope

decision.decision_id: the same decision identity as the trace.
decision.type: customer_grounded_role_intelligence.
decision.status: completed, review_required, or abstained.
scope.purpose: workforce decision support.
scope.tenant_scope: authenticated_tenant.

evidence references

Passport exposes evidence references with:

evidence_reference_id (safe token, tenant-bound)
source_reference (safe token)
source_type
source_version (identified or unavailable)
relationship (supports, contradicts, contextualizes)
authority and authority_basis

Reference ids are tenant-safe and do not expose raw internal evidence or source IDs.

authority, relevance, coverage, freshness

authority: the role of the evidence family inside the decision.
relevance: assessed score, level, and method.
coverage: measured or limited as reported by runtime context; if no focus-area request, it can be not_applicable.
freshness: not_assessed in this phase when no governed freshness policy is available.

confidence, evidence sufficiency, limitations

assessment.confidence: assessed confidence score, level, and method where available.
assessment.trust_score: this phase uses not_assessed.
assessment.evidence_sufficiency: indicates whether grounded support is sufficient, limited, or insufficient.
assessment.limitations: endpoint-specific limits and reasons.

abstention and human review

governance.abstention: abstained or not_abstained with reason when applicable.
governance.human_review: required or not, with reasons and status.

request and decision trace correlation

trace.decision_trace_id: stable reference to the decision trace.
trace.request_id: correlation back to the runtime request.
trace.generated_at: UTC timestamp for the projection.

Current limited semantics

This first slice is deliberately bounded:

no universal freshness claim
no Decision Card dependency
no cross-tenant or cross-endpoint inference
no raw prompt, raw role context, or provider payload in the Passport

Example request and compact Passport excerpt

{
  "role_title": "Senior Workforce Analyst",
  "role_context": "Review role coverage across SQL and stakeholder planning.",
  "source_ids": ["src_role_framework", "src_policy_guidance"],
  "include_passport": true
}

The following is an abridged (non-complete schema) excerpt of the Passport section only:

{
  "passport": {
    "passport_id": "dp_c3f4a2d1e9b84c12a3d09f2e8b77a4c1",
    "schema_version": "1.0.0",
    "decision": {
      "decision_id": "grounded-decision-7f9c1e",
      "type": "customer_grounded_role_intelligence",
      "status": "review_required",
      "summary": "Tenant-scoped evidence requires review before use."
    },
    "scope": {
      "purpose": "workforce_decision_support",
      "subject_reference": "subject_5f6e8a8de7c41b2d0a9f",
      "tenant_scope": "authenticated_tenant"
    },
    "evidence": {
      "references": [
        {
          "evidence_reference_id": "evid_9e3b4c12f0a7db1d2c8f",
          "evidence_class": "customer_grounding",
          "source_reference": "src_a1d4c7f9e2b31",
          "source_type": "customer_role_profile",
          "source_version": {
            "status": "identified",
            "value": "ver_1f4b9c2a7d3e6f8a0"
          },
          "authority": "customer_grounded",
          "authority_basis": "Customer-owned tenant framework and policy context."
        }
      ],
      "freshness": {
        "status": "not_assessed",
        "reason": "No governed freshness policy is currently attached to this slice."
      },
      "coverage": {
        "status": "not_applicable",
        "reason": "Focus-area coverage was not requested for this report."
      },
      "conflicts": [],
      "missing_evidence": []
    },
    "assessment": {
      "trust_score": {
        "status": "not_assessed",
        "reason": "No governed Trust Score method is available for this slice."
      }
    },
    "governance": {
      "abstention": {
        "status": "not_abstained"
      },
      "human_review": {
        "required": true,
        "status": "pending",
        "reasons": ["human_review_required_for_downstream_policy"]
      }
    },
    "trace": {
      "decision_trace_id": "trace_8a1d3f",
      "request_id": "req_44ab9f",
      "generated_at": "2026-08-11T12:11:20Z"
    }
  }
}

The excerpt omits unrelated report fields and additional required Passport fields to keep the focus on the concepts above. Use the generated OpenAPI contract for the complete response shape.

What is intentionally excluded (current release)

full retrieval provenance
source tenant identifier or internal artifact IDs
raw evidence IDs
raw prompts or provider payloads
connectors, vector retrieval, SDK, or hosted MCP document store claims

For the current public flow and examples: